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

package/README.md

@@ -47,6 +47,25 @@ 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.
 
@@ -59,7 +78,7 @@ 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.
+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.
@@ -79,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.
@@ -96,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.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/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.4",
+  "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": {