From 406bfb23b96a787289d4f7b03d2e1af01472778d Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Wed, 1 Apr 2026 23:28:57 +0530 Subject: [PATCH 01/28] fix(security): bound ast.Pow in safe_eval --- core/framework/graph/safe_eval.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/core/framework/graph/safe_eval.py b/core/framework/graph/safe_eval.py index 6c32a8da..2d5f7cbf 100644 --- a/core/framework/graph/safe_eval.py +++ b/core/framework/graph/safe_eval.py @@ -2,6 +2,29 @@ import ast import operator from typing import Any +# Power operations can allocate extremely large integers. Keep conservative +# limits here so untrusted edge conditions cannot exhaust CPU or memory. +MAX_POWER_ABS_EXPONENT = 1_000 +MAX_POWER_RESULT_BITS = 4_096 + + +def _safe_pow(base: Any, exp: Any) -> Any: + if isinstance(exp, (int, float)) and abs(exp) > MAX_POWER_ABS_EXPONENT: + raise ValueError( + f"Power exponent exceeds safe limit ({MAX_POWER_ABS_EXPONENT})" + ) + + if isinstance(base, int) and isinstance(exp, int) and exp > 0: + abs_base = abs(base) + if abs_base > 1: + # Estimate bit growth instead of materializing a huge integer. + estimated_bits = exp * (abs_base.bit_length() - 1) + 1 + if estimated_bits > MAX_POWER_RESULT_BITS: + raise ValueError("Power operation exceeds safe size limit") + + return operator.pow(base, exp) + + # Safe operators whitelist SAFE_OPERATORS = { ast.Add: operator.add, @@ -10,7 +33,7 @@ SAFE_OPERATORS = { ast.Div: operator.truediv, ast.FloorDiv: operator.floordiv, ast.Mod: operator.mod, - ast.Pow: operator.pow, + ast.Pow: _safe_pow, ast.LShift: operator.lshift, ast.RShift: operator.rshift, ast.BitOr: operator.or_, From fd71501215962c33e713d952f6d6b16dbb1a72b3 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Wed, 1 Apr 2026 23:29:02 +0530 Subject: [PATCH 02/28] test(safe_eval): add ast.Pow DoS regression coverage --- core/tests/test_safe_eval.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/core/tests/test_safe_eval.py b/core/tests/test_safe_eval.py index 8bc13416..8a929137 100644 --- a/core/tests/test_safe_eval.py +++ b/core/tests/test_safe_eval.py @@ -94,6 +94,18 @@ class TestArithmetic: def test_power(self): assert safe_eval("2 ** 10") == 1024 + def test_power_large_exponent_blocked(self): + with pytest.raises(ValueError, match="Power exponent"): + safe_eval("2 ** 1001") + + def test_power_large_result_blocked(self): + with pytest.raises(ValueError, match="Power operation"): + safe_eval("99 ** 1000") + + def test_nested_power_blocked(self): + with pytest.raises(ValueError, match="Power exponent"): + safe_eval("2 ** 2 ** 20") + def test_complex_expression(self): assert safe_eval("(2 + 3) * 4 - 1") == 19 From d1cbfd1e54f09e746acd914dd8e11dce3c63be42 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Wed, 1 Apr 2026 23:35:41 +0530 Subject: [PATCH 03/28] fix(security): enforce safe_eval execution timeout --- core/framework/graph/safe_eval.py | 90 ++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 8 deletions(-) diff --git a/core/framework/graph/safe_eval.py b/core/framework/graph/safe_eval.py index 2d5f7cbf..3edfced7 100644 --- a/core/framework/graph/safe_eval.py +++ b/core/framework/graph/safe_eval.py @@ -1,11 +1,18 @@ import ast import operator +import signal +import threading +import time +from contextlib import contextmanager from typing import Any # Power operations can allocate extremely large integers. Keep conservative # limits here so untrusted edge conditions cannot exhaust CPU or memory. MAX_POWER_ABS_EXPONENT = 1_000 MAX_POWER_RESULT_BITS = 4_096 +# Typical edge-condition evaluations in this repo complete well under 1ms. +# 100ms leaves ample headroom for legitimate checks while failing fast on abuse. +DEFAULT_TIMEOUT_MS = 100 def _safe_pow(base: Any, exp: Any) -> Any: @@ -25,6 +32,47 @@ def _safe_pow(base: Any, exp: Any) -> Any: return operator.pow(base, exp) +def _timeout_message(timeout_ms: int) -> str: + return f"safe_eval exceeded {timeout_ms}ms execution timeout" + + +def _check_timeout(deadline: float | None, timeout_ms: int | None) -> None: + if deadline is not None and timeout_ms is not None and time.perf_counter() >= deadline: + raise TimeoutError(_timeout_message(timeout_ms)) + + +@contextmanager +def _execution_timeout(timeout_ms: int | None): + if timeout_ms is None: + yield + return + + if timeout_ms <= 0: + raise ValueError("timeout_ms must be greater than 0") + + can_use_alarm = ( + hasattr(signal, "SIGALRM") + and hasattr(signal, "ITIMER_REAL") + and hasattr(signal, "setitimer") + and threading.current_thread() is threading.main_thread() + ) + if not can_use_alarm: + yield + return + + def _handle_timeout(signum, frame): + raise TimeoutError(_timeout_message(timeout_ms)) + + old_handler = signal.getsignal(signal.SIGALRM) + signal.signal(signal.SIGALRM, _handle_timeout) + signal.setitimer(signal.ITIMER_REAL, timeout_ms / 1000) + try: + yield + finally: + signal.setitimer(signal.ITIMER_REAL, 0) + signal.signal(signal.SIGALRM, old_handler) + + # Safe operators whitelist SAFE_OPERATORS = { ast.Add: operator.add, @@ -77,10 +125,19 @@ SAFE_FUNCTIONS = { class SafeEvalVisitor(ast.NodeVisitor): - def __init__(self, context: dict[str, Any]): + def __init__( + self, + context: dict[str, Any], + *, + deadline: float | None = None, + timeout_ms: int | None = None, + ): self.context = context + self.deadline = deadline + self.timeout_ms = timeout_ms def visit(self, node: ast.AST) -> Any: + _check_timeout(self.deadline, self.timeout_ms) # Override visit to prevent default behavior and ensure only explicitly allowed nodes work method = "visit_" + node.__class__.__name__ visitor = getattr(self, method, self.generic_visit) @@ -206,6 +263,7 @@ class SafeEvalVisitor(ast.NodeVisitor): raise AttributeError(f"Object has no attribute '{node.attr}'") def visit_Call(self, node: ast.Call) -> Any: + _check_timeout(self.deadline, self.timeout_ms) # Only allow calling whitelisted functions func = self.visit(node.func) @@ -249,16 +307,24 @@ class SafeEvalVisitor(ast.NodeVisitor): args = [self.visit(arg) for arg in node.args] keywords = {kw.arg: self.visit(kw.value) for kw in node.keywords} + _check_timeout(self.deadline, self.timeout_ms) return func(*args, **keywords) -def safe_eval(expr: str, context: dict[str, Any] | None = None) -> Any: +def safe_eval( + expr: str, + context: dict[str, Any] | None = None, + *, + timeout_ms: int | None = DEFAULT_TIMEOUT_MS, +) -> Any: """ Safely evaluate a python expression string. Args: expr: The expression string to evaluate. context: Dictionary of variables available in the expression. + timeout_ms: Maximum evaluation time in milliseconds. Use ``None`` to + disable the timeout. Returns: The result of the evaluation. @@ -274,10 +340,18 @@ def safe_eval(expr: str, context: dict[str, Any] | None = None) -> Any: full_context = context.copy() full_context.update(SAFE_FUNCTIONS) - try: - tree = ast.parse(expr, mode="eval") - except SyntaxError as e: - raise SyntaxError(f"Invalid syntax in expression: {e}") from e + deadline = None if timeout_ms is None else time.perf_counter() + (timeout_ms / 1000) - visitor = SafeEvalVisitor(full_context) - return visitor.visit(tree) + with _execution_timeout(timeout_ms): + try: + tree = ast.parse(expr, mode="eval") + except SyntaxError as e: + raise SyntaxError(f"Invalid syntax in expression: {e}") from e + + _check_timeout(deadline, timeout_ms) + visitor = SafeEvalVisitor( + full_context, + deadline=deadline, + timeout_ms=timeout_ms, + ) + return visitor.visit(tree) From 81774d5d0ef68bd1a23add43a2064571a6f22725 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Wed, 1 Apr 2026 23:36:14 +0530 Subject: [PATCH 04/28] test(safe_eval): cover execution timeout behavior --- core/tests/test_safe_eval.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/core/tests/test_safe_eval.py b/core/tests/test_safe_eval.py index 8a929137..f7b0ed54 100644 --- a/core/tests/test_safe_eval.py +++ b/core/tests/test_safe_eval.py @@ -9,6 +9,7 @@ AST nodes, disallowed function calls). import pytest +import framework.graph.safe_eval as safe_eval_module from framework.graph.safe_eval import safe_eval # --------------------------------------------------------------------------- @@ -110,6 +111,25 @@ class TestArithmetic: assert safe_eval("(2 + 3) * 4 - 1") == 19 +class TestExecutionTimeout: + def test_default_timeout(self): + assert safe_eval_module.DEFAULT_TIMEOUT_MS == 100 + + def test_timeout_must_be_positive(self): + with pytest.raises(ValueError, match="timeout_ms"): + safe_eval("1 + 1", timeout_ms=0) + + def test_timeout_can_be_disabled(self): + assert safe_eval("1 + 1", timeout_ms=None) == 2 + + def test_timeout_exceeded_raises(self, monkeypatch): + ticks = iter([0.0, 1.0]) + monkeypatch.setattr(safe_eval_module.time, "perf_counter", lambda: next(ticks)) + + with pytest.raises(TimeoutError, match="1ms"): + safe_eval("1 + 1", timeout_ms=1) + + # --------------------------------------------------------------------------- # Unary operators # --------------------------------------------------------------------------- From 42fd1ec8d1b2909c954a04d258c40c25bcf88eb2 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Wed, 1 Apr 2026 23:47:37 +0530 Subject: [PATCH 05/28] chore: formatted --- core/framework/graph/safe_eval.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/core/framework/graph/safe_eval.py b/core/framework/graph/safe_eval.py index 3edfced7..101cb329 100644 --- a/core/framework/graph/safe_eval.py +++ b/core/framework/graph/safe_eval.py @@ -17,9 +17,7 @@ DEFAULT_TIMEOUT_MS = 100 def _safe_pow(base: Any, exp: Any) -> Any: if isinstance(exp, (int, float)) and abs(exp) > MAX_POWER_ABS_EXPONENT: - raise ValueError( - f"Power exponent exceeds safe limit ({MAX_POWER_ABS_EXPONENT})" - ) + raise ValueError(f"Power exponent exceeds safe limit ({MAX_POWER_ABS_EXPONENT})") if isinstance(base, int) and isinstance(exp, int) and exp > 0: abs_base = abs(base) From 267f797abcd4d0751b545948b0b2cd578db4c5ab Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Thu, 2 Apr 2026 00:12:03 +0530 Subject: [PATCH 06/28] fix(security): preserve host alarm state in safe_eval --- core/framework/graph/safe_eval.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/core/framework/graph/safe_eval.py b/core/framework/graph/safe_eval.py index 101cb329..83453d64 100644 --- a/core/framework/graph/safe_eval.py +++ b/core/framework/graph/safe_eval.py @@ -51,6 +51,7 @@ def _execution_timeout(timeout_ms: int | None): can_use_alarm = ( hasattr(signal, "SIGALRM") and hasattr(signal, "ITIMER_REAL") + and hasattr(signal, "getitimer") and hasattr(signal, "setitimer") and threading.current_thread() is threading.main_thread() ) @@ -58,17 +59,24 @@ def _execution_timeout(timeout_ms: int | None): yield return + current_delay, current_interval = signal.getitimer(signal.ITIMER_REAL) + if current_delay > 0 or current_interval > 0: + # safe_eval runs inside a shared framework process, so it must not + # replace a timer another subsystem already owns. + yield + return + def _handle_timeout(signum, frame): raise TimeoutError(_timeout_message(timeout_ms)) old_handler = signal.getsignal(signal.SIGALRM) signal.signal(signal.SIGALRM, _handle_timeout) - signal.setitimer(signal.ITIMER_REAL, timeout_ms / 1000) + old_delay, old_interval = signal.setitimer(signal.ITIMER_REAL, timeout_ms / 1000) try: yield finally: - signal.setitimer(signal.ITIMER_REAL, 0) signal.signal(signal.SIGALRM, old_handler) + signal.setitimer(signal.ITIMER_REAL, old_delay, old_interval) # Safe operators whitelist From dacda3337f4005035fd8eb498c7b6eeaa37eb091 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Thu, 2 Apr 2026 00:12:15 +0530 Subject: [PATCH 07/28] test(safe_eval): cover alarm state preservation --- core/tests/test_safe_eval.py | 83 ++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/core/tests/test_safe_eval.py b/core/tests/test_safe_eval.py index f7b0ed54..5570d8fa 100644 --- a/core/tests/test_safe_eval.py +++ b/core/tests/test_safe_eval.py @@ -129,6 +129,89 @@ class TestExecutionTimeout: with pytest.raises(TimeoutError, match="1ms"): safe_eval("1 + 1", timeout_ms=1) + def test_existing_process_timer_is_preserved(self, monkeypatch): + calls: list[tuple[str, object]] = [] + main_thread = object() + + monkeypatch.setattr(safe_eval_module.signal, "SIGALRM", object(), raising=False) + monkeypatch.setattr(safe_eval_module.signal, "ITIMER_REAL", object(), raising=False) + monkeypatch.setattr( + safe_eval_module.signal, + "getitimer", + lambda which: (5.0, 0.0), + raising=False, + ) + monkeypatch.setattr( + safe_eval_module.signal, + "setitimer", + lambda *args: calls.append(("setitimer", args)), + raising=False, + ) + monkeypatch.setattr( + safe_eval_module.signal, + "signal", + lambda *args: calls.append(("signal", args)), + ) + monkeypatch.setattr(safe_eval_module.threading, "main_thread", lambda: main_thread) + monkeypatch.setattr( + safe_eval_module.threading, + "current_thread", + lambda: main_thread, + ) + + with safe_eval_module._execution_timeout(100): + pass + + assert calls == [] + + def test_timeout_restores_alarm_state(self, monkeypatch): + calls: list[tuple[str, object]] = [] + main_thread = object() + old_handler = object() + + monkeypatch.setattr(safe_eval_module.signal, "SIGALRM", object(), raising=False) + monkeypatch.setattr(safe_eval_module.signal, "ITIMER_REAL", object(), raising=False) + monkeypatch.setattr( + safe_eval_module.signal, + "getitimer", + lambda which: (0.0, 0.0), + raising=False, + ) + monkeypatch.setattr( + safe_eval_module.signal, + "getsignal", + lambda which: old_handler, + ) + + def fake_signal(which, handler): + calls.append(("signal", handler)) + + def fake_setitimer(which, delay, interval=0.0): + calls.append(("setitimer", (delay, interval))) + return (0.0, 0.0) + + monkeypatch.setattr(safe_eval_module.signal, "signal", fake_signal) + monkeypatch.setattr( + safe_eval_module.signal, + "setitimer", + fake_setitimer, + raising=False, + ) + monkeypatch.setattr(safe_eval_module.threading, "main_thread", lambda: main_thread) + monkeypatch.setattr( + safe_eval_module.threading, + "current_thread", + lambda: main_thread, + ) + + with safe_eval_module._execution_timeout(100): + pass + + assert calls[0][0] == "signal" + assert calls[1] == ("setitimer", (0.1, 0.0)) + assert calls[2] == ("signal", old_handler) + assert calls[3] == ("setitimer", (0.0, 0.0)) + # --------------------------------------------------------------------------- # Unary operators From 6022f6c91193244f5616c6fc431adc0b30eee8f1 Mon Sep 17 00:00:00 2001 From: Sundaram Kumar Jha Date: Thu, 2 Apr 2026 00:44:50 +0530 Subject: [PATCH 08/28] refactor: bit estimation formula --- core/framework/graph/safe_eval.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/framework/graph/safe_eval.py b/core/framework/graph/safe_eval.py index 83453d64..3697c4c3 100644 --- a/core/framework/graph/safe_eval.py +++ b/core/framework/graph/safe_eval.py @@ -23,7 +23,7 @@ def _safe_pow(base: Any, exp: Any) -> Any: abs_base = abs(base) if abs_base > 1: # Estimate bit growth instead of materializing a huge integer. - estimated_bits = exp * (abs_base.bit_length() - 1) + 1 + estimated_bits = exp * abs_base.bit_length() if estimated_bits > MAX_POWER_RESULT_BITS: raise ValueError("Power operation exceeds safe size limit") From dc64cc68a14374cc00f22c085a6e9faccef67532 Mon Sep 17 00:00:00 2001 From: Richard Tang Date: Fri, 3 Apr 2026 21:52:42 -0700 Subject: [PATCH 09/28] feat: add a html file for browser extension instruction --- docs/browser-extension-setup.html | 242 ++++++++++++++++++++++++++++++ quickstart.sh | 51 ++----- 2 files changed, 258 insertions(+), 35 deletions(-) create mode 100644 docs/browser-extension-setup.html diff --git a/docs/browser-extension-setup.html b/docs/browser-extension-setup.html new file mode 100644 index 00000000..6e8c3b9e --- /dev/null +++ b/docs/browser-extension-setup.html @@ -0,0 +1,242 @@ + + + + + + Hive — Browser Extension Setup + + + +
+

Hive Browser Extension Setup

+

Follow these steps to load the Hive Browser Bridge extension into Chrome.

+ + +
+
+ 1 + Go to Chrome Extension Settings +
+

Open the Chrome extensions page and enable Developer mode using the toggle in the top-right corner.

+ chrome://extensions/ +
If the link above doesn't open, copy chrome://extensions/ and paste it into your Chrome address bar.
+ Image +
+ + +
+
+ 2 + Click "Load unpacked" +
+

Once Developer mode is enabled, you'll see a button bar appear. Click Load unpacked.

+ Image +
+ + +
+
+ 3 + Select the extension folder +
+

In the folder picker, navigate to (or paste) the following path:

+
tools/browser-extension
+
The quickstart script copies this path to your clipboard — just paste it in the folder picker.
+
If pasting doesn't work, navigate manually: open the folder where you cloned the Hive repo, then go into tools → browser-extension. For example, if you cloned to ~/projects/hive, the full path would be ~/projects/hive/tools/browser-extension.
+ Image +
+ + +
+
+ 4 + Verify the extension loaded +
+

You should see Hive Browser Bridge appear in your extensions list. Make sure it is enabled.

+ Image +
+ +
+

You're all set!

+

Return to your terminal and press Enter to continue the quickstart.

+
+
+ + + + diff --git a/quickstart.sh b/quickstart.sh index 789aa79c..325df0d9 100755 --- a/quickstart.sh +++ b/quickstart.sh @@ -1932,47 +1932,28 @@ else printf '%s' "$EXTENSION_PATH" | pbcopy 2>/dev/null && _copied=true fi - # Show instructions first, then wait for the user before opening Chrome - echo -e " ${BOLD}When Chrome opens to the extensions page, you will need to:${NC}" - echo "" - echo -e " ${CYAN}1.${NC} Enable ${BOLD}Developer mode${NC} (toggle in the top-right corner)" - echo -e " ${CYAN}2.${NC} Click ${BOLD}Load unpacked${NC}" - echo -e " ${CYAN}3.${NC} Paste this path into the folder picker:" - echo "" - echo -e " ${BOLD}$EXTENSION_PATH${NC}" - echo "" - if [ "${_copied:-false}" = "true" ]; then - echo -e " ${DIM}(path already copied to clipboard — just Ctrl+V in the folder picker)${NC}" - echo "" - fi - read -r -p " Press Enter when you are ready to set up the Chrome extension... " _dummy || true echo "" - # Open chrome://extensions in Chrome - echo " Opening chrome://extensions in Chrome..." - if [[ "$OSTYPE" == darwin* ]]; then - # macOS: use open -a to properly handle chrome:// URLs - _chrome_app="" - if [[ "$CHROME_BIN" == *"Google Chrome"* ]]; then - _chrome_app="Google Chrome" - elif [[ "$CHROME_BIN" == *"Microsoft Edge"* ]]; then - _chrome_app="Microsoft Edge" - elif [[ "$CHROME_BIN" == *"Chromium"* ]]; then - _chrome_app="Chromium" - fi - if [ -n "$_chrome_app" ]; then - open -a "$_chrome_app" "chrome://extensions" 2>/dev/null - else - "$CHROME_BIN" "chrome://extensions" > /dev/null 2>&1 & - fi - else - "$CHROME_BIN" "chrome://extensions" > /dev/null 2>&1 & + # Open setup guide in default browser + SETUP_URL="file://$SCRIPT_DIR/docs/browser-extension-setup.html?path=$(printf '%s' "$EXTENSION_PATH" | sed 's/ /%20/g')" + echo -e " Opening browser extension setup guide..." + if [ "${_copied:-false}" = "true" ]; then + echo -e " ${DIM}(extension path copied to clipboard — paste it in the folder picker)${NC}" + fi + if [[ "$OSTYPE" == darwin* ]]; then + open "$SETUP_URL" 2>/dev/null + elif command -v xdg-open &> /dev/null; then + xdg-open "$SETUP_URL" > /dev/null 2>&1 & + elif command -v wslview &> /dev/null; then + wslview "$SETUP_URL" > /dev/null 2>&1 & + else + echo -e " ${DIM}Could not open browser automatically. Visit:${NC}" + echo -e " ${BOLD}$SETUP_URL${NC}" fi - sleep 1 echo "" - read -r -p " Press Enter once you see 'Hive Browser Bridge' in the extensions list... " _dummy || true + read -r -p " Press Enter once you've finished the extension setup... " _dummy || true CHROME_LAUNCHED=true fi From 634658e829cf790581eaa081b067dc82f647825e Mon Sep 17 00:00:00 2001 From: Emmanuel Nwanguma Date: Sun, 5 Apr 2026 02:52:47 +0100 Subject: [PATCH 10/28] docs(tools): add README for 11 tools (batch 1 of 2) (#6886) Partial fix for #6486 Add README.md for: aws_s3_tool, azure_sql_tool, cloudinary_tool, duckduckgo_tool, file_system_toolkits, gitlab_tool, google_search_console_tool, greenhouse_tool, hubspot_tool, kafka_tool, microsoft_graph_tool --- .../aden_tools/tools/aws_s3_tool/README.md | 59 +++++++++++++ .../aden_tools/tools/azure_sql_tool/README.md | 62 ++++++++++++++ .../tools/cloudinary_tool/README.md | 59 +++++++++++++ .../tools/duckduckgo_tool/README.md | 64 ++++++++++++++ .../tools/file_system_toolkits/README.md | 65 +++++++++++++++ .../aden_tools/tools/gitlab_tool/README.md | 62 ++++++++++++++ .../google_search_console_tool/README.md | 68 +++++++++++++++ .../tools/greenhouse_tool/README.md | 60 ++++++++++++++ .../aden_tools/tools/hubspot_tool/README.md | 73 ++++++++++++++++ .../src/aden_tools/tools/kafka_tool/README.md | 58 +++++++++++++ .../tools/microsoft_graph_tool/README.md | 83 +++++++++++++++++++ 11 files changed, 713 insertions(+) create mode 100644 tools/src/aden_tools/tools/aws_s3_tool/README.md create mode 100644 tools/src/aden_tools/tools/azure_sql_tool/README.md create mode 100644 tools/src/aden_tools/tools/cloudinary_tool/README.md create mode 100644 tools/src/aden_tools/tools/duckduckgo_tool/README.md create mode 100644 tools/src/aden_tools/tools/file_system_toolkits/README.md create mode 100644 tools/src/aden_tools/tools/gitlab_tool/README.md create mode 100644 tools/src/aden_tools/tools/google_search_console_tool/README.md create mode 100644 tools/src/aden_tools/tools/greenhouse_tool/README.md create mode 100644 tools/src/aden_tools/tools/hubspot_tool/README.md create mode 100644 tools/src/aden_tools/tools/kafka_tool/README.md create mode 100644 tools/src/aden_tools/tools/microsoft_graph_tool/README.md diff --git a/tools/src/aden_tools/tools/aws_s3_tool/README.md b/tools/src/aden_tools/tools/aws_s3_tool/README.md new file mode 100644 index 00000000..2bcaad04 --- /dev/null +++ b/tools/src/aden_tools/tools/aws_s3_tool/README.md @@ -0,0 +1,59 @@ +# AWS S3 Tool + +Manage Amazon S3 buckets and objects using AWS Signature V4 authentication. + +## Tools + +| Tool | Description | +|------|-------------| +| `s3_list_buckets` | List all S3 buckets in the account | +| `s3_list_objects` | List objects in a bucket with optional prefix filter | +| `s3_get_object` | Download an object's content (text or base64) | +| `s3_put_object` | Upload content to an S3 object | +| `s3_delete_object` | Delete an object from a bucket | +| `s3_copy_object` | Copy an object between buckets or keys | +| `s3_get_object_metadata` | Get object metadata (size, content type, ETag) | +| `s3_generate_presigned_url` | Generate a pre-signed URL for temporary access | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `AWS_ACCESS_KEY_ID` | AWS access key | +| `AWS_SECRET_ACCESS_KEY` | AWS secret key | +| `AWS_REGION` | AWS region (default: `us-east-1`) | + +Get credentials at: [AWS Console](https://console.aws.amazon.com/iam/) + +## Usage Examples + +### List buckets +```python +s3_list_buckets() +``` + +### List objects with prefix +```python +s3_list_objects(bucket="my-bucket", prefix="data/", max_keys=20) +``` + +### Upload a file +```python +s3_put_object(bucket="my-bucket", key="reports/q1.csv", content="col1,col2\n1,2") +``` + +### Generate a pre-signed URL +```python +s3_generate_presigned_url(bucket="my-bucket", key="file.pdf", expires_in=3600) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are required", "help": "Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables"} +{"error": "HTTP 404: ..."} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/azure_sql_tool/README.md b/tools/src/aden_tools/tools/azure_sql_tool/README.md new file mode 100644 index 00000000..7151caff --- /dev/null +++ b/tools/src/aden_tools/tools/azure_sql_tool/README.md @@ -0,0 +1,62 @@ +# Azure SQL Tool + +Manage Azure SQL servers, databases, and firewall rules via the Azure Management REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `azure_sql_list_servers` | List SQL servers in a subscription or resource group | +| `azure_sql_get_server` | Get details of a specific SQL server | +| `azure_sql_list_databases` | List databases on a SQL server | +| `azure_sql_get_database` | Get details of a specific database | +| `azure_sql_list_firewall_rules` | List firewall rules for a SQL server | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `AZURE_SUBSCRIPTION_ID` | Azure subscription ID | +| `AZURE_SQL_ACCESS_TOKEN` | Azure Management API bearer token | + +To obtain a token: +1. Register an app in Azure AD (Entra ID) +2. Assign SQL DB Contributor or Reader role +3. Obtain a token via client credentials flow with scope `https://management.azure.com/.default` + +See: [Azure SQL REST API](https://learn.microsoft.com/en-us/rest/api/sql/) + +Note: Access tokens typically expire within 1 hour and require refresh. + +## Usage Examples + +### List all SQL servers +```python +azure_sql_list_servers() +``` + +### List servers in a resource group +```python +azure_sql_list_servers(resource_group="my-rg") +``` + +### Get databases on a server +```python +azure_sql_list_databases(resource_group="my-rg", server_name="my-server") +``` + +### Check firewall rules +```python +azure_sql_list_firewall_rules(resource_group="my-rg", server_name="my-server") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "AZURE_SQL_ACCESS_TOKEN and AZURE_SUBSCRIPTION_ID are required"} +{"error": "Azure API error (HTTP 404): Resource not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/cloudinary_tool/README.md b/tools/src/aden_tools/tools/cloudinary_tool/README.md new file mode 100644 index 00000000..0b46b1c1 --- /dev/null +++ b/tools/src/aden_tools/tools/cloudinary_tool/README.md @@ -0,0 +1,59 @@ +# Cloudinary Tool + +Upload, manage, search, and transform media assets using the Cloudinary API. + +## Tools + +| Tool | Description | +|------|-------------| +| `cloudinary_upload` | Upload an image or file to Cloudinary | +| `cloudinary_list_resources` | List resources with optional type and prefix filters | +| `cloudinary_get_resource` | Get detailed info about a specific resource | +| `cloudinary_delete_resource` | Delete a resource by public ID | +| `cloudinary_search` | Search resources using Cloudinary's search API | +| `cloudinary_get_usage` | Get account usage statistics | +| `cloudinary_rename_resource` | Rename a resource's public ID | +| `cloudinary_add_tag` | Add a tag to one or more resources | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `CLOUDINARY_CLOUD_NAME` | Your Cloudinary cloud name | +| `CLOUDINARY_API_KEY` | API key | +| `CLOUDINARY_API_SECRET` | API secret | + +Get credentials at: [Cloudinary Console](https://console.cloudinary.com/) + +## Usage Examples + +### Upload an image +```python +cloudinary_upload(file_url="https://example.com/photo.jpg", public_id="my-photo") +``` + +### Search for resources +```python +cloudinary_search(expression="cat AND format:jpg", max_results=10) +``` + +### Get account usage +```python +cloudinary_get_usage() +``` + +### Delete a resource +```python +cloudinary_delete_resource(public_id="my-photo") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, and CLOUDINARY_API_SECRET not set", "help": "Get credentials from your Cloudinary dashboard at https://console.cloudinary.com/"} +{"error": "Cloudinary API error (HTTP 404): Resource not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/duckduckgo_tool/README.md b/tools/src/aden_tools/tools/duckduckgo_tool/README.md new file mode 100644 index 00000000..e3e92bac --- /dev/null +++ b/tools/src/aden_tools/tools/duckduckgo_tool/README.md @@ -0,0 +1,64 @@ +# DuckDuckGo Tool + +Search the web, news, and images using DuckDuckGo. No API key required. + +## Tools + +| Tool | Description | +|------|-------------| +| `duckduckgo_search` | Search the web for pages and results | +| `duckduckgo_news` | Search for recent news articles | +| `duckduckgo_images` | Search for images | + +## Setup + +No credentials required. DuckDuckGo searches are free and unauthenticated. + +## Usage Examples + +### Web search +```python +duckduckgo_search(query="python async best practices", max_results=5) +``` + +### Search with optional parameters +```python +duckduckgo_search( + query="AI frameworks", + max_results=10, + region="us-en", + safesearch="moderate", + timelimit="m", # past month +) +``` + +### News search +```python +duckduckgo_news(query="AI agents 2026", max_results=10, region="us-en") +``` + +### Image search +```python +duckduckgo_images(query="neural network diagram", max_results=5, size="Large") +``` + +## Optional Parameters + +| Parameter | Tools | Description | +|-----------|-------|-------------| +| `region` | All | Region code (default: `us-en`) | +| `safesearch` | search, images | `off`, `moderate`, `strict` (default: `moderate`) | +| `timelimit` | search, news | `d` (day), `w` (week), `m` (month), `y` (year) | +| `size` | images | `Small`, `Medium`, `Large`, `Wallpaper` | + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "Search failed: connection timeout"} +``` + +When no results are found, tools return a successful response with an empty list: +```python +{"query": "obscure search", "results": [], "count": 0} +``` diff --git a/tools/src/aden_tools/tools/file_system_toolkits/README.md b/tools/src/aden_tools/tools/file_system_toolkits/README.md new file mode 100644 index 00000000..b083c2a5 --- /dev/null +++ b/tools/src/aden_tools/tools/file_system_toolkits/README.md @@ -0,0 +1,65 @@ +# File System Toolkits + +A collection of file system tools for reading, writing, searching, and executing commands within the agent workspace. + +## Tools + +| Tool | Description | +|------|-------------| +| `apply_diff` | Apply a unified diff to a file | +| `apply_patch` | Apply a patch file to modify source files | +| `hashline_edit` | Edit a file using hashline-addressed replacements | +| `replace_file_content` | Find and replace content in a file | +| `grep_search` | Search file contents using regex patterns | +| `list_dir` | List directory contents with metadata | +| `execute_command_tool` | Execute a shell command in the workspace | +| `save_data` | Save data to a file in the agent's data directory | +| `load_data` | Load data from a file in the data directory | +| `serve_file_to_user` | Serve a file to the user for download | +| `list_data_files` | List files in the agent's data directory | +| `append_data` | Append data to an existing file | + +## Sub-modules + +| Module | Description | +|--------|-------------| +| `apply_diff/` | Unified diff application | +| `apply_patch/` | Patch file application | +| `data_tools/` | Data persistence (save, load, append, list, serve) | +| `execute_command_tool/` | Shell command execution with sanitization | +| `grep_search/` | File content search (uses ripgrep if available) | +| `hashline_edit/` | Hashline-based file editing | +| `list_dir/` | Directory listing | +| `replace_file_content/` | Find-and-replace in files | + +## Setup + +No external credentials required. File operations are scoped to the agent's workspace directory. + +## Security + +- `command_sanitizer.py` validates and sanitizes shell commands before execution +- `security.py` provides path traversal protection +- All file operations are workspace-scoped + +## Usage Examples + +### Search for a pattern in files +```python +grep_search(pattern="def register_tools", path="tools/src/", include="*.py") +``` + +### List directory contents +```python +list_dir(path="core/framework/", workspace_id="ws1", agent_id="agent1", session_id="s1") +``` + +### Save data to a file +```python +save_data(filename="results.json", data='{"status": "complete"}', data_dir="/path/to/data") +``` + +### Execute a command +```python +execute_command_tool(command="python -m pytest tests/ -v") +``` diff --git a/tools/src/aden_tools/tools/gitlab_tool/README.md b/tools/src/aden_tools/tools/gitlab_tool/README.md new file mode 100644 index 00000000..8fc47162 --- /dev/null +++ b/tools/src/aden_tools/tools/gitlab_tool/README.md @@ -0,0 +1,62 @@ +# GitLab Tool + +Manage GitLab projects, issues, and merge requests via the GitLab REST API v4. + +## Tools + +| Tool | Description | +|------|-------------| +| `gitlab_list_projects` | List projects with optional search and visibility filters | +| `gitlab_get_project` | Get details of a specific project | +| `gitlab_list_issues` | List issues with state, label, and assignee filters | +| `gitlab_get_issue` | Get details of a specific issue | +| `gitlab_create_issue` | Create a new issue in a project | +| `gitlab_update_issue` | Update an existing issue (title, description, state, labels, assignee) | +| `gitlab_list_merge_requests` | List merge requests with state and label filters | +| `gitlab_get_merge_request` | Get details of a specific merge request | +| `gitlab_create_merge_request_note` | Add a comment to a merge request | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `GITLAB_TOKEN` | GitLab personal access token | +| `GITLAB_URL` | GitLab instance URL (optional, defaults to `https://gitlab.com`) | + +Get a token at: [GitLab Access Tokens](https://gitlab.com/-/user_settings/personal_access_tokens) + +Required scopes: `api` (full API access) or `read_api` + `read_repository` for read-only. + +## Usage Examples + +### List your projects +```python +gitlab_list_projects(membership=True, per_page=10) +``` + +### Search for issues +```python +gitlab_list_issues(project_id="12345", state="opened", labels="bug") +``` + +### Create an issue +```python +gitlab_create_issue(project_id="12345", title="Fix login bug", description="Steps to reproduce...") +``` + +### Add a comment to a merge request +```python +gitlab_create_merge_request_note(project_id="12345", merge_request_iid=42, body="LGTM!") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "GITLAB_TOKEN not set", "help": "Create a personal access token at https://gitlab.com/-/user_settings/personal_access_tokens"} +{"error": "Unauthorized. Check your GitLab token."} +{"error": "Forbidden. Insufficient permissions."} +{"error": "Request to GitLab timed out"} +``` diff --git a/tools/src/aden_tools/tools/google_search_console_tool/README.md b/tools/src/aden_tools/tools/google_search_console_tool/README.md new file mode 100644 index 00000000..daa3570b --- /dev/null +++ b/tools/src/aden_tools/tools/google_search_console_tool/README.md @@ -0,0 +1,68 @@ +# Google Search Console Tool + +Analyze search performance, manage sitemaps, and inspect URLs using the Google Search Console API. + +## Tools + +| Tool | Description | +|------|-------------| +| `gsc_search_analytics` | Query search analytics data with dimension and date filters | +| `gsc_list_sites` | List all verified sites in the account | +| `gsc_list_sitemaps` | List sitemaps for a site | +| `gsc_inspect_url` | Inspect a URL's indexing status | +| `gsc_submit_sitemap` | Submit a sitemap URL for a site | +| `gsc_delete_sitemap` | Delete a submitted sitemap | +| `gsc_top_queries` | Get top search queries for a site | +| `gsc_top_pages` | Get top pages by clicks for a site | + +## Setup + +Requires Google OAuth2 via Aden: + +1. Connect your Google account at [hive.adenhq.com](https://hive.adenhq.com) +2. The `GOOGLE_SEARCH_CONSOLE_TOKEN` is managed automatically by the Aden credential system + +Or set manually: + +| Variable | Description | +|----------|-------------| +| `GOOGLE_SEARCH_CONSOLE_TOKEN` | Google OAuth2 access token | + +Required OAuth scopes: `https://www.googleapis.com/auth/webmasters.readonly` (read) or `https://www.googleapis.com/auth/webmasters` (read/write). + +## Usage Examples + +### Get top queries for the last 7 days +```python +gsc_top_queries(site_url="https://example.com", days=7, limit=20) +``` + +### Check a URL's index status +```python +gsc_inspect_url(site_url="https://example.com", inspection_url="https://example.com/page") +``` + +### Submit a sitemap +```python +gsc_submit_sitemap(site_url="https://example.com", sitemap_url="https://example.com/sitemap.xml") +``` + +### Query search analytics with filters +```python +gsc_search_analytics( + site_url="https://example.com", + start_date="2026-01-01", + end_date="2026-01-31", + dimensions=["query", "page"], + row_limit=50, +) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "GOOGLE_SEARCH_CONSOLE_TOKEN not set", "help": "Set GOOGLE_SEARCH_CONSOLE_TOKEN or connect via hive.adenhq.com"} +{"error": "Unauthorized. Check your GOOGLE_SEARCH_CONSOLE_TOKEN."} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/greenhouse_tool/README.md b/tools/src/aden_tools/tools/greenhouse_tool/README.md new file mode 100644 index 00000000..2a2a2a1b --- /dev/null +++ b/tools/src/aden_tools/tools/greenhouse_tool/README.md @@ -0,0 +1,60 @@ +# Greenhouse Tool + +Manage jobs, candidates, applications, and offers using the Greenhouse Harvest API. + +## Tools + +| Tool | Description | +|------|-------------| +| `greenhouse_list_jobs` | List jobs with optional status and department filters | +| `greenhouse_get_job` | Get details of a specific job | +| `greenhouse_list_candidates` | List candidates with optional search and date filters | +| `greenhouse_get_candidate` | Get details of a specific candidate | +| `greenhouse_list_applications` | List applications with optional job and status filters | +| `greenhouse_get_application` | Get details of a specific application | +| `greenhouse_list_offers` | List offers with optional status filter | +| `greenhouse_add_candidate_note` | Add a note to a candidate's profile | +| `greenhouse_list_scorecards` | List scorecards for an application | + +## Setup + +Set the following environment variable: + +| Variable | Description | +|----------|-------------| +| `GREENHOUSE_API_TOKEN` | Greenhouse Harvest API token | + +Get a token at: Configure > Dev Center > API Credential Management in your Greenhouse account. + +The token uses HTTP Basic Auth (token as username, empty password). + +## Usage Examples + +### List open jobs +```python +greenhouse_list_jobs(status="open", per_page=20) +``` + +### Search candidates +```python +greenhouse_list_candidates(search="jane@example.com", per_page=10) +``` + +### Get application details +```python +greenhouse_get_application(application_id=12345) +``` + +### Add a note to a candidate +```python +greenhouse_add_candidate_note(candidate_id=12345, body="Strong technical interview performance.") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "GREENHOUSE_API_TOKEN not set", "help": "Get your API key from Greenhouse: Configure > Dev Center > API Credential Management"} +{"error": "Greenhouse API error (HTTP 404): Resource not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/hubspot_tool/README.md b/tools/src/aden_tools/tools/hubspot_tool/README.md new file mode 100644 index 00000000..163815dc --- /dev/null +++ b/tools/src/aden_tools/tools/hubspot_tool/README.md @@ -0,0 +1,73 @@ +# HubSpot Tool + +Manage contacts, companies, deals, and associations using the HubSpot CRM API v3/v4. + +## Tools + +| Tool | Description | +|------|-------------| +| `hubspot_search_contacts` | Search contacts by name, email, phone | +| `hubspot_get_contact` | Get a contact by ID | +| `hubspot_create_contact` | Create a new contact | +| `hubspot_update_contact` | Update a contact's properties | +| `hubspot_search_companies` | Search companies by name, domain | +| `hubspot_get_company` | Get a company by ID | +| `hubspot_create_company` | Create a new company | +| `hubspot_update_company` | Update a company's properties | +| `hubspot_search_deals` | Search deals by name | +| `hubspot_get_deal` | Get a deal by ID | +| `hubspot_create_deal` | Create a new deal | +| `hubspot_update_deal` | Update a deal's properties | +| `hubspot_delete_object` | Delete (archive) a contact, company, or deal | +| `hubspot_list_associations` | List associations between CRM objects | +| `hubspot_create_association` | Create an association between two objects | + +## Setup + +Set the following environment variable or use Aden OAuth: + +| Variable | Description | +|----------|-------------| +| `HUBSPOT_ACCESS_TOKEN` | HubSpot private app access token | + +Get a token at: [HubSpot Developer Portal](https://developers.hubspot.com/docs/api/creating-an-app) + +Supports multi-account via `account` parameter for Aden OAuth users. + +## Usage Examples + +### Search contacts +```python +hubspot_search_contacts(query="jane@example.com", properties=["email", "firstname", "lastname"]) +``` + +### Create a deal +```python +hubspot_create_deal(properties={"dealname": "New Partnership", "amount": "50000"}) +``` + +### Link a contact to a company +```python +hubspot_create_association( + from_object_type="contacts", + from_object_id="101", + to_object_type="companies", + to_object_id="202", + association_type_id=1, +) +``` + +### Delete a contact +```python +hubspot_delete_object(object_type="contacts", object_id="101") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "HubSpot credentials not configured", "help": "Set HUBSPOT_ACCESS_TOKEN or configure via credential store"} +{"error": "Invalid or expired HubSpot access token"} +{"error": "HubSpot rate limit exceeded. Try again later."} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/kafka_tool/README.md b/tools/src/aden_tools/tools/kafka_tool/README.md new file mode 100644 index 00000000..7d5a8c15 --- /dev/null +++ b/tools/src/aden_tools/tools/kafka_tool/README.md @@ -0,0 +1,58 @@ +# Kafka Tool + +Manage Apache Kafka topics, produce messages, and monitor consumer groups via the Confluent Kafka REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `kafka_list_topics` | List all topics in the Kafka cluster | +| `kafka_get_topic` | Get details and configuration of a topic | +| `kafka_create_topic` | Create a new topic with partition and replication settings | +| `kafka_produce_message` | Produce a message to a topic | +| `kafka_list_consumer_groups` | List all consumer groups | +| `kafka_get_consumer_group_lag` | Get consumer lag for a group | + +## Setup + +Set the following environment variables: + +| Variable | Required | Description | +|----------|----------|-------------| +| `KAFKA_REST_URL` | Yes | Confluent Kafka REST Proxy URL | +| `KAFKA_CLUSTER_ID` | Yes | Kafka cluster ID | +| `KAFKA_API_KEY` | No | API key (for authenticated clusters) | +| `KAFKA_API_SECRET` | No | API secret (for authenticated clusters) | + +Get credentials at: [Confluent Cloud](https://confluent.cloud/) + +## Usage Examples + +### List topics +```python +kafka_list_topics() +``` + +### Create a topic +```python +kafka_create_topic(topic_name="events", partitions_count=3, replication_factor=3) +``` + +### Produce a message +```python +kafka_produce_message(topic_name="events", key="user-123", value='{"action": "login"}') +``` + +### Check consumer lag +```python +kafka_get_consumer_group_lag(consumer_group_id="my-consumer-group") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "KAFKA_REST_URL is required", "help": "Set KAFKA_REST_URL environment variable"} +{"error": "KAFKA_CLUSTER_ID is required", "help": "Set KAFKA_CLUSTER_ID environment variable"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/microsoft_graph_tool/README.md b/tools/src/aden_tools/tools/microsoft_graph_tool/README.md new file mode 100644 index 00000000..d4d15afe --- /dev/null +++ b/tools/src/aden_tools/tools/microsoft_graph_tool/README.md @@ -0,0 +1,83 @@ +# Microsoft Graph Tool + +Access Outlook mail, Microsoft Teams, and OneDrive files via the Microsoft Graph API v1.0. + +## Tools + +### Outlook Mail + +| Tool | Description | +|------|-------------| +| `outlook_list_messages` | List emails with optional folder and search filters | +| `outlook_get_message` | Get details of a specific email | +| `outlook_send_mail` | Send an email | + +### Microsoft Teams + +| Tool | Description | +|------|-------------| +| `teams_list_teams` | List teams the user belongs to | +| `teams_list_channels` | List channels in a team | +| `teams_send_channel_message` | Send a message to a team channel | +| `teams_get_channel_messages` | Get recent messages from a channel | + +### OneDrive + +| Tool | Description | +|------|-------------| +| `onedrive_search_files` | Search for files across OneDrive | +| `onedrive_list_files` | List files in a folder | +| `onedrive_download_file` | Download a file's content | +| `onedrive_upload_file` | Upload a small file to OneDrive (up to 4MB) | + +## Setup + +Set the following environment variable or use Aden OAuth: + +| Variable | Description | +|----------|-------------| +| `MICROSOFT_GRAPH_ACCESS_TOKEN` | Microsoft Graph API access token | + +Get credentials at: [Azure App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps) + +Required permissions: `Mail.Read`, `Mail.Send`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `Files.ReadWrite` + +## Usage Examples + +### List unread emails +```python +outlook_list_messages(folder="inbox", search="is:unread", top=10) +``` + +### Send an email +```python +outlook_send_mail( + to=["jane@example.com"], + subject="Meeting Notes", + body="Here are the notes from today's meeting.", +) +``` + +### List Teams channels +```python +teams_list_channels(team_id="team-abc-123") +``` + +### Search OneDrive files +```python +onedrive_search_files(query="quarterly report", top=5) +``` + +### Upload a file to OneDrive +```python +onedrive_upload_file(file_path="Documents/notes.txt", content="Meeting notes here") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "MICROSOFT_GRAPH_ACCESS_TOKEN not set", "help": "Set MICROSOFT_GRAPH_ACCESS_TOKEN or connect via hive.adenhq.com"} +{"error": "Microsoft Graph API error (HTTP 403): Insufficient privileges"} +{"error": "Request timed out"} +``` From 2e5670ace6878eca5efd4f438fa675e0a1871347 Mon Sep 17 00:00:00 2001 From: Emmanuel Nwanguma Date: Sun, 5 Apr 2026 03:00:14 +0100 Subject: [PATCH 11/28] docs(tools): add README for 11 tools (batch 2 of 2) (#6887) Partial fix for #6486 Add README.md for: n8n_tool, obsidian_tool, pagerduty_tool, pipedrive_tool, plaid_tool, powerbi_tool, quickbooks_tool, salesforce_tool, sap_tool, terraform_tool, tines_tool --- tools/src/aden_tools/tools/n8n_tool/README.md | 56 +++++++++++++++ .../aden_tools/tools/obsidian_tool/README.md | 54 ++++++++++++++ .../aden_tools/tools/pagerduty_tool/README.md | 62 ++++++++++++++++ .../aden_tools/tools/pipedrive_tool/README.md | 72 +++++++++++++++++++ .../src/aden_tools/tools/plaid_tool/README.md | 57 +++++++++++++++ .../aden_tools/tools/powerbi_tool/README.md | 56 +++++++++++++++ .../tools/quickbooks_tool/README.md | 61 ++++++++++++++++ .../tools/salesforce_tool/README.md | 66 +++++++++++++++++ tools/src/aden_tools/tools/sap_tool/README.md | 56 +++++++++++++++ .../aden_tools/tools/terraform_tool/README.md | 57 +++++++++++++++ .../src/aden_tools/tools/tines_tool/README.md | 55 ++++++++++++++ 11 files changed, 652 insertions(+) create mode 100644 tools/src/aden_tools/tools/n8n_tool/README.md create mode 100644 tools/src/aden_tools/tools/obsidian_tool/README.md create mode 100644 tools/src/aden_tools/tools/pagerduty_tool/README.md create mode 100644 tools/src/aden_tools/tools/pipedrive_tool/README.md create mode 100644 tools/src/aden_tools/tools/plaid_tool/README.md create mode 100644 tools/src/aden_tools/tools/powerbi_tool/README.md create mode 100644 tools/src/aden_tools/tools/quickbooks_tool/README.md create mode 100644 tools/src/aden_tools/tools/salesforce_tool/README.md create mode 100644 tools/src/aden_tools/tools/sap_tool/README.md create mode 100644 tools/src/aden_tools/tools/terraform_tool/README.md create mode 100644 tools/src/aden_tools/tools/tines_tool/README.md diff --git a/tools/src/aden_tools/tools/n8n_tool/README.md b/tools/src/aden_tools/tools/n8n_tool/README.md new file mode 100644 index 00000000..33f25d93 --- /dev/null +++ b/tools/src/aden_tools/tools/n8n_tool/README.md @@ -0,0 +1,56 @@ +# n8n Tool + +Manage n8n workflows and executions via the n8n REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `n8n_list_workflows` | List workflows with optional status and tag filters | +| `n8n_get_workflow` | Get details of a specific workflow | +| `n8n_activate_workflow` | Activate a workflow | +| `n8n_deactivate_workflow` | Deactivate a workflow | +| `n8n_list_executions` | List workflow executions with optional status filter | +| `n8n_get_execution` | Get details of a specific execution | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `N8N_API_KEY` | n8n API key | +| `N8N_BASE_URL` | n8n instance URL (e.g., `https://your-n8n.example.com`) | + +Get an API key at: Settings → API → Create API Key in your n8n instance. + +## Usage Examples + +### List active workflows +```python +n8n_list_workflows(active="true") +``` + +### Get workflow details +```python +n8n_get_workflow(workflow_id="123") +``` + +### Activate a workflow +```python +n8n_activate_workflow(workflow_id="123") +``` + +### List recent executions +```python +n8n_list_executions(status="success", limit=10) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "n8n credentials not configured", "help": "Set N8N_API_KEY and N8N_BASE_URL environment variables or configure via credential store"} +{"error": "n8n API error (HTTP 404): Workflow not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/obsidian_tool/README.md b/tools/src/aden_tools/tools/obsidian_tool/README.md new file mode 100644 index 00000000..30fa016d --- /dev/null +++ b/tools/src/aden_tools/tools/obsidian_tool/README.md @@ -0,0 +1,54 @@ +# Obsidian Tool + +Read, write, search, and manage notes in an Obsidian vault via the Obsidian Local REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `obsidian_read_note` | Read the content of a note by path | +| `obsidian_write_note` | Create or overwrite a note | +| `obsidian_append_note` | Append content to an existing note | +| `obsidian_search` | Search notes by text or regex | +| `obsidian_list_files` | List files and folders in a vault path | +| `obsidian_get_active` | Get the currently active note | + +## Setup + +Requires the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin. + +| Variable | Description | +|----------|-------------| +| `OBSIDIAN_REST_API_KEY` | API key from the Local REST API plugin | +| `OBSIDIAN_REST_BASE_URL` | REST API URL (default: `https://127.0.0.1:27124`) | + +## Usage Examples + +### Read a note +```python +obsidian_read_note(path="Projects/hive-contributions.md") +``` + +### Write a note +```python +obsidian_write_note(path="Daily/2026-03-30.md", content="# Today\n\n- Submitted PR") +``` + +### Search the vault +```python +obsidian_search(query="event bus tests", context_length=100) +``` + +### List files in a folder +```python +obsidian_list_files(path="Projects/") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "OBSIDIAN_REST_API_KEY not set", "help": "Set OBSIDIAN_REST_API_KEY environment variable or configure via credential store"} +{"error": "Obsidian API error (HTTP 404): Note not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/pagerduty_tool/README.md b/tools/src/aden_tools/tools/pagerduty_tool/README.md new file mode 100644 index 00000000..cf88edc9 --- /dev/null +++ b/tools/src/aden_tools/tools/pagerduty_tool/README.md @@ -0,0 +1,62 @@ +# PagerDuty Tool + +Manage incidents, services, on-calls, and escalation policies via the PagerDuty REST API v2. + +## Tools + +| Tool | Description | +|------|-------------| +| `pagerduty_list_incidents` | List incidents with status, urgency, and date filters | +| `pagerduty_get_incident` | Get details of a specific incident | +| `pagerduty_create_incident` | Create a new incident | +| `pagerduty_update_incident` | Update an incident's status or assignment | +| `pagerduty_list_services` | List services with optional name filter | +| `pagerduty_list_oncalls` | List current on-call schedules | +| `pagerduty_add_incident_note` | Add a note to an incident | +| `pagerduty_list_escalation_policies` | List escalation policies | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `PAGERDUTY_API_KEY` | PagerDuty REST API token | +| `PAGERDUTY_FROM_EMAIL` | Email address for write operations (used in `From` header) | + +Get a token at: [PagerDuty API Access Keys](https://support.pagerduty.com/docs/api-access-keys) + +## Usage Examples + +### List triggered incidents +```python +pagerduty_list_incidents(statuses=["triggered", "acknowledged"], limit=10) +``` + +### Create an incident +```python +pagerduty_create_incident( + title="Database connection pool exhausted", + service_id="P1234AB", + urgency="high", +) +``` + +### Acknowledge an incident +```python +pagerduty_update_incident(incident_id="P5678CD", status="acknowledged") +``` + +### Check who's on call +```python +pagerduty_list_oncalls() +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "PAGERDUTY_API_KEY is required", "help": "Set PAGERDUTY_API_KEY environment variable"} +{"error": "PagerDuty API error (HTTP 404): Incident not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/pipedrive_tool/README.md b/tools/src/aden_tools/tools/pipedrive_tool/README.md new file mode 100644 index 00000000..76d01d9a --- /dev/null +++ b/tools/src/aden_tools/tools/pipedrive_tool/README.md @@ -0,0 +1,72 @@ +# Pipedrive Tool + +Manage deals, contacts, organizations, activities, and pipelines using the Pipedrive CRM API. + +## Tools + +| Tool | Description | +|------|-------------| +| `pipedrive_list_deals` | List deals with status, stage, and sort filters | +| `pipedrive_get_deal` | Get details of a specific deal | +| `pipedrive_create_deal` | Create a new deal | +| `pipedrive_update_deal` | Update a deal's properties | +| `pipedrive_list_persons` | List contacts with optional search | +| `pipedrive_search_persons` | Search contacts by name or email | +| `pipedrive_create_person` | Create a new contact | +| `pipedrive_list_organizations` | List organizations | +| `pipedrive_list_activities` | List activities with type and date filters | +| `pipedrive_create_activity` | Create a new activity | +| `pipedrive_list_pipelines` | List all sales pipelines | +| `pipedrive_list_stages` | List stages in a pipeline | +| `pipedrive_add_note` | Add a note to a deal, person, or organization | + +## Setup + +Set the following environment variable: + +| Variable | Description | +|----------|-------------| +| `PIPEDRIVE_API_TOKEN` | Pipedrive API token | + +Get a token at: Settings > Personal preferences > API in your Pipedrive account. + +## Usage Examples + +### List open deals +```python +pipedrive_list_deals(status="open", sort="update_time DESC", limit=20) +``` + +### Search for a contact +```python +pipedrive_search_persons(term="jane@example.com") +``` + +### Create a deal +```python +pipedrive_create_deal(title="Enterprise License", value=50000, currency="USD") +``` + +### Create a contact +```python +pipedrive_create_person(name="Jane Doe", email="jane@example.com") +``` + +### Create an activity +```python +pipedrive_create_activity(subject="Follow-up call", activity_type="call", due_date="2026-04-15") +``` + +### Add a note to a deal +```python +pipedrive_add_note(content="Follow up scheduled for next week.", deal_id=12345) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "PIPEDRIVE_API_TOKEN not set", "help": "Get your API token from Pipedrive Settings > Personal preferences > API"} +{"error": "Pipedrive API error (HTTP 404): Deal not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/plaid_tool/README.md b/tools/src/aden_tools/tools/plaid_tool/README.md new file mode 100644 index 00000000..64cec9c3 --- /dev/null +++ b/tools/src/aden_tools/tools/plaid_tool/README.md @@ -0,0 +1,57 @@ +# Plaid Tool + +Access bank accounts, balances, and transactions using the Plaid API. + +## Tools + +| Tool | Description | +|------|-------------| +| `plaid_get_accounts` | List linked bank accounts | +| `plaid_get_balance` | Get real-time account balances | +| `plaid_sync_transactions` | Sync new transactions incrementally | +| `plaid_get_transactions` | Get transactions with date range and filters | +| `plaid_get_institution` | Get details about a financial institution | +| `plaid_search_institutions` | Search for institutions by name | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `PLAID_CLIENT_ID` | Plaid client ID | +| `PLAID_SECRET` | Plaid secret key | +| `PLAID_ENV` | Environment: `sandbox`, `development`, or `production` (default: `sandbox`) | + +Get credentials at: [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) + +## Usage Examples + +### Get account balances +```python +plaid_get_balance(access_token="access-sandbox-abc123") +``` + +### Get recent transactions +```python +plaid_get_transactions( + access_token="access-sandbox-abc123", + start_date="2026-01-01", + end_date="2026-01-31", + count=50, +) +``` + +### Search for a bank +```python +plaid_search_institutions(query="Chase", count=5) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "PLAID_CLIENT_ID and PLAID_SECRET not set", "help": "Get credentials at https://dashboard.plaid.com/developers/keys"} +{"error": "Plaid API error: INVALID_ACCESS_TOKEN"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/powerbi_tool/README.md b/tools/src/aden_tools/tools/powerbi_tool/README.md new file mode 100644 index 00000000..03b11953 --- /dev/null +++ b/tools/src/aden_tools/tools/powerbi_tool/README.md @@ -0,0 +1,56 @@ +# Power BI Tool + +Manage Power BI workspaces, datasets, and reports via the Power BI REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `powerbi_list_workspaces` | List workspaces with optional name filter | +| `powerbi_list_datasets` | List datasets in a workspace | +| `powerbi_list_reports` | List reports in a workspace | +| `powerbi_refresh_dataset` | Trigger a dataset refresh | +| `powerbi_get_refresh_history` | Get refresh history for a dataset | + +## Setup + +Set the following environment variable: + +| Variable | Description | +|----------|-------------| +| `POWERBI_ACCESS_TOKEN` | Power BI REST API bearer token | + +Get a token via Azure AD: [Power BI REST API](https://learn.microsoft.com/en-us/power-bi/developer/embedded/register-app) + +Required permissions: `Dataset.ReadWrite.All`, `Workspace.Read.All` + +## Usage Examples + +### List workspaces +```python +powerbi_list_workspaces() +``` + +### List datasets in a workspace +```python +powerbi_list_datasets(workspace_id="abc-123") +``` + +### Trigger a dataset refresh +```python +powerbi_refresh_dataset(workspace_id="abc-123", dataset_id="def-456") +``` + +### Check refresh history +```python +powerbi_get_refresh_history(workspace_id="abc-123", dataset_id="def-456") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "POWERBI_ACCESS_TOKEN is required", "help": "Set POWERBI_ACCESS_TOKEN environment variable"} +{"error": "Power BI API error (HTTP 403): Insufficient permissions"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/quickbooks_tool/README.md b/tools/src/aden_tools/tools/quickbooks_tool/README.md new file mode 100644 index 00000000..c8413cd5 --- /dev/null +++ b/tools/src/aden_tools/tools/quickbooks_tool/README.md @@ -0,0 +1,61 @@ +# QuickBooks Tool + +Manage customers, invoices, payments, and company info using the QuickBooks Online API. + +## Tools + +| Tool | Description | +|------|-------------| +| `quickbooks_query` | Run a QuickBooks SQL-like query | +| `quickbooks_get_entity` | Get any entity by type and ID | +| `quickbooks_create_customer` | Create a new customer | +| `quickbooks_create_invoice` | Create a new invoice | +| `quickbooks_get_company_info` | Get company information | +| `quickbooks_list_invoices` | List invoices with date and status filters | +| `quickbooks_get_customer` | Get a customer by ID | +| `quickbooks_create_payment` | Record a payment against an invoice | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `QUICKBOOKS_ACCESS_TOKEN` | OAuth2 access token | +| `QUICKBOOKS_REALM_ID` | QuickBooks company/realm ID | + +Get credentials at: [Intuit Developer Portal](https://developer.intuit.com/) + +## Usage Examples + +### Query customers +```python +quickbooks_query(query="SELECT * FROM Customer WHERE DisplayName LIKE '%Acme%'") +``` + +### Create a customer +```python +quickbooks_create_customer(display_name="Acme Corp", email="billing@acme.com") +``` + +### Create an invoice +```python +quickbooks_create_invoice( + customer_id="123", + line_items=[{"description": "Consulting", "amount": 5000, "quantity": 1}], +) +``` + +### List recent invoices +```python +quickbooks_list_invoices(start_date="2026-01-01", status="Overdue") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "QUICKBOOKS_ACCESS_TOKEN and QUICKBOOKS_REALM_ID are required", "help": "Set QUICKBOOKS_ACCESS_TOKEN and QUICKBOOKS_REALM_ID environment variables"} +{"error": "QuickBooks API error (HTTP 401): AuthenticationFailed"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/salesforce_tool/README.md b/tools/src/aden_tools/tools/salesforce_tool/README.md new file mode 100644 index 00000000..15768ef0 --- /dev/null +++ b/tools/src/aden_tools/tools/salesforce_tool/README.md @@ -0,0 +1,66 @@ +# Salesforce Tool + +Query, create, update, and manage Salesforce CRM records via the Salesforce REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `salesforce_soql_query` | Execute a SOQL query | +| `salesforce_get_record` | Get a record by object type and ID | +| `salesforce_create_record` | Create a new record | +| `salesforce_update_record` | Update an existing record | +| `salesforce_delete_record` | Delete a record | +| `salesforce_describe_object` | Get metadata and fields for an object type | +| `salesforce_list_objects` | List all available Salesforce objects | +| `salesforce_search_records` | Search records using SOSL | +| `salesforce_get_record_count` | Get the total count of records for an object | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `SALESFORCE_ACCESS_TOKEN` | OAuth2 access token | +| `SALESFORCE_INSTANCE_URL` | Salesforce instance URL (e.g., `https://yourorg.salesforce.com`) | + +Get credentials at: [Salesforce Connected Apps](https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm) + +## Usage Examples + +### Query contacts +```python +salesforce_soql_query(query="SELECT Id, Name, Email FROM Contact WHERE Email != null LIMIT 10") +``` + +### Create a lead +```python +salesforce_create_record( + object_type="Lead", + fields={"FirstName": "Jane", "LastName": "Doe", "Company": "Acme"}, +) +``` + +### Update an opportunity +```python +salesforce_update_record( + object_type="Opportunity", + record_id="006xx000001234", + fields={"StageName": "Closed Won", "Amount": 50000}, +) +``` + +### Search across objects +```python +salesforce_search_records(search_query="FIND {Acme} IN ALL FIELDS RETURNING Account, Contact") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "Salesforce credentials not configured", "help": "Set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL environment variables or configure via credential store"} +{"error": "Salesforce API error (HTTP 400): MALFORMED_QUERY"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/sap_tool/README.md b/tools/src/aden_tools/tools/sap_tool/README.md new file mode 100644 index 00000000..6f13d5e3 --- /dev/null +++ b/tools/src/aden_tools/tools/sap_tool/README.md @@ -0,0 +1,56 @@ +# SAP Tool + +Access SAP S/4HANA data via OData APIs — purchase orders, business partners, products, and sales orders. + +## Tools + +| Tool | Description | +|------|-------------| +| `sap_list_purchase_orders` | List purchase orders with optional filters | +| `sap_get_purchase_order` | Get details of a specific purchase order | +| `sap_list_business_partners` | List business partners with search and category filters | +| `sap_list_products` | List products with optional search | +| `sap_list_sales_orders` | List sales orders with customer and date filters | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `SAP_BASE_URL` | SAP S/4HANA OData base URL | +| `SAP_USERNAME` | SAP username for Basic Auth | +| `SAP_PASSWORD` | SAP password for Basic Auth | + +Get credentials from your SAP system administrator. + +## Usage Examples + +### List purchase orders +```python +sap_list_purchase_orders(top=20) +``` + +### Get a specific purchase order +```python +sap_get_purchase_order(purchase_order="4500000001") +``` + +### Search business partners +```python +sap_list_business_partners(search="Acme", category="supplier", top=10) +``` + +### List recent sales orders +```python +sap_list_sales_orders(top=20) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "SAP_BASE_URL, SAP_USERNAME, and SAP_PASSWORD are required", "help": "Set SAP_BASE_URL, SAP_USERNAME, and SAP_PASSWORD environment variables"} +{"error": "SAP API error (HTTP 404): Resource not found"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/terraform_tool/README.md b/tools/src/aden_tools/tools/terraform_tool/README.md new file mode 100644 index 00000000..34d9de8e --- /dev/null +++ b/tools/src/aden_tools/tools/terraform_tool/README.md @@ -0,0 +1,57 @@ +# Terraform Tool + +Manage Terraform Cloud/Enterprise workspaces and runs via the Terraform API. + +## Tools + +| Tool | Description | +|------|-------------| +| `terraform_list_workspaces` | List workspaces in an organization | +| `terraform_get_workspace` | Get details of a specific workspace | +| `terraform_list_runs` | List runs for a workspace | +| `terraform_get_run` | Get details of a specific run | +| `terraform_create_run` | Trigger a new plan/apply run | + +## Setup + +Set the following environment variable: + +| Variable | Description | +|----------|-------------| +| `TFC_TOKEN` | Terraform Cloud/Enterprise API token | +| `TFC_URL` | Terraform Enterprise URL (optional, defaults to Terraform Cloud) | + +Get a token at: [Terraform Cloud Tokens](https://app.terraform.io/app/settings/tokens) + +Note: The `organization` name is passed as a parameter to tools, not as an environment variable. + +## Usage Examples + +### List workspaces +```python +terraform_list_workspaces(organization="my-org") +``` + +### Get workspace details +```python +terraform_get_workspace(workspace_id="ws-abc123") +``` + +### List runs for a workspace +```python +terraform_list_runs(workspace_id="ws-abc123") +``` + +### Trigger a new run +```python +terraform_create_run(workspace_id="ws-abc123", message="Deploy v2.1.0") +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "TFC_TOKEN is required", "help": "Set TFC_TOKEN environment variable"} +{"error": "organization is required"} +{"error": "Request timed out"} +``` diff --git a/tools/src/aden_tools/tools/tines_tool/README.md b/tools/src/aden_tools/tools/tines_tool/README.md new file mode 100644 index 00000000..248565e1 --- /dev/null +++ b/tools/src/aden_tools/tools/tines_tool/README.md @@ -0,0 +1,55 @@ +# Tines Tool + +Manage Tines automation stories and actions via the Tines API. + +## Tools + +| Tool | Description | +|------|-------------| +| `tines_list_stories` | List stories with optional status filter | +| `tines_get_story` | Get details of a specific story | +| `tines_list_actions` | List actions in a story | +| `tines_get_action` | Get details of a specific action | +| `tines_get_action_logs` | Get execution logs for an action | + +## Setup + +Set the following environment variables: + +| Variable | Description | +|----------|-------------| +| `TINES_API_KEY` | Tines API key | +| `TINES_DOMAIN` | Tines tenant URL (e.g., `https://your-tenant.tines.com`) | + +Get an API key at: Settings → API Keys in your Tines account. + +## Usage Examples + +### List all stories +```python +tines_list_stories() +``` + +### Get story details +```python +tines_get_story(story_id=12345) +``` + +### List actions in a story +```python +tines_list_actions(story_id=12345) +``` + +### Get action logs +```python +tines_get_action_logs(action_id=67890) +``` + +## Error Handling + +All tools return error dicts on failure: +```python +{"error": "TINES_DOMAIN and TINES_API_KEY are required", "help": "Set TINES_DOMAIN and TINES_API_KEY environment variables"} +{"error": "Tines API error (HTTP 404): Story not found"} +{"error": "Request timed out"} +``` From aaa5d661c3a15fb219586a5dae5db14275dea428 Mon Sep 17 00:00:00 2001 From: Hundao <38208494+Hundao@users.noreply.github.com> Date: Sun, 5 Apr 2026 14:21:32 +0800 Subject: [PATCH 12/28] fix(ci): unbreak main - playwright deps + framework test suite (#6955) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(tools): move playwright back to main dependencies playwright was moved to the browser extra in c7e85aa9 as part of the GCU refactor to use a browser extension. But web_scrape_tool still imports playwright at module level and requires it unconditionally, so CI's Test Tools job breaks with ModuleNotFoundError. web_scrape_tool has no fallback without playwright — it's a hard dependency, not optional. Put it back in main deps. Fixes CI failure on Test Tools (ubuntu-latest). * chore: remove dead test_highlights.py script tools/test_highlights.py is orphaned from the GCU refactor in c7e85aa9: - imports highlight_coordinate and highlight_element from gcu.browser.highlight, but highlight.py was deleted in that refactor - calls BrowserSession.start(), open_tab(), get_active_page(), stop() — none of these methods exist on the current BrowserSession class The script can't run at all, and it's tripping ruff's I001 import-order check (fail on Lint CI after cache invalidation). * test: fix browser/refs tests broken by GCU refactor Tests were still testing the old Playwright-based API after c7e85aa9 moved GCU to an extension-bridge architecture. test_refs.py (6 tests): Refs system now produces CSS selectors like [role="button"][aria-label="Submit"]:nth-of-type(1) for the bridge's DOM matcher, instead of Playwright's role=button[name="Submit"] >> nth=0. Updated expected values to match. Renamed test_escapes_quotes_in_name to test_quoted_name_passes_through and added a comment noting that inner quotes aren't currently escaped (follow-up concern). test_browser_tools_comprehensive.py (4 tests): - test_screenshot_full_page: browser_screenshot passes selector=None when no selector is provided; update assertion. - test_file_upload: browser_upload validates file paths exist on disk. Create real tmp files and mock the CDP calls it makes. - test_evaluate_with_bare_return: renamed to test_evaluate_passes_script_through_to_bridge. IIFE wrapping lives in bridge.evaluate, not in the browser_evaluate tool — mocking the bridge bypasses the wrapping logic, so the tool just passes the script through. - test_evaluate_complex_script: browser_evaluate returns bridge's raw result (no 'ok' wrapper); check for 'result' key instead. test_browser_advanced_tools.py (deleted): The whole file patched get_session and page.wait_for_function (the old Playwright-based API). The bug it guarded against (user text interpolated into a JS source string) is architecturally impossible in the new bridge-based tools, which send text via structured RPC. Coverage for browser_wait exists in test_browser_tools_comprehensive.py. * test(core): fix event_loop tests broken by hive-v1 refactor Several framework tests were left failing or hanging after the hive-v1 refactor landed. This un-breaks CI without touching production code. - Worker auto-escalation: 8 tests were hanging because EventLoopNode with event_bus treats non-queen/non-subagent nodes as workers and auto-escalates to queen, then blocks on _await_user_input forever (no queen in standalone tests). Opt out via is_subagent_mode=True. - MockConversationStore: added clear() to match the production store (storage/conversation_store.py), which event_loop_node.py:425 calls. - Executor output semantics: result.output now only contains terminal- node outputs; two handoff tests now read intermediate outputs from result.session_state["data_buffer"]. - Restore filter: test_restore_from_checkpoint needs set_current_phase so restore()'s phase_id filter matches. - Removed two _build_context tests whose target method no longer exists (replaced by standalone build_node_context()). Remaining execution_id coverage is adequate in TestExecutionId + integration tests. * style: ruff format + drop em dash in comment * test(core): fix remaining framework tests broken by hive-v1 refactor Rounds out the fix started in the previous commit. Full framework suite now passes (1589 passed, 0 failed). - conftest.py: force-bind framework.runner submodules (mcp_registry, mcp_client, mcp_connection_manager) as attributes on the parent package. Without this, pytest monkeypatch.setattr with dotted-string paths fails because the attribute walker can't resolve the submodule even though __init__.py imports from it. Affects ~25 MCP tests. - test_queen_memory: _execute_tool() grew a required caller kwarg for worker type-restrictions. Pass caller="queen" so path-traversal checks run without caller restrictions interfering. - test_session_manager_worker_handoff: _subscribe_worker_digest was removed in the refactor, dropped the dead monkeypatches. - test_skill_context_protection: NodeConversation now reads _run_id in add_tool_result(), so the __new__-based test helper has to initialise it. - test_node_conversation: restore() now filters parts by run_id for crash recovery. Renamed the stale test and flipped the assertion to match the new filtering semantics. - test_tool_registry: CONTEXT_PARAMS was updated (workspace_id out, profile in). Switched the test's example stripped params. * docs: drop circular PR reference in test_refs comment Addresses CodeRabbit nitpick. The comment referenced the PR that was adding the comment, which becomes a self-reference after merge. --- core/pyproject.toml | 2 +- core/tests/conftest.py | 18 ++++ core/tests/test_event_loop_integration.py | 33 ++++++-- core/tests/test_event_loop_node.py | 80 ++++++++---------- core/tests/test_node_conversation.py | 10 ++- core/tests/test_queen_memory.py | 18 +++- .../test_session_manager_worker_handoff.py | 3 - core/tests/test_skill_context_protection.py | 1 + core/tests/test_tool_registry.py | 10 +-- tools/pyproject.toml | 6 +- tools/test_highlights.py | 84 ------------------- tools/tests/test_browser_advanced_tools.py | 42 ---------- .../tests/test_browser_tools_comprehensive.py | 52 ++++++++---- tools/tests/test_refs.py | 24 +++--- uv.lock | 12 +-- 15 files changed, 165 insertions(+), 230 deletions(-) create mode 100644 core/tests/conftest.py delete mode 100644 tools/test_highlights.py delete mode 100644 tools/tests/test_browser_advanced_tools.py diff --git a/core/pyproject.toml b/core/pyproject.toml index 8fff708d..d79e1022 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -74,4 +74,4 @@ dev = [ "pytest>=8.0", "pytest-asyncio>=0.23", "pytest-xdist>=3.0", - ] +] diff --git a/core/tests/conftest.py b/core/tests/conftest.py new file mode 100644 index 00000000..903e2d3e --- /dev/null +++ b/core/tests/conftest.py @@ -0,0 +1,18 @@ +"""Test setup for framework tests.""" + +from __future__ import annotations + +# Ensure framework.runner submodules are bound as attributes on their parent +# package. Under this repo's layout, `from framework.runner.foo import X` does +# not always bind `foo` onto `framework.runner` (observed via dir() inspection), +# which breaks `monkeypatch.setattr("framework.runner.foo.Y", ...)` because the +# pytest path resolver walks attributes. Force the bindings here so tests can +# patch submodule attributes via the dotted-string API. +import framework.runner # noqa: F401 — load parent package first +import framework.runner.mcp_client as _mcp_client +import framework.runner.mcp_connection_manager as _mcp_connection_manager +import framework.runner.mcp_registry as _mcp_registry + +framework.runner.mcp_registry = _mcp_registry +framework.runner.mcp_connection_manager = _mcp_connection_manager +framework.runner.mcp_client = _mcp_client diff --git a/core/tests/test_event_loop_integration.py b/core/tests/test_event_loop_integration.py index 8ecc99b3..72096e13 100644 --- a/core/tests/test_event_loop_integration.py +++ b/core/tests/test_event_loop_integration.py @@ -168,6 +168,13 @@ class MockConversationStore: async def close(self) -> None: pass + async def clear(self) -> None: + # Clear parts, cursor, and meta — keep the store object alive. + # Matches the real store (storage/conversation_store.py:clear). + self._parts.clear() + self._cursor = None + self._meta = None + async def destroy(self) -> None: self._parts.clear() self._meta = None @@ -246,6 +253,7 @@ def make_ctx( client_facing: bool = False, available_tools: list[Tool] | None = None, stream_id: str = "", + is_subagent_mode: bool = False, ) -> NodeContext: """Build a NodeContext for direct EventLoopNode testing.""" runtime = MagicMock(spec=Runtime) @@ -278,6 +286,7 @@ def make_ctx( llm=llm, available_tools=available_tools or [], stream_id=stream_id, + is_subagent_mode=is_subagent_mode, ) @@ -474,7 +483,12 @@ async def test_event_loop_with_event_bus(): scripts = [StreamScript(text="All done.")] llm = make_llm(scripts) - ctx = make_ctx(llm=llm, output_keys=[]) + # is_subagent_mode=True bypasses worker auto-escalation in EventLoopNode. + # When event_bus is provided, a non-queen/non-subagent node is treated as + # a worker and auto-escalates to queen after a text-only turn (grace=1), + # then blocks forever on _await_user_input waiting for queen guidance. + # Standalone unit tests have no queen, so we mark as subagent to opt out. + ctx = make_ctx(llm=llm, output_keys=[], is_subagent_mode=True) node = EventLoopNode( event_bus=bus, @@ -1000,10 +1014,13 @@ async def test_context_handoff_between_nodes(runtime): result = await executor.execute(graph, goal, {}) assert result.success - assert "lead_score" in result.output + # After hive-v1 executor refactor, result.output only contains terminal + # node outputs. Full buffer (with handoff data) is in session_state. assert "strategy" in result.output + buffer_data = result.session_state.get("data_buffer", {}) + assert "lead_score" in buffer_data if USE_MOCK_LLM: - assert result.output["lead_score"] == 92 + assert buffer_data["lead_score"] == 92 assert result.output["strategy"] == "premium" @@ -1068,7 +1085,8 @@ async def test_internal_node_no_client_output(): scripts = [StreamScript(text="Internal processing.")] llm = make_llm(scripts) - ctx = make_ctx(llm=llm, output_keys=[], client_facing=False) + # is_subagent_mode=True: standalone test, opts out of worker auto-escalation. + ctx = make_ctx(llm=llm, output_keys=[], client_facing=False, is_subagent_mode=True) node = EventLoopNode( event_bus=bus, @@ -1167,10 +1185,13 @@ async def test_mixed_node_graph(runtime): result = await executor.execute(graph, goal, {}) assert result.success - assert "summary" in result.output + # Terminal node is "format" - only its output appears in result.output. + # Intermediate outputs are in session_state's data buffer. assert "report" in result.output + buffer_data = result.session_state.get("data_buffer", {}) + assert "summary" in buffer_data if USE_MOCK_LLM: - assert "3 leads processed" in result.output["summary"] + assert "3 leads processed" in buffer_data["summary"] # =========================================================================== diff --git a/core/tests/test_event_loop_node.py b/core/tests/test_event_loop_node.py index bad425e8..7516d455 100644 --- a/core/tests/test_event_loop_node.py +++ b/core/tests/test_event_loop_node.py @@ -147,8 +147,16 @@ def build_ctx( input_data=None, goal_context="", stream_id=None, + is_subagent_mode=False, ): - """Build a NodeContext for testing.""" + """Build a NodeContext for testing. + + When EventLoopNode is constructed with event_bus, a non-queen/non-subagent + node is treated as a worker and auto-escalates to queen on text-only turns + (see event_loop_node.py:1277). Standalone tests with event_bus but no queen + should pass is_subagent_mode=True to opt out, otherwise the loop hangs + forever waiting for queen guidance that never arrives. + """ return NodeContext( runtime=runtime, node_id=node_spec.id, @@ -159,6 +167,7 @@ def build_ctx( available_tools=tools or [], goal_context=goal_context, stream_id=stream_id, + is_subagent_mode=is_subagent_mode, ) @@ -423,7 +432,8 @@ class TestEventBusLifecycle: handler=lambda e: received_events.append(e.type), ) - ctx = build_ctx(runtime, node_spec, buffer, llm) + # Subagent mode opts out of worker auto-escalation (no queen in tests). + ctx = build_ctx(runtime, node_spec, buffer, llm, is_subagent_mode=True) node = EventLoopNode(event_bus=bus, config=LoopConfig(max_iterations=5)) result = await node.execute(ctx) @@ -805,15 +815,13 @@ class TestEscalate: bus.subscribe(event_types=[EventType.ESCALATION_REQUESTED], handler=capture) - ctx = build_ctx(runtime, node_spec, buffer, llm, stream_id="worker") + # is_subagent_mode=True: test drives node.execute() directly, so this + # runs in subagent pattern (no queen). Opts out of worker auto-escalation + # that would otherwise fire extra ESCALATION_REQUESTED events on + # subsequent text-only turns. + ctx = build_ctx(runtime, node_spec, buffer, llm, stream_id="worker", is_subagent_mode=True) node = EventLoopNode(event_bus=bus, config=LoopConfig(max_iterations=5)) - async def queen_reply(): - await asyncio.sleep(0.05) - await node.inject_event("Acknowledged, proceed.") - - task = asyncio.create_task(queen_reply()) - async def queen_reply(): await asyncio.sleep(0.05) await node.inject_event("Acknowledged, proceed.") @@ -855,7 +863,9 @@ class TestEscalate: queen_executor.node_registry = {"queen": queen_node} manager._subscribe_worker_handoffs(session, queen_executor) - ctx = build_ctx(runtime, node_spec, buffer, llm, stream_id="worker") + # is_subagent_mode=True opts out of worker auto-escalation. + # Standalone test without real queen loop, see other escalate tests. + ctx = build_ctx(runtime, node_spec, buffer, llm, stream_id="worker", is_subagent_mode=True) node = EventLoopNode(event_bus=bus, config=LoopConfig(max_iterations=5)) async def queen_reply(): @@ -1300,6 +1310,9 @@ class TestCrashRecovery: output_keys=["result"], store=store, ) + # Tag messages with phase_id matching the node so restore() finds them. + # Restore filters parts by phase_id=ctx.node_id in non-continuous mode. + conv.set_current_phase(node_spec.id) await conv.add_user_message("Initial input") await conv.add_assistant_message("Working on it...") @@ -1754,7 +1767,8 @@ class TestTransientErrorRetry: handler=lambda e: retry_events.append(e), ) - ctx = build_ctx(runtime, node_spec, buffer, llm) + # is_subagent_mode=True opts out of worker auto-escalation. + ctx = build_ctx(runtime, node_spec, buffer, llm, is_subagent_mode=True) node = EventLoopNode( event_bus=bus, config=LoopConfig( @@ -2084,12 +2098,14 @@ class TestToolDoomLoopIntegration: is_error=False, ) + # is_subagent_mode=True opts out of worker auto-escalation. ctx = build_ctx( runtime, node_spec, buffer, llm, tools=[Tool(name="search", description="s", parameters={})], + is_subagent_mode=True, ) node = EventLoopNode( judge=judge, @@ -2147,6 +2163,9 @@ class TestToolDoomLoopIntegration: is_error=False, ) + # is_subagent_mode=True opts out of worker auto-escalation. The + # test still exercises worker doom-loop escalation (a separate path) + # via the doom-loop detection at event_loop_node.py:1229. ctx = build_ctx( runtime, spec, @@ -2154,6 +2173,7 @@ class TestToolDoomLoopIntegration: llm, tools=[Tool(name="search", description="s", parameters={})], stream_id="worker", + is_subagent_mode=True, ) node = EventLoopNode( judge=judge, @@ -2352,12 +2372,14 @@ class TestToolDoomLoopIntegration: is_error=True, ) + # is_subagent_mode=True opts out of worker auto-escalation. ctx = build_ctx( runtime, node_spec, buffer, llm, tools=[Tool(name="failing_tool", description="s", parameters={})], + is_subagent_mode=True, ) node = EventLoopNode( judge=judge, @@ -2409,42 +2431,6 @@ class TestExecutionId: adapter = StreamRuntimeAdapter(stream_runtime=mock_stream_runtime, execution_id="exec_456") assert adapter.execution_id == "exec_456" - def test_build_context_passes_execution_id_from_adapter(self): - """_build_context picks up execution_id from a StreamRuntimeAdapter runtime.""" - from framework.graph.executor import GraphExecutor - from framework.graph.goal import Goal - - runtime = MagicMock() - runtime.execution_id = "exec_123" - executor = GraphExecutor(runtime=runtime) - - goal = Goal(id="g1", name="test", description="test", success_criteria=[]) - node_spec = NodeSpec( - id="n1", name="n1", description="test", node_type="event_loop", output_keys=["r"] - ) - ctx = executor._build_context( - node_spec=node_spec, buffer=DataBuffer(), goal=goal, input_data={} - ) - assert ctx.execution_id == "exec_123" - - def test_build_context_defaults_execution_id_for_plain_runtime(self): - """Plain Runtime.execution_id returns '' by default.""" - from framework.graph.executor import GraphExecutor - from framework.graph.goal import Goal - - runtime = MagicMock(spec=Runtime) - runtime.execution_id = "" - executor = GraphExecutor(runtime=runtime) - - goal = Goal(id="g1", name="test", description="test", success_criteria=[]) - node_spec = NodeSpec( - id="n1", name="n1", description="test", node_type="event_loop", output_keys=["r"] - ) - ctx = executor._build_context( - node_spec=node_spec, buffer=DataBuffer(), goal=goal, input_data={} - ) - assert ctx.execution_id == "" - # --------------------------------------------------------------------------- # Subagent data buffer snapshot includes accumulator outputs diff --git a/core/tests/test_node_conversation.py b/core/tests/test_node_conversation.py index 2662149d..d47eaa3b 100644 --- a/core/tests/test_node_conversation.py +++ b/core/tests/test_node_conversation.py @@ -476,7 +476,13 @@ class TestPersistence: assert restored.messages[0].content == "u1" @pytest.mark.asyncio - async def test_restore_ignores_run_id_and_loads_all_parts(self): + async def test_restore_filters_by_run_id_for_crash_recovery(self): + """Restore with a non-legacy run_id only loads parts from that run. + + This ensures intentional restarts (new run_id) start fresh while + crash recovery (same run_id) resumes correctly. Legacy parts (no + run_id) and other runs' parts are excluded. + """ store = MockConversationStore() await store.write_meta({"system_prompt": "hello"}) await store.write_part(0, {"seq": 0, "role": "user", "content": "legacy"}) @@ -489,7 +495,7 @@ class TestPersistence: restored = await NodeConversation.restore(store, run_id="run-a") assert restored is not None - assert [m.content for m in restored.messages] == ["legacy", "run-a", "run-b"] + assert [m.content for m in restored.messages] == ["run-a"] assert restored.next_seq == 3 @pytest.mark.asyncio diff --git a/core/tests/test_queen_memory.py b/core/tests/test_queen_memory.py index 4e9121b8..cd7fe65a 100644 --- a/core/tests/test_queen_memory.py +++ b/core/tests/test_queen_memory.py @@ -410,7 +410,9 @@ def test_path_traversal_read(tmp_path: Path): from framework.agents.queen.reflection_agent import _execute_tool (tmp_path / "safe.md").write_text("safe content") - result = _execute_tool("read_memory_file", {"filename": "../../etc/passwd"}, tmp_path) + result = _execute_tool( + "read_memory_file", {"filename": "../../etc/passwd"}, tmp_path, caller="queen" + ) assert "ERROR" in result assert "path components not allowed" in result.lower() or "escapes" in result.lower() @@ -422,6 +424,7 @@ def test_path_traversal_write(tmp_path: Path): "write_memory_file", {"filename": "../escape.md", "content": "---\nname: evil\n---\nbad"}, tmp_path, + caller="queen", ) assert "ERROR" in result assert not (tmp_path.parent / "escape.md").exists() @@ -431,7 +434,9 @@ def test_path_traversal_delete(tmp_path: Path): from framework.agents.queen.reflection_agent import _execute_tool (tmp_path / "target.md").write_text("content") - result = _execute_tool("delete_memory_file", {"filename": "../target.md"}, tmp_path) + result = _execute_tool( + "delete_memory_file", {"filename": "../target.md"}, tmp_path, caller="queen" + ) assert "ERROR" in result assert (tmp_path / "target.md").exists() # not deleted @@ -443,14 +448,19 @@ def test_safe_path_accepted(tmp_path: Path): "write_memory_file", {"filename": "good-file.md", "content": "---\nname: good\n---\ncontent"}, tmp_path, + caller="queen", ) assert "Wrote" in result assert (tmp_path / "good-file.md").exists() - result = _execute_tool("read_memory_file", {"filename": "good-file.md"}, tmp_path) + result = _execute_tool( + "read_memory_file", {"filename": "good-file.md"}, tmp_path, caller="queen" + ) assert "content" in result - result = _execute_tool("delete_memory_file", {"filename": "good-file.md"}, tmp_path) + result = _execute_tool( + "delete_memory_file", {"filename": "good-file.md"}, tmp_path, caller="queen" + ) assert "Deleted" in result diff --git a/core/tests/test_session_manager_worker_handoff.py b/core/tests/test_session_manager_worker_handoff.py index 24af689a..6b9a90a5 100644 --- a/core/tests/test_session_manager_worker_handoff.py +++ b/core/tests/test_session_manager_worker_handoff.py @@ -147,7 +147,6 @@ async def test_load_worker_core_defaults_to_session_llm_model(monkeypatch, tmp_p monkeypatch.setattr("framework.runner.AgentRunner.load", fake_load) monkeypatch.setattr(manager, "_cleanup_stale_active_sessions", lambda *_args: None) - monkeypatch.setattr(manager, "_subscribe_worker_digest", lambda *_args: None) monkeypatch.setattr(manager, "_subscribe_worker_colony_memory", AsyncMock()) monkeypatch.setattr( "framework.tools.queen_lifecycle_tools._read_agent_triggers_json", @@ -184,7 +183,6 @@ async def test_load_worker_core_keeps_explicit_worker_model_override(monkeypatch monkeypatch.setattr("framework.runner.AgentRunner.load", fake_load) monkeypatch.setattr(manager, "_cleanup_stale_active_sessions", lambda *_args: None) - monkeypatch.setattr(manager, "_subscribe_worker_digest", lambda *_args: None) monkeypatch.setattr(manager, "_subscribe_worker_colony_memory", AsyncMock()) monkeypatch.setattr( "framework.tools.queen_lifecycle_tools._read_agent_triggers_json", @@ -220,7 +218,6 @@ async def test_load_worker_core_continues_when_colony_memory_subscription_fails( monkeypatch.setattr("framework.runner.AgentRunner.load", lambda *args, **kwargs: runner) monkeypatch.setattr(manager, "_cleanup_stale_active_sessions", lambda *_args: None) - monkeypatch.setattr(manager, "_subscribe_worker_digest", lambda *_args: None) monkeypatch.setattr( manager, "_subscribe_worker_colony_memory", diff --git a/core/tests/test_skill_context_protection.py b/core/tests/test_skill_context_protection.py index 894146b3..cf63ba81 100644 --- a/core/tests/test_skill_context_protection.py +++ b/core/tests/test_skill_context_protection.py @@ -11,6 +11,7 @@ def _make_conversation() -> NodeConversation: conv._next_seq = 0 conv._current_phase = None conv._store = None + conv._run_id = None return conv diff --git a/core/tests/test_tool_registry.py b/core/tests/test_tool_registry.py index 8c3a722f..14288670 100644 --- a/core/tests/test_tool_registry.py +++ b/core/tests/test_tool_registry.py @@ -688,20 +688,20 @@ def test_convert_mcp_tool_strips_context_params(): input_schema={ "type": "object", "properties": { - "workspace_id": {"type": "string"}, # context param → stripped "agent_id": {"type": "string"}, # context param → stripped + "data_dir": {"type": "string"}, # context param → stripped "query": {"type": "string"}, # regular param → kept }, - "required": ["workspace_id", "query"], + "required": ["agent_id", "query"], }, ) tool = registry._convert_mcp_tool_to_framework_tool(mcp_tool) # noqa: SLF001 props = tool.parameters["properties"] - assert "workspace_id" not in props assert "agent_id" not in props + assert "data_dir" not in props assert "query" in props - # workspace_id should also be stripped from required - assert "workspace_id" not in tool.parameters["required"] + # agent_id should also be stripped from required + assert "agent_id" not in tool.parameters["required"] assert "query" in tool.parameters["required"] diff --git a/tools/pyproject.toml b/tools/pyproject.toml index d22f2f04..8f2a85ef 100644 --- a/tools/pyproject.toml +++ b/tools/pyproject.toml @@ -26,6 +26,8 @@ dependencies = [ "fastmcp>=2.0.0", "diff-match-patch>=20230430", "python-dotenv>=1.0.0", + "playwright>=1.40.0", + "playwright-stealth>=2.0.0", "litellm==1.81.7", # pinned: supply chain attack in >=1.82.7 (adenhq/hive#6783) "dnspython>=2.4.0", "resend>=2.0.0", @@ -49,8 +51,6 @@ sandbox = [ ] browser = [ "pillow>=10.0.0", - "playwright>=1.40.0", - "playwright-stealth>=2.0.0", ] ocr = [ "pytesseract>=0.3.10", @@ -78,8 +78,6 @@ all = [ "google-cloud-bigquery>=3.0.0", "databricks-sdk>=0.30.0", "databricks-mcp>=0.1.0", - "playwright>=1.40.0", - "playwright-stealth>=2.0.0", ] [tool.uv.sources] diff --git a/tools/test_highlights.py b/tools/test_highlights.py deleted file mode 100644 index 535e4b2b..00000000 --- a/tools/test_highlights.py +++ /dev/null @@ -1,84 +0,0 @@ -""" -Manual test script for browser highlight animations. - -Launches a visible browser, goes to Google, searches "aden hive", -and clicks the first result — with highlight animations on each action. - -Usage: - python tools/test_highlights.py -""" - -import asyncio -import sys - -# Ensure the package is importable -sys.path.insert(0, "tools/src") - -from gcu.browser.highlight import highlight_coordinate, highlight_element -from gcu.browser.session import BrowserSession - - -async def step(label: str) -> None: - print(f"\n→ {label}") - - -async def main() -> None: - session = BrowserSession(profile="highlight-test") - - try: - # 1. Start browser (visible) - await step("Starting browser (headless=False)") - result = await session.start(headless=False, persistent=False) - print(f" {result}") - - # 2. Open a tab and navigate to Google - await step("Navigating to google.com") - result = await session.open_tab("https://www.google.com") - print(f" {result}") - - page = session.get_active_page() - assert page, "No active page" - - # Small pause so you can see the page load - await asyncio.sleep(1) - - # 3. Highlight + fill the search bar - selector = 'textarea[name="q"]' - await step(f"Highlighting search bar: {selector}") - await highlight_element(page, selector) - - await step("Filling search bar with 'aden hive'") - await page.fill(selector, "aden hive") - await asyncio.sleep(0.5) - - # 4. Press Enter to search - await step("Pressing Enter") - await page.press(selector, "Enter") - await page.wait_for_load_state("domcontentloaded", timeout=10000) - await asyncio.sleep(1) - - # 5. Highlight + click the first search result link - first_result = "#search a h3" - await step(f"Highlighting first result: {first_result}") - await highlight_element(page, first_result) - - await step("Clicking first result") - await page.click(first_result, timeout=10000) - await page.wait_for_load_state("domcontentloaded", timeout=10000) - await asyncio.sleep(1) - - # 6. Bonus: test coordinate highlight at center of viewport - await step("Testing coordinate highlight at viewport center (960, 540)") - await highlight_coordinate(page, 960, 540) - - print("\n✓ All steps complete. Browser stays open for 5 seconds...") - await asyncio.sleep(5) - - finally: - await step("Stopping browser") - await session.stop() - print("Done.") - - -if __name__ == "__main__": - asyncio.run(main()) diff --git a/tools/tests/test_browser_advanced_tools.py b/tools/tests/test_browser_advanced_tools.py deleted file mode 100644 index 8300b314..00000000 --- a/tools/tests/test_browser_advanced_tools.py +++ /dev/null @@ -1,42 +0,0 @@ -"""Tests for browser advanced tools.""" - -from unittest.mock import AsyncMock, MagicMock, patch - -import pytest -from fastmcp import FastMCP - -from gcu.browser.tools.advanced import register_advanced_tools - - -@pytest.fixture -def mcp() -> FastMCP: - """Create a fresh FastMCP instance for testing.""" - return FastMCP("test-browser-advanced") - - -@pytest.fixture -def browser_wait_fn(mcp): - """Register browser tools and return the browser_wait function.""" - register_advanced_tools(mcp) - return mcp._tool_manager._tools["browser_wait"].fn - - -@pytest.mark.asyncio -async def test_browser_wait_passes_text_as_function_argument(browser_wait_fn): - """Quoted and multiline text should be passed as data, not JS source.""" - text = "O'Reilly\nMedia" - page = MagicMock() - page.wait_for_function = AsyncMock() - - session = MagicMock() - session.get_page.return_value = page - - with patch("gcu.browser.tools.advanced.get_session", return_value=session): - result = await browser_wait_fn(text=text, timeout_ms=1234) - - assert result == {"ok": True, "action": "wait", "condition": "text", "text": text} - page.wait_for_function.assert_awaited_once_with( - "(text) => document.body.innerText.includes(text)", - arg=text, - timeout=1234, - ) diff --git a/tools/tests/test_browser_tools_comprehensive.py b/tools/tests/test_browser_tools_comprehensive.py index f172af50..1196358e 100644 --- a/tools/tests/test_browser_tools_comprehensive.py +++ b/tools/tests/test_browser_tools_comprehensive.py @@ -622,7 +622,7 @@ class TestInspection: # browser_screenshot returns list of content blocks assert isinstance(result, list) - mock_bridge.screenshot.assert_awaited_once_with(100, full_page=True) + mock_bridge.screenshot.assert_awaited_once_with(100, full_page=True, selector=None) class TestAdvancedTools: @@ -671,9 +671,27 @@ class TestAdvancedTools: assert result["result"]["value"]["status"] == "success" @pytest.mark.asyncio - async def test_file_upload(self, mcp: FastMCP, mock_bridge: MagicMock): + async def test_file_upload(self, mcp: FastMCP, mock_bridge: MagicMock, tmp_path): """Test file upload functionality.""" - mock_bridge.upload_file = AsyncMock(return_value={"ok": True, "files": 2}) + # Create real files — browser_upload validates they exist on disk + file1 = tmp_path / "file1.pdf" + file2 = tmp_path / "file2.pdf" + file1.write_bytes(b"fake pdf 1") + file2.write_bytes(b"fake pdf 2") + + # Mock the CDP calls used by browser_upload + mock_bridge.cdp_attach = AsyncMock(return_value={"ok": True}) + + async def mock_cdp(tab_id, method, params=None): + if method == "DOM.getDocument": + return {"root": {"nodeId": 1}} + if method == "DOM.querySelector": + return {"nodeId": 42} + if method == "DOM.setFileInputFiles": + return {"ok": True} + return {"ok": True} + + mock_bridge._cdp = AsyncMock(side_effect=mock_cdp) register_advanced_tools(mcp) browser_upload = mcp._tool_manager._tools["browser_upload"].fn @@ -685,10 +703,11 @@ class TestAdvancedTools: ): result = await browser_upload( selector="input[type='file']", - file_paths=["/tmp/file1.pdf", "/tmp/file2.pdf"], + file_paths=[str(file1), str(file2)], ) assert result.get("ok") is True + assert result.get("count") == 2 class TestErrorHandling: @@ -745,8 +764,14 @@ class TestIFWrapping: """Tests for JavaScript IIFE wrapping to handle return statements.""" @pytest.mark.asyncio - async def test_evaluate_with_bare_return(self, mcp: FastMCP, mock_bridge: MagicMock): - """Test that scripts with bare return statements are wrapped properly.""" + async def test_evaluate_passes_script_through_to_bridge( + self, mcp: FastMCP, mock_bridge: MagicMock + ): + """browser_evaluate should pass the script through to bridge.evaluate unchanged. + + IIFE wrapping happens inside bridge.evaluate (see bridge.py), not in + the tool layer. The tool's job is just to forward the script. + """ call_args = [] async def mock_evaluate_capture(tab_id: int, script: str) -> dict: @@ -763,15 +788,12 @@ class TestIFWrapping: "gcu.browser.tools.advanced._get_context", return_value={"groupId": 1, "activeTabId": 100}, ): - # Script with bare return at top level result = await browser_evaluate(script="return 42;") - # Verify the script was wrapped in IIFE - assert len(call_args) == 1 - wrapped_script = call_args[0] - assert wrapped_script.startswith("(function()") - assert wrapped_script.endswith("})()") - assert result.get("ok") is True + # Tool passes script through unchanged — wrapping is bridge's job + assert call_args == ["return 42;"] + # Tool returns bridge's raw result + assert result == {"result": {"value": 42}} @pytest.mark.asyncio async def test_evaluate_complex_script(self, mcp: FastMCP, mock_bridge: MagicMock): @@ -798,7 +820,9 @@ class TestIFWrapping: """ result = await browser_evaluate(script=complex_script) - assert result.get("ok") is True + # browser_evaluate returns bridge.evaluate's raw result + assert "result" in result + assert result["result"]["value"] == {"total": 100, "filtered": 50} class TestConcurrentOperations: diff --git a/tools/tests/test_refs.py b/tools/tests/test_refs.py index 109fb47c..a4eb0980 100644 --- a/tools/tests/test_refs.py +++ b/tools/tests/test_refs.py @@ -111,7 +111,7 @@ class TestResolveRef: "e0": RefEntry(role="button", name="Submit", nth=0), } result = resolve_ref("e0", ref_map) - assert result == 'role=button[name="Submit"] >> nth=0' + assert result == '[role="button"][aria-label="Submit"]:nth-of-type(1)' def test_passes_through_css_selectors(self): ref_map = {"e0": RefEntry(role="button", name="OK", nth=0)} @@ -133,33 +133,37 @@ class TestResolveRef: with pytest.raises(ValueError, match="no snapshot"): resolve_ref("e0", None) - def test_escapes_quotes_in_name(self): + def test_quoted_name_passes_through(self): + # Note: the CSS selector output does not currently escape inner quotes. + # This produces technically-broken CSS when name contains double quotes, + # but the bridge-based matcher appears to tolerate it. Tracked + # separately as a follow-up. ref_map = { "e0": RefEntry(role="button", name='Say "Hello"', nth=0), } result = resolve_ref("e0", ref_map) - assert result == 'role=button[name="Say \\"Hello\\""] >> nth=0' + assert result == '[role="button"][aria-label="Say "Hello""]:nth-of-type(1)' def test_no_name_produces_role_only_selector(self): ref_map = { "e0": RefEntry(role="textbox", name=None, nth=0), } result = resolve_ref("e0", ref_map) - assert result == "role=textbox >> nth=0" + assert result == '[role="textbox"]:nth-of-type(1)' def test_empty_name(self): ref_map = { "e0": RefEntry(role="button", name="", nth=0), } result = resolve_ref("e0", ref_map) - assert result == 'role=button[name=""] >> nth=0' + assert result == '[role="button"][aria-label=""]:nth-of-type(1)' def test_nth_in_selector(self): ref_map = { "e0": RefEntry(role="link", name="Next", nth=2), } result = resolve_ref("e0", ref_map) - assert result == 'role=link[name="Next"] >> nth=2' + assert result == '[role="link"][aria-label="Next"]:nth-of-type(3)' # --------------------------------------------------------------------------- @@ -172,13 +176,13 @@ class TestRoundTrip: snapshot = '- button "Submit"\n- textbox "Email"\n- link "Home"' _, ref_map = annotate_snapshot(snapshot) - # Each ref should resolve to a valid Playwright role selector + # Each ref should resolve to a valid CSS selector (bridge-based API) for ref_id, entry in ref_map.items(): resolved = resolve_ref(ref_id, ref_map) - assert resolved.startswith(f"role={entry.role}") + assert resolved.startswith(f'[role="{entry.role}"]') if entry.name is not None: - assert f'name="{entry.name}"' in resolved - assert f"nth={entry.nth}" in resolved + assert f'[aria-label="{entry.name}"]' in resolved + assert f":nth-of-type({entry.nth + 1})" in resolved def test_css_selectors_still_work_after_annotate(self): snapshot = '- button "OK"' diff --git a/uv.lock b/uv.lock index f4d44eaa..3f225ea7 100644 --- a/uv.lock +++ b/uv.lock @@ -3498,6 +3498,8 @@ dependencies = [ { name = "jsonpath-ng" }, { name = "litellm" }, { name = "pandas" }, + { name = "playwright" }, + { name = "playwright-stealth" }, { name = "psycopg2-binary" }, { name = "pydantic" }, { name = "pypdf" }, @@ -3516,8 +3518,6 @@ all = [ { name = "google-cloud-bigquery" }, { name = "openpyxl" }, { name = "pillow" }, - { name = "playwright" }, - { name = "playwright-stealth" }, { name = "pytesseract" }, { name = "restrictedpython" }, ] @@ -3526,8 +3526,6 @@ bigquery = [ ] browser = [ { name = "pillow" }, - { name = "playwright" }, - { name = "playwright-stealth" }, ] databricks = [ { name = "databricks-mcp" }, @@ -3585,10 +3583,8 @@ requires-dist = [ { name = "pillow", marker = "extra == 'all'", specifier = ">=10.0.0" }, { name = "pillow", marker = "extra == 'browser'", specifier = ">=10.0.0" }, { name = "pillow", marker = "extra == 'ocr'", specifier = ">=10.0.0" }, - { name = "playwright", marker = "extra == 'all'", specifier = ">=1.40.0" }, - { name = "playwright", marker = "extra == 'browser'", specifier = ">=1.40.0" }, - { name = "playwright-stealth", marker = "extra == 'all'", specifier = ">=2.0.0" }, - { name = "playwright-stealth", marker = "extra == 'browser'", specifier = ">=2.0.0" }, + { name = "playwright", specifier = ">=1.40.0" }, + { name = "playwright-stealth", specifier = ">=2.0.0" }, { name = "psycopg2-binary", specifier = ">=2.9.0" }, { name = "pydantic", specifier = ">=2.0.0" }, { name = "pypdf", specifier = ">=4.0.0" }, From 6024ae42416d8a0d3f01dd85a51a6aeb6a7f6fbb Mon Sep 17 00:00:00 2001 From: Faryal Rzwan Date: Mon, 6 Apr 2026 18:44:51 +0500 Subject: [PATCH 13/28] docs(tools): add README for 9 tools (batch 1) (#6881) * docs(tools): add README for huggingface, jira, pinecone, langfuse, linear, mongodb, redis, vercel, confluence * docs(tools): fix review comments in confluence, mongodb and vercel READMEs * docs(mongodb): add MONGODB_DATA_SOURCE to setup section The code uses os.getenv("MONGODB_DATA_SOURCE") in every API request body as the dataSource field. Without it, requests send an empty dataSource and fail. Add it back to the setup section. --------- Co-authored-by: hundao --- .../tools/confluence_tool/README.md | 198 ++++++++++++++++++ .../tools/huggingface_tool/README.md | 101 +++++++++ .../src/aden_tools/tools/jira_tool/README.md | 127 +++++++++++ .../aden_tools/tools/langfuse_tool/README.md | 102 +++++++++ .../aden_tools/tools/linear_tool/README.md | 151 +++++++++++++ .../aden_tools/tools/mongodb_tool/README.md | 100 +++++++++ .../aden_tools/tools/pinecone_tool/README.md | 127 +++++++++++ .../src/aden_tools/tools/redis_tool/README.md | 96 +++++++++ .../aden_tools/tools/vercel_tool/README.md | 106 ++++++++++ 9 files changed, 1108 insertions(+) create mode 100644 tools/src/aden_tools/tools/confluence_tool/README.md create mode 100644 tools/src/aden_tools/tools/huggingface_tool/README.md create mode 100644 tools/src/aden_tools/tools/jira_tool/README.md create mode 100644 tools/src/aden_tools/tools/langfuse_tool/README.md create mode 100644 tools/src/aden_tools/tools/linear_tool/README.md create mode 100644 tools/src/aden_tools/tools/mongodb_tool/README.md create mode 100644 tools/src/aden_tools/tools/pinecone_tool/README.md create mode 100644 tools/src/aden_tools/tools/redis_tool/README.md create mode 100644 tools/src/aden_tools/tools/vercel_tool/README.md diff --git a/tools/src/aden_tools/tools/confluence_tool/README.md b/tools/src/aden_tools/tools/confluence_tool/README.md new file mode 100644 index 00000000..49a50106 --- /dev/null +++ b/tools/src/aden_tools/tools/confluence_tool/README.md @@ -0,0 +1,198 @@ +# Confluence Tool + +Wiki and knowledge management via Confluence Cloud REST API v2. + +## Available Functions + +### Spaces & Pages + +- `confluence_list_spaces(limit=25)` + - `limit` (int, optional): Max results (1-250, default 25) + - Returns: `{"spaces": [...], "count": N}` with id, key, name, type, status + +- `confluence_list_pages(space_id="", title="", limit=25)` + - `space_id` (str, optional): Filter by space ID + - `title` (str, optional): Filter by exact page title + - `limit` (int, optional): Max results (1-250) + - Returns: `{"pages": [...], "count": N}` with id, title, space_id, version + +- `confluence_get_page(page_id, body_format="storage")` + - `page_id` (str): Page ID (required) + - `body_format` (str, optional): `"storage"`, `"view"`, or `"atlas_doc_format"` + - Returns: Full page details with body content (truncated to 5000 chars) + +- `confluence_get_page_children(page_id, limit=25)` + - `page_id` (str): Parent page ID (required) + - `limit` (int, optional): Max results (1-250) + - Returns: `{"children": [...], "count": N}` + +### CRUD Operations + +- `confluence_create_page(space_id, title, body, parent_id="")` + - `space_id` (str): Space ID to create page in (required) + - `title` (str): Page title (required) + - `body` (str): Page content in Confluence storage format (XHTML) (required) + - `parent_id` (str, optional): Parent page ID for child pages + - Returns: `{"id": "...", "title": "...", "status": "created"}` + +- `confluence_update_page(page_id, title, body, version_number)` + - `page_id` (str): Page ID (required) + - `title` (str): Page title (required, even if unchanged) + - `body` (str): New content in storage format (required) + - `version_number` (int): Current version + 1 (required) + - Returns: `{"id": "...", "title": "...", "version": N, "status": "updated"}` + +- `confluence_delete_page(page_id)` + - `page_id` (str): Page ID to delete (required) + - Returns: `{"page_id": "...", "status": "deleted"}` + +### Search + +- `confluence_search(query, space_key="", limit=25)` + - `query` (str): Search text (used in CQL `text~` query) (required) + - `space_key` (str, optional): Filter by space key (e.g., `"DEV"`) + - `limit` (int, optional): Max results (1-50) + - Returns: `{"results": [...], "count": N}` with title, excerpt, page_id, space + +## Required Credentials + +Set these environment variables: + +```bash +# Your Confluence domain (e.g., your-company.atlassian.net) +export CONFLUENCE_DOMAIN="your-company.atlassian.net" + +# Your Atlassian account email +export CONFLUENCE_EMAIL="you@company.com" + +# Generate an API token at https://id.atlassian.com/manage/api-tokens +export CONFLUENCE_API_TOKEN="your_api_token_here" +``` + +> 💡 **Tip**: Make sure the user has permissions to access the spaces and pages you want to interact with. + +## Example Usage + +```python +# List all spaces +spaces = confluence_list_spaces(limit=10) +# Returns: {"spaces": [{"id": "123", "key": "DEV", "name": "Development", ...}], ...} + +# List pages in a specific space +pages = confluence_list_pages(space_id="123", limit=20) + +# Get a specific page's content +page = confluence_get_page(page_id="456", body_format="storage") +# Returns: {"id": "456", "title": "...", "body": "

Content...

", ...} + +# Search for pages containing "API documentation" +results = confluence_search(query="API documentation", space_key="DEV") +# Returns: {"results": [{"title": "...", "excerpt": "...", "page_id": "..."}], ...} + +# Create a new page +new_page = confluence_create_page( + space_id="123", + title="Meeting Notes 2026-03-31", + body="

Meeting Notes

Attendees: Alice, Bob

", + parent_id="456" # Optional: make it a child page +) + +# Update an existing page (must increment version number) +# First get current version +current = confluence_get_page(page_id="789") +current_version = current["version"] # e.g., 5 + +confluence_update_page( + page_id="789", + title="Updated Title", + body="

Updated Content

", + version_number=current_version + 1 # Must be current + 1 +) + +# Get child pages of a parent +children = confluence_get_page_children(page_id="456") + +# Delete a page +confluence_delete_page(page_id="789") +``` + +## Body Format (Storage Format) + +The `body` parameter uses Confluence **storage format** (XHTML-like). Examples: + +```python +# Simple paragraph +body = "

This is a paragraph.

" + +# Heading and list +body = """ +

Meeting Notes

+

Attendees

+
    +
  • Alice
    • +
  • Bob
    • +
+

Action Items

+
    +
  1. Review PR #123
    2. +
  2. Update documentation
    3. +
+""" + +# Code block +body = """ + + python + + +""" +``` + +## Version Number Requirement + +When updating a page, you **must** provide the next version number: + +```python +# 1. Get current page +page = confluence_get_page(page_id="123") +current_version = page["version"] # e.g., 5 + +# 2. Update with version + 1 +confluence_update_page( + page_id="123", + title="Same Title", + body="

Updated content

", + version_number=current_version + 1 # 6 in this example +) +``` + +## Error Handling + +All functions return error dicts on failure: + +```python +# Missing credentials +{"error": "CONFLUENCE_DOMAIN, CONFLUENCE_EMAIL, and CONFLUENCE_API_TOKEN not set", "help": "Generate an API token at https://id.atlassian.com/manage/api-tokens"} + +# Unauthorized +{"error": "Unauthorized. Check your Confluence credentials."} + +# Not found +{"error": "Not found"} + +# Wrong version number on update +{"error": "Confluence API error 409: Version mismatch"} + +# Request timeout +{"error": "Request to Confluence timed out"} +``` + +## Reference + +- [Confluence Cloud API v2 Docs](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/) +- [Get API Token](https://id.atlassian.com/manage/api-tokens) +- [CQL (Confluence Query Language)](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/) +- [Storage Format Reference](https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-content/#content-storage-format) \ No newline at end of file diff --git a/tools/src/aden_tools/tools/huggingface_tool/README.md b/tools/src/aden_tools/tools/huggingface_tool/README.md new file mode 100644 index 00000000..03de9a78 --- /dev/null +++ b/tools/src/aden_tools/tools/huggingface_tool/README.md @@ -0,0 +1,101 @@ +# HuggingFace Tool + +Discover models, datasets, and spaces on HuggingFace Hub, run model inference, generate embeddings, and manage inference endpoints. + +## Tools + +| Tool | Description | +|------|-------------| +| `huggingface_search_models` | Search for models by query, author, or popularity | +| `huggingface_get_model` | Get details about a specific model | +| `huggingface_search_datasets` | Search for datasets by query or author | +| `huggingface_get_dataset` | Get details about a specific dataset | +| `huggingface_search_spaces` | Search for Spaces by query or author | +| `huggingface_whoami` | Get info about the authenticated HuggingFace user | +| `huggingface_run_inference` | Run inference on any model via the Inference API | +| `huggingface_run_embedding` | Generate text embeddings via the Inference API | +| `huggingface_list_inference_endpoints` | List deployed Inference Endpoints | + +## Setup + +Requires a HuggingFace API token: + +```bash +export HUGGINGFACE_TOKEN="hf_your_token_here" +``` + +> Get your token at https://huggingface.co/settings/tokens + +## Usage Examples + +### Search for models +```python +huggingface_search_models(query="llama", sort="downloads", limit=10) +``` + +### Get model details +```python +huggingface_get_model(model_id="meta-llama/Llama-3-8B") +``` + +### Search for datasets +```python +huggingface_search_datasets(query="squad", author="rajpurkar", limit=5) +``` + +### Get dataset details +```python +huggingface_get_dataset(dataset_id="openai/gsm8k") +``` + +### Search for Spaces +```python +huggingface_search_spaces(query="stable diffusion", sort="likes", limit=10) +``` + +### Get authenticated user info +```python +huggingface_whoami() +``` + +### Run inference +```python +huggingface_run_inference( + model_id="facebook/bart-large-cnn", + inputs="HuggingFace is a company that builds NLP tools and hosts models...", + parameters='{"max_new_tokens": 128}' +) +``` + +### Generate embeddings +```python +huggingface_run_embedding( + model_id="sentence-transformers/all-MiniLM-L6-v2", + inputs="The quick brown fox jumps over the lazy dog" +) +``` + +### List inference endpoints +```python +huggingface_list_inference_endpoints(namespace="my-org") +``` + +## Sort Options + +| Value | Description | +|-------|-------------| +| `downloads` | Sort by download count (default for models/datasets) | +| `likes` | Sort by likes (default for spaces) | +| `lastModified` | Sort by last modified date | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "HUGGINGFACE_TOKEN not set", "help": "Get a token at https://huggingface.co/settings/tokens"} +{"error": "Unauthorized. Check your HUGGINGFACE_TOKEN."} +{"error": "Model is loading", "estimated_time": 20, "help": "The model is being loaded. Retry after the estimated time."} +{"error": "Inference request timed out. Try a smaller input or a faster model."} +{"error": "Model not found: "} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/jira_tool/README.md b/tools/src/aden_tools/tools/jira_tool/README.md new file mode 100644 index 00000000..c8d77d0d --- /dev/null +++ b/tools/src/aden_tools/tools/jira_tool/README.md @@ -0,0 +1,127 @@ +# Jira Tool + +Search, create, update, and transition Jira issues and projects via the Jira Cloud REST API v3. + +## Tools + +| Tool | Description | +|------|-------------| +| `jira_search_issues` | Search issues using JQL | +| `jira_get_issue` | Get full details of a specific issue | +| `jira_create_issue` | Create a new issue in a project | +| `jira_update_issue` | Update fields on an existing issue | +| `jira_list_transitions` | List available status transitions for an issue | +| `jira_transition_issue` | Move an issue to a new status | +| `jira_add_comment` | Add a comment to an issue | +| `jira_list_projects` | List all projects in the workspace | +| `jira_get_project` | Get details about a specific project | + +## Setup + +Requires Jira Cloud credentials: + +```bash +export JIRA_DOMAIN="your-org.atlassian.net" +export JIRA_EMAIL="you@example.com" +export JIRA_API_TOKEN="your_api_token" +``` + +> Create an API token at https://id.atlassian.com/manage/api-tokens + +## Usage Examples + +### Search issues with JQL +```python +jira_search_issues( + jql="project = PROJ AND status = 'In Progress'", + max_results=25 +) +``` + +### Get issue details +```python +jira_get_issue(issue_key="PROJ-123") +``` + +### Create a new issue +```python +jira_create_issue( + project_key="PROJ", + summary="Fix login bug", + issue_type="Bug", + description="Users cannot log in with SSO.", + priority="High", + labels="auth,sso" +) +``` + +### Update an issue +```python +jira_update_issue( + issue_key="PROJ-123", + summary="Updated title", + priority="Medium" +) +``` + +### Transition an issue to a new status +```python +# Step 1: find available transitions +jira_list_transitions(issue_key="PROJ-123") + +# Step 2: apply the transition +jira_transition_issue( + issue_key="PROJ-123", + transition_id="31", + comment="Moving to done after review." +) +``` + +### Add a comment +```python +jira_add_comment( + issue_key="PROJ-123", + body="This has been fixed in the latest deploy." +) +``` + +### List all projects +```python +jira_list_projects(max_results=50, query="backend") +``` + +### Get project details +```python +jira_get_project(project_key="PROJ") +``` + +## Issue Types + +| Type | Description | +|------|-------------| +| `Task` | Standard work item (default) | +| `Bug` | Defect or problem | +| `Story` | User story | +| `Epic` | Large body of work | + +## Priority Levels + +| Priority | Description | +|----------|-------------| +| `Highest` | Critical | +| `High` | Important | +| `Medium` | Normal | +| `Low` | Minor | +| `Lowest` | Trivial | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "JIRA_DOMAIN, JIRA_EMAIL, and JIRA_API_TOKEN not set", "help": "Create an API token at https://id.atlassian.com/manage/api-tokens"} +{"error": "Unauthorized. Check your Jira credentials."} +{"error": "Forbidden. Check your Jira permissions."} +{"error": "Rate limited. Try again shortly."} +{"error": "Not found."} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/langfuse_tool/README.md b/tools/src/aden_tools/tools/langfuse_tool/README.md new file mode 100644 index 00000000..d7fedca6 --- /dev/null +++ b/tools/src/aden_tools/tools/langfuse_tool/README.md @@ -0,0 +1,102 @@ +# Langfuse Tool + +LLM observability for tracing, scoring, and prompt management using Langfuse. + +## Tools + +| Tool | Description | +|------|-------------| +| `langfuse_list_traces` | List traces with optional filters | +| `langfuse_get_trace` | Get full details of a specific trace | +| `langfuse_list_scores` | List scores with optional filters | +| `langfuse_create_score` | Create a score for a trace or observation | +| `langfuse_list_prompts` | List prompts from prompt management | +| `langfuse_get_prompt` | Get a specific prompt by name and version | + +## Setup + +Requires Langfuse public and secret key pair: + +```bash +export LANGFUSE_PUBLIC_KEY="pk-lf-..." +export LANGFUSE_SECRET_KEY="sk-lf-..." + +# Optional: defaults to US cloud +export LANGFUSE_HOST="https://cloud.langfuse.com" +# EU cloud: +# export LANGFUSE_HOST="https://eu.cloud.langfuse.com" +# Self-hosted: +# export LANGFUSE_HOST="https://your-self-hosted-langfuse.com" +``` + +> Get your keys from https://cloud.langfuse.com/project/<id>/settings + +## Usage Examples + +### List recent traces +```python +langfuse_list_traces(user_id="user_123", limit=20) +``` + +### Get full trace details +```python +langfuse_get_trace(trace_id="trace_abc123") +``` + +### List scores for a trace +```python +langfuse_list_scores(trace_id="trace_abc123") +``` + +### Create a score +```python +langfuse_create_score( + trace_id="trace_abc123", + name="correctness", + value=0.95, + data_type="NUMERIC", + comment="Output matches expected format perfectly" +) +``` + +### List production prompts +```python +langfuse_list_prompts(label="production") +``` + +### Get a specific prompt version +```python +langfuse_get_prompt( + prompt_name="customer-support-agent", + label="production" +) +``` + +## Score Data Types + +| Type | Description | Example Value | +|------|-------------|---------------| +| `NUMERIC` | Continuous numeric score | `0.95`, `85.0` | +| `CATEGORICAL` | Category label | `"good"`, `"bad"` | +| `BOOLEAN` | Binary pass/fail | `1.0` (pass), `0.0` (fail) | + +## Score Sources + +| Source | Description | +|--------|-------------| +| `API` | Score created via API | +| `ANNOTATION` | Human annotation via Langfuse UI | +| `EVAL` | Automated evaluation job | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "Langfuse credentials not configured", "help": "Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY environment variables or configure via credential store"} +{"error": "Invalid Langfuse API keys"} +{"error": "Insufficient permissions for this Langfuse resource"} +{"error": "Langfuse resource not found"} +{"error": "Langfuse rate limit exceeded. Try again later."} +{"error": "Request timed out"} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/linear_tool/README.md b/tools/src/aden_tools/tools/linear_tool/README.md new file mode 100644 index 00000000..f004f30c --- /dev/null +++ b/tools/src/aden_tools/tools/linear_tool/README.md @@ -0,0 +1,151 @@ +# Linear Tool + +Manage issues, projects, teams, labels, cycles, and users via the Linear GraphQL API. + +## Tools + +| Tool | Description | +|------|-------------| +| `linear_issue_create` | Create a new issue | +| `linear_issue_get` | Get issue details by ID or identifier | +| `linear_issue_update` | Update an existing issue | +| `linear_issue_delete` | Delete an issue | +| `linear_issue_search` | Search issues with filters | +| `linear_issue_add_comment` | Add a comment to an issue | +| `linear_issue_comments_list` | List comments on an issue | +| `linear_issue_relation_create` | Create a relation between two issues | +| `linear_project_create` | Create a new project | +| `linear_project_get` | Get project details | +| `linear_project_update` | Update a project | +| `linear_project_list` | List projects with optional filters | +| `linear_teams_list` | List all teams in the workspace | +| `linear_team_get` | Get team details including states and members | +| `linear_workflow_states_get` | Get workflow states for a team | +| `linear_label_create` | Create a new label for a team | +| `linear_labels_list` | List all labels | +| `linear_users_list` | List all users in the workspace | +| `linear_user_get` | Get user details and assigned issues | +| `linear_viewer` | Get details about the authenticated user | +| `linear_cycles_list` | List cycles (sprints) for a team | + +## Setup + +Requires a Linear personal API key: + +```bash +export LINEAR_API_KEY="lin_api_your_api_key" +``` + +> Get your API key at https://linear.app/settings/api + +## Usage Examples + +### Create an issue +```python +linear_issue_create( + title="Fix login bug", + team_id="TEAM_UUID", + description="Users cannot log in with SSO.", + priority=1 +) +``` + +### Get an issue +```python +linear_issue_get(issue_id="ENG-123") +``` + +### Search issues +```python +linear_issue_search( + query="login bug", + team_id="TEAM_UUID", + limit=20 +) +``` + +### Update an issue +```python +linear_issue_update( + issue_id="ENG-123", + state_id="STATE_UUID", + priority=2 +) +``` + +### Add a comment +```python +linear_issue_add_comment( + issue_id="ENG-123", + body="Fixed in PR #456. Ready for review." +) +``` + +### Create a relation between issues +```python +linear_issue_relation_create( + issue_id="ENG-123", + related_issue_id="ENG-456", + relation_type="blocks" +) +``` + +### List teams +```python +linear_teams_list() +``` + +### Get workflow states for a team +```python +linear_workflow_states_get(team_id="TEAM_UUID") +``` + +### List cycles (sprints) +```python +linear_cycles_list(team_id="TEAM_UUID", limit=10) +``` + +### Get authenticated user +```python +linear_viewer() +``` + +## Priority Levels + +| Value | Description | +|-------|-------------| +| `0` | No priority | +| `1` | Urgent | +| `2` | High | +| `3` | Medium | +| `4` | Low | + +## Project States + +| State | Description | +|-------|-------------| +| `planned` | Not yet started | +| `started` | In progress | +| `paused` | On hold | +| `completed` | Done | +| `canceled` | Canceled | + +## Issue Relation Types + +| Type | Description | +|------|-------------| +| `related` | Generally related (default) | +| `blocks` | This issue blocks the other | +| `duplicate` | Duplicate of the other issue | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "Linear credentials not configured", "help": "Set LINEAR_API_KEY environment variable or configure via credential store. Get an API key at https://linear.app/settings/api"} +{"error": "Invalid or expired Linear API key"} +{"error": "Insufficient permissions. Check your Linear API key scopes."} +{"error": "Linear rate limit exceeded. Try again later."} +{"error": "Request timed out"} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/mongodb_tool/README.md b/tools/src/aden_tools/tools/mongodb_tool/README.md new file mode 100644 index 00000000..55251233 --- /dev/null +++ b/tools/src/aden_tools/tools/mongodb_tool/README.md @@ -0,0 +1,100 @@ +# MongoDB Tool + +Perform document CRUD and aggregation on MongoDB collections via the Atlas Data API (or compatible replacements like Delbridge and RESTHeart). + +## Tools + +| Tool | Description | +|------|-------------| +| `mongodb_find` | Find multiple documents matching a filter | +| `mongodb_find_one` | Find a single document matching a filter | +| `mongodb_insert_one` | Insert a single document into a collection | +| `mongodb_update_one` | Update a single document matching a filter | +| `mongodb_delete_one` | Delete a single document matching a filter | +| `mongodb_aggregate` | Run an aggregation pipeline on a collection | + +## Setup + +Requires MongoDB Atlas Data API credentials: + +```bash +export MONGODB_DATA_API_URL="https://data.mongodb-api.com/app//endpoint/data/v1" +export MONGODB_API_KEY="your_api_key" +export MONGODB_DATA_SOURCE="your_cluster_name" # e.g. "Cluster0" +``` + +> Enable the Data API and get credentials from https://cloud.mongodb.com under **App Services → Data API** + +> **Note:** The Atlas Data API reached EOL in September 2025. Compatible replacements like [Delbridge](https://github.com/stdatlas/delbridge) and [RESTHeart](https://restheart.org/) use the same interface. + +## Usage Examples + +### Find documents +```python +mongodb_find( + database="mydb", + collection="users", + filter='{"status": "active"}', + sort='{"created": -1}', + limit=10 +) +``` + +### Find a single document +```python +mongodb_find_one( + database="mydb", + collection="users", + filter='{"email": "alice@example.com"}', + projection='{"name": 1, "email": 1, "_id": 0}' +) +``` + +### Insert a document +```python +mongodb_insert_one( + database="mydb", + collection="users", + document='{"name": "Alice", "email": "alice@example.com", "status": "active"}' +) +``` + +### Update a document +```python +mongodb_update_one( + database="mydb", + collection="users", + filter='{"email": "alice@example.com"}', + update='{"$set": {"status": "inactive"}}', + upsert=False +) +``` + +### Delete a document +```python +mongodb_delete_one( + database="mydb", + collection="users", + filter='{"email": "alice@example.com"}' +) +``` + +### Run an aggregation pipeline +```python +mongodb_aggregate( + database="mydb", + collection="orders", + pipeline='[{"$match": {"status": "completed"}}, {"$group": {"_id": "$userId", "total": {"$sum": "$amount"}}}]' +) +``` + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "MONGODB_DATA_API_URL and MONGODB_API_KEY are required", "help": "Set MONGODB_DATA_API_URL and MONGODB_API_KEY environment variables"} +{"error": "HTTP 401: ..."} +{"error": "filter must be valid JSON"} +{"error": "no document found matching filter"} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/pinecone_tool/README.md b/tools/src/aden_tools/tools/pinecone_tool/README.md new file mode 100644 index 00000000..22c08c5b --- /dev/null +++ b/tools/src/aden_tools/tools/pinecone_tool/README.md @@ -0,0 +1,127 @@ +# Pinecone Tool + +Manage Pinecone vector indexes and perform vector operations for semantic search and RAG workflows. + +## Tools + +| Tool | Description | +|------|-------------| +| `pinecone_list_indexes` | List all indexes in your Pinecone project | +| `pinecone_create_index` | Create a new serverless index | +| `pinecone_describe_index` | Get configuration and status of a specific index | +| `pinecone_delete_index` | Delete an index (irreversible) | +| `pinecone_upsert_vectors` | Insert or update vectors in an index | +| `pinecone_query_vectors` | Query an index for similar vectors | +| `pinecone_fetch_vectors` | Fetch specific vectors by ID | +| `pinecone_delete_vectors` | Delete vectors by ID, filter, or entire namespace | +| `pinecone_index_stats` | Get vector counts and namespace statistics for an index | + +## Setup + +Requires a Pinecone API key: + +```bash +export PINECONE_API_KEY="your_api_key_here" +``` + +> Get your API key at https://app.pinecone.io/ under **API Keys** + +## Usage Examples + +### List all indexes +```python +pinecone_list_indexes() +``` + +### Create a new index +```python +pinecone_create_index( + name="my-index", + dimension=1536, + metric="cosine", + cloud="aws", + region="us-east-1" +) +``` + +### Describe an index +```python +pinecone_describe_index(index_name="my-index") +``` + +### Upsert vectors +```python +pinecone_upsert_vectors( + index_host="https://my-index-abc123.svc.pinecone.io", + vectors=[ + {"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"source": "doc1"}}, + {"id": "vec2", "values": [0.4, 0.5, 0.6], "metadata": {"source": "doc2"}}, + ], + namespace="my-namespace" +) +``` + +### Query for similar vectors +```python +pinecone_query_vectors( + index_host="https://my-index-abc123.svc.pinecone.io", + vector=[0.1, 0.2, 0.3], + top_k=5, + filter={"source": {"$eq": "doc1"}}, + include_metadata=True +) +``` + +### Fetch vectors by ID +```python +pinecone_fetch_vectors( + index_host="https://my-index-abc123.svc.pinecone.io", + ids=["vec1", "vec2"], + namespace="my-namespace" +) +``` + +### Delete vectors +```python +# By ID +pinecone_delete_vectors( + index_host="https://my-index-abc123.svc.pinecone.io", + ids=["vec1", "vec2"] +) + +# All vectors in a namespace +pinecone_delete_vectors( + index_host="https://my-index-abc123.svc.pinecone.io", + namespace="my-namespace", + delete_all=True +) +``` + +### Get index stats +```python +pinecone_index_stats(index_host="https://my-index-abc123.svc.pinecone.io") +``` + +### Delete an index +```python +pinecone_delete_index(index_name="my-index") +``` + +## Distance Metrics + +| Metric | Description | +|--------|-------------| +| `cosine` | Cosine similarity (default, recommended for text embeddings) | +| `euclidean` | Euclidean distance | +| `dotproduct` | Dot product (for normalized vectors) | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "PINECONE_API_KEY not set", "help": "Get an API key at https://app.pinecone.io/ under API Keys"} +{"error": "Unauthorized. Check your PINECONE_API_KEY."} +{"error": "Pinecone API error 400: ..."} +{"error": "Request to Pinecone timed out"} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/redis_tool/README.md b/tools/src/aden_tools/tools/redis_tool/README.md new file mode 100644 index 00000000..997c4666 --- /dev/null +++ b/tools/src/aden_tools/tools/redis_tool/README.md @@ -0,0 +1,96 @@ +# Redis Tool + +Key-value, hash, list, pub/sub, and utility operations for Redis via a connection URL. + +## Tools + +| Tool | Description | +|------|-------------| +| `redis_get` | Get the value of a key | +| `redis_set` | Set a key-value pair with optional TTL | +| `redis_delete` | Delete one or more keys | +| `redis_keys` | List keys matching a pattern (non-blocking SCAN) | +| `redis_hset` | Set a field in a hash | +| `redis_hgetall` | Get all fields and values from a hash | +| `redis_lpush` | Push values to the head of a list | +| `redis_lrange` | Get a range of elements from a list | +| `redis_publish` | Publish a message to a channel | +| `redis_ttl` | Get the time-to-live of a key in seconds | +| `redis_info` | Get Redis server information and statistics | + +## Setup + +Requires a Redis connection URL: + +```bash +export REDIS_URL="redis://localhost:6379" +# With password: +# export REDIS_URL="redis://:yourpassword@host:6379/0" +# With TLS: +# export REDIS_URL="rediss://:yourpassword@host:6379/0" +``` + +## Usage Examples + +### Get and set a key +```python +redis_set(key="user:123:name", value="Alice", ttl=3600) +redis_get(key="user:123:name") +``` + +### Delete keys +```python +redis_delete(keys="user:123:name, user:123:session") +``` + +### List keys matching a pattern +```python +redis_keys(pattern="user:*", count=50) +``` + +### Work with a hash +```python +redis_hset(key="user:123", field="email", value="alice@example.com") +redis_hgetall(key="user:123") +``` + +### Work with a list +```python +redis_lpush(key="task_queue", values="task1, task2, task3") +redis_lrange(key="task_queue", start=0, stop=-1) +``` + +### Publish a message +```python +redis_publish(channel="notifications", message="New order received") +``` + +### Check TTL +```python +redis_ttl(key="user:123:session") +# Returns: {"key": "user:123:session", "ttl": 3542} +# -1 = no expiry, -2 = key doesn't exist +``` + +### Get server info +```python +redis_info() +``` + +## TTL Reference + +| TTL Value | Meaning | +|-----------|---------| +| `> 0` | Seconds remaining until expiry | +| `-1` | Key exists with no expiry | +| `-2` | Key does not exist | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "REDIS_URL not set", "help": "Set REDIS_URL (e.g. redis://localhost:6379 or redis://:password@host:6379/0)"} +{"error": "Redis GET failed: Connection refused"} +{"error": "Redis SET failed: ..."} +``` \ No newline at end of file diff --git a/tools/src/aden_tools/tools/vercel_tool/README.md b/tools/src/aden_tools/tools/vercel_tool/README.md new file mode 100644 index 00000000..38b7f779 --- /dev/null +++ b/tools/src/aden_tools/tools/vercel_tool/README.md @@ -0,0 +1,106 @@ +# Vercel Tool + +Manage deployments, projects, domains, and environment variables via the Vercel REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `vercel_list_deployments` | List deployments, optionally filtered by project or state | +| `vercel_get_deployment` | Get details of a specific deployment | +| `vercel_list_projects` | List all Vercel projects | +| `vercel_get_project` | Get details of a specific project | +| `vercel_list_project_domains` | List domains configured for a project | +| `vercel_list_env_vars` | List environment variables for a project | +| `vercel_create_env_var` | Create an environment variable for a project | + +## Setup + +Requires a Vercel access token: + +```bash +export VERCEL_TOKEN="your_vercel_token" +``` + +> Get a token at https://vercel.com/account/tokens + +## Usage Examples + +### List recent deployments +```python +vercel_list_deployments(limit=10, state="READY") +``` + +### List deployments for a specific project +```python +vercel_list_deployments(project_id="my-project", limit=5) +``` + +### Get deployment details +```python +vercel_get_deployment(deployment_id="dpl_abc123") +``` + +### List all projects +```python +vercel_list_projects(limit=20) +``` + +### Get project details +```python +vercel_get_project(project_id="my-project") +``` + +### List domains for a project +```python +vercel_list_project_domains(project_id="my-project") +``` + +### List environment variables +```python +vercel_list_env_vars(project_id="my-project") +``` + +### Create an environment variable +```python +vercel_create_env_var( + project_id="my-project", + key="DATABASE_URL", + value="postgresql://user:pass@host/db", + target="production,preview", + env_type="encrypted" +) +``` + +## Deployment States + +| State | Description | +|-------|-------------| +| `BUILDING` | Currently building | +| `READY` | Live and serving traffic | +| `ERROR` | Build or runtime error | +| `QUEUED` | Waiting to build | +| `INITIALIZING` | Starting up | +| `CANCELED` | Manually canceled | + +## Environment Variable Types + +| Type | Description | +|------|-------------| +| `encrypted` | Encrypted at rest, not visible after creation (default) | +| `secret` | Reference to a shared secret, value not stored directly | +| `plain` | Plaintext, visible in dashboard | +| `sensitive` | Encrypted, never shown after creation | +| `system` | System-provided variable | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "VERCEL_TOKEN not set", "help": "Get a token at https://vercel.com/account/tokens"} +{"error": "Unauthorized. Check your VERCEL_TOKEN."} +{"error": "Forbidden: ..."} +{"error": "Vercel API error 404: ..."} +{"error": "Request to Vercel timed out"} +``` \ No newline at end of file From 4b795584f63b9312f6e9e58df7f2db5ad7ff57e4 Mon Sep 17 00:00:00 2001 From: Leayx Date: Mon, 6 Apr 2026 10:56:59 -0300 Subject: [PATCH 14/28] micro-fix(quickstart): correct npm invocation in powershell script (#6816) - powerShell supports direct command invocation without requiring the call operator "&" - the script used the call operator "&" to invoke `npm install` and `npm run build` - which caused incorrect command parsing in PowerShell when combined with output redirection "2>&1" - This resulted in unexpected errors such as "Unknown command: pm", even though the commands worked correctly when executed manually - removed the unnecessary use of the call operator "&" and invoked npm commands directly - npm commands now execute correctly within the script, aligning with standard PowerShell behavior and eliminating the parsing issue --- quickstart.ps1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/quickstart.ps1 b/quickstart.ps1 index 31d05a57..99ef8eff 100644 --- a/quickstart.ps1 +++ b/quickstart.ps1 @@ -589,14 +589,14 @@ if ($NodeAvailable) { Write-Host " Installing npm packages... " -NoNewline Push-Location $frontendDir try { - $installOutput = & npm install --no-fund --no-audit 2>&1 + $installOutput = npm install --no-fund --no-audit 2>&1 if ($LASTEXITCODE -eq 0) { Write-Ok "ok" # Clean stale tsbuildinfo cache — tsc -b incremental builds fail # silently when these are out of sync with source files Get-ChildItem -Path $frontendDir -Filter "tsconfig*.tsbuildinfo" -ErrorAction SilentlyContinue | Remove-Item -Force Write-Host " Building frontend... " -NoNewline - $buildOutput = & npm run build 2>&1 + $buildOutput = npm run build 2>&1 if ($LASTEXITCODE -eq 0) { Write-Ok "ok" Write-Ok "Frontend built -> core/frontend/dist/" From 8f2d87cc5dd2fc072fe4ea9b14d1cb1abe29dc49 Mon Sep 17 00:00:00 2001 From: Sujan Kumar MV <82932721+KRYSTALM7@users.noreply.github.com> Date: Mon, 6 Apr 2026 19:40:22 +0530 Subject: [PATCH 15/28] docs(tools): add README for 10 tools (batch 3) (#6913) * docs(tools): add README for 10 tools (batch 3) Adds README.md for: supabase_tool, zoom_tool, twitter_tool, twilio_tool, shopify_tool, snowflake_tool, zendesk_tool, yahoo_finance_tool, youtube_transcript_tool, docker_hub_tool Partial fix for #6486 * docs(shopify): fix fulfillment_status value and body_html param name - fulfillment_status example: "unfulfilled" is not a valid Shopify API value, changed to "unshipped" - tool table: "description" is not the actual param name, it's body_html --------- Co-authored-by: hundao --- .../tools/docker_hub_tool/README.md | 124 ++++++++++++++++ .../aden_tools/tools/shopify_tool/README.md | 135 ++++++++++++++++++ .../aden_tools/tools/snowflake_tool/README.md | 111 ++++++++++++++ .../aden_tools/tools/supabase_tool/README.md | 131 +++++++++++++++++ .../aden_tools/tools/twilio_tool/README.md | 111 ++++++++++++++ .../aden_tools/tools/twitter_tool/README.md | 108 ++++++++++++++ .../tools/yahoo_finance_tool/README.md | 118 +++++++++++++++ .../tools/youtube_transcript_tool/README.md | 110 ++++++++++++++ .../aden_tools/tools/zendesk_tool/README.md | 134 +++++++++++++++++ .../src/aden_tools/tools/zoom_tool/README.md | 130 +++++++++++++++++ 10 files changed, 1212 insertions(+) create mode 100644 tools/src/aden_tools/tools/docker_hub_tool/README.md create mode 100644 tools/src/aden_tools/tools/shopify_tool/README.md create mode 100644 tools/src/aden_tools/tools/snowflake_tool/README.md create mode 100644 tools/src/aden_tools/tools/supabase_tool/README.md create mode 100644 tools/src/aden_tools/tools/twilio_tool/README.md create mode 100644 tools/src/aden_tools/tools/twitter_tool/README.md create mode 100644 tools/src/aden_tools/tools/yahoo_finance_tool/README.md create mode 100644 tools/src/aden_tools/tools/youtube_transcript_tool/README.md create mode 100644 tools/src/aden_tools/tools/zendesk_tool/README.md create mode 100644 tools/src/aden_tools/tools/zoom_tool/README.md diff --git a/tools/src/aden_tools/tools/docker_hub_tool/README.md b/tools/src/aden_tools/tools/docker_hub_tool/README.md new file mode 100644 index 00000000..012c8a13 --- /dev/null +++ b/tools/src/aden_tools/tools/docker_hub_tool/README.md @@ -0,0 +1,124 @@ +# Docker Hub Tool + +Search repositories, list tags, inspect images, manage webhooks, and delete tags via the Docker Hub API v2. + +## Tools + +| Tool | Description | +|------|-------------| +| `docker_hub_search` | Search Docker Hub for public repositories | +| `docker_hub_list_repos` | List repositories for a user or organization | +| `docker_hub_get_repo` | Get detailed info about a specific repository | +| `docker_hub_list_tags` | List tags for a repository | +| `docker_hub_get_tag_detail` | Get details for a specific image tag | +| `docker_hub_delete_tag` | Delete a tag from a repository | +| `docker_hub_list_webhooks` | List webhooks configured for a repository | + +## Setup + +Requires a Docker Hub Personal Access Token (PAT): + +1. Go to [hub.docker.com](https://hub.docker.com) → **Account Settings → Security → New Access Token** +2. Give it a name and select the required permissions (Read, Write, Delete as needed) +3. Copy the token immediately — it is only shown once + +```bash +DOCKER_HUB_TOKEN=your-personal-access-token +DOCKER_HUB_USERNAME=your-docker-hub-username +``` + +> `DOCKER_HUB_USERNAME` is used as the default namespace when listing repos. If it is unset and no `namespace` is passed to `docker_hub_list_repos`, the tool will return an error: `"namespace is required (or set DOCKER_HUB_USERNAME)"`. + +## Usage Examples + +### Search for public repositories + +```python +docker_hub_search(query="nginx", max_results=10) +``` + +### List your own repositories + +```python +docker_hub_list_repos(namespace="myusername", max_results=25) +``` + +### Get repository details + +```python +docker_hub_get_repo(repository="library/nginx") +``` + +### List tags for a repository + +```python +docker_hub_list_tags(repository="library/nginx", max_results=20) +``` + +### Get details for a specific tag + +```python +docker_hub_get_tag_detail( + repository="library/nginx", + tag="latest", +) +``` + +### Delete a tag + +```python +docker_hub_delete_tag( + repository="myusername/myapp", + tag="old-release-1.0", +) +``` + +### List webhooks for a repository + +```python +docker_hub_list_webhooks(repository="myusername/myapp") +``` + +## Response Format + +`docker_hub_list_tags` returns tags sorted by `last_updated` descending: + +```python +{ + "repository": "library/nginx", + "tags": [ + { + "name": "latest", + "full_size": 68000000, + "last_updated": "2025-05-01T12:00:00Z", + "digest": "sha256:abc123...", + }, + ... + ] +} +``` + +`docker_hub_get_tag_detail` includes per-architecture image info: + +```python +{ + "repository": "library/nginx", + "tag": "latest", + "full_size": 68000000, + "images": [ + {"architecture": "amd64", "os": "linux", "size": 34000000, "digest": "sha256:..."}, + {"architecture": "arm64", "os": "linux", "size": 32000000, "digest": "sha256:..."}, + ] +} +``` + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "DOCKER_HUB_TOKEN not set", "help": "Create a PAT at https://hub.docker.com/settings/security"} +{"error": "Unauthorized. Check your DOCKER_HUB_TOKEN."} +{"error": "Not found"} +{"error": "Request to Docker Hub timed out"} +``` diff --git a/tools/src/aden_tools/tools/shopify_tool/README.md b/tools/src/aden_tools/tools/shopify_tool/README.md new file mode 100644 index 00000000..2ac0c93f --- /dev/null +++ b/tools/src/aden_tools/tools/shopify_tool/README.md @@ -0,0 +1,135 @@ +# Shopify Tool + +Order, product, and customer management via the Shopify Admin REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `shopify_list_orders` | List orders with optional status and fulfillment filters | +| `shopify_get_order` | Get full details of a specific order by ID | +| `shopify_list_products` | List products with optional status, type, and vendor filters | +| `shopify_get_product` | Get full product details including variants and images | +| `shopify_update_product` | Update title, body_html, status, tags, or vendor of a product | +| `shopify_list_customers` | List customers in the store | +| `shopify_get_customer` | Get full customer details including addresses and order stats | +| `shopify_search_customers` | Search customers by email, name, or other fields | +| `shopify_create_draft_order` | Create a draft order with line items | + +## Setup + +Requires a Shopify Custom App access token and your store name: + +1. Go to your Shopify admin → **Settings → Apps and sales channels → Develop apps** +2. Create a custom app and install it with the required API scopes +3. Copy the **Admin API access token** from the app credentials + +```bash +SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx +SHOPIFY_STORE_NAME=your-store-name +``` + +> `SHOPIFY_STORE_NAME` is the subdomain of your store. For `https://my-shop.myshopify.com`, use `my-shop`. + +Required API scopes: +- `read_orders`, `write_orders` — order management +- `read_products`, `write_products` — product management +- `read_customers`, `write_customers` — customer management +- `read_draft_orders`, `write_draft_orders` — draft order creation + +## Usage Examples + +### List open orders + +```python +shopify_list_orders(status="open", limit=50) +``` + +### List paid but unfulfilled orders + +```python +shopify_list_orders( + financial_status="paid", + fulfillment_status="unshipped", + limit=25, +) +``` + +### Get a specific order + +```python +shopify_get_order(order_id="5678901234") +``` + +### List active products + +```python +shopify_list_products(status="active", limit=50) +``` + +### Get a specific product + +```python +shopify_get_product(product_id="1234567890") +``` + +### Update a product + +```python +shopify_update_product( + product_id="1234567890", + title="Updated Product Name", + status="active", + tags="sale,featured", +) +``` + +### List customers + +```python +shopify_list_customers(limit=100) +``` + +### Search customers by email + +```python +shopify_search_customers(query="email:alice@example.com") +``` + +### Search customers by name + +```python +shopify_search_customers(query="first_name:Alice") +``` + +### Create a draft order + +```python +shopify_create_draft_order( + line_items_json='[{"variant_id": 12345678, "quantity": 2}]', + customer_id="987654321", + note="VIP order", + tags="manual,vip", +) +``` + +## Order Status Values + +| Filter | Values | +|--------|--------| +| `status` | `open`, `closed`, `cancelled`, `any` | +| `financial_status` | `paid`, `pending`, `refunded`, `voided` | +| `fulfillment_status` | `fulfilled`, `partial`, `on_hold`, `null` (unfulfilled) | + +> **Note:** `fulfillment_status=null` filters for unfulfilled orders. Shopify silently ignores unrecognized filter values rather than returning an error. + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "Shopify credentials not configured", "help": "Set SHOPIFY_ACCESS_TOKEN and SHOPIFY_STORE_NAME environment variables or configure via credential store"} +{"error": "Invalid Shopify access token"} +{"error": "Insufficient API scopes for this Shopify resource"} +{"error": "Shopify rate limit exceeded. Try again later."} +``` diff --git a/tools/src/aden_tools/tools/snowflake_tool/README.md b/tools/src/aden_tools/tools/snowflake_tool/README.md new file mode 100644 index 00000000..fdb73429 --- /dev/null +++ b/tools/src/aden_tools/tools/snowflake_tool/README.md @@ -0,0 +1,111 @@ +# Snowflake Tool + +SQL statement execution and async query management via the Snowflake REST API v2. + +## Tools + +| Tool | Description | +|------|-------------| +| `snowflake_execute_sql` | Execute a SQL statement and return results | +| `snowflake_get_statement_status` | Poll the status and results of an async query | +| `snowflake_cancel_statement` | Cancel a running SQL statement | + +## Setup + +Requires a Snowflake account identifier and an OAuth or JWT access token: + +1. Note your **Account Identifier** (e.g. `orgname-accountname` or `xy12345.us-east-1`) +2. Generate an access token via OAuth, key-pair authentication, or Snowflake programmatic access + +```bash +SNOWFLAKE_ACCOUNT=orgname-accountname +SNOWFLAKE_TOKEN=your-oauth-or-jwt-token +``` + +Optional — set default context to avoid repeating them per query: + +```bash +SNOWFLAKE_WAREHOUSE=COMPUTE_WH +SNOWFLAKE_DATABASE=MY_DATABASE +SNOWFLAKE_SCHEMA=PUBLIC +SNOWFLAKE_TOKEN_TYPE=OAUTH +``` + +> `SNOWFLAKE_TOKEN_TYPE` defaults to `OAUTH`. Set to `KEYPAIR_JWT` if using key-pair auth. + +## Usage Examples + +### Run a simple query + +```python +snowflake_execute_sql(statement="SELECT CURRENT_USER(), CURRENT_DATABASE()") +``` + +### Query a specific database and schema + +```python +snowflake_execute_sql( + statement="SELECT * FROM orders WHERE status = 'pending' LIMIT 100", + database="SALES_DB", + schema="PUBLIC", + warehouse="COMPUTE_WH", +) +``` + +### Run a long query asynchronously + +```python +# Returns immediately with status="running" +result = snowflake_execute_sql( + statement="SELECT COUNT(*) FROM very_large_table", + timeout=120, +) + +# Poll until complete +snowflake_get_statement_status( + statement_handle=result["statement_handle"] +) +``` + +### Cancel a running query + +```python +snowflake_cancel_statement( + statement_handle="01abc123-0000-0001-0000-000100020003" +) +``` + +## Response Format + +A completed query returns: + +```python +{ + "statement_handle": "01abc...", + "status": "complete", + "num_rows": 42, + "columns": ["ID", "NAME", "CREATED_AT"], + "rows": [["1", "Alice", "2024-01-01"], ...], + "truncated": False, # True if > 100 rows returned +} +``` + +An async query in progress returns: + +```python +{ + "statement_handle": "01abc...", + "status": "running", + "message": "Asynchronous execution in progress", +} +``` + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "SNOWFLAKE_ACCOUNT and SNOWFLAKE_TOKEN are required", "help": "Set SNOWFLAKE_ACCOUNT and SNOWFLAKE_TOKEN environment variables"} +{"error": "HTTP 422: Query failed"} +{"error": "statement is required"} +``` diff --git a/tools/src/aden_tools/tools/supabase_tool/README.md b/tools/src/aden_tools/tools/supabase_tool/README.md new file mode 100644 index 00000000..8d1a94f4 --- /dev/null +++ b/tools/src/aden_tools/tools/supabase_tool/README.md @@ -0,0 +1,131 @@ +# Supabase Tool + +Database queries, auth, and edge function invocation via the Supabase REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `supabase_select` | Query rows from a table using PostgREST filters | +| `supabase_insert` | Insert one or more rows into a table | +| `supabase_update` | Update rows matching PostgREST filters | +| `supabase_delete` | Delete rows matching PostgREST filters | +| `supabase_auth_signup` | Register a new user via Supabase Auth (GoTrue) | +| `supabase_auth_signin` | Sign in a user and retrieve an access token | +| `supabase_edge_invoke` | Invoke a Supabase Edge Function | + +## Setup + +Requires a Supabase project URL and anon/service key: + +1. Go to [supabase.com/dashboard](https://supabase.com/dashboard) → your project → **Project Settings → API** +2. Copy your **Project URL** and **anon public** key (or service role key for elevated access) + +Set the following environment variables: + +```bash +SUPABASE_URL=https://your-project-id.supabase.co +SUPABASE_ANON_KEY=your-anon-or-service-key +``` + +## Usage Examples + +### Query rows with filters + +```python +supabase_select( + table="users", + columns="id,name,email", + filters="status=eq.active&role=eq.admin", + order="created_at.desc", + limit=50, +) +``` + +### Insert a single row + +```python +supabase_insert( + table="orders", + rows='{"customer_id": 42, "total": 99.99, "status": "pending"}', +) +``` + +### Insert multiple rows + +```python +supabase_insert( + table="products", + rows='[{"name": "Widget A", "price": 10}, {"name": "Widget B", "price": 20}]', +) +``` + +### Update rows matching a filter + +```python +supabase_update( + table="orders", + filters="id=eq.123", + data='{"status": "shipped"}', +) +``` + +### Delete rows matching a filter + +```python +supabase_delete( + table="sessions", + filters="expires_at=lt.2024-01-01", +) +``` + +### Sign up a new user + +```python +supabase_auth_signup( + email="alice@example.com", + password="securepassword", +) +``` + +### Sign in and get an access token + +```python +supabase_auth_signin( + email="alice@example.com", + password="securepassword", +) +``` + +### Invoke an Edge Function + +```python +supabase_edge_invoke( + function_name="send-welcome-email", + body='{"user_id": "abc123"}', + method="POST", +) +``` + +## PostgREST Filter Syntax + +| Operator | Meaning | Example | +|----------|---------|---------| +| `eq` | equals | `status=eq.active` | +| `neq` | not equals | `role=neq.admin` | +| `gt` | greater than | `age=gt.18` | +| `lt` | less than | `price=lt.100` | +| `like` | pattern match | `name=like.*Alice*` | +| `is` | is null/true/false | `deleted_at=is.null` | + +Combine multiple filters with `&`: `"status=eq.active&role=eq.admin"` + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "SUPABASE_ANON_KEY or SUPABASE_URL not set", "help": "Get your keys at https://supabase.com/dashboard → Project Settings → API"} +{"error": "Supabase error 403: ..."} +{"error": "Request to Supabase timed out"} +``` diff --git a/tools/src/aden_tools/tools/twilio_tool/README.md b/tools/src/aden_tools/tools/twilio_tool/README.md new file mode 100644 index 00000000..4825f9b5 --- /dev/null +++ b/tools/src/aden_tools/tools/twilio_tool/README.md @@ -0,0 +1,111 @@ +# Twilio Tool + +SMS and WhatsApp messaging, call logs, and phone number management via the Twilio REST API. + +## Tools + +| Tool | Description | +|------|-------------| +| `twilio_send_sms` | Send an SMS message | +| `twilio_send_whatsapp` | Send a WhatsApp message | +| `twilio_list_messages` | List recent messages with optional filters | +| `twilio_get_message` | Get details of a specific message by SID | +| `twilio_delete_message` | Delete a message from your Twilio account | +| `twilio_list_phone_numbers` | List phone numbers owned by the account | +| `twilio_list_calls` | List recent calls with optional filters | + +## Setup + +Requires a Twilio Account SID and Auth Token: + +1. Go to [console.twilio.com](https://console.twilio.com) +2. Copy your **Account SID** and **Auth Token** from the dashboard + +```bash +TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +TWILIO_AUTH_TOKEN=your-auth-token +``` + +> Phone numbers must be in **E.164 format**: `+14155552671` + +## Usage Examples + +### Send an SMS + +```python +twilio_send_sms( + to="+14155552671", + from_number="+18005550100", + body="Your verification code is 123456", +) +``` + +### Send a WhatsApp message + +```python +twilio_send_whatsapp( + to="+14155552671", + from_number="+14155550000", + body="Hello from Twilio WhatsApp!", +) +``` + +### List recent messages + +```python +twilio_list_messages(page_size=20) +``` + +### Filter messages by recipient + +```python +twilio_list_messages(to="+14155552671", page_size=10) +``` + +### Get a specific message + +```python +twilio_get_message(message_sid="SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") +``` + +### Delete a message + +```python +twilio_delete_message(message_sid="SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") +``` + +### List phone numbers on the account + +```python +twilio_list_phone_numbers() +``` + +### List recent calls + +```python +twilio_list_calls(status="completed", page_size=20) +``` + +## Call Status Values + +| Status | Meaning | +|--------|---------| +| `queued` | Call is queued | +| `ringing` | Recipient's phone is ringing | +| `in-progress` | Call is active | +| `completed` | Call ended successfully | +| `busy` | Recipient was busy | +| `failed` | Call failed | +| `no-answer` | No answer | +| `canceled` | Call was canceled | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN not set", "help": "Get credentials from https://console.twilio.com/"} +{"error": "Unauthorized. Check your Twilio credentials."} +{"error": "Rate limited. Try again shortly."} +{"error": "Message not found."} +``` diff --git a/tools/src/aden_tools/tools/twitter_tool/README.md b/tools/src/aden_tools/tools/twitter_tool/README.md new file mode 100644 index 00000000..f6b37232 --- /dev/null +++ b/tools/src/aden_tools/tools/twitter_tool/README.md @@ -0,0 +1,108 @@ +# Twitter Tool + +Tweet search, user lookup, and timeline access via the X (Twitter) API v2. + +## Tools + +| Tool | Description | +|------|-------------| +| `twitter_search_tweets` | Search recent tweets from the last 7 days | +| `twitter_get_user` | Get a user profile by username | +| `twitter_get_user_tweets` | Get recent tweets from a user's timeline | +| `twitter_get_tweet` | Get details of a specific tweet by ID | +| `twitter_get_user_followers` | Get followers of a user | +| `twitter_get_tweet_replies` | Get replies to a specific tweet | +| `twitter_get_list_tweets` | Get recent tweets from a Twitter/X list | + +## Setup + +Requires an X (Twitter) Bearer Token for read-only API v2 access: + +1. Go to [developer.x.com](https://developer.x.com) → **Projects & Apps → Your App → Keys and Tokens** +2. Copy the **Bearer Token** under **Authentication Tokens** + +```bash +X_BEARER_TOKEN=your-bearer-token +``` + +> The Bearer Token provides read-only access. Write operations (post, like, retweet) are not supported by this tool. + +## Usage Examples + +### Search recent tweets + +```python +twitter_search_tweets( + query="python machine learning -is:retweet lang:en", + max_results=25, + sort_order="recency", +) +``` + +### Search tweets from a specific user + +```python +twitter_search_tweets(query="from:openai has:media", max_results=10) +``` + +### Get a user profile + +```python +twitter_get_user(username="elonmusk") +``` + +### Get a user's recent tweets + +```python +twitter_get_user_tweets( + user_id="44196397", + max_results=20, + exclude_replies=True, + exclude_retweets=True, +) +``` + +### Get a specific tweet + +```python +twitter_get_tweet(tweet_id="1234567890123456789") +``` + +### Get followers of a user + +```python +twitter_get_user_followers(user_id="44196397", max_results=50) +``` + +### Get replies to a tweet + +```python +twitter_get_tweet_replies(tweet_id="1234567890123456789", max_results=20) +``` + +### Get tweets from a list + +```python +twitter_get_list_tweets(list_id="84839422", max_results=10) +``` + +## Search Query Operators + +| Operator | Example | Meaning | +|----------|---------|---------| +| `from:` | `from:nasa` | Tweets by a specific user | +| `to:` | `to:support` | Replies to a specific user | +| `-is:retweet` | `-is:retweet` | Exclude retweets | +| `has:media` | `has:media` | Tweets with media | +| `lang:` | `lang:en` | Filter by language | +| `#` | `#python` | Hashtag search | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "X_BEARER_TOKEN is required", "help": "Set X_BEARER_TOKEN environment variable"} +{"error": "HTTP 429: ..."} +{"error": "tweet_id is required"} +``` diff --git a/tools/src/aden_tools/tools/yahoo_finance_tool/README.md b/tools/src/aden_tools/tools/yahoo_finance_tool/README.md new file mode 100644 index 00000000..ab250888 --- /dev/null +++ b/tools/src/aden_tools/tools/yahoo_finance_tool/README.md @@ -0,0 +1,118 @@ +# Yahoo Finance Tool + +Latest available stock quotes, historical prices, financial statements, and company info via the `yfinance` library. + +> **Note:** Data is sourced from Yahoo Finance and may be delayed by 15 minutes or more depending on the exchange. + +## Tools + +| Tool | Description | +|------|-------------| +| `yahoo_finance_quote` | Get current stock quote and key statistics | +| `yahoo_finance_history` | Get historical OHLCV price data | +| `yahoo_finance_financials` | Get income statement, balance sheet, or cash flow | +| `yahoo_finance_info` | Get detailed company information | +| `yahoo_finance_search` | Search for ticker symbols by company name or keyword | + +## Setup + +No API key or credentials required. The tool uses the `yfinance` Python library which accesses Yahoo Finance data directly. + +> Data is provided by Yahoo Finance and is subject to their terms of use. + +## Usage Examples + +### Get a stock quote + +```python +yahoo_finance_quote(symbol="AAPL") +``` + +### Get historical daily prices for the last month + +```python +yahoo_finance_history( + symbol="MSFT", + period="1mo", + interval="1d", +) +``` + +### Get intraday prices (last 5 days, hourly) + +```python +yahoo_finance_history( + symbol="GOOGL", + period="5d", + interval="1h", +) +``` + +### Get the income statement + +```python +yahoo_finance_financials(symbol="AAPL", statement="income") +``` + +### Get the balance sheet + +```python +yahoo_finance_financials(symbol="TSLA", statement="balance") +``` + +### Get the cash flow statement + +```python +yahoo_finance_financials(symbol="NVDA", statement="cashflow") +``` + +### Get company info + +```python +yahoo_finance_info(symbol="AMZN") +``` + +### Search for a ticker symbol + +```python +yahoo_finance_search(query="Tesla") +``` + +## Period Values + +| Period | Meaning | +|--------|---------| +| `1d` | 1 day | +| `5d` | 5 days | +| `1mo` | 1 month | +| `3mo` | 3 months | +| `6mo` | 6 months | +| `1y` | 1 year | +| `2y` | 2 years | +| `5y` | 5 years | +| `ytd` | Year to date | +| `max` | All available history | + +## Interval Values + +| Interval | Meaning | +|----------|---------| +| `1m` | 1 minute (last 7 days only) | +| `5m` | 5 minutes | +| `1h` | 1 hour | +| `1d` | Daily | +| `1wk` | Weekly | +| `1mo` | Monthly | + +> **Interval constraints:** Intraday intervals have range limits enforced by yfinance. `1m` is limited to the last 7 days. `5m`, `15m`, `30m`, and `1h` are limited to the last 60 days. Invalid combinations return an empty result silently rather than raising an error. + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "symbol is required"} +{"error": "No data found for symbol 'XYZ'"} +{"error": "Invalid statement type: xyz. Use: income, balance, cashflow"} +{"error": "Failed to fetch quote for AAPL: ..."} +``` diff --git a/tools/src/aden_tools/tools/youtube_transcript_tool/README.md b/tools/src/aden_tools/tools/youtube_transcript_tool/README.md new file mode 100644 index 00000000..7c7cdf5d --- /dev/null +++ b/tools/src/aden_tools/tools/youtube_transcript_tool/README.md @@ -0,0 +1,110 @@ +# YouTube Transcript Tool + +Retrieve video transcripts and list available caption tracks via the `youtube-transcript-api` library. + +## Tools + +| Tool | Description | +|------|-------------| +| `youtube_get_transcript` | Get the transcript/captions for a YouTube video | +| `youtube_list_transcripts` | List all available transcript languages for a video | + +## Setup + +No API key required. The tool uses the `youtube-transcript-api` Python library and works with any public video that has captions enabled — no authentication needed. + +Ensure the package is installed: + +```bash +pip install youtube-transcript-api +``` + +> Only videos with captions enabled (auto-generated or manual) can be transcribed. Private or age-restricted videos may not be accessible. + +## Usage Examples + +### Get the English transcript of a video + +```python +youtube_get_transcript( + video_id="dQw4w9WgXcQ", + language="en", +) +``` + +### Get transcript in another language + +```python +youtube_get_transcript( + video_id="dQw4w9WgXcQ", + language="de", +) +``` + +### Get transcript preserving HTML formatting tags + +```python +youtube_get_transcript( + video_id="dQw4w9WgXcQ", + language="en", + preserve_formatting=True, +) +``` + +### List all available transcript languages + +```python +youtube_list_transcripts(video_id="dQw4w9WgXcQ") +``` + +## Response Format + +`youtube_get_transcript` returns: + +```python +{ + "video_id": "dQw4w9WgXcQ", + "language": "English", + "language_code": "en", + "is_generated": True, + "snippet_count": 312, + "snippets": [ + {"text": "Never gonna give you up", "start": 18.44, "duration": 1.72}, + ... + ] +} +``` + +`youtube_list_transcripts` returns: + +```python +{ + "video_id": "dQw4w9WgXcQ", + "count": 3, + "transcripts": [ + {"language": "English", "language_code": "en", "is_generated": True, "is_translatable": True}, + {"language": "German", "language_code": "de", "is_generated": False, "is_translatable": True}, + ] +} +``` + +## Finding the Video ID + +The video ID is the `v=` parameter in a YouTube URL: + +``` +https://www.youtube.com/watch?v=dQw4w9WgXcQ + ^^^^^^^^^^^ + This is the video ID +``` + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "video_id is required"} +{"error": "TranscriptsDisabled: ..."} +{"error": "NoTranscriptFound: ..."} +{"error": "youtube-transcript-api package not installed. Run: pip install youtube-transcript-api"} +``` diff --git a/tools/src/aden_tools/tools/zendesk_tool/README.md b/tools/src/aden_tools/tools/zendesk_tool/README.md new file mode 100644 index 00000000..8773dd5d --- /dev/null +++ b/tools/src/aden_tools/tools/zendesk_tool/README.md @@ -0,0 +1,134 @@ +# Zendesk Tool + +Ticket management, comments, user listing, and search via the Zendesk Support API. + +## Tools + +| Tool | Description | +|------|-------------| +| `zendesk_list_tickets` | List tickets in the account | +| `zendesk_get_ticket` | Get full details of a specific ticket | +| `zendesk_create_ticket` | Create a new support ticket | +| `zendesk_update_ticket` | Update ticket status, priority, or tags | +| `zendesk_search_tickets` | Search tickets using Zendesk query syntax | +| `zendesk_get_ticket_comments` | List all comments on a ticket | +| `zendesk_add_ticket_comment` | Add a public reply or internal note to a ticket | +| `zendesk_list_users` | List users filtered by role | + +## Setup + +Requires a Zendesk subdomain, agent email, and API token: + +1. Log in to your Zendesk admin panel +2. Go to **Admin → Apps and integrations → APIs → Zendesk API** +3. Enable **Token Access** and create a new API token + +```bash +ZENDESK_SUBDOMAIN=your-subdomain +ZENDESK_EMAIL=agent@yourcompany.com +ZENDESK_API_TOKEN=your-api-token +``` + +> `ZENDESK_SUBDOMAIN` is the part before `.zendesk.com`. For `https://acme.zendesk.com`, use `acme`. + +## Usage Examples + +### List open tickets + +```python +zendesk_list_tickets(page_size=25) +``` + +### Get a specific ticket + +```python +zendesk_get_ticket(ticket_id=12345) +``` + +### Create a new ticket + +```python +zendesk_create_ticket( + subject="Login button not working", + body="Users are reporting that the login button on mobile is unresponsive.", + priority="high", + ticket_type="incident", + tags="mobile,login,bug", +) +``` + +### Update a ticket status + +```python +zendesk_update_ticket( + ticket_id=12345, + status="pending", + priority="urgent", +) +``` + +### Add a public reply to a ticket + +```python +zendesk_add_ticket_comment( + ticket_id=12345, + body="We have identified the issue and a fix is being deployed.", + public=True, +) +``` + +### Add an internal note + +```python +zendesk_add_ticket_comment( + ticket_id=12345, + body="Escalated to the backend team via Slack #incidents.", + public=False, +) +``` + +### Search tickets + +```python +zendesk_search_tickets( + query="status:open priority:urgent", + sort_by="updated_at", + sort_order="desc", +) +``` + +### Search by assignee and tag + +```python +zendesk_search_tickets(query="assignee:agent@company.com tags:billing") +``` + +### List all agents + +```python +zendesk_list_users(role="agent", page_size=50) +``` + +## Ticket Status Values + +| Status | Meaning | +|--------|---------| +| `new` | Newly created, unassigned | +| `open` | Assigned and being worked on | +| `pending` | Waiting for requester response | +| `hold` | Waiting on a third party | +| `solved` | Resolved by agent | +| `closed` | Permanently closed | + +## Error Handling + +All tools return error dicts on failure: + +```python +[ + {"error": "ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, and ZENDESK_API_TOKEN not set", "help": "Create an API token in Zendesk Admin > Apps and integrations > APIs > Zendesk API"}, + {"error": "Unauthorized. Check your Zendesk credentials."}, + {"error": "Forbidden. Check your Zendesk permissions."}, + {"error": "Rate limited. Try again shortly."}, +] +``` diff --git a/tools/src/aden_tools/tools/zoom_tool/README.md b/tools/src/aden_tools/tools/zoom_tool/README.md new file mode 100644 index 00000000..420a3641 --- /dev/null +++ b/tools/src/aden_tools/tools/zoom_tool/README.md @@ -0,0 +1,130 @@ +# Zoom Tool + +Meeting management, recordings, and user info via the Zoom API v2. + +## Tools + +| Tool | Description | +|------|-------------| +| `zoom_get_user` | Get Zoom user profile information | +| `zoom_list_meetings` | List scheduled, live, or upcoming meetings for a user | +| `zoom_get_meeting` | Get full details of a specific meeting | +| `zoom_create_meeting` | Create a new instant or scheduled meeting | +| `zoom_update_meeting` | Update topic, time, duration, or agenda of a meeting | +| `zoom_delete_meeting` | Cancel and delete a meeting | +| `zoom_list_recordings` | List cloud recordings within a date range | +| `zoom_list_meeting_participants` | List participants from a past meeting | +| `zoom_list_meeting_registrants` | List registrants for a registration-enabled meeting | + +## Setup + +Requires a Zoom Server-to-Server OAuth access token: + +1. Go to [marketplace.zoom.us](https://marketplace.zoom.us) → **Develop → Build App → Server-to-Server OAuth** +2. Create an app and note the **Account ID**, **Client ID**, and **Client Secret** +3. Generate an access token and set it as an environment variable: + +```bash +ZOOM_ACCESS_TOKEN=your-server-to-server-oauth-token +``` + +> **Token expiry:** Server-to-Server OAuth tokens expire after **1 hour**. You will need to regenerate the token and update `ZOOM_ACCESS_TOKEN` when you see an `"Invalid or expired Zoom access token"` error. + +Required OAuth scopes: +- `meeting:read` — list and read meetings +- `meeting:write` — create, update, delete meetings +- `recording:read` — list cloud recordings +- `user:read` — read user profiles + +## Usage Examples + +### Get authenticated user info + +```python +zoom_get_user(user_id="me") +``` + +### List upcoming meetings + +```python +zoom_list_meetings(user_id="me", type="upcoming", page_size=10) +``` + +### Create a scheduled meeting + +```python +zoom_create_meeting( + topic="Sprint Planning", + start_time="2025-06-01T10:00:00Z", + duration=60, + timezone="America/New_York", + agenda="Review sprint backlog and assign tasks", +) +``` + +### Create an instant meeting + +```python +zoom_create_meeting(topic="Quick Sync") +``` + +### Update a meeting + +```python +zoom_update_meeting( + meeting_id="123456789", + topic="Sprint Planning - Updated", + duration=90, +) +``` + +### Delete a meeting + +```python +zoom_delete_meeting(meeting_id="123456789") +``` + +### List cloud recordings for a date range + +```python +zoom_list_recordings( + from_date="2025-05-01", + to_date="2025-05-31", + user_id="me", +) +``` + +### List participants from a past meeting + +```python +zoom_list_meeting_participants(meeting_id="123456789") +``` + +### List approved registrants + +```python +zoom_list_meeting_registrants( + meeting_id="123456789", + status="approved", +) +``` + +## Meeting Types + +| Type value | Meaning | +|------------|---------| +| `upcoming` | All upcoming meetings | +| `scheduled` | Scheduled meetings only | +| `live` | Currently live meetings | +| `previous_meetings` | Past meetings | + +## Error Handling + +All tools return error dicts on failure: + +```python +{"error": "Zoom credentials not configured", "help": "Set ZOOM_ACCESS_TOKEN environment variable or configure via credential store"} +{"error": "Invalid or expired Zoom access token"} +{"error": "Insufficient Zoom API scopes for this operation"} +{"error": "Zoom rate limit exceeded. Try again later."} +``` From 4df924d3d7f9f036343ff54d1fa48d33e2696af8 Mon Sep 17 00:00:00 2001 From: Aashutosh Pandey Date: Mon, 6 Apr 2026 20:20:43 +0530 Subject: [PATCH 16/28] fix(security): prevent error_middleware from leaking internal exception details to HTTP clients (#6903) The error_middleware was returning str(e) and type(e).__name__ directly in JSON responses, which could expose file paths, database connection strings, API key names, and internal class names to untrusted clients. Changes: - Return generic 'Internal server error' message instead of raw exception - Improve server-side log to include request method and path - Add unit tests verifying no internal details are leaked The full exception traceback remains available via logger.exception() for server-side debugging. Co-authored-by: Aashutosh Pandey --- core/framework/server/app.py | 13 ++- core/tests/test_error_middleware.py | 129 ++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+), 4 deletions(-) create mode 100644 core/tests/test_error_middleware.py diff --git a/core/framework/server/app.py b/core/framework/server/app.py index 369b017b..adb1c295 100644 --- a/core/framework/server/app.py +++ b/core/framework/server/app.py @@ -133,15 +133,20 @@ async def cors_middleware(request: web.Request, handler): @web.middleware async def error_middleware(request: web.Request, handler): - """Catch exceptions and return JSON error responses.""" + """Catch exceptions and return JSON error responses. + + Returns a generic error message to the client to avoid leaking + internal details (file paths, config values, stack traces). + The full exception is still logged server-side. + """ try: return await handler(request) except web.HTTPException: raise # Let aiohttp handle its own HTTP exceptions - except Exception as e: - logger.exception(f"Unhandled error: {e}") + except Exception: + logger.exception("Unhandled error on %s %s", request.method, request.path) return web.json_response( - {"error": str(e), "type": type(e).__name__}, + {"error": "Internal server error"}, status=500, ) diff --git a/core/tests/test_error_middleware.py b/core/tests/test_error_middleware.py new file mode 100644 index 00000000..39eb5c9f --- /dev/null +++ b/core/tests/test_error_middleware.py @@ -0,0 +1,129 @@ +""" +Tests for error_middleware in framework.server.app. + +Verifies that the error middleware does NOT leak internal exception +details (file paths, config values, stack traces) to HTTP clients. +""" + +import pytest +from aiohttp import web +from aiohttp.test_utils import TestClient, TestServer + +from framework.server.app import error_middleware + +# --------------------------------------------------------------------------- +# Handlers used in tests +# --------------------------------------------------------------------------- + + +async def _handler_raise_value_error(request: web.Request) -> web.Response: + """Handler that raises ValueError with sensitive path info.""" + raise ValueError("/home/user/.hive/credentials/secret_key.json not found") + + +async def _handler_raise_runtime_error(request: web.Request) -> web.Response: + """Handler that raises RuntimeError with internal details.""" + raise RuntimeError("Connection to postgres://admin:s3cret@db:5432/hive failed") + + +async def _handler_raise_key_error(request: web.Request) -> web.Response: + """Handler that raises KeyError with config key name.""" + raise KeyError("ANTHROPIC_API_KEY") + + +async def _handler_success(request: web.Request) -> web.Response: + """Handler that returns a normal 200 response.""" + return web.json_response({"status": "ok"}) + + +async def _handler_http_not_found(request: web.Request) -> web.Response: + """Handler that raises aiohttp's HTTP 404.""" + raise web.HTTPNotFound(reason="Agent not found") + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_app() -> web.Application: + """Create a minimal aiohttp app with error_middleware and test routes.""" + app = web.Application(middlewares=[error_middleware]) + app.router.add_get("/value-error", _handler_raise_value_error) + app.router.add_get("/runtime-error", _handler_raise_runtime_error) + app.router.add_get("/key-error", _handler_raise_key_error) + app.router.add_get("/success", _handler_success) + app.router.add_get("/not-found", _handler_http_not_found) + return app + + +# --------------------------------------------------------------------------- +# Tests +# --------------------------------------------------------------------------- + + +class TestErrorMiddlewareInfoLeak: + """Verify error_middleware returns generic messages, not internal details.""" + + @pytest.mark.asyncio + async def test_does_not_leak_file_paths(self): + """ValueError with file path must not appear in response body.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/value-error") + assert resp.status == 500 + body = await resp.json() + assert body["error"] == "Internal server error" + # Ensure no sensitive details leaked + assert ".hive" not in body["error"] + assert "secret_key" not in body["error"] + assert "type" not in body # type field should not exist + + @pytest.mark.asyncio + async def test_does_not_leak_connection_strings(self): + """RuntimeError with DB connection string must not appear in response.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/runtime-error") + assert resp.status == 500 + body = await resp.json() + assert body["error"] == "Internal server error" + assert "postgres" not in body["error"] + assert "s3cret" not in body["error"] + + @pytest.mark.asyncio + async def test_does_not_leak_env_var_names(self): + """KeyError with env var name must not appear in response body.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/key-error") + assert resp.status == 500 + body = await resp.json() + assert body["error"] == "Internal server error" + assert "ANTHROPIC_API_KEY" not in body["error"] + + @pytest.mark.asyncio + async def test_does_not_leak_exception_type(self): + """Response must not include the Python exception type name.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/value-error") + body = await resp.json() + assert "type" not in body + assert "ValueError" not in str(body) + + @pytest.mark.asyncio + async def test_success_response_unchanged(self): + """Normal 200 responses must pass through untouched.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/success") + assert resp.status == 200 + body = await resp.json() + assert body == {"status": "ok"} + + @pytest.mark.asyncio + async def test_http_exceptions_pass_through(self): + """aiohttp HTTPExceptions (404, etc.) must not be caught.""" + async with TestClient(TestServer(_make_app())) as client: + resp = await client.get("/not-found") + assert resp.status == 404 + + +if __name__ == "__main__": + pytest.main([__file__, "-v"]) From 1ac50ab5328bfda1bd0dd6525b4e2f67441a4bf9 Mon Sep 17 00:00:00 2001 From: Akash Date: Mon, 6 Apr 2026 20:32:26 +0530 Subject: [PATCH 17/28] feat: add theme toggle and tab improvements (#6062) Co-authored-by: Akash Kumar --- core/frontend/index.html | 2 +- core/frontend/src/components/ThemeToggle.tsx | 20 +++ core/frontend/src/components/TopBar.tsx | 147 ++++++++++++------- core/frontend/src/context/ThemeContext.tsx | 49 +++++++ core/frontend/src/main.tsx | 9 +- 5 files changed, 170 insertions(+), 57 deletions(-) create mode 100644 core/frontend/src/components/ThemeToggle.tsx create mode 100644 core/frontend/src/context/ThemeContext.tsx diff --git a/core/frontend/index.html b/core/frontend/index.html index 2630d58a..135decf2 100644 --- a/core/frontend/index.html +++ b/core/frontend/index.html @@ -1,5 +1,5 @@ - + diff --git a/core/frontend/src/components/ThemeToggle.tsx b/core/frontend/src/components/ThemeToggle.tsx new file mode 100644 index 00000000..f6ed61fe --- /dev/null +++ b/core/frontend/src/components/ThemeToggle.tsx @@ -0,0 +1,20 @@ +import { Sun, Moon } from "lucide-react"; +import { useTheme } from "../context/ThemeContext"; + +export default function ThemeToggle() { + const { theme, setTheme } = useTheme(); + + return ( + + ); +} \ No newline at end of file diff --git a/core/frontend/src/components/TopBar.tsx b/core/frontend/src/components/TopBar.tsx index 2b3ff7b5..635e087b 100644 --- a/core/frontend/src/components/TopBar.tsx +++ b/core/frontend/src/components/TopBar.tsx @@ -1,8 +1,14 @@ import { useState, useCallback } from "react"; import { useNavigate } from "react-router-dom"; import { Crown, X } from "lucide-react"; +import { + loadPersistedTabs, + savePersistedTabs, + TAB_STORAGE_KEY, + type PersistedTabState, +} from "@/lib/tab-persistence"; +import ThemeToggle from "./ThemeToggle"; import { sessionsApi } from "@/api/sessions"; -import { loadPersistedTabs, savePersistedTabs, TAB_STORAGE_KEY, type PersistedTabState } from "@/lib/tab-persistence"; import BrowserStatusBadge from "@/components/BrowserStatusBadge"; export interface TopBarTab { @@ -27,65 +33,89 @@ interface TopBarProps { children?: React.ReactNode; } -export default function TopBar({ tabs: tabsProp, onTabClick, onCloseTab, canCloseTabs, afterTabs, children }: TopBarProps) { +export default function TopBar({ + tabs: tabsProp, + onTabClick, + onCloseTab, + canCloseTabs, + afterTabs, + children, +}: TopBarProps) { const navigate = useNavigate(); // Fallback: read persisted tabs when no live tabs provided const [persisted, setPersisted] = useState(() => - tabsProp ? null : loadPersistedTabs() + tabsProp ? null : loadPersistedTabs(), ); const tabs: TopBarTab[] = tabsProp ?? deriveTabs(persisted); const showClose = canCloseTabs ?? true; - const handleTabClick = useCallback((agentType: string) => { - if (onTabClick) { - onTabClick(agentType); - } else { - navigate(`/workspace?agent=${encodeURIComponent(agentType)}`); - } - }, [onTabClick, navigate]); - - const handleCloseTab = useCallback((agentType: string, e: React.MouseEvent) => { - e.stopPropagation(); - if (onCloseTab) { - onCloseTab(agentType); - return; - } - // Kill the backend session (queen/worker) even outside workspace - sessionsApi.list() - .then(({ sessions }) => { - const match = sessions.find(s => s.agent_path.endsWith(agentType)); - if (match) return sessionsApi.stop(match.session_id); - }) - .catch(() => {}); // fire-and-forget - - // Fallback: update localStorage directly (non-workspace pages) - setPersisted(prev => { - if (!prev) return null; - const nextTabs = prev.tabs.filter(t => t.agentType !== agentType); - if (nextTabs.length === 0) { - localStorage.removeItem(TAB_STORAGE_KEY); - return null; + const handleTabClick = useCallback( + (agentType: string) => { + if (onTabClick) { + onTabClick(agentType); + } else { + navigate(`/workspace?agent=${encodeURIComponent(agentType)}`); } - const removedIds = new Set(prev.tabs.filter(t => t.agentType === agentType).map(t => t.id)); - const nextSessions = { ...prev.sessions }; - for (const id of removedIds) delete nextSessions[id]; - const nextActiveSession = { ...prev.activeSessionByAgent }; - delete nextActiveSession[agentType]; - const nextActiveWorker = prev.activeWorker === agentType - ? nextTabs[0].agentType - : prev.activeWorker; - const nextState: PersistedTabState = { - tabs: nextTabs, - activeSessionByAgent: nextActiveSession, - activeWorker: nextActiveWorker, - sessions: nextSessions, - }; - savePersistedTabs(nextState); - return nextState; - }); - }, [onCloseTab]); + }, + [onTabClick, navigate], + ); + + const handleCloseTab = useCallback( + (agentType: string, e: React.MouseEvent) => { + e.stopPropagation(); + if (onCloseTab) { + onCloseTab(agentType); + return; + } + // Kill the backend session (queen/worker) even outside workspace + + sessionsApi + .list() + .then(({ sessions }) => { + const match = sessions.find((s) => s.agent_path.endsWith(agentType)); + if (match) return sessionsApi.stop(match.session_id); + }) + .catch(() => {}); // fire-and-forget + + // Fallback: update localStorage directly (non-workspace pages) + setPersisted((prev) => { + if (!prev) return null; + const nextTabs = prev.tabs.filter((t) => t.agentType !== agentType); + + if (nextTabs.length === 0) { + localStorage.removeItem(TAB_STORAGE_KEY); + return null; + } + + const removedIds = new Set( + prev.tabs.filter((t) => t.agentType === agentType).map((t) => t.id), + ); + const nextSessions = { ...prev.sessions }; + for (const id of removedIds) delete nextSessions[id]; + + const nextActiveSession = { ...prev.activeSessionByAgent }; + delete nextActiveSession[agentType]; + + const nextActiveWorker = + prev.activeWorker === agentType + ? nextTabs[0].agentType + : prev.activeWorker; + + const nextState: PersistedTabState = { + tabs: nextTabs, + activeSessionByAgent: nextActiveSession, + activeWorker: nextActiveWorker, + sessions: nextSessions, + }; + + savePersistedTabs(nextState); + return nextState; + }); + }, + [onCloseTab], + ); return (
@@ -115,6 +145,7 @@ export default function TopBar({ tabs: tabsProp, onTabClick, onCloseTab, canClos )} + {tab.label} {showClose && ( ))}
+ {afterTabs} )}
+ {children && (
@@ -145,15 +178,23 @@ export default function TopBar({ tabs: tabsProp, onTabClick, onCloseTab, canClos /** Derive TopBarTab[] from persisted localStorage state (used outside workspace). */ function deriveTabs(persisted: PersistedTabState | null): TopBarTab[] { if (!persisted) return []; + const seen = new Set(); const tabs: TopBarTab[] = []; + for (const tab of persisted.tabs) { if (seen.has(tab.agentType)) continue; + seen.add(tab.agentType); + const sessionData = persisted.sessions?.[tab.id]; - const hasRunning = sessionData?.graphNodes?.some( - (n) => n.status === "running" || n.status === "looping" - ) ?? false; + + const hasRunning = + sessionData?.graphNodes?.some( + (n) => n.status === "running" || n.status === "looping", + ) ?? false; + + tabs.push({ agentType: tab.agentType, label: tab.label, diff --git a/core/frontend/src/context/ThemeContext.tsx b/core/frontend/src/context/ThemeContext.tsx new file mode 100644 index 00000000..1a38b24b --- /dev/null +++ b/core/frontend/src/context/ThemeContext.tsx @@ -0,0 +1,49 @@ +import React, { createContext, useContext, useEffect, useState } from "react"; + +type Theme = "light" | "dark"; + +interface ThemeContextValue { + theme: Theme; + setTheme: (theme: Theme) => void; +} + +const ThemeContext = createContext(null); + +export function ThemeProvider({ children }: { children: React.ReactNode }) { + const [theme, setTheme] = useState(() => { + const stored = localStorage.getItem("theme"); + + if (stored === "light" || stored === "dark") { + return stored; + } + + return window.matchMedia("(prefers-color-scheme: dark)").matches + ? "dark" + : "light"; + }); + + useEffect(() => { + const root = document.documentElement; + + root.classList.remove("light", "dark"); + root.classList.add(theme); + + localStorage.setItem("theme", theme); + }, [theme]); + + return ( + + {children} + + ); +} + +export function useTheme(): ThemeContextValue { + const context = useContext(ThemeContext); + + if (!context) { + throw new Error("useTheme must be used within a ThemeProvider"); + } + + return context; +} \ No newline at end of file diff --git a/core/frontend/src/main.tsx b/core/frontend/src/main.tsx index 5f512729..aaf33e01 100644 --- a/core/frontend/src/main.tsx +++ b/core/frontend/src/main.tsx @@ -1,10 +1,13 @@ import ReactDOM from "react-dom/client"; import { BrowserRouter } from "react-router-dom"; +import { ThemeProvider } from "./context/ThemeContext"; import App from "./App"; import "./index.css"; ReactDOM.createRoot(document.getElementById("root")!).render( - - - + + + + + , ); From 33e6c018a398a702c8ce40286b7ee2a6b3426648 Mon Sep 17 00:00:00 2001 From: "Rodrigo M.V.S." <88489374+RodrigoMvs123@users.noreply.github.com> Date: Mon, 6 Apr 2026 12:16:29 -0300 Subject: [PATCH 18/28] docs: Add Frontend Dev Workflow subsection to CONTRIBUTING.md (#6523) * chore: update package-lock.json after npm install * fix: export validate_agent_path from server module * fix: remove circular import in server module * docs: Add Frontend Dev Workflow subsection to CONTRIBUTING.md * chore: revert accidental package-lock.json changes * docs: clarify frontend dev requires both backend and dev server --------- Co-authored-by: hundao --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5565e43d..7415caaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -333,6 +333,22 @@ make test-live # Run live API integration tests (requires credentials) - **WebSocket** for real-time updates - **Tailwind CSS** for styling +### Frontend Dev Workflow + +> **Note:** `./quickstart.sh` handles the full setup including the web UI. +> The commands below are for contributors iterating on the frontend code after +> initial setup is complete. + +```bash +# Start the backend server +hive serve + +# In a separate terminal, run the frontend dev server with hot-reload +cd core/frontend +npm install # only needed after dependency changes +npm run dev +``` + ### Useful Development Commands ```bash From 66866e524db175fd73b897b9c021ae7fcd93f600 Mon Sep 17 00:00:00 2001 From: Richard Tang Date: Mon, 6 Apr 2026 13:05:03 -0700 Subject: [PATCH 19/28] fix: remove old new agent button --- core/frontend/src/pages/workspace.tsx | 230 ++------------------------ 1 file changed, 10 insertions(+), 220 deletions(-) diff --git a/core/frontend/src/pages/workspace.tsx b/core/frontend/src/pages/workspace.tsx index 10595293..5c2055e3 100644 --- a/core/frontend/src/pages/workspace.tsx +++ b/core/frontend/src/pages/workspace.tsx @@ -1,7 +1,6 @@ import { useState, useCallback, useRef, useEffect, useMemo } from "react"; -import ReactDOM from "react-dom"; import { useSearchParams, useNavigate } from "react-router-dom"; -import { Plus, KeyRound, Sparkles, Layers, ChevronLeft, Bot, Loader2, WifiOff, X, FolderOpen } from "lucide-react"; +import { Plus, KeyRound, Loader2, WifiOff, X, FolderOpen } from "lucide-react"; import type { GraphNode, NodeStatus } from "@/components/graph-types"; import DraftGraph from "@/components/DraftGraph"; import ChatPanel, { type ChatMessage } from "@/components/ChatPanel"; @@ -9,12 +8,11 @@ import TopBar from "@/components/TopBar"; import { TAB_STORAGE_KEY, loadPersistedTabs, savePersistedTabs, type PersistedTabState } from "@/lib/tab-persistence"; import NodeDetailPanel from "@/components/NodeDetailPanel"; import CredentialsModal, { type Credential, createFreshCredentials, cloneCredentials, allRequiredCredentialsMet, clearCredentialCache } from "@/components/CredentialsModal"; -import { agentsApi } from "@/api/agents"; import { executionApi } from "@/api/execution"; import { graphsApi } from "@/api/graphs"; import { sessionsApi } from "@/api/sessions"; import { useMultiSSE } from "@/hooks/use-sse"; -import type { LiveSession, AgentEvent, DiscoverEntry, NodeSpec, DraftGraph as DraftGraphData } from "@/api/types"; +import type { LiveSession, AgentEvent, NodeSpec, DraftGraph as DraftGraphData } from "@/api/types"; import { sseEventToChatMessage, formatAgentDisplayName } from "@/lib/chat-helpers"; import { topologyToGraphNodes } from "@/lib/graph-converter"; import { cronToLabel } from "@/lib/graphUtils"; @@ -90,152 +88,6 @@ function createSession(agentType: string, label: string, existingCredentials?: C }; } -// --- NewTabPopover --- -type PopoverStep = "root" | "new-agent-choice" | "clone-pick"; - -interface NewTabPopoverProps { - open: boolean; - onClose: () => void; - anchorRef: React.RefObject; - activeWorker: string; - discoverAgents: DiscoverEntry[]; - onFromScratch: () => void; - onCloneAgent: (agentPath: string, agentName: string) => void; -} - -function NewTabPopover({ open, onClose, anchorRef, discoverAgents, onFromScratch, onCloneAgent }: NewTabPopoverProps) { - const [step, setStep] = useState("root"); - const [pos, setPos] = useState<{ top: number; left: number } | null>(null); - const ref = useRef(null); - - useEffect(() => { if (open) setStep("root"); }, [open]); - - // Compute position from anchor button - useEffect(() => { - if (open && anchorRef.current) { - const rect = anchorRef.current.getBoundingClientRect(); - const POPUP_WIDTH = 240; // w-60 = 15rem = 240px - const overflows = rect.left + POPUP_WIDTH > window.innerWidth - 8; - console.log("Anchor rect:", rect, "Overflows:", overflows); -setPos({ - top: rect.bottom + 4, - left: overflows ? rect.right - POPUP_WIDTH : rect.left, -}); - } - }, [open, anchorRef]); - - // Close on outside click - useEffect(() => { - if (!open) return; - const handler = (e: MouseEvent) => { - if ( - ref.current && !ref.current.contains(e.target as Node) && - anchorRef.current && !anchorRef.current.contains(e.target as Node) - ) onClose(); - }; - document.addEventListener("mousedown", handler); - return () => document.removeEventListener("mousedown", handler); - }, [open, onClose, anchorRef]); - - // Close on Escape - useEffect(() => { - if (!open) return; - const handler = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); }; - document.addEventListener("keydown", handler); - return () => document.removeEventListener("keydown", handler); - }, [open, onClose]); - - if (!open || !pos) return null; - - const optionClass = - "flex items-center gap-3 w-full px-3 py-2.5 rounded-lg text-sm text-left transition-colors hover:bg-muted/60 text-foreground"; - const iconWrap = - "w-7 h-7 rounded-md flex items-center justify-center bg-muted/80 flex-shrink-0"; - - return ReactDOM.createPortal( -
-
- {step !== "root" && ( - - )} - - {step === "root" ? "Add Tab" : step === "new-agent-choice" ? "New Agent" : "Open Agent"} - -
- -
- {step === "root" && ( - <> - - - - )} - - {step === "new-agent-choice" && ( - <> - - - - )} - - {step === "clone-pick" && ( -
- {discoverAgents.map(agent => ( - - ))} - {discoverAgents.length === 0 && ( -

No agents found

- )} -
- )} -
-
, - document.body - ); -} - function fmtLogTs(ts: string): string { try { const d = new Date(ts); @@ -581,8 +433,6 @@ export default function Workspace() { const [triggerScheduleSaving, setTriggerScheduleSaving] = useState(false); const [triggerCronSaved, setTriggerCronSaved] = useState(false); const [triggerTaskSaved, setTriggerTaskSaved] = useState(false); - const [newTabOpen, setNewTabOpen] = useState(false); - const newTabBtnRef = useRef(null); const [graphPanelPct, setGraphPanelPct] = useState(30); const savedGraphPanelPct = useRef(30); const resizing = useRef(false); @@ -734,15 +584,6 @@ export default function Workspace() { } }, [agentStates, activeWorker, updateAgentState]); - // --- Fetch discovered agents for NewTabPopover --- - const [discoverAgents, setDiscoverAgents] = useState([]); - useEffect(() => { - agentsApi.discover().then(result => { - const { Framework: _fw, ...userFacing } = result; - const all = Object.values(userFacing).flat(); - setDiscoverAgents(all); - }).catch(() => { }); - }, []); // --- Agent loading: loadAgentForType --- const loadingRef = useRef(new Set()); @@ -1144,7 +985,7 @@ export default function Workspace() { i === 0 ? { ...s, // Preserve existing label if it was already set with a #N suffix by - // addAgentSession/handleHistoryOpen. Only overwrite with the bare + // handleHistoryOpen. Only overwrite with the bare // displayName when the label doesn't match the resolved display name. label: s.label.startsWith(displayName) ? s.label : displayName, backendSessionId: session.session_id, @@ -2749,45 +2590,6 @@ export default function Workspace() { } }, [sessionsByAgent, activeWorker, navigate, agentStates]); - // Open a tab for an agent type. If a tab already exists, switch to it - // instead of creating a duplicate — each agent gets one session. - // Exception: "new-agent" tabs always create a new instance since each - // represents a distinct conversation the user is starting from scratch. - const addAgentSession = useCallback((agentType: string, agentLabel?: string) => { - const isNewAgent = agentType === "new-agent" || agentType.startsWith("new-agent-"); - - if (!isNewAgent) { - const existingTabKey = Object.keys(sessionsByAgent).find( - k => baseAgentType(k) === agentType && (sessionsByAgent[k] || []).length > 0, - ); - if (existingTabKey) { - setActiveWorker(existingTabKey); - const existing = sessionsByAgent[existingTabKey]?.[0]; - if (existing) { - setActiveSessionByAgent(prev => ({ ...prev, [existingTabKey]: existing.id })); - } - return; - } - } - - const tabKey = isNewAgent ? `new-agent-${makeId()}` : agentType; - const existingNewAgentCount = isNewAgent - ? Object.keys(sessionsByAgent).filter( - k => (k === "new-agent" || k.startsWith("new-agent-")) && (sessionsByAgent[k] || []).length > 0 - ).length - : 0; - const rawLabel = agentLabel || (isNewAgent ? "New Agent" : formatAgentDisplayName(agentType)); - const displayLabel = existingNewAgentCount === 0 ? rawLabel : `${rawLabel} #${existingNewAgentCount + 1}`; - const newSession = createSession(tabKey, displayLabel); - - setSessionsByAgent(prev => ({ - ...prev, - [tabKey]: [newSession], - })); - setActiveSessionByAgent(prev => ({ ...prev, [tabKey]: newSession.id })); - setActiveWorker(tabKey); - }, [sessionsByAgent]); - // Open a history session: switch to its existing tab, or open a new tab. // Async so we can pre-fetch messages before creating the tab — this gives // instant visual feedback without waiting for loadAgentForType. @@ -2894,25 +2696,13 @@ export default function Workspace() { }} onCloseTab={closeAgentTab} afterTabs={ - <> - - setNewTabOpen(false)} - anchorRef={newTabBtnRef} - activeWorker={activeWorker} - discoverAgents={discoverAgents} - onFromScratch={() => { addAgentSession("new-agent"); }} - onCloneAgent={(agentPath, agentName) => { addAgentSession(agentPath, agentName); }} - /> - + } >

Open the Chrome extensions page and enable Developer mode using the toggle in the top-right corner.

- chrome://extensions/ -
If the link above doesn't open, copy chrome://extensions/ and paste it into your Chrome address bar.
+ +
Chrome doesn't allow pages to open chrome:// URLs directly. Click the button above to copy the link, then paste it into your address bar and press Enter.
Image
@@ -208,7 +230,10 @@ Select the extension folder

In the folder picker, navigate to (or paste) the following path:

-
tools/browser-extension
+
+ tools/browser-extension + +
The quickstart script copies this path to your clipboard — just paste it in the folder picker.
If pasting doesn't work, navigate manually: open the folder where you cloned the Hive repo, then go into tools → browser-extension. For example, if you cloned to ~/projects/hive, the full path would be ~/projects/hive/tools/browser-extension.
Image @@ -237,6 +262,23 @@ if (extPath) { document.getElementById('extension-path').textContent = extPath; } + + // Copy chrome://extensions/ button + document.getElementById('chrome-link-btn').addEventListener('click', function() { + navigator.clipboard.writeText('chrome://extensions/').then(() => { + this.textContent = 'Copied!'; + setTimeout(() => { this.textContent = 'Copy chrome://extensions/'; }, 1500); + }); + }); + + // Copy path button + document.getElementById('copy-path-btn').addEventListener('click', function() { + const path = document.getElementById('extension-path').textContent; + navigator.clipboard.writeText(path).then(() => { + this.textContent = 'Copied!'; + setTimeout(() => { this.textContent = 'Copy'; }, 1500); + }); + }); From cd9a625041c265a8fcf1c3c7cd6d3f7a5bc89893 Mon Sep 17 00:00:00 2001 From: Richard Tang Date: Mon, 6 Apr 2026 13:21:06 -0700 Subject: [PATCH 21/28] fix: dynamic absolute path and instruction --- docs/browser-extension-setup.html | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/browser-extension-setup.html b/docs/browser-extension-setup.html index 6d1310f0..d7ec5779 100644 --- a/docs/browser-extension-setup.html +++ b/docs/browser-extension-setup.html @@ -229,13 +229,12 @@ 3 Select the extension folder -

In the folder picker, navigate to (or paste) the following path:

+

In the folder picker, paste the path below. Click Copy to copy it to your clipboard.

tools/browser-extension
-
The quickstart script copies this path to your clipboard — just paste it in the folder picker.
-
If pasting doesn't work, navigate manually: open the folder where you cloned the Hive repo, then go into tools → browser-extension. For example, if you cloned to ~/projects/hive, the full path would be ~/projects/hive/tools/browser-extension.
+
Alternatively, you can navigate there manually: open the folder where you cloned the Hive repo, then go into tools → browser-extension.
Image @@ -256,11 +255,19 @@