@monster-orange/den 0.4.14 → 0.4.16

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).
@@ -928,10 +1046,253 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
 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],
     ),
@@ -954,6 +1315,8 @@ const WORKSPACE_TOOLS = new Set([
   "logs_tail",
   "tests_available",
   "manifest_validate",
+  "manifest_draft",
+  "service_try",
   "stacks",
   "service_up",
   "service_down",
@@ -1006,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-routes.ts

@@ -98,7 +98,7 @@ import {
 } from "../../shared/den-config.js";
 import {
   readWorkspacesFile,
-  repoFolders,
+  conversationFolders,
   resolveWorkspaceDir,
 } from "../../shared/environment-manager/workspaces.js";
 import { getStateDir } from "../../shared/paths.js";
@@ -119,6 +119,7 @@ import {
   updatePersona,
   listRuntimes,
   markInterrupted,
+  cancelStalePersonaChanges,
   NOT_IN_WORKSPACE,
   pruneStopped,
   removeAgent,
@@ -129,6 +130,7 @@ import {
   setRuntimePath,
   resolveAgentsDeps,
   importAgent,
+  changePersona,
   listConversations,
   relaunchAgent,
   resumeAgent,
@@ -159,10 +161,12 @@ export interface AgentRouteDeps {
   agents?: AgentsDeps;
   /** When a first instruction counts its session ready (tests: shorter). */
   instruction?: { quietMs?: number; maxMs?: number };
+  /** AG-18: how "after this turn" polls (tests: shorter). */
+  personaWait?: { pollMs?: number; maxMs?: number };
 }
 
 const AGENTS_PATH =
-  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths))?$/;
+  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths|persona))?$/;
 
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
 const PERSONA_PATH = /^\/api\/personas\/([^/]+)$/;
@@ -195,10 +199,7 @@ function webDeps(over: AgentsDeps = {}): AgentsResolved {
           workspaceFolders: (ws: string) => {
             const cfg = readWorkspacesFile().workspaces[ws];
             if (!cfg) throw new AgentError(`workspace "${ws}" does not exist`);
-            return [
-              resolveWorkspaceDir(ws, cfg, getReposRoot()),
-              ...repoFolders(cfg),
-            ];
+            return conversationFolders(ws, cfg, getReposRoot());
           },
         }),
     stdout: NO_TTY,
@@ -479,6 +480,7 @@ export async function handleAgentRoutes(
     | "remove"
     | "name"
     | "paths"
+    | "persona"
     | undefined;
 
   if (!action && method === "GET") {
@@ -553,6 +555,13 @@ export async function handleAgentRoutes(
     if (id !== undefined) agentRecord(d, id, ws);
     // AG-14.4: MCP agent_resume may resume another agent of its scope.
     const agent = agentPrincipalOf(req);
+    // AG-18: a persona is the person's choice: an agent could widen its
+    // own permissions with it. Any agent credential or claim is refused.
+    if (verb === "persona" && (agent || actor))
+      throw new AgentError(
+        "only a person can change an agent's persona (an agent can't change its own or another's)",
+        { status: 403 },
+      );
     if (verb === "resume" && agent) {
       const why = agentResumeRefusal(agent, ws, id!, mcpActions());
       if (why) throw new AgentError(why, { status: 403 });
@@ -650,6 +659,62 @@ export async function handleAgentRoutes(
         agent: rec.id,
         ...(rec.displayName ? { displayName: rec.displayName } : {}),
       });
+    } else if (verb === "persona") {
+      const body = await jsonBody(req);
+      for (const k of Object.keys(body))
+        if (!PERSONA_KEYS.includes(k))
+          throw new AgentError(
+            `${k}: unknown field (a persona change takes ${PERSONA_KEYS.join(", ")})`,
+            { usage: true },
+          );
+      const str = (k: string): string | undefined => {
+        const v = body[k];
+        if (v === undefined || v === null || v === "") return undefined;
+        if (typeof v !== "string" || v.length > 128 || /[^\x21-\x7e]/.test(v))
+          throw new AgentError(`${k} must be a short name`, { usage: true });
+        return v;
+      };
+      const persona = str("persona");
+      if (!persona)
+        throw new AgentError("persona is required", { usage: true });
+      const when = str("when");
+      if (when !== undefined && when !== "now" && when !== "after-turn")
+        throw new AgentError("when must be now or after-turn", {
+          usage: true,
+        });
+      const from = agentRecord(d, id!, ws).persona;
+      const by = principalOf(req) ?? "this machine";
+      what = `persona ${id} in ${ws}: ${from} → ${persona}, by ${by}`;
+      const change = () =>
+        changePersona(
+          d,
+          id!,
+          ws,
+          {
+            persona,
+            ...(str("model") !== undefined ? { model: str("model") } : {}),
+            ...(str("version") !== undefined
+              ? { version: str("version") }
+              : {}),
+            ...(when ? { when: when as "now" | "after-turn" } : {}),
+            by,
+          },
+          deps.personaWait ?? {},
+        );
+      if (when === "after-turn") {
+        // It may wait for a long turn: answer now, audit when it's done.
+        agentRecord(d, id!, ws);
+        void change().then(
+          (s) => audit(what, s.early ? "exited at once" : undefined),
+          (e: unknown) =>
+            audit(what, e instanceof Error ? e.message : String(e)),
+        );
+        sendJson(res, { ok: true, agent: id, pending: true, persona }, 202);
+        return true;
+      }
+      const s = await change();
+      audit(what, s.early ? "exited at once" : undefined);
+      sendStarted(res, s, d);
     } else if (verb === "remove") {
       const removed = await removeAgent(d, id!, ws);
       audit(what);
@@ -666,7 +731,9 @@ export async function handleAgentRoutes(
   return true;
 }
 
-const IMPORT_KEYS = ["persona", "runtime", "id"];
+const IMPORT_KEYS = ["persona", "runtime", "id", "model", "version"];
+/** AG-18: what a persona change takes. */
+const PERSONA_KEYS = ["persona", "model", "version", "when"];
 
 /**
  * Bring in (AG-17.1): GET lists the workspace's conversations, POST
@@ -740,6 +807,8 @@ async function conversations(
       persona,
       runtime: str("runtime"),
       id: str("id"),
+      ...(str("model") !== undefined ? { model: str("model") } : {}),
+      ...(str("version") !== undefined ? { version: str("version") } : {}),
     });
     what = `bring in ${session} as ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
     audit(s.early ? "exited at once" : undefined);
@@ -1092,6 +1161,21 @@ export function startAgentUpkeep(
 ): void {
   const d = webDeps(deps.agents);
   const restart = async () => {
+    // AG-18: a persona change waiting for a turn's end lived in memory.
+    try {
+      for (const c of cancelStalePersonaChanges(d)) {
+        const what = `persona ${c.id} in ${c.workspace}: ${c.from} → ${c.to}, by ${c.by ?? "this machine"}`;
+        recordAction(null, {
+          verb: "agents",
+          detail: what,
+          outcome: "refused",
+          reason: "persona change cancelled: Den restarted",
+        });
+        log(`Persona change cancelled (Den restarted): ${what}`);
+      }
+    } catch (e) {
+      log(`  ⚠ persona changes after the restart: ${(e as Error).message}`);
+    }
     try {
       const f = await markInterrupted(d);
       if (f.interrupted.length)