@tangle-network/agent-provider-cli-bridge 0.9.3 → 0.9.5

package/README.md

@@ -8,6 +8,10 @@ import { createCliBridgeProvider } from '@tangle-network/agent-provider-cli-brid
 const provider = createCliBridgeProvider({
   baseUrl: 'http://127.0.0.1:8787',
   bearerToken: process.env.CLI_BRIDGE_TOKEN,
+  defaultExecution: {
+    kind: 'host',
+    jail: { mode: 'fs-jail' },
+  },
 })
 
 const environment = await provider.create({
@@ -43,10 +47,38 @@ The provider rejects any coordinate or digest mismatch instead of attaching to a
 If the caller crashes before saving `controlRef`, call `provider.lookupRun()` with the planned run coordinates.
 The lookup returns the server-issued digest only when all five planned coordinates match the retained run.
 
+## Which call adds a turn
+
+Continuation has two tiers, and the tier depends on whether the environment object came from `create()` or from `get()`.
+
+In the process that created the environment, `environment.dispatch()`, `environment.stream()`, and `session.prompt()` all add a turn.
+Passing the same `sessionId` continues the same CLI conversation.
+
+After `provider.get(environmentId)` reconstructs the environment, only `session.continueNative(request, { turn })` can add a turn.
+It requires the `nativeContinuation` capability, which the provider publishes only for the Pi harness today, and only when the running Bridge proves the same contract.
+The reconstructed environment deliberately refuses every other way to start work: `environment.stream()` and `environment.dispatch()` throw "a reconstructed cli-bridge environment can only control an existing run", and `session.prompt()` throws "a reconstructed cli-bridge session cannot start another turn".
+A reconstructed environment for any other harness therefore controls its existing runs (status, cursor replay, result, cancellation, and interaction responses) but adds no turn.
+Restart-safe continuation for those harnesses needs native sessions in the Bridge server itself, which the Bridge does not have yet; it is tracked in the `drewstone/cli-bridge` repository and cannot be reached from this adapter.
+
+The capability document keeps `sessions.continue: true` on a reconstructed environment because the Agent Interface couples that flag to `retainedControl`: a document that reports `sessions.continue: false` while keeping retained run control fails `AgentEnvironmentCapabilitiesSchema` with "retained control requires exact run, result, event, cancellation, replay, detach, turn, and session identity together".
+`nativeContinuation` is the flag that states whether a reconstructed environment can add a turn: present means `continueNative` works, absent means no call on that environment starts one.
+
+A runtime caller continues a retained run with `RetainedRunHandle.continueNative`, not with `startRetainedRunInEnvironment`.
+`startRetainedRunInEnvironment` requires `provider.list` for its ownership proof, and this provider exposes no `list`; it then calls `environment.dispatch()`, which a reconstructed environment refuses.
+
 The bridge model is selected from run data in this order: the turn, the provider default, or the profile's `harness` plus `model.default`.
 Execution fails before network use when none is present.
 
-Passing the same `sessionId` on later turns continues the same CLI conversation.
+`defaultExecution` is the existing cli-bridge `execution` request object.
+The provider forwards it unchanged to the Bridge session or chat request.
+Host execution accepts `jail`, `netJail`, and `timeoutMs`.
+Sandbox execution accepts `repoUrl`, `gitRef`, `capability`, `ttlSeconds`, `netJail`, and `timeoutMs`.
+The Bridge validates the object and applies its operator confinement rules.
+Retained native sessions currently require `kind: 'host'`.
+The provider rejects a sandbox default before it creates the retained session; use one-shot execution for `kind: 'sandbox'`.
+The Bridge currently refuses `netJail` with `kind: 'sandbox'`; use the sandbox's own egress policy.
+
+Passing the same `sessionId` on later turns continues the same CLI conversation while the creating process still holds the environment.
 `executionId` gives a turn stable bridge identity, and `lastEventId` reattaches after a reader failure.
 `dispatch()` starts a bridge-owned durable run and returns after detaching its HTTP reader.
 The returned `AgentSession` exposes status, cursor-based event replay, the terminal result, continuation, and cancellation.
@@ -66,7 +98,7 @@ Replay and result reads fail loudly after cli-bridge's configured replay retenti
 Stopping a `session.events()` reader detaches only that replay observer.
 Stopping a direct `environment.stream()` reader or destroying the environment cancels its active bridge runs and waits for terminal confirmation.
 
-Pi retained sessions also expose typed permission interactions.
+Pi retained sessions also expose typed permission interactions and native continuation.
 The provider stores the selected harness, exact model route, and canonical create digest inside its opaque environment identifier.
 This identifier lets `provider.get()` reconstruct profile-selected routes after process death without a cache or repeated configuration.
 The create digest prevents an altered profile or workspace from reusing the previous retained identity.
@@ -83,6 +115,8 @@ The environment and session then expose `respondToInteraction()` for exact respo
 Each command carries its run, session, execution, request digest, and stable operation identifier.
 Native turns require caller-stable `turnId` and `executionId` values so an ambiguous admission cannot create another run.
 The bridge records repeated operations and rejects a different answer for an existing operation.
+Repeating one operation identifier returns its stored acknowledgement; a new operation identifier for an interaction that is already resolved returns `already_resolved_same` when the answer matches and `already_resolved_different` when it does not, and answering an interaction that a run cancellation closed returns `cancelled`.
+The `expired` acknowledgement stays in the contract, but the Bridge never emits it, so only the unit contradiction table covers it.
 The provider reports an unconfirmed network result as retryable and never reports it as accepted.
 Native replay reads `/v1/runs/:runId/events` and validates each canonical envelope through Agent Interface before exposing it.
 When a turn supplies `interactions`, the provider carries its exact map, including an explicit `{}`; an omitted map remains omitted.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { type AgentExactRunControlRef, type HarnessType } from "@tangle-network/
 import { type CliBridgeRunLookupInput } from "./retained-control.js";
 import { type CliBridgeProviderOptions } from "./provider-options.js";
 export type { CliBridgeProviderOptions } from "./provider-options.js";
+export type { CliBridgeExecution } from "./provider-options.js";
 export type { CliBridgeRunLookupInput } from "./retained-control.js";
 export { safeEndpointFromBaseUrl } from "./observation.js";
 export interface CliBridgeProvider extends AgentEnvironmentProvider {

package/dist/index.js

@@ -76,6 +76,7 @@ export function createCliBridgeProvider(options) {
             environmentId,
             allowDispatch: true,
             cancelRunsOnDestroy: true,
+            creation: "created",
             capabilities: await resolveCapabilities(selectedBackend, model, true, selectedBackend === "pi" ||
                 (model !== undefined && remotelyVerifiedRoutes.has(model))),
             selectedBackend,

package/dist/provider-options.d.ts

@@ -1,19 +1,40 @@
 import type { AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
 export declare const MAX_CLI_BRIDGE_TIMEOUT_MS = 2147483647;
+/**
+ * The execution object accepted by cli-bridge's request wire contract.
+ *
+ * The provider forwards this object unchanged as `execution`; cli-bridge owns
+ * validation, confinement resolution, and execution placement.
+ */
+export type CliBridgeExecution = {
+    kind: "host";
+    jail?: {
+        mode?: "off" | "write-jail" | "fs-jail";
+        root?: string;
+    };
+    netJail?: {
+        mode?: "off" | "net-jail";
+        allow?: string[];
+    };
+    timeoutMs?: number;
+} | {
+    kind: "sandbox";
+    repoUrl?: string;
+    gitRef?: string;
+    capability?: string;
+    ttlSeconds?: number;
+    netJail?: {
+        mode?: "off" | "net-jail";
+        allow?: string[];
+    };
+    timeoutMs?: number;
+};
 export interface CliBridgeProviderOptions {
     baseUrl: string;
     bearerToken?: string;
     defaultModel?: string;
     defaultMode?: "byob" | "hosted-safe" | "hosted-sandboxed";
-    defaultExecution?: {
-        kind: "host";
-    } | {
-        kind: "sandbox";
-        repoUrl?: string;
-        gitRef?: string;
-        capability?: string;
-        ttlSeconds?: number;
-    };
+    defaultExecution?: CliBridgeExecution;
     /** Maximum wait for response headers. Defaults to no timeout. */
     headersTimeoutMs?: number;
     /** Maximum idle time between response body chunks. Defaults to no timeout. */

package/dist/retained-environment.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEnvironment, AgentEnvironmentCapabilities, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentCreation, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CreateCliBridgeEnvironmentArgs {
     readonly options: CliBridgeProviderOptions;
@@ -7,6 +7,13 @@ export interface CreateCliBridgeEnvironmentArgs {
     readonly environmentId: string;
     readonly allowDispatch: boolean;
     readonly cancelRunsOnDestroy: boolean;
+    /**
+     * The verdict of the create call that builds this environment. The create
+     * path states `created` because it provisions the handle that tracks every
+     * run it starts; the in-process idempotency helper supplies `replayed`; a
+     * reconstruction through `get()` states nothing.
+     */
+    readonly creation?: AgentEnvironmentCreation;
     /**
      * The document this provider publishes. The environment offers an optional
      * operation only where the document claims it, so a caller never selects an

package/dist/retained-environment.js

@@ -5,6 +5,18 @@ import { cliBridgeInteractionResponder } from "./interaction-response.js";
 import { assertCliBridgeRequestedInteractions, assertCliBridgeTurnModel, continueCliBridgeNative, readCliBridgeNativeContextBoundary, supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { assertRunMatchesControlRef, exactControlRefForSession, prepareCliBridgeRun, runFromControlRef, } from "./retained-run-state.js";
 import { createCliBridgeTransport } from "./transport.js";
+/**
+ * One refusal for every call that would add a turn to a reconstructed
+ * environment. `provider.get()` rebuilds control of existing runs from the
+ * opaque environment id alone, so it holds no create request that a new native
+ * session could reuse. Only `session.continueNative` advances a retained run
+ * after reconstruction, and only where the Bridge proves `nativeContinuation`.
+ */
+function assertCliBridgeTurnAllowed(allowed, surface) {
+    if (allowed)
+        return;
+    throw new Error(`a reconstructed cli-bridge environment cannot start a turn through ${surface}; use session.continueNative, which requires the nativeContinuation capability`);
+}
 export function createCliBridgeEnvironment(args) {
     const { options, providerName, environmentInput, environmentId } = args;
     const transport = createCliBridgeTransport(options);
@@ -27,9 +39,7 @@ export function createCliBridgeEnvironment(args) {
     const stream = async function* (turn) {
         if (destroyed)
             throw new Error("cli-bridge environment is destroyed");
-        if (!args.allowDispatch) {
-            throw new Error("a reconstructed cli-bridge environment can only control an existing run");
-        }
+        assertCliBridgeTurnAllowed(args.allowDispatch, "environment.stream()");
         if (args.selectedModel !== undefined &&
             args.capabilities.retainedControl !== undefined) {
             assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
@@ -48,6 +58,7 @@ export function createCliBridgeEnvironment(args) {
     return {
         id: environmentId,
         provider: providerName,
+        ...(args.creation === undefined ? {} : { creation: args.creation }),
         capabilities: args.capabilities,
         ...(environmentInput.name ? { name: environmentInput.name } : {}),
         status: async (statusOptions) => {
@@ -58,9 +69,7 @@ export function createCliBridgeEnvironment(args) {
         async dispatch(turn) {
             if (destroyed)
                 throw new Error("cli-bridge environment is destroyed");
-            if (!args.allowDispatch) {
-                throw new Error("a reconstructed cli-bridge environment cannot dispatch new work");
-            }
+            assertCliBridgeTurnAllowed(args.allowDispatch, "environment.dispatch()");
             if (args.selectedModel !== undefined &&
                 args.capabilities.retainedControl !== undefined) {
                 assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
@@ -229,9 +238,7 @@ function createCliBridgeSession(args) {
             return result;
         },
         async prompt(input) {
-            if (!args.allowPrompt) {
-                throw new Error("a reconstructed cli-bridge session cannot start another turn");
-            }
+            assertCliBridgeTurnAllowed(args.allowPrompt, "session.prompt()");
             if (input.sessionId && input.sessionId !== args.id) {
                 throw new Error(`cli-bridge session "${args.id}" cannot prompt session "${input.sessionId}"`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -59,7 +59,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.3.0",
+    "@tangle-network/agent-interface": "^1.4.0",
     "undici": "7.29.0"
   },
   "devDependencies": {