@shellraining/dsh-side-chat 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,1038 @@
+// Generated by `pnpm run build`; edit src/, not this file.
+
+// src/shared/protocol.ts
+var PLUGIN_NAME = "dsh-side-chat";
+var API_PREFIX = "/dsh-side-chat/api/";
+var JSON_ROUTES = ["create", "prompt", "cancel", "close", "snapshot"];
+var EVENTS_ROUTE = "events";
+var SESSION_ID_PREFIX = "side-chat-";
+var BOUNDARY_SOURCE_KIND = "plugin:side-chat";
+var BOUNDARY_FIRST_LINE = "Side conversation boundary.";
+var CLIENT_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "user/message",
+  "assistant/message",
+  "assistant/attempt",
+  "tool/result",
+  "request/context",
+  "llm/retry-started"
+]);
+
+// src/host/util.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : void 0;
+}
+function errorMessage(error) {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.length > 500 ? `${text.slice(0, 499)}\u2026` : text;
+}
+function clip(text, max) {
+  if (typeof text !== "string") return "";
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
+function textBlocks(content) {
+  const list = asArray(content);
+  if (list === void 0) return [];
+  const out = [];
+  for (const block of list) {
+    if (isRecord(block) && block.type === "text" && typeof block.text === "string") out.push(block.text);
+  }
+  return out;
+}
+function failure(code, message) {
+  return message === void 0 ? { ok: false, code } : { ok: false, code, message };
+}
+function success(fields) {
+  return { ok: true, ...fields };
+}
+function toDisposer(value) {
+  if (typeof value !== "function") return void 0;
+  return () => {
+    Reflect.apply(value, void 0, []);
+  };
+}
+
+// src/host/http.ts
+var MAX_REQUEST_BODY_BYTES = 1024 * 1024;
+var SSE_HEADERS = Object.freeze({
+  "Content-Type": "text/event-stream; charset=utf-8",
+  "Cache-Control": "no-cache, no-transform",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no"
+});
+function isAsyncIterable(value) {
+  return isRecord(value) && typeof Reflect.get(value, Symbol.asyncIterator) === "function";
+}
+async function readRequestBody(req) {
+  if (!isAsyncIterable(req)) return "";
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    let bytes;
+    if (typeof chunk === "string") bytes = Buffer.from(chunk, "utf8");
+    else if (chunk instanceof Uint8Array) bytes = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    else throw new Error("request body chunk is not binary or text");
+    size += bytes.byteLength;
+    if (size > MAX_REQUEST_BODY_BYTES) throw new Error("request body exceeds the size limit");
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks, size).toString("utf8");
+}
+async function readJsonBody(req) {
+  const body = await readRequestBody(req);
+  return body.trim() === "" ? {} : JSON.parse(body);
+}
+function isJsonObject(value) {
+  return isRecord(value) && !Array.isArray(value);
+}
+function sendJson(res, value) {
+  let body;
+  try {
+    body = JSON.stringify(value);
+  } catch {
+    body = JSON.stringify(failure("internal", "response is not JSON-serializable"));
+  }
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(body);
+}
+function trySendJson(res, value, logger) {
+  try {
+    sendJson(res, value);
+  } catch (error) {
+    logger?.warn?.(`[side-chat] response write failed: ${errorMessage(error)}`);
+  }
+}
+function routeHandler(handler, logger) {
+  return async function sideChatRoute(req, res) {
+    let args = {};
+    try {
+      const parsed = await readJsonBody(req);
+      if (isJsonObject(parsed)) args = parsed;
+    } catch (error) {
+      logger?.warn?.(`[side-chat] rejected request: ${errorMessage(error)}`);
+      trySendJson(res, failure("internal", `invalid request body: ${errorMessage(error)}`), logger);
+      return;
+    }
+    let result;
+    try {
+      result = await handler(args);
+    } catch (error) {
+      logger?.warn?.(`[side-chat] route handler failed: ${errorMessage(error)}`);
+      result = failure("internal", errorMessage(error));
+    }
+    trySendJson(res, result, logger);
+  };
+}
+function sseFrame(eventName, value) {
+  return `event: ${eventName}
+data: ${JSON.stringify(value)}
+
+`;
+}
+var SSE_HEARTBEAT = ": ping\n\n";
+
+// src/host/service.ts
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+// src/host/entries.ts
+var SNAPSHOT_PAGE_LIMIT = 2e3;
+function isNumber(value) {
+  return typeof value === "number";
+}
+function projectEntry(event) {
+  if (!isRecord(event)) return void 0;
+  const { seq, type, time, surfaceOp } = event;
+  if (typeof seq !== "number" || typeof type !== "string" || !CLIENT_EVENT_TYPES.has(type)) return void 0;
+  const sourceEventSeqs = asArray(event.sourceEventSeqs);
+  return {
+    seq,
+    type,
+    ...typeof time === "number" || typeof time === "string" ? { time } : {},
+    data: event.data,
+    ...typeof surfaceOp === "string" ? { surfaceOp } : {},
+    ...sourceEventSeqs !== void 0 && sourceEventSeqs.every(isNumber) ? { sourceEventSeqs } : {}
+  };
+}
+function snapshotEntries(events, floor = 0, limit = SNAPSHOT_PAGE_LIMIT) {
+  const list = [];
+  for (const event of asArray(events) ?? []) {
+    const entry = projectEntry(event);
+    if (entry !== void 0 && entry.seq >= floor) list.push(entry);
+  }
+  if (limit > 0 && list.length > limit) return { entries: list.slice(list.length - limit), truncated: true };
+  return { entries: list, truncated: false };
+}
+
+// src/host/live.ts
+var LiveAttemptState = class {
+  /** Last accepted frame revision; 0 before the first frame. */
+  revision = 0;
+  /** The in-flight attempt, or undefined when no attempt is streaming. */
+  active = void 0;
+  /**
+   * Fold one assistant-stream frame into the live state.
+   * @param frame - an `agent/assistant-stream` frame (`start`, `chunk`, `end`).
+   * @returns true when the frame was accepted; malformed frames are ignored.
+   */
+  accept(frame) {
+    if (!isRecord(frame)) return false;
+    const { type, revision } = frame;
+    if (type !== "start" && type !== "chunk" && type !== "end") return false;
+    if (typeof revision !== "number" || !Number.isSafeInteger(revision)) return false;
+    let startAttemptId = "";
+    if (type === "start") {
+      const attemptId = frame.attemptId;
+      if (typeof attemptId !== "string" || attemptId === "") return false;
+      startAttemptId = attemptId;
+      if (revision === 1 && this.revision !== 0) {
+        this.revision = 0;
+        this.active = void 0;
+      }
+    }
+    if (revision !== this.revision + 1) {
+      this.active = void 0;
+      this.revision = revision;
+      return true;
+    }
+    this.revision = revision;
+    if (type === "start") {
+      this.active = {
+        attemptId: startAttemptId,
+        turn: frame.turn,
+        step: frame.step,
+        nextIndex: 0,
+        partials: /* @__PURE__ */ new Map(),
+        order: []
+      };
+      return true;
+    }
+    if (type === "chunk") {
+      const active = this.active;
+      if (active === void 0 || frame.attemptId !== active.attemptId || frame.index !== active.nextIndex) {
+        this.active = void 0;
+        return true;
+      }
+      pushStreamChunk(active.partials, active.order, frame.chunk);
+      active.nextIndex += 1;
+      return true;
+    }
+    this.active = void 0;
+    return true;
+  }
+  /**
+   * Drop the active attempt once its message committed. The loop commits the
+   * complete `assistant/message` / `assistant/attempt` before emitting the
+   * matching `end` frame, so the committed event is the first settlement signal.
+   * @param turn - durable turn of the committed event.
+   * @param step - durable step of the committed event.
+   * @returns whether the active attempt was settled.
+   */
+  settle(turn, step) {
+    const active = this.active;
+    if (active === void 0 || active.turn !== turn || active.step !== step) return false;
+    this.active = void 0;
+    return true;
+  }
+  /** Snapshot the live state, both for `live` frames and the snapshot route. */
+  snapshot() {
+    const active = this.active;
+    if (active === void 0) return { revision: this.revision, activeAttempt: null };
+    const blocks = [];
+    for (const index of active.order) {
+      const partial = active.partials.get(index);
+      if (partial === void 0) continue;
+      const block = renderStreamBlock(partial);
+      if (block !== void 0) blocks.push(block);
+    }
+    return {
+      revision: this.revision,
+      activeAttempt: {
+        attemptId: active.attemptId,
+        turn: active.turn,
+        step: active.step,
+        nextIndex: active.nextIndex,
+        blocks
+      }
+    };
+  }
+};
+function pushStreamChunk(partials, order, chunk) {
+  if (!isRecord(chunk) || typeof chunk.type !== "string") return;
+  const index = chunk.index;
+  if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0) return;
+  const create = (blockType) => {
+    const partial = {
+      blockType,
+      text: "",
+      toolCallId: void 0,
+      toolCallName: void 0,
+      toolCallArgs: "",
+      finalized: false
+    };
+    partials.set(index, partial);
+    order.push(index);
+    return partial;
+  };
+  const ensure = (blockType) => partials.get(index) ?? create(blockType);
+  switch (chunk.type) {
+    case "block-start":
+      if (!partials.has(index)) create(typeof chunk.blockType === "string" ? chunk.blockType : void 0);
+      return;
+    case "text-delta":
+    case "reasoning-delta": {
+      const partial = ensure(chunk.type === "text-delta" ? "text" : "reasoning");
+      if (partial.finalized) return;
+      if (typeof chunk.text === "string") partial.text += chunk.text;
+      return;
+    }
+    case "tool-call-delta": {
+      const partial = ensure("tool-call");
+      if (partial.finalized) return;
+      if (typeof chunk.id === "string") partial.toolCallId = chunk.id;
+      if (typeof chunk.name === "string" && chunk.name !== "") partial.toolCallName = chunk.name;
+      if (typeof chunk.argumentsDelta === "string") partial.toolCallArgs += chunk.argumentsDelta;
+      return;
+    }
+    case "block-end": {
+      const block = chunk.block;
+      const blockType = isRecord(block) ? block.type : void 0;
+      if (typeof blockType !== "string") return;
+      ensure(blockType).finalized = true;
+      return;
+    }
+    default:
+      return;
+  }
+}
+function renderStreamBlock(partial) {
+  switch (partial.blockType) {
+    case "text":
+      return partial.text === "" ? void 0 : { kind: "text", text: partial.text };
+    case "reasoning":
+      return partial.text === "" ? void 0 : { kind: "reasoning", text: partial.text };
+    case "tool-call":
+      return {
+        kind: "tool-call",
+        callId: partial.toolCallId ?? "",
+        name: partial.toolCallName ?? "",
+        argsRaw: partial.toolCallArgs
+      };
+    default:
+      return void 0;
+  }
+}
+
+// src/host/seed.ts
+var RECENT_CONTEXT_MAX_CHARS = 6e3;
+function completedTurnPrefix(events) {
+  const list = asArray(events);
+  if (list === void 0) return [];
+  for (let index = list.length - 1; index >= 0; index -= 1) {
+    const event = list[index];
+    if (isRecord(event) && event.type === "turn/end") return list.slice(0, index + 1);
+  }
+  return [];
+}
+function isSystemNoise(text) {
+  if (typeof text !== "string") return false;
+  return text.includes("<system-reminder>") || text.includes("<system_reminder>") || text.trimStart().startsWith("Current runtime context");
+}
+function contextLine(event) {
+  const data = isRecord(event.data) ? event.data : void 0;
+  switch (event.type) {
+    case "user/message": {
+      const source = isRecord(data?.source) ? data.source : void 0;
+      if (source?.kind !== "user") return void 0;
+      const text = textBlocks(data?.content).filter((block) => !isSystemNoise(block)).join(" ").trim();
+      return text === "" ? void 0 : `User: ${clip(text, 500)}`;
+    }
+    case "assistant/message": {
+      const message = isRecord(data?.message) ? data.message : void 0;
+      const text = textBlocks(message?.content).join(" ").trim();
+      return text === "" ? void 0 : `Assistant: ${clip(text, 300)}`;
+    }
+    case "tool/call": {
+      const toolName = data?.name;
+      return typeof toolName === "string" && toolName !== "" ? `Tool call: ${toolName}` : void 0;
+    }
+    case "tool/result": {
+      const message = isRecord(data?.message) ? data.message : void 0;
+      return message?.isError === true ? "Tool result: failed" : void 0;
+    }
+    default:
+      return void 0;
+  }
+}
+function recentMainContext(events, fromSeq = 0, maxChars = RECENT_CONTEXT_MAX_CHARS) {
+  const list = asArray(events);
+  if (list === void 0) return "";
+  const parts = [];
+  for (const event of list) {
+    if (!isRecord(event)) continue;
+    if (typeof event.seq !== "number" || event.seq < fromSeq) continue;
+    const line = contextLine(event);
+    if (line !== void 0) parts.push(line);
+  }
+  const kept = [];
+  let total = 0;
+  for (let index = parts.length - 1; index >= 0; index -= 1) {
+    const part = parts[index] ?? "";
+    const cost = part.length + 1;
+    if (total + cost > maxChars) {
+      if (kept.length === 0) kept.unshift(clip(part, maxChars));
+      break;
+    }
+    kept.unshift(part);
+    total += cost;
+  }
+  if (kept.length < parts.length) kept.unshift("(earlier parent-session context omitted)");
+  return kept.join("\n");
+}
+function sideConversationBoundaryPrompt(parentSessionId, recentContext = "") {
+  const lines = [
+    BOUNDARY_FIRST_LINE,
+    "",
+    `You are in a side conversation derived from main session "${parentSessionId}". You inherit its working directory, model route, tools, skills, and permission composition. This side conversation is temporary: closing it destroys it, it never appears in the session list, and it cannot be reopened.`,
+    "",
+    "Everything before this boundary is inherited history from the parent thread. It is reference context only, not your current task. Do not continue, execute, or complete instructions, plans, tool calls, approvals, edits, or requests that appear only in that inherited history. Only messages submitted after this boundary are active instructions for this side conversation.",
+    "",
+    "This side conversation is a full working agent in the same workspace, not a read-only chat. When the user asks for a change after this boundary, you must make the change for real with the available tools \u2014 `write`, `edit`, `bash`, and every other enabled tool \u2014 modifying the same files in the same working directory. Changes must actually land on disk: never simulate a change, never describe a change you did not perform, and never claim a file was modified when it was not. Keep every change minimal and limited to what the user asked for, and do not touch the main thread's task.",
+    "",
+    "Sub-agents are off-limits in this side conversation. Do not interact with any existing or new sub-agents, even if sub-agents were used before this boundary. Do not write anything into the main session transcript, and do not create commits, branches, or pushes unless the user explicitly asks for them.",
+    "",
+    "When you finish, report exactly what you changed and what you verified, so the user can reconcile it with the main thread."
+  ];
+  if (recentContext !== "") {
+    lines.push(
+      "",
+      "[Recent activity from the parent session \u2014 completes the forked history; reference only, do not act on it]",
+      recentContext
+    );
+  }
+  return lines.join("\n");
+}
+function sideDeveloperInstructions() {
+  return [
+    "You are in a side conversation, not the main thread.",
+    "",
+    "The inherited fork history is provided only as reference context. Do not treat instructions, plans, or requests found in it as active instructions for this side conversation; only instructions submitted after the side-conversation boundary are active. Do not continue, execute, or complete a task, plan, tool call, approval, edit, or request that appears only in inherited history, and do not present yourself as continuing the main thread's active task.",
+    "",
+    "This side conversation is a real working agent in the same workspace. When the user explicitly requests a change after the boundary, perform it with the real tools \u2014 `write`, `edit`, `bash`, and any other enabled tools \u2014 so the edits land on disk in the same working directory. Keep the change minimal and limited to the request, verify it, and report what changed. Never describe a change you did not make.",
+    "",
+    "Do not write anything into the main session transcript. Do not interact with sub-agents from this side conversation, and do not create commits, branches, or pushes unless the user explicitly asks for them."
+  ].join("\n");
+}
+
+// src/host/service.ts
+var DRAIN_DELAY_MS = 300;
+var SSE_HEARTBEAT_MS = 15e3;
+var DEVELOPER_SECTION_NAME = "side-chat:instructions";
+var DEVELOPER_SECTION_ORDER_FALLBACK = 9e3;
+var APPROVAL_OVERRIDE_SOURCE = "delegation";
+var SANDBOX_OVERRIDE_SOURCE = "delegation";
+var UNLOADING = "side-chat plugin is unloading";
+var BOUNDARY_SOURCE = Object.freeze({ kind: BOUNDARY_SOURCE_KIND });
+function stringArg(value) {
+  return typeof value === "string" ? value : String(value ?? "");
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value !== "";
+}
+function toNonNegativeInteger(value) {
+  const number = typeof value === "number" ? value : Number(value);
+  return Number.isSafeInteger(number) && number >= 0 ? number : void 0;
+}
+function artifactDirectory(header, location) {
+  const path = isRecord(location) ? location.path : void 0;
+  const id = header?.id;
+  if (typeof path !== "string" || !isAbsolute(path)) return void 0;
+  if (typeof id !== "string" || !id.startsWith(SESSION_ID_PREFIX)) return void 0;
+  const dir = dirname(path);
+  return basename(dir) === id ? dir : void 0;
+}
+function requestContextWindow(agent) {
+  const session = agent.session;
+  if (session === void 0 || typeof session.requestContext !== "function") return void 0;
+  let context;
+  try {
+    context = session.requestContext();
+  } catch {
+    return void 0;
+  }
+  const value = isRecord(context) ? context.contextWindow : void 0;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function developerSectionOrder(systemPrompt) {
+  const suffixOrder = systemPrompt.getSectionOrder?.("DEPLOYMENT_PERSONA_SUFFIX");
+  return typeof suffixOrder === "number" && Number.isFinite(suffixOrder) ? suffixOrder - 10 : DEVELOPER_SECTION_ORDER_FALLBACK;
+}
+function routeOptions(parent) {
+  const session = parent.session;
+  const requestHeader = typeof session?.requestHeader === "function" ? session.requestHeader() : void 0;
+  const config = isRecord(requestHeader) ? requestHeader.config : void 0;
+  const route = isRecord(config) && nonEmptyString(config.provider) && nonEmptyString(config.model) ? config : isRecord(parent.options) ? parent.options : {};
+  const { provider, model, reasoningEffort, maxTokens } = route;
+  return {
+    ...typeof provider === "string" ? { provider } : {},
+    ...typeof model === "string" ? { model } : {},
+    ...typeof reasoningEffort === "string" ? { reasoningEffort } : {},
+    ...typeof maxTokens === "number" ? { maxTokens } : {}
+  };
+}
+var SideChatService = class {
+  ctx;
+  entries = /* @__PURE__ */ new Map();
+  /** identity -> sessionId (idempotent create and attach). */
+  byIdentity = /* @__PURE__ */ new Map();
+  /** identity -> in-flight create result (deduplicates concurrent creates). */
+  pendingCreates = /* @__PURE__ */ new Map();
+  /** sessionId -> last contained agent failure, for the panel error banner. */
+  lastErrors = /* @__PURE__ */ new Map();
+  /** sessionId -> live attempt fold (fed even with no stream client connected). */
+  liveStates = /* @__PURE__ */ new Map();
+  /** sessionId -> open SSE streams. */
+  streams = /* @__PURE__ */ new Map();
+  /** Disposers of the Cordis event listeners, called at plugin unload. */
+  listenerDisposers = [];
+  /** Set at plugin unload so a creation still in flight cannot leak its agent. */
+  closing = false;
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.listen("agent/error", (payload) => this.onAgentError(payload));
+    this.listen("agent/status", (payload) => this.onAgentStatus(payload));
+    this.listen("agent/assistant-stream", (payload) => this.onAssistantStream(payload));
+    this.listen("session/event", (session, event) => this.onSessionEvent(session, event));
+  }
+  listen(eventName, listener) {
+    const dispose = toDisposer(this.ctx.on?.(eventName, listener));
+    if (dispose !== void 0) this.listenerDisposers.push(dispose);
+  }
+  warn(message) {
+    this.ctx.logger?.warn?.(`[side-chat] ${message}`);
+  }
+  entryOf(sessionId) {
+    return sessionId === "" ? void 0 : this.entries.get(sessionId);
+  }
+  /** The id of an owned side agent named by an `agent/*` event payload. */
+  ownedAgentId(payload) {
+    const agent = isRecord(payload) ? payload.agent : void 0;
+    const id = isRecord(agent) ? agent.id : void 0;
+    return typeof id === "string" && this.entries.has(id) ? id : void 0;
+  }
+  /** Record one contained side-session failure and push it to open streams. */
+  onAgentError(payload) {
+    const id = this.ownedAgentId(payload);
+    if (id === void 0) return;
+    const error = isRecord(payload) ? payload.error : void 0;
+    const message = error instanceof Error ? error.message : String((isRecord(error) ? error.message : void 0) ?? error);
+    this.lastErrors.set(id, message);
+    this.broadcast(id, "error", { message });
+  }
+  /** Push one agent status transition to open streams of an owned session. */
+  onAgentStatus(payload) {
+    const id = this.ownedAgentId(payload);
+    if (id === void 0) return;
+    const status = isRecord(payload) ? payload.status : void 0;
+    this.broadcast(id, "status", { status: stringArg(status), running: status === "running" });
+  }
+  /**
+   * Fold one attempt frame into the session's live state. State is kept even
+   * without a stream client because the snapshot route serves it as fallback.
+   */
+  onAssistantStream(payload) {
+    const id = this.ownedAgentId(payload);
+    if (id === void 0) return;
+    let state = this.liveStates.get(id);
+    if (state === void 0) {
+      state = new LiveAttemptState();
+      this.liveStates.set(id, state);
+    }
+    if (state.accept(isRecord(payload) ? payload.frame : void 0)) this.broadcastLive(id);
+  }
+  /**
+   * Observe committed session events: settle the active live attempt when its
+   * message commits (before the matching `end` frame arrives) and forward every
+   * new committed event to open streams in sequence order.
+   */
+  onSessionEvent(session, event) {
+    const record = isRecord(session) ? session : void 0;
+    const header = isRecord(record?.header) ? record.header : void 0;
+    const id = typeof record?.id === "string" ? record.id : header?.id;
+    if (typeof id !== "string" || !this.entries.has(id)) return;
+    if (!isRecord(event)) return;
+    const state = this.liveStates.get(id);
+    if (state !== void 0 && (event.type === "assistant/message" || event.type === "assistant/attempt")) {
+      const data = isRecord(event.data) ? event.data : void 0;
+      if (state.settle(data?.turn, data?.step)) this.broadcastLive(id);
+    }
+    this.broadcastEvent(id, event);
+  }
+  /** Push an authoritative replacement of one session's live state to streams. */
+  broadcastLive(sessionId) {
+    const streams = this.streams.get(sessionId);
+    if (streams === void 0 || streams.size === 0) return;
+    this.broadcast(sessionId, "live", { live: this.liveOf(sessionId) });
+  }
+  /** Write one SSE frame to every open stream of one side session. */
+  broadcast(sessionId, eventName, value) {
+    const streams = this.streams.get(sessionId);
+    if (streams === void 0 || streams.size === 0) return;
+    let frame;
+    try {
+      frame = sseFrame(eventName, value);
+    } catch (error) {
+      this.warn(`${eventName} frame not serializable: ${errorMessage(error)}`);
+      return;
+    }
+    for (const stream of [...streams]) this.writeStream(stream, frame);
+  }
+  /** Write one committed session event to streams that have not seen its seq. */
+  broadcastEvent(sessionId, event) {
+    const streams = this.streams.get(sessionId);
+    if (streams === void 0 || streams.size === 0) return;
+    const entry = projectEntry(event);
+    if (entry === void 0) return;
+    let frame;
+    try {
+      frame = sseFrame("event", { entry });
+    } catch (error) {
+      this.warn(`event frame not serializable: ${errorMessage(error)}`);
+      return;
+    }
+    for (const stream of [...streams]) {
+      if (entry.seq < stream.floor || entry.seq <= stream.cursor) continue;
+      if (this.writeStream(stream, frame)) stream.cursor = entry.seq;
+    }
+  }
+  /** Write raw SSE text to one stream; a failed or ended carrier ends the stream. */
+  writeStream(stream, text) {
+    if (stream.closed) return false;
+    if (stream.res.writableEnded || stream.res.destroyed) {
+      this.endStream(stream);
+      return false;
+    }
+    try {
+      stream.res.write(text);
+      return true;
+    } catch (error) {
+      this.warn(`event stream write failed: ${errorMessage(error)}`);
+      this.endStream(stream);
+      return false;
+    }
+  }
+  /** Tear down one stream: clear its heartbeat, detach listeners, end the response. */
+  endStream(stream) {
+    if (stream.closed) return;
+    stream.closed = true;
+    if (stream.heartbeat !== void 0) {
+      clearInterval(stream.heartbeat);
+      stream.heartbeat = void 0;
+    }
+    const streams = this.streams.get(stream.sessionId);
+    if (streams !== void 0) {
+      streams.delete(stream);
+      if (streams.size === 0) this.streams.delete(stream.sessionId);
+    }
+    const detach = stream.detach;
+    stream.detach = void 0;
+    try {
+      detach?.();
+    } catch {
+    }
+    try {
+      if (!stream.res.writableEnded) stream.res.end();
+    } catch {
+    }
+  }
+  /** End every open stream of one side session (close / unload). */
+  endStreamsFor(sessionId) {
+    const streams = this.streams.get(sessionId);
+    if (streams === void 0) return;
+    for (const stream of [...streams]) this.endStream(stream);
+    this.streams.delete(sessionId);
+  }
+  /** Current live state of one side session for `live` frames and snapshots. */
+  liveOf(sessionId) {
+    return this.liveStates.get(sessionId)?.snapshot() ?? null;
+  }
+  /**
+   * Create (or re-attach to) the side session of one identity. The identity is
+   * the opaque client `instanceKey` when one was sent (one side session per
+   * client tab instance), otherwise `source:<sourceId>` (one per parent). With
+   * `attachOnly`, an existing or in-flight session is returned and a missing
+   * one is `not-found`: no agent is ever created, and the parent need not be live.
+   */
+  async create(args) {
+    if (this.closing) return failure("internal", UNLOADING);
+    const sourceId = stringArg(args.sourceId);
+    if (sourceId === "") return failure("unknown-source", "missing sourceId");
+    const attachOnly = args.attachOnly === true;
+    let parent;
+    if (!attachOnly) {
+      parent = this.ctx.agents.get(sourceId);
+      if (parent === void 0) return failure("unknown-source", `unknown source session "${sourceId}"`);
+    }
+    const instanceKey = args.instanceKey;
+    const identity = nonEmptyString(instanceKey) ? instanceKey : `source:${sourceId}`;
+    const existingId = this.byIdentity.get(identity);
+    if (existingId !== void 0) {
+      const existing = this.entries.get(existingId);
+      if (existing !== void 0) {
+        return success({ sessionId: existingId, inheritedEventCount: existing.inheritedEventCount });
+      }
+      this.byIdentity.delete(identity);
+    }
+    const inflight = this.pendingCreates.get(identity);
+    if (inflight !== void 0) return await inflight;
+    if (parent === void 0) return failure("not-found");
+    const started = this.createSession(sourceId, parent, identity);
+    this.pendingCreates.set(identity, started);
+    try {
+      return await started;
+    } finally {
+      if (this.pendingCreates.get(identity) === started) this.pendingCreates.delete(identity);
+    }
+  }
+  async createSession(sourceId, parent, identity) {
+    const ctx = this.ctx;
+    const parentSession = parent.session;
+    try {
+      const events = typeof parentSession?.snapshotEvents === "function" ? parentSession.snapshotEvents() : [];
+      const seed = completedTurnPrefix(events);
+      const inheritedEventCount = seed.length;
+      const recentContext = recentMainContext(events, inheritedEventCount);
+      const header = parentSession?.header ?? {};
+      const agentPreset = ctx.get("agentPresets")?.composedPreset?.(parent.ctx);
+      const sandboxMode = ctx.get("sandboxPolicy")?.overrideOf?.(parentSession);
+      const approvalPolicy = ctx.get("approval")?.overrideOf?.(parentSession);
+      const sessionId = `${SESSION_ID_PREFIX}${randomUUID()}`;
+      const boundaryText = sideConversationBoundaryPrompt(String(header.id ?? sourceId), recentContext);
+      const meta = {
+        ...typeof header.cwd === "string" ? { cwd: header.cwd } : {},
+        ...nonEmptyString(agentPreset) ? { agentPreset } : {},
+        ...inheritedEventCount > 0 ? { isSeeded: true } : {},
+        origin: "subagent"
+      };
+      const boundary = {
+        id: `${SESSION_ID_PREFIX}boundary-${randomUUID()}`,
+        role: "user",
+        content: [{ type: "text", text: boundaryText }],
+        source: BOUNDARY_SOURCE
+      };
+      const setup = (childCtx, agent) => {
+        childCtx.get("agentPresets")?.composeFrom?.(childCtx, parent.ctx);
+        const session = agent.session;
+        if (session === void 0) throw new Error("side agent has no session");
+        if (sandboxMode !== void 0) {
+          session.append("sandbox/mode", { mode: sandboxMode, source: SANDBOX_OVERRIDE_SOURCE });
+        }
+        if (approvalPolicy !== void 0) {
+          session.append("approval/policy", { policy: approvalPolicy, source: APPROVAL_OVERRIDE_SOURCE });
+        }
+        session.append("user/message", boundary, { surfaceOp: "append" });
+        childCtx.systemPrompt.section({
+          name: DEVELOPER_SECTION_NAME,
+          order: developerSectionOrder(childCtx.systemPrompt),
+          text: sideDeveloperInstructions()
+        });
+      };
+      const handle = await ctx.agents.create({
+        sessionId,
+        meta,
+        ...inheritedEventCount > 0 ? { seed, inheritedEventCount } : {},
+        agentOptions: routeOptions(parent),
+        setup
+      });
+      if (this.closing) {
+        await this.retire(sessionId, handle);
+        return failure("internal", UNLOADING);
+      }
+      this.entries.set(sessionId, { sessionId, identity, handle, inheritedEventCount });
+      this.byIdentity.set(identity, sessionId);
+      return success({ sessionId, inheritedEventCount });
+    } catch (error) {
+      return failure("create-failed", errorMessage(error));
+    }
+  }
+  async prompt(args) {
+    const sessionId = stringArg(args.sessionId);
+    const text = typeof args.text === "string" ? args.text : "";
+    if (text.trim() === "") return failure("empty-prompt");
+    const entry = this.entryOf(sessionId);
+    if (entry === void 0) return failure("not-found");
+    try {
+      entry.handle.agent.followup({
+        id: `${SESSION_ID_PREFIX}message-${randomUUID()}`,
+        role: "user",
+        content: [{ type: "text", text }],
+        source: { kind: "user" }
+      });
+    } catch (error) {
+      return failure("prompt-failed", errorMessage(error));
+    }
+    return success({});
+  }
+  async cancel(args) {
+    const entry = this.entryOf(stringArg(args.sessionId));
+    if (entry === void 0) return failure("not-found");
+    entry.handle.agent.cancel({ kind: "user" });
+    return success({});
+  }
+  async snapshot(args) {
+    const sessionId = stringArg(args.sessionId);
+    const entry = this.entryOf(sessionId);
+    if (entry === void 0) return failure("not-found");
+    return success(this.baseline(entry, args.fromSeq).payload);
+  }
+  async close(args) {
+    const sessionId = stringArg(args.sessionId);
+    const entry = this.entryOf(sessionId);
+    if (entry === void 0) return failure("not-found");
+    this.entries.delete(sessionId);
+    if (this.byIdentity.get(entry.identity) === sessionId) this.byIdentity.delete(entry.identity);
+    this.lastErrors.delete(sessionId);
+    this.liveStates.delete(sessionId);
+    this.endStreamsFor(sessionId);
+    const artifactDir = this.locateArtifact(entry.handle.agent);
+    try {
+      await entry.handle.dispose();
+    } catch (error) {
+      return failure("dispose-failed", errorMessage(error));
+    }
+    if (artifactDir !== void 0) await this.removeArtifact(sessionId, artifactDir);
+    return success({});
+  }
+  /**
+   * The event floor of one owned session: never below the inherited prefix,
+   * never below an explicitly requested sequence.
+   */
+  eventFloor(entry, fromSeq) {
+    const fromSession = entry.handle.agent.session?.inheritedEventCount;
+    const inheritedEventCount = Number.isSafeInteger(entry.inheritedEventCount) ? entry.inheritedEventCount : typeof fromSession === "number" && Number.isSafeInteger(fromSession) ? fromSession : 0;
+    const requested = toNonNegativeInteger(fromSeq);
+    return { inheritedEventCount, floor: Math.max(inheritedEventCount, requested ?? inheritedEventCount) };
+  }
+  /** The baseline shared by the `snapshot` route and the stream's `hello` frame. */
+  baseline(entry, fromSeq) {
+    const { sessionId, handle: { agent } } = entry;
+    const { inheritedEventCount, floor } = this.eventFloor(entry, fromSeq);
+    const session = agent.session;
+    const events = typeof session?.snapshotEvents === "function" ? session.snapshotEvents(floor) : [];
+    const { entries, truncated } = snapshotEntries(events, floor);
+    const status = stringArg(agent.status);
+    const contextWindow = requestContextWindow(agent);
+    return {
+      floor,
+      payload: {
+        inheritedEventCount,
+        status,
+        running: status === "running",
+        lastError: this.lastErrors.get(sessionId) ?? null,
+        ...contextWindow === void 0 ? {} : { contextWindow },
+        entries,
+        truncated,
+        live: this.liveOf(sessionId)
+      }
+    };
+  }
+  /**
+   * Serve one `text/event-stream` stream of the live assistant attempt and newly
+   * committed events. `webServer.register` hands this a raw Node request and
+   * response with direct ownership, so failure before the stream starts is a
+   * normal JSON response (the client then falls back to polling) and every
+   * write/cleanup is contained here.
+   */
+  async openEventStream(req, res) {
+    let args;
+    try {
+      const parsed = await readJsonBody(req);
+      if (!isJsonObject(parsed)) throw new Error("request body must be a JSON object");
+      args = parsed;
+    } catch (error) {
+      this.warn(`rejected event stream request: ${errorMessage(error)}`);
+      trySendJson(res, failure("internal", `invalid request body: ${errorMessage(error)}`), this.ctx.logger);
+      return;
+    }
+    const entry = this.entryOf(stringArg(args.sessionId));
+    if (entry === void 0) {
+      trySendJson(res, failure("not-found"), this.ctx.logger);
+      return;
+    }
+    try {
+      this.startEventStream(req, res, entry, args.fromSeq);
+    } catch (error) {
+      this.warn(`event stream setup failed: ${errorMessage(error)}`);
+      try {
+        res.end();
+      } catch {
+      }
+    }
+  }
+  /**
+   * Write the stream headers and the `hello` baseline, then register the stream
+   * for subsequent committed events, live frames and status/error frames. Runs
+   * synchronously so no session event can slip between the hello snapshot and
+   * the stream's registration.
+   */
+  startEventStream(req, res, entry, fromSeq) {
+    const { sessionId } = entry;
+    const { payload, floor } = this.baseline(entry, fromSeq);
+    const last = payload.entries.at(-1);
+    const stream = {
+      sessionId,
+      res,
+      floor,
+      // Everything at or below this seq is already represented in the hello frame.
+      cursor: last === void 0 ? floor - 1 : last.seq,
+      heartbeat: void 0,
+      detach: void 0,
+      closed: false
+    };
+    res.writeHead(200, SSE_HEADERS);
+    const onClose = () => this.endStream(stream);
+    req.on("close", onClose);
+    res.on("close", onClose);
+    stream.detach = () => {
+      req.off("close", onClose);
+      res.off("close", onClose);
+    };
+    this.writeStream(stream, sseFrame("hello", success(payload)));
+    if (stream.closed) return;
+    let streams = this.streams.get(sessionId);
+    if (streams === void 0) {
+      streams = /* @__PURE__ */ new Set();
+      this.streams.set(sessionId, streams);
+    }
+    streams.add(stream);
+    const heartbeat = setInterval(() => this.writeStream(stream, SSE_HEARTBEAT), SSE_HEARTBEAT_MS);
+    heartbeat.unref();
+    stream.heartbeat = heartbeat;
+  }
+  /** Resolve the persisted artifact directory before disposal, while the header is still live. */
+  locateArtifact(agent) {
+    try {
+      const persistence = this.ctx.get("sessionPersistence");
+      const header = agent.session?.header;
+      if (typeof persistence?.locate !== "function" || header === void 0) return void 0;
+      return artifactDirectory(header, persistence.locate(header));
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Delete only this plugin's own persisted session directory, after a short
+   * drain delay. Runs in the host process (no shell, no sandbox escalation);
+   * `force` + `recursive` make a missing artifact a no-op, and any failure only
+   * warns because the agent is already disposed.
+   */
+  async removeArtifact(sessionId, dir) {
+    if (!sessionId.startsWith(SESSION_ID_PREFIX) || !isAbsolute(dir) || basename(dir) !== sessionId) {
+      this.warn(`artifact cleanup for "${sessionId}" refused: unexpected directory "${dir}"`);
+      return;
+    }
+    try {
+      await delay(DRAIN_DELAY_MS);
+      await rm(dir, { recursive: true, force: true });
+    } catch (error) {
+      this.warn(`artifact cleanup for "${sessionId}" failed: ${errorMessage(error)}`);
+    }
+  }
+  /**
+   * Dispose one side agent during unload and, once disposal succeeded, remove
+   * its artifact in the background. The directory is located before disposal.
+   * Never rejects.
+   */
+  async retire(sessionId, handle) {
+    const dir = this.locateArtifact(handle.agent);
+    try {
+      await handle.dispose();
+    } catch (error) {
+      this.warn(`dispose of "${sessionId}" during unload failed: ${errorMessage(error)}`);
+      return;
+    }
+    if (dir !== void 0) void this.removeArtifact(sessionId, dir);
+  }
+  /** Plugin unload: detach listeners, end streams, dispose every side agent. */
+  disposeAll() {
+    this.closing = true;
+    for (const dispose of this.listenerDisposers) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+    this.listenerDisposers.length = 0;
+    for (const sessionId of [...this.streams.keys()]) this.endStreamsFor(sessionId);
+    this.streams.clear();
+    this.liveStates.clear();
+    for (const entry of this.entries.values()) void this.retire(entry.sessionId, entry.handle);
+    this.entries.clear();
+    this.byIdentity.clear();
+    this.pendingCreates.clear();
+    this.lastErrors.clear();
+  }
+};
+
+// src/host/index.ts
+var name = PLUGIN_NAME;
+var inject = ["webServer", "agents"];
+function apply(ctx) {
+  const warn = (message) => ctx.logger?.warn?.(`[side-chat] ${message}`);
+  const service = new SideChatService(ctx);
+  const webServer = ctx.webServer;
+  if (webServer !== void 0 && typeof webServer.register === "function") {
+    const routeDisposers = [];
+    const register = (route) => {
+      try {
+        const dispose = toDisposer(webServer.register?.(route));
+        if (dispose !== void 0) routeDisposers.push(dispose);
+      } catch (error) {
+        warn(`route ${route.path} not registered: ${errorMessage(error)}`);
+      }
+    };
+    const table = {
+      create: (args) => service.create(args),
+      prompt: (args) => service.prompt(args),
+      cancel: (args) => service.cancel(args),
+      close: (args) => service.close(args),
+      snapshot: (args) => service.snapshot(args)
+    };
+    for (const route of JSON_ROUTES) {
+      register({ kind: "exact", path: `${API_PREFIX}${route}`, handler: routeHandler(table[route], ctx.logger) });
+    }
+    register({
+      kind: "exact",
+      path: `${API_PREFIX}${EVENTS_ROUTE}`,
+      handler: (req, res) => service.openEventStream(req, res).catch((error) => {
+        warn(`event stream failed: ${errorMessage(error)}`);
+        try {
+          res.end();
+        } catch {
+        }
+      })
+    });
+    ctx.effect(() => () => {
+      for (const dispose of routeDisposers) {
+        try {
+          dispose();
+        } catch (error) {
+          warn(`route disposal failed: ${errorMessage(error)}`);
+        }
+      }
+      routeDisposers.length = 0;
+    }, "side-chat: routes");
+  } else {
+    warn("webServer is unavailable; the client RPC surface is not mounted");
+  }
+  ctx.effect(() => () => service.disposeAll(), "side-chat: sessions");
+}
+export {
+  apply,
+  inject,
+  name
+};