@monster-orange/den 0.4.12 → 0.4.14

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

@@ -12,8 +12,38 @@
  *                                                 runs its version command and
  *                                                 refuses a path that isn't
  *                                                 that runtime (AG-0.5)
+ *   GET  /api/personas/<id>                       one persona with its
+ *                                                 instructions (Details)
+ *   POST /api/personas                            New persona (AG-10.7): a
+ *                                                 local one; a person only
+ *   POST /api/personas/<id>                       Edit: a local one only
+ *                                                 (409 read_only otherwise)
+ *   DELETE /api/personas/<id>                     Delete: a local one only
  *   GET  /api/workspaces/<ws>/agents              the workspace's agents
- *   POST /api/workspaces/<ws>/agents              start { persona, runtime?, model?, id? }
+ *   POST /api/workspaces/<ws>/agents              start { persona, runtime?,
+ *                                                 model?, version?,
+ *                                                 permission?, allow?,
+ *                                                 instruction?, id? }
+ *                                                 (AG-10.1): each checked
+ *                                                 against the catalog; the
+ *                                                 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)
  *   POST /api/workspaces/<ws>/agents/<id>/stop
  *   POST /api/workspaces/<ws>/agents/<id>/resume  the same conversation (AG-14)
  *   POST /api/workspaces/<ws>/agents/<id>/fresh   a new conversation, same
@@ -68,15 +98,25 @@ import {
 } from "../../shared/den-config.js";
 import {
   readWorkspacesFile,
+  repoFolders,
   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,
+  deletePersona,
   listAgents,
   listPersonas,
+  personaDetail,
+  registries,
+  sendFirstInstruction,
+  startPlainSession,
+  updatePersona,
   listRuntimes,
   markInterrupted,
   NOT_IN_WORKSPACE,
@@ -88,6 +128,8 @@ import {
   resumeInterrupted,
   setRuntimePath,
   resolveAgentsDeps,
+  importAgent,
+  listConversations,
   relaunchAgent,
   resumeAgent,
   startAgent,
@@ -105,21 +147,30 @@ 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";
 
 export interface AgentRouteDeps {
   /** The operations' deps (tests: an in-process host, a temp state dir). */
   agents?: AgentsDeps;
+  /** When a first instruction counts its session ready (tests: shorter). */
+  instruction?: { quietMs?: number; maxMs?: number };
 }
 
 const AGENTS_PATH =
   /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths))?$/;
 
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
-/** A start's body is a few short names. */
-const MAX_BODY = 4096;
+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). */
 const MANY_BODY = 64 * 1024;
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -136,6 +187,20 @@ 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 [
+              resolveWorkspaceDir(ws, cfg, getReposRoot()),
+              ...repoFolders(cfg),
+            ];
+          },
+        }),
     stdout: NO_TTY,
     out: () => undefined,
     err: () => undefined,
@@ -158,6 +223,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,
     );
@@ -174,12 +240,12 @@ function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
   throw e;
 }
 
-function sessionNameOf(
+function sessionTitleOf(
   rec: Started["rec"],
   d: AgentsResolved,
-): { sessionName?: string } {
+): { sessionTitle?: string } {
   const n = agentSessionName(rec, d.stateDir());
-  return n ? { sessionName: n } : {};
+  return n ? { sessionTitle: n } : {};
 }
 
 /** A started or resumed agent's answer: its record, or its early exit. */
@@ -187,6 +253,7 @@ function sendStarted(
   res: http.ServerResponse,
   s: Started & { fresh?: boolean },
   d: AgentsResolved,
+  extra: Record<string, unknown> = {},
 ): void {
   if (s.early) {
     const code =
@@ -217,21 +284,50 @@ function sendStarted(
       // The host's id: the Agents tab opens its pane by it (?open=<id>).
       sessionId: s.info.ref.id,
       startedAt: s.rec.startedAt,
+      ...(s.rec.model ? { model: s.rec.model } : {}),
+      ...(s.rec.version ? { version: s.rec.version } : {}),
+      ...(s.rec.permission ? { permission: s.rec.permission } : {}),
+      ...(s.rec.overrides?.length ? { overrides: s.rec.overrides } : {}),
       ...(s.rec.displayName ? { displayName: s.rec.displayName } : {}),
-      // AG-4b: its session's name (Den's rename or the runtime's), as the
-      // lists show it (MCP agent_resume answers with this).
-      ...sessionNameOf(s.rec, d),
+      // AG-4b: the name its session shows (Den's rename or the runtime's),
+      // as the lists show it (MCP agent_resume answers with this). Its
+      // handle is `session`.
+      ...sessionTitleOf(s.rec, d),
     },
     // A resume with nothing to continue yet started fresh (same id).
     ...(s.fresh ? { fresh: true } : {}),
     ...(s.warnings.length ? { warnings: s.warnings } : {}),
+    ...extra,
   });
 }
 
-/** What a POST's body names: a few optional strings. */
-async function startBody(
-  req: http.IncomingMessage,
-): Promise<Record<string, string | undefined>> {
+/** What a start's body names: optional strings, a command list, an instruction. */
+interface StartBody {
+  persona?: string;
+  runtime?: string;
+  model?: string;
+  id?: string;
+  version?: string;
+  permission?: string;
+  allow?: unknown;
+  instruction?: unknown;
+  /** AG-10.10: a display name, checked as a rename's is. */
+  name?: unknown;
+}
+
+const START_KEYS = [
+  "persona",
+  "runtime",
+  "model",
+  "id",
+  "version",
+  "permission",
+  "allow",
+  "instruction",
+  "name",
+];
+
+async function startBody(req: http.IncomingMessage): Promise<StartBody> {
   const raw = await readBody(req).catch(() => "");
   if (raw.length > MAX_BODY)
     throw new AgentError("request too large", { status: 413, usage: true });
@@ -243,15 +339,40 @@ async function startBody(
   }
   if (!v || typeof v !== "object" || Array.isArray(v))
     throw new AgentError("the body must be a JSON object", { usage: true });
-  const out: Record<string, string | undefined> = {};
-  for (const k of ["persona", "runtime", "model", "id"]) {
-    const x = (v as Record<string, unknown>)[k];
+  const o = v as Record<string, unknown>;
+  for (const k of Object.keys(o))
+    if (!START_KEYS.includes(k))
+      throw new AgentError(
+        `${k}: unknown field (a start takes ${START_KEYS.join(", ")})`,
+        { usage: true },
+      );
+  const out: Record<string, unknown> = {};
+  for (const k of [
+    "persona",
+    "runtime",
+    "model",
+    "id",
+    "version",
+    "permission",
+  ]) {
+    const x = o[k];
     if (x === undefined || x === null || x === "") continue;
     if (typeof x !== "string")
       throw new AgentError(`${k} must be a string`, { usage: true });
+    if (x.length > 128 || /[^\x21-\x7e]/.test(x))
+      throw new AgentError(
+        `${k} must be a short name (no spaces or control characters)`,
+        {
+          usage: true,
+        },
+      );
     out[k] = x;
   }
-  return out;
+  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;
 }
 
 /**
@@ -267,6 +388,9 @@ export async function handleAgentRoutes(
 ): Promise<boolean> {
   const m = AGENTS_PATH.exec(pathname);
   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" ||
@@ -277,22 +401,57 @@ export async function handleAgentRoutes(
     pathname !== "/api/agents/runtimes" &&
     !m &&
     !rp &&
+    !pp &&
+    !plain &&
+    !conv &&
     !many
   )
     return false;
   const method = req.method ?? "GET";
   const d = webDeps(deps.agents);
 
+  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);
+
   if (rp) return runtimePath(req, res, safeDecode(rp[1]), d);
   if (many) return manyAgents(req, res, pathname, d);
   if (!m) {
     if (method !== "GET" && method !== "HEAD")
-      return methodNotAllowed(res, "GET");
+      return methodNotAllowed(
+        res,
+        pathname === "/api/personas" ? "GET, POST" : "GET",
+      );
     try {
       const ws = queryWorkspace(req, d);
       const runtimes = await listRuntimes(d, ws);
       sendJson(res, {
-        ...(pathname === "/api/personas" ? { personas: listPersonas(d) } : {}),
+        ...(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.
@@ -403,16 +562,55 @@ export async function handleAgentRoutes(
       if (!body.persona)
         throw new AgentError("persona is required", { usage: true });
       what = `start ${body.id ?? body.persona} in ${ws}`;
+      const instruction = checkInstruction(body.instruction);
       const s = await startAgent(d, {
         workspace: ws,
         persona: body.persona,
         runtime: body.runtime,
         model: body.model,
         id: body.id,
+        ...(body.version !== undefined ? { version: body.version } : {}),
+        ...(body.permission !== undefined
+          ? { permission: body.permission }
+          : {}),
+        ...(body.allow !== undefined ? { allow: body.allow } : {}),
+        ...(body.name !== undefined ? { name: body.name } : {}),
+        strict: true,
       });
-      what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
+      const ov = s.rec.overrides?.length
+        ? `; overrides ${s.rec.overrides.join(", ")}`
+        : "";
+      what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}${ov}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s, d);
+      sendStarted(res, s, d, instruction ? { instruction: "pending" } : {});
+      // AG-10.1: its first message, once it is ready: typed into its
+      // session (the host's write path), never an argument. Its text is
+      // never logged; its length is.
+      if (instruction && !s.early) {
+        const id = s.rec.id;
+        void sendFirstInstruction(
+          d,
+          s.info.ref.id,
+          s.rec.runtime,
+          instruction,
+          deps.instruction ?? {},
+        ).then((sent) =>
+          recordAction(
+            actor,
+            {
+              verb: "agents",
+              detail: `first instruction to ${id} in ${ws} (${instruction.length} characters)`,
+              ...(sent
+                ? {}
+                : {
+                    outcome: "refused" as const,
+                    reason: "its session ended or no host",
+                  }),
+            },
+            principalOf(req),
+          ),
+        );
+      }
     } else if (verb === "stop") {
       // The answer comes once the session has ended (200, stopped: true),
       // or, still running after the wait, 202 with stillStopping: true.
@@ -468,6 +666,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 {
@@ -586,6 +869,113 @@ function queryWorkspace(
   return ws;
 }
 
+/**
+ * The persona routes (AG-10.6, 10.7): GET one (anyone who may read);
+ * POST (new: `id` null; edit: a local one), DELETE (a local one): a
+ * person only. An agent's token can't make or change a persona (its
+ * permissions are the person's to set). Every change is audited, refused
+ * or done; never the instructions themselves.
+ */
+async function personaRoute(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  id: string | null,
+  d: AgentsResolved,
+): Promise<true> {
+  const method = req.method ?? "GET";
+  if (id !== null && (method === "GET" || method === "HEAD")) {
+    try {
+      sendJson(res, { persona: personaDetail(d, id) });
+    } catch (e) {
+      sendError(res, e);
+    }
+    return true;
+  }
+  if (method !== "POST" && !(method === "DELETE" && id !== null))
+    return methodNotAllowed(
+      res,
+      id === null ? "GET, POST" : "GET, POST, DELETE",
+    );
+  const actor = auditActorOf(req);
+  const verb = id === null ? "create" : method === "DELETE" ? "delete" : "edit";
+  let what = `persona ${verb}${id ? ` ${id}` : ""}`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "agents",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    if (actor && !actor.unverified)
+      throw new AgentError(
+        "an agent can't create, change or delete personas: a person sets what agents may do",
+        { status: 403 },
+      );
+    if (verb === "delete") {
+      deletePersona(d, id!);
+      audit();
+      sendJson(res, { ok: true, deleted: id });
+      return true;
+    }
+    const body = await jsonBody(req);
+    const p =
+      verb === "create" ? createPersona(d, body) : updatePersona(d, id!, body);
+    what = `persona ${verb} ${p.id}`;
+    audit();
+    sendJson(res, { ok: true, persona: p });
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e);
+  }
+  return true;
+}
+
+/**
+ * POST /api/workspaces/<ws>/sessions (AG-10.1 Plain session): a person's
+ * login shell in the workspace's folder. A person only; audited.
+ */
+async function plainSession(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  ws: string,
+  d: AgentsResolved,
+): Promise<true> {
+  if (req.method !== "POST") return methodNotAllowed(res, "POST");
+  const actor = auditActorOf(req);
+  let what = `plain session in ${ws}`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "sessions",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    if (actor && !actor.unverified)
+      throw new AgentError("an agent can't start a session from the page", {
+        status: 403,
+      });
+    const { info } = await startPlainSession(d, ws);
+    what = `plain session ${info.name} in ${ws}`;
+    audit();
+    sendJson(res, {
+      ok: true,
+      session: { id: info.ref.id, name: info.name, workspace: ws },
+    });
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e, ws);
+  }
+  return true;
+}
+
 /**
  * POST /api/agents/runtimes/<id>/path: a person only, never an agent (it
  * runs the path given). Audited, refused or done; never the path's output.

package/src/ui/server/public/agent-start.js

@@ -37,9 +37,10 @@ export function personaOptions(personas) {
     .join("");
 }
 
-/** The help line under the persona select: the picked persona's role. */
+/** The help line under the persona select: the picked persona's description. */
 export function personaHelp(personas, id) {
-  return (personas ?? []).find((p) => p.id === id)?.role ?? "";
+  const p = (personas ?? []).find((x) => x.id === id);
+  return p?.description ?? p?.role ?? "";
 }
 
 /** A runtime's name for people ("Claude Code"); its id when it has none. */