aimux-cli 0.1.15 → 0.1.18

package/dist/metadata-server.js

@@ -1,9 +1,10 @@
 import { createServer } from "node:http";
-import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
-import { basename } from "node:path";
-import { getDashboardClientUiStatePath, getProjectId, getProjectStateDir } from "./paths.js";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getDashboardClientUiStatePath, getPlansDir, getProjectId, getProjectStateDir } from "./paths.js";
 import { updateSessionMetadata, clearSessionLogs, saveMetadataEndpoint, loadMetadataState, } from "./metadata-store.js";
+import { contextualizeAlertInput, mergeDisplayContext, metadataDisplayContext, } from "./alert-display.js";
 import { notifyAlert } from "./notify.js";
 import { clearNotifications, listNotifications, markNotificationsRead, unreadNotificationCount, } from "./notifications.js";
 import { updateNotificationContext } from "./notification-context.js";
@@ -11,84 +12,60 @@ import { AgentTracker } from "./agent-tracker.js";
 import { createThread, listThreadSummaries, markThreadSeen, readMessages, readThread, setThreadStatus, } from "./threads.js";
 import { sendDirectMessage, sendThreadMessage } from "./orchestration.js";
 import { acceptHandoff, approveReview, acceptTask, assignTask, blockTask, completeHandoff, completeTask, reopenTask, requestTaskChanges, sendHandoff, } from "./orchestration-actions.js";
+import { readAllTasks, readTask } from "./tasks.js";
 import { buildWorkflowEntries } from "./workflow.js";
 import { markLastUsed } from "./last-used.js";
 import { formatRelativeRecency } from "./recency.js";
-import { getAttachment, getAttachmentContent, ingestAttachmentFromBase64, ingestAttachmentFromPath, } from "./attachment-store.js";
+import { getAttachment, getAttachmentContent } from "./attachment-store.js";
 import { ProjectEventBus } from "./project-events.js";
 import { getProjectServiceManifest } from "./project-service-manifest.js";
 import { applyShellStateTransition } from "./shell-state.js";
+import { isTeammateSession, selectDirectTeammates } from "./team.js";
 import { listSwitchableAgentItems, resolveAttentionAgent, resolveNextAgent, resolvePrevAgent, serializeFastControlItem, } from "./fast-control.js";
 import { TmuxRuntimeManager } from "./tmux/runtime-manager.js";
 import { openTargetForClient } from "./tmux/window-open.js";
 import { getDashboardCommandSpec } from "./dashboard/command-spec.js";
-function compactSessionId(sessionId) {
-    const compact = sessionId.replace(/-[a-z0-9]{4,}$/i, "");
-    return compact || sessionId;
+import { createRuntimeExchangeStore, } from "./runtime-core/exchange-store.js";
+import { listTopologySessionStates } from "./runtime-core/topology-sessions.js";
+const LIBRARY_DOC_ALLOWLIST = [
+    { path: "AGENTS.md", kind: "instructions", title: "AGENTS.md" },
+    { path: "CLAUDE.md", kind: "adapter", title: "CLAUDE.md" },
+    { path: "CODEX.md", kind: "adapter", title: "CODEX.md" },
+    { path: "README.md", kind: "project", title: "README.md" },
+];
+function isLibraryPathExposed(path) {
+    const normalized = path.replaceAll("\\", "/").toLowerCase();
+    return !normalized.startsWith(".aimux/") && !normalized.endsWith("config.json");
 }
-function metadataDisplayContext(metadata) {
-    return {
-        label: metadata?.label,
-        worktreePath: metadata?.context?.worktreePath,
-        worktreeName: metadata?.context?.worktreeName,
-        branch: metadata?.context?.branch,
-    };
-}
-function mergeDisplayContext(base, override) {
-    return {
-        label: override.label ?? base.label,
-        command: override.command ?? base.command,
-        worktreePath: override.worktreePath ?? base.worktreePath,
-        worktreeName: override.worktreeName ?? base.worktreeName,
-        branch: override.branch ?? base.branch,
-    };
-}
-function displayWorktreeLabel(context) {
-    const worktreeName = context.worktreeName?.trim();
-    const branch = context.branch?.trim();
-    if (worktreeName)
-        return worktreeName;
-    if (branch)
-        return branch;
-    const path = context.worktreePath?.trim();
-    return path ? basename(path) : undefined;
-}
-function sessionAlertSubject(sessionId, context) {
-    if (!sessionId)
-        return undefined;
-    const label = context?.label?.trim() || context?.command?.trim() || compactSessionId(sessionId);
-    const worktree = context ? displayWorktreeLabel(context) : undefined;
-    return worktree ? `${label} @ ${worktree}` : label;
-}
-function sessionAlertTitle(kind, sessionId, fallback, context) {
-    const title = fallback?.trim();
-    const subject = sessionAlertSubject(sessionId, context);
-    if (!subject)
-        return title || "aimux";
-    if (kind === "needs_input")
-        return `${subject} needs input`;
-    if (kind === "blocked") {
-        if (!title || (sessionId && title === `${sessionId} is blocked`))
-            return `${subject} is blocked`;
-        return title;
-    }
-    if (kind === "task_failed") {
-        if (!title || (sessionId && title === `${sessionId} errored`))
-            return `${subject} errored`;
-        return title;
-    }
-    if (kind === "task_done") {
-        if (!title || (sessionId && title === `${sessionId} finished`))
-            return `${subject} finished`;
-        return title;
-    }
-    if (!title)
-        return subject;
-    if (title.includes(subject))
-        return title;
-    if (sessionId && title.includes(sessionId))
-        return title.replace(sessionId, subject);
-    return `${subject}: ${title}`;
+function listLibraryDocuments(projectRoot = process.cwd()) {
+    return LIBRARY_DOC_ALLOWLIST.flatMap((entry) => {
+        if (!isLibraryPathExposed(entry.path))
+            return [];
+        try {
+            const fullPath = join(projectRoot, entry.path);
+            if (!existsSync(fullPath))
+                return [];
+            const stat = statSync(fullPath);
+            if (!stat.isFile())
+                return [];
+            const content = readFileSync(fullPath, "utf8");
+            return [
+                {
+                    id: entry.path,
+                    title: entry.title,
+                    path: entry.path,
+                    kind: entry.kind,
+                    size: stat.size,
+                    updatedAt: stat.mtime.toISOString(),
+                    content: content.slice(0, 40_000),
+                    truncated: content.length > 40_000,
+                },
+            ];
+        }
+        catch {
+            return [];
+        }
+    });
 }
 function dashboardClientKeyFromSession(sessionName) {
     return sessionName.replace(/[^a-zA-Z0-9._-]/g, "_");
@@ -136,6 +113,7 @@ function markActiveWindowFocused(tmux, projectRoot, currentClientSession, curren
         return false;
     updateNotificationContext("tui", {
         focused: true,
+        screen: match.metadata.kind === "service" ? "service" : "agent",
         sessionId: match.metadata.sessionId,
         panelOpen: false,
     });
@@ -162,6 +140,17 @@ function desiredPort() {
     const hash = createHash("sha1").update(getProjectId()).digest("hex").slice(0, 6);
     return 43000 + (parseInt(hash, 16) % 10000);
 }
+// Plan paths join this directly into `${sessionId}.md`, so restrict to a
+// conservative charset (no whitespace, no separators, no traversal) and
+// cap length so we don't produce surprising filenames.
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+function validateSessionId(raw) {
+    if (!SESSION_ID_PATTERN.test(raw))
+        return { ok: false };
+    if (raw.includes(".."))
+        return { ok: false };
+    return { ok: true, value: raw };
+}
 async function readJson(req) {
     const chunks = [];
     for await (const chunk of req) {
@@ -192,6 +181,153 @@ function sendSseEvent(res, event, data) {
     res.write(`event: ${event}\n`);
     res.write(`data: ${JSON.stringify(data)}\n\n`);
 }
+function topologyDesktopSessionList(statuses) {
+    return listTopologySessionStates({ statuses }).map((session) => ({
+        ...session,
+        status: session.status ?? "offline",
+        team: session.team,
+    }));
+}
+function firstLine(value) {
+    return (value
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean) ?? "");
+}
+function teammateTaskDescription(body) {
+    const explicitTitle = typeof body.title === "string" ? body.title.trim() : "";
+    if (explicitTitle)
+        return explicitTitle;
+    const explicitDescription = typeof body.description === "string" ? body.description.trim() : "";
+    if (explicitDescription)
+        return explicitDescription;
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    const bodyText = typeof body.body === "string" ? body.body.trim() : "";
+    const text = bodyText || prompt;
+    const line = firstLine(text);
+    return line ? line.slice(0, 120) : "Teammate task";
+}
+function teammateTaskPrompt(body) {
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    if (prompt)
+        return prompt;
+    const text = typeof body.body === "string" ? body.body.trim() : "";
+    return text || undefined;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function optionalStringOrFirst(value) {
+    if (typeof value === "string")
+        return optionalString(value);
+    if (!Array.isArray(value))
+        return undefined;
+    return value.map(optionalString).find(Boolean);
+}
+function runtimeInboxEntries(input = {}) {
+    const exchange = createRuntimeExchangeStore().read();
+    const threadById = new Map(exchange.threads.map((thread) => [thread.id, thread]));
+    const taskById = new Map(exchange.tasks.map((task) => [task.id, task]));
+    const latestMessageByThread = new Map();
+    for (const message of exchange.messages) {
+        const existing = latestMessageByThread.get(message.threadId);
+        if (!existing || existing.ts < message.ts)
+            latestMessageByThread.set(message.threadId, message);
+    }
+    const entries = exchange.inbox
+        .filter((entry) => !input.participantId || entry.participantId === input.participantId)
+        .filter((entry) => input.includeNotifications || threadById.get(entry.subjectId)?.tags?.includes("notification") !== true)
+        .filter((entry) => input.includeDone || entry.state !== "done")
+        .filter((entry) => !input.unreadOnly || entry.state !== "done")
+        .map((entry) => runtimeInboxEntry(entry, threadById, taskById, latestMessageByThread))
+        .filter((entry) => Boolean(entry));
+    return entries.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+function runtimeInboxEntry(entry, threadById, taskById, latestMessageByThread) {
+    if (entry.subjectKind === "thread" || entry.subjectKind === "handoff" || entry.subjectKind === "message") {
+        const thread = threadById.get(entry.subjectId);
+        if (!thread)
+            return undefined;
+        const message = latestMessageByThread.get(thread.id);
+        return {
+            id: entry.id,
+            subjectKind: entry.subjectKind,
+            subjectId: entry.subjectId,
+            participantId: entry.participantId,
+            sessionId: entry.participantId,
+            title: thread.title,
+            subtitle: `${thread.kind} · ${thread.status}`,
+            body: message?.body ?? thread.title,
+            createdAt: entry.updatedAt,
+            unread: entry.state !== "done",
+            state: entry.state,
+            urgency: entry.urgency,
+        };
+    }
+    const task = taskById.get(entry.subjectId);
+    if (!task)
+        return undefined;
+    return {
+        id: entry.id,
+        subjectKind: entry.subjectKind,
+        subjectId: entry.subjectId,
+        participantId: entry.participantId,
+        sessionId: entry.participantId,
+        title: task.description,
+        subtitle: `${task.type ?? "task"} · ${task.status}`,
+        body: task.result ?? task.error ?? task.prompt,
+        createdAt: entry.updatedAt,
+        unread: entry.state !== "done",
+        state: entry.state,
+        urgency: entry.urgency,
+    };
+}
+function markRuntimeInboxRead(input = {}) {
+    const store = createRuntimeExchangeStore();
+    const exchange = store.read();
+    const threadById = new Map(exchange.threads.map((thread) => [thread.id, thread]));
+    const entries = store
+        .read()
+        .inbox.filter((entry) => !input.id || entry.id === input.id)
+        .filter((entry) => !input.participantId || entry.participantId === input.participantId)
+        .filter((entry) => input.includeNotifications || threadById.get(entry.subjectId)?.tags?.includes("notification") !== true);
+    let updated = 0;
+    for (const entry of entries) {
+        if (entry.state !== "done")
+            updated += 1;
+        if (entry.subjectKind === "thread" || entry.subjectKind === "handoff" || entry.subjectKind === "message") {
+            markThreadSeen(entry.subjectId, entry.participantId);
+        }
+    }
+    store.update((exchange) => ({
+        ...exchange,
+        inbox: exchange.inbox.map((entry) => (!input.id || entry.id === input.id) &&
+            (!input.participantId || entry.participantId === input.participantId) &&
+            (input.includeNotifications || threadById.get(entry.subjectId)?.tags?.includes("notification") !== true)
+            ? { ...entry, state: "done" }
+            : entry),
+    }));
+    return updated;
+}
+function teammateApiRecord(session) {
+    return {
+        id: session.id,
+        sessionId: session.id,
+        tool: session.command,
+        command: session.command,
+        label: session.team?.label ?? session.label,
+        role: session.team?.role,
+        status: session.status,
+        worktreePath: session.worktreePath,
+        headline: session.headline,
+        preview: session.preview,
+        createdAt: session.createdAt,
+        lastUsedAt: session.lastUsedAt,
+        pending: session.pending,
+        pendingAction: session.pendingAction,
+        team: session.team,
+    };
+}
 export class MetadataServer {
     options;
     server = null;
@@ -241,6 +377,57 @@ export class MetadataServer {
     notifyChange() {
         this.options.onChange?.();
     }
+    resolveDirectTeammates(parentSessionId) {
+        if (!parentSessionId.trim()) {
+            return { ok: false, status: 400, error: "parentSessionId is required" };
+        }
+        const topologySessions = topologyDesktopSessionList(["running", "idle", "offline"]);
+        const sessions = topologySessions.filter((session) => !isTeammateSession(session));
+        const teammates = topologySessions.filter(isTeammateSession);
+        const parent = [...sessions, ...teammates].find((session) => session.id === parentSessionId);
+        if (!parent) {
+            return { ok: false, status: 404, error: `parent agent "${parentSessionId}" not found` };
+        }
+        if (isTeammateSession(parent)) {
+            return { ok: false, status: 400, error: "teammate agents cannot create or delegate to nested teams" };
+        }
+        return {
+            ok: true,
+            parent,
+            teammates: selectDirectTeammates(teammates, parentSessionId),
+        };
+    }
+    resolveDirectTeammate(parentSessionId, teammateSessionId) {
+        if (!teammateSessionId.trim()) {
+            return { ok: false, status: 400, error: "teammateSessionId is required" };
+        }
+        const resolved = this.resolveDirectTeammates(parentSessionId);
+        if (!resolved.ok)
+            return resolved;
+        const teammate = resolved.teammates.find((session) => session.id === teammateSessionId);
+        if (!teammate) {
+            return {
+                ok: false,
+                status: 404,
+                error: `teammate "${teammateSessionId}" is not attached to parent "${parentSessionId}"`,
+            };
+        }
+        return { ok: true, parent: resolved.parent, teammate };
+    }
+    resolveDirectGraveyardTeammate(parentSessionId, teammateSessionId) {
+        const resolved = this.resolveDirectTeammates(parentSessionId);
+        if (!resolved.ok)
+            return resolved;
+        const teammate = selectDirectTeammates(topologyDesktopSessionList(["graveyard"]), resolved.parent.id).find((session) => session.id === teammateSessionId);
+        if (!teammate) {
+            return {
+                ok: false,
+                status: 404,
+                error: `graveyard teammate "${teammateSessionId}" is not attached to parent "${parentSessionId}"`,
+            };
+        }
+        return { ok: true, parent: resolved.parent, teammate };
+    }
     listen(port) {
         return new Promise((resolve, reject) => {
             if (!this.server)
@@ -258,11 +445,7 @@ export class MetadataServer {
     }
     emitAlert(input) {
         const displayContext = this.resolveSessionAlertDisplayContext(input.sessionId, input.worktreePath);
-        this.eventBus.publishAlert({
-            ...input,
-            title: sessionAlertTitle(input.kind, input.sessionId, input.title, displayContext),
-            worktreePath: input.worktreePath ?? displayContext?.worktreePath,
-        });
+        this.eventBus.publishAlert(contextualizeAlertInput(input, displayContext));
     }
     resolveSessionAlertDisplayContext(sessionId, worktreePath) {
         if (!sessionId)
@@ -343,6 +526,14 @@ export class MetadataServer {
         return [...new Set(fallbackRecipients.map((value) => value?.trim()).filter(Boolean))];
     }
     async handle(req, res) {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        if (req.method === "OPTIONS") {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
         const url = new URL(req.url ?? "/", "http://127.0.0.1");
         if (req.method === "GET" && url.pathname === "/events") {
             const sessionFilter = url.searchParams.get("sessionId")?.trim() || null;
@@ -452,6 +643,26 @@ export class MetadataServer {
             });
             return;
         }
+        if (req.method === "GET" && url.pathname === "/library") {
+            send(res, 200, {
+                ok: true,
+                documents: listLibraryDocuments(),
+            });
+            return;
+        }
+        if (req.method === "GET" && url.pathname === "/inbox") {
+            const unreadOnly = url.searchParams.get("unread") === "1";
+            const participantId = url.searchParams.get("participant")?.trim() || undefined;
+            const includeDone = url.searchParams.get("includeDone") === "1";
+            const includeNotifications = url.searchParams.get("includeNotifications") === "1";
+            const inbox = runtimeInboxEntries({ unreadOnly, participantId, includeDone, includeNotifications });
+            send(res, 200, {
+                ok: true,
+                inbox,
+                unreadCount: inbox.filter((entry) => entry.unread).length,
+            });
+            return;
+        }
         if (req.method === "GET" && url.pathname === "/health") {
             send(res, 200, {
                 ok: true,
@@ -518,6 +729,15 @@ export class MetadataServer {
             send(res, 200, buildWorkflowEntries(url.searchParams.get("participant") ?? "user"));
             return;
         }
+        if (req.method === "GET" && url.pathname === "/tasks") {
+            const sessionId = url.searchParams.get("session")?.trim();
+            const status = url.searchParams.get("status")?.trim();
+            const tasks = readAllTasks()
+                .filter((task) => !sessionId || task.assignedTo === sessionId || task.assignedBy === sessionId)
+                .filter((task) => !status || task.status === status);
+            send(res, 200, { ok: true, tasks });
+            return;
+        }
         if (req.method === "POST" && url.pathname === "/usage/mark") {
             const body = (await readJson(req));
             const itemId = body.itemId?.trim() || "";
@@ -635,7 +855,14 @@ export class MetadataServer {
             return;
         }
         if (req.method === "GET" && url.pathname.startsWith("/threads/")) {
-            const threadId = decodeURIComponent(url.pathname.slice("/threads/".length));
+            let threadId;
+            try {
+                threadId = decodeURIComponent(url.pathname.slice("/threads/".length));
+            }
+            catch {
+                send(res, 400, { ok: false, error: "invalid threadId" });
+                return;
+            }
             const thread = readThread(threadId);
             if (!thread) {
                 send(res, 404, { ok: false, error: "thread not found" });
@@ -644,7 +871,92 @@ export class MetadataServer {
             send(res, 200, { thread, messages: readMessages(threadId) });
             return;
         }
+        if (req.method === "GET" && url.pathname.startsWith("/tasks/")) {
+            let taskId;
+            try {
+                taskId = decodeURIComponent(url.pathname.slice("/tasks/".length));
+            }
+            catch {
+                send(res, 400, { ok: false, error: "invalid taskId" });
+                return;
+            }
+            const task = readTask(taskId);
+            if (!task) {
+                send(res, 404, { ok: false, error: "task not found" });
+                return;
+            }
+            const thread = task.threadId ? readThread(task.threadId) : undefined;
+            const messages = task.threadId ? readMessages(task.threadId) : [];
+            send(res, 200, { ok: true, task, thread, messages });
+            return;
+        }
         try {
+            if (req.method === "GET" && url.pathname.startsWith("/plans/")) {
+                let raw;
+                try {
+                    raw = decodeURIComponent(url.pathname.slice("/plans/".length));
+                }
+                catch {
+                    send(res, 400, { ok: false, error: "invalid sessionId" });
+                    return;
+                }
+                const validation = validateSessionId(raw);
+                if (!validation.ok) {
+                    send(res, 400, { ok: false, error: "invalid sessionId" });
+                    return;
+                }
+                const sessionId = validation.value;
+                const planPath = join(getPlansDir(), `${sessionId}.md`);
+                try {
+                    const content = readFileSync(planPath, "utf8");
+                    send(res, 200, { ok: true, sessionId, content });
+                }
+                catch (err) {
+                    if (err?.code === "ENOENT") {
+                        send(res, 404, { ok: false, error: "Plan not found" });
+                        return;
+                    }
+                    send(res, 500, { ok: false, error: "Failed to read plan" });
+                    return;
+                }
+                return;
+            }
+            if (req.method === "PUT" && url.pathname.startsWith("/plans/")) {
+                let raw;
+                try {
+                    raw = decodeURIComponent(url.pathname.slice("/plans/".length));
+                }
+                catch {
+                    send(res, 400, { ok: false, error: "invalid sessionId" });
+                    return;
+                }
+                const validation = validateSessionId(raw);
+                if (!validation.ok) {
+                    send(res, 400, { ok: false, error: "invalid sessionId" });
+                    return;
+                }
+                const sessionId = validation.value;
+                const body = (await readJson(req));
+                if (typeof body.content !== "string") {
+                    send(res, 400, { ok: false, error: "content must be a string" });
+                    return;
+                }
+                const planPath = join(getPlansDir(), `${sessionId}.md`);
+                const dir = dirname(planPath);
+                const tmpPath = join(dir, `.${sessionId}.${randomUUID()}.tmp`);
+                try {
+                    mkdirSync(dir, { recursive: true });
+                    writeFileSync(tmpPath, body.content, "utf8");
+                    renameSync(tmpPath, planPath);
+                }
+                catch {
+                    rmSync(tmpPath, { force: true });
+                    send(res, 500, { ok: false, error: "Failed to write plan" });
+                    return;
+                }
+                send(res, 200, { ok: true, sessionId });
+                return;
+            }
             if (req.method === "POST" && url.pathname === "/set-status") {
                 const body = (await readJson(req));
                 updateSessionMetadata(body.session, (current) => ({
@@ -728,7 +1040,7 @@ export class MetadataServer {
                 const currentClientSession = body.currentClientSession?.trim() || url.searchParams.get("currentClientSession")?.trim() || undefined;
                 const clientTty = body.clientTty?.trim() || url.searchParams.get("clientTty")?.trim() || undefined;
                 const desktop = this.options.desktop.getState();
-                const session = (desktop.sessions ?? []).find((entry) => entry.id === sessionId);
+                const session = [...(desktop.sessions ?? []), ...(desktop.teammates ?? [])].find((entry) => entry.id === sessionId);
                 const service = (desktop.services ?? []).find((entry) => entry.id === sessionId);
                 const tmux = new TmuxRuntimeManager();
                 const openWindowId = (windowId, itemId) => {
@@ -989,7 +1301,7 @@ export class MetadataServer {
                     this.emitAlert({
                         kind: "notification",
                         sessionId: body.session,
-                        title: sessionAlertTitle("notification", body.session, body.event.source),
+                        title: body.event.source ?? "notification",
                         message: body.event.message || "Agent notification.",
                         dedupeKey: body.event.message ? `notify:${body.session}:${body.event.message}` : undefined,
                         cooldownMs: 15_000,
@@ -1092,7 +1404,7 @@ export class MetadataServer {
                 this.emitAlert({
                     kind,
                     sessionId,
-                    title: sessionAlertTitle(kind, sessionId, body.title),
+                    title: body.title ?? "",
                     message: [body.subtitle?.trim(), body.message?.trim() || body.title?.trim() || "aimux"]
                         .filter(Boolean)
                         .join(" — "),
@@ -1132,12 +1444,23 @@ export class MetadataServer {
                 send(res, 200, { ok: true, cleared });
                 return;
             }
+            if (req.method === "POST" && (url.pathname === "/inbox/read" || url.pathname === "/inbox/clear")) {
+                const body = (await readJson(req));
+                const updated = markRuntimeInboxRead({
+                    id: body.id?.trim() || undefined,
+                    participantId: body.participant?.trim() || body.sessionId?.trim() || undefined,
+                    includeNotifications: body.includeNotifications === true,
+                });
+                send(res, 200, { ok: true, updated });
+                return;
+            }
             if (req.method === "POST" && url.pathname === "/shell-state") {
                 const body = (await readJson(req));
                 const result = applyShellStateTransition({
                     state: body.state,
                     sessionId: body.sessionId,
                     tool: body.tool,
+                    command: body.command,
                     tracker: this.tracker,
                     emitAlert: (input) => this.emitAlert(input),
                 });
@@ -1209,7 +1532,12 @@ export class MetadataServer {
             }
             if (req.method === "POST" && url.pathname === "/threads/mark-seen") {
                 const body = (await readJson(req));
-                const thread = markThreadSeen(body.threadId, body.session);
+                const sessionId = (body.session ?? body.sessionId ?? "").trim();
+                if (!sessionId) {
+                    send(res, 400, { ok: false, error: "session is required" });
+                    return;
+                }
+                const thread = markThreadSeen(body.threadId, sessionId);
                 if (!thread) {
                     send(res, 404, { ok: false, error: "thread not found" });
                     return;
@@ -1238,7 +1566,9 @@ export class MetadataServer {
                     ? this.options.actions.sendHandoff(body)
                     : sendHandoff({
                         from: body.from?.trim() || "user",
-                        to: body.to ?? [],
+                        to: body.to?.length
+                            ? body.to
+                            : [body.assignee, body.tool].map(optionalString).filter((value) => Boolean(value)),
                         body: body.body,
                         title: body.title,
                         worktreePath: body.worktreePath,
@@ -1287,7 +1617,7 @@ export class MetadataServer {
                 const body = (await readJson(req));
                 const result = await assignTask({
                     from: body.from?.trim() || "user",
-                    to: body.to?.trim(),
+                    to: optionalStringOrFirst(body.to),
                     assignee: body.assignee?.trim(),
                     tool: body.tool?.trim(),
                     description: body.description,
@@ -1373,6 +1703,207 @@ export class MetadataServer {
                 send(res, 200, { ok: true, ...result });
                 return;
             }
+            if (req.method === "GET" && url.pathname === "/agents/teammates") {
+                const parentSessionId = url.searchParams.get("parentSessionId")?.trim() ?? "";
+                const result = this.resolveDirectTeammates(parentSessionId);
+                if (!result.ok) {
+                    send(res, result.status, { ok: false, error: result.error });
+                    return;
+                }
+                send(res, 200, {
+                    ok: true,
+                    parentSessionId: result.parent.id,
+                    teammates: result.teammates.map(teammateApiRecord),
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/create") {
+                const body = (await readJson(req));
+                const parentSessionId = body.parentSessionId?.trim() ?? "";
+                if (!parentSessionId) {
+                    send(res, 400, { ok: false, error: "parentSessionId is required" });
+                    return;
+                }
+                body.parentSessionId = parentSessionId;
+                if (this.options.desktop?.getState) {
+                    const resolved = this.resolveDirectTeammates(parentSessionId);
+                    if (!resolved.ok) {
+                        send(res, resolved.status, { ok: false, error: resolved.error });
+                        return;
+                    }
+                }
+                const initialTaskPrompt = body.initialTask ? teammateTaskPrompt(body.initialTask) : undefined;
+                if (body.initialTask && !initialTaskPrompt) {
+                    send(res, 400, { ok: false, error: "initialTask requires body or prompt" });
+                    return;
+                }
+                if (!this.options.lifecycle?.createTeammateAgent) {
+                    send(res, 501, { ok: false, error: "teammate creation not supported by this service" });
+                    return;
+                }
+                const result = await this.options.lifecycle.createTeammateAgent({
+                    parentSessionId: body.parentSessionId,
+                    role: body.role,
+                    label: body.label,
+                    tool: body.tool,
+                    sessionId: body.sessionId,
+                    worktreePath: body.worktreePath,
+                    open: body.open,
+                    extraArgs: body.extraArgs,
+                    order: body.order,
+                });
+                const taskResult = body.initialTask && initialTaskPrompt
+                    ? await assignTask({
+                        from: result.parentSessionId,
+                        to: result.sessionId,
+                        description: teammateTaskDescription(body.initialTask),
+                        prompt: initialTaskPrompt,
+                        worktreePath: optionalString(body.initialTask.worktreePath) ?? optionalString(body.worktreePath),
+                    })
+                    : undefined;
+                if (taskResult) {
+                    this.emitAssignedTaskAlert(taskResult);
+                }
+                this.options.onChange?.();
+                send(res, 200, { ok: true, ...result, task: taskResult?.task, thread: taskResult?.thread });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/tasks") {
+                const body = (await readJson(req));
+                const parentSessionId = body.parentSessionId?.trim() ?? "";
+                const teammateSessionId = body.teammateSessionId?.trim() ?? "";
+                if (!teammateSessionId) {
+                    send(res, 400, { ok: false, error: "teammateSessionId is required" });
+                    return;
+                }
+                const resolved = this.resolveDirectTeammates(parentSessionId);
+                if (!resolved.ok) {
+                    send(res, resolved.status, { ok: false, error: resolved.error });
+                    return;
+                }
+                const teammate = resolved.teammates.find((session) => session.id === teammateSessionId);
+                if (!teammate) {
+                    send(res, 404, {
+                        ok: false,
+                        error: `teammate "${teammateSessionId}" is not attached to parent "${parentSessionId}"`,
+                    });
+                    return;
+                }
+                const prompt = teammateTaskPrompt(body);
+                if (!prompt) {
+                    send(res, 400, { ok: false, error: "teammate task requires body or prompt" });
+                    return;
+                }
+                const result = await assignTask({
+                    from: resolved.parent.id,
+                    to: teammate.id,
+                    description: teammateTaskDescription(body),
+                    prompt,
+                    worktreePath: optionalString(body.worktreePath) ??
+                        optionalString(teammate.worktreePath) ??
+                        optionalString(resolved.parent.worktreePath),
+                });
+                this.emitAssignedTaskAlert(result);
+                this.options.onChange?.();
+                send(res, 200, { ok: true, parentSessionId: resolved.parent.id, teammateSessionId: teammate.id, ...result });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/send") {
+                send(res, 410, {
+                    ok: false,
+                    error: "raw teammate send has been removed; create durable teammate work with /agents/teammates/tasks",
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/stop") {
+                const body = (await readJson(req));
+                const resolved = this.resolveDirectTeammate(body.parentSessionId?.trim() ?? "", body.teammateSessionId?.trim() ?? "");
+                if (!resolved.ok) {
+                    send(res, resolved.status, { ok: false, error: resolved.error });
+                    return;
+                }
+                if (!this.options.lifecycle?.stopAgent) {
+                    send(res, 501, { ok: false, error: "agent stop not supported by this service" });
+                    return;
+                }
+                const result = await this.options.lifecycle.stopAgent({ sessionId: resolved.teammate.id });
+                this.options.onChange?.();
+                send(res, 200, {
+                    ok: true,
+                    parentSessionId: resolved.parent.id,
+                    teammateSessionId: resolved.teammate.id,
+                    ...result,
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/resume") {
+                const body = (await readJson(req));
+                const resolved = this.resolveDirectTeammate(body.parentSessionId?.trim() ?? "", body.teammateSessionId?.trim() ?? "");
+                if (!resolved.ok) {
+                    send(res, resolved.status, { ok: false, error: resolved.error });
+                    return;
+                }
+                if (!this.options.desktop?.resumeAgent) {
+                    send(res, 501, { ok: false, error: "agent resume not supported by this service" });
+                    return;
+                }
+                const result = await this.options.desktop.resumeAgent({
+                    sessionId: resolved.teammate.id,
+                    session: resolved.teammate,
+                });
+                this.options.onChange?.();
+                send(res, 200, {
+                    ok: true,
+                    parentSessionId: resolved.parent.id,
+                    teammateSessionId: resolved.teammate.id,
+                    ...result,
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/kill") {
+                const body = (await readJson(req));
+                const resolved = this.resolveDirectTeammate(body.parentSessionId?.trim() ?? "", body.teammateSessionId?.trim() ?? "");
+                if (!resolved.ok) {
+                    send(res, resolved.status, { ok: false, error: resolved.error });
+                    return;
+                }
+                if (!this.options.lifecycle?.killAgent) {
+                    send(res, 501, { ok: false, error: "agent kill not supported by this service" });
+                    return;
+                }
+                const result = await this.options.lifecycle.killAgent({
+                    sessionId: resolved.teammate.id,
+                });
+                this.options.onChange?.();
+                send(res, 200, {
+                    ok: true,
+                    parentSessionId: resolved.parent.id,
+                    teammateSessionId: resolved.teammate.id,
+                    ...result,
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/agents/teammates/resurrect") {
+                const body = (await readJson(req));
+                const resolved = this.resolveDirectGraveyardTeammate(body.parentSessionId?.trim() ?? "", body.teammateSessionId?.trim() ?? "");
+                if (!resolved.ok) {
+                    send(res, resolved.status, { ok: false, error: resolved.error });
+                    return;
+                }
+                if (!this.options.desktop?.resurrectGraveyard) {
+                    send(res, 501, { ok: false, error: "agent graveyard resurrection not supported by this service" });
+                    return;
+                }
+                const result = await this.options.desktop.resurrectGraveyard({ sessionId: resolved.teammate.id });
+                this.options.onChange?.();
+                send(res, 200, {
+                    ok: true,
+                    parentSessionId: resolved.parent.id,
+                    teammateSessionId: resolved.teammate.id,
+                    ...result,
+                });
+                return;
+            }
             if (req.method === "POST" && url.pathname === "/agents/fork") {
                 const body = (await readJson(req));
                 if (!this.options.lifecycle?.forkAgent) {
@@ -1401,7 +1932,7 @@ export class MetadataServer {
                     send(res, 501, { ok: false, error: "agent resume not supported by this service" });
                     return;
                 }
-                const result = await this.options.desktop.resumeAgent(body);
+                const result = await this.options.desktop.resumeAgent({ sessionId: body.sessionId });
                 this.options.onChange?.();
                 send(res, 200, { ok: true, ...result });
                 return;
@@ -1424,10 +1955,6 @@ export class MetadataServer {
                     return;
                 }
                 const result = await this.options.lifecycle.renameAgent(body);
-                updateSessionMetadata(body.sessionId, (current) => ({
-                    ...current,
-                    label: body.label?.trim() || undefined,
-                }));
                 this.options.onChange?.();
                 send(res, 200, { ok: true, ...result });
                 return;
@@ -1449,45 +1976,30 @@ export class MetadataServer {
                     send(res, 501, { ok: false, error: "agent kill not supported by this service" });
                     return;
                 }
-                const result = await this.options.lifecycle.killAgent(body);
+                const result = await this.options.lifecycle.killAgent({ sessionId: body.sessionId });
                 this.options.onChange?.();
                 send(res, 200, { ok: true, ...result });
                 return;
             }
             if (req.method === "POST" && url.pathname === "/agents/input") {
                 const body = (await readJson(req));
-                if (!this.options.lifecycle?.writeAgentInput) {
-                    send(res, 501, { ok: false, error: "agent input not supported by this service" });
+                const sessionId = body.sessionId?.trim() ?? "";
+                if (!sessionId) {
+                    send(res, 400, { ok: false, error: "sessionId is required" });
                     return;
                 }
-                const result = await this.options.lifecycle.writeAgentInput(body);
-                if (this.options.lifecycle.readAgentHistory) {
-                    try {
-                        const history = await this.options.lifecycle.readAgentHistory({ sessionId: body.sessionId, lastN: 20 });
-                        this.eventBus.publishHistoryUpdate({
-                            sessionId: history.sessionId,
-                            messages: history.messages,
-                            lastN: history.lastN,
-                        });
-                    }
-                    catch {
-                        // History update is best-effort; the write result should still succeed.
-                    }
+                const text = typeof body.text === "string" ? body.text : "";
+                if (!text.trim()) {
+                    send(res, 400, { ok: false, error: "text is required" });
+                    return;
+                }
+                if (!this.options.lifecycle?.sendAgentInput) {
+                    send(res, 501, { ok: false, error: "agent input not supported by this service" });
+                    return;
                 }
+                const result = await this.options.lifecycle.sendAgentInput({ sessionId, text });
                 this.options.onChange?.();
-                send(res, 200, { ok: result.accepted, ...result });
-                return;
-            }
-            if (req.method === "POST" && url.pathname === "/attachments") {
-                const body = (await readJson(req));
-                const attachment = body.path?.trim()
-                    ? ingestAttachmentFromPath(body.path)
-                    : ingestAttachmentFromBase64({
-                        filename: body.filename,
-                        mimeType: body.mimeType,
-                        contentBase64: String(body.contentBase64 ?? ""),
-                    });
-                send(res, 200, { ok: true, attachment });
+                send(res, 200, { ok: true, ...result });
                 return;
             }
             const attachmentContentMatch = url.pathname.match(/^\/attachments\/([^/]+)\/content$/);
@@ -1531,23 +2043,7 @@ export class MetadataServer {
                 return;
             }
             if (req.method === "GET" && url.pathname === "/agents/history") {
-                const sessionId = url.searchParams.get("sessionId")?.trim();
-                const lastNRaw = url.searchParams.get("lastN");
-                if (!sessionId) {
-                    send(res, 400, { ok: false, error: "sessionId is required" });
-                    return;
-                }
-                if (!this.options.lifecycle?.readAgentHistory) {
-                    send(res, 501, { ok: false, error: "agent history not supported by this service" });
-                    return;
-                }
-                const lastN = lastNRaw === null || lastNRaw.trim() === "" ? undefined : Number.parseInt(lastNRaw, 10);
-                if (lastNRaw !== null && Number.isNaN(lastN)) {
-                    send(res, 400, { ok: false, error: "lastN must be an integer" });
-                    return;
-                }
-                const result = await this.options.lifecycle.readAgentHistory({ sessionId, lastN });
-                send(res, 200, { ok: true, ...result });
+                send(res, 410, { ok: false, error: "agent message history requires the runtime core replacement" });
                 return;
             }
             if (req.method === "POST" && url.pathname === "/worktrees/create") {
@@ -1663,11 +2159,16 @@ export class MetadataServer {
             }
             if (req.method === "POST" && url.pathname === "/graveyard/resurrect") {
                 const body = (await readJson(req));
+                const sessionId = (body.sessionId ?? body.id ?? "").trim();
+                if (!sessionId) {
+                    send(res, 400, { ok: false, error: "sessionId is required" });
+                    return;
+                }
                 if (!this.options.desktop?.resurrectGraveyard) {
-                    send(res, 501, { ok: false, error: "graveyard resurrect not supported by this service" });
+                    send(res, 501, { ok: false, error: "agent graveyard resurrection not supported by this service" });
                     return;
                 }
-                const result = await this.options.desktop.resurrectGraveyard(body);
+                const result = await this.options.desktop.resurrectGraveyard({ sessionId });
                 this.options.onChange?.();
                 send(res, 200, { ok: true, ...result });
                 return;
@@ -1675,7 +2176,7 @@ export class MetadataServer {
             if (req.method === "POST" && url.pathname === "/graveyard/worktrees/resurrect") {
                 const body = (await readJson(req));
                 if (!this.options.desktop?.resurrectGraveyardWorktree) {
-                    send(res, 501, { ok: false, error: "worktree graveyard resurrect not supported by this service" });
+                    send(res, 501, { ok: false, error: "worktree graveyard resurrection not supported by this service" });
                     return;
                 }
                 const result = await this.options.desktop.resurrectGraveyardWorktree(body);