@monster-orange/den 0.4.13 → 0.4.15

package/src/ui/server/agent-routes.ts

@@ -29,6 +29,18 @@
  *                                                 instruction is typed into
  *                                                 the session once it is
  *                                                 ready, never an argument
+ *   GET  /api/workspaces/<ws>/conversations[?runtime=<r>]  Bring in
+ *                                                 (AG-17.1): each runtime's
+ *                                                 own conversations in the
+ *                                                 workspace's folder, newest
+ *                                                 first, with which runtimes
+ *                                                 can bring one in
+ *   POST /api/workspaces/<ws>/conversations/<id>/import  { persona,
+ *                                                 runtime?, id? }: the
+ *                                                 runtime's resume of it, as
+ *                                                 a Den agent; 409
+ *                                                 open_elsewhere when it was
+ *                                                 written in the last minute
  *   POST /api/workspaces/<ws>/sessions            a plain session: the login
  *                                                 shell in the workspace's
  *                                                 folder (AG-10.1)
@@ -86,12 +98,14 @@ import {
 } from "../../shared/den-config.js";
 import {
   readWorkspacesFile,
+  conversationFolders,
   resolveWorkspaceDir,
 } from "../../shared/environment-manager/workspaces.js";
 import { getStateDir } from "../../shared/paths.js";
 import { HostError } from "../../shared/sessions/client.js";
 import {
   AgentError,
+  defaultId,
   agentRecord,
   checkInstruction,
   createPersona,
@@ -114,6 +128,8 @@ import {
   resumeInterrupted,
   setRuntimePath,
   resolveAgentsDeps,
+  importAgent,
+  listConversations,
   relaunchAgent,
   resumeAgent,
   startAgent,
@@ -131,7 +147,10 @@ import {
   auditActorOf,
   principalOf,
 } from "./request-guard.js";
-import { agentResumeRefusal } from "./agent-resume-grant.js";
+import {
+  agentImportRefusal,
+  agentResumeRefusal,
+} from "./agent-resume-grant.js";
 import { readBody, sendJson } from "./http-helpers.js";
 import type { Actor } from "../../shared/agent-actor.js";
 
@@ -148,6 +167,8 @@ const AGENTS_PATH =
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
 const PERSONA_PATH = /^\/api\/personas\/([^/]+)$/;
 const PLAIN_PATH = /^\/api\/workspaces\/([^/]+)\/sessions$/;
+const CONVERSATIONS_PATH =
+  /^\/api\/workspaces\/([^/]+)\/conversations(?:\/([^/]+)\/import)?$/;
 /** A start's body: a few names, commands and a first instruction. */
 const MAX_BODY = 32 * 1024;
 /** A list of names (a page's workspaces, an Undo's agents). */
@@ -166,6 +187,17 @@ function webDeps(over: AgentsDeps = {}): AgentsResolved {
       if (!cfg) throw new AgentError(`workspace "${ws}" does not exist`);
       return resolveWorkspaceDir(ws, cfg, getReposRoot());
     },
+    // AG-17.1: its folder and each by-path repo's, outside it too. A caller
+    // that gives its own folder (a test) gives its folders too, or just it.
+    ...(over.workspaceDir
+      ? {}
+      : {
+          workspaceFolders: (ws: string) => {
+            const cfg = readWorkspacesFile().workspaces[ws];
+            if (!cfg) throw new AgentError(`workspace "${ws}" does not exist`);
+            return conversationFolders(ws, cfg, getReposRoot());
+          },
+        }),
     stdout: NO_TTY,
     out: () => undefined,
     err: () => undefined,
@@ -188,6 +220,7 @@ function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
         error,
         ...(e.code && e.code !== NOT_IN_WORKSPACE ? { code: e.code } : {}),
         ...(e.hints.length ? { hints: e.hints } : {}),
+        ...(e.running ? { running: e.running } : {}),
       },
       e.status,
     );
@@ -275,6 +308,8 @@ interface StartBody {
   permission?: string;
   allow?: unknown;
   instruction?: unknown;
+  /** AG-10.10: a display name, checked as a rename's is. */
+  name?: unknown;
 }
 
 const START_KEYS = [
@@ -286,6 +321,7 @@ const START_KEYS = [
   "permission",
   "allow",
   "instruction",
+  "name",
 ];
 
 async function startBody(req: http.IncomingMessage): Promise<StartBody> {
@@ -331,6 +367,8 @@ async function startBody(req: http.IncomingMessage): Promise<StartBody> {
   }
   if (o.allow !== undefined && o.allow !== null) out.allow = o.allow;
   if (o.instruction !== undefined) out.instruction = o.instruction;
+  if (o.name !== undefined && o.name !== null && o.name !== "")
+    out.name = o.name;
   return out as StartBody;
 }
 
@@ -349,6 +387,7 @@ export async function handleAgentRoutes(
   const rp = RUNTIME_PATH.exec(pathname);
   const pp = PERSONA_PATH.exec(pathname);
   const plain = PLAIN_PATH.exec(pathname);
+  const conv = CONVERSATIONS_PATH.exec(pathname);
   // AG-14's routes over many agents at once.
   const many =
     pathname === "/api/agents/clear-stopped" ||
@@ -361,6 +400,7 @@ export async function handleAgentRoutes(
     !rp &&
     !pp &&
     !plain &&
+    !conv &&
     !many
   )
     return false;
@@ -369,6 +409,14 @@ export async function handleAgentRoutes(
 
   if (pp) return personaRoute(req, res, safeDecode(pp[1]), d);
   if (plain) return plainSession(req, res, safeDecode(plain[1]), d);
+  if (conv)
+    return conversations(
+      req,
+      res,
+      safeDecode(conv[1]),
+      conv[2] === undefined ? undefined : safeDecode(conv[2]),
+      d,
+    );
   if (pathname === "/api/personas" && method === "POST")
     return personaRoute(req, res, null, d);
 
@@ -387,6 +435,20 @@ export async function handleAgentRoutes(
         ...(pathname === "/api/personas"
           ? { personas: listPersonas(d), ...registries(d) }
           : {}),
+        // AG-10.10: the id a new start of each persona takes here.
+        ...(pathname === "/api/personas" && ws
+          ? {
+              startsAs: Object.fromEntries(
+                listPersonas(d).flatMap((p) => {
+                  try {
+                    return [[p.id, defaultId(d.stateDir(), p.id, ws)]];
+                  } catch {
+                    return []; // no free id: the start says so
+                  }
+                }),
+              ),
+            }
+          : {}),
         runtimes,
         ...(ws ? { workspace: ws } : {}),
         // AG-0.2: the file a person edits to set a runtime's path.
@@ -509,6 +571,7 @@ export async function handleAgentRoutes(
           ? { permission: body.permission }
           : {}),
         ...(body.allow !== undefined ? { allow: body.allow } : {}),
+        ...(body.name !== undefined ? { name: body.name } : {}),
         strict: true,
       });
       const ov = s.rec.overrides?.length
@@ -600,6 +663,91 @@ export async function handleAgentRoutes(
   return true;
 }
 
+const IMPORT_KEYS = ["persona", "runtime", "id"];
+
+/**
+ * Bring in (AG-17.1): GET lists the workspace's conversations, POST
+ * …/<id>/import brings one in. A person's, or an agent's opted in through
+ * mcp.actions' agent_import inside its scope. Every import is audited.
+ */
+async function conversations(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  ws: string,
+  session: string | undefined,
+  d: AgentsResolved,
+): Promise<true> {
+  const method = req.method ?? "GET";
+  const actor = auditActorOf(req);
+  const agent = agentPrincipalOf(req);
+  const allowed = () => {
+    if (agent) {
+      const why = agentImportRefusal(agent, ws, mcpActions());
+      if (why) throw new AgentError(why, { status: 403 });
+    } else guard(actor);
+  };
+  if (session === undefined) {
+    if (method !== "GET" && method !== "HEAD")
+      return methodNotAllowed(res, "GET");
+    try {
+      allowed();
+      const runtime =
+        new URL(req.url ?? "/", "http://x").searchParams.get("runtime") ??
+        undefined;
+      const listed = listConversations(d, ws, runtime);
+      sendJson(res, { workspace: ws, folder: d.workspaceDir(ws), ...listed });
+    } catch (e) {
+      sendError(res, e, ws);
+    }
+    return true;
+  }
+  if (method !== "POST") return methodNotAllowed(res, "POST");
+  let what = `bring in ${session} in ${ws}`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "agents",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    allowed();
+    const body = await jsonBody(req);
+    for (const k of Object.keys(body))
+      if (!IMPORT_KEYS.includes(k))
+        throw new AgentError(
+          `${k}: unknown field (an import takes ${IMPORT_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" || !NAME_RE.test(v))
+        throw new AgentError(`${k} must be a name`, { usage: true });
+      return v;
+    };
+    const persona = str("persona");
+    if (!persona) throw new AgentError("persona is required", { usage: true });
+    const s = await importAgent(d, {
+      workspace: ws,
+      session,
+      persona,
+      runtime: str("runtime"),
+      id: str("id"),
+    });
+    what = `bring in ${session} as ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
+    audit(s.early ? "exited at once" : undefined);
+    sendStarted(res, s, d);
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e, ws);
+  }
+  return true;
+}
+
 /** The org config's mcp.actions; none when it can't be read. */
 function mcpActions(): readonly string[] {
   try {

package/src/ui/server/approval-routes.ts

@@ -0,0 +1,390 @@
+/**
+ * ON-3's held writes (0.4.15; ON-SPEC ON-3 and the 2026-11-07 decisions):
+ * an agent's change waits for the person, and runs only on their Allow.
+ *
+ *   POST /api/approvals               { action, args, note? }: hold one
+ *                                     (anyone who may reach the server; an
+ *                                     agent's own MCP tools call it)
+ *   GET  /api/approvals               what waits, for the person's dialog
+ *                                     (never an agent's token)
+ *   GET  /api/approvals/<id>          one request: the asker's own, or the
+ *                                     person's
+ *   POST /api/approvals/<id>/decide   { decision: allow | deny }: the
+ *                                     person's signed-in browser only
+ *                                     (approvals.ts approverAllowed)
+ *
+ * The dialog's words are Den's: each action's check() turns the args into
+ * a line, its parts and the Review lines, and refuses bad args before
+ * anything waits. The agent's note is only ever shown quoted. Allow runs
+ * the action from the args stored when it was asked, after checking them
+ * again (the world may have changed while it waited). Every ask and every
+ * decision is in the activity trail.
+ */
+import type * as http from "http";
+import { agentTokenLive } from "../../shared/actor-token.js";
+import {
+  APPROVAL_TICKET_HEADER,
+  ApprovalQueue,
+  approverAllowed,
+  newApprovalTicket,
+  type Approval,
+  type Decision,
+} from "./approvals.js";
+import { recordAction } from "./audit.js";
+import { readBody, sendJson } from "./http-helpers.js";
+import {
+  agentPrincipalOf,
+  auditActorOf,
+  principalOf,
+  type GuardResult,
+} from "./request-guard.js";
+
+export type HeldCheck =
+  | {
+      ok: true;
+      /** The args as they will run (normalized). */
+      args: Record<string, unknown>;
+      /** One plain line: what it will do ("create the workspace \"web\""). */
+      summary: string;
+      /** The line's parts, for a page to word it in its own language. */
+      params: Record<string, string>;
+      /** Review: what it will do, line by line. */
+      details: string[];
+    }
+  | { ok: false; error: string };
+
+export interface HeldAction {
+  check(args: Record<string, unknown>): Promise<HeldCheck> | HeldCheck;
+  /** Runs it from checked args; answers like the CLI's --json ({ ok, … }). */
+  run(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export type HeldActions = Readonly<Record<string, HeldAction>>;
+
+/** The queue, its run being the action's, with the args checked again. */
+export function createApprovalQueue(
+  actions: HeldActions,
+  stateDir: () => string,
+  o: { ttlMs?: number; now?: () => number } = {},
+): ApprovalQueue {
+  return new ApprovalQueue({
+    ...o,
+    // An agent with no live token (stopped, `web logout --all`) is gone.
+    actorLive: (actor) =>
+      !actor.startsWith("agent:") ||
+      agentTokenLive(stateDir(), actor.slice("agent:".length)),
+    run: async (action, args) => {
+      const a = actions[action];
+      if (!a) return { ok: false, error: `no action ${action}` };
+      const again = await a.check({ ...args });
+      if (!again.ok) return { ok: false, error: again.error };
+      return a.run(again.args);
+    },
+  });
+}
+
+const ONE_PATH = /^\/api\/approvals\/([A-Za-z0-9_-]{16})$/;
+const DECIDE_PATH = /^\/api\/approvals\/([A-Za-z0-9_-]{16})\/decide$/;
+
+/** Whether `pathname` is one of the routes above. */
+export function isApprovalPath(pathname: string): boolean {
+  return (
+    pathname === "/api/approvals" ||
+    ONE_PATH.test(pathname) ||
+    DECIDE_PATH.test(pathname)
+  );
+}
+
+/** Who asked: the credential's actor, else this machine's anonymous caller. */
+function askerOf(req: http.IncomingMessage): string {
+  return principalOf(req) ?? "loopback";
+}
+
+/** What a page or the asking agent sees of one request. */
+export function approvalView(a: Approval): Record<string, unknown> {
+  return {
+    id: a.id,
+    action: a.action,
+    ...(a.agent ? { agent: a.agent } : {}),
+    summary: a.summary,
+    ...(a.params ? { params: a.params } : {}),
+    ...(a.details ? { details: a.details } : {}),
+    ...(a.note ? { note: a.note } : {}),
+    state: a.state,
+    requestedAt: new Date(a.requestedAt).toISOString(),
+    expiresAt: new Date(a.expiresAt).toISOString(),
+    ...(a.decidedAt ? { decidedAt: new Date(a.decidedAt).toISOString() } : {}),
+    ...(a.result !== undefined ? { result: a.result } : {}),
+    ...(a.endedBecause ? { endedBecause: a.endedBecause } : {}),
+  };
+}
+
+async function jsonBody(
+  req: http.IncomingMessage,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const raw = await readBody(req);
+    if (raw.length > 32 * 1024) return null;
+    const v: unknown = JSON.parse(raw || "{}");
+    return v && typeof v === "object" && !Array.isArray(v)
+      ? (v as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+const refuse = (
+  res: http.ServerResponse,
+  status: number,
+  code: string,
+  error: string,
+): void => sendJson(res, { ok: false, code, error }, status);
+
+/** Handles the routes above; false when `pathname` is not one of them. */
+export async function handleApprovalRoutes(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  guard: Extract<GuardResult, { ok: true }>,
+  deps: {
+    queue: ApprovalQueue;
+    actions: HeldActions;
+    /** `mcp.approvals` (default on); off, nothing new is held. */
+    enabled?: () => boolean;
+  },
+): Promise<boolean> {
+  if (!isApprovalPath(pathname)) return false;
+  const method = (req.method ?? "GET").toUpperCase();
+  res.setHeader("Cache-Control", "no-store");
+  const agent = agentPrincipalOf(req);
+
+  if (pathname === "/api/approvals" && method === "POST") {
+    let on: boolean;
+    try {
+      on = deps.enabled ? deps.enabled() : true;
+    } catch {
+      on = false;
+    }
+    if (!on) {
+      refuse(
+        res,
+        403,
+        "approvals_off",
+        "This distribution turned the held writes off (mcp.approvals: false).",
+      );
+      return true;
+    }
+    const body = await jsonBody(req);
+    if (!body) {
+      refuse(
+        res,
+        400,
+        "bad_body",
+        "The body must be JSON: { action, args, note? }.",
+      );
+      return true;
+    }
+    const extra = Object.keys(body).filter(
+      (k) => k !== "action" && k !== "args" && k !== "note",
+    );
+    if (extra.length) {
+      refuse(res, 400, "unknown_field", `Unknown field: ${extra.join(", ")}.`);
+      return true;
+    }
+    const action = typeof body.action === "string" ? body.action : "";
+    const held = Object.hasOwn(deps.actions, action)
+      ? deps.actions[action]
+      : undefined;
+    if (!held) {
+      refuse(
+        res,
+        400,
+        "unknown_action",
+        `Den holds ${Object.keys(deps.actions).join(", ")} for the person; not "${action}".`,
+      );
+      return true;
+    }
+    const args =
+      body.args && typeof body.args === "object" && !Array.isArray(body.args)
+        ? (body.args as Record<string, unknown>)
+        : {};
+    const checked = await held.check(args);
+    if (!checked.ok) {
+      recordAction(
+        auditActorOf(req),
+        {
+          verb: "approval-ask",
+          detail: action,
+          outcome: "refused",
+          reason: checked.error,
+        },
+        principalOf(req),
+      );
+      refuse(res, 400, "invalid_args", checked.error);
+      return true;
+    }
+    // An asker with no agent token proves it is the asker with a ticket.
+    const ticket = agent ? null : newApprovalTicket();
+    let a: Approval;
+    try {
+      a = deps.queue.request({
+        ...(ticket ? { ticketHash: ticket.hash } : {}),
+        actor: askerOf(req),
+        ...(agent ? { agent: agent.actor.slice("agent:".length) } : {}),
+        action,
+        args: checked.args,
+        summary: checked.summary,
+        params: checked.params,
+        details: checked.details,
+        note: typeof body.note === "string" ? body.note : undefined,
+      });
+    } catch (e) {
+      refuse(res, 429, "too_many_waiting", (e as Error).message);
+      return true;
+    }
+    recordAction(
+      auditActorOf(req),
+      { verb: "approval-ask", detail: `${action}: ${a.summary} [${a.id}]` },
+      principalOf(req),
+    );
+    sendJson(
+      res,
+      {
+        ok: true,
+        ...approvalView(a),
+        ...(ticket ? { ticket: ticket.ticket } : {}),
+      },
+      202,
+    );
+    return true;
+  }
+
+  if (
+    pathname === "/api/approvals" &&
+    (method === "GET" || method === "HEAD")
+  ) {
+    // An agent: its own requests and their outcomes, never another's.
+    if (agent) {
+      sendJson(res, {
+        ok: true,
+        mine: deps.queue.ofActor(agent.actor).map(approvalView),
+      });
+      return true;
+    }
+    // `?count=1`: how many wait, and nothing else, for a page that holds no
+    // approval key (it says "sign in to see it" without a refusal a poll
+    // would log every 3 s).
+    if (new URL(req.url ?? "/", "http://x").searchParams.get("count") === "1") {
+      sendJson(res, { ok: true, waiting: deps.queue.pending().length });
+      return true;
+    }
+    const who = approverAllowed(req, guard, "read");
+    if (!who.ok) {
+      // How many wait, so a signed-out page can say "sign in to see it";
+      // never what they are.
+      sendJson(
+        res,
+        {
+          ok: false,
+          code: who.code,
+          error:
+            "What waits for the person is theirs to see: a signed-in browser holding its approval key.",
+          waiting: deps.queue.pending().length,
+        },
+        403,
+      );
+      return true;
+    }
+    sendJson(res, {
+      ok: true,
+      pending: deps.queue.pending().map(approvalView),
+    });
+    return true;
+  }
+
+  const one = ONE_PATH.exec(pathname);
+  if (one && (method === "GET" || method === "HEAD")) {
+    const a = deps.queue.get(one[1]);
+    // An agent sees its own requests only; an anonymous asker the one it
+    // holds the ticket for; the person any. Anything else is "no such request".
+    const ticket = req.headers[APPROVAL_TICKET_HEADER];
+    const mayRead =
+      !!a &&
+      (agent
+        ? a.actor === agent.actor
+        : deps.queue.ticketMatches(
+            a.id,
+            typeof ticket === "string" ? ticket : undefined,
+          ) || approverAllowed(req, guard, "read").ok);
+    if (!a || !mayRead) {
+      refuse(
+        res,
+        404,
+        "not_found",
+        "No such request (it may have ended at a restart).",
+      );
+      return true;
+    }
+    sendJson(res, { ok: true, ...approvalView(a) });
+    return true;
+  }
+
+  const dec = DECIDE_PATH.exec(pathname);
+  if (dec && method === "POST") {
+    const who = approverAllowed(req, guard);
+    if (!who.ok) {
+      recordAction(
+        auditActorOf(req),
+        {
+          verb: "approval-decide",
+          detail: dec[1],
+          outcome: "refused",
+          reason: who.code,
+        },
+        principalOf(req),
+      );
+      refuse(res, 403, who.code, who.error);
+      return true;
+    }
+    const body = await jsonBody(req);
+    const decision = body?.decision;
+    if (decision !== "allow" && decision !== "deny") {
+      refuse(res, 400, "bad_decision", 'decision is "allow" or "deny".');
+      return true;
+    }
+    const r = await deps.queue.decide(
+      dec[1],
+      decision as Decision,
+      who.session,
+    );
+    recordAction(
+      auditActorOf(req),
+      r.ok
+        ? {
+            verb: "approval-decide",
+            detail: `${decision} ${r.approval.action}: ${r.approval.summary} [${dec[1]}]`,
+          }
+        : {
+            verb: "approval-decide",
+            detail: `${decision} [${dec[1]}]`,
+            outcome: "refused",
+            reason: r.code,
+          },
+      principalOf(req),
+    );
+    if (r.ok) sendJson(res, { ok: true, ...approvalView(r.approval) });
+    else
+      refuse(
+        res,
+        r.code === "not_found" ? 404 : r.code === "expired" ? 410 : 409,
+        r.code,
+        r.error,
+      );
+    return true;
+  }
+
+  res.writeHead(405, { Allow: "GET, POST" });
+  res.end();
+  return true;
+}