@agentproto/runtime 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -316,7 +316,7 @@ declare function composeMode(cfg: Partial<SessionConfig>, modes: readonly Declar
  * and session_monitor MCP tool (long-poll multiplexed).
  */
 
-type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:command-done" | "session:model-changed" | "session:config-changed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:permission-request" | "session:permission-resolved" | "session:exited" | "session:command-done" | "session:model-changed" | "session:config-changed" | "session:renamed" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed";
 /**
  * Structured detail on why a session is awaiting input, when derivable.
  * `source: "structured"` — a driver-reported ACP-style prompt (e.g. a tool
@@ -470,6 +470,24 @@ type SessionConfigChangedEvent = {
         ts: string;
     };
 }[SessionConfigAxis];
+/**
+ * Emitted when an operator sets or clears a session's user-facing name
+ * (`PATCH /sessions/:id`, the `session_rename` MCP verb). Unlike
+ * `session:config-changed`, a name is NOT a `SessionConfig` axis — it never
+ * touches the live agent, only the descriptor's display fields — so it rides
+ * its own event. `title`/`label` carry the values now on the descriptor
+ * (absent when that field was cleared). Same bus distribution as every other
+ * lifecycle event: `session_events_poll`, the webhook notifier, the routine
+ * engine — which is how a live UI (the VS Code tree / transcript header/tab)
+ * learns to repaint the name without waiting for its next snapshot poll.
+ */
+interface SessionRenamedEvent {
+    type: "session:renamed";
+    sessionId: string;
+    title?: string;
+    label?: string;
+    ts: string;
+}
 /** Emitted by the supervisor when a completion policy's gate passes. */
 interface PolicyPassedEvent {
     type: "policy:passed";
@@ -534,7 +552,7 @@ interface CronFailedEvent {
     error: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent;
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | SessionExitedEvent | SessionCommandDoneEvent | SessionModelChangedEvent | SessionConfigChangedEvent | SessionRenamedEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -1391,6 +1409,19 @@ interface SessionsRegistry {
      *  there is nothing to re-validate). Throws only when the id is
      *  unknown. */
     unarchiveSession(id: string): SessionDescriptor;
+    /** Set or clear a session's user-facing name (`PATCH /sessions/:id`, the
+     *  `session_rename` MCP verb). Each of `title`/`label`: a non-empty string
+     *  sets that field (trimmed, capped to the derivation's `MAX_LENGTH` by
+     *  code point); an empty/whitespace-only string or `null` CLEARS it (the
+     *  UI reverts to the derived title / friendly fallback); `undefined`
+     *  leaves it untouched. Persists via the same `schedulePersist` every
+     *  descriptor mutation uses, and emits `session:renamed` so live UIs
+     *  repaint. Pure display state — never touches the live agent. Throws when
+     *  the id is unknown. */
+    renameSession(id: string, patch: {
+        title?: string | null;
+        label?: string | null;
+    }): SessionDescriptor;
     /** Subscribe to a session's output. Returns an unsubscribe fn.
      *  Initial backfill: synchronously invokes `onLine` once for each
      *  line currently in the ring buffer so attaches show context. */

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { createReadStream, existsSync, promises, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, createWriteStream, statSync, openSync, closeSync } from 'fs';
+import { createReadStream, existsSync, promises, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, realpathSync, createWriteStream, statSync, openSync, closeSync } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { join, resolve, dirname, isAbsolute, normalize, relative, basename } from 'path';
 import { createInterface } from 'readline';
@@ -1955,9 +1955,19 @@ function setActiveWorkspace(config, slug) {
 function findWorkspace(config, slug) {
   return config.workspaces.find((w) => w.slug === sanitizeSlug(slug));
 }
+function canonical(p) {
+  try {
+    return realpathSync(resolve(p));
+  } catch {
+    return resolve(p);
+  }
+}
 function findWorkspaceByPath(config, dir) {
-  const resolved = resolve(dir);
-  const candidates = config.workspaces.filter((w) => resolved.startsWith(resolve(w.path) + "/") || resolved === resolve(w.path)).sort((a, b) => b.path.length - a.path.length);
+  const resolved = canonical(dir);
+  const candidates = config.workspaces.filter((w) => {
+    const wPath = canonical(w.path);
+    return resolved.startsWith(wPath + "/") || resolved === wPath;
+  }).sort((a, b) => b.path.length - a.path.length);
   return candidates[0];
 }
 function getActiveWorkspace(config) {
@@ -2043,6 +2053,76 @@ async function loadConfig(path) {
     return {};
   }
 }
+var markerSchema = z.object({ worktreeId: z.string() });
+function statOrUndefined(path) {
+  try {
+    return statSync(path);
+  } catch {
+    return void 0;
+  }
+}
+function readWorktreeGitDir(dir) {
+  const link = (() => {
+    try {
+      return readFileSync(join(dir, ".git"), "utf8");
+    } catch {
+      return void 0;
+    }
+  })();
+  if (link === void 0) return void 0;
+  const target = /^gitdir:\s*(.+)$/m.exec(link)?.[1]?.trim();
+  if (!target) return void 0;
+  const gitDir = isAbsolute(target) ? target : resolve(dir, target);
+  return statOrUndefined(join(gitDir, "gitdir"))?.isFile() === true ? gitDir : void 0;
+}
+function readMainRepoPath(gitDir) {
+  let raw;
+  try {
+    raw = readFileSync(join(gitDir, "commondir"), "utf8").trim();
+  } catch {
+    return void 0;
+  }
+  if (!raw) return void 0;
+  const commonGitDir = isAbsolute(raw) ? raw : resolve(gitDir, raw);
+  return dirname(commonGitDir);
+}
+function readWorktreeId(gitDir) {
+  let raw;
+  try {
+    raw = readFileSync(join(gitDir, "agentproto-worktree.json"), "utf8");
+  } catch {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  const result = markerSchema.safeParse(parsed);
+  return result.success ? result.data.worktreeId : void 0;
+}
+function resolveWorktreeIdentity(cwd) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    const dotGit = statOrUndefined(join(dir, ".git"));
+    if (dotGit) {
+      if (!dotGit.isFile()) return void 0;
+      const gitDir = readWorktreeGitDir(dir);
+      if (gitDir === void 0) return void 0;
+      const worktreeId = readWorktreeId(gitDir);
+      const mainRepoPath = readMainRepoPath(gitDir);
+      return {
+        worktreePath: dir,
+        ...worktreeId === void 0 ? {} : { worktreeId },
+        ...mainRepoPath === void 0 ? {} : { mainRepoPath }
+      };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
 
 // src/providers-store.ts
 var providers_store_exports = {};
@@ -2613,15 +2693,38 @@ async function spawnAgentSession(deps2, input) {
     try {
       const config = await loadWorkspacesConfig();
       if (!cwd) {
-        const ws = input.workspaceSlug ? findWorkspace(config, input.workspaceSlug) : getActiveWorkspace(config);
-        if (ws) {
-          cwd = ws.path;
-          resolvedSlug = ws.slug;
+        if (input.workspaceSlug) {
+          const ws = findWorkspace(config, input.workspaceSlug);
+          if (ws) {
+            cwd = ws.path;
+            resolvedSlug = ws.slug;
+          }
+        } else if (callerScope) {
+          const parentCwd = callerScope.ownerSessionId ? registry.get(callerScope.ownerSessionId)?.cwd : void 0;
+          if (parentCwd) {
+            cwd = parentCwd;
+            const ws = findWorkspaceByPath(config, parentCwd);
+            if (ws) {
+              resolvedSlug = ws.slug;
+            }
+          }
+        } else {
+          const ws = getActiveWorkspace(config);
+          if (ws) {
+            cwd = ws.path;
+            resolvedSlug = ws.slug;
+          }
         }
       } else if (!resolvedSlug) {
         const ws = findWorkspaceByPath(config, cwd);
         if (ws) {
           resolvedSlug = ws.slug;
+        } else {
+          const identity = resolveWorktreeIdentity(cwd);
+          if (identity?.mainRepoPath) {
+            const baseWs = findWorkspaceByPath(config, identity.mainRepoPath);
+            if (baseWs) resolvedSlug = baseWs.slug;
+          }
         }
       }
     } catch {
@@ -2827,7 +2930,8 @@ async function spawnAgentSession(deps2, input) {
   const effectivePrompt = input.prompt ? `${composeRoleContext(role, input.promptAppend, roleRegistry)}
 
 ${input.prompt}` : input.prompt;
-  const initialTitle = input.prompt ? deriveSessionTitle(input.prompt) : void 0;
+  const explicitTitle = input.title?.trim() ? input.title.trim() : void 0;
+  const initialTitle = explicitTitle ?? (input.prompt ? deriveSessionTitle(input.prompt) : void 0);
   let settleClaim;
   if (input.idempotencyKey) {
     const claims = claimsFor(registry);
@@ -5648,6 +5752,90 @@ function registerSessionTools(rawServer, opts) {
       }
     }
   );
+  server.tool(
+    "session_rename",
+    "Set or clear a session's user-facing name \u2014 the label the sessions tree, transcript header, and tab show. `label` out-ranks `title` in that display chain, so a user rename should write `label` (the default a UI picks) to be sure it shows; `title` is the auto-derived first-sentence fallback. For EACH of `title`/`label`: a non-empty string sets it (trimmed + length-capped), an empty string clears it (reverting to the derived title / a friendly `adapter \xB7 id` fallback), and omitting it leaves that field untouched. Persists across daemon restarts. Does NOT rename the adapter-native session or touch the running agent.",
+    {
+      idOrName: z.string().min(1).describe("Session id or name to rename \u2014 from `session_list`."),
+      label: z.string().optional().describe(
+        "New label (the winning display field). Empty string clears it. Omit to leave the label untouched."
+      ),
+      title: z.string().optional().describe(
+        "New title (the auto-derived fallback slot). Empty string clears it, reverting to the first-sentence derivation. Omit to leave it untouched."
+      )
+    },
+    async (input) => {
+      const prev = registry.findByIdOrName(input.idOrName);
+      if (!prev) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `no session "${input.idOrName}" found` })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (callerScope) {
+        const subtree = collectSubtree(
+          callerScope.ownerSessionId,
+          registry.list({ includeArchived: true })
+        );
+        if (!subtree.has(prev.id)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "orchestrator_session_out_of_scope",
+                  message: `session_rename: session "${prev.id}" is not in your subtree \u2014 a scoped orchestrator can only rename sessions it (transitively) spawned.`,
+                  ok: false,
+                  sessionId: prev.id
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+      if (input.title === void 0 && input.label === void 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "nothing_to_rename",
+                message: "session_rename: supply at least one of `title` or `label`.",
+                ok: false,
+                sessionId: prev.id
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const desc = registry.renameSession(prev.id, {
+          ...input.title !== void 0 ? { title: input.title } : {},
+          ...input.label !== void 0 ? { label: input.label } : {}
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(desc, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `session_rename: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
   server.tool(
     "terminal_start",
     "Spawn a process under a real PTY (node-pty) on the host. Bytes (including ANSI escapes, alt-screen sequences) flow through the daemon's byte ring buffer; subscribers attach via the WS at /sessions/:id/pty. Use for interactive TUIs (claude, vim, htop) or to orchestrate shells from another agent. Returns the session descriptor.",
@@ -8940,60 +9128,6 @@ function createTerminalTranscriptWriter(opts) {
     }
   };
 }
-var markerSchema = z.object({ worktreeId: z.string() });
-function statOrUndefined(path) {
-  try {
-    return statSync(path);
-  } catch {
-    return void 0;
-  }
-}
-function readWorktreeGitDir(dir) {
-  const link = (() => {
-    try {
-      return readFileSync(join(dir, ".git"), "utf8");
-    } catch {
-      return void 0;
-    }
-  })();
-  if (link === void 0) return void 0;
-  const target = /^gitdir:\s*(.+)$/m.exec(link)?.[1]?.trim();
-  if (!target) return void 0;
-  const gitDir = isAbsolute(target) ? target : resolve(dir, target);
-  return statOrUndefined(join(gitDir, "gitdir"))?.isFile() === true ? gitDir : void 0;
-}
-function readWorktreeId(gitDir) {
-  let raw;
-  try {
-    raw = readFileSync(join(gitDir, "agentproto-worktree.json"), "utf8");
-  } catch {
-    return void 0;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return void 0;
-  }
-  const result = markerSchema.safeParse(parsed);
-  return result.success ? result.data.worktreeId : void 0;
-}
-function resolveWorktreeIdentity(cwd) {
-  let dir = resolve(cwd);
-  for (; ; ) {
-    const dotGit = statOrUndefined(join(dir, ".git"));
-    if (dotGit) {
-      if (!dotGit.isFile()) return void 0;
-      const gitDir = readWorktreeGitDir(dir);
-      if (gitDir === void 0) return void 0;
-      const worktreeId = readWorktreeId(gitDir);
-      return worktreeId === void 0 ? { worktreePath: dir } : { worktreePath: dir, worktreeId };
-    }
-    const parent = dirname(dir);
-    if (parent === dir) return void 0;
-    dir = parent;
-  }
-}
 function normalizeAgentPromptOptions(raw) {
   if (!Array.isArray(raw)) return void 0;
   const labels = raw.map((o) => {
@@ -10529,6 +10663,33 @@ function createSessionsRegistry(opts) {
       stampProcessAlive(rt.desc);
       return rt.desc;
     },
+    renameSession(id, patch) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`renameSession: no session "${id}"`);
+      const apply = (field) => {
+        const raw = patch[field];
+        if (raw === void 0) return;
+        const trimmed = raw === null ? "" : raw.trim();
+        if (trimmed === "") {
+          rt.desc[field] = void 0;
+          return;
+        }
+        const points = Array.from(trimmed);
+        rt.desc[field] = points.length > MAX_LENGTH ? points.slice(0, MAX_LENGTH).join("") : trimmed;
+      };
+      apply("title");
+      apply("label");
+      schedulePersist();
+      sessionEvents?.emit({
+        type: "session:renamed",
+        sessionId: id,
+        ...rt.desc.title !== void 0 ? { title: rt.desc.title } : {},
+        ...rt.desc.label !== void 0 ? { label: rt.desc.label } : {},
+        ts: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      stampProcessAlive(rt.desc);
+      return rt.desc;
+    },
     listPendingPermissions(filter) {
       const all = Array.from(pendingPermissions.values());
       const scoped = filter?.sessionId ? all.filter((p) => p.sessionId === filter.sessionId) : all;
@@ -13667,6 +13828,9 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         })() : {},
         ...typeof b.prompt === "string" ? { prompt: b.prompt } : {},
         ...typeof b.label === "string" ? { label: b.label } : {},
+        // Explicit title override (SPEC-3 FIX C, `--title`) — wins over the
+        // first-sentence derivation from the prompt (see session-spawn.ts).
+        ...typeof b.title === "string" ? { title: b.title } : {},
         ...typeof b.idempotencyKey === "string" && b.idempotencyKey.length > 0 ? { idempotencyKey: b.idempotencyKey } : {},
         ...typeof b.role === "string" && b.role.length > 0 ? { role: b.role } : {},
         ...typeof b.promptAppend === "string" ? { promptAppend: b.promptAppend } : {},
@@ -13923,6 +14087,49 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     }
     return true;
   }
+  const terminalInputMatch = path.match(/^\/sessions\/([^/]+)\/terminal\/input$/);
+  if (terminalInputMatch && req.method === "POST") {
+    const id2 = terminalInputMatch[1];
+    if (!id2) return false;
+    if (!ptyEnabled) {
+      json(501, {
+        error: "pty_not_configured",
+        message: "POST /sessions/:id/terminal/input needs the host to inject `spawnPty` into createGateway (node-pty optional dep \u2014 install in @agentproto/cli)."
+      });
+      return true;
+    }
+    const desc = registry.get(id2);
+    if (!desc) {
+      json(404, { error: "no_session", message: `no session "${id2}"` });
+      return true;
+    }
+    const body = await readJsonBody(req);
+    const text6 = body?.text;
+    if (typeof text6 !== "string") {
+      json(400, { error: "missing_text", message: "Body `text` must be a string." });
+      return true;
+    }
+    if (desc.kind !== "terminal" || desc.pty !== true) {
+      json(400, {
+        error: "not_a_pty",
+        message: `session "${id2}" is not a live PTY (kind=${desc.kind})`
+      });
+      return true;
+    }
+    const enter = body?.enter !== false;
+    let ok = true;
+    if (text6.length > 0) ok = registry.writeTerminalInput(id2, text6) && ok;
+    if (enter) ok = registry.writeTerminalInput(id2, "\r") && ok;
+    if (!ok) {
+      json(400, {
+        error: "not_a_pty",
+        message: `session "${id2}" has no live PTY to write to`
+      });
+      return true;
+    }
+    json(200, { ok: true });
+    return true;
+  }
   const modelMatch = path.match(/^\/sessions\/([^/]+)\/model$/);
   if (modelMatch && req.method === "POST") {
     const id2 = modelMatch[1];
@@ -14046,6 +14253,31 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     }
     return true;
   }
+  const renameMatch = path.match(/^\/sessions\/([^/]+)$/);
+  if (renameMatch && req.method === "PATCH") {
+    const rawIdOrName2 = renameMatch[1];
+    if (!rawIdOrName2) return false;
+    const resolved = registry.findByIdOrName(rawIdOrName2);
+    if (!resolved) {
+      json(404, { error: "session_not_found", id: rawIdOrName2 });
+      return true;
+    }
+    const body = await readJsonBody(req);
+    const b = body && typeof body === "object" ? body : {};
+    const field = (v) => typeof v === "string" ? v : v === null ? null : void 0;
+    const patch = {
+      ..."title" in b ? { title: field(b.title) } : {},
+      ..."label" in b ? { label: field(b.label) } : {}
+    };
+    try {
+      const desc = registry.renameSession(resolved.id, patch);
+      json(200, desc);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      json(msg.includes("no session") ? 404 : 500, { error: "rename_failed", message: msg });
+    }
+    return true;
+  }
   if (path === "/sessions" && req.method === "POST") {
     const body = await readJsonBody(req);
     if (!body || typeof body !== "object") {