feat(sdk): resume durable agent sessions

Persist explicit SDK sessions across managed Host restarts and restore them through the existing Agent Runtime. Keep transient query behavior unchanged and preserve same-session writer exclusion.

Author: limityan

sdk/typescript/README.md

@@ -9,8 +9,9 @@ The slice validates the intended public object model:
 - one application-level `AgentClient` owns one managed native
   `bitfun-sdk-host` process and one Host connection;
 - `client.query()` uses a Host-managed transient Session;
-- `client.sessions.create()` creates an explicit Session whose Turns reuse the
-  same connection and existing Agent Runtime owner;
+- `client.sessions.create()` creates a durable Session whose Turns reuse the
+  same connection, while `client.sessions.resume(id)` attaches it to a later
+  Host process;
 - `Query` is an ordered async stream with idempotent cancellation, cached final
   `Result`, and explicit close semantics;
 - the same stream reports safe Tool lifecycle facts and permission requests;
@@ -22,6 +23,12 @@ kill-on-close Job Object, while Unix managed Hosts run in an isolated process
 group. A cleanup result whose outcome is unknown makes the connection
 unusable and triggers Host reclamation.
 
+Durable Sessions are persisted by the existing Agent Runtime. Closing a
+Session or its client unloads it without deleting its history, so a later
+client using the same workspace can resume it by ID. Existing OS-level Session
+locks reject a second writer while another Host process owns that same Session;
+different Sessions remain independent.
+
 It does not start the CLI or the Node/Bun Plugin Host, and it does not implement
 another Agent Runtime. The managed native Host adapts this package to the
 existing `agent-runtime::sdk` API.
@@ -75,6 +82,23 @@ for await (const item of query) {
 const result = await query.result();
 ```
 
+Use an explicit Session when the application needs continuity across client or
+Host restarts. Here `options` is the same trusted `AgentClientOptions` value
+shown above:
+
+```typescript
+const firstClient = await AgentClient.start(options);
+const session = await firstClient.sessions.create({ sessionName: "review" });
+const sessionId = session.id;
+await (await session.startTurn({ prompt: "Inspect the current changes" })).result();
+await firstClient.close(); // unloads the Session and exits its managed Host
+
+const nextClient = await AgentClient.start(options);
+const resumed = await nextClient.sessions.resume(sessionId);
+await (await resumed.startTurn({ prompt: "Now summarize the risks" })).result();
+await nextClient.close();
+```
+
 An explicit absolute `hostPath` remains available as a development override.
 The SDK never searches `PATH` or an environment variable for the Host.
 
@@ -88,8 +112,8 @@ separately. This PR does not publish the package. A future registry release
 still needs platform packages, signing, and release verification.
 
 Browser and mobile runtimes cannot launch the local native Host. Custom
-functions, general user-input callbacks, structured output, usage, Session
-resume, Python support, platform package publication, signing, and downloads
+functions, general user-input callbacks, structured output, usage, Python
+support, platform package publication, signing, and downloads
 remain deferred.
 
 ## Development

sdk/typescript/scripts/generate-wire.mjs

@@ -61,6 +61,7 @@ const requiredTypes = [
   "SessionCloseResult",
   "SessionCreateParams",
   "SessionCreateResult",
+  "SessionResumeParams",
   "ShutdownResult",
   "TemporaryModelConfig",
   "TemporaryModelProvider",

sdk/typescript/scripts/generated-wire-runtime.test.mjs

@@ -43,12 +43,13 @@ test("Rust wire export produces executable validators for every type", async ()
   }
 
   const initializeResult = {
-    protocolVersion: 3,
+    protocolVersion: 4,
     runtimeVersion: "0.1.0",
     stability: "not_delivered",
     capabilities: {
       sessionCreate: true,
-      sessionCreateLifetime: "connection",
+      sessionCreateLifetime: "durable",
+      sessionResume: true,
       query: true,
       queryCancel: true,
       sessionClose: true,

sdk/typescript/src/internal/client.ts

@@ -4,7 +4,7 @@ import { JsonRpcConnection } from "./json-rpc.js";
 import type { HostTransport } from "./transport.js";
 import type { InitializeParams, InitializeResult } from "./wire/index.js";
 
-const PROTOCOL_VERSION = 3;
+const PROTOCOL_VERSION = 4;
 const DEFAULT_INITIALIZE_TIMEOUT_MS = 30_000;
 
 export async function createAgentClient(

sdk/typescript/src/internal/wire-validation.ts

@@ -36,6 +36,7 @@ export function validateResponseResult<T>(method: string, value: unknown): T {
     case "initialize":
       return validateInitializeResult(value) as T;
     case "session/create":
+    case "session/resume":
       return validateSessionCreateResult(value) as T;
     case "query/start":
       return validateQueryStartResult(value) as T;

sdk/typescript/src/session.ts

@@ -4,6 +4,7 @@ import type {
   SessionCloseParams,
   SessionCreateParams,
   SessionCreateResult,
+  SessionResumeParams,
 } from "./internal/wire/index.js";
 import type { JsonRpcConnection } from "./internal/json-rpc.js";
 import { withTimeout } from "./internal/deadline.js";
@@ -70,6 +71,21 @@ export class Sessions {
     this.#onSession(session);
     return session;
   }
+
+  async resume(sessionId: string): Promise<Session> {
+    this.#ensureClientOpen();
+    if (sessionId.trim().length === 0) {
+      throw new Error("sessionId must not be empty");
+    }
+    const params: SessionResumeParams = { sessionId };
+    const resumed = await this.#connection.request<SessionCreateResult>(
+      "session/resume",
+      params,
+    );
+    const session = Session.create(this.#connection, resumed, this.#onQuery);
+    this.#onSession(session);
+    return session;
+  }
 }
 
 export class Session {

sdk/typescript/src/types.ts

@@ -84,7 +84,7 @@ export interface SdkErrorDetails {
   recovery?: RecoveryAction;
 }
 
-export type SessionLifetime = "connection";
+export type SessionLifetime = "connection" | "durable";
 
 export interface QueryInput {
   prompt: string;

sdk/typescript/test/client.test.ts

@@ -55,7 +55,7 @@ test("a Query streams tool and permission events before the terminal Result", as
   assert.ok(client instanceof AgentClient);
   assert.equal(initializeRequests.length, 1);
   assert.deepEqual(initializeRequests[0], {
-    protocolVersion: 3,
+    protocolVersion: 4,
     clientInfo: { name: "@bitfun/agent-sdk", version: "0.0.0" },
     capabilities: {
       serverNotifications: true,
@@ -187,6 +187,7 @@ test("an explicit Session starts Turns on the existing client connection", async
   } as SessionCreateInput);
   assert.equal(session.id, "session-explicit");
   assert.equal(session.agent, "agentic");
+  assert.equal(session.lifetime, "durable");
 
   const query = await session.startTurn({ prompt: "continue" });
   assert.equal((await query.result()).outputText, "continued");
@@ -203,6 +204,37 @@ test("an explicit Session starts Turns on the existing client connection", async
   ]);
 });
 
+test("a durable Session resumes on a new client connection", async () => {
+  const clientToHost = new PassThrough();
+  const hostToClient = new PassThrough();
+  const methods: string[] = [];
+  const host = runResumeFixtureHost(clientToHost, hostToClient, methods);
+  const client = await createAgentClient(
+    {
+      readable: hostToClient,
+      writable: clientToHost,
+      close: async () => {
+        clientToHost.end();
+        await host;
+      },
+    },
+    clientOptions,
+  );
+
+  const session = await client.sessions.resume("session-persisted");
+  assert.equal(session.id, "session-persisted");
+  assert.equal(session.lifetime, "durable");
+  await session.close();
+  await client.close();
+
+  assert.deepEqual(methods, [
+    "initialize",
+    "session/resume",
+    "session/close",
+    "shutdown",
+  ]);
+});
+
 test("Query cancel and close are idempotent and the Host Result remains authoritative", async () => {
   const clientToHost = new PassThrough();
   const hostToClient = new PassThrough();
@@ -530,12 +562,13 @@ async function runFixtureHost(
         jsonrpc: "2.0",
         id: request.id,
         result: {
-          protocolVersion: 3,
+          protocolVersion: 4,
           runtimeVersion: "0.2.17",
           stability: "not_delivered",
           capabilities: {
             sessionCreate: true,
-            sessionCreateLifetime: "connection",
+            sessionCreateLifetime: "durable",
+            sessionResume: true,
             query: true,
             queryCancel: true,
             sessionClose: true,
@@ -725,7 +758,7 @@ async function runSessionFixtureHost(
           sessionId: "session-explicit",
           sessionName: "Explicit",
           agent: "agentic",
-          lifetime: "connection",
+          lifetime: "durable",
         },
       });
       continue;
@@ -786,6 +819,59 @@ async function runSessionFixtureHost(
   }
 }
 
+async function runResumeFixtureHost(
+  requests: PassThrough,
+  responses: PassThrough,
+  methods: string[],
+): Promise<void> {
+  const lines = createInterface({ input: requests, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const request = JSON.parse(line) as {
+      id: number;
+      method: string;
+      params: Record<string, unknown>;
+    };
+    methods.push(request.method);
+    if (request.method === "initialize") {
+      write(responses, initializeResponse(request.id));
+      continue;
+    }
+    if (request.method === "session/resume") {
+      assert.deepEqual(request.params, { sessionId: "session-persisted" });
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: {
+          sessionId: "session-persisted",
+          sessionName: "Persisted",
+          agent: "agentic",
+          lifetime: "durable",
+          workspacePath: "D:/workspace/project",
+        },
+      });
+      continue;
+    }
+    if (request.method === "session/close") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { sessionId: "session-persisted", unloaded: true },
+      });
+      continue;
+    }
+    if (request.method === "shutdown") {
+      write(responses, {
+        jsonrpc: "2.0",
+        id: request.id,
+        result: { accepted: true },
+      });
+      responses.end();
+      return;
+    }
+    throw new Error(`Unexpected fixture method: ${request.method}`);
+  }
+}
+
 async function runCancelFixtureHost(
   requests: PassThrough,
   responses: PassThrough,
@@ -1227,12 +1313,13 @@ function initializeResponse(id: number): unknown {
     jsonrpc: "2.0",
     id,
     result: {
-      protocolVersion: 3,
+      protocolVersion: 4,
       runtimeVersion: "0.2.17",
       stability: "not_delivered",
       capabilities: {
         sessionCreate: true,
-        sessionCreateLifetime: "connection",
+        sessionCreateLifetime: "durable",
+        sessionResume: true,
         query: true,
         queryCancel: true,
         sessionClose: true,

sdk/typescript/test/fixtures/host.mjs

@@ -5,7 +5,7 @@ for await (const line of lines) {
   const request = JSON.parse(line);
   if (request.method === "initialize") {
     if (
-      request.params?.protocolVersion !== 3 ||
+      request.params?.protocolVersion !== 4 ||
       request.params?.model?.apiKey !== "fixture-secret"
     ) {
       throw new Error("Invalid initialize request");
@@ -14,12 +14,13 @@ for await (const line of lines) {
       jsonrpc: "2.0",
       id: request.id,
       result: {
-        protocolVersion: 3,
+        protocolVersion: 4,
         runtimeVersion: "fixture",
         stability: "not_delivered",
         capabilities: {
           sessionCreate: true,
-          sessionCreateLifetime: "connection",
+          sessionCreateLifetime: "durable",
+          sessionResume: true,
           query: true,
           queryCancel: true,
           sessionClose: true,

sdk/typescript/test/lifecycle-timeouts.test.ts

@@ -130,7 +130,7 @@ test("Session.close aborts an unresponsive Host after its cleanup deadline", asy
     sessionId: "session-timeout",
     sessionName: "timeout",
     agent: "agentic",
-    lifetime: "connection",
+    lifetime: "durable",
   };
   const createSession = Session.create as unknown as (
     owner: JsonRpcConnection,