@tangle-network/agent-provider-cli-bridge 2.0.2 → 2.0.4

package/dist/sandbox/refusal.js

@@ -0,0 +1,159 @@
+import { harnessSystemPromptIntents, } from "@tangle-network/agent-interface";
+import { EnvironmentProviderError } from "@tangle-network/agent-interface/environment-provider";
+import { materializeProfile } from "@tangle-network/agent-profile-materialize";
+import { harnessModelSupportFor } from "@tangle-network/cli-agent-registry";
+import { BOX_HARNESSES, boxHarness } from "./box.js";
+/** A profile axis no workspace control enforces here, with the reason it is refused. */
+const REFUSED_PROFILE_AXES = [
+    { path: "profile.confidential", present: (p) => p.confidential !== undefined, reason: "confidential execution needs placement and attestation this provider does not offer" },
+    { path: "profile.seats", present: (p) => p.seats !== undefined, reason: "an ordered subscription chain is not implemented; this provider runs one Router-routed model" },
+    { path: "profile.connections", present: (p) => (p.connections?.length ?? 0) > 0, reason: "connections must be resolved to MCP servers before create" },
+    { path: "profile.proxySecrets", present: (p) => p.proxySecrets !== undefined, reason: "proxy-held credentials are not supported" },
+    { path: "profile.resources.knowledge", present: (p) => Array.isArray(Reflect.get(p.resources ?? {}, "knowledge")) && Reflect.get(p.resources ?? {}, "knowledge").length > 0, reason: "knowledge must be resolved by the runtime before materialization" },
+    { path: "profile.model.maxVisibleOutputTokens", present: (p) => p.model?.maxVisibleOutputTokens !== undefined, reason: "no workspace control enforces an output token cap" },
+    { path: "profile.model.maxReasoningTokens", present: (p) => p.model?.maxReasoningTokens !== undefined, reason: "no workspace control enforces a reasoning token cap" },
+    { path: "profile.model.maxTotalOutputTokens", present: (p) => p.model?.maxTotalOutputTokens !== undefined, reason: "no workspace control enforces a total output token cap" },
+    { path: "profile.extensions", present: (p) => Object.values(p.extensions ?? {}).some((value) => value !== undefined), reason: "no backend extension namespace is implemented" },
+];
+function metadataCredentialSource(profile) {
+    const metadata = profile.model?.metadata;
+    return metadata !== null && typeof metadata === "object" ? metadata.credentialSource : undefined;
+}
+/** The harness a request selects, or the refusal that names why none can be. */
+export function resolveBoxHarness(profile, backend, declared) {
+    const selected = profile.harness ?? backend;
+    if (selected === undefined) {
+        throw new EnvironmentProviderError("refused", "a profile or backend must name a harness; a prompt is never run as a shell command", { path: "profile.harness" });
+    }
+    if (profile.harness !== undefined && backend !== undefined && profile.harness !== backend) {
+        throw new EnvironmentProviderError("refused", `backend ${backend} conflicts with profile.harness ${profile.harness}`, { path: "backend" });
+    }
+    if (!declared.includes(selected) || boxHarness(selected) === undefined) {
+        throw new EnvironmentProviderError("refused", `harness ${selected} is not in this provider's declared set (${declared.join(", ")})`, { path: backend === undefined ? "profile.harness" : "backend" });
+    }
+    return selected;
+}
+/**
+ * Validate a profile against what the box can run, without any sandbox call.
+ *
+ * It plans with the same materializer the Bridge in the box uses, so a
+ * dimension the planner cannot lower is refused here with its own reason.
+ */
+export function validateBoxProfile(profile, backend, declared) {
+    const issues = [];
+    const error = (code, path, message) => {
+        issues.push({ level: "error", code, path, message });
+    };
+    let harness;
+    try {
+        harness = resolveBoxHarness(profile, backend, declared);
+    }
+    catch (caught) {
+        const refusal = caught;
+        error("harness_refused", refusal.path ?? "profile.harness", refusal.message);
+    }
+    for (const axis of REFUSED_PROFILE_AXES) {
+        if (axis.present(profile))
+            error("axis_refused", axis.path, axis.reason);
+    }
+    if (metadataCredentialSource(profile) === "subscription") {
+        error("subscription_refused", "profile.model.metadata.credentialSource", "subscription credentials are not delivered into a cloud box; the model routes through the Router, and a subscription profile is never run on a managed key");
+    }
+    if (harness !== undefined) {
+        const intents = harnessSystemPromptIntents(harness);
+        if (profile.prompt?.systemPrompt !== undefined && !intents.replace)
+            error("system_prompt_refused", "profile.prompt.systemPrompt", `${harness} cannot replace its system prompt`);
+        if (profile.prompt?.appendSystemPrompt !== undefined && !intents.append)
+            error("system_prompt_refused", "profile.prompt.appendSystemPrompt", `${harness} cannot append to its system prompt`);
+        const model = profile.model?.default;
+        if (model !== undefined) {
+            const support = harnessModelSupportFor(harness, { provider: profile.model?.provider, model });
+            if (!support.supported)
+                error("model_refused", "profile.model.default", support.message);
+        }
+        try {
+            const plan = materializeProfile(profile, harness);
+            for (const entry of plan.unsupported)
+                error("unsupported", `profile.${entry.dimension}`, entry.reason);
+        }
+        catch (caught) {
+            error("materialization_refused", "profile", caught instanceof Error ? caught.message : String(caught));
+        }
+    }
+    return { ok: !issues.some((issue) => issue.level === "error"), issues };
+}
+/** Throw the first refusal of a validation result as a typed error that names its path. */
+export function assertProfileValid(result) {
+    const first = result.issues.find((issue) => issue.level === "error");
+    if (first !== undefined) {
+        throw new EnvironmentProviderError("refused", first.message, { ...(first.path === undefined ? {} : { path: first.path }) });
+    }
+}
+/**
+ * Refuse every create-input field this provider cannot honor, before any
+ * vendor call. A field is never accepted and dropped.
+ */
+export function refuseUnsupportedCreateInput(input, support) {
+    const refuse = (path, message) => {
+        throw new EnvironmentProviderError("refused", message, { path });
+    };
+    if (typeof input.profile === "string")
+        refuse("profile", `named profile ${input.profile} is unsupported; pass an inline AgentProfile`);
+    if (input.requestedId !== undefined)
+        refuse("requestedId", "the vendor issues sandbox ids");
+    if (input.runtimeAttachments !== undefined)
+        refuse("runtimeAttachments", "runtime MCP attachments are not supported");
+    if (input.idempotencyKey !== undefined)
+        refuse("idempotencyKey", "durable keyed create is not implemented");
+    if (input.billingOwner !== undefined)
+        refuse("billingOwner", "billing owners are not supported");
+    if (input.secrets !== undefined)
+        refuse("secrets", "secrets are not supported; pass env");
+    if (input.proxySecrets !== undefined)
+        refuse("proxySecrets", "proxy secrets are not supported");
+    if (input.proxySecretParents !== undefined)
+        refuse("proxySecretParents", "proxy secret parents are not supported");
+    if (input.providerOptions !== undefined && Object.keys(input.providerOptions).length > 0)
+        refuse("providerOptions", "no provider option is implemented");
+    const workspace = input.workspace;
+    if (workspace !== undefined) {
+        if (workspace.snapshot !== undefined)
+            refuse("workspace.snapshot", "workspace snapshots are not supported");
+        if (workspace.checkpoint !== undefined)
+            refuse("workspace.checkpoint", "workspace checkpoints are not supported");
+        if (workspace.cwd?.base === "host")
+            refuse("workspace.cwd", "a host cwd is refused; use base \"repository\"");
+        if (workspace.providerOptions !== undefined && Object.keys(workspace.providerOptions).length > 0)
+            refuse("workspace.providerOptions", "no workspace provider option is implemented");
+        if (workspace.environment !== undefined && workspace.image !== undefined)
+            refuse("workspace.image", "workspace cannot specify both environment and image");
+        if (workspace.environment !== undefined && !support.environment)
+            refuse("workspace.environment", "this vendor selects no template or snapshot");
+        if (workspace.image !== undefined && !support.image)
+            refuse("workspace.image", "this vendor selects no image");
+    }
+    if (input.resources !== undefined) {
+        if (!support.resources)
+            refuse("resources", "this vendor sets no resources at create");
+        if (input.resources.providerOptions !== undefined)
+            refuse("resources.providerOptions", "no resource provider option is implemented");
+    }
+    if (input.egress !== undefined && !support.egress.includes(input.egress.mode)) {
+        refuse("egress", `egress mode ${input.egress.mode} is not enforced by this vendor`);
+    }
+}
+/** The harnesses this module can declare. */
+export function declarableHarnesses() {
+    return Object.keys(BOX_HARNESSES);
+}
+/** Whether the shared planner lowers this profile dimension for the harness. */
+export function plannerLowers(harness, dimension) {
+    const probe = { hooks: { PostToolUse: [{ command: "true" }] } };
+    try {
+        const plan = materializeProfile(probe, harness);
+        return !plan.unsupported.some((entry) => entry.dimension === dimension);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sandbox/vendor.d.ts

@@ -0,0 +1,105 @@
+import type { AgentEnvironmentEgressMode, AgentEnvironmentStatus, ExecRequest, ExecResult, ResourceRequest } from "@tangle-network/agent-interface/environment-provider";
+/**
+ * What a cloud sandbox must expose so a CLI Bridge can run inside it.
+ *
+ * A vendor adapter is only this: create the sandbox from the box image, run
+ * commands in it, expose the Bridge port, report status, destroy it. Profile
+ * materialization, turns, events, usage, cancellation and refusals all belong
+ * to the Bridge and to {@link createBridgeSandboxProvider}.
+ */
+export interface BridgeSandbox {
+    /** The vendor's own sandbox id. It becomes `AgentEnvironment.id`. */
+    readonly id: string;
+    readonly region?: string;
+    /**
+     * Run a command to completion as the box user.
+     *
+     * A non-zero exit is a result, never a throw. `signal` and `timeoutMs` end
+     * the remote command itself, not only the client call.
+     */
+    exec(command: string, options?: ExecRequest): Promise<ExecResult>;
+    /**
+     * Start a process that outlives this call, with `env` set on that process
+     * only. The Bridge runs this way, so its credentials never enter the sandbox
+     * default environment or any command line.
+     */
+    spawn(command: string, options: {
+        cwd?: string;
+        env: Record<string, string>;
+    }): Promise<void>;
+    /** Exact bytes written by `write`; a relative path resolves against the workspace directory. */
+    read(path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /** Creates parent directories. */
+    write(path: string, content: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** The URL that reaches `port` inside the sandbox, plus any headers the vendor's gateway requires. */
+    endpoint(port: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    /** The vendor's current lifecycle state; `stopped` or `expired` after destroy or expiry. */
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentEnvironmentStatus>;
+    /** Delete the sandbox. Resolves when it is already gone. */
+    destroy(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export interface BridgeSandboxCreateRequest {
+    name?: string;
+    /** Tags the vendor stores with the sandbox, string values only. Always carries the run tag. */
+    metadata: Record<string, string>;
+    /** Caller environment for the sandbox's default exec environment. */
+    env: Record<string, string>;
+    /** Finite lifetime the vendor enforces; longer than any turn the caller may run. */
+    lifetimeMs: number;
+    /** Vendor template, snapshot or image the caller chose; absent selects the published box image. */
+    environment?: string;
+    image?: string;
+    resources?: ResourceRequest;
+    egress?: {
+        mode: AgentEnvironmentEgressMode;
+        allowDomains: readonly string[];
+    };
+    /** Aborting must cancel the vendor create and destroy a sandbox that arrives late. */
+    signal?: AbortSignal;
+}
+export interface BridgeSandboxSummary {
+    id: string;
+    status: AgentEnvironmentStatus;
+    name?: string;
+    metadata: Record<string, string>;
+}
+/** Create-input fields a vendor honors beyond the always-honored ones. Everything else is refused. */
+export interface BridgeVendorSupport {
+    /** `workspace.environment` selects a vendor template or snapshot. */
+    environment: boolean;
+    /** `workspace.image` selects a vendor image. */
+    image: boolean;
+    resources: boolean;
+    /** Egress modes the vendor enforces; absent modes are refused. */
+    egress: readonly AgentEnvironmentEgressMode[];
+}
+export interface BridgeSandboxVendor {
+    /** Provider name reported on every environment, for example `e2b`. */
+    readonly name: string;
+    readonly support: BridgeVendorSupport;
+    create(request: BridgeSandboxCreateRequest): Promise<BridgeSandbox>;
+    /** `null` only when the vendor definitively reports no such sandbox; transport failures throw. */
+    connect(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeSandbox | null>;
+    /** Sandboxes whose tags contain every entry of `metadata`, with their true status. */
+    list(query: {
+        name?: string;
+        metadata?: Record<string, string>;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeSandboxSummary[]>;
+}

package/dist/sandbox/vendor.js

@@ -0,0 +1 @@
+export {};

package/dist/wire.d.ts

@@ -27,11 +27,14 @@ export declare function toolCallsFromDelta(value: unknown): Array<{
 }>;
 export declare function safeJson(value: string): Record<string, unknown> | null;
 export declare function usageFromOpenAi(value: unknown): TokenUsage | undefined;
+export declare function providerUsageFromOpenAi(value: unknown): Record<string, unknown> | undefined;
 export declare function modelRequestsFromOpenAi(value: unknown): number | undefined;
-/** Preserve the provider identity that cli-bridge returns on each completion frame. */
+/** Compatibility model and explicit provider observations have different authority. */
 export declare function responseIdentityFromOpenAi(value: unknown): {
     model?: string;
     system_fingerprint?: string;
+    provider_models?: string[];
+    provider_model?: string;
 } | undefined;
 export declare function modelRequestCount(value: unknown): number | undefined;
 export declare function cliBridgeRunId(environmentId: string, turn: AgentTurnInput, turnId: string): string;

package/dist/wire.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { AgentExactRunControlRefSchema, RequestedInteractionsSchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface";
+import { AgentExactRunControlRefSchema, CONTRACT_MAX_ARRAY_LENGTH, RequestedInteractionsSchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface";
 export function toChatCompletionsBody(options, environmentInput, turn, coordinates) {
     const profile = inlineProfile(environmentInput.profile);
     const execution = executionFromInput(options, environmentInput);
@@ -257,47 +257,61 @@ export function safeJson(value) {
     }
 }
 export function usageFromOpenAi(value) {
-    if (!value || typeof value !== "object")
+    const record = providerUsageFromOpenAi(value);
+    if (!record)
         return undefined;
-    const record = value;
-    const inputTokens = nonNegativeSafeInteger(record.prompt_tokens) ??
-        nonNegativeSafeInteger(record.input_tokens);
-    const outputTokens = nonNegativeSafeInteger(record.completion_tokens) ??
-        nonNegativeSafeInteger(record.output_tokens);
+    const inputTokens = nonNegativeSafeInteger(record.prompt_tokens) ?? nonNegativeSafeInteger(record.input_tokens);
+    const outputTokens = nonNegativeSafeInteger(record.completion_tokens) ?? nonNegativeSafeInteger(record.output_tokens);
     if (inputTokens === undefined || outputTokens === undefined)
         return undefined;
-    const totalTokens = nonNegativeSafeInteger(record.total_tokens);
-    const cacheReadInputTokens = nonNegativeSafeInteger(record.cache_read_input_tokens);
-    const cacheCreationInputTokens = nonNegativeSafeInteger(record.cache_creation_input_tokens);
-    const reasoningTokens = nonNegativeSafeInteger(record.reasoning_tokens);
+    const usage = { inputTokens, outputTokens };
+    for (const [key, wireKey] of [
+        ["totalTokens", "total_tokens"], ["cacheReadInputTokens", "cache_read_input_tokens"],
+        ["cacheCreationInputTokens", "cache_write_input_tokens"], ["reasoningTokens", "reasoning_tokens"],
+    ]) {
+        const count = nonNegativeSafeInteger(record[wireKey]) ??
+            (key === "cacheCreationInputTokens" ? nonNegativeSafeInteger(record.cache_creation_input_tokens) : undefined);
+        if (count !== undefined)
+            usage[key] = count;
+    }
     const cost = finiteNonNegativeNumber(record.cost);
-    return {
-        inputTokens,
-        outputTokens,
-        ...(totalTokens !== undefined ? { totalTokens } : {}),
-        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
-        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
-        ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
-        ...(cost !== undefined ? { cost } : {}),
-    };
+    if (cost !== undefined)
+        usage.cost = cost;
+    return usage;
+}
+export function providerUsageFromOpenAi(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
 }
 export function modelRequestsFromOpenAi(value) {
     if (!value || typeof value !== "object")
         return undefined;
     return modelRequestCount(value.model_requests);
 }
-/** Preserve the provider identity that cli-bridge returns on each completion frame. */
+/** Compatibility model and explicit provider observations have different authority. */
 export function responseIdentityFromOpenAi(value) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const record = value;
-    const model = nonEmptyString(record.model);
-    const systemFingerprint = nonEmptyString(record.system_fingerprint);
-    if (model === undefined && systemFingerprint === undefined)
+    const record = providerUsageFromOpenAi(value);
+    if (!record)
         return undefined;
+    if (record.provider_model !== undefined && nonEmptyString(record.provider_model) === undefined) {
+        throw new Error("cli-bridge returned an invalid provider model observation");
+    }
+    const models = record.provider_models;
+    if (models !== undefined && (!Array.isArray(models) || models.length > CONTRACT_MAX_ARRAY_LENGTH ||
+        models.some(model => nonEmptyString(model) === undefined))) {
+        throw new Error("cli-bridge returned invalid provider model observations");
+    }
+    const observations = [...new Set([
+            ...(models ?? []),
+            ...(nonEmptyString(record.provider_model) ? [record.provider_model] : []),
+        ])];
+    if (observations.length > CONTRACT_MAX_ARRAY_LENGTH)
+        throw new Error("cli-bridge provider model observations exceed contract bounds");
     return {
-        ...(model === undefined ? {} : { model }),
-        ...(systemFingerprint === undefined ? {} : { system_fingerprint: systemFingerprint }),
+        ...(nonEmptyString(record.model) ? { model: record.model } : {}),
+        ...(nonEmptyString(record.system_fingerprint) ? { system_fingerprint: record.system_fingerprint } : {}),
+        ...(observations.length ? { provider_models: observations } : {}),
+        ...(observations.length === 1 ? { provider_model: observations[0] } : {}),
     };
 }
 export function modelRequestCount(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./sandbox": {
+      "import": "./dist/sandbox/index.js",
+      "types": "./dist/sandbox/index.d.ts",
+      "default": "./dist/sandbox/index.js"
     }
   },
   "repository": {
@@ -60,15 +65,29 @@
     "dist/transport.js",
     "dist/wire.d.ts",
     "dist/wire.js",
+    "dist/sandbox/index.d.ts",
+    "dist/sandbox/index.js",
+    "dist/sandbox/box.d.ts",
+    "dist/sandbox/box.js",
+    "dist/sandbox/image.d.ts",
+    "dist/sandbox/image.js",
+    "dist/sandbox/provider.d.ts",
+    "dist/sandbox/provider.js",
+    "dist/sandbox/refusal.d.ts",
+    "dist/sandbox/refusal.js",
+    "dist/sandbox/vendor.d.ts",
+    "dist/sandbox/vendor.js",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^5.10.2",
-    "undici": "8.12.3"
+    "@tangle-network/agent-interface": "^5.10.12",
+    "undici": "8.12.3",
+    "@tangle-network/agent-profile-materialize": "1.1.4",
+    "@tangle-network/cli-agent-registry": "^0.14.0"
   },
   "devDependencies": {
-    "@tangle-network/agent-provider-testkit": "0.12.1",
+    "@tangle-network/agent-provider-testkit": "0.12.2",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "5.0.5"
@@ -78,6 +97,6 @@
     "check-types": "tsc --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run src",
-    "test:integration": "test -n \"$CLI_BRIDGE_INTEGRATION_ROOT\" || { echo 'CLI_BRIDGE_INTEGRATION_ROOT is required; see README' >&2; exit 1; }; pnpm run build && vitest run tests/cli-bridge.integration.test.ts"
+    "test:integration": "test -n \"$CLI_BRIDGE_INTEGRATION_ROOT\" || { echo 'CLI_BRIDGE_INTEGRATION_ROOT is required; see README' >&2; exit 1; }; pnpm run build && vitest run tests"
   }
 }