@tomflow/chatloop-tools

Tools is the single private MCP Gateway and local Supervisor for Chat Loop. The installed SDK and its CLI entrypoints are stable; tool capabilities are independently assembled at build time, not detected from arbitrary runtime files, registry URLs, or user-supplied executable paths.

Public entrypoints

• npm SDK: index.mjs exposes loadToolsCli() and runToolsSupervisor().
• npm executable: bin/cli.mjs, command chatloop-tools.
• Private process entry: bin/supervisor.mjs; not another npm executable.
• MCP stdio: chatloop-tools mcp.

Run chatloop-tools --help, chatloop-tools capabilities, or chatloop-tools doctor for the installed commands and local readiness. Doctor does not verify ChatGPT authorization, Chrome Owner, or deployment.

chatloop-tools api-usage 60 asks the existing local Supervisor for the last 60 minutes of recorded MCP, Tools SDK/CLI, Extension/Native, Trace SDK and platform Tunnel SDK API calls. With an exact authorized Context Project grant it also aggregates that Project's sanitized context.api events. Counts, success, failure, incomplete calls and calls per minute are grouped by named entrypoint and deduplicated by call/span ID; unmatched completions are reported separately. Nested calls share a soft traceId and retain unique spanId/parentSpanId, including a sanitized MCP-to-Context-CLI parent handoff. It never starts a Supervisor, opens a browser, replays a call, or reads model inputs. The Trace writer stores only safe API identity, call ID, phase, time and bounded duration/error code; Context logs remain Project-scoped. Browser dispatch is only listener acceptance, not an authenticated user click or successful ChatGPT action. These rates are API invocation rates, not UI click-through rates. This is best-effort telemetry, not proof that every standalone package invocation reached the Supervisor; without a verified running Supervisor it returns BLOCKED, not invented data. npm run check verifies generated six-package AOP copies and all published callable SDK facades (the gate reports its live count), while Context's 34 declared methods and MCP Provider catalog have separate capability tests. Internal Trace Writer health/record operations are excluded from re-submitting themselves to prevent recursive logs. Non-authoritative process/control logs use a bounded async queue, with drops and pending counts visible in Supervisor Trace health.

Usage: chatloop-tools <command> [target]
Commands: doctor, mcp, start, stop, restart, status, upgrade, tunnel, capabilities, api-usage
Run: chatloop-tools <command> --help

Usage: chatloop-tools start [desktop-commander|tunnel]
Start all enabled tools or one.

Capability composition

providers/<id>.mjs owns each MCP Provider's tool names, schemas, activation condition, scoped call adapter and optional CLI commands.

The five built-in Providers are:

• desktop: allowlisted Desktop Commander tools and isolated fixtures
• extension: official pinned Extension CLI and nine scoped actions
• runtime: exact-request receipt lookup without replay
• context: independent Context SDK read/write schemas and fixed CLI
• trace: Project-scoped diagnosis and SOFT stage observations

npm run build:providers generates providers.generated.mjs, the static assembly and release fingerprint manifest. Both tools/list and tools/call use a single lib/mcp-tool-router.mjs instance. lib/gateway.mjs handles MCP framing only; it knows no individual Provider. There is no parallel hand-maintained API inventory or runtime plugin directory scan.

lib/cli-command-router.mjs also recognizes additional CLI commands owned by Providers, without another central command branch.

Add a tool or CLI command

1. Create providers/<id>.mjs with a provider export: unique id and names, plus create(services) returning tools() and call(name,args). An optional commands list can declare name, help and run({args,api}) returning {exitCode,result}. A CLI-only Provider may set names:[] and omit create() entirely; it does not need a fake MCP tool or adapter.
2. Build: npm run build:providers.
3. Verify: npm run build:providers:check, npm test and workspace npm run check.

The compiler rejects duplicate tool and command identities, missing implementations, and attempts to shadow built-in CLI names. At runtime unregistered, undeclared and disabled tools fail closed as UNKNOWN_TOOL. test/provider-composition.test.mjs demonstrates adding and removing a sixth isolated Provider with an MCP tool and CLI command, with no edits to any existing Provider, the Gateway, or either npm entrypoint.

Authority and lifecycle

• Desktop Commander publishes only the reviewed 21 tools, regardless of upstream vendor additions. GUI Terminal launches remain prohibited.
• Context enforces Project authorization, CAS, Store epochs, and durable request receipts. Tools does not own a second task database.
• Extension alone controls browser Owner and actual ChatGPT Action sends.
• Supervisor alone owns child-process lifecycle, serialization, unknown side-effect receipts and the single Trace writer.
• Trace observations and logging never authorize business writes or trigger retries of unknown effects. In particular, verified Extension MCP results are returned before optional Trace transport finishes; a slow, rejecting or unavailable observer cannot replace the action receipt. These events are best-effort evidence, not an all-API AOP coverage claim.

No legacy Task Registry MCP or JSON fallback is shipped. Historical SourceUnit files remain migration evidence, not alternate current facts.

Local validation and packaging

• npm test runs isolated package and Gateway regression tests.
• Workspace npm run check verifies API boundaries, source syntax, documentation links, and both Context/Tools generated compositions.
• Workspace npm run pack:tools -- <existing-output-directory> produces an offline, version-pinned Tools tarball containing the declared Context and Trace SDKs plus their verified runtime dependency closure (ps-list and @tomflow/chatloop-extension for the current Context SDK). Release tests must cold-install the tarball and actually load Context's Local Operator; checking filenames or importing only the SDK root is insufficient. The build checks the provider manifest before packaging. Release staging uses the candidate package's own generated Provider manifest and fingerprints every Tools-owned source file, including new Provider helpers; missing, substituted, or added files block activation before Owner handoff.
• chatloop-tools upgrade prepare <absolute-tarball.tgz> <sha256> and chatloop-tools upgrade activate <sha256> are separate authorized steps.

Source tests and a release tarball do not prove npm publication, an installed Supervisor upgrade, private MCP activation or real Chrome E2E. Check the installed version and authoritative runtime evidence separately.