agentus 0.3.9 → 0.4.0

package/packages/server/src/acp/session-manager.ts

@@ -14,6 +14,7 @@ import type {
   RequestPermissionResponse,
 } from "@agentclientprotocol/sdk";
 import { BACKENDS, buildSpawnEnv, nativePlanSourceOf, type BackendSpec } from "./backends.js";
+import { SKILLS_ROOT, installSkills, resolveSkillsDir } from "../skills/install.js";
 import { classifyError, checkedHealth, effectiveArgs, handshakeFrom, rowToSpec } from "./registry.js";
 import type { BackendHandshake, CheckErrorCode } from "./registry.js";
 import {
@@ -35,10 +36,19 @@ import type {
   SessionModeState,
   TurnTrace,
 } from "../../../shared/src/index.js";
-import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
+import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, clampTitle, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
 import { PLAN_GUIDANCE_ACTIVE, PLAN_GUIDANCE_INTRO, PLAN_GUIDANCE_NATIVE } from "../../../shared/src/index.js";
 import { PREFS_DEFAULT, type PlanHintSettings } from "../settings.js";
 
+// The cockpit CLI an agent is handed (issue #15). Resolved from THIS module's location, so it points
+// at the same tree the server runs from — a checkout and an installed package alike (`bin/` is in the
+// package's `files`).
+// The path we hand agents as `AGENTUS_COCKPIT_BIN` is the `agentus` launcher itself — there is no
+// second command to install, and `agentus cockpit <command>` is the only spelling anywhere. (The
+// implementation is `bin/cockpit.mjs`, but that file is the subcommand, not a product name: agents
+// never see it, so it must not become a second thing users have to learn.)
+const COCKPIT_BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../../bin/agentus.mjs");
+
 // Permission prompts must not hang a session forever (design.md §8-4).
 // Env-tunable so QA can exercise the timeout path in seconds instead of minutes.
 const PERMISSION_TIMEOUT_MS = Number(process.env.AGENTUS_PERM_TIMEOUT_MS || 5 * 60_000);
@@ -167,9 +177,10 @@ interface LiveSession {
   }>;
   alwaysAllow: Set<string>; // "allow_always" remembered per live session only (AionUi F-PERM-05)
   stderrBuf: string[];
-  /** What the agent says it can do (initialize.agentCapabilities), kept because the title
-   *  regeneration is only possible when it advertises `session/fork`. */
-  caps: { fork: boolean; load: boolean };
+  /** What the agent says it can do (initialize.agentCapabilities). `fork` gates title
+   *  regeneration, `load` gates resume; `image` is the one a TURN can be refused on — see
+   *  `IMAGE_UNSUPPORTED` in `prompt()`. */
+  caps: { fork: boolean; load: boolean; image: boolean };
   /** Incremented when a turn STARTS. An interrupt waits for the specific turn it cancelled,
    *  so a second interrupting utterance that already started its own turn is not mistaken for
    *  "the one I cancelled is still running". */
@@ -212,6 +223,11 @@ interface LiveSession {
    *  what keeps the tool's writes scoped to this one session even if the spawn command is copied
    *  out of `ps`. Lives and dies with the process that received it. */
   planToken: string;
+  /** Minted per agent process and handed to the CHILD's ENVIRONMENT (issue #15): the cockpit CLI
+   *  (`$AGENTUS_COCKPIT_BIN`) reads it, so an agent can look at the rest of the cockpit without ever
+   *  touching a port or a token itself. Scoped to this one session, like `planToken` — and dies with
+   *  the process that received it, so a copied `ps` line is worth nothing later. */
+  cockpitToken: string;
   /** ACP v2 lets a session carry several plans (`planId`); the card renders one. Whichever planId
    *  shows up first is adopted and the rest are left alone — see the `plan_update` case. */
   planId?: string;
@@ -252,6 +268,11 @@ export class SessionManager {
       // flag alone, so a restored-then-archived slot can be live). It is listed by `archived()`
       // instead — one row in one bucket, or the rail shows the same slot twice.
       .filter((s) => this.#store.getSession(s.info.id)?.archivedAt == null)
+      // A SYSTEM session (the 工作播报 observer, issue #16) is the cockpit's own machinery: it has a
+      // transcript and a process like any other slot, but it is not WORK IN FLIGHT. Filtering here —
+      // the one gate the rail, the cockpit CLI and the warm-slot ranking all read through — is what
+      // keeps an observer from showing up as a ghost row beside the session it watches.
+      .filter((s) => !s.info.system)
       .map((s) => ({
         ...s.info,
         lastSeq: this.#store.maxSeq(s.info.id),
@@ -263,6 +284,33 @@ export class SessionManager {
       .sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0) || b.createdAt - a.createdAt);
   }
 
+  /** Wait until a slot can accept a prompt (its handshake finished), or explain why it never will.
+   *  `create()` deliberately returns BEFORE the handshake, so a caller that spawns and prompts in the
+   *  same breath (the 工作播报 observer, issue #16) has to wait for the one thing only the agent can
+   *  tell us. Throws on a slot that died while we waited — silence would leave the observer looking
+   *  alive forever. */
+  async awaitReady(id: string, timeoutMs = 30_000): Promise<SessionInfo> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const s = this.#sessions.get(id);
+      if (!s) throw new Error(`no such session: ${id}`);
+      if (s.conn && s.info.acpSessionId) return s.info;
+      if (s.info.status === "error" || s.info.status === "closed") {
+        throw new Error(`session ${id} is ${s.info.status}${s.info.lastError ? `: ${s.info.lastError}` : ""}`);
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`session ${id} did not become ready within ${Math.round(timeoutMs / 1000)}s`);
+      }
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+
+  /** The ACP mode state of a live slot, for callers that must not go through the rail's lists
+   *  (issue #16's observer picks a read-only mode as soon as the handshake announces one). */
+  modesOf(id: string): SessionModeState | null {
+    return this.#sessions.get(id)?.info.modes ?? null;
+  }
+
   isBusy(id: string): boolean {
     return this.#sessions.get(id)?.busy ?? false;
   }
@@ -377,7 +425,10 @@ export class SessionManager {
     } catch { /* the row is evidence, not control flow */ }
   }
 
-  async create(backend: BackendId, cwd: string, title?: string): Promise<SessionInfo> {
+  /** `opts.system` marks a session the COCKPIT is spawning for itself (issue #16's observer). It
+   *  is a real ACP session and behaves like one everywhere below (close, idle-reap, resume), but it
+   *  is born out of the rail's scope and stays out of it. */
+  async create(backend: BackendId, cwd: string, title?: string, opts: { system?: boolean } = {}): Promise<SessionInfo> {
     const shape = this.#spawnShape(backend);
     if (!shape) throw new Error(`unknown backend: ${backend}`);
     const { spec, args } = shape;
@@ -386,6 +437,13 @@ export class SessionManager {
 
     // isolation: never let a child inherit its way back into the live runtime home
     const plan = buildSpawnEnv(spec);
+    // before the handshake, because the agent resolves its skill roots when the session starts —
+    // not later
+    plan.env = this.#skillsEnv(spec, plan.env);
+    // the cockpit CLI's identity for THIS process (issue #15) — minted before the spawn because it
+    // travels in the child's own environment
+    const cockpitToken = randomUUID();
+    plan.env = this.#cockpitEnv(plan.env, id, cockpitToken);
     // measured once per spawn: how long the row took to reach `ready` (or to die trying)
     const spawnStarted = Date.now();
 
@@ -420,11 +478,13 @@ export class SessionManager {
         pid: child.pid ?? null,
         title: title || `${spec.label} @ ${shortCwd(cwd)}`,
         autoTitle: title || `${spec.label} @ ${shortCwd(cwd)}`,
+        ...(opts.system ? { system: true } : {}),
         createdAt: now, modes: null, configOptions: [], commands: [],
       },
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
-      caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
+      caps: { fork: false, load: false, image: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      cockpitToken,
       // A brand-new process is, by definition, freshly used: the click that spawned it is the
       // activity. Without this the slot inherits the store's message clock — yesterday's — and the
       // reaper's first tick after the spawn kills the process the operator just asked for.
@@ -494,14 +554,7 @@ export class SessionManager {
         protocolVersion: 1,
         clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
       });
-      const caps = (init?.agentCapabilities ?? {}) as {
-        loadSession?: boolean;
-        sessionCapabilities?: { fork?: unknown };
-      };
-      live.caps = {
-        fork: Boolean(caps.sessionCapabilities?.fork),
-        load: Boolean(caps.loadSession),
-      };
+      live.caps = readCaps(init?.agentCapabilities);
       const res = await conn.newSession({ cwd, mcpServers: this.#planMcpServers(spec, live) });
       live.info.acpSessionId = res.sessionId;
       live.info.status = "ready";
@@ -556,6 +609,13 @@ export class SessionManager {
     // point of the workspace being a separate field (see shared/index.ts).
     const resumeCwd = row.workspace || row.cwd;
     const plan = buildSpawnEnv(spec);
+    // A resumed slot is a fresh agent process and re-resolves its skill roots, so a release that
+    // changed the skill lands here too — not only on first create.
+    plan.env = this.#skillsEnv(spec, plan.env);
+    // a resumed slot is a NEW process: its cockpit identity is minted here, like create()'s. The old
+    // child's token died with the old child.
+    const cockpitToken = randomUUID();
+    plan.env = this.#cockpitEnv(plan.env, id, cockpitToken);
     // ── Can this slot come back AT ALL? ──────────────────────────────────────────────────────
     // A session's agent-side state lives in the home it was CREATED under; a resume hands the
     // agent whatever home the row names TODAY. If those differ, the agent is being asked about a
@@ -594,6 +654,9 @@ export class SessionManager {
         workspace: row.workspace ?? null,
         contextLimit: row.contextLimit ?? null,
         status: "starting", pid: child.pid ?? null, title: row.title,
+        // a resumed system session is still a system session (issue #16): the observer is reaped and
+        // resumed like any slot, and must come back out of the rail's scope, not into it
+        ...(row.system ? { system: true } : {}),
         createdAt: row.createdAt,
         modes: (row.modes ?? null) as SessionModeState | null,
         configOptions: (row.configOptions ?? []) as ConfigOptionView[],
@@ -603,8 +666,9 @@ export class SessionManager {
         commands: normCommands(row.commands),
       },
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
-      caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
+      caps: { fork: false, load: false, image: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      cockpitToken,
       // A brand-new process is, by definition, freshly used: the click that spawned it is the
       // activity. Without this the slot inherits the store's message clock — yesterday's — and the
       // reaper's first tick after the spawn kills the process the operator just asked for.
@@ -644,6 +708,7 @@ export class SessionManager {
         protocolVersion: 1,
         clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
       });
+      live.caps = readCaps(reloadInit?.agentCapabilities);
       let loaded = (await conn.loadSession({
         sessionId: row.acpSessionId, cwd: row.cwd, mcpServers: this.#planMcpServers(spec, live),
       })) as { modes?: SessionModeState | null; configOptions?: ConfigOptionView[]; sessionId?: string } | undefined;
@@ -813,7 +878,7 @@ export class SessionManager {
     const lastAtAll = this.#store.lastActivityAt();
     return this.#store
       .listSessions(true)
-      .filter((r) => r.archivedAt != null)
+      .filter((r) => r.archivedAt != null && !r.system)
       .map((r) => {
         const live = this.#sessions.get(r.id);
         // An archived row can still have a process — resume does not touch the flag — and then it is
@@ -842,7 +907,8 @@ export class SessionManager {
   cold(limit = 20): SessionInfo[] {
     return this.#store
       .listSessions(true)
-      .filter((r) => r.archivedAt == null && !this.#sessions.has(r.id))
+      // system rows are the cockpit's own (see list()): never offered as a slot to wake
+      .filter((r) => r.archivedAt == null && !r.system && !this.#sessions.has(r.id))
       .map((r) => this.#infoFromRow(r))
       // cold rows by the same rule as live ones (recent chat first), THEN take the page
       .sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0) || b.createdAt - a.createdAt)
@@ -856,7 +922,8 @@ export class SessionManager {
       workspace: r.workspace ?? null,
       models: (r.models ?? null) as SessionInfo["models"],
       contextLimit: r.contextLimit ?? null,
-      title: r.title, autoTitle: r.autoTitle ?? null, status: r.status, pid: null, createdAt: r.createdAt,
+      title: r.title, autoTitle: r.autoTitle ?? null, titleBy: r.titleBy ?? null, status: r.status, pid: null,
+      createdAt: r.createdAt,
       modes: (r.modes ?? null) as SessionModeState | null,
       configOptions: (r.configOptions ?? []) as ConfigOptionView[],
       usage: (r.usage ?? null) as SessionInfo["usage"],
@@ -864,6 +931,7 @@ export class SessionManager {
       lastSeq: this.#store.maxSeq(r.id),
       lastAt: this.#store.lastActivityAt().get(r.id) ?? r.createdAt,
       archivedAt: r.archivedAt ?? null,
+      ...(r.system ? { system: true } : {}),
       // no process by construction: this path only ever runs for a row that is not in the map
       cold: true,
     };
@@ -873,10 +941,27 @@ export class SessionManager {
     sessionId: string,
     text: string,
     attachments: PromptAttachment[] = [],
-    opts: { interrupt?: boolean } = {},
+    opts: {
+      interrupt?: boolean;
+      /**
+       * Who SAID this, when it was not the operator at the keyboard — today only the cockpit's
+       * cross-session `send`. It rides the stored payload so the page can label the bubble instead of
+       * presenting another agent's words as the operator's own (which is what it did before: a user
+       * message, no attribution, indistinguishable from something they typed).
+       */
+      origin?: { sessionId: string; title?: string | null };
+    } = {},
   ): Promise<void> {
     const s = this.#need(sessionId);
     if (!s.conn || !s.info.acpSessionId) throw new Error("session not ready");
+    // An image the agent cannot take is refused HERE, above the floor-taking logic (issue #17):
+    // · below it, a busy agent answers "turn already running" and the operator never learns that the
+    //   picture is the problem — they retry, the turn ends, and it fails the same way for a new reason;
+    // · through it, one of two silent failures: the agent errors on a content block, or drops it and
+    //   answers as if nothing was attached.
+    // Neither is something the cockpit could explain afterwards, so it is said now, and the running
+    // turn is left alone (a refused prompt must never cancel one).
+    if (attachments.some((a) => a.kind === "image") && !s.caps.image) throw new Error(IMAGE_UNSUPPORTED);
     if (s.busy) {
       // Someone is talking over the agent. Plain prompts are refused (the operator's send
       // button is a stop button), but a call utterance carries `interrupt: true`: give the
@@ -933,7 +1018,14 @@ export class SessionManager {
     const turnStartedAt = Date.now();
     this.#emit({ t: "turn-start", sessionId, trace: this.#turnTrace(s) });
     const msg = this.#store.appendMessage({
-      sessionId, kind: "user", payload: { text, attachments: summarize(attachments) }, createdAt: Date.now(),
+      sessionId,
+      kind: "user",
+      payload: {
+        text,
+        attachments: summarize(attachments),
+        ...(opts.origin ? { origin: { sessionId: opts.origin.sessionId, title: opts.origin.title ?? null } } : {}),
+      },
+      createdAt: Date.now(),
     });
     this.#touch(s, msg.createdAt);
     this.#emit({ t: "message", message: msg });
@@ -1103,6 +1195,68 @@ export class SessionManager {
    *  is driving the session and vanishes for an agent started from the CLI, cron or Studio — which
    *  is the whole difference from a `config.yaml` entry like the `ekko_studio_*` ones (§4).
    *  The token in `env` is minted for THIS session, so a copied-out command writes only its own. */
+  /** The cockpit CLI's identity, in the CHILD's environment (issue #15).
+   *
+   *  Handed over the same way the plan token is — per process, per session, nowhere else — so the
+   *  agent never handles a port or a secret: it runs `$AGENTUS_COCKPIT_BIN context` and the CLI reads
+   *  these three. Rendering it into a prompt, an `echo`, or a `ps` line is the one thing the CLI's own
+   *  `capabilities` forbids, and the token is worth nothing once this process is gone. */
+  #cockpitEnv(env: NodeJS.ProcessEnv, sessionId: string, token: string): NodeJS.ProcessEnv {
+    return {
+      ...env,
+      AGENTUS_COCKPIT_ENDPOINT: `http://127.0.0.1:${process.env.AGENTUS_PORT ?? 8788}`,
+      AGENTUS_COCKPIT_TOKEN: token,
+      AGENTUS_COCKPIT_SESSION: sessionId,
+      AGENTUS_COCKPIT_BIN: COCKPIT_BIN,
+    };
+  }
+
+  /** Hand this package's skills to the agent for THIS process only, when its backend has a channel.
+   *
+   *  `skillsEnv` (Hermes: `HERMES_EXTERNAL_SKILLS_DIRS`, the per-process half of `skills.external_dirs`)
+   *  is a root the agent reads and we never write: `skill_view` resolves our corpus, and not one byte
+   *  lands in the operator's home — the same `~/.hermes` that Studio, cron and every terminal `hermes`
+   *  share, where a copied skill would surface in sessions that have nothing to do with the cockpit.
+   *  A backend without such a variable falls through to `#installSkills`, the only channel it has.
+   */
+  #skillsEnv(spec: BackendSpec, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+    if (!spec.skillsEnv) return env;
+    return { ...env, [spec.skillsEnv]: SKILLS_ROOT };
+  }
+
+  /**
+   * FALLBACK (vendors with no extra-roots channel): copy this package's skills into the agent's own
+   * skills directory. Every backend we ship today takes `skillsEnv` instead, so this only runs for a
+   * row whose spec names `skillsDir` without one.
+   *
+   * Failures are WARNINGS, never session failures: a slot whose skill could not be written still runs
+   * — it just learns about the CLI from the one-line reminder and `agentus cockpit skill` instead of
+   * native discovery. Turning a read-only-to-us directory (a home owned by root, a read-only mount)
+   * into a dead slot would be a much worse trade than a missing manual.
+   */
+  #installSkills(spec: BackendSpec, home: string | null): void {
+    if (!spec.skillsDir || !home) return;
+    try {
+      const r = installSkills(resolveSkillsDir(spec.skillsDir, home));
+      if (r.installed.length || r.updated.length) {
+        console.log(
+          `[agentus] skills → ${r.dir}: ` +
+            [...r.installed.map((n) => `${n} (new)`), ...r.updated.map((n) => `${n} (updated)`)].join(", "),
+        );
+      }
+    } catch (err) {
+      console.warn(`[agentus] could not install skills into ${spec.skillsDir} (${home}): ${errMessage(err)}`);
+    }
+  }
+
+  /** Resolve a cockpit-channel token to the session it was minted for (issue #15). One token, one
+   *  session: a copied env var reads that session's scope and nothing wider. */
+  cockpitCaller(token: string): string | null {
+    if (!token) return null;
+    for (const s of this.#sessions.values()) if (s.cockpitToken === token) return s.info.id;
+    return null;
+  }
+
   #planMcpServers(spec: BackendSpec, live: LiveSession): McpServer[] {
     if (nativePlanSourceOf(spec) !== "none") return [];
     return [
@@ -1219,7 +1373,7 @@ export class SessionManager {
    *  truth (it does not own this list) or the model will keep believing it does. On an MCP-driven row
    *  the tool is the session's ONLY writer, so it takes the card over even when an older build had
    *  written it from frames (`acceptsToolWrite`). */
-  writePlanFromMcp(sessionId: string, token: string, input: { items: unknown; explanation?: unknown }):
+  writePlanFromMcp(sessionId: string, token: string, input: { items: unknown; title?: unknown; explanation?: unknown }):
     | { ok: true; accepted: boolean; reason?: string; plan: PlanSnapshot | null }
     | { ok: false; error: string } {
     const live = this.#sessions.get(sessionId);
@@ -1243,6 +1397,10 @@ export class SessionManager {
     }
     const plan = this.#store.upsertPlan(sessionId, {
       items,
+      // `undefined` = keep whatever title is on the card (same rule as the remark): most writes are
+      // a status flip and carry no title, and those must not erase the phrase the completion card
+      // reads. `null`/empty clears it (clampTitle answers null).
+      ...(input.title !== undefined ? { title: clampTitle(input.title) } : {}),
       ...(input.explanation !== undefined ? { explanation: clampExplanation(input.explanation) } : {}),
       source: "mcp",
       // A write means work is happening again: the previous turn's terminal stamp no longer
@@ -1312,6 +1470,14 @@ export class SessionManager {
       return null;
     }
 
+    // The cockpit channel (issue #15) rides the same block: ONE line, because its whole job is to say
+    // that a readable panel exists. The contract itself lives on the other end (`capabilities` is
+    // self-describing), so nothing here needs to be kept in sync with the CLI.
+    body.push(
+      "",
+      "本驾驶舱可用 `$AGENTUS_COCKPIT_BIN session list`（其它会话状态/消息/计划；先 capabilities，全文 skill）。",
+    );
+
     return {
       type: "resource",
       resource: {
@@ -1604,6 +1770,16 @@ export class SessionManager {
     if (live.replaying && (isTextFrame || isToolFrame) && this.#store.maxSeq(live.info.id) > 0) {
       return;
     }
+    // A status line from the agent (issue #18). Hermes sends these on ACP as an EMPTY thought chunk
+    // whose `_meta.hermes` carries the sentence — the protocol has no status object, and `_meta` is the
+    // extension door it does leave open. Honoured here rather than in the web, because the decision that
+    // matters is 「do not persist」: a recall count belongs to the turn that is running, and writing it
+    // into the transcript would put 「recalled 8 memories」 above a conversation from last month.
+    const statusText = statusLineOf(u);
+    if (statusText) {
+      this.#emit({ t: "status", sessionId: live.info.id, text: statusText, statusKind: statusKindOf(u) });
+      return;
+    }
     let msg: Parameters<Store["appendMessage"]>[0] | null = null;
     switch (st) {
       case "agent_message_chunk":
@@ -1802,7 +1978,10 @@ export class SessionManager {
     // The remembered window follows the model, so it has to be refreshed whenever the
     // model (or anything else) changes — this is the one place every mutation passes.
     s.info.modelContextLimit = this.#store.getModelLimit(s.info.models?.currentModelId ?? null);
-    this.#emit({ t: "session", session: s.info });
+    // A system session never appears in a `session` frame: the rail would add it to a bucket that
+    // list()/cold() deliberately do not contain, and #13 is precisely the bug where the two
+    // disagree. The page learns about observers through `speak` lines, not through the rail.
+    if (!s.info.system) this.#emit({ t: "session", session: s.info });
     const row = this.#store.getSession(s.info.id);
     if (row) {
       // Persist the LIVE metadata too, not just status/pid: without modes/configOptions/
@@ -1833,6 +2012,22 @@ export class SessionManager {
     return this.#store.messagesAfter(sessionId, afterSeq, limit);
   }
 
+  /** The cockpit CLI's read view (issue #15): the sessions the OPERATOR can see, in one list —
+   *  live and cold, never 已归档 (that is the operator's shelf, not work in flight).
+   *
+   *  Cold rows are capped by `cold()`'s own page size on purpose: an agent asking "what is going on"
+   *  gets the recent cockpit, not a scrollback of every session this install ever made. */
+  cockpitRows(): SessionInfo[] {
+    return [...this.list(), ...this.cold(50)];
+  }
+
+  /** Approvals a session is WAITING on right now — the one fact worth waking another agent for. */
+  pendingFor(sessionId: string): PermissionRequestView[] {
+    // The map holds `{view, resolve, timer}`; only the VIEW is safe to hand out (the other two are
+    // the waiter itself).
+    return [...(this.#sessions.get(sessionId)?.pendingPermissions.values() ?? [])].map((p) => p.view);
+  }
+
   /** Re-point a slot's workspace. Live slot: panels + the *next* resume move; the
    *  running child keeps the cwd it was spawned with (ACP fixes cwd at newSession).
    *  Cold slot: the resume will come up in the new directory. */
@@ -1861,14 +2056,18 @@ export class SessionManager {
    *  renamable without waking it up (the agent never hears about this). `null`/blank
    *  clears back to the generated title; control characters fold to spaces and the
    *  result is capped, because this string is rendered in a single-line row. */
-  rename(id: string, title: string | null): SessionInfo {
+  rename(id: string, title: string | null, by: string | null = null): SessionInfo {
     const clean = title == null ? null : title.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim().slice(0, 120).trim();
-    if (!this.#store.renameSession(id, clean && clean.length ? clean : null)) {
+    // A cleared name has no author: after `--auto` the session carries the GENERATED title again, so
+    // keeping "an agent named this" would describe a name that no longer exists.
+    const attributed = clean && clean.length && by ? by : null;
+    if (!this.#store.renameSession(id, clean && clean.length ? clean : null, attributed)) {
       throw new Error(`no such session: ${id}`);
     }
     const live = this.#sessions.get(id);
     if (live) {
       live.info.title = this.#store.getSession(id)?.title ?? live.info.title;
+      live.info.titleBy = attributed;
       this.#updateSession(live);
       this.#emit({ t: "session", session: live.info });
       return live.info;
@@ -1880,7 +2079,7 @@ export class SessionManager {
       workspace: row.workspace ?? null,
       models: (row.models ?? null) as SessionInfo["models"],
       contextLimit: row.contextLimit ?? null,
-      title: row.title, status: row.status, pid: null, createdAt: row.createdAt,
+      title: row.title, titleBy: row.titleBy ?? null, status: row.status, pid: null, createdAt: row.createdAt,
       modes: (row.modes ?? null) as SessionModeState | null,
       configOptions: (row.configOptions ?? []) as ConfigOptionView[],
       usage: (row.usage ?? null) as SessionInfo["usage"],
@@ -2167,6 +2366,50 @@ export class SessionManager {
 /** ACP ContentBlock[] for a prompt: text first (the instruction), then media.
  *  Text attachments are inlined with a filename header because that is what every
  *  agent actually reads well; images go as protocol image blocks. */
+/** What a turn must say when the agent cannot take a picture (issue #17).
+ *
+ *  Kept as a module constant because TWO places have to agree on it: `prompt()` throws it, and the
+ *  server turns it into "your sentence comes back" just like `turn already running`. A second
+ *  literal would drift the moment one side is reworded. */
+export const IMAGE_UNSUPPORTED =
+  "这个后端不支持图片输入（agent 没在 initialize 里声明 promptCapabilities.image）—— 去掉图片再发，或换一个能看图的模型";
+
+/** Read the three capabilities this cockpit acts on. Defensive on purpose: `promptCapabilities`
+ *  is absent on agents that predate it, and an absent field means "no", not "try anyway" — a
+ *  silently dropped image is the failure this whole read exists to prevent. */
+function readCaps(capabilities: unknown): { fork: boolean; load: boolean; image: boolean } {
+  const c = (capabilities ?? {}) as {
+    loadSession?: boolean;
+    sessionCapabilities?: { fork?: unknown };
+    promptCapabilities?: { image?: unknown };
+  };
+  return {
+    fork: Boolean(c.sessionCapabilities?.fork),
+    load: Boolean(c.loadSession),
+    image: c.promptCapabilities?.image === true,
+  };
+}
+
+/** The sentence inside a status carrier, or null when the frame is an ordinary thought chunk.
+ *
+ *  Shape (hermes `acp_adapter/events.py:make_status_cb`): `agent_thought_chunk` with an empty content
+ *  block and `_meta.hermes = { kind: "status", statusKind, text }`. Read defensively — `_meta` is the
+ *  one part of an ACP frame a client may see from agents we have never run.
+ */
+function statusLineOf(u: Record<string, unknown>): string | null {
+  const meta = u?._meta as { hermes?: { kind?: unknown; text?: unknown } } | undefined;
+  const h = meta?.hermes;
+  if (!h || h.kind !== "status") return null;
+  const text = typeof h.text === "string" ? h.text.trim() : "";
+  return text || null;
+}
+
+function statusKindOf(u: Record<string, unknown>): string | undefined {
+  const meta = u?._meta as { hermes?: { statusKind?: unknown } } | undefined;
+  const kind = meta?.hermes?.statusKind;
+  return typeof kind === "string" && kind ? kind : undefined;
+}
+
 function buildPromptBlocks(text: string, attachments: PromptAttachment[]): unknown[] {
   const blocks: unknown[] = [];
   const body = text.trim();
@@ -2202,6 +2445,7 @@ function sessionRow(i: SessionInfo, home: string | null = null) {
     modes: i.modes ?? null, configOptions: i.configOptions ?? [],
     usage: i.usage ?? null, commands: i.commands ?? [],
     models: i.models ?? null,
+    system: Boolean(i.system),
     // only ever written by the insert (creation); see Store.upsertSession
     home,
   };