negotium 0.1.6 → 0.1.8

package/dist/runtime/src/agents/rollout/shared.ts

@@ -0,0 +1,205 @@
+/**
+ * Helpers shared by every agent's rollout encoder.
+ *
+ * Each rollout file under `agents/rollout/<agent>.ts` materializes a
+ * synthetic SDK-native JSONL from a provider-agnostic `ConversationEntry`
+ * stream. The cwd validation, UUID shape check, and chat-pair extraction
+ * are identical regardless of agent, so they live here.
+ */
+
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DM_WORKSPACE_DIR, TOPIC_WORKSPACE_DIR, WORKSPACE_DIR } from "#platform/config";
+import { logger } from "#platform/logger";
+import type { ConversationEntry } from "#storage/conversations";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Captured fixture snapshots — `claude-attachments.jsonl`, `codex-shell.jsonl`,
+ * etc. — live one level above the per-agent rollout files (under
+ * `agents/fixtures/`) so each agent can pull from the same directory without
+ * duplicating fixtures.
+ *
+ * To refresh fixtures: run any live Codex/Claude session, copy the first few
+ * non-conversational entries from the resulting rollout file, and update
+ * `src/agents/fixtures/{codex-shell,claude-attachments}.jsonl`.
+ */
+export const FIXTURES_DIR = join(__dirname, "..", "fixtures");
+
+/** Deep-clone to avoid mutating cached fixture objects. */
+export function clone<T>(obj: T): T {
+  return structuredClone(obj);
+}
+
+/**
+ * UUID v4/v7 shape — both 36 chars with the standard 8-4-4-4-12 hex layout.
+ * We do not enforce the version nibble because randomUUID (v4) and uuidv7
+ * coexist; the only requirement for our caller is that the value is safe to
+ * embed in a path component and that the SDK accepts it as a session/thread
+ * identifier.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function assertUuidLike(label: string, value: string): void {
+  if (!UUID_RE.test(value)) {
+    throw new Error(`rollout: ${label} is not a UUID-shaped string: ${value}`);
+  }
+}
+
+/**
+ * Reject cwds that escape Otium-managed workspace roots. We use `path.resolve`
+ * to normalize `..` traversal; symlink-based escapes are out of scope (the
+ * workspace roots are not expected to contain attacker-controlled symlinks).
+ */
+function assertCwdInWorkspace(cwd: string): void {
+  const abs = resolve(cwd);
+  // Synthetic rollouts for spawn/fork must be written under the same root as
+  // live topic turns or provider resume looks in a different cwd hash than the
+  // one we generated.
+  const roots = [WORKSPACE_DIR, DM_WORKSPACE_DIR, TOPIC_WORKSPACE_DIR];
+  const ok = roots.some((root) => abs === root || abs.startsWith(`${root}/`));
+  if (!ok) {
+    throw new Error(`rollout: cwd outside trusted workspace roots: ${cwd} (resolved=${abs})`);
+  }
+}
+
+/** Best-effort guarantee that the resumed cwd will exist when the SDK stats it. */
+export function ensureCwdExists(cwd: string): void {
+  assertCwdInWorkspace(cwd);
+  try {
+    mkdirSync(cwd, { recursive: true });
+  } catch (err) {
+    logger.warn({ err, cwd }, "rollout: ensureCwdExists failed — caller should pre-create cwd");
+  }
+}
+
+/**
+ * Length-bound a string by Unicode code points rather than UTF-16 units, so a
+ * truncation never lands in the middle of a multi-byte sequence and produces
+ * a malformed character. Used for in-line tool annotations where we only need
+ * a rough preview, not the full payload.
+ */
+function truncate(text: string, n: number): string {
+  const cps = Array.from(text);
+  return cps.length > n ? `${cps.slice(0, n).join("")}…` : text;
+}
+
+/**
+ * Reduce a UnifiedEvent stream to user/assistant message pairs. Tool calls and
+ * tool results are inlined as bracketed annotations on the surrounding
+ * assistant turn so the historical narrative is preserved when synthesizing a
+ * native rollout for a different SDK. Streaming text deltas are folded into
+ * their final consolidated `text` event to avoid double-counting partial
+ * tokens.
+ */
+export type ChatPair = { userText: string; assistantText: string };
+
+interface ExtractOptions {
+  includeToolAnnotations: boolean;
+}
+
+export function extractChatPairs(
+  entries: ConversationEntry[],
+  opts: ExtractOptions = { includeToolAnnotations: true },
+): ChatPair[] {
+  const pairs: ChatPair[] = [];
+  let pendingUser: string | null = null;
+  let pendingAssistantParts: string[] = [];
+  let toolBuffer: string[] = [];
+
+  const flushAssistant = () => {
+    if (pendingUser === null) return;
+    const tools =
+      opts.includeToolAnnotations && toolBuffer.length > 0 ? `\n\n${toolBuffer.join("\n")}` : "";
+    const assistantText = pendingAssistantParts.join("").trim() + tools;
+    if (assistantText.trim()) {
+      pairs.push({ userText: pendingUser, assistantText });
+    }
+    pendingUser = null;
+    pendingAssistantParts = [];
+    toolBuffer = [];
+  };
+
+  for (const entry of entries) {
+    const ev = entry.event;
+    switch (ev.type) {
+      case "user_message": {
+        // Explicit user prompt marker emitted by the query handler before each
+        // turn. Close the previous pair (in case the prior turn streamed
+        // assistant text without a clean termination) and stage this prompt.
+        flushAssistant();
+        pendingUser = (ev as { content: string }).content;
+        break;
+      }
+      case "session":
+        // Session-id metadata. Provider sessions can change mid-conversation
+        // (e.g. agent flip after rollout reconstruction), but the SDK normally
+        // emits this *during* a turn — after the user prompt was already
+        // recorded, before the assistant text arrives. Only flush when there
+        // is actual assistant content in flight; otherwise we'd discard the
+        // staged user prompt and the next text event would synthesize a bogus
+        // "(continued)" pair.
+        if (pendingAssistantParts.length > 0 || toolBuffer.length > 0) {
+          flushAssistant();
+        }
+        break;
+      case "text": {
+        // Per-block assistant text. claudeProvider emits one of these per text
+        // content block, so a single turn can yield multiple `text` events
+        // interleaved with tool_use. Accumulate (do NOT flush yet) — the
+        // turn's `result` event below carries the final concatenation and
+        // is the proper boundary.
+        if (pendingUser === null) {
+          pendingUser = "(continued)";
+        }
+        pendingAssistantParts.push((ev as { content: string }).content);
+        break;
+      }
+      case "result": {
+        // End-of-turn marker. `result.content` is the canonical final answer
+        // produced by the provider, so prefer it over the accumulated `text`
+        // chunks (which may be partial or out of order across SDKs).
+        if (pendingUser === null) {
+          pendingUser = "(continued)";
+        }
+        pendingAssistantParts = [(ev as { content: string }).content];
+        flushAssistant();
+        break;
+      }
+      case "text_delta":
+        // Skip — final `text`/`result` event carries the complete content.
+        break;
+      case "tool_use": {
+        const u = ev as { name: string; input: Record<string, unknown> };
+        toolBuffer.push(`<!-- Tool: ${u.name} ${truncate(JSON.stringify(u.input), 200)} -->`);
+        break;
+      }
+      case "tool_result": {
+        const u = ev as { content: string };
+        toolBuffer.push(`<!-- Tool result: ${truncate(u.content, 200)} -->`);
+        break;
+      }
+      case "error": {
+        const u = ev as { content: string };
+        toolBuffer.push(`[Error: ${truncate(u.content, 200)}]`);
+        break;
+      }
+      // Other UnifiedEvent variants (`tool_progress`, `tool_use_summary`,
+      // `file`, `text_delta` already handled above) carry no conversational
+      // content, so they do not contribute to a chat pair. We intentionally
+      // omit a default branch — the explicit user_message variant introduced
+      // by the recorder makes the previous "treat unrecognized as user" hack
+      // unnecessary, and adding new UnifiedEvent variants in the future
+      // should require an explicit decision here, not silent inheritance.
+      case "tool_progress":
+      case "tool_use_summary":
+      case "file":
+      case "status":
+        break;
+    }
+  }
+  flushAssistant();
+  return pairs;
+}

package/dist/runtime/src/agents/self-config-core.ts

@@ -0,0 +1,415 @@
+import { switchApiTopicAgent } from "#agents/api-topic-agent-switch";
+import { resolveModelForAgent } from "#agents/model-catalog";
+import { getRegistry } from "#agents/registry";
+import { WsHub } from "#bus";
+import { resolveTopicWorkspaceDir } from "#platform/config";
+import { getApiTopicConfig, setApiTopicConfig } from "#storage/api-topic-config";
+import { getTopic } from "#storage/api-topics";
+import {
+  cancelPendingSelfSchedule,
+  createPendingSelfSchedule,
+  getPendingSelfSchedule,
+  updatePendingSelfSchedule,
+} from "#storage/self-schedules";
+import { createDerivedTopic, TopicTitleConflictError } from "#topics/derive";
+import { topicMarkdownLink } from "#topics/links";
+import type { AgentKind, EffortLevel } from "#types";
+import type { TopicDto } from "#types/api";
+
+export const SELF_CONFIG_MCP_KEY = "topic-config";
+
+export type SelfConfigField = "agent" | "model" | "effort";
+export const SELF_SCHEDULE_MAX_DELAY_SECONDS = 86_400;
+export const SELF_SCHEDULE_MAX_MESSAGE_LENGTH = 10_000;
+
+export interface SelfConfigContext {
+  topicId: string;
+  userId: string;
+  cwd?: string;
+  /** Raw current user request. Used to prevent autonomous MCP agent switches. */
+  currentUserPrompt?: string;
+  /** Called after a successful set_* so the caller can trigger a follow-up turn. */
+  onConfigChanged?: (field: SelfConfigField) => void;
+}
+
+export interface SelfConfigResult {
+  text: string;
+  isError?: boolean;
+}
+
+function ok(text: string): SelfConfigResult {
+  return { text };
+}
+
+function err(text: string): SelfConfigResult {
+  return { text, isError: true };
+}
+
+function requireAccessibleTopic(ctx: SelfConfigContext): TopicDto | SelfConfigResult {
+  if (!ctx.topicId || !ctx.userId) return err("Error: missing topicId/userId context.");
+  const topic = getTopic(ctx.topicId);
+  if (!topic) return err(`Error: topic '${ctx.topicId}' not found.`);
+  if (!topic.participants.some((p) => p.userId === ctx.userId)) {
+    return err("Error: user is not a member of this topic.");
+  }
+  return topic;
+}
+
+function requireTopic(ctx: SelfConfigContext): TopicDto | SelfConfigResult {
+  const topic = requireAccessibleTopic(ctx);
+  if (isResult(topic)) return topic;
+  if (!topic.agent) return err("Error: this topic has no AI agent invited.");
+  return topic;
+}
+
+function isResult(value: TopicDto | SelfConfigResult): value is SelfConfigResult {
+  return "text" in value;
+}
+
+function currentAgent(topic: TopicDto): AgentKind {
+  return (topic.agent ?? "maestro") as AgentKind;
+}
+
+function effectiveDefaultModel(topic: TopicDto, agent: AgentKind): string {
+  const registry = getRegistry(agent);
+  return resolveModelForAgent(agent, topic.defaultModel, registry);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function agentAliases(agent: AgentKind): string[] {
+  switch (agent) {
+    case "codex":
+      return ["codex", "코덱스", "gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"];
+    case "claude":
+      return ["claude", "클로드", "sonnet", "opus", "fable"];
+    case "maestro":
+      return [
+        "maestro",
+        "마에스트로",
+        "메스트로",
+        "deepseek",
+        "deepseek-pro",
+        "deepseek-flash",
+        "딥시크",
+      ];
+  }
+}
+
+function hasExplicitAgentSwitchRequest(prompt: string | undefined, agent: AgentKind): boolean {
+  if (!prompt?.trim()) return false;
+  const text = prompt.toLowerCase().replace(/\s+/g, " ").trim();
+  const aliases = agentAliases(agent).map(escapeRegExp);
+  const target = `(?:${aliases.join("|")})`;
+  const switchVerb =
+    "(?:바꿔|바꿔줘|변경|변경해|전환|전환해|설정|설정해|써줘|사용|가|switch|change|set|use)";
+  const switchSubject = "(?:agent|runtime|model|에이전트|런타임|모델)";
+
+  return [
+    new RegExp(`^/(?:agent|runtime)\\s+${target}(?:\\s|$)`, "iu"),
+    new RegExp(`${target}\\s*(?:로|으로)\\s*.{0,16}${switchVerb}`, "iu"),
+    new RegExp(`${switchSubject}.{0,24}${target}.{0,24}${switchVerb}`, "iu"),
+    new RegExp(`${switchVerb}.{0,24}${switchSubject}.{0,24}${target}`, "iu"),
+    new RegExp(`(?:switch|change|set|use).{0,24}${target}`, "iu"),
+  ].some((pattern) => pattern.test(text));
+}
+
+export function setSelfConfigModel(ctx: SelfConfigContext, model: string): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const cfg = getApiTopicConfig(topic.id) ?? {};
+  if (cfg.modelLocked) return err("Model for this topic is locked by the user. Cannot override.");
+
+  const agent = currentAgent(topic);
+  const registry = getRegistry(agent);
+  if (resolveModelForAgent(agent, model, registry) !== model) {
+    return err(
+      `'${model}' is not a valid model for agent '${agent}'. If it belongs to another agent, call set_agent first.`,
+    );
+  }
+
+  setApiTopicConfig(topic.id, { ...cfg, model });
+  // Keep the provider conversation. Codex and Claude both support changing
+  // the model for a later turn while resuming the same thread/session.
+  WsHub.get().broadcastTopicUpdated(topic.id);
+  ctx.onConfigChanged?.("model");
+  return ok(`Model for this topic set to '${model}' (agent=${agent}). Applies from the next turn.`);
+}
+
+export function getSelfConfigModel(ctx: SelfConfigContext): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const cfg = getApiTopicConfig(topic.id);
+  const agent = currentAgent(topic);
+  const registry = getRegistry(agent);
+  const fallback = effectiveDefaultModel(topic, agent);
+  const resolved = cfg?.model ? resolveModelForAgent(agent, cfg.model, registry) : fallback;
+  const value = cfg?.model && resolved === cfg.model ? cfg.model : `default (${fallback})`;
+  const lock = cfg?.modelLocked ? " [locked by user]" : "";
+  return ok(`Model (agent=${agent}): ${value}${lock}`);
+}
+
+export function setSelfConfigAgent(ctx: SelfConfigContext, agent: AgentKind): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const cfg = getApiTopicConfig(topic.id) ?? {};
+  // Agent is a topic property; the same path is used by UI and MCP.
+
+  const existing = currentAgent(topic);
+  if (existing === agent) return ok(`Agent is already '${agent}'. No change.`);
+  if (cfg.agentLocked) return err("Agent for this topic is locked by the user. Cannot override.");
+  if (!hasExplicitAgentSwitchRequest(ctx.currentUserPrompt, agent)) {
+    return err(
+      `Agent switch to '${agent}' requires an explicit request in the current user message.`,
+    );
+  }
+
+  // Switching agents invalidates provider-native session ids and per-agent
+  // model/effort overrides. The helper mirrors Otium's switchTopicAgent:
+  // write rollout, manifest the synthetic session in the unified log, then
+  // commit config + durable session.
+  const switched = switchApiTopicAgent({
+    topicId: topic.id,
+    topicTitle: topic.title,
+    userId: ctx.userId,
+    fromAgent: existing,
+    agent,
+    cwd: ctx.cwd ?? resolveTopicWorkspaceDir(topic.id),
+    config: { ...cfg, model: undefined, effort: undefined },
+    defaultModel: topic.defaultModel,
+    defaultEffort: topic.defaultEffort,
+    reason: "self-config-agent-switch",
+  });
+  if (!switched.ok) return err(switched.error);
+
+  WsHub.get().broadcastTopicUpdated(topic.id);
+  ctx.onConfigChanged?.("agent");
+  const sessionNote =
+    switched.outcome.kind === "bridged"
+      ? ` Conversation history was bridged into a ${agent} session (${switched.outcome.bridgedSessionId}).`
+      : switched.outcome.reason === "bridge-failed"
+        ? " Conversation history bridge failed; the next turn starts fresh."
+        : " No prior conversation history was found; the next turn starts fresh.";
+  return ok(
+    `Agent for this topic set to '${agent}'. Model/effort reset to '${agent}' defaults.${sessionNote}`,
+  );
+}
+
+export function getSelfConfigAgent(ctx: SelfConfigContext): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const lock = "";
+  return ok(`Agent: ${currentAgent(topic)}${lock}`);
+}
+
+export function setSelfConfigEffort(ctx: SelfConfigContext, effort: EffortLevel): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const cfg = getApiTopicConfig(topic.id) ?? {};
+  if (cfg.effortLocked) return err("Effort for this topic is locked by the user. Cannot override.");
+
+  const agent = currentAgent(topic);
+  const registry = getRegistry(agent);
+  if (!registry.validateEffort(effort)) {
+    return err(
+      `'${effort}' is not a valid effort for agent '${agent}'. Valid: ${registry.validEfforts.join(", ")}.`,
+    );
+  }
+
+  setApiTopicConfig(topic.id, { ...cfg, effort });
+  WsHub.get().broadcastTopicUpdated(topic.id);
+  ctx.onConfigChanged?.("effort");
+  return ok(
+    `Effort for this topic set to '${effort}' (agent=${agent}). Applies from the next turn.`,
+  );
+}
+
+export function getSelfConfigEffort(ctx: SelfConfigContext): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  const cfg = getApiTopicConfig(topic.id);
+  const agent = currentAgent(topic);
+  const registry = getRegistry(agent);
+  const fallback = registry.defaultEffort ? `default (${registry.defaultEffort})` : "default (off)";
+  const value = cfg?.effort ?? fallback;
+  const lock = cfg?.effortLocked ? " [locked by user]" : "";
+  return ok(`Effort (agent=${agent}): ${value}${lock}`);
+}
+
+/**
+ * Persist the topic's sole pending one-shot continuation. The inbox worker
+ * claims due rows only when the room is idle and keeps running claims durable
+ * until the turn settles.
+ */
+export function scheduleSelfConfigContinue(
+  ctx: SelfConfigContext,
+  delaySeconds: number,
+  message: string,
+  nowMs = Date.now(),
+): SelfConfigResult {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+  if (
+    !Number.isInteger(delaySeconds) ||
+    delaySeconds < 1 ||
+    delaySeconds > SELF_SCHEDULE_MAX_DELAY_SECONDS
+  ) {
+    return err(`delay_seconds must be an integer from 1 to ${SELF_SCHEDULE_MAX_DELAY_SECONDS}.`);
+  }
+  const cleanMessage = message.trim();
+  if (!cleanMessage) return err("message is required.");
+  if (cleanMessage.length > SELF_SCHEDULE_MAX_MESSAGE_LENGTH) {
+    return err(`message must be ${SELF_SCHEDULE_MAX_MESSAGE_LENGTH} characters or fewer.`);
+  }
+
+  const deliverAtMs = nowMs + delaySeconds * 1000;
+  const created = createPendingSelfSchedule({
+    topicId: topic.id,
+    userId: ctx.userId,
+    message: cleanMessage,
+    deliverAt: deliverAtMs,
+    now: nowMs,
+  });
+  if (!created.ok) {
+    return err(
+      `This topic already has a pending self-schedule (${created.existing.id}) for ` +
+        `${new Date(created.existing.deliverAt).toISOString()}. ` +
+        "Use update_self_schedule or cancel_self_schedule instead of creating another one.",
+    );
+  }
+  const deliverAt = new Date(deliverAtMs).toISOString();
+  return ok(
+    `Scheduled this topic to resume in ${delaySeconds} seconds at ${deliverAt}. ` +
+      `Schedule ID: ${created.schedule.id}. ` +
+      `The continuation is durable across node restarts (delivery granularity is about 5 seconds).`,
+  );
+}
+
+export function getSelfConfigSchedule(
+  ctx: SelfConfigContext,
+  nowMs = Date.now(),
+): SelfConfigResult {
+  const topic = requireAccessibleTopic(ctx);
+  if (isResult(topic)) return topic;
+  const schedule = getPendingSelfSchedule(topic.id);
+  if (!schedule) return ok("This topic has no pending self-schedule.");
+  const remainingSeconds = Math.max(0, Math.ceil((schedule.deliverAt - nowMs) / 1000));
+  return ok(
+    [
+      `Pending self-schedule: ${schedule.id}`,
+      `Deliver at: ${new Date(schedule.deliverAt).toISOString()} (in about ${remainingSeconds} seconds)`,
+      `Message: ${schedule.message}`,
+    ].join("\n"),
+  );
+}
+
+export function updateSelfConfigSchedule(
+  ctx: SelfConfigContext,
+  scheduleId: string,
+  updates: { delaySeconds?: number; message?: string },
+  nowMs = Date.now(),
+): SelfConfigResult {
+  const topic = requireAccessibleTopic(ctx);
+  if (isResult(topic)) return topic;
+  if (updates.delaySeconds === undefined && updates.message === undefined) {
+    return err("Provide delay_seconds, message, or both.");
+  }
+  if (
+    updates.delaySeconds !== undefined &&
+    (!Number.isInteger(updates.delaySeconds) ||
+      updates.delaySeconds < 1 ||
+      updates.delaySeconds > SELF_SCHEDULE_MAX_DELAY_SECONDS)
+  ) {
+    return err(`delay_seconds must be an integer from 1 to ${SELF_SCHEDULE_MAX_DELAY_SECONDS}.`);
+  }
+  let cleanMessage: string | undefined;
+  if (updates.message !== undefined) {
+    cleanMessage = updates.message.trim();
+    if (!cleanMessage) return err("message is required when provided.");
+    if (cleanMessage.length > SELF_SCHEDULE_MAX_MESSAGE_LENGTH) {
+      return err(`message must be ${SELF_SCHEDULE_MAX_MESSAGE_LENGTH} characters or fewer.`);
+    }
+  }
+
+  const updated = updatePendingSelfSchedule({
+    topicId: topic.id,
+    scheduleId,
+    message: cleanMessage,
+    deliverAt: updates.delaySeconds === undefined ? undefined : nowMs + updates.delaySeconds * 1000,
+    now: nowMs,
+  });
+  if (!updated) {
+    return err(
+      `Pending self-schedule '${scheduleId}' was not found. It may have been cancelled, replaced, or already started.`,
+    );
+  }
+  return ok(
+    `Updated self-schedule ${updated.id}. It will resume at ${new Date(updated.deliverAt).toISOString()}.`,
+  );
+}
+
+export function cancelSelfConfigSchedule(
+  ctx: SelfConfigContext,
+  scheduleId: string,
+): SelfConfigResult {
+  const topic = requireAccessibleTopic(ctx);
+  if (isResult(topic)) return topic;
+  if (!cancelPendingSelfSchedule(topic.id, scheduleId)) {
+    return err(
+      `Pending self-schedule '${scheduleId}' was not found. It may have been cancelled, replaced, or already started.`,
+    );
+  }
+  return ok(`Cancelled self-schedule ${scheduleId}.`);
+}
+
+export async function spawnSelfConfigTopic(
+  ctx: SelfConfigContext,
+  name?: string,
+): Promise<SelfConfigResult> {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  let derived: TopicDto | null;
+  try {
+    derived = await createDerivedTopic(topic.id, ctx.userId, false, {
+      name,
+      allowActiveSource: true,
+    });
+  } catch (e) {
+    if (e instanceof TopicTitleConflictError) return err(`${e.message} — pick a different name.`);
+    throw e;
+  }
+  if (!derived) return err("Failed to spawn topic (source not found or permission denied).");
+  return ok(`Spawned new topic "${derived.title}".\nLink: ${topicMarkdownLink(derived.id)}`);
+}
+
+export async function forkSelfConfigTopic(
+  ctx: SelfConfigContext,
+  name?: string,
+): Promise<SelfConfigResult> {
+  const topic = requireTopic(ctx);
+  if (isResult(topic)) return topic;
+
+  let derived: TopicDto | null;
+  try {
+    derived = await createDerivedTopic(topic.id, ctx.userId, true, {
+      name,
+      allowActiveSource: true,
+    });
+  } catch (e) {
+    if (e instanceof TopicTitleConflictError) return err(`${e.message} — pick a different name.`);
+    throw e;
+  }
+  if (!derived) return err("Failed to fork topic (source not found or permission denied).");
+  return ok(
+    `Forked new topic "${derived.title}". History copied.\nLink: ${topicMarkdownLink(derived.id)}`,
+  );
+}

package/dist/runtime/src/agents/task-events.ts

@@ -0,0 +1,44 @@
+import { readTasks, taskFileMtimeNs, taskScopeKey } from "#storage/tasks";
+import type { AgentQueryOptions, UnifiedEvent } from "#types";
+
+export interface TaskEventScope {
+  userId: string;
+  scopeKey: string;
+}
+
+export function resolveTaskEventScope(opts: AgentQueryOptions): TaskEventScope | null {
+  if (opts.silent) return null;
+  if (!opts.userId) return null;
+  if (opts.sessionType === "dm" || opts.sessionType === "ephemeral") {
+    return { userId: opts.userId, scopeKey: "dm" };
+  }
+  if (opts.sessionType === "manager") {
+    return { userId: opts.userId, scopeKey: opts.topicId ?? "general" };
+  }
+  if (!opts.session) return null;
+  return {
+    userId: opts.userId,
+    scopeKey: taskScopeKey({ topicId: opts.topicId, session: opts.session }),
+  };
+}
+
+/**
+ * The task MCP server runs as a child process of the agent SDK. Its writes do
+ * not appear in the provider stream, so after tool results and terminal
+ * results we stat the shared store and inject the full task snapshot when it
+ * changed.
+ */
+export async function* withTaskSnapshots(
+  inner: AsyncGenerator<UnifiedEvent>,
+  scope: TaskEventScope,
+): AsyncGenerator<UnifiedEvent> {
+  let lastMtime = taskFileMtimeNs(scope.userId, scope.scopeKey);
+  for await (const event of inner) {
+    yield event;
+    if (event.type !== "tool_result" && event.type !== "result") continue;
+    const mtime = taskFileMtimeNs(scope.userId, scope.scopeKey);
+    if (mtime === lastMtime) continue;
+    lastMtime = mtime;
+    yield { type: "tasks", tasks: readTasks(scope.userId, scope.scopeKey) };
+  }
+}