@tangle-network/agent-provider-cli-bridge 1.0.3 → 1.1.1

package/README.md

@@ -107,6 +107,11 @@ When `dispatch()` receives no `sessionId`, it creates one from that turn's stabl
 Replay and result reads fail loudly after cli-bridge's configured replay retention expires.
 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.
+Destroying an environment does not close a native Bridge session that has reached a terminal result.
+For a one-shot Pi session, call `closeExactCliBridgeSession(options, controlRef)` after reading the result.
+The provider verifies the exact run and session before it closes the session.
+Repeat cleanup of the same closed session succeeds without sending another close request.
+Keep the `controlRef` from durable admission so a process restart can perform the same cleanup.
 
 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.

package/dist/index.d.ts

@@ -6,6 +6,7 @@ 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 { closeExactCliBridgeSession } from "./retained-control.js";
 export interface CliBridgeProvider extends AgentEnvironmentProvider {
     /** Recover the server-issued digest for one pre-dispatch retained admission. */
     lookupRun(input: CliBridgeRunLookupInput): Promise<AgentExactRunControlRef | null>;

package/dist/index.js

@@ -10,6 +10,7 @@ import { narrowedCliBridgeObservation } from "./observation.js";
 import { cliBridgeEnvironmentId, optionalCliBridgeEnvironmentRoute, } from "./environment-identity.js";
 import { resolveBridgeModel } from "./wire.js";
 export { safeEndpointFromBaseUrl } from "./observation.js";
+export { closeExactCliBridgeSession } from "./retained-control.js";
 export function createCliBridgeProvider(options) {
     assertCliBridgeProviderOptions(options);
     const name = options.name ?? "cli-bridge";

package/dist/retained-control.d.ts

@@ -1,8 +1,10 @@
 import { type AgentExactRunControlRef, type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest } from "@tangle-network/agent-interface";
 import type { AgentSessionStatus } from "@tangle-network/agent-interface/environment-provider";
 import { type CliBridgeProviderOptions } from "./provider-options.js";
-import type { CliBridgeRun, CliBridgeRunSnapshot } from "./retained-run-state.js";
+import { type CliBridgeRun, type CliBridgeRunSnapshot } from "./retained-run-state.js";
 import type { CliBridgeResponse, CliBridgeTransport } from "./transport.js";
+/** Release one terminal native session using the exact retained run it last owned. */
+export declare function closeExactCliBridgeSession(options: CliBridgeProviderOptions, controlRef: AgentExactRunControlRef, signal?: AbortSignal): Promise<void>;
 export declare function cliBridgeCancellationSignal(options: CliBridgeProviderOptions): AbortSignal;
 export declare function captureCliBridgeRunIdentity(response: CliBridgeResponse, run: CliBridgeRun, required: boolean): void;
 export declare function detachCliBridgeReader(body: AsyncIterable<Uint8Array>): Promise<void>;

package/dist/retained-control.js

@@ -1,8 +1,69 @@
 import { AgentExactRunControlRefSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, agentRunCancellationRequestDigest, agentRunCancellationAcknowledgementMatchesRequest, sameAgentRunControlRef, } from "@tangle-network/agent-interface";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
+import { runFromControlRef } from "./retained-run-state.js";
 import { createCliBridgeTransport, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
-import { assertCliBridgeRunId, runSnapshot } from "./wire.js";
+import { assertCliBridgeRunId, runSnapshot, safeJson } from "./wire.js";
 const DEFAULT_CANCELLATION_WAIT_MS = 30_000;
+/** Release one terminal native session using the exact retained run it last owned. */
+export async function closeExactCliBridgeSession(options, controlRef, signal) {
+    assertCliBridgeProviderOptions(options);
+    const exact = AgentExactRunControlRefSchema.parse(controlRef);
+    if (exact.provider !== (options.name ?? "cli-bridge")) {
+        throw new Error("cli-bridge session close targets another provider");
+    }
+    const timeoutSignal = AbortSignal.timeout(options.cancelWaitMs ?? DEFAULT_CANCELLATION_WAIT_MS);
+    const operationSignal = signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
+    const transport = createCliBridgeTransport(options);
+    try {
+        const run = await getCliBridgeRun(options, transport, runFromControlRef(exact), undefined, operationSignal);
+        if (!run?.terminal) {
+            throw new Error("cli-bridge cannot close a session before its exact run is terminal");
+        }
+        const endpoint = `${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(exact.sessionId)}`;
+        const currentResponse = await transport.fetch(endpoint, {
+            method: "GET",
+            headers: requestHeaders(options),
+            signal: operationSignal,
+        });
+        const currentText = await readBoundedCliBridgeResponse(currentResponse, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, operationSignal);
+        if (!currentResponse.ok) {
+            throw new Error(`cli-bridge session status returned HTTP ${currentResponse.status}`);
+        }
+        const current = safeJson(currentText);
+        if (current?.id !== exact.sessionId || current.run_id !== exact.runId) {
+            throw new Error("cli-bridge session close targets another retained run");
+        }
+        if (current.status === "closed")
+            return;
+        if (current.status === "running") {
+            throw new Error("cli-bridge cannot close an active retained session");
+        }
+        const response = await transport.fetch(`${endpoint}/close`, {
+            method: "POST",
+            headers: requestHeaders(options),
+            signal: operationSignal,
+        });
+        const responseText = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, operationSignal);
+        if (!response.ok) {
+            throw new Error(`cli-bridge session close returned HTTP ${response.status}`);
+        }
+        const confirmation = safeJson(responseText);
+        const closed = confirmation?.session;
+        if (typeof closed !== "object" || closed === null || Array.isArray(closed)) {
+            throw new Error("cli-bridge session close did not confirm the exact closed session");
+        }
+        const session = closed;
+        if (confirmation?.closed !== true ||
+            session.id !== exact.sessionId ||
+            session.run_id !== exact.runId ||
+            session.status !== "closed") {
+            throw new Error("cli-bridge session close did not confirm the exact closed session");
+        }
+    }
+    finally {
+        await transport.close();
+    }
+}
 export function cliBridgeCancellationSignal(options) {
     assertCliBridgeProviderOptions(options);
     return AbortSignal.timeout(options.cancelWaitMs ?? DEFAULT_CANCELLATION_WAIT_MS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -64,13 +64,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^2.7.0",
-    "undici": "8.10.1"
+    "@tangle-network/agent-interface": "^2.13.1",
+    "undici": "8.11.2"
   },
   "devDependencies": {
-    "@types/node": "26.4.1",
+    "@types/node": "26.6.3",
     "typescript": "7.0.2",
-    "vitest": "4.1.11"
+    "vitest": "5.0.2"
   },
   "scripts": {
     "build": "pnpm run clean && tsc -p tsconfig.build.json",