@hue-run/sdk 0.3.2 → 0.4.2

package/dist/setup/source.js

@@ -0,0 +1,269 @@
+import { parse } from "@babel/parser";
+import { spawnSync } from "node:child_process";
+function node(value) {
+    return value && typeof value === "object" && typeof value.type === "string"
+        ? value
+        : undefined;
+}
+function nodes(value) {
+    return Array.isArray(value) ? value.flatMap((value) => (node(value) ? [node(value)] : [])) : [];
+}
+function identifier(value, name) {
+    const item = node(value);
+    return item?.type === "Identifier" && item.name === name;
+}
+function member(value, owner, name) {
+    const item = node(value);
+    return (item?.type === "MemberExpression" &&
+        item.computed === false &&
+        identifier(item.object, owner) &&
+        identifier(item.property, name));
+}
+function walk(value, visit, parent) {
+    if (Array.isArray(value))
+        for (const item of value)
+            walk(item, visit, parent);
+    else if (node(value)) {
+        visit(value, parent);
+        for (const [key, item] of Object.entries(value))
+            if (key !== "loc" && key !== "comments" && key !== "tokens")
+                walk(item, visit, value);
+    }
+}
+/** Syntax inspection only: no application imports, evaluation, or package lifecycle. */
+export function inspectExpressSource(source) {
+    const fail = () => new Error("Unsupported or ambiguous Express source/telemetry ownership");
+    const program = parse(source, { sourceType: "module", plugins: ["typescript"] }).program;
+    const body = program.body;
+    if (program.interpreter || program.directives.length)
+        throw fail();
+    const constructors = body.filter((item) => {
+        if (item.type !== "VariableDeclaration")
+            return false;
+        const declarations = nodes(item.declarations);
+        const call = node(declarations[0]?.init);
+        return (declarations.length === 1 &&
+            identifier(declarations[0]?.id, "app") &&
+            call?.type === "CallExpression" &&
+            identifier(call.callee, "express") &&
+            nodes(call.arguments).length === 0);
+    });
+    if (constructors.length !== 1 || constructors[0].end === undefined)
+        throw fail();
+    const imports = body.filter((item) => item.type === "ImportDeclaration");
+    if (!imports.some((item) => node(item.source)?.value === "express" &&
+        nodes(item.specifiers).some((specifier) => specifier.type === "ImportDefaultSpecifier" && identifier(specifier.local, "express"))))
+        throw fail();
+    for (const item of imports) {
+        const source = node(item.source)?.value;
+        if (source === "@opentelemetry/api" &&
+            nodes(item.specifiers).some((specifier) => specifier.type !== "ImportSpecifier" ||
+                !["trace", "SpanKind"].some((name) => identifier(specifier.imported, name))))
+            throw fail();
+        // Unknown bootstraps/import graphs could initialize a competing context manager.
+        if (typeof source !== "string" ||
+            !(source === "express" ||
+                source === "@opentelemetry/api" ||
+                ["node:fs", "node:fs/promises", "node:timers/promises", "node:stream"].includes(source)))
+            throw fail();
+    }
+    let routeCalls = 0;
+    let listenerCalls = 0;
+    walk(program, (item, parent) => {
+        // The one setup request traverses a private local proxy. Apps inspecting
+        // socket identity need manual integration so setup cannot alter their input.
+        if (["MemberExpression", "OptionalMemberExpression", "ObjectProperty"].includes(item.type) &&
+            ["socket", "connection"].some((name) => identifier(item.property ?? item.key, name) ||
+                node(item.property ?? item.key)?.value === name))
+            throw fail();
+        if (["process", "Number"].some((name) => identifier(item, name)) &&
+            ((parent?.type === "VariableDeclarator" && parent.id === item) ||
+                ((parent?.type === "FunctionDeclaration" || parent?.type === "ClassDeclaration") &&
+                    parent.id === item) ||
+                (Array.isArray(parent?.params) && parent.params.includes(item)) ||
+                (parent?.type.endsWith("Specifier") && parent.local === item) ||
+                (parent?.type === "ObjectProperty" && parent.value === item) ||
+                parent?.type === "ArrayPattern" ||
+                parent?.type === "RestElement" ||
+                (parent?.type === "AssignmentPattern" && parent.left === item) ||
+                (parent?.type === "AssignmentExpression" && parent.left === item) ||
+                (parent?.type === "UpdateExpression" && parent.argument === item)))
+            throw fail();
+        if (identifier(item, "app") &&
+            !((parent?.type === "VariableDeclarator" &&
+                parent.id === item &&
+                node(parent.init)?.type === "CallExpression" &&
+                identifier(node(parent.init)?.callee, "express")) ||
+                (parent?.type === "MemberExpression" && parent.object === item)))
+            throw fail();
+        if (item.type === "MemberExpression" &&
+            identifier(item.object, "app") &&
+            !(parent?.type === "CallExpression" &&
+                parent.callee === item &&
+                ["get", "listen"].some((name) => member(item, "app", name))))
+            throw fail();
+        if (item.type === "ExportAllDeclaration" ||
+            (item.type === "ExportNamedDeclaration" && item.source) ||
+            item.type === "TSImportEqualsDeclaration")
+            throw fail();
+        if ((item.type === "AssignmentExpression" && identifier(item.left, "app")) ||
+            (item.type === "UpdateExpression" && identifier(item.argument, "app")))
+            throw fail();
+        if (item.type === "CallExpression" &&
+            node(item.callee)?.type === "MemberExpression" &&
+            identifier(node(item.callee)?.object, "app") &&
+            !["get", "listen"].some((name) => member(item.callee, "app", name)))
+            throw fail();
+        if (item.type === "CallExpression" && member(item.callee, "app", "get"))
+            routeCalls++;
+        if (item.type === "CallExpression" && member(item.callee, "app", "listen"))
+            listenerCalls++;
+        if (item.type === "ImportExpression" ||
+            (item.type === "CallExpression" &&
+                (node(item.callee)?.type === "Import" ||
+                    identifier(item.callee, "require") ||
+                    identifier(item.callee, "eval"))))
+            throw fail();
+        if (item.type === "MemberExpression" &&
+            ["setGlobalContextManager", "disable", "register"].some((name) => identifier(item.property, name)))
+            throw fail();
+    });
+    const routes = body
+        .filter((item) => item.type === "ExpressionStatement")
+        .map((item) => node(item.expression))
+        .filter((item) => item?.type === "CallExpression" && member(item.callee, "app", "get"));
+    if (routes.length !== 1 || routeCalls !== 1 || routes[0].start <= constructors[0].end)
+        throw fail();
+    const arguments_ = nodes(routes[0].arguments);
+    if (arguments_.length !== 2 ||
+        arguments_[0].type !== "StringLiteral" ||
+        typeof arguments_[0].value !== "string")
+        throw fail();
+    const raw = arguments_[0].extra?.raw;
+    if (raw !== JSON.stringify(arguments_[0].value) && raw !== `'${arguments_[0].value}'`)
+        throw fail();
+    const handler = arguments_[1];
+    if (!["FunctionExpression", "ArrowFunctionExpression"].includes(handler.type) &&
+        !(handler.type === "Identifier" &&
+            body.some((item) => item.type === "FunctionDeclaration" && identifier(item.id, String(handler.name)))))
+        throw fail();
+    const listeners = body
+        .filter((item) => item.type === "ExpressionStatement")
+        .map((item) => node(item.expression))
+        .filter((item) => item?.type === "CallExpression" && member(item.callee, "app", "listen"));
+    if (listeners.length !== 1 || listenerCalls !== 1 || listeners[0].start <= routes[0].end)
+        throw fail();
+    const listenerArguments = nodes(listeners[0].arguments);
+    const portArgument = listenerArguments[0];
+    const port = portArgument?.type === "CallExpression" && identifier(portArgument.callee, "Number")
+        ? nodes(portArgument.arguments).length === 1
+            ? nodes(portArgument.arguments)[0]
+            : undefined
+        : portArgument;
+    if (listenerArguments.length !== 2 ||
+        port?.type !== "MemberExpression" ||
+        port.computed !== false ||
+        !member(port.object, "process", "env") ||
+        !identifier(port.property, "PORT") ||
+        listenerArguments[1]?.type !== "StringLiteral" ||
+        listenerArguments[1].value !== "127.0.0.1")
+        throw fail();
+    return {
+        constructorEnd: constructors[0].end,
+        importOffset: 0,
+        requestPath: arguments_[0].value,
+    };
+}
+const PYTHON_INSPECT = String.raw `
+import ast, json, sys
+source = sys.stdin.read()
+tree = ast.parse(source)
+compile(source, '<setup-static-inspection>', 'exec')
+parents = {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+lines = source.splitlines(keepends=True)
+def endline(item):
+    return sum(len(line.encode('utf-8')) for line in lines[:item.end_lineno])
+def name(item, value):
+    return isinstance(item, ast.Name) and item.id == value
+def member(item, owner, attr):
+    return isinstance(item, ast.Attribute) and name(item.value, owner) and item.attr == attr
+constructors = [item for item in tree.body if isinstance(item, ast.Assign) and len(item.targets) == 1 and name(item.targets[0], 'app') and isinstance(item.value, ast.Call) and name(item.value.func, 'Flask') and len(item.value.args) == 1 and name(item.value.args[0], '__name__') and not item.value.keywords]
+assert len(constructors) == 1
+for item in ast.walk(tree):
+    parent = parents.get(item)
+    if isinstance(item, ast.Attribute) and item.attr in ('socket', 'connection'):
+        raise AssertionError('Socket-aware applications require manual integration')
+    if isinstance(item, ast.Constant) and item.value == 'werkzeug.socket':
+        raise AssertionError('Socket-aware applications require manual integration')
+    if isinstance(item, ast.Name) and item.id in ('int', 'os') and isinstance(item.ctx, ast.Store):
+        raise AssertionError('Custom port conversion requires manual integration')
+    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and item.name in ('int', 'os'):
+        raise AssertionError('Custom port conversion requires manual integration')
+    if isinstance(item, ast.arg) and item.arg in ('int', 'os'):
+        raise AssertionError('Custom port conversion requires manual integration')
+    if isinstance(item, ast.alias):
+        bound = item.asname or item.name.split('.')[0]
+        if bound == 'int' or (bound == 'os' and not (isinstance(parent, ast.Import) and item.name == 'os')):
+            raise AssertionError('Custom port conversion requires manual integration')
+    if name(item, 'app'):
+        assert (parent is constructors[0] and item in parent.targets) or (isinstance(parent, ast.Attribute) and parent.value is item)
+    if isinstance(item, ast.Attribute) and name(item.value, 'app'):
+        assert isinstance(parent, ast.Call) and parent.func is item and item.attr in ('get', 'run')
+# Insertion after a statement's line must not cross another semicolon statement.
+assert all(left.end_lineno < right.lineno for left, right in zip(tree.body, tree.body[1:]))
+assert any(isinstance(item, ast.ImportFrom) and item.module == 'flask' and any(alias.name == 'Flask' and alias.asname in (None, 'Flask') for alias in item.names) for item in tree.body)
+routes = [(item, decorator) for item in tree.body if isinstance(item, ast.FunctionDef) for decorator in item.decorator_list if isinstance(decorator, ast.Call) and member(decorator.func, 'app', 'get')]
+all_routes = [item for item in ast.walk(tree) if isinstance(item, ast.Call) and member(item.func, 'app', 'get')]
+assert len(routes) == len(all_routes) == 1
+handler, route = routes[0]
+assert handler.decorator_list == [route]
+assert handler.lineno > constructors[0].end_lineno and len(route.args) == 1 and not route.keywords and isinstance(route.args[0], ast.Constant) and isinstance(route.args[0].value, str)
+assert ast.get_source_segment(source, route.args[0]) in (json.dumps(route.args[0].value), "'" + route.args[0].value + "'")
+listeners = [item for item in ast.walk(tree) if isinstance(item, ast.Call) and member(item.func, 'app', 'run')]
+assert len(listeners) == 1
+listener = listeners[0]
+statement = parents.get(listener)
+assert isinstance(statement, ast.Expr) and statement.value is listener and statement.lineno > handler.end_lineno
+owner = parents.get(statement)
+if owner is not tree:
+    assert isinstance(owner, ast.If) and parents.get(owner) is tree and owner.body == [statement] and not owner.orelse
+    condition = owner.test
+    assert isinstance(condition, ast.Compare) and name(condition.left, '__name__') and len(condition.ops) == 1 and isinstance(condition.ops[0], ast.Eq) and len(condition.comparators) == 1 and isinstance(condition.comparators[0], ast.Constant) and condition.comparators[0].value == '__main__'
+assert not listener.args and all(keyword.arg in ('host', 'port') for keyword in listener.keywords)
+keywords = {keyword.arg: keyword.value for keyword in listener.keywords}
+assert len(keywords) == len(listener.keywords) and 'port' in keywords
+if 'host' in keywords:
+    assert isinstance(keywords['host'], ast.Constant) and keywords['host'].value == '127.0.0.1'
+port = keywords['port']
+assert isinstance(port, ast.Call) and name(port.func, 'int') and len(port.args) == 1 and not port.keywords
+value = port.args[0]
+assert isinstance(value, ast.Subscript) and member(value.value, 'os', 'environ') and isinstance(value.slice, ast.Constant) and value.slice.value == 'PORT'
+assert any(isinstance(item, ast.Import) and any(alias.name == 'os' and alias.asname in (None, 'os') for alias in item.names) for item in tree.body)
+index = 0
+if tree.body and isinstance(tree.body[0], ast.Expr) and isinstance(tree.body[0].value, ast.Constant) and isinstance(tree.body[0].value.value, str): index = 1
+while index < len(tree.body) and isinstance(tree.body[index], ast.ImportFrom) and tree.body[index].module == '__future__': index += 1
+offset = endline(tree.body[index - 1]) if index else sum(len(line.encode('utf-8')) for line in lines[:tree.body[0].lineno - 1])
+print(json.dumps(dict(constructorEnd=endline(constructors[0]), importOffset=offset, requestPath=route.args[0].value)))
+`;
+/** An isolated stdlib parser never imports/executes the customer's Python module. */
+export function inspectFlaskSource(source) {
+    const result = spawnSync("python3", ["-I", "-B", "-S", "-c", PYTHON_INSPECT], {
+        input: source,
+        encoding: "utf8",
+        timeout: 5000,
+        maxBuffer: 8192,
+        shell: false,
+    });
+    if (result.status !== 0)
+        throw new Error("An isolated Python 3 parser and unambiguous Flask source are required");
+    const value = JSON.parse(result.stdout);
+    const bytes = Buffer.from(source);
+    for (const field of ["constructorEnd", "importOffset"]) {
+        if (!Number.isInteger(value[field]) || value[field] < 0 || value[field] > bytes.length)
+            throw new Error("Invalid Python source position");
+        value[field] = bytes.subarray(0, value[field]).toString("utf8").length;
+    }
+    if (typeof value.requestPath !== "string")
+        throw new Error("Invalid Python route");
+    return value;
+}

package/dist/setup/types.d.ts

@@ -1,7 +1,7 @@
 /** Version carried by every setup JSONL event. */
-export declare const SETUP_EVENT_CONTRACT_VERSION: 1;
+export declare const SETUP_EVENT_CONTRACT_VERSION: 2;
 /** Names in the version 1 setup event contract. */
-export type SetupEventName = "run.started" | "project.detected" | "plan.ready" | "step.started" | "step.completed" | "file.changed" | "diagnostic" | "action.required" | "trial.created" | "receipt.verified" | "claim.required" | "claim.completed" | "run.completed" | "run.failed";
+export type SetupEventName = "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" | "run.failed";
 interface EventBase<Name extends SetupEventName> {
     /** JSONL contract version, independent of the package version. */
     contractVersion: typeof SETUP_EVENT_CONTRACT_VERSION;
@@ -48,7 +48,7 @@ export interface ProjectDetectedEvent extends EventBase<"project.detected"> {
 /** A bounded local setup plan. */
 export interface SetupPlan {
     /** Ordered setup step names. */
-    steps: Array<"detect-project" | "configure-telemetry" | "verify-receipt" | "claim-project">;
+    steps: Array<"detect-project" | "install-runtime" | "configure-telemetry" | "verify-application-receipt" | "claim-project">;
     /** Whether this plan is permitted to change project files. */
     mutatesProject: boolean;
     /** Whether completion ultimately requires a backend adapter. */
@@ -87,16 +87,23 @@ export interface DiagnosticEvent extends EventBase<"diagnostic"> {
     /** Secret-free human-readable explanation. */
     message: string;
 }
+/** Published, non-blocking privacy and security disclosure shown before telemetry. */
+export interface PrivacyNoticeEvent extends EventBase<"privacy.notice"> {
+    /** Canonical privacy notice URL supplied by setup preflight. */
+    privacyUrl: "https://hue.run/privacy";
+    /** Published effective date supplied by setup preflight. */
+    effectiveDate: "2026-08-24";
+    /** Canonical security information URL supplied by setup preflight. */
+    securityUrl: "https://trust.hue.run/";
+}
 /** Progress needs an explicit local or human action. */
 export interface ActionRequiredEvent extends EventBase<"action.required"> {
     /** Kind of action needed to continue. */
-    action: "claim-project" | "configure" | "run-instrumented-request" | "open-claim-url" | "capture-approved-content" | "review-content-approved-trace";
+    action: "claim-project" | "configure" | "select-project" | "integrate-application" | "run-instrumented-request" | "open-claim-handoff" | "restart-claim-handoff";
     /** Secret-free explanation of the action. */
     message: string;
     /** Optional command the caller may run. */
     command?: string;
-    /** Optional HTTPS destination for a user action. */
-    url?: string;
 }
 /** A backend adapter created an anonymous trial. */
 export interface TrialCreatedEvent extends EventBase<"trial.created"> {
@@ -111,13 +118,13 @@ export interface ReceiptVerifiedEvent extends EventBase<"receipt.verified"> {
     receiptId: string;
     /** Verified lowercase OpenTelemetry trace identifier; this does not prove content approval. */
     traceId: string;
+    /** Repository-owned runtime boundary that produced the verified trace. */
+    source: "repository-http-boundary";
 }
 /** The anonymous project can be claimed by a person. */
 export interface ClaimRequiredEvent extends EventBase<"claim.required"> {
     /** Non-secret claim identifier. */
     claimId: string;
-    /** User-facing claim destination; never persisted in setup checkpoints. */
-    url: string;
 }
 /** A backend adapter confirmed that the project was claimed. */
 export interface ClaimCompletedEvent extends EventBase<"claim.completed"> {
@@ -141,5 +148,5 @@ export interface RunFailedEvent extends EventBase<"run.failed"> {
     resumable: boolean;
 }
 /** Version 1 setup JSONL event union. */
-export type SetupEvent = RunStartedEvent | ProjectDetectedEvent | PlanReadyEvent | StepStartedEvent | StepCompletedEvent | FileChangedEvent | DiagnosticEvent | ActionRequiredEvent | TrialCreatedEvent | ReceiptVerifiedEvent | ClaimRequiredEvent | ClaimCompletedEvent | RunCompletedEvent | RunFailedEvent;
+export type SetupEvent = RunStartedEvent | ProjectDetectedEvent | PlanReadyEvent | StepStartedEvent | StepCompletedEvent | FileChangedEvent | DiagnosticEvent | PrivacyNoticeEvent | ActionRequiredEvent | TrialCreatedEvent | ReceiptVerifiedEvent | ClaimRequiredEvent | ClaimCompletedEvent | RunCompletedEvent | RunFailedEvent;
 export {};

package/dist/setup/types.js

@@ -1,2 +1,2 @@
 /** Version carried by every setup JSONL event. */
-export const SETUP_EVENT_CONTRACT_VERSION = 1;
+export const SETUP_EVENT_CONTRACT_VERSION = 2;

package/dist/setup.d.ts

@@ -1,6 +1,10 @@
 /** Local, resumable installer setup-session contracts used by the `hue` command. */
-export { SETUP_EVENT_CONTRACT_VERSION, type ActionRequiredEvent, type ClaimCompletedEvent, type ClaimRequiredEvent, type DiagnosticEvent, type FileChangedEvent, type PlanReadyEvent, type ProjectDetectedEvent, type ReceiptVerifiedEvent, type RunCompletedEvent, type RunFailedEvent, type RunStartedEvent, type SetupEvent, type SetupEventName, type SetupPlan, type SetupProjectDetection, type StepCompletedEvent, type StepStartedEvent, type TrialCreatedEvent, } from "./setup/types.js";
+export { SETUP_EVENT_CONTRACT_VERSION, type ActionRequiredEvent, type ClaimCompletedEvent, type ClaimRequiredEvent, type DiagnosticEvent, type FileChangedEvent, type PlanReadyEvent, type PrivacyNoticeEvent, type ProjectDetectedEvent, type ReceiptVerifiedEvent, type RunCompletedEvent, type RunFailedEvent, type RunStartedEvent, type SetupEvent, type SetupEventName, type SetupPlan, type SetupProjectDetection, type StepCompletedEvent, type StepStartedEvent, type TrialCreatedEvent, } from "./setup/types.js";
 export { createInitialSetupState, transitionSetup, type SetupEffect, type SetupMachineInput, type SetupMachineState, type SetupTransition, } from "./setup/machine.js";
-export { runSetup, type SetupBackendAdapter, type SetupBackendClaim, type SetupBackendReceipt, type SetupBackendTrial, type SetupCheckpointAdapter, type SetupProjectAdapter, type SetupRunOptions, type SetupRunResult, } from "./setup/runner.js";
+export { runSetup, type SetupBackendOperations, type SetupCheckpointAdapter, type SetupProjectAdapter, type SetupRunOptions, type SetupRunResult, } from "./setup/runner.js";
+export { SetupBackendAdapter, SetupBackendError, type SetupBackendAdapterOptions, type SetupBackendClaim, type SetupApplicationEvidence, type SetupBackendReceipt, type SetupBackendTrial, type SetupCredentialResult, type SetupInstallationStatus, type SetupPreflightStatus, type SetupClaimHandoff, type SetupProbeEvidence, } from "./setup/backend.js";
+export { SetupApplicationActionRequired, installSetupRuntime, planSetupApplication, runSetupCommand, wireSetupApplication, type SetupApplicationPlan, type SetupCommand, type SetupCommandRunner, } from "./setup/application.js";
+export { type SetupFileChange } from "./setup/configure.js";
+export { FileSetupInstallationStore, type SetupInstallationRecord, type SetupStoredCredential, type SetupStoredApplicationEvidence, type SetupStoredApplicationAttempt, type SetupStoredClaimHandoff, type SetupStoredProbe, } from "./setup/installation.js";
 export { detectSetupProject } from "./setup/detect.js";
 export { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, type SetupOutputMode, } from "./setup/render.js";

package/dist/setup.js

@@ -2,5 +2,8 @@
 export { SETUP_EVENT_CONTRACT_VERSION, } from "./setup/types.js";
 export { createInitialSetupState, transitionSetup, } from "./setup/machine.js";
 export { runSetup, } from "./setup/runner.js";
+export { SetupBackendAdapter, SetupBackendError, } from "./setup/backend.js";
+export { SetupApplicationActionRequired, installSetupRuntime, planSetupApplication, runSetupCommand, wireSetupApplication, } from "./setup/application.js";
+export { FileSetupInstallationStore, } from "./setup/installation.js";
 export { detectSetupProject } from "./setup/detect.js";
 export { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, } from "./setup/render.js";

package/dist/types.d.ts

@@ -138,6 +138,30 @@ export interface SpanOptions {
     /** Explicit parent context, for example from {@link HueClient.extract}. */
     parentContext?: Context;
 }
+/**
+ * MCP `initialize` `serverInfo` for {@link HueClient.tool}. Pass
+ * `client.getServerVersion()` after connect; any MCP server works.
+ */
+export interface McpServerInfo {
+    /** `serverInfo.name` from MCP initialize, recorded as `mcp.server.name`. */
+    name?: string;
+    /** `serverInfo.version` from MCP initialize, recorded as `mcp.server.version`. */
+    version?: string;
+}
+/**
+ * Options for {@link HueClient.tool}. `callId` is the provider-issued tool-call
+ * id; `mcp` is the MCP server that handled the call.
+ */
+export interface ToolOptions extends Pick<SpanOptions, "parentContext"> {
+    /** Provider-issued identifier of this tool call, recorded as `gen_ai.tool.call.id`. */
+    callId?: string;
+    /**
+     * MCP server that handled this call. Pass `client.getServerVersion()` or the
+     * `initialize` `serverInfo` so a generic verb such as `get_thread` is attributed
+     * to that server rather than inferred from the tool name.
+     */
+    mcp?: McpServerInfo;
+}
 /** Provider-reported token counts for {@link HueSpan.setUsage}. */
 export interface TokenUsage {
     /** Provider-reported prompt tokens (`gen_ai.usage.input_tokens`). */

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.3.2";
+export declare const sdkVersion = "0.4.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.3.2";
+export const sdkVersion = "0.4.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -84,6 +84,7 @@
     "test": "bun test tests"
   },
   "dependencies": {
+    "@babel/parser": "7.29.9",
     "@opentelemetry/api-logs": "0.222.0",
     "@opentelemetry/core": "2.11.0",
     "@opentelemetry/otlp-exporter-base": "0.222.0",

package/setup-events.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hue.run/schemas/setup-events-v1.json",
-  "title": "Hue setup-session installer event version 1",
+  "$id": "https://hue.run/schemas/setup-events-v2.json",
+  "title": "Hue setup-session installer event version 2",
   "description": "Installer lifecycle events only. run.* events are setup-session invocations, not Hue Runs.",
   "oneOf": [
     { "$ref": "#/$defs/run.started" },
@@ -11,6 +11,7 @@
     { "$ref": "#/$defs/step.completed" },
     { "$ref": "#/$defs/file.changed" },
     { "$ref": "#/$defs/diagnostic" },
+    { "$ref": "#/$defs/privacy.notice" },
     { "$ref": "#/$defs/action.required" },
     { "$ref": "#/$defs/trial.created" },
     { "$ref": "#/$defs/receipt.verified" },
@@ -24,14 +25,14 @@
       "type": "object",
       "required": ["contractVersion", "event", "runId", "sequence", "timestamp"],
       "properties": {
-        "contractVersion": { "const": 1 },
+        "contractVersion": { "const": 2 },
         "event": { "type": "string", "maxLength": 40 },
         "runId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" },
         "sequence": { "type": "integer", "minimum": 1, "maximum": 10000 },
         "timestamp": { "type": "string", "format": "date-time", "maxLength": 40 }
       }
     },
-    "step": { "enum": ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"] },
+    "step": { "enum": ["detect-project", "install-runtime", "configure-telemetry", "verify-application-receipt", "claim-project"] },
     "text": { "type": "string", "minLength": 1, "maxLength": 1000 },
     "identifier": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" },
     "plan": {
@@ -93,26 +94,32 @@
       "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["level", "code", "message"], "properties": { "event": { "const": "diagnostic" }, "level": { "enum": ["info", "warning", "error"] }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$" }, "message": { "$ref": "#/$defs/text" } } }],
       "unevaluatedProperties": false
     },
+    "privacy.notice": {
+      "type": "object",
+      "description": "Published privacy and security disclosure presented before telemetry; no acknowledgement or consent is inferred.",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["privacyUrl", "effectiveDate", "securityUrl"], "properties": { "event": { "const": "privacy.notice" }, "privacyUrl": { "const": "https://hue.run/privacy" }, "effectiveDate": { "const": "2026-08-24" }, "securityUrl": { "const": "https://trust.hue.run/" } } }],
+      "unevaluatedProperties": false
+    },
     "action.required": {
       "type": "object",
-      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["action", "message"], "properties": { "event": { "const": "action.required" }, "action": { "enum": ["claim-project", "configure", "run-instrumented-request", "open-claim-url", "capture-approved-content", "review-content-approved-trace"] }, "message": { "$ref": "#/$defs/text" }, "command": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } } }],
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["action", "message"], "properties": { "event": { "const": "action.required" }, "action": { "enum": ["claim-project", "configure", "select-project", "integrate-application", "run-instrumented-request", "open-claim-handoff", "restart-claim-handoff"] }, "message": { "$ref": "#/$defs/text" }, "command": { "type": "string", "minLength": 1, "maxLength": 200 } } }],
       "unevaluatedProperties": false
     },
     "trial.created": {
       "type": "object",
-      "description": "An anonymous setup trial hard-pinned to trial_metadata_v1.",
+      "description": "An anonymous setup trial restricted to metadata-only-v1.",
       "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["trialId", "expiresAt"], "properties": { "event": { "const": "trial.created" }, "trialId": { "$ref": "#/$defs/identifier" }, "expiresAt": { "type": "string", "format": "date-time", "maxLength": 40 } } }],
       "unevaluatedProperties": false
     },
     "receipt.verified": {
       "type": "object",
-      "description": "Instrumentation-only proof for an anonymous trace; not evidence of content approval or Scenario suitability.",
-      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["receiptId", "traceId"], "properties": { "event": { "const": "receipt.verified" }, "receiptId": { "$ref": "#/$defs/identifier" }, "traceId": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } }],
+      "description": "Exact stored trace/span evidence from the exercised repository HTTP boundary; does not establish that every application operation is instrumented.",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["receiptId", "traceId", "source"], "properties": { "event": { "const": "receipt.verified" }, "receiptId": { "$ref": "#/$defs/identifier" }, "traceId": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "source": { "const": "repository-http-boundary" } } }],
       "unevaluatedProperties": false
     },
     "claim.required": {
       "type": "object",
-      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["claimId", "url"], "properties": { "event": { "const": "claim.required" }, "claimId": { "$ref": "#/$defs/identifier" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } } }],
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["claimId"], "properties": { "event": { "const": "claim.required" }, "claimId": { "$ref": "#/$defs/identifier" } } }],
       "unevaluatedProperties": false
     },
     "claim.completed": {