@tangle-network/agent-provider-tangle 0.9.0 → 0.10.0

package/dist/tangle-types.d.ts

@@ -1,5 +1,5 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 export interface TangleExactProcessOptions {
     teamId?: string;
@@ -30,6 +30,29 @@ export interface SandboxClientLike {
         signal?: AbortSignal;
     }): Promise<SandboxInstanceLike[]>;
     describePlacement?(box: SandboxInstanceLike): unknown;
+    /** Account usage counters for the credential behind this client. */
+    usage?(): Promise<SandboxAccountUsageLike>;
+    /** Plan, credit balance, and concurrency ceiling for the account. */
+    subscription?(): Promise<SandboxSubscriptionLike>;
+}
+/** The account usage counters the observation reads. */
+export interface SandboxAccountUsageLike {
+    activeSandboxes: number;
+    periodStart: Date | string;
+    periodEnd: Date | string;
+}
+/**
+ * The subscription fields the observation reads.
+ *
+ * `creditsAvailableUsd` can be negative on an overage plan, and
+ * `maxConcurrentSandboxes` is 0 when the account has no ceiling. Neither value
+ * fits the contract's non-negative credit and quota shapes, so the observation
+ * reports those two cases as unavailable instead of clamping them.
+ */
+export interface SandboxSubscriptionLike {
+    plan: string;
+    creditsAvailableUsd: number;
+    maxConcurrentSandboxes: number;
 }
 /**
  * The `GET /capabilities` document as this adapter reads it: what the DEPLOYED
@@ -70,6 +93,16 @@ export interface SandboxRuntimeCapabilityDocument {
         /** Buffered run events replay by execution. */
         eventReplay?: boolean;
     };
+    interactions?: {
+        /**
+         * The interaction route records every acknowledged resolution durably:
+         * repeating a response replays the recorded resolution, a different answer
+         * for a recorded resolution raises a conflict, and the deployment refuses
+         * rather than acknowledge a resolution it cannot record. Absent on an
+         * image that predates the flag, which is unknown and never a claim.
+         */
+        responseDedupe?: boolean;
+    };
 }
 export interface SandboxProcessStatusLike {
     pid: number;
@@ -99,11 +132,112 @@ export interface SandboxProcessManagerLike {
         signal?: AbortSignal;
     }): Promise<SandboxProcessLike>;
 }
+/**
+ * The connection fields this adapter reads.
+ *
+ * The Sandbox connection object also carries a bearer token and its expiry.
+ * Neither is declared here, so no code path can copy a credential into an
+ * observation: the adapter reads the runtime URL and nothing else.
+ */
+export interface SandboxConnectionLike {
+    runtimeUrl?: string;
+}
+/** Live cgroup sample for one sandbox. `null` fields mean the host reported none. */
+export interface SandboxResourceUsageLike {
+    memoryCurrentMb: number;
+    memoryPeakMb: number | null;
+    memoryLimitMb: number | null;
+    cpuUsageUsec: number;
+    sampledAtMs: number;
+}
+/**
+ * The GPU lease fields the observation reads: the accelerator actually
+ * attached, and the compute cost charged for it. `billing` exists after the
+ * lease stops; `estimatedCustomerCostUsd` is the running estimate before that.
+ */
+export interface SandboxGpuLeaseLike {
+    accelerator: {
+        kind: string;
+        count: number;
+        memoryMB?: number;
+    };
+    region?: string;
+    billing?: {
+        customerCostUsd: number;
+    };
+    estimatedCustomerCostUsd?: number;
+}
+/** Interactive terminal metadata the runtime reports for one PTY. */
+export interface SandboxTerminalInfoLike {
+    sessionId: string;
+    connectionId?: string;
+    name?: string;
+    shell?: string;
+    command?: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    createdAt?: string;
+    lastActivityAt?: string;
+    isRunning?: boolean;
+    exitCode?: number;
+    exitSignal?: string;
+}
+/** The `ready` acknowledgement the terminal WebSocket returns on attach. */
+export interface SandboxTerminalReadyLike {
+    connectionId: string;
+    sessionId: string;
+    /** True when the runtime reattached an existing PTY and replays its history. */
+    restored: boolean;
+    /** How long the runtime keeps the PTY alive after this socket closes. */
+    detachTimeoutMs: number;
+}
+/** Callbacks bound before the terminal socket opens. */
+export interface SandboxTerminalHandlersLike {
+    onData?: (data: Uint8Array) => void;
+    onReady?: (info: SandboxTerminalReadyLike) => void;
+    onExit?: (info: {
+        exitCode?: number;
+        exitSignal?: string;
+    }) => void;
+    onError?: (error: Error) => void;
+    onClose?: (code: number, reason: string) => void;
+}
+/** One live terminal WebSocket. */
+export interface SandboxTerminalStreamLike {
+    readonly connectionId: string;
+    readonly ready: SandboxTerminalReadyLike;
+    readonly isOpen: boolean;
+    write(data: string | Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    close(): Promise<void>;
+}
+/**
+ * The terminal surface this adapter binds: metadata lookup plus the live PTY
+ * attach. Reusing a connection id reattaches an existing PTY and replays its
+ * buffered output; a new id starts a shell or the requested command.
+ */
+export interface SandboxTerminalsLike {
+    get(sessionId: string): Promise<SandboxTerminalInfoLike | null>;
+    attach(connectionId: string, options?: {
+        cols?: number;
+        rows?: number;
+        command?: string;
+        cwd?: string;
+        handlers?: SandboxTerminalHandlersLike;
+    }): Promise<SandboxTerminalStreamLike>;
+}
 export interface SandboxInstanceLike {
     id: string;
     name?: string;
     status?: unknown;
     metadata?: Record<string, unknown>;
+    /** Network location of the sandbox runtime, without its bearer. */
+    connection?: SandboxConnectionLike;
+    /** When the platform retires this sandbox, when it set a lifetime. */
+    expiresAt?: Date | string;
+    /** GPU lease attached at create time, when one was requested. */
+    gpuLease?: SandboxGpuLeaseLike;
     streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
     prompt?(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
     dispatchPrompt?(message: string | InputPart[], options?: PromptOptions): Promise<unknown>;
@@ -155,6 +289,14 @@ export interface SandboxInstanceLike {
      * reads; a malformed document throws.
      */
     capabilities?(): Promise<SandboxRuntimeCapabilityDocument | null>;
+    /**
+     * Live cgroup sample for the whole sandbox. Resolves to null when the host
+     * collects no cgroup statistics, which the observation reports as an absent
+     * measurement rather than a zero.
+     */
+    resourceUsage?(): Promise<SandboxResourceUsageLike | null>;
+    /** Interactive terminal transport. Absent on a client that cannot serve a PTY. */
+    terminals?: SandboxTerminalsLike;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -186,6 +328,44 @@ export interface SandboxSessionLike {
     cancelRun?(request: AgentRunCancellationRequest, options?: {
         signal?: AbortSignal;
     }): Promise<AgentRunCancellationAcknowledgement>;
+    /**
+     * Every ask still awaiting a response on this session. The adapter reads the
+     * answer spec from here to refuse an answer the ask does not accept, so an
+     * ask that has already left the outstanding set is absent rather than an
+     * error. Absent on a Sandbox SDK that cannot list the outstanding set.
+     */
+    interactions?(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly InteractionRequest[]>;
+    /**
+     * Deliver one digest-bound response to the exact ask its binding names.
+     *
+     * The result carries the acknowledgement the deployment's durable record
+     * produced, and `serverResult` carries that record itself. Absent on a
+     * Sandbox SDK older than 0.23.0, whose response path selected an ask by
+     * position rather than by id.
+     */
+    respondToInteraction?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxInteractionCommandResultLike>;
+}
+/**
+ * The Sandbox SDK's reply to one response command.
+ *
+ * Both members are read as unvalidated wire content: the acknowledgement
+ * reaches the canonical schema before this adapter returns it, and the
+ * resolution is read only for the two facts the acknowledgement cannot
+ * carry — whether the deployment confirmed delivery, and the digest of the
+ * response a conflicting resolution already holds.
+ */
+export interface SandboxInteractionCommandResultLike {
+    acknowledgement: unknown;
+    serverResult?: {
+        status?: unknown;
+        delivered?: unknown;
+        existingResponseDigest?: unknown;
+        [key: string]: unknown;
+    };
 }
 export interface TangleProviderOptions {
     client: SandboxClientLike;

package/dist/tangle-usage-log.d.ts

@@ -0,0 +1,22 @@
+import type { TokenUsage } from "@tangle-network/agent-interface";
+/** One execution's measured token usage and cost. */
+export interface ExecutionUsageRecord {
+    executionId: string;
+    usage: TokenUsage;
+    observedAt: string;
+}
+/**
+ * The newest per-execution usage this environment handle measured.
+ *
+ * Sandbox reports token usage and cost on the result of one execution, never
+ * for the environment as a whole, so the only environment-scoped answer is the
+ * newest execution the handle actually saw. The record lives with the handle:
+ * an environment rebuilt through `provider.get(id)` starts with none, and the
+ * observation then reports the usage surface as unavailable rather than as a
+ * measured zero.
+ */
+export interface ExecutionUsageLog {
+    record(executionId: string | undefined, usage: TokenUsage | undefined): void;
+    latest(): ExecutionUsageRecord | undefined;
+}
+export declare function createExecutionUsageLog(): ExecutionUsageLog;

package/dist/tangle-usage-log.js

@@ -0,0 +1,22 @@
+import { boundedIdentifier } from "./tangle-contract-safety.js";
+export function createExecutionUsageLog() {
+    let latest;
+    return {
+        record(executionId, usage) {
+            // Usage without the execution it belongs to cannot be attributed, and an
+            // execution without usage measured nothing. Neither is recorded.
+            if (executionId === undefined || usage === undefined)
+                return;
+            latest = {
+                executionId: boundedIdentifier(executionId, "Tangle execution id"),
+                usage,
+                observedAt: new Date().toISOString(),
+            };
+        },
+        latest() {
+            return latest === undefined
+                ? undefined
+                : { ...latest, usage: { ...latest.usage } };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,8 @@
     "dist/tangle-exact-process-environment.js",
     "dist/tangle-contract-safety.d.ts",
     "dist/tangle-contract-safety.js",
+    "dist/tangle-failure-reason.d.ts",
+    "dist/tangle-failure-reason.js",
     "dist/tangle-exact-process-runtime.d.ts",
     "dist/tangle-exact-process-runtime.js",
     "dist/tangle-exact-process-validation.d.ts",
@@ -49,12 +51,24 @@
     "dist/tangle-environment-dispatch.js",
     "dist/tangle-environment-session.d.ts",
     "dist/tangle-environment-session.js",
+    "dist/tangle-interaction-response.d.ts",
+    "dist/tangle-interaction-response.js",
     "dist/tangle-environment-control.d.ts",
     "dist/tangle-environment-control.js",
     "dist/tangle-environment-validation.d.ts",
     "dist/tangle-environment-validation.js",
     "dist/tangle-events.d.ts",
     "dist/tangle-events.js",
+    "dist/tangle-observation.d.ts",
+    "dist/tangle-observation.js",
+    "dist/tangle-resources.d.ts",
+    "dist/tangle-resources.js",
+    "dist/tangle-terminal.d.ts",
+    "dist/tangle-terminal.js",
+    "dist/tangle-terminal-frames.d.ts",
+    "dist/tangle-terminal-frames.js",
+    "dist/tangle-usage-log.d.ts",
+    "dist/tangle-usage-log.js",
     "dist/tangle-prompt.d.ts",
     "dist/tangle-prompt.js",
     "dist/tangle-provider.d.ts",
@@ -69,10 +83,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.51.0"
+    "@tangle-network/agent-interface": "0.52.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.19.6 <1.0.0"
+    "@tangle-network/sandbox": ">=0.23.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -82,11 +96,11 @@
   "devDependencies": {
     "@tangle-network/agent-eval": "0.145.3",
     "@tangle-network/agent-runtime": "0.132.13",
-    "@tangle-network/sandbox": "0.22.0",
+    "@tangle-network/sandbox": "0.23.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.7.1"
+    "@tangle-network/agent-provider-testkit": "0.7.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",