Embedding Example

The TypeScript embedding example in examples/embedding/typescript demonstrates the SDK host shape without requiring the hosted console.

Flow

1. Create an SDK client with a marketplace client, local auth store, signing verifier, and host-provided CodeModeCore.
2. Search the marketplace for a capability.
3. Inspect module docs, permissions, auth metadata, generated MiniGo API, and CodeMode ABI.
4. Install and pin a module version.
5. Download and verify the signed integration.
6. Persist provider auth locally through the host AuthStore.
7. Register the verified install envelope with the SDK.
8. Check MiniGo CodeMode orchestration with the injected core.
9. Execute MiniGo CodeMode through the injected core and module actions through host-owned runtime code.
10. Fulfill module host calls through the embedding application's local hostCallHandler.
11. Return structured output, logs, metrics, and errors to the embedding app.

Run

npm --workspace @invoketool/example-embedding-typescript run typecheck
npm --workspace @invoketool/example-embedding-typescript run demo
npm --workspace @invoketool/example-embedding-typescript run acceptance-demo

The example is intentionally local-first: it shows that a product can build an embedded marketplace and execution experience without redirecting users to the hosted InvokeTool UI for provider auth. Provider tokens are written to the local AuthStore and read back only through the SDK host-call handler; they are not sent to InvokeTool marketplace or integration download APIs.

Deployed Acceptance Smoke

Before using live credentials, run the local mock harness for the same deployed smoke script:

npm run acceptance:deployed:smoke:test

This starts a local mock InvokeTool API, serves a signed integration module and install envelope, executes the deployed smoke script unchanged, and checks integration verification, WASM execution, usage telemetry, persisted usage polling, and provider-token leak assertions. It is regression coverage for the smoke script, not final acceptance evidence.

After deploying apps/api, applying D1 migrations, configuring Better Auth and Dodo secrets, and creating a console API key scoped to the target organization with project:read, module:read, and module:install, run the deployed smoke harness against the real API. The variable names are also listed in examples/embedding/typescript/.env.example; replace every placeholder value before running the deployed command. INVOKETOOL_API_URL must be the deployed HTTPS API origin, without a path, query string, fragment, or embedded URL credentials. If INVOKETOOL_ACCEPTANCE_MODULE_ID is set, it must be a module ID containing only letters, numbers, dots, underscores, or dashes. If INVOKETOOL_ACCEPTANCE_QUERY is set, it must be a non-empty real marketplace search query, not a placeholder. The preflight and smoke auto-load examples/embedding/typescript/.env when it exists, without overriding already-exported shell variables. To load a different local secrets file, export INVOKETOOL_ACCEPTANCE_ENV_FILE with an absolute path; preflight and direct smoke invocation report an explicit failure if that file is missing. The embedding app's agent must provide the MiniGo CodeMode snippet to INVOKETOOL_AGENT_CODEMODE_SNIPPET_PATH; that snippet must define func Run, call github_to_slack_create_issue_and_notify unless the module override changes the acceptance module, and return IssueUrl plus Notified. The checked-in examples/embedding/typescript/agent-acceptance-snippet.mgo sample documents the expected shape for the default github_to_slack module, but final acceptance should point at the fresh file produced by the embedding app's agent using an absolute path:

INVOKETOOL_API_URL="$DEPLOYED_INVOKETOOL_API_URL" \
INVOKETOOL_API_KEY="$DEPLOYED_INVOKETOOL_API_KEY" \
INVOKETOOL_ORG_ID="$DEPLOYED_INVOKETOOL_ORG_ID" \
INVOKETOOL_SIGNING_SECRET="$DEPLOYED_INVOKETOOL_SIGNING_SECRET" \
INVOKETOOL_AGENT_CODEMODE_SNIPPET_PATH="$ABSOLUTE_PATH_TO_AGENT_AUTHORED_MINIGO_SNIPPET" \
npm run acceptance:deployed:preflight

set -o pipefail
INVOKETOOL_API_URL="$DEPLOYED_INVOKETOOL_API_URL" \
INVOKETOOL_API_KEY="$DEPLOYED_INVOKETOOL_API_KEY" \
INVOKETOOL_ORG_ID="$DEPLOYED_INVOKETOOL_ORG_ID" \
INVOKETOOL_SIGNING_SECRET="$DEPLOYED_INVOKETOOL_SIGNING_SECRET" \
INVOKETOOL_AGENT_CODEMODE_SNIPPET_PATH="$ABSOLUTE_PATH_TO_AGENT_AUTHORED_MINIGO_SNIPPET" \
npm run acceptance:deployed | tee deployed-smoke-output.json

npm run acceptance:deployed runs the same preflight first and stops before network calls when required values are missing, malformed, or still set to template placeholders, when the API URL is not a deployed HTTPS origin, or when the snippet file is unreadable, missing func Run, or missing the generated <module_id>_<action_id> extern call. Optional provider-token variables should be left unset unless they contain real local test values; placeholder optional-token values are rejected too.

The smoke harness searches the hosted marketplace, inspects docs, auth metadata, permissions, generated MiniGo API, CodeMode ABI, and extern snapshots, reads the protected integration descriptor with module:read, pins the module with module:install, confirms the installed-module list and available-update query, reads Dodo-backed billing state, usage, integration-download history, and persisted execution history, and asserts that any provider-token environment variables were not sent to InvokeTool APIs. By default it also downloads the install envelope through the hosted API client, verifies it with the SDK, executes MiniGo CodeMode through the injected core, emits local runtime evidence, and verifies provider credentials remain local. Do not set INVOKETOOL_SKIP_RUNTIME_ACCEPTANCE=1; the preflight and smoke intentionally fail in skip mode because final acceptance requires runtime execution evidence.

After the deployed smoke passes, export acceptance evidence from the console and compare it with the smoke output:

set -o pipefail
npm run acceptance:deployed | tee deployed-smoke-output.json
npm run acceptance:deployed:evidence -- deployed-smoke-output.json invoketool-acceptance-org.json

The smoke output file may include npm script headers and preflight output before the final JSON object. Keep the full captured file; the evidence verifier extracts the deployed smoke JSON from it. The console export downloads as invoketool-acceptance-<organization_id>.json; use that downloaded path as the second verifier argument, or rename it to match the example command.

The verifier checks that the API-key organization metadata and module read/install permissions, non-secret API-key inventory identity, Dodo customer/subscription billing state, organization-scoped usage counters, module install/pin/update-check lifecycle evidence, installed module, install history, explicit runtime_acceptance_enabled: true evidence, HTTP(S) issue_url plus notified runtime results, persisted execution history, SDK telemetry, and provider credential leak evidence agree across both outputs. It also recursively rejects console exports that include API key material.