@hue-run/sdk 0.3.2 → 0.4.1

package/CLI.md

@@ -1,52 +1,275 @@
-# Hue setup-session CLI contract
+# Hue setup CLI
 
-The local setup-session CLI core shipped in TypeScript `0.3.1` and is available from npm:
+The local setup-session CLI core shipped in TypeScript `0.3.1`. TypeScript `0.4.0` is an unreleased,
+activation-gated candidate for the real one-command flow:
 
 ```sh
-hue setup
-hue setup --agent
-hue resume
-hue status
-hue claim # reports account attachment unavailable in this local core
+npx --yes @hue-run/sdk@latest setup --agent
+# Default Terminal mode, when a person is present:
+npx @hue-run/sdk@latest setup
 ```
 
-These commands belong only to an installer setup session. They do not create or launch a Hue Run,
-Scenario, evaluation, or worker. `claim` only means attaching the anonymous setup project to an
-account; there is no generic `connect` command or local-agent connection in this CLI.
-
-`setup` only inspects bounded manifest and lockfile metadata. It does not execute repository code,
-change project files, open a browser, ask a question, create a trial, or contact Hue. `claim` also
-makes no network request in this build and reports that account attachment is unavailable. `resume`
-deterministically continues the same setup-session checkpoint; `status` reads it without changing
-it.
-
-Checkpoints are secret-free JSON files outside the project, under the operating system's user state
-directory. On POSIX, directories use mode `0700` and files use mode `0600`; Windows uses its
-per-user local state directory without interpreting POSIX mode bits. Writes are atomic, and a
-configured state location inside the project is rejected. Checkpoints contain project categories
-and hashes, never environment values, credentials, source contents, or claim URLs.
-
-`--agent` is explicitly noninteractive JSONL. It never uses ANSI, stdin, or a browser, and each
-invocation emits exactly one terminal `run.completed` or `run.failed` installer event. Those names
-describe the setup-session lifecycle, not a Hue Run. Human output is an append-only inline
-transcript. Plain and JSONL output contain no ANSI; `NO_COLOR`, `TERM=dumb`, CI, and non-TTY output
-select plain mode automatically.
-
-Every JSONL record carries `contractVersion: 1`. The TypeScript union is exported from
-`@hue-run/sdk/setup`; the JSON Schema is exported as
-`@hue-run/sdk/setup-events.schema.json`. Consumers must ignore neither unknown versions nor terminal
-failures.
-
-The future Fern implementation plugs into `SetupBackendAdapter`. Its three installer operations
-create an anonymous setup trial hard-pinned to `trial_metadata_v1`, verify instrumentation-only
-receipt evidence, and read account-claim state. Inputs carry deterministic idempotency keys and an
-optional abort signal. Adapter results must use bounded, non-secret IDs; claim URLs may be sensitive
-and therefore must never be checkpointed. Receipt verification does not prove that task or
-environment content was captured and must never authorize Scenario publication. The adapter must
-not create a Scenario, evaluation, worker, or Hue Run. No live implementation ships in this slice.
-
-The V1 handoff is deliberately staged: setup verifies the anonymous instrumentation trace; `hue claim`
-preserves the project and trace history; then the user performs an explicit content-approved capture
-or rerun, with a prepared tester as the first golden path. Only that content-approved trace passes to
-the separate review/publication flow for a Scenario. The actual URL and that handoff contract remain
-deferred. Setup itself does not capture content, create, publish, or run a Scenario.
+These public commands are not working onboarding promises until candidate publication, Fern
+activation, production acceptance and `latest` promotion all pass. The automatic matrix is limited
+to Express with npm, Express with Bun, and Flask with uv in a single application package with one recognizable
+entrypoint, a literal existing GET route and `PORT` supplied by the environment. The command uses the
+detected manager to install an exact runtime, inserts two owned middleware marker blocks without
+rewriting business logic, starts that exact entrypoint without a shell, authenticates its loopback
+socket before sending HTTP, makes one request on that same socket, flushes, and verifies its exact trace/span receipt.
+A delayed listener, failing handler, missing telemetry or receipt failure never authorizes replay of
+business work. A setup probe is separate transport evidence and cannot establish application
+instrumentation.
+
+Workspace roots, mixed languages/managers, custom Hue versions, edited marker blocks, unfamiliar
+entrypoints and ambiguous routes stop with `action.required`. Follow its specific local action and
+rerun the same installation; select the intended application package with `--project` when needed.
+Setup does not choose a monorepo package or silently broaden its supported shapes. Preserve the
+application's business logic when completing an integration manually.
+
+The bounded fixture contract is ESM JavaScript/TypeScript Express with `const app = express();`,
+one literal `app.get(...)`, an environment-selected listen port, and a start script containing only
+`node path/to/server.mjs` (or `.js`, `.ts`, `.mts`) or `bun path/to/server.mjs`. A Bun start script
+requires the Bun manager. Plain JavaScript does not need a TypeScript dependency. Flask uses root
+`app.py`, `app = Flask(__name__)`, one literal `@app.get(...)` and a port read from
+`os.environ["PORT"]`. Routes cannot contain network-path prefixes, escapes or dynamic segments.
+JavaScript/TypeScript shebang/BOM entrypoints require manual integration. Python UTF-8/ASCII
+shebang, encoding, comments, module docstring (including parenthesized forms) and future imports
+are preserved using an isolated stdlib Python 3 syntax parser. Other encodings and ambiguous
+statement layouts are refused. Package roots nested in an npm/Bun workspace or beneath any Python
+project manifest are refused because managers can update ancestor locks; Python build-system/custom-source projects are also outside this matrix.
+`uv` uses binary-only dependency installation and starts with no implicit sync/build.
+
+The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
+`capture_content=False`. For a supported application, setup installs the dependency and adds the
+managed import and middleware registration to the existing entrypoint; an unreferenced helper is
+not a completed integration. TypeScript uses `@hue-run/sdk@0.4.1`, `@opentelemetry/api@1.9.1` and
+`@opentelemetry/context-async-hooks@2.11.0`; Python uses `hue-run==0.2.2`.
+Content capture requires an ordinary account-managed key and a later explicit application decision.
+
+The generated bootstrap supplies standard active SERVER-span context across asynchronous/streaming
+handlers; the core SDK's global-provider/context ownership is unchanged. It preserves a working
+caller context manager and disposes only its own instance. Unknown local imports, custom/late manager
+bootstraps, runtime preloads and conflicting OTel dependencies require manual review before any
+mutation or provisioning. Automatic Express entrypoints import only Express, the standard OTel API,
+or the supported `node:fs`, `node:fs/promises`, `node:timers/promises` and `node:stream` modules.
+Syntax parsing, not matches inside comments/strings/templates/regular expressions, establishes the
+constructor and literal route. Custom middleware, alternate route methods, app aliases/escapes and
+extra Flask handler decorators are outside the automatic matrix. The one selected request must finish with a 2xx response; a 404 or
+telemetry failure never authorizes a business retry.
+
+Bun runtime checks and application launch use an explicit empty config and disable dotenv loading.
+Local runtime/preload settings, dotenv files and a global `.bunfig.toml` require manual review before
+any Bun invocation. The only supported local `bunfig.toml` is an `[install]` section with one
+credential-free registry origin for package installation; this does not become runtime config.
+
+Automatic Express listeners must be the single top-level
+`app.listen(Number(process.env.PORT), "127.0.0.1")` (the direct `process.env.PORT` argument
+is also recognized). Flask permits only `app.run(port=int(os.environ["PORT"]))`, optionally
+with `host="127.0.0.1"`, at module level or under the usual main guard. Custom callbacks,
+server handles, socket metadata access, reloaders, workers and listener options require manual
+integration. Flask dotenv/runtime bootstrap configuration also requires review.
+Before dependency or credential changes, an isolated compile-only check validates the selected
+Node/Bun entrypoint without executing it; Node-unsupported TypeScript syntax is refused.
+
+During this setup-owned invocation only, a bounded server-first proof authenticates the retained
+loopback connection. HTTP uses that exact socket once, with no redirect, redial or retry. Express
+uses a private inner listener and a one-connection forwarding listener; Flask uses its standard
+request-handler seam. The per-attempt secret stays in memory/private child transport, never in
+events, checkpoints or receipts. Ordinary app starts have no handshake and retain their original
+listener behavior. This prevents accidental requests to an unrelated listener, not access by
+malicious code running as the same local user.
+
+Setup creates no Scenario, Hue Run, evaluation, source capture, worker or remote execution. Package
+manager lifecycle scripts are disabled. The supported existing application entrypoint is executed
+directly with fixed argv solely for its bounded local HTTP verification; no shell command is accepted.
+
+## Technical preflight and privacy disclosure
+
+Read-only project detection and conflict checks precede project mutation. Public
+`GET /api/v1/setup/preflight` reports `available` or `inactive`, `metadata-only-v1`, trial limits and
+lifetime, and the published privacy and security information. An inactive deployment remains
+unverified. An available deployment proceeds through runtime installation, private installation and
+credential provisioning, managed application wiring, one application request and exact receipt
+verification.
+
+Before telemetry, `privacy.notice` presents `https://hue.run/privacy`, effective date `2026-08-24`,
+and `https://trust.hue.run/`. This is a non-blocking disclosure. Setup has no acceptance step or
+acceptance fields and does not infer a person's acknowledgement. It does not invent notice content.
+
+The anonymous ingestion window is 24 hours with lifetime limits of 100 traces, 1,000 spans and 2 MiB
+of sanitized stored data. Unclaimed data is purged seven days after expiry. Claim preserves the
+project and its data; the setup-issued replacement key remains metadata-only.
+
+## Commands and modes
+
+```sh
+hue setup                 # provision/configure/verify, then prepare a private owner handoff
+hue resume                # continue the same project/origin installation
+hue status                # read status; after claim, reconcile generation 1 if necessary
+hue claim                 # open the owner-only handoff, or reconcile after browser claim
+hue claim --restart       # explicit owner recovery; requires an interactive local terminal
+hue setup --agent         # noninteractive version-2 JSONL events
+hue setup --format human  # explicit append-only terminal rendering
+hue setup --origin http://127.0.0.1:PORT # isolated loopback tests only
+```
+
+Hosted setup accepts HTTPS origins only. HTTP is accepted solely for `localhost`, `127.0.0.1` and
+`[::1]` test origins. Origins with credentials, paths, queries or fragments are refused, and
+redirects are never followed.
+
+`--agent` never reads stdin or opens a browser. It emits exactly one terminal `run.completed` or
+`run.failed` event and only a generic owner action. No setup mode prints a bearer claim URL or token.
+The CLI saves the capability in an ignored owner-only local handoff and human Terminal mode opens
+only that local file; the browser consumes the short-lived one-time capability. A repository-reading
+agent can read local project files, so this boundary prevents durable transcript/log disclosure, not
+a malicious local process. The browser owns the claim cookie; the CLI never reads it. After claim
+completes, rerun `hue claim` or `hue status` to fetch credential generation 1, atomically replace the
+locally managed key, verify the preserved original receipt and confirm the old key receives `401`.
+The superseded key is retained only in private managed state until that check succeeds, so an
+interruption does not lose the revocation check. Reconciliation does not replay the application
+request or require a second one.
+
+A pending handoff expires after at most ten minutes and is exchanged once for a distinct browser
+session lasting at most thirty minutes; both deadlines are bounded by trial expiry. Status polling
+never creates or rotates a handoff. Retrying or reopening a pending handoff keeps its original ID
+and expiry; a consumed handoff with an active browser session remains intact. Only the owner can
+explicitly replace an expired or lost handoff with `hue claim --restart`; this persists a new ID and
+uses the observed predecessor for compare-and-swap. A conflict refreshes status once and stops.
+At most 32 distinct handoff IDs exist per installation; `SETUP_HANDOFF_LIMIT` is terminal. Replacing a
+handoff does not create a trial, reset quota or rerun business work.
+
+## Local state and conflicts
+
+Before its first network write, setup creates a lowercase UUIDv4 and a 32-byte random installation
+secret. They live with the current telemetry credential in `.hue/installation-<origin-hash>.json`.
+The file is added to `.gitignore`, written atomically with mode `0600`, and scoped to this exact
+project and Hue origin. A pending browser capability is stored only in
+`.hue/claim-handoff-<origin-hash>.html`, also ignored and mode `0600`; `.hue` uses mode `0700`.
+Setup rejects symlinks, unsafe paths, oversized or invalid state, custom files at its managed config
+paths, and unexpected edits to files it previously managed. It preserves unrelated `.gitignore`,
+manifests, lockfiles and project files.
+
+Secret-free checkpoints remain in the operating system's per-user state directory and support
+interruption/resume. Claim capabilities never enter checkpoints or public events. Credential retries are idempotent; a lost
+credential response is recovered by asking for the same generation. `SETUP_CHANGED` triggers one
+status refresh. `SETUP_REVOKED`, expired/purged installations, custom credential conflicts and
+exhausted lifetime quota fail closed instead of silently replacing an installation or key.
+
+Commands serialize all origins for one canonical project and reload current state under that lock.
+Every invocation re-detects current manifests, managers and managed blocks before mutation. Normal
+interruptions release the lock; after a forcible process kill, the owner must inspect the stale
+non-secret lock under canonical `/tmp` on Linux/macOS
+(`hue-setup-locks-<uid>/<sha256(canonical-project-root)>`) and remove only that lock after confirming
+no setup command remains active. Its location does not depend on `TMPDIR`, `HOME` or state-directory
+overrides; project aliases and different Hue origins share ownership. Other operating systems fail
+closed for automatic setup. Setup never breaks an unexplained lock automatically or retries
+business work.
+
+Both setup credential generations use exactly
+`^hue_setup_(live|test)_setup-([a-f0-9]{24})_([A-Za-z0-9_-]{43})$`, with `keyId` equal to
+`setup-` plus the token's 24-character identifier, fixed kind `anonymous_trial`, and the sole
+capability `setup_telemetry_write`.
+Normal project credentials and unknown token shapes are refused in setup responses and private
+managed state. These credentials authorize metadata-only OTLP at `/api/v1/otlp/v1/traces` and exact
+content-free receipt verification at `/api/v1/setup/traces/{traceId}/receipt`. They do not authorize
+generic project, receipt, evaluation, log or browsing APIs. Python `0.2.2` can export with the setup
+credential; the CLI verifies the dedicated setup receipt instead of Python's generic receipt helper.
+
+Each command uses bounded timeouts and retries. Provisioning records at most five attempts per local
+installation in an hour and makes at most two attempts in one invocation; the live service's stricter
+per-network admission remains authoritative. Receipt polling honors the SDK's bounded deadline and
+`Retry-After`. A missing or late receipt is reported as resumable and unverified, never as success.
+
+The TypeScript event union is exported from `@hue-run/sdk/setup`; its JSON Schema is exported as
+`@hue-run/sdk/setup-events.schema.json`. Event `run.*` names describe only CLI invocations, not Hue
+Runs.
+
+## Public machine events and actions
+
+Events carry `contractVersion: 2`, a non-secret invocation ID, sequence and timestamp. The closed
+event set is `run.started`, `project.detected`, `plan.ready`, `step.started`, `step.completed`,
+`file.changed`, `diagnostic`, `privacy.notice`, `action.required`, `trial.created`,
+`receipt.verified`, `claim.required`, `claim.completed`, `run.completed` and `run.failed`.
+
+Event version 1 shipped in TypeScript `0.3.1` and `0.3.2`; its public claim URL, action set and receipt
+step are incompatible with this flow. The v2 schema shipped in TypeScript `0.4.0` with identity
+`https://hue.run/schemas/setup-events-v2.json`. Event version 2 is independent of Setup HTTP
+`protocolVersion: 1` and the checkpoint format.
+
+`privacy.notice` has only `privacyUrl`, `effectiveDate` and `securityUrl` beyond the event envelope,
+with the literal values above. `receipt.verified` carries non-secret `receiptId`, `traceId` and
+`source: "repository-http-boundary"`. It confirms the exercised application boundary and every
+expected span, positive stored span count, empty missing IDs and absent input/output content.
+It does not establish instrumentation of unexercised application paths. `claim.required` and
+`claim.completed` carry only the non-secret `claimId`; neither contains a URL or capability.
+
+The closed `action.required.action` set is:
+
+| Action | Caller response |
+| --- | --- |
+| `claim-project` | Defer account linkage to the project owner. |
+| `configure` | Resolve the reported availability or managed-configuration issue. |
+| `select-project` | Select one supported application package explicitly with `--project`. |
+| `integrate-application` | Resolve the reported unsupported or ambiguous integration safely. |
+| `run-instrumented-request` | Inspect the prior attempt and missing evidence; do not automatically replay business work. |
+| `open-claim-handoff` | Ask the owner to run `hue claim` in an interactive local terminal. |
+| `restart-claim-handoff` | Ask the owner to explicitly run `hue claim --restart` if recovery is needed. |
+
+A coding agent follows the non-secret message and optional command, reports unverified steps, and
+leaves browser account linkage for the human. It must not read or copy the private handoff into a
+transcript. `run.completed` with `action_required` is a successful pause, not proof that all setup
+steps completed. `claim.completed` requires reconciliation and the retained evidence checks.
+
+## Staging/live acceptance runner
+
+Fern owns hosted acceptance and its private browser/inbox orchestration. SDK verification builds and
+retains the exact tarball; it does not spend a live admission or claim hosted success. The Fern job
+first accepts the reviewed PR archive, then after merge downloads the exact `publish=false` Release
+SDK archive without repacking and repeats acceptance. It uses two persistent installations and at
+most four provisioning admissions. Local compatibility fixtures do not spend hosted admissions.
+
+The local/manual diagnostic runner accepts an already prepared supported application fixture. Its `--language`
+scaffolding does not create such an application, and its human-output option does not allocate a PTY.
+It records CLI outcomes, not independent original-handler span binding or server evidence. It always
+exits nonzero: exit `2` means the diagnostic finished but acceptance remains unverified; malformed
+events, private output and child failures also fail closed. Even a valid version-2 application receipt
+event followed by `ready` cannot make this runner an acceptance gate. Do not use it to authorize a
+release, count it as hosted acceptance, or suppress its exit code in a release gate:
+
+```sh
+node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifacts/typescript
+# Set project to an existing supported fixture; use the same directory on resume.
+project=/absolute/path/to/supported-fixture
+node packages/sdk-typescript/scripts/verify-setup-live.mjs \
+  --archive .artifacts/typescript/hue-run-sdk-0.4.1.tgz \
+  --origin https://STAGING_ORIGIN \
+  --project "$project" --command setup \
+  --evidence .context/setup-staging-before-claim.json
+```
+
+After the approved backend is available, run `hue claim` from an interactive owner terminal to open
+the private local handoff and finish the real browser claim, then reconcile the same project:
+
+```sh
+node packages/sdk-typescript/scripts/verify-setup-live.mjs \
+  --archive .artifacts/typescript/hue-run-sdk-0.4.1.tgz \
+  --origin https://STAGING_ORIGIN \
+  --project "$project" --command claim \
+  --evidence .context/setup-staging-after-claim.json
+```
+
+Repeat from an existing supported Flask/uv fixture when that diagnostic pass is budgeted. Evidence files explicitly
+record `purpose: "diagnostic-only"`, `independentlyVerifiedApplication: false` and `accepted: false`,
+with the archive hash, bounded event names and terminal outcome—never the claim capability, installation proof,
+telemetry key, cookie, verification URL, project path or trace/span IDs. The runner installs and
+executes the exact tarball; it does not establish hosted acceptance, registry publication or
+production activation.
+
+Hosted acceptance separately executes installed Express/npm, Express/Bun and Flask/uv fixture
+coverage, with Agent JSONL and a real default-mode PTY. It independently verifies exact stored IDs,
+the privacy disclosure, one handler invocation, verified-account adoption and owner transfer,
+preserved project/data, replacement receipt access and old-key `401`. Browser orchestration opens
+only the private local file and produces no secret-bearing screenshots, traces, logs or artifacts.
+Publication under a candidate dist-tag, registry acceptance, production activation, promotion of
+the same version to `latest`, and clean-project literal `@latest` smoke remain separate gates; see
+[RELEASING.md](../../RELEASING.md).

package/ENVIRONMENTS.md

@@ -161,6 +161,16 @@ await tools.refund_charge!.execute({ charge_id: "ch_2" });
 await client.finishRun(run.id, { idempotencyKey: randomUUID(), status: "completed" });
 ```
 
+Each bound call is an ordinary `hue.tool` span. When the catalog names an MCP server, the span
+also carries `mcp.server.name`. Wrap any MCP client the same way, using `serverInfo` from
+`initialize` — this is not specific to Hue-hosted Gmail or Slack:
+
+```ts
+await hue.tool(name, args, () => client.callTool({ name, arguments: args }), {
+  mcp: client.getServerVersion(),
+});
+```
+
 An observation with `status: "error"` is a recorded world answer, not a transport exception.
 Run mutations retry with stable invocation/idempotency identities. Registry writes do not retry
 automatically because identity creation and publication have no request key.

package/README.md

@@ -65,6 +65,18 @@ HTTPS is required except for loopback HTTP or the explicit
 [`allowInsecureHttp`](#local-development-without-a-hue-account) opt-in. Redirects are refused for both
 project checks and exports.
 
+The setup CLI shipped in TypeScript `0.4.0` also prepares the `hue` executable. The unreleased
+`npx --yes @hue-run/sdk@latest setup --agent` path supports Express with npm, Express with Bun, and
+Flask with uv in one application package with an unambiguous entrypoint and existing GET route. It
+installs the runtime, wires the application, makes one request and verifies that request's exact
+trace/span receipt. Unsupported or ambiguous repositories receive a structured action. Technical
+preflight checks availability and presents the published [privacy notice](https://hue.run/privacy)
+and [security information](https://trust.hue.run/) before telemetry. Anonymous trials last 24 hours
+and are limited to 100 traces, 1,000 spans and 2 MiB. A private owner-only browser handoff supports
+account linkage; the original request evidence is retained and business work is never replayed on
+claim. Setup never enables content capture or creates a Scenario, Hue Run, evaluation, source capture
+or remote execution. See the [setup CLI contract](./CLI.md) for the supported shapes and release gates.
+
 `checkConnection()` rejects with `HueConnectionError`: its fixed message is safe to log, `status`
 carries the HTTP status when Hue answered, and `cause` carries the underlying network, timeout or
 parsing error. `serviceVersion` and `resourceAttributes` (for example
@@ -120,7 +132,10 @@ options come after the callback and also accept `name`, `sessionId`, `userId`, `
 nonnegative integer `gen_ai.usage.input_tokens` / `output_tokens`; other values are omitted and
 counted as instrumentation failures. Unknown usage stays absent. `hue.tool(name, input, execute)`
 creates an `execute_tool {name}` span with `gen_ai.tool.name`, arguments and result; an optional
-fourth argument `{ callId }` records the provider's tool call id as `gen_ai.tool.call.id`. Content
+fourth argument `{ callId }` records the provider's tool call id as `gen_ai.tool.call.id`. When the
+tool came from an MCP server, pass `{ mcp: client.getServerVersion() }` (the MCP `initialize`
+`serverInfo`) to record `mcp.server.name` and `mcp.server.version` so a generic verb such as
+`get_thread` is attributed to that server. Content
 helpers (`setInput`, `setOutput`, `tool` arguments and results, `recordMessages`,
 `SpanOptions.input`) accept any value and encode plain JSON data (`JsonValue`) at runtime; a value
 that is not JSON, such as a `Date` or a class instance, is omitted with an instrumentation failure
@@ -412,8 +427,9 @@ Scorer deferral shipped in TypeScript `0.3.1`. Only built-ins
 and bound `local_code` callbacks run here; other pins remain pending for their authorized executor.
 See [scorer execution](EVALUATIONS.md#hosted-and-manual-scorer-pins).
 
-The [setup CLI](CLI.md) is a resumable local inspection core. Existing customers connect their
-agents with `runLocalAgent()`; setup does not register workers or launch Scenarios.
+The published [setup CLI](CLI.md) is a resumable local inspection core; the unreleased `0.4.0`
+candidate adds the bounded application onboarding flow described above. Existing customers connect
+their agents with `runLocalAgent()`; setup does not register workers or launch Scenarios.
 
 ## Managed targets
 

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type Context, type Span, type Tracer } from "@opentelemetry/api";
 import { HueTransport } from "./transport.js";
-import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, ModelOptions, ProjectConnection, SpanOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
+import type { ExportReport, FlushableLoggerProvider, FlushableTracerProvider, HueOptions, HueSpan, ModelOptions, ProjectConnection, SpanOptions, ToolOptions, VerifyTraceOptions, TraceVerification, SafeLifecycleOptions, SafeLifecycleResult } from "./types.js";
 /**
  * Attach mode: the application owns its OpenTelemetry providers and passes the transport whose
  * processors it attached to them. The client flushes these providers but never shuts them down.
@@ -73,11 +73,11 @@ export declare class HueClient {
      * are recorded as `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` when `captureContent`
      * is true; values that are not JSON-encodable are omitted with an instrumentation failure.
      * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
+     * `options.mcp` records the MCP `initialize` `serverInfo` as `mcp.server.name` /
+     * `mcp.server.version` so a generic tool name can be attributed to the server that
+     * handled it. Pass `client.getServerVersion()`.
      */
-    tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: Pick<SpanOptions, "parentContext"> & {
-        /** Provider-issued identifier of this tool call, recorded as `gen_ai.tool.call.id`. */
-        callId?: string;
-    }): Promise<T>;
+    tool<T>(name: string, input: unknown, execute: () => Promise<T> | T, options?: ToolOptions): Promise<T>;
     /**
      * Runs `callback` inside a GenAI client span for one direct provider call, named
      * `{operation} {model}` unless `options.name` is given and carrying `gen_ai.operation.name`,

package/dist/client.js

@@ -298,20 +298,27 @@ export class HueClient {
      * are recorded as `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` when `captureContent`
      * is true; values that are not JSON-encodable are omitted with an instrumentation failure.
      * `options.callId` is recorded as `gen_ai.tool.call.id`, like the Python `call_id=` keyword.
+     * `options.mcp` records the MCP `initialize` `serverInfo` as `mcp.server.name` /
+     * `mcp.server.version` so a generic tool name can be attributed to the server that
+     * handled it. Pass `client.getServerVersion()`.
      */
     async tool(name, input, execute, options = {}) {
         const attributes = {
             "gen_ai.operation.name": "execute_tool",
             "gen_ai.tool.name": name,
         };
-        const callId = options.callId;
-        if (callId !== undefined) {
-            // A blank or non-string id is omitted and counted; the tool call itself still runs.
-            if (isLabel(callId))
-                attributes["gen_ai.tool.call.id"] = callId;
+        const stamp = (key, value) => {
+            if (value === undefined)
+                return;
+            // A blank or non-string label is omitted and counted; the tool call itself still runs.
+            if (isLabel(value))
+                attributes[key] = value;
             else if (this.enabled && !this.closed)
                 this.transport.instrumentationFailure();
-        }
+        };
+        stamp("gen_ai.tool.call.id", options.callId);
+        stamp("mcp.server.name", options.mcp?.name);
+        stamp("mcp.server.version", options.mcp?.version);
         return this.withSpan(`execute_tool ${name}`, async ({ span }) => {
             this.setContent(span, "gen_ai.tool.call.arguments", input);
             const result = await execute();

package/dist/environment/tools.d.ts

@@ -26,5 +26,10 @@ export interface BindEnvironmentToolsOptions {
     /** Optional durable invocation-ID factory for caller-owned resume state. */
     invocationId?(action: string): string;
 }
-/** Binds a run's generated catalog to plain local callables without changing the agent framework. */
+/**
+ * Binds a run's generated catalog to plain local callables without changing the agent
+ * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` so a generic verb is
+ * attributed to that MCP server.
+ */
 export declare function bindEnvironmentTools(options: BindEnvironmentToolsOptions): Record<string, EnvironmentTool>;

package/dist/environment/tools.js

@@ -1,5 +1,10 @@
 import { randomUUID } from "node:crypto";
-/** Binds a run's generated catalog to plain local callables without changing the agent framework. */
+/**
+ * Binds a run's generated catalog to plain local callables without changing the agent
+ * framework. Each call is recorded through {@link HueClient.tool}. Catalog entries that
+ * include `mcp` stamp `mcp.server.name` / `mcp.server.version` so a generic verb is
+ * attributed to that MCP server.
+ */
 export function bindEnvironmentTools(options) {
     const tools = {};
     for (const action of options.run.actions) {
@@ -16,6 +21,7 @@ export function bindEnvironmentTools(options) {
                 })).observation;
                 return options.hue.tool(action.name, args, execute, {
                     parentContext: options.parentContext,
+                    ...(action.mcp === undefined ? {} : { mcp: action.mcp }),
                 });
             },
         };

package/dist/environment/types.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue } from "../types.js";
+import type { JsonValue, McpServerInfo } from "../types.js";
 export type { JsonValue } from "../types.js";
 /** Human-readable identity used when creating an environment. */
 export interface EnvironmentIdentity {
@@ -251,6 +251,11 @@ export interface ActionDefinition {
     description?: string;
     /** Generated input contract. */
     inputSchema: ActionSchema;
+    /**
+     * MCP `initialize` identity when this action is served by one MCP surface.
+     * Bound environment tools record it on the tool span as `mcp.server.name`.
+     */
+    mcp?: McpServerInfo;
 }
 /** Recorded answer returned by the simulated world. */
 export interface Observation {

package/dist/receipt.js

@@ -31,7 +31,7 @@ function validId(value, length) {
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function parseReceipt(value, traceId, expected, origin) {
+function parseReceipt(value, traceId, expected, origin, setup = false) {
     if (!record(value) ||
         value.traceId !== traceId ||
         !Number.isSafeInteger(value.spanCount) ||
@@ -52,6 +52,24 @@ function parseReceipt(value, traceId, expected, origin) {
     }
     if (traceUrl.origin !== origin || traceUrl.username || traceUrl.password)
         invalidResponse();
+    if (setup) {
+        const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+        if (traceUrl.href !== value.traceUrl ||
+            traceUrl.hash ||
+            !traceUrl.pathname.startsWith("/traces/") ||
+            !uuid.test(traceUrl.pathname.slice(8)))
+            invalidResponse();
+        const queryNames = [];
+        traceUrl.searchParams.forEach((value, name) => {
+            if (!["projectId", "organizationId"].includes(name) ||
+                queryNames.includes(name) ||
+                !uuid.test(value))
+                invalidResponse();
+            queryNames.push(name);
+        });
+        if (queryNames.length !== 2)
+            invalidResponse();
+    }
     const matched = value.matchedSpanIds, missing = value.missingSpanIds;
     if (!Array.isArray(matched) ||
         !Array.isArray(missing) ||
@@ -128,6 +146,13 @@ async function pause(milliseconds, signal) {
 }
 /** Observe persisted evidence after the application and its exporter have finished. */
 export async function verifyTrace(connection, traceId, options = {}) {
+    return verifyTraceAtPath(connection, traceId, options, false, fetch);
+}
+/** @internal Dedicated receipt path for setup credentials; ordinary clients stay unchanged. */
+export async function verifySetupTrace(connection, traceId, options, fetcher, signal) {
+    return verifyTraceAtPath(connection, traceId, options, true, fetcher, signal);
+}
+async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, signal) {
     if (!validId(traceId, 32))
         throw new TypeError("traceId must be a nonzero lowercase 32-character OpenTelemetry trace ID");
     if (options === null || typeof options !== "object" || Array.isArray(options))
@@ -148,27 +173,28 @@ export async function verifyTrace(connection, traceId, options = {}) {
         throw new TypeError("timeoutMillis must be greater than zero and at most 60000");
     // Snapshot caller arrays so concurrent mutation cannot alter the verification criteria.
     const expectedIds = [...expected], requiredFields = [...required];
-    const url = new URL(`/api/v1/traces/${traceId}/receipt`, connection.baseUrl);
+    const url = new URL(`/api/v1/${setup ? "setup/" : ""}traces/${traceId}/receipt`, connection.baseUrl);
     for (const id of expectedIds)
         url.searchParams.append("expectedSpanId", id);
     const controller = new AbortController();
     const deadline = performance.now() + timeout;
     const timer = setTimeout(() => controller.abort(), timeout);
+    const requestSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     let receipt = null;
     let delay = 250;
     try {
-        while (!controller.signal.aborted && performance.now() < deadline) {
-            const response = await fetch(url, {
+        while (!requestSignal.aborted && performance.now() < deadline) {
+            const response = await fetcher(url, {
                 headers: { Authorization: `Bearer ${connection.apiKey}`, Accept: "application/json" },
                 redirect: "manual",
                 credentials: "omit",
                 cache: "no-store",
-                signal: controller.signal,
+                signal: requestSignal,
             });
             let retryAfter = 0;
             if (response.status === 200) {
-                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin);
-                if (!controller.signal.aborted &&
+                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin, setup);
+                if (!requestSignal.aborted &&
                     performance.now() < deadline &&
                     receipt.missingSpanIds.length === 0 &&
                     requiredFields.every((field) => receipt.fields[field]))
@@ -195,7 +221,7 @@ export async function verifyTrace(connection, traceId, options = {}) {
             if (remaining <= 0)
                 break;
             const wait = Math.max(delay, retryAfter);
-            await pause(Math.min(wait, remaining), controller.signal);
+            await pause(Math.min(wait, remaining), requestSignal);
             // A truncated backoff exhausts this call even if a timer wakes just early.
             if (wait >= remaining)
                 break;
@@ -203,6 +229,8 @@ export async function verifyTrace(connection, traceId, options = {}) {
         }
     }
     catch (error) {
+        if (signal?.aborted)
+            throw new Error("Setup interrupted");
         if (!controller.signal.aborted && performance.now() < deadline) {
             if (error instanceof HueTraceVerificationError)
                 throw error;