onex-cli 1.18.2__tar.gz → 1.19.0__tar.gz

{onex_cli-1.18.2 → onex_cli-1.19.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.19.0] - 2026-04-14
+
+### Added
+- **`onex logs --function`** - Filter logs by invoke handler name
+  (e.g. `--function invoice_automation_contract`). Matches the canonical
+  `function_name` field in shared-runtime and trigger-service structured
+  logs. Solves "my stream/schedule/event handler has no URL path so
+  `--path` doesn't help me find its logs."
+- **`onex logs --invocation-source`** - Filter logs by WHY the handler
+  ran. One of `http`, `stream`, `event`, `schedule`, `s3`, `async_invoke`,
+  `manual`. Combines with `--function` to isolate e.g. only the
+  stream-triggered runs of a specific handler.
+- **`onex executions`** - New command. Canonical "did my handler run,
+  when, and why" view, backed by MongoDB `invoke_executions` so it
+  survives Loki log retention. Accepts `--source`, `--status`,
+  `--trace-id`, `--last`, `--limit`, `--json`. Compact colored table
+  output with `invocation_detail` (e.g. `contract/update/<doc_id>` for
+  stream triggers, `schedule/<trigger_id>` for cron,
+  `<bucket>/<event>/<key>` for s3) under each row.
+- **MCP tool `onex_executions`** - Same query surface as the CLI command,
+  exposed to Claude Code. Docstring includes rich examples so Claude
+  picks up the stream/schedule/manual patterns automatically.
+- **MCP tool `onex_logs`** - Gained `function_name` and
+  `invocation_source` parameters to match the new CLI flags. Docstring
+  updated with examples covering invoke-handler tracing.
+
+### Notes
+- Requires platform commits `52599d9` (unified invocation tracking) and
+  `11f10e6` (MONGODB_URI_PLATFORM env fix) to be deployed on the target
+  environment. Without those, `onex executions` will return empty rows
+  because `invoke_executions` isn't being populated with the new
+  top-level `invocation_source` field.
+- Documented in `docs/service-developers/CLI_REFERENCE.md`,
+  `REQUEST_TRACING.md`, `LOGGING.md`, `TROUBLESHOOTING.md`, and `FAQ.md`.
+
 ## [1.13.0] - 2026-03-30
 
 ### Added

{onex_cli-1.18.2/onex_cli.egg-info → onex_cli-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onex-cli
-Version: 1.18.2
+Version: 1.19.0
 Summary: Official CLI for deploying and managing services on OneXEOS Platform (Windows, macOS, Linux)
 Home-page: https://github.com/onexeos/onex-cli
 Author: OneXEOS Platform Team

{onex_cli-1.18.2 → onex_cli-1.19.0}/onex/__init__.py

@@ -1,2 +1,2 @@
 # OneXEOS Services CLI
-__version__ = "1.18.2"
+__version__ = "1.19.0"

{onex_cli-1.18.2 → onex_cli-1.19.0}/onex/__main__.py

@@ -17,6 +17,7 @@ Commands:
   provision - Manually provision resources
   invoke    - Invoke handlers directly
   trace     - Track requests through platform
+  executions - List invoke execution history (cross-source)
   replay    - Re-send a previously captured request
   test      - Run E2E tests against the platform
   create-e2e - Scaffold E2E tests for a service
@@ -30,7 +31,7 @@ Environments:
 """
 
 import click
-from onex.commands import deploy, undeploy, dev, debug, init, logs, status, provision, invoke, trace, validate, login, logout, env, platform, vpn, switch, mcp, create, replay, es, s3, test, create_e2e, reload
+from onex.commands import deploy, undeploy, dev, debug, init, logs, status, provision, invoke, trace, validate, login, logout, env, platform, vpn, switch, mcp, create, replay, es, s3, test, create_e2e, reload, executions
 
 
 # Commands that don't require authentication
@@ -100,6 +101,7 @@ cli.add_command(reload.reload)
 cli.add_command(provision.provision)
 cli.add_command(invoke.invoke)
 cli.add_command(trace.trace)
+cli.add_command(executions.executions)
 cli.add_command(replay.replay)
 cli.add_command(es.es)
 cli.add_command(s3.s3)

onex_cli-1.19.0/onex/commands/executions.py

@@ -0,0 +1,159 @@
+"""
+Executions command — query invoke execution history from invoke_executions.
+
+Covers every invocation of a handler regardless of source: HTTP, stream
+trigger, event, schedule, s3, async invoke, manual CLI. Backed by the
+platform ExecutionTracker (MongoDB invoke_executions collection).
+"""
+
+import json as _json
+
+import click
+import requests
+
+from onex.config import get_config, get_access_token, get_active_environment
+from onex.utils import print_error, print_info, print_warning
+from onex.utils.auth import auto_refresh_token
+
+
+VALID_SOURCES = ['http', 'stream', 'event', 'schedule', 's3', 'async_invoke', 'manual']
+VALID_STATUSES = ['pending', 'running', 'succeeded', 'failed', 'retrying', 'dead_letter']
+
+
+@click.command()
+@click.argument('function_name', required=False)
+@click.option('--source', 'invocation_source',
+              type=click.Choice(VALID_SOURCES),
+              help='Filter by invocation source (why the handler ran)')
+@click.option('--status', type=click.Choice(VALID_STATUSES),
+              help='Filter by execution status')
+@click.option('--trace-id', help='Filter by trace ID')
+@click.option('--last', help='Time range (e.g., 1h, 30m, 24h, 7d)')
+@click.option('--limit', default=20, help='Max rows to return (default: 20)')
+@click.option('--offset', default=0, help='Pagination offset')
+@click.option('--env', default=None, help='Environment (local/dev/staging/prod)')
+@click.option('--platform-url', help='Override platform URL')
+@click.option('--json', 'output_json', is_flag=True, help='Output as JSON')
+def executions(function_name, invocation_source, status, trace_id, last,
+               limit, offset, env, platform_url, output_json):
+    """List invoke execution history for a handler.
+
+    Answers questions like "has my stream-triggered invoice handler actually
+    run in the last day, and did it succeed?" — data that Loki log retention
+    may have aged out but invoke_executions still has.
+
+    \b
+    Examples:
+      # Every run of a handler in the last 24h
+      onex executions automation:invoice_automation_contract --last 24h
+
+      # Only the stream-triggered runs
+      onex executions automation:invoice_automation_contract \\
+          --source stream --last 7d
+
+      # Failed manual (CLI) test runs
+      onex executions automation:invoice_automation_contract \\
+          --source manual --status failed --last 7d
+
+      # All scheduled runs across ALL handlers in the last hour
+      onex executions --source schedule --last 1h
+
+      # Everything tied to a specific trace_id (cross-source)
+      onex executions --trace-id abc-123-def
+    """
+    if env is None:
+        env = get_active_environment()
+
+    config = get_config()
+    platform_base_url = platform_url or config.get_platform_url(env)
+    url = f"{platform_base_url}/api/invoke/executions"
+
+    access_token = get_access_token(env)
+    headers = {}
+    if access_token:
+        headers['Authorization'] = f'Bearer {access_token}'
+
+    params = {'limit': limit, 'offset': offset}
+    if function_name:
+        params['function_name'] = function_name
+    if invocation_source:
+        params['invocation_source'] = invocation_source
+    if status:
+        params['status'] = status
+    if trace_id:
+        params['trace_id'] = trace_id
+    if last:
+        params['last'] = last
+
+    try:
+        response = requests.get(url, params=params, headers=headers, timeout=15)
+
+        if response.status_code == 401 and env != "local":
+            print_warning("Token expired, refreshing...")
+            if auto_refresh_token(env, silent=False):
+                access_token = get_access_token(env)
+                headers['Authorization'] = f'Bearer {access_token}'
+                response = requests.get(url, params=params, headers=headers, timeout=15)
+            else:
+                print_error("Authentication failed - could not refresh token")
+                print_info(f"Please login again: onex login --env {env}")
+                return
+
+        if response.status_code != 200:
+            print_error(f"Failed to fetch executions: HTTP {response.status_code}")
+            try:
+                print_error(response.json().get('detail', response.text[:200]))
+            except Exception:
+                print_error(response.text[:200])
+            return
+
+        data = response.json()
+        rows = data.get('executions', [])
+        total = data.get('total', 0)
+
+        if output_json:
+            click.echo(_json.dumps(data, indent=2, default=str))
+            return
+
+        if not rows:
+            click.echo(f"No executions found (total={total}).")
+            return
+
+        # Compact table
+        click.echo(f"\n{total} execution(s), showing {len(rows)}:\n")
+        header = f"{'STARTED':<20} {'STATUS':<10} {'SOURCE':<13} {'MS':>7}  FUNCTION / DETAIL"
+        click.echo(header)
+        click.echo('-' * len(header))
+        for r in rows:
+            started = (r.get('started_at') or '')[:19].replace('T', ' ')
+            st = (r.get('status') or '?')[:10]
+            src = (r.get('invocation_source') or '-')[:13]
+            ms = r.get('execution_time_ms')
+            ms_str = f"{ms:7.0f}" if isinstance(ms, (int, float)) else "      -"
+            fname = r.get('function_name') or '-'
+            detail = r.get('invocation_detail') or ''
+
+            # Color-code by status
+            if st == 'failed' or st == 'dead_letter':
+                line = click.style(f"{started:<20} {st:<10} {src:<13} {ms_str}  {fname}", fg='red')
+            elif st == 'succeeded':
+                line = f"{started:<20} {click.style(st, fg='green'):<10} {src:<13} {ms_str}  {fname}"
+                # click.style adds ANSI bytes so the format width is off; re-render:
+                line = f"{started:<20} {st:<10} {src:<13} {ms_str}  {fname}"
+            else:
+                line = f"{started:<20} {st:<10} {src:<13} {ms_str}  {fname}"
+            click.echo(line)
+            if detail:
+                click.echo(f"{'':<20} {'':<10} {'':<13} {'':>7}  └─ {detail}")
+            err = r.get('error')
+            if err:
+                err_preview = err if len(err) < 120 else err[:117] + '...'
+                click.echo(click.style(f"{'':<20} {'':<10} {'':<13} {'':>7}  ⚠ {err_preview}", fg='yellow'))
+
+        click.echo()
+
+    except requests.exceptions.ConnectionError:
+        print_error(f"Cannot connect to platform at {platform_base_url}")
+        print_info("Make sure platform is running")
+    except Exception as e:
+        print_error(f"Error fetching executions: {e}")

{onex_cli-1.18.2 → onex_cli-1.19.0}/onex/commands/logs.py

@@ -24,12 +24,18 @@ from onex.utils.auth import auto_refresh_token
 @click.option('--path', help='Filter by API path')
 @click.option('--method', help='Filter by HTTP method (GET, POST, etc.)')
 @click.option('--event', help='Filter by event type (service_ready, error, etc.)')
+@click.option('--function', 'function_name',
+              help='Filter by invoke handler function name (e.g. invoice_automation_contract)')
+@click.option('--invocation-source',
+              type=click.Choice(['http', 'stream', 'event', 'schedule', 's3', 'async_invoke', 'manual']),
+              help='Filter by why the handler ran (stream trigger, schedule, manual, etc.)')
 @click.option('--grep', help='Search message with regex pattern')
 @click.option('--last', help='Time range (e.g., 1h, 30m, 24h)')
 # Output options
 @click.option('--json', 'output_json', is_flag=True, help='Output as JSON')
 def logs(service_name, follow, lines, env, platform_url, level, trace_id, user_id,
-         company_id, path, method, event, grep, last, output_json):
+         company_id, path, method, event, function_name, invocation_source,
+         grep, last, output_json):
     """View service logs from platform with powerful filtering.
 
     \b
@@ -51,6 +57,22 @@ def logs(service_name, follow, lines, env, platform_url, level, trace_id, user_i
 
       # Multiple filters combined
       onex logs product --level ERROR,WARNING --company-id comp123 --last 2h
+
+    \b
+    Invoke handler tracing (stream/schedule/event/s3 triggers):
+      # Every run of a specific invoke handler in the last 24h
+      onex logs automation --function invoice_automation_contract --last 24h
+
+      # Only the stream-triggered runs (e.g. contract updates)
+      onex logs automation --function invoice_automation_contract \\
+          --invocation-source stream --last 24h
+
+      # Only the manual (CLI/MCP) test runs that failed
+      onex logs automation --function invoice_automation_contract \\
+          --invocation-source manual --level ERROR --last 7d
+
+      # All scheduled (cron) invocations across a service
+      onex logs automation --invocation-source schedule --last 1h
     """
     from onex.config import get_active_environment
 
@@ -90,6 +112,10 @@ def logs(service_name, follow, lines, env, platform_url, level, trace_id, user_i
         params['method'] = method
     if event:
         params['event'] = event
+    if function_name:
+        params['function_name'] = function_name
+    if invocation_source:
+        params['invocation_source'] = invocation_source
     if grep:
         params['grep'] = grep
     if last:

{onex_cli-1.18.2 → onex_cli-1.19.0}/onex/mcp/server.py

@@ -678,6 +678,8 @@ async def onex_logs(
     path: str = None,
     method: str = None,
     event: str = None,
+    function_name: str = None,
+    invocation_source: str = None,
     grep: str = None,
     last: str = None
 ) -> str:
@@ -686,6 +688,10 @@ async def onex_logs(
     Fetches recent logs for a deployed service with advanced filtering options.
     Perfect for debugging specific issues, tracking user requests, and finding errors.
 
+    For invoke handlers triggered by non-HTTP sources (stream/schedule/event/s3),
+    use function_name + invocation_source to isolate those runs — they have no
+    URL path so path/method filters don't help.
+
     Args:
         service_name: Name of the service (e.g., 'email-service', 'product', 'auth')
         env: Environment (local/dev/staging/prod). Default: active environment
@@ -697,6 +703,11 @@ async def onex_logs(
         path: Filter by API path (e.g., "/auth/login")
         method: Filter by HTTP method (GET, POST, etc.)
         event: Filter by event type (service_ready, error, etc.)
+        function_name: Filter by invoke handler function name (e.g.
+            "invoice_automation_contract"). Matches the canonical
+            `function_name` field in shared-runtime / trigger logs.
+        invocation_source: Filter by WHY the handler ran. One of:
+            http, stream, event, schedule, s3, async_invoke, manual.
         grep: Search message with regex pattern
         last: Time range (e.g., "1h", "30m", "24h")
 
@@ -721,6 +732,20 @@ async def onex_logs(
 
         User: "Track user123's activity in the last 6 hours"
         → onex_logs(service_name="auth", user_id="user123", last="6h")
+
+        User: "Has my invoice_automation_contract handler run at all today?"
+        → onex_logs(service_name="automation",
+                    function_name="invoice_automation_contract",
+                    last="24h")
+
+        User: "Show me only the stream-triggered runs of invoice_automation_contract"
+        → onex_logs(service_name="automation",
+                    function_name="invoice_automation_contract",
+                    invocation_source="stream", last="24h")
+
+        User: "Did any scheduled jobs fail in the last hour?"
+        → onex_logs(service_name="automation",
+                    invocation_source="schedule", level="ERROR", last="1h")
     """
     if env is None:
         env = get_active_environment()
@@ -740,6 +765,11 @@ async def onex_logs(
         if trace_id:
             # Query across platform services, filter by trace_id in log line
             label_filters.append('service=~"gateway|shared-runtime|trigger-scheduler|event-bridge|stream-trigger|s3-trigger|deployment-controller"')
+        elif function_name or invocation_source:
+            # Invoke-handler mode: widen to include the trigger services so we
+            # also see the "stream_trigger_executing" / "schedule_trigger_executing"
+            # log lines emitted upstream of shared-runtime.
+            label_filters.append('service=~"shared-runtime|trigger-scheduler|event-bridge|stream-trigger|s3-trigger"')
         else:
             # Use container label + path filter for service isolation
             label_filters.append('container="shared-runtime"')
@@ -750,8 +780,11 @@ async def onex_logs(
         pipeline = []
         if trace_id:
             pipeline.append(f'|~ "{trace_id}"')
-        # Filter by service name via path prefix (e.g. /product/... or /manufacturing/...)
-        if not trace_id:
+        # Filter by service name via path prefix (e.g. /product/... or /manufacturing/...).
+        # Skip this when the caller is asking about invoke handlers by
+        # function_name / invocation_source — those lines have no URL path
+        # and would be filtered out incorrectly.
+        if not trace_id and not function_name and not invocation_source:
             pipeline.append(f'|~ "/{service_name}/"')
         if level:
             level_pattern = '|'.join(l.strip().lower() for l in level.split(','))
@@ -766,6 +799,16 @@ async def onex_logs(
             pipeline.append(f'|~ "{company_id}"')
         if event:
             pipeline.append(f'|~ "{event}"')
+        if function_name:
+            # Match the canonical JSON field in structured logs. Back-compat
+            # `function` field is still accepted during transition window.
+            pipeline.append(
+                f'|~ "\\"function_name\\":\\"{function_name}\\"|\\"function\\":\\"{function_name}\\""'
+            )
+        if invocation_source:
+            pipeline.append(
+                f'|~ "\\"invocation_source\\":\\"{invocation_source}\\""'
+            )
         if grep:
             pipeline.append(f'|~ "{grep}"')
 
@@ -873,6 +916,145 @@ async def onex_logs(
         return f"Error fetching logs: {e}"
 
 
+@mcp.tool()
+async def onex_executions(
+    function_name: Optional[str] = None,
+    invocation_source: Optional[str] = None,
+    status: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    last: Optional[str] = None,
+    limit: int = 20,
+    env: str = None,
+) -> str:
+    """List invoke handler execution history from invoke_executions.
+
+    This is the canonical "did my handler run, when, and why" view. It
+    covers EVERY invocation of a handler regardless of source: HTTP,
+    stream trigger, event, schedule, s3, async invoke, manual CLI. Backed
+    by MongoDB (invoke_executions collection) so it survives Loki log
+    retention.
+
+    Use this when log queries are timing out or when you need to answer
+    "has this handler ever run" over a long window. For the actual log
+    content of a specific run, follow up with onex_logs(trace_id=...) or
+    onex_trace(trace_id=...).
+
+    Args:
+        function_name: Filter by handler name (e.g.
+            "automation:invoice_automation_contract")
+        invocation_source: Filter by WHY the handler ran. One of:
+            http, stream, event, schedule, s3, async_invoke, manual.
+        status: Filter by execution status (pending, running, succeeded,
+            failed, retrying, dead_letter)
+        trace_id: Filter by trace ID
+        last: Time range (e.g., "1h", "24h", "7d")
+        limit: Max rows to return. Default: 20
+        env: Environment (local/dev/staging/prod). Default: active environment
+
+    Returns:
+        Compact table of executions with start time, status, invocation
+        source, duration, function name, and the invocation_detail
+        (the "why" — e.g. "contract/update/<doc_id>").
+
+    Examples:
+        User: "Has invoice_automation_contract actually run in the last day?"
+        → onex_executions(
+            function_name="automation:invoice_automation_contract",
+            last="24h"
+          )
+
+        User: "Show me only the stream-triggered runs of invoice_automation_contract in the last week"
+        → onex_executions(
+            function_name="automation:invoice_automation_contract",
+            invocation_source="stream", last="7d"
+          )
+
+        User: "Which manual test invokes failed for this handler?"
+        → onex_executions(
+            function_name="automation:invoice_automation_contract",
+            invocation_source="manual", status="failed", last="7d"
+          )
+
+        User: "Did any scheduled jobs fail in the last hour?"
+        → onex_executions(invocation_source="schedule", status="failed", last="1h")
+
+        User: "Everything tied to this trace"
+        → onex_executions(trace_id="abc-123-def")
+    """
+    if env is None:
+        env = get_active_environment()
+
+    platform_url = _get_platform_url(env)
+    url = f"{platform_url}/api/invoke/executions"
+
+    params = {'limit': limit}
+    if function_name:
+        params['function_name'] = function_name
+    if invocation_source:
+        params['invocation_source'] = invocation_source
+    if status:
+        params['status'] = status
+    if trace_id:
+        params['trace_id'] = trace_id
+    if last:
+        params['last'] = last
+
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            resp = await client.get(url, params=params)
+
+        if resp.status_code != 200:
+            return f"Executions query failed: HTTP {resp.status_code} - {resp.text[:200]}"
+
+        data = resp.json()
+        rows = data.get('executions', [])
+        total = data.get('total', 0)
+
+        if not rows:
+            filters_desc = []
+            if function_name:
+                filters_desc.append(f"function={function_name}")
+            if invocation_source:
+                filters_desc.append(f"source={invocation_source}")
+            if status:
+                filters_desc.append(f"status={status}")
+            if last:
+                filters_desc.append(f"last={last}")
+            filter_str = ", ".join(filters_desc) if filters_desc else "no filters"
+            return f"No executions found ({filter_str}). Total matching: {total}"
+
+        out = [f"Found {total} execution(s), showing {len(rows)}:\n"]
+        out.append(f"{'STARTED':<20} {'STATUS':<11} {'SOURCE':<13} {'MS':>8}  FUNCTION")
+        out.append("-" * 90)
+        for r in rows:
+            started = (r.get('started_at') or '')[:19].replace('T', ' ')
+            st = (r.get('status') or '?')[:11]
+            src = (r.get('invocation_source') or '-')[:13]
+            ms = r.get('execution_time_ms')
+            ms_str = f"{ms:8.0f}" if isinstance(ms, (int, float)) else "       -"
+            fname = r.get('function_name') or '-'
+            out.append(f"{started:<20} {st:<11} {src:<13} {ms_str}  {fname}")
+            detail = r.get('invocation_detail')
+            if detail:
+                out.append(f"  └─ {detail}")
+            err = r.get('error')
+            if err:
+                err_preview = err if len(err) < 150 else err[:147] + '...'
+                out.append(f"  ⚠  {err_preview}")
+            tid = r.get('trace_id')
+            if tid:
+                out.append(f"  trace_id: {tid}")
+
+        return "\n".join(out)
+
+    except httpx.ConnectError:
+        return f"Cannot connect to platform at {platform_url}"
+    except httpx.TimeoutException:
+        return "Executions query timed out"
+    except Exception as e:
+        return f"Error fetching executions: {e}"
+
+
 @mcp.tool()
 async def onex_status(
     service_name: Optional[str] = None,

{onex_cli-1.18.2 → onex_cli-1.19.0/onex_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onex-cli
-Version: 1.18.2
+Version: 1.19.0
 Summary: Official CLI for deploying and managing services on OneXEOS Platform (Windows, macOS, Linux)
 Home-page: https://github.com/onexeos/onex-cli
 Author: OneXEOS Platform Team

{onex_cli-1.18.2 → onex_cli-1.19.0}/onex_cli.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ onex/commands/deploy.py
 onex/commands/dev.py
 onex/commands/env.py
 onex/commands/es.py
+onex/commands/executions.py
 onex/commands/init.py
 onex/commands/invoke.py
 onex/commands/login.py

{onex_cli-1.18.2 → onex_cli-1.19.0}/tests/test_mcp_logs_e2e.py

@@ -15,7 +15,7 @@ import re
 import httpx
 import pytest
 
-from onex.mcp.server import onex_logs, _get_platform_url, _auth_headers
+from onex.mcp.server import onex_logs, onex_executions, _get_platform_url, _auth_headers
 
 
 # ---------------------------------------------------------------------------
@@ -47,11 +47,32 @@ class TestSignature:
         sig = inspect.signature(onex_logs)
         expected = [
             "service_name", "env", "lines", "level", "trace_id",
-            "user_id", "company_id", "path", "method", "event", "grep", "last",
+            "user_id", "company_id", "path", "method", "event",
+            "function_name", "invocation_source", "grep", "last",
         ]
         for param in expected:
             assert param in sig.parameters, f"Missing parameter: {param}"
 
+    def test_executions_signature(self):
+        """onex_executions exposes the expected filter parameters."""
+        sig = inspect.signature(onex_executions)
+        expected = [
+            "function_name", "invocation_source", "status",
+            "trace_id", "last", "limit", "env",
+        ]
+        for param in expected:
+            assert param in sig.parameters, f"Missing parameter: {param}"
+
+    def test_executions_docstring_has_examples(self):
+        """The tool description Claude sees must include usage examples."""
+        doc = onex_executions.__doc__ or ""
+        assert "invoice_automation_contract" in doc, (
+            "docstring should include the canonical stream-trigger example "
+            "so Claude picks up the pattern"
+        )
+        assert "invocation_source=\"stream\"" in doc
+        assert "invocation_source=\"schedule\"" in doc
+
 
 # ---------------------------------------------------------------------------
 # 2. Auth headers — sent on every request