feat(sdk): add DaemonSessionClient skeleton

packages/sdk-typescript/README.md

@@ -101,6 +101,56 @@ const query = qwen.query('Your prompt', {
 });
 ```
 
+### Experimental Daemon Session Client
+
+`DaemonSessionClient` is an experimental wrapper for clients that talk to a
+running `qwen serve` daemon over HTTP + SSE. It binds one daemon session so TUI,
+channel, IDE, or web backend adapters do not need to pass `sessionId` into every
+call.
+
+```typescript
+import { DaemonClient, DaemonSessionClient } from '@qwen-code/sdk';
+
+const daemon = new DaemonClient({
+  baseUrl: 'http://127.0.0.1:4170',
+  token: process.env['QWEN_SERVER_TOKEN'],
+});
+
+const caps = await daemon.capabilities();
+const session = await DaemonSessionClient.createOrAttach(daemon, {
+  workspaceCwd: caps.workspaceCwd,
+});
+
+const eventController = new AbortController();
+const eventTask = (async () => {
+  for await (const event of session.events({
+    signal: eventController.signal,
+  })) {
+    console.log(event.type, event.data);
+  }
+})();
+
+const result = await session.prompt({
+  prompt: [{ type: 'text', text: 'Summarize this workspace.' }],
+});
+
+eventController.abort();
+await eventTask;
+console.log(result.stopReason);
+```
+
+`session.events()` tracks the last seen SSE event id and reuses it on the next
+subscription by default. Pass `{ resume: false }` to start a fresh subscription
+without sending `Last-Event-ID`.
+
+When `createOrAttach()` is called with `modelServiceId`, the returned session
+client seeds its first event subscription with `Last-Event-ID: 0`. This replays
+the daemon ring from the oldest available event so adapters can observe
+attach-time `model_switch_failed` or `model_switched` events that are not
+reported on the create/attach HTTP response. Raw `DaemonClient` callers should
+pass `{ lastEventId: 0 }` on their first `subscribeEvents()` call when they use
+`modelServiceId`.
+
 ### Message Types
 
 The SDK provides type guards to identify different message types:

packages/sdk-typescript/src/daemon/DaemonSessionClient.ts

@@ -0,0 +1,155 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { DaemonClient } from './DaemonClient.js';
+import {
+  type CreateSessionRequest,
+  type PromptRequest,
+  type SubscribeOptions,
+} from './DaemonClient.js';
+import type {
+  DaemonEvent,
+  DaemonSession,
+  PermissionResponse,
+  PromptResult,
+  SetModelResult,
+} from './types.js';
+
+export interface DaemonSessionClientOptions {
+  client: DaemonClient;
+  session: DaemonSession;
+  /**
+   * Seed replay state for callers that persisted the last seen SSE event id.
+   * When omitted, the first event subscription starts live.
+   */
+  lastEventId?: number;
+}
+
+export interface DaemonSessionSubscribeOptions extends SubscribeOptions {
+  /**
+   * Reuse this client's last seen SSE event id when `lastEventId` is not
+   * supplied. Defaults to true so reconnecting client adapters get replay
+   * behavior without carrying the id through every call.
+   */
+  resume?: boolean;
+}
+
+/**
+ * Session-scoped wrapper around `DaemonClient`.
+ *
+ * `DaemonClient` mirrors the raw HTTP API and requires a `sessionId` on each
+ * method. `DaemonSessionClient` is the adapter-facing layer for TUI, channel,
+ * IDE, and web backends: it binds one daemon session, forwards the existing
+ * Stage 1 routes, and preserves SSE replay state. It intentionally does not
+ * interpret daemon event payloads; typed event reducers belong to the protocol
+ * schema layer.
+ */
+export class DaemonSessionClient {
+  readonly client: DaemonClient;
+  readonly session: DaemonSession;
+  private lastSeenEventId: number | undefined;
+  private subscriptionActive = false;
+
+  constructor(opts: DaemonSessionClientOptions) {
+    this.client = opts.client;
+    this.session = { ...opts.session };
+    this.lastSeenEventId = opts.lastEventId;
+  }
+
+  /**
+   * Creates a new daemon session or attaches to an existing matching session.
+   */
+  static async createOrAttach(
+    client: DaemonClient,
+    req: CreateSessionRequest = {},
+  ): Promise<DaemonSessionClient> {
+    const session = await client.createOrAttachSession(req);
+    // `modelServiceId` switch failures are reported on SSE, not the
+    // create/attach HTTP response. Seed the first subscription from the
+    // daemon replay ring so create-then-subscribe clients observe attach-time
+    // `model_switch_failed` / `model_switched` events.
+    const lastEventId = req.modelServiceId ? 0 : undefined;
+    return new DaemonSessionClient({ client, session, lastEventId });
+  }
+
+  get sessionId(): string {
+    return this.session.sessionId;
+  }
+
+  get workspaceCwd(): string {
+    return this.session.workspaceCwd;
+  }
+
+  get attached(): boolean {
+    return this.session.attached;
+  }
+
+  get lastEventId(): number | undefined {
+    return this.lastSeenEventId;
+  }
+
+  setLastEventId(lastEventId: number | undefined): void {
+    this.lastSeenEventId = lastEventId;
+  }
+
+  async prompt(
+    req: PromptRequest,
+    signal?: AbortSignal,
+  ): Promise<PromptResult> {
+    return await this.client.prompt(this.sessionId, req, signal);
+  }
+
+  async cancel(): Promise<void> {
+    await this.client.cancel(this.sessionId);
+  }
+
+  async setModel(modelId: string): Promise<SetModelResult> {
+    return await this.client.setSessionModel(this.sessionId, modelId);
+  }
+
+  async respondToPermission(
+    requestId: string,
+    response: PermissionResponse,
+  ): Promise<boolean> {
+    return await this.client.respondToPermission(requestId, response);
+  }
+
+  events(
+    opts: DaemonSessionSubscribeOptions = {},
+  ): AsyncGenerator<DaemonEvent> {
+    return this.subscribeEvents(opts);
+  }
+
+  async *subscribeEvents(
+    opts: DaemonSessionSubscribeOptions = {},
+  ): AsyncGenerator<DaemonEvent> {
+    if (this.subscriptionActive) {
+      throw new Error(
+        'Another event subscription is already active on this session. ' +
+          'Reuse the existing AsyncGenerator or create a separate DaemonSessionClient.',
+      );
+    }
+
+    this.subscriptionActive = true;
+    try {
+      const { resume = true, ...subscribeOpts } = opts;
+      const lastEventId =
+        subscribeOpts.lastEventId ??
+        (resume ? this.lastSeenEventId : undefined);
+
+      for await (const event of this.client.subscribeEvents(this.sessionId, {
+        ...subscribeOpts,
+        lastEventId,
+      })) {
+        yield event;
+        // Terminal/synthetic frames may not carry an SSE id.
+        if (event.id !== undefined) this.lastSeenEventId = event.id;
+      }
+    } finally {
+      this.subscriptionActive = false;
+    }
+  }
+}

packages/sdk-typescript/src/daemon/index.ts

@@ -12,6 +12,11 @@ export {
   type PromptRequest,
   type SubscribeOptions,
 } from './DaemonClient.js';
+export {
+  DaemonSessionClient,
+  type DaemonSessionClientOptions,
+  type DaemonSessionSubscribeOptions,
+} from './DaemonSessionClient.js';
 export { parseSseStream, SseFramingError } from './sse.js';
 export { DaemonCapabilityMissingError, requireWorkspaceCwd } from './types.js';
 export type {

packages/sdk-typescript/src/index.ts

@@ -8,6 +8,7 @@ export {
   DaemonCapabilityMissingError,
   DaemonClient,
   DaemonHttpError,
+  DaemonSessionClient,
   parseSseStream,
   requireWorkspaceCwd,
   SseFramingError,
@@ -18,6 +19,8 @@ export {
   type DaemonMode,
   type DaemonProtocolVersions,
   type DaemonSession,
+  type DaemonSessionClientOptions,
+  type DaemonSessionSubscribeOptions,
   type DaemonSessionSummary,
   type PermissionOutcome,
   type PermissionOutcomeCancelled,