@monster-orange/den 0.4.13 → 0.4.15

package/src/ui/mcp/tools.ts

@@ -64,6 +64,15 @@ export interface ToolContext {
    * behaves as it always has.
    */
   scope?: McpScope;
+  /**
+   * How a write waits for the person's answer (ON-3, approvals): poll
+   * every `intervalMs` for up to `waitMs`. Tests pass a short one.
+   */
+  approvalWait?: {
+    intervalMs: number;
+    waitMs: number;
+    sleep?: (ms: number) => Promise<void>;
+  };
 }
 
 type Args = Record<string, unknown>;
@@ -178,6 +187,20 @@ const read = (
 ): DenTool => ({ name, title, description, action: false, shape, run });
 
 const READ_TOOLS: DenTool[] = [
+  read(
+    "approval_check",
+    "Check an approval",
+    "Where one of your write requests stands (workspace_create, repo_add, service_try): `state` pending, done (with the server's `result`), denied, or expired. `id` is the request id the write tool gave you. Reads only.",
+    { id: z.string().describe("The request id a write tool returned") },
+    async (a, { api }) => {
+      const id = str(a.id)?.trim() ?? "";
+      if (!/^[A-Za-z0-9_-]{16}$/.test(id))
+        throw new Refusal(
+          "approval_check: give the request id a write tool returned.",
+        );
+      return getApproval(api, id);
+    },
+  ),
   read(
     "status",
     "Service health",
@@ -528,6 +551,79 @@ const READ_TOOLS: DenTool[] = [
       );
     },
   ),
+  read(
+    "onboard_status",
+    "Onboarding status",
+    "What's set up and the one next step: `checks` (distribution, node, git, docker, web, workspaces, repos, service, mcp), each `ok`, `warn` or `todo` with its `detail` and, when there is one, a `fix` command or an `ask` for the person; then `next`: the step in plain words and its `command`. Reads only. Start here when setting Den up.",
+    {},
+    (_a, { api }) => api.get("/api/onboard/status"),
+  ),
+  read(
+    "repos_detect",
+    "Find repos in a folder",
+    "Scan one folder for git repos (the folder itself, or one or two levels down) and say how each runs: `manifest` (its own, a side-car, or none), `runs` (the commands Den detected) or `ask` and `choices` when there are several ways. `workspaces` suggests a grouping: the repos in one parent folder go in a workspace named after it. `path` is required: an absolute folder (or ~/…) inside the person's home, not Den's state folder. Reads only: it never writes, runs a repo's tools or follows a symlink. Skips node_modules, vendor and dot-folders; at most `max` repos (50).",
+    {
+      path: z
+        .string()
+        .describe("The folder to scan: absolute, or starting with ~/"),
+      max: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("At most this many repos (default and ceiling 50)"),
+    },
+    async (a, { api, scope }) => {
+      // Scanning folders is Den-wide, not one workspace's: the server's own
+      // (unscoped) agent does onboarding.
+      if (scope)
+        throw new ScopeRefusal(
+          `repos_detect: this MCP server is scoped to workspace "${scope.workspace}" (${scope.actor}), and scanning folders reaches outside any workspace; nothing was read. Den's own unscoped MCP server does onboarding.`,
+        );
+      const p = needPath("repos_detect", a);
+      return refusedOn400("repos_detect", () =>
+        api.get("/api/onboard/repos", {
+          path: p,
+          ...(typeof a.max === "number" ? { max: String(a.max) } : {}),
+        }),
+      );
+    },
+  ),
+  read(
+    "manifest_draft",
+    "Draft a side-car manifest",
+    "The side-car manifest `repo add` would write for one repo, checked by the same validator, with nothing written (`repo add --dry-run`): `draft` (the YAML), `validation`, `manifest.file` (where it would go, never in the repo) and `services`. When the repo can start in several ways it answers `ask` and `choices` instead: call again with `run` set to the one the person picks. A repo with its own manifest needs no draft (`manifest.source: repo`). `path`: the repo's absolute folder (or ~/…) inside the person's home.",
+    {
+      path: z.string().describe("The repo's folder: absolute, or ~/…"),
+      name: z
+        .string()
+        .optional()
+        .describe("The repo name (default: its folder)"),
+      run: z
+        .string()
+        .optional()
+        .describe("The start command, when detection asked which one"),
+      down: z.string().optional().describe("The stop command"),
+      health: z
+        .string()
+        .optional()
+        .describe("An http(s) URL for the health check"),
+    },
+    async (a, { api, scope }) => {
+      const p = needPath("manifest_draft", a);
+      if (scope) await assertPathInScope("manifest_draft", api, scope, p);
+      return refusedOn400("manifest_draft", () =>
+        api.get("/api/onboard/manifest", {
+          path: p,
+          name: str(a.name),
+          run: str(a.run),
+          down: str(a.down),
+          health: str(a.health),
+        }),
+      );
+    },
+  ),
   read(
     "edge_status",
     "Edge status",
@@ -551,6 +647,28 @@ const READ_TOOLS: DenTool[] = [
   ),
 ];
 
+/** The `path` argument, or a refusal before anything is asked. */
+function needPath(tool: string, a: Args): string {
+  const p = str(a.path)?.trim();
+  if (!p)
+    throw new Refusal(`${tool}: give a path (an absolute folder, or ~/…).`);
+  return p;
+}
+
+/** The web server's 400 (the path rule said no) as a refusal naming why. */
+async function refusedOn400(
+  tool: string,
+  call: () => Promise<unknown>,
+): Promise<unknown> {
+  try {
+    return await call();
+  } catch (e) {
+    if (e instanceof DenHttpError && e.status === 400)
+      throw new Refusal(`${tool}: ${e.body}`);
+    throw e;
+  }
+}
+
 /**
  * The /api/workspaces body a scoped answer is counted against, read at most
  * once every few seconds per scope (one tool call often makes several).
@@ -776,6 +894,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,15 +1040,259 @@ 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);
 export const ACTION_TOOL_NAMES: readonly McpAction[] = MCP_ACTIONS;
 
-/** The tools to register: every read tool, plus the actions the org named. */
+// ── Writes held for the person (ON-3, 0.4.15) ──────────────────────────────
+
+/** How long a write waits for the person by default, and how often it looks. */
+const APPROVAL_WAIT: NonNullable<ToolContext["approvalWait"]> = {
+  intervalMs: 2_000,
+  waitMs: 120_000,
+};
+
+/**
+ * The tickets this MCP server was handed for its own asks (id → ticket):
+ * with no agent token, a ticket is what lets it read its own request.
+ * Never shown to the agent. Bounded; the oldest go first.
+ */
+const TICKETS = new Map<string, string>();
+const MAX_TICKETS = 200;
+function keepTicket(id: string, ticket: unknown): void {
+  if (typeof ticket !== "string" || !ticket) return;
+  TICKETS.set(id, ticket);
+  while (TICKETS.size > MAX_TICKETS)
+    TICKETS.delete(TICKETS.keys().next().value as string);
+}
+/** GET one approval, with its ticket when this server asked for it. */
+function getApproval(api: DenApi, id: string): Promise<unknown> {
+  const t = TICKETS.get(id);
+  return api.get(
+    `/api/approvals/${id}`,
+    {},
+    "GET",
+    undefined,
+    t ? { "X-Den-Approval-Ticket": t } : undefined,
+  );
+}
+
+/**
+ * Ask the web server to hold `action` for the person (POST /api/approvals),
+ * then wait for the answer. Allowed: what the server's run said (an error
+ * when it failed). Denied, expired, the agent stopped: a refusal. Still
+ * pending: a plain answer naming approval_check.
+ */
+async function askPerson(
+  tool: string,
+  action: string,
+  args: Args,
+  note: unknown,
+  ctx: ToolContext,
+): Promise<unknown> {
+  const clean = Object.fromEntries(
+    Object.entries(args).filter(([, v]) => v !== undefined && v !== ""),
+  );
+  let asked: { id?: unknown; ticket?: unknown };
+  try {
+    asked = (await ctx.api.get("/api/approvals", {}, "POST", {
+      action,
+      args: clean,
+      ...(typeof note === "string" && note.trim() ? { note: note.trim() } : {}),
+    })) as { id?: unknown; ticket?: unknown };
+  } catch (e) {
+    if (e instanceof DenHttpError && [400, 403, 409, 429].includes(e.status))
+      throw new Refusal(`${tool}: ${e.body}`);
+    throw e;
+  }
+  const id = String(asked?.id ?? "");
+  keepTicket(id, asked?.ticket);
+  const w = ctx.approvalWait ?? APPROVAL_WAIT;
+  const sleep =
+    w.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+  const until = Date.now() + w.waitMs;
+  for (;;) {
+    const a = (await getApproval(ctx.api, id)) as {
+      state?: string;
+      result?: unknown;
+      endedBecause?: string;
+    };
+    if (a.state === "done") {
+      const result = a.result as { ok?: unknown } | undefined;
+      const out = { approved: true, id, result };
+      if (result && result.ok === false) throw new ActionFailed(out);
+      return out;
+    }
+    if (a.state === "denied")
+      throw new Refusal(
+        a.endedBecause === "actor_gone"
+          ? `${tool}: the agent that asked was stopped before the person allowed it (request ${id}); nothing ran.`
+          : `${tool}: the person denied it (request ${id}); nothing ran.`,
+      );
+    if (a.state === "expired")
+      throw new Refusal(
+        `${tool}: nobody answered in time (request ${id}); nothing ran. Ask again when the person is at Den.`,
+      );
+    if (Date.now() >= until) break;
+    await sleep(w.intervalMs);
+  }
+  return `Waiting for the person to approve in Den (request ${id}); call approval_check with this id later.`;
+}
+
+/** A required string argument, or a refusal before anything is asked. */
+function needArg(tool: string, a: Args, k: string, what: string): string {
+  const v = str(a[k])?.trim();
+  if (!v) throw new Refusal(`${tool}: give ${k} (${what}).`);
+  return v;
+}
+
+const noteArg = z
+  .string()
+  .max(500)
+  .optional()
+  .describe(
+    'One line for the person on why (shown quoted as "Agent says"; Den writes the request itself)',
+  );
+
+/** Onboarding writes are the unscoped server agent's. */
+function refuseScoped(tool: string, scope: McpScope | undefined): void {
+  if (scope)
+    throw new ScopeRefusal(
+      `${tool}: this MCP server is scoped to workspace "${scope.workspace}" (${scope.actor}), and ${tool} changes Den beyond it; nothing was asked. Den's own unscoped MCP server does onboarding.`,
+    );
+}
+
+const HELD =
+  " Nothing changes until the person allows it in Den's browser dialog: the request waits up to 10 minutes; this call waits up to 2 for the answer, then returns the request id for approval_check.";
+
+const APPROVAL_TOOLS: DenTool[] = [
+  {
+    name: "workspace_create",
+    title: "Create a workspace",
+    description: "Create an empty Den workspace named `name`." + HELD,
+    action: true,
+    shape: {
+      name: z
+        .string()
+        .describe(
+          "The workspace name (no quotes, slashes or control characters)",
+        ),
+      note: noteArg,
+    },
+    async run(a, ctx) {
+      refuseScoped("workspace_create", ctx.scope);
+      const name = needArg("workspace_create", a, "name", "the workspace name");
+      return askPerson(
+        "workspace_create",
+        "workspace_create",
+        { name },
+        a.note,
+        ctx,
+      );
+    },
+  },
+  {
+    name: "repo_add",
+    title: "Add a repo",
+    description:
+      "Add the local repo at `path` to a workspace, as `repo add` does (manifest_draft first shows what it would write)." +
+      HELD,
+    action: true,
+    shape: {
+      path: z
+        .string()
+        .describe(
+          "The repo's folder: absolute, or ~/… inside the person's home",
+        ),
+      workspace: workspaceArg,
+      name: z
+        .string()
+        .optional()
+        .describe("The repo name (default: its folder)"),
+      run: z
+        .string()
+        .optional()
+        .describe("The start command, when detection asked which"),
+      down: z.string().optional().describe("The stop command"),
+      health: z
+        .string()
+        .optional()
+        .describe("An http(s) URL for the health check"),
+      note: noteArg,
+    },
+    async run(a, ctx) {
+      refuseScoped("repo_add", ctx.scope);
+      const p = needArg("repo_add", a, "path", "the repo's folder");
+      return askPerson(
+        "repo_add",
+        "repo_add",
+        {
+          path: p,
+          workspace: str(a.workspace),
+          name: str(a.name),
+          run: str(a.run),
+          down: str(a.down),
+          health: str(a.health),
+        },
+        a.note,
+        ctx,
+      );
+    },
+  },
+  {
+    name: "service_try",
+    title: "Start one service",
+    description:
+      "Start one service locally (`up`, as the Services page does) and report how it went: the exit code and the last lines of output." +
+      HELD,
+    action: true,
+    shape: {
+      service: z.string().describe("The service: <repo> or <repo>/<service>"),
+      workspace: workspaceArg,
+      note: noteArg,
+    },
+    async run(a, ctx) {
+      const service = needArg(
+        "service_try",
+        a,
+        "service",
+        "<repo> or <repo>/<service>",
+      );
+      return askPerson(
+        "service_try",
+        "service_try",
+        { service, workspace: str(a.workspace) },
+        a.note,
+        ctx,
+      );
+    },
+  },
+];
+
+/**
+ * The held writes: registered unless `mcp.approvals: false` (the person's
+ * Allow is the gate, so they are on by default).
+ */
+export const APPROVAL_TOOL_NAMES: readonly string[] = APPROVAL_TOOLS.map(
+  (t) => t.name,
+);
+
+/** One line saying whether the held writes are on (MCP instructions, --list, doctor). */
+export function approvalsState(
+  cfg: Pick<ResolvedMcpConfig, "approvals">,
+): string {
+  return cfg.approvals
+    ? `held writes on: ${APPROVAL_TOOL_NAMES.join(", ")} run only after the person's Allow in the browser (mcp.approvals: false turns them off)`
+    : `held writes off (mcp.approvals: false): ${APPROVAL_TOOL_NAMES.join(", ")} are not registered`;
+}
+
+/** The tools to register: every read tool, the held writes (unless turned off), plus the actions the org named. */
 export function toolsFor(cfg: ResolvedMcpConfig, scope?: McpScope): DenTool[] {
   const tools = [
     ...READ_TOOLS,
+    ...(cfg.approvals ? APPROVAL_TOOLS : []),
     ...MCP_ACTIONS.filter((a) => cfg.actions.includes(a)).map(
       (a) => ACTION_TOOLS[a],
     ),
@@ -896,6 +1315,8 @@ const WORKSPACE_TOOLS = new Set([
   "logs_tail",
   "tests_available",
   "manifest_validate",
+  "manifest_draft",
+  "service_try",
   "stacks",
   "service_up",
   "service_down",
@@ -903,6 +1324,7 @@ const WORKSPACE_TOOLS = new Set([
   "workspace_sync",
   "run_tests",
   "agent_resume",
+  "agent_import",
 ]);
 
 /**
@@ -947,6 +1369,10 @@ export function pinnedTool(t: DenTool, scope: McpScope): DenTool {
  * than the web server it talks to.
  */
 export const ROUTE_SINCE: Readonly<Record<string, string>> = {
+  "/api/approvals": "0.4.15",
+  "/api/onboard/status": "0.4.15",
+  "/api/onboard/repos": "0.4.15",
+  "/api/onboard/manifest": "0.4.15",
   "/api/stacks": "0.2.0",
   "/api/edge": "0.2.0",
   "/api/security/plan": "0.2.0",

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;
+  }
+}