@monster-orange/den 0.4.13 → 0.4.14

package/src/ui/cli/agent-ops.ts

@@ -129,6 +129,7 @@ import {
   syncConfiguredRuntimes,
   type AgentMcp,
   type LaunchInput,
+  type LaunchOutput,
   type Runtime,
 } from "../../shared/agents/runtimes.js";
 import type {
@@ -136,6 +137,11 @@ import type {
   RuntimeModel,
   RuntimePermissions,
 } from "../../shared/agents/runtime.js";
+import {
+  OPEN_ELSEWHERE_MESSAGE,
+  openElsewhere,
+  type RuntimeConversation,
+} from "../../shared/agents/conversations.js";
 import {
   archiveHandoff,
   DEFAULT_ROTATE,
@@ -185,6 +191,11 @@ export interface AgentsDeps extends SessionsDeps {
   distRoot?: () => string;
   /** A workspace's checkout directory: where its agents run. */
   workspaceDir?: (ws: string) => string;
+  /**
+   * AG-17.1: the folders a workspace's conversations may have run in: its
+   * own folder, and each repo's path, a repo added by path outside it too.
+   */
+  workspaceFolders?: (ws: string) => string[];
   /** The MCP server binary and its env; Den adds the scoped args. */
   mcpServer?: () => { command: string[] | string; env: Record<string, string> };
   /**
@@ -221,6 +232,7 @@ export interface AgentsResolved extends Resolved {
   agentsConfig: () => ResolvedAgentsConfig;
   distRoot: () => string;
   workspaceDir: (ws: string) => string;
+  workspaceFolders: (ws: string) => string[];
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
   stopWaitMs: number;
@@ -250,6 +262,8 @@ export class AgentError extends Error {
   readonly usage: boolean;
   readonly code?: string;
   readonly hints: string[];
+  /** AG-10.10: the running agent a start collided with, so a page can open it. */
+  readonly running?: { id: string; sessionId: string };
   constructor(
     message: string,
     o: {
@@ -257,6 +271,7 @@ export class AgentError extends Error {
       usage?: boolean;
       code?: string;
       hints?: string[];
+      running?: { id: string; sessionId: string };
     } = {},
   ) {
     super(message);
@@ -265,6 +280,7 @@ export class AgentError extends Error {
     this.usage = o.usage ?? false;
     this.code = o.code;
     this.hints = o.hints ?? [];
+    if (o.running) this.running = o.running;
   }
 }
 
@@ -276,6 +292,7 @@ const refused = (message: string, hints: string[] = [], status = 409) =>
   new AgentError(message, { status, hints });
 
 let workspaceDirFn: ((ws: string) => string) | null = null;
+let repoPathsFn: ((ws: string) => string[]) | null = null;
 /** The workspaces config, for start and resume (loaded on first use). */
 export async function loadAgentWorkspaces(d: AgentsDeps): Promise<void> {
   await loadWorkspaces(d);
@@ -287,6 +304,9 @@ export async function loadAgentWorkspaces(d: AgentsDeps): Promise<void> {
     if (!cfg) throw usage(`workspace "${name}" does not exist`, 404);
     return ws.resolveWorkspaceDir(name, cfg, getReposRoot());
   };
+  // A by-path repo's own folder (repo add <path>), wherever it is.
+  repoPathsFn = (name) =>
+    ws.repoFolders(ws.readWorkspacesFile().workspaces[name]);
 }
 
 /** The distribution's bin shim (as `mcp connect` registers), else Den's CLI. */
@@ -317,6 +337,17 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
         if (!workspaceDirFn) throw new Error("workspaces not loaded");
         return workspaceDirFn(ws);
       }),
+    workspaceFolders:
+      d.workspaceFolders ??
+      ((ws) => {
+        const dir = d.workspaceDir
+          ? d.workspaceDir(ws)
+          : (() => {
+              if (!workspaceDirFn) throw new Error("workspaces not loaded");
+              return workspaceDirFn(ws);
+            })();
+        return [dir, ...(repoPathsFn?.(ws) ?? [])];
+      }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
     stopWaitMs: d.stopWaitMs ?? STOP_WAIT_MS,
@@ -1012,13 +1043,26 @@ function sessionOf(
 }
 
 /**
- * The id an agent gets: --id, else the persona's id while it is free (or
- * this workspace's), else `<persona>-<ws>`.
+ * The id a new start gets without --id (AG-10.10): the persona's id while
+ * no agent has it; `<persona>-<ws>` when another workspace's agent has it;
+ * else the first of `<base>-2`, `<base>-3`… no agent has. A stopped agent's
+ * id is never reused by a new start: only its Resume or Start fresh.
  */
-function defaultId(stateDir: string, persona: string, ws: string): string {
+export function defaultId(
+  stateDir: string,
+  persona: string,
+  ws: string,
+): string {
   const rec = readRecord(stateDir, persona);
-  if (!rec || rec.workspace === ws) return persona;
-  return `${persona}-${ws}`.slice(0, 64);
+  if (!rec) return persona;
+  const base = rec.workspace === ws ? persona : `${persona}-${ws}`.slice(0, 64);
+  if (base !== persona && !readRecord(stateDir, base)) return base;
+  const stem = base.slice(0, 58);
+  for (let n = 2; n < 1000; n++) {
+    const id = `${stem}-${n}`;
+    if (!readRecord(stateDir, id)) return id;
+  }
+  throw refused(`no free agent id for ${persona}: give one with --id`);
 }
 
 function checkId(where: string, id: string): void {
@@ -1310,6 +1354,8 @@ export interface StartRequest {
   permission?: string;
   /** Extra allowed commands for this launch, instead of the persona's. */
   allow?: unknown;
+  /** AG-10.10: a display name for this agent (AG-4b's), to tell two apart. */
+  name?: unknown;
   /**
    * The page's start (AG-10.1): a model must be one the runtime offers,
    * never a free string (the CLI's --model for generic stays free).
@@ -1418,6 +1464,11 @@ interface StartMore {
   rotations?: AgentRecord["rotations"];
   /** Called once the old session is known ended, before the launch. */
   beforeLaunch?: () => void;
+  /**
+   * AG-17.1, bring in a conversation: launch the runtime's resume of this
+   * one (its id, in the folder it ran in) instead of a new conversation.
+   */
+  bringIn?: { token: string; cwd: string };
 }
 
 export async function startAgent(
@@ -1438,6 +1489,13 @@ export async function startAgent(
     );
   const id = req.id ?? defaultId(d.stateDir(), persona.id, ws);
   checkId(where, id);
+  let given: string | null = null;
+  if (req.name !== undefined)
+    try {
+      given = checkDisplayName(req.name);
+    } catch (e) {
+      throw usage(`${where}: ${(e as Error).message}`);
+    }
   syncCatalog(d);
   const rt = runtimeFor(req.runtime ?? persona.runtime ?? DEFAULT_RUNTIME_ID);
   const det = await availableOrRefuse(d, rt, ws);
@@ -1457,6 +1515,10 @@ export async function startAgent(
       ...(rt.permissions ? { allow } : {}),
     }),
     ...(more.firstPrompt ? { firstPrompt: more.firstPrompt } : {}),
+    // AG-17.1: the runtime's resume, in the folder the conversation ran in.
+    ...(more.bringIn
+      ? { worktree: more.bringIn.cwd, resumeToken: more.bringIn.token }
+      : {}),
   };
   // AG-13.4: a command a runtime can't express is said, never dropped.
   const unexpressed =
@@ -1470,10 +1532,14 @@ export async function startAgent(
     const sessions = await c.list();
     const old = prev ? sessionOf(sessions, prev) : undefined;
     if (old && !old.exited)
-      throw refused(`agent ${id} is running (${old.name})`, [
-        `Attach: ${d.cli} sessions attach ${old.name}`,
-      ]);
-    const out = launchOrThrow(() => rt.launch(input));
+      throw new AgentError(`agent ${id} is running (${old.name})`, {
+        status: 409,
+        hints: [`Attach: ${d.cli} sessions attach ${old.name}`],
+        running: { id, sessionId: old.ref.id },
+      });
+    const out = more.bringIn
+      ? { ...broughtIn(rt, input), resumeToken: more.bringIn.token }
+      : launchOrThrow(() => rt.launch(input));
     more.beforeLaunch?.();
     // A new conversation: a handoff left from the last one is kept aside,
     // so the next rotation needs its own (den#4).
@@ -1504,18 +1570,24 @@ export async function startAgent(
           // AG-4b: a name given to the agent is the agent's, not its
           // conversation's: Start fresh and Relaunch keep it. AG-10.8:
           // else its persona's name ("Rita").
-          ...(prev?.displayName
-            ? { displayName: prev.displayName }
-            : persona.displayName
-              ? { displayName: persona.displayName }
-              : {}),
-          ...(prev?.displayName && prev.displayNameAt
-            ? { displayNameAt: prev.displayNameAt }
-            : {}),
+          // AG-10.10: a name given at start wins.
+          ...(given
+            ? { displayName: given, displayNameAt: new Date().toISOString() }
+            : prev?.displayName
+              ? {
+                  displayName: prev.displayName,
+                  ...(prev.displayNameAt
+                    ? { displayNameAt: prev.displayNameAt }
+                    : {}),
+                }
+              : persona.displayName
+                ? { displayName: persona.displayName }
+                : {}),
           // 0.4.8: launched on this token, so a resume continues it.
           ...(out.resumeToken
             ? { resumeToken: out.resumeToken, launched: true }
             : {}),
+          ...(more.bringIn ? { broughtInAt: new Date().toISOString() } : {}),
         },
         argv: out.argv,
         env: out.env,
@@ -1536,6 +1608,183 @@ export async function startAgent(
   });
 }
 
+/** A bring-in's launch: the runtime's resume (AG-17.1), never a new one. */
+function broughtIn(
+  rt: Runtime,
+  input: LaunchInput,
+): Omit<LaunchOutput, "resumeToken"> {
+  const out = launchOrThrow(() => rt.resume?.(input) ?? null);
+  if (!out) throw refused(`${rt.id} can't continue a conversation`);
+  return out;
+}
+
+// ── AG-17.1: bring in a conversation ────────────────────────────────────────
+
+/** A runtime's conversation as Bring in lists it. */
+export interface ListedConversation extends RuntimeConversation {
+  runtime: string;
+  /** Written in the last minute: still open in another terminal. */
+  open: boolean;
+  /** The Den agent already continuing it, if one is. */
+  agent?: string;
+}
+
+/** Each runtime, and whether it can bring a conversation in. */
+export interface BringInRuntime {
+  id: string;
+  label: string;
+  bringIn: boolean;
+  /** Why it can't, for the page. */
+  why?: string;
+}
+
+function bringInRuntimes(): BringInRuntime[] {
+  return runtimeIds().map((id) => {
+    const rt = getRuntime(id)!;
+    const label = rt.label ?? id;
+    return rt.listSessions
+      ? { id, label, bringIn: true }
+      : {
+          id,
+          label,
+          bringIn: false,
+          why: `${label} can't bring in a conversation yet`,
+        };
+  });
+}
+
+/** The conversation id each agent of this state dir continues. */
+function agentByToken(d: AgentsResolved): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const r of listRecords(d.stateDir()))
+    if (r.resumeToken) m.set(`${r.runtime} ${r.resumeToken}`, r.id);
+  return m;
+}
+
+/**
+ * The conversations Bring in offers for workspace `ws` (AG-17.1): each
+ * runtime's own (only those with listSessions), that ran in the
+ * workspace's folder or inside it, newest first. Reading never starts
+ * anything; a runtime's history is read only at the ends of each file.
+ */
+export function listConversations(
+  d: AgentsResolved,
+  ws: string,
+  runtime?: string,
+): { runtimes: BringInRuntime[]; conversations: ListedConversation[] } {
+  const where = "agents import";
+  checkWorkspaceName(where, ws);
+  if (!d.workspaceExists(ws))
+    throw usage(`${where}: workspace "${ws}" does not exist`, 404);
+  syncCatalog(d);
+  if (runtime !== undefined) runtimeFor(runtime);
+  // Its folder and every repo's (one under another is scanned once).
+  const folders = [
+    ...new Set(d.workspaceFolders(ws).map((f) => path.resolve(f))),
+  ];
+  const scan = folders.filter(
+    (f) => !folders.some((o) => o !== f && f.startsWith(o + path.sep)),
+  );
+  const taken = agentByToken(d);
+  const now = Date.now();
+  const conversations: ListedConversation[] = [];
+  const seen = new Set<string>();
+  for (const id of runtimeIds()) {
+    if (runtime !== undefined && id !== runtime) continue;
+    const rt = getRuntime(id);
+    if (!rt?.listSessions) continue;
+    for (const c of scan.flatMap((f) => rt.listSessions!(f, d.env))) {
+      if (seen.has(`${id} ${c.id}`)) continue;
+      seen.add(`${id} ${c.id}`);
+      const agent = taken.get(`${id} ${c.id}`);
+      conversations.push({
+        ...c,
+        runtime: id,
+        open: openElsewhere(c.lastAt, now),
+        ...(agent ? { agent } : {}),
+      });
+    }
+  }
+  conversations.sort((a, b) => b.lastAt.localeCompare(a.lastAt));
+  return { runtimes: bringInRuntimes(), conversations };
+}
+
+export interface ImportRequest {
+  workspace: string;
+  /** The runtime's conversation id. */
+  session: string;
+  persona: string;
+  runtime?: string;
+  id?: string;
+}
+
+/** The persona's id, else the first `<persona>-<n>` no agent has. */
+function freeId(d: AgentsResolved, persona: string): string {
+  if (!readRecord(d.stateDir(), persona)) return persona;
+  for (let n = 2; n < 1000; n++) {
+    const id = `${persona.slice(0, 58)}-${n}`;
+    if (!readRecord(d.stateDir(), id)) return id;
+  }
+  throw refused(`no free agent id for ${persona}: give one with --id`);
+}
+
+/**
+ * Bring a conversation in (AG-17.1): the runtime's resume of it, under Den
+ * (its token, hooks, guards, the folder it ran in, the audit trail), as a
+ * new agent with the persona given. Afterwards it is an agent like any
+ * other: stop, resume, rename. Refused while the conversation is open in
+ * another terminal (written in the last minute), when an agent already
+ * continues it, or when it isn't one of the workspace's.
+ */
+export async function importAgent(
+  d: AgentsResolved,
+  req: ImportRequest,
+): Promise<Started> {
+  const where = "agents import";
+  const runtime = req.runtime ?? DEFAULT_RUNTIME_ID;
+  const { runtimes, conversations } = listConversations(
+    d,
+    req.workspace,
+    runtime,
+  );
+  const rt = runtimes.find((r) => r.id === runtime);
+  if (!rt?.bringIn)
+    throw refused(
+      rt?.why ?? `${runtime} can't bring in a conversation`,
+      [],
+      422,
+    );
+  const c = conversations.find((x) => x.id === req.session);
+  if (!c)
+    throw refused(
+      `${where}: no ${rt.label} conversation "${req.session}" in workspace ${req.workspace}'s folder`,
+      [`List them: ${d.cli} agents import -w ${req.workspace}`],
+      404,
+    );
+  if (c.agent)
+    throw new AgentError(
+      `${where}: agent ${c.agent} already continues this conversation`,
+      {
+        code: "already_agent",
+        hints: [
+          `Resume it: ${d.cli} agents resume ${c.agent} -w ${req.workspace}`,
+        ],
+      },
+    );
+  if (c.open)
+    throw new AgentError(OPEN_ELSEWHERE_MESSAGE, { code: "open_elsewhere" });
+  if (!fs.statSync(c.cwd, { throwIfNoEntry: false })?.isDirectory())
+    throw refused(`${where}: the folder it ran in, ${c.cwd}, is gone`);
+  const id = req.id ?? freeId(d, req.persona);
+  if (readRecord(d.stateDir(), id))
+    throw refused(`${where}: agent ${id} exists; give this one another --id`);
+  return startAgent(
+    d,
+    { workspace: req.workspace, persona: req.persona, runtime, id },
+    { bringIn: { token: c.id, cwd: c.cwd } },
+  );
+}
+
 // ── stop, resume ────────────────────────────────────────────────────────────
 
 /** The code of a refusal naming another workspace's agent. */

package/src/ui/cli/agents-command.ts

@@ -28,6 +28,13 @@
  *           same conversation id (there is nothing to continue).
  *           --all-interrupted (AG-14.3): every agent interrupted when Den or
  *           the machine restarted that can resume.
+ *   import  (AG-17.1) bring in a conversation started outside Den: with
+ *           no --session, the runtime's own conversations in the
+ *           workspace's folder (newest first); with --session <id> and
+ *           --persona <p>, the runtime's resume of it (den-claude:
+ *           --resume <id>) in the folder it ran in, as a new agent under
+ *           Den's token, hooks and guards. Refused while it is still open
+ *           in another terminal (written in the last minute).
  *   rm      (AG-14.1b) forgets a stopped, interrupted or exited agent (never
  *           a running one); --stopped forgets every one of -w <ws> (or of
  *           every workspace). The runtime's own history stays.
@@ -69,7 +76,9 @@ import {
 } from "../../shared/agents/records.js";
 import {
   AgentError,
+  importAgent,
   listAgents,
+  listConversations,
   listPersonas as personaList,
   listRuntimes,
   loadAgentWorkspaces,
@@ -107,7 +116,7 @@ export {
 
 export const AGENTS_HELP = {
   usage:
-    "agents <list|start|stop|resume|relaunch|rm|personas|doctor|handback-check|handoff-check> ...",
+    "agents <list|start|stop|resume|relaunch|import|rm|personas|doctor|handback-check|handoff-check> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -132,6 +141,12 @@ export const AGENTS_HELP = {
     "    compactions (default 3) or its pull request merged, and its handoff.md",
     "    passes the check, a fresh conversation (same persona, workspace, folder,",
     "    grants) whose first prompt is the handoff",
+    "{cli} agents import -w <ws> [--runtime <r>] [--json]",
+    "{cli} agents import -w <ws> --session <id> --persona <p> [--runtime <r>] [--id <id>]",
+    "    bring in a conversation started outside Den: the first lists the runtime's",
+    "    own (default den-claude) in the workspace's folder; the second continues",
+    "    one as a Den agent (its resume, in the folder it ran in). Refused while it",
+    "    is still open in another terminal: close it there first",
     "{cli} agents rm <id> [-w <ws>]",
     "{cli} agents rm --stopped [-w <ws>]",
     "    forget a stopped, interrupted or exited agent (never a running one);",
@@ -279,6 +294,72 @@ async function start(args: string[], d: AgentsResolved): Promise<number> {
   );
 }
 
+/** `agents import` (AG-17.1): list, or bring one in. */
+async function bringIn(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents import";
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--runtime": true,
+    "--session": true,
+    "--persona": true,
+    "--id": true,
+    "--json": false,
+  });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
+  const runtime = str(p, "--runtime");
+  const session = str(p, "--session");
+  if (!session) {
+    if (str(p, "--persona") || str(p, "--id"))
+      throw new UsageError(`${where}: --persona and --id need --session <id>`);
+    const { runtimes, conversations } = listConversations(d, ws, runtime);
+    if (p.flags["--json"]) {
+      d.out(
+        JSON.stringify({ workspace: ws, runtimes, conversations }, null, 2),
+      );
+      return 0;
+    }
+    for (const r of runtimes)
+      if (!r.bringIn && (!runtime || runtime === r.id)) d.err(`${r.why}`);
+    if (!conversations.length) {
+      d.out(`no conversations to bring in for workspace ${ws}`);
+      return 0;
+    }
+    d.out(
+      columns([
+        ["ID", "RUNTIME", "LAST", "TITLE", "FOLDER", "NOTE"],
+        ...conversations.map((c) => [
+          c.id,
+          c.runtime,
+          c.lastAt.slice(0, 16).replace("T", " "),
+          c.title ?? "(untitled)",
+          c.cwd,
+          c.agent ? `agent ${c.agent}` : c.open ? "open elsewhere" : "",
+        ]),
+      ]).join("\n"),
+    );
+    d.out(
+      `bring one in: ${d.cli} agents import -w ${ws} --session <id> --persona <p>`,
+    );
+    return 0;
+  }
+  const persona = str(p, "--persona");
+  if (!persona) throw new UsageError(`${where} needs --persona <p>`);
+  const s = await importAgent(d, {
+    workspace: ws,
+    session,
+    persona,
+    runtime,
+    id: str(p, "--id"),
+  });
+  return report(
+    d,
+    s,
+    `brought in ${session} as agent ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
+}
+
 /** `<id> [-w <ws>]`. */
 function idAndWorkspace(
   where: string,
@@ -616,6 +697,9 @@ export async function cmdAgents(
         case "relaunch":
           await loadAgentWorkspaces(deps);
           return await relaunch(rest, d);
+        case "import":
+          await loadAgentWorkspaces(deps);
+          return await bringIn(rest, d);
         case "rm":
           await loadAgentWorkspaces(deps);
           return await rm(rest, d);

package/src/ui/mcp/api.ts

@@ -140,12 +140,23 @@ const ACTION_ROUTES: Record<string, string> = {
   "/api/workspace/sync": "POST",
 };
 
-/** Action routes with a parameter: an agent's resume (MCP agent_resume). */
+/**
+ * Action routes with a parameter: an agent's resume (MCP agent_resume),
+ * and Bring in's list and import (MCP agent_import, AG-17.1).
+ */
 const ACTION_ROUTE_PATTERNS: { re: RegExp; method: string }[] = [
   {
     re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/agents\/[A-Za-z0-9._-]{1,64}\/resume$/,
     method: "POST",
   },
+  {
+    re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/conversations$/,
+    method: "GET",
+  },
+  {
+    re: /^\/api\/workspaces\/[A-Za-z0-9._-]{1,64}\/conversations\/[A-Za-z0-9][A-Za-z0-9_-]{0,127}\/import$/,
+    method: "POST",
+  },
 ];
 
 /**

package/src/ui/mcp/tools.ts

@@ -776,6 +776,63 @@ const agentResumeTool: DenTool = {
   },
 };
 
+/** A runtime's conversation id (Claude Code: a uuid). */
+const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+/**
+ * MCP agent_import (AG-17.1): bring in a conversation started outside Den
+ * as an agent of this workspace (or a granted one). No session: the list.
+ * Opt-in through mcp.actions; the web server checks the scope again.
+ */
+const agentImportTool: DenTool = {
+  name: "agent_import",
+  title: "Bring in a conversation",
+  description:
+    "Bring in a conversation started outside Den (in the workspace's folder) as a Den agent: its runtime's own resume, in the folder it ran in, under Den's token, hooks and guards. Without session: lists the conversations there are (id, title, lastAt, cwd, runtime, open, agent). With session and persona: brings that one in and answers with the agent. Refused while it is still open in another terminal (written in the last minute), or when an agent already continues it.",
+  action: true,
+  shape: {
+    session: z
+      .string()
+      .optional()
+      .describe("The runtime's conversation id (omit to list them)"),
+    persona: z.string().optional().describe("The persona to run it as"),
+    runtime: z.string().optional().describe("The runtime (default den-claude)"),
+    workspace: workspaceArg,
+  },
+  async run(a, { api, scope }) {
+    let ws = str(a.workspace) ?? scope?.workspace;
+    if (!ws) {
+      const focused = (await api.get("/api/workspaces")) as {
+        focus?: unknown;
+      };
+      ws = typeof focused?.focus === "string" ? focused.focus : undefined;
+    }
+    if (!ws || !NAME_RE.test(ws))
+      throw new Refusal("agent_import: name the workspace");
+    if (scope && ws !== scope.workspace && !(scope.grants ?? []).includes(ws))
+      throw new ScopeRefusal(
+        `agent_import: workspace "${ws}" is outside this agent's scope ("${scope.workspace}")`,
+      );
+    const runtime = str(a.runtime);
+    if (runtime && !NAME_RE.test(runtime))
+      throw new Refusal("agent_import: runtime must be a runtime id");
+    const session = str(a.session);
+    const base = `/api/workspaces/${encodeURIComponent(ws)}/conversations`;
+    if (!session) return api.get(base, runtime ? { runtime } : {}, "GET");
+    if (!SESSION_RE.test(session))
+      throw new Refusal("agent_import: session must be a conversation id");
+    const persona = str(a.persona);
+    if (!persona || !NAME_RE.test(persona))
+      throw new Refusal("agent_import: name the persona to run it as");
+    return api.get(
+      `${base}/${encodeURIComponent(session)}/import`,
+      {},
+      "POST",
+      { persona, ...(runtime ? { runtime } : {}) },
+    );
+  },
+};
+
 const ACTION_TOOLS: Record<McpAction, DenTool> = {
   service_up: lifecycleTool("up"),
   service_down: lifecycleTool("down"),
@@ -865,6 +922,7 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
     },
   },
   agent_resume: agentResumeTool,
+  agent_import: agentImportTool,
 };
 
 export const READ_TOOL_NAMES: readonly string[] = READ_TOOLS.map((t) => t.name);
@@ -903,6 +961,7 @@ const WORKSPACE_TOOLS = new Set([
   "workspace_sync",
   "run_tests",
   "agent_resume",
+  "agent_import",
 ]);
 
 /**

package/src/ui/server/agent-resume-grant.ts

@@ -51,3 +51,38 @@ export function agentResumeTarget(
     return null;
   }
 }
+
+/**
+ * MCP `agent_import` (AG-17.1): bring a conversation in as an agent, and
+ * list the ones there are. Off unless `mcp.actions` lists it; only in the
+ * caller's workspace or one its grants give it. A person's otherwise.
+ */
+export const AGENT_IMPORT_ACTION = "agent_import";
+
+/** GET /api/workspaces/<ws>/conversations, POST …/<id>/import. */
+export const AGENT_IMPORT_ROUTE =
+  /^\/api\/workspaces\/([^/]+)\/conversations(?:\/([^/]+)\/import)?$/;
+
+/** Why this agent may not bring in a conversation of `ws`, or null. */
+export function agentImportRefusal(
+  p: ResumingAgent,
+  ws: string,
+  actions: readonly string[],
+): string | null {
+  if (!actions.includes(AGENT_IMPORT_ACTION))
+    return `${p.actor} can't bring in conversations: the org config's mcp.actions doesn't list ${AGENT_IMPORT_ACTION}.`;
+  if (ws !== p.workspace && !p.grants.includes(ws))
+    return `${p.actor} can bring in conversations of workspace ${p.workspace} only${p.grants.length ? ` (or ${p.grants.join(", ")}, its grants)` : ""}, not ${ws}.`;
+  return null;
+}
+
+/** The import route's workspace, decoded; null when it isn't it. */
+export function agentImportTarget(pathname: string): { ws: string } | null {
+  const m = AGENT_IMPORT_ROUTE.exec(pathname);
+  if (!m) return null;
+  try {
+    return { ws: decodeURIComponent(m[1]) };
+  } catch {
+    return null;
+  }
+}