@monster-orange/den 0.3.0 → 0.4.0

package/src/ui/mcp/scope.ts

@@ -4,11 +4,18 @@
  * filters lists to it, and stamps the actor on every web API call (the
  * x-den-mcp-agent / x-den-mcp-workspace headers, see shared/agent-actor.ts).
  *
+ * `--grant <ws>` (AG-2a, AG spec §5b; repeatable) widens the scope to another
+ * workspace, and only as far as the org config's `agents.<id>.grants` says
+ * (checkGrants): an agent never grants itself one. A call that names a
+ * granted workspace is served, and reported to the audit trail with both
+ * workspaces named. Lists show the scoped workspace and its grants.
+ *
  * It binds cooperating agents only: the scope lives in this process, and the
  * web server's HTTP API does not check it yet (WS-3a).
  */
 import * as path from "path";
 import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
+import type { ResolvedAgentsConfig } from "../../shared/den-config.js";
 import type { DenApi } from "./api.js";
 import { Refusal } from "./guards.js";
 
@@ -17,6 +24,16 @@ export interface McpScope {
   workspace: string;
   /** Who acts: `agent:<id>`. */
   actor: string;
+  /**
+   * Other workspaces it may name (`--grant`, from agents.<id>.grants);
+   * absent when there are none.
+   */
+  grants?: string[];
+}
+
+/** The workspaces a scope serves: its own first, then its grants. */
+export function scopeWorkspaces(scope: McpScope): string[] {
+  return [scope.workspace, ...(scope.grants ?? [])];
 }
 
 /** A call reached outside the scoped workspace. Always reported (F2). */
@@ -35,10 +52,11 @@ export class ScopeUsageError extends Error {
   }
 }
 
-const FLAGS: Record<string, "workspace" | "actor"> = {
+const FLAGS: Record<string, "workspace" | "actor" | "grant"> = {
   "--workspace": "workspace",
   "-w": "workspace",
   "--actor": "actor",
+  "--grant": "grant",
 };
 
 /**
@@ -53,6 +71,7 @@ export function parseScopeFlags(argv: readonly string[]): {
   rest: string[];
 } {
   const got: Partial<Record<"workspace" | "actor", string>> = {};
+  const grants: string[] = [];
   const rest: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -71,12 +90,25 @@ export function parseScopeFlags(argv: readonly string[]): {
         throw new ScopeUsageError(`${name} needs a value`);
       i++;
     }
+    if (key === "grant") {
+      if (!WORKSPACE_NAME_RE.test(value))
+        throw new ScopeUsageError(
+          `--grant "${printable(value)}" is not a workspace name`,
+        );
+      if (!grants.includes(value)) grants.push(value);
+      continue;
+    }
     if (got[key] !== undefined && got[key] !== value)
       throw new ScopeUsageError(`--${key} given twice`);
     got[key] = value;
   }
-  if (got.workspace === undefined && got.actor === undefined)
+  if (got.workspace === undefined && got.actor === undefined) {
+    if (grants.length)
+      throw new ScopeUsageError(
+        "--grant needs --workspace and --actor: a grant widens a scoped server",
+      );
     return { scope: null, rest };
+  }
   if (got.workspace === undefined)
     throw new ScopeUsageError(
       "--actor needs --workspace: a scoped server serves one workspace",
@@ -95,7 +127,35 @@ export function parseScopeFlags(argv: readonly string[]): {
       `--actor "${printable(got.actor)}" is not agent:<id> ` +
         "(the id: letters, digits, dots, dashes, underscores; at most 64)",
     );
-  return { scope: { workspace: got.workspace, actor: got.actor }, rest };
+  const widened = grants.filter((g) => g !== got.workspace);
+  return {
+    scope: {
+      workspace: got.workspace,
+      actor: got.actor,
+      ...(widened.length ? { grants: widened } : {}),
+    },
+    rest,
+  };
+}
+
+/**
+ * Null when every `--grant` is one the org config gives this agent
+ * (`agents.<id>.grants`), else the refusal. A grant is config in git,
+ * reviewed like code: a flag alone never widens a scope.
+ */
+export function checkGrants(
+  scope: McpScope,
+  agents: Pick<ResolvedAgentsConfig, "agents">,
+): string | null {
+  const id = scope.actor.slice("agent:".length);
+  const allowed = agents.agents[id]?.grants ?? [];
+  for (const g of scope.grants ?? [])
+    if (!allowed.includes(g))
+      return (
+        `--grant ${g}: ${scope.actor} has no such grant in agents.${id}.grants ` +
+        "of the org config; a grant is config, never a flag alone"
+      );
+  return null;
 }
 
 /** A value echoed back in an error: one printable line, bounded. */
@@ -124,7 +184,14 @@ export function printablePath(v: string, max = 160): string {
   return `${head}…${more}${tail}`;
 }
 
-/** The refusal for a call that names `other`. */
+/** "grants: a, b" or "no grants": what else the scope reaches. */
+function grantsNote(scope: McpScope): string {
+  return scope.grants?.length
+    ? `grants: ${scope.grants.join(", ")}`
+    : "no grants";
+}
+
+/** The refusal for a call that names `other`; it names the agent's grants. */
 export function otherWorkspace(
   tool: string,
   scope: McpScope,
@@ -132,7 +199,7 @@ export function otherWorkspace(
 ): ScopeRefusal {
   return new ScopeRefusal(
     `${tool}: this MCP server is scoped to workspace "${scope.workspace}" ` +
-      `(${scope.actor}); "${printable(other)}" is another workspace, so nothing was read or run.`,
+      `(${scope.actor}; ${grantsNote(scope)}); "${printable(other)}" is another workspace, so nothing was read or run.`,
   );
 }
 
@@ -146,9 +213,20 @@ export function pinWorkspace(
   scope: McpScope,
 ): Record<string, unknown> {
   const ws = args.workspace;
-  if (ws !== undefined && ws !== null && ws !== "" && ws !== scope.workspace)
+  if (ws === undefined || ws === null || ws === "")
+    return { ...args, workspace: scope.workspace };
+  if (!scopeWorkspaces(scope).includes(String(ws)))
     throw otherWorkspace(tool, scope, String(ws));
-  return { ...args, workspace: scope.workspace };
+  return { ...args, workspace: String(ws) };
+}
+
+/** The granted workspace `args` names, or null for the scope's own. */
+export function crossedWorkspace(
+  args: Record<string, unknown>,
+  scope: McpScope,
+): string | null {
+  const ws = args.workspace;
+  return typeof ws === "string" && ws && ws !== scope.workspace ? ws : null;
 }
 
 /** What /api/workspaces answers (the fields the scope reads). */
@@ -175,13 +253,20 @@ export function filterWorkspacesBody(
 ): Record<string, unknown> {
   const b = asRecord(body) as WorkspacesBody;
   const ws = scope.workspace;
+  const served = scopeWorkspaces(scope);
   const only = (v: unknown): Record<string, unknown> => {
     const r = asRecord(v);
-    return ws in r ? { [ws]: r[ws] } : {};
+    return Object.fromEntries(
+      served.filter((n) => n in r).map((n) => [n, r[n]]),
+    );
   };
   return {
-    active: Array.isArray(b.active) ? b.active.filter((n) => n === ws) : [],
-    ...(b.focus === ws ? { focus: ws } : {}),
+    active: Array.isArray(b.active)
+      ? b.active.filter((n) => served.includes(n as string))
+      : [],
+    ...(typeof b.focus === "string" && served.includes(b.focus)
+      ? { focus: b.focus }
+      : {}),
     workspaces: only(b.workspaces),
     ...(b.resolvedDirs !== undefined
       ? { resolvedDirs: only(b.resolvedDirs) }
@@ -189,7 +274,11 @@ export function filterWorkspacesBody(
     ...(b.codeWorkspacePaths !== undefined
       ? { codeWorkspacePaths: only(b.codeWorkspacePaths) }
       : {}),
-    scope: { workspace: ws, actor: scope.actor },
+    scope: {
+      workspace: ws,
+      actor: scope.actor,
+      ...(scope.grants?.length ? { grants: scope.grants } : {}),
+    },
   };
 }
 
@@ -219,23 +308,38 @@ export async function assertScopeExists(
   return body;
 }
 
+/** Throws unless the granted workspace `ws` exists in this distribution. */
+export async function assertGrantExists(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  ws: string,
+): Promise<void> {
+  const body = await api.get("/api/workspaces");
+  if (!(ws in asRecord(asRecord(body).workspaces)))
+    throw new ScopeRefusal(
+      `${tool}: ${scope.actor} has a grant for workspace "${printable(ws)}", which does not exist in this distribution; nothing was read or run.`,
+    );
+}
+
 /**
  * Tests run against the focused workspace (the web server has no workspace
  * argument for them): a scoped server runs or lists them only when that is
- * its own.
+ * its own or a granted one. Returns the focused workspace.
  */
 export async function assertScopeFocused(
   tool: string,
   api: DenApi,
   scope: McpScope,
-): Promise<void> {
+): Promise<string> {
   const focused = focusedOf(await api.get("/api/workspaces"));
-  if (focused !== scope.workspace)
-    throw new ScopeRefusal(
-      `${tool}: tests run against the focused workspace` +
-        `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
-        `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
-    );
+  // A granted workspace that is focused is served too (and audited).
+  if (focused && scopeWorkspaces(scope).includes(focused)) return focused;
+  throw new ScopeRefusal(
+    `${tool}: tests run against the focused workspace` +
+      `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
+      `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
+  );
 }
 
 /** The fields of an /api/services entry the scope checks read. */

package/src/ui/mcp/server.ts

@@ -11,6 +11,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { agentAuditHeaders } from "../../shared/agent-actor.js";
 import {
+  readAgentsConfig,
   readMcpConfig,
   type ResolvedMcpConfig,
 } from "../../shared/den-config.js";
@@ -22,7 +23,12 @@ import { createDenApi, type DenApi } from "./api.js";
 import { ownServer } from "../cli/server-identity.js";
 import { callTool, toolsFor, type ToolContext } from "./tools.js";
 import { plural } from "../../shared/plural.js";
-import { parseScopeFlags, ScopeUsageError, type McpScope } from "./scope.js";
+import {
+  checkGrants,
+  parseScopeFlags,
+  ScopeUsageError,
+  type McpScope,
+} from "./scope.js";
 
 export interface DenMcpOptions {
   cfg: ResolvedMcpConfig;
@@ -146,7 +152,7 @@ export const MCP_USAGE = (cli: string): string =>
     `Usage: ${cli} mcp [--port <web port>]`,
     `       ${cli} mcp --list`,
     `       ${cli} mcp --call <tool> ['<json args>']`,
-    `       ${cli} mcp --workspace <ws> --actor agent:<id> [...]`,
+    `       ${cli} mcp --workspace <ws> --actor agent:<id> [--grant <ws>…] [...]`,
     "",
     `An MCP server over stdio for agents, a client of the running web server`,
     `(\`${cli} web up\`; default port: config web.port). Read tools always;`,
@@ -160,6 +166,10 @@ export const MCP_USAGE = (cli: string): string =>
     "is recorded as agent:<id>. It binds cooperating agents only: the web",
     "server's HTTP API does not check the scope yet.",
     "",
+    "--grant <ws> (repeatable) also serves another workspace, only when the org",
+    "config's agents.<id>.grants lists it; each such call is recorded with both",
+    "workspaces. `agents start` passes an agent's grants for you.",
+    "",
     `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
@@ -269,6 +279,20 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     process.exitCode = 2;
     return;
   }
+  if (scope?.grants?.length) {
+    // A grant is config: a flag alone never widens a scope.
+    let refused: string | null;
+    try {
+      refused = checkGrants(scope, readAgentsConfig());
+    } catch (e) {
+      refused = (e as Error).message;
+    }
+    if (refused) {
+      process.stderr.write(`${cli} mcp: ${refused}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   let port = parsePort(argv);
   if (port === undefined) {
     try {
@@ -315,6 +339,7 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     `${cli} mcp: ${plural(toolsFor(cfg).length, "tool")} ` +
       `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}` +
       (scope ? ` · scoped to ${scope.workspace} as ${scope.actor}` : "") +
+      (scope?.grants?.length ? ` · grants: ${scope.grants.join(", ")}` : "") +
       "\n",
   );
 }

package/src/ui/mcp/tools.ts

@@ -35,10 +35,12 @@ import {
 } from "./guards.js";
 import {
   ScopeRefusal,
+  assertGrantExists,
   assertPathInScope,
   assertScopeExists,
   assertScopeFocused,
   assertServicesInScope,
+  crossedWorkspace,
   filterWorkspacesBody,
   pinWorkspace,
   type McpScope,
@@ -303,7 +305,12 @@ const READ_TOOLS: DenTool[] = [
     "The test modules of a pillar, and which repos (branch + SHA) they come from.",
     { pillar: z.enum(PILLARS) },
     async (a, { api, scope }) => {
-      if (scope) await assertScopeFocused("tests_available", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "tests_available",
+          await assertScopeFocused("tests_available", api, scope),
+        );
       return {
         modules: await api.get("/api/modules", { pillar: String(a.pillar) }),
         sources: await api.get("/api/test-sources", {
@@ -538,7 +545,12 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
       const mode =
         pillar === "security" ? (str(a.mode) ?? "baseline") : undefined;
       assertRunTestsAllowed({ pillar, env, mode }, cfg);
-      if (scope) await assertScopeFocused("run_tests", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "run_tests",
+          await assertScopeFocused("run_tests", api, scope),
+        );
       if (pillar === "security") {
         for (const service of modules.length ? modules : [undefined]) {
           const plan = (await api.get("/api/security/plan", {
@@ -710,9 +722,36 @@ async function scopeArgs(
     await assertScopeExists(ctx.api, scope);
     verifiedScopes.add(scope);
   }
-  return "workspace" in tool.shape
-    ? pinWorkspace(tool.name, args, scope)
-    : args;
+  if (!("workspace" in tool.shape)) return args;
+  const pinned = pinWorkspace(tool.name, args, scope);
+  const crossed = crossedWorkspace(pinned, scope);
+  if (crossed) {
+    await assertGrantExists(tool.name, ctx.api, scope, crossed);
+    await reportCrossWorkspace(ctx.api, tool.name, crossed);
+  }
+  return pinned;
+}
+
+/**
+ * A call into a granted workspace (AG-2a, §5b) is recorded before it runs,
+ * with both workspaces named: the server's entry takes the scoped one from
+ * the actor's headers and the target from this report.
+ */
+async function reportCrossWorkspace(
+  api: DenApi,
+  tool: string,
+  target: string,
+): Promise<void> {
+  await api.get("/api/activity", {}, "POST", { tool, crossWorkspace: target });
+}
+
+/** Report `ws` when it is a granted workspace, not the scope's own. */
+async function crossIfGranted(
+  ctx: { api: DenApi; scope: McpScope },
+  tool: string,
+  ws: string,
+): Promise<void> {
+  if (ws !== ctx.scope.workspace) await reportCrossWorkspace(ctx.api, tool, ws);
 }
 
 export async function callTool(

package/src/ui/server/audit.ts

@@ -8,6 +8,7 @@
 import * as path from "path";
 import {
   actorLabel,
+  WORKSPACE_NAME_RE,
   type Actor,
   type AgentActor,
 } from "../../shared/agent-actor.js";
@@ -25,6 +26,11 @@ export interface AuditEntry {
   agent?: string;
   /** The workspace that scoped server is pinned to. */
   workspace?: string;
+  /**
+   * The other workspace a call reached under a grant (`agents.<id>.grants`,
+   * AG-2a); `workspace` is the agent's own.
+   */
+  targetWorkspace?: string;
   /** exec | run | sync, or the MCP tool name for a refused non-lifecycle call */
   verb: string;
   detail: string;
@@ -63,6 +69,7 @@ export function recordAction(
     outcome?: "refused";
     reason?: string;
     addresses?: string[];
+    targetWorkspace?: string;
   },
 ): AuditEntry {
   const entry: AuditEntry = {
@@ -78,6 +85,9 @@ export function recordAction(
           ...(actor.workspace ? { workspace: actor.workspace } : {}),
         }
       : {}),
+    ...(action.targetWorkspace
+      ? { targetWorkspace: action.targetWorkspace }
+      : {}),
     verb: action.verb,
     detail: action.detail,
     ...(action.outcome ? { outcome: action.outcome } : {}),
@@ -194,6 +204,31 @@ export function recordAgentRefusal(
   });
 }
 
+/**
+ * A scoped agent's call into a workspace it holds a grant for (AG-2a, AG
+ * spec §5b), reported by its MCP server before the call runs. Recorded
+ * with both workspaces: the agent's own (from its headers) and the target.
+ * Null, and nothing recorded, unless the actor is a scoped agent and the
+ * target is a well-formed workspace other than its own. `GET /api/activity
+ * ?address=workspace:<ws>` lists it under either workspace.
+ */
+export function recordCrossWorkspace(
+  actor: Actor,
+  report: { tool?: unknown; crossWorkspace?: unknown },
+): AuditEntry | null {
+  if (!actor?.agent || !actor.workspace) return null;
+  const target =
+    typeof report.crossWorkspace === "string" ? report.crossWorkspace : "";
+  if (!WORKSPACE_NAME_RE.test(target) || target === actor.workspace)
+    return null;
+  const tool = clean(report.tool, 64).replace(/[^A-Za-z0-9_]/g, "") || "tool";
+  return recordAction(actor, {
+    verb: tool,
+    detail: `in workspace ${target}, under a grant to ${actor.agent} of workspace ${actor.workspace}`,
+    targetWorkspace: target,
+  });
+}
+
 /**
  * The catalog repo a refused call's `path` is inside (manifest_validate), so
  * the refusal shows in that repo's activity: the repo whose checkout is the

package/src/ui/server/index.ts

@@ -168,6 +168,7 @@ import {
   actorSuffix,
   recordAction,
   recordAgentRefusal,
+  recordCrossWorkspace,
   repoAtPath,
   setAuditSink,
 } from "./audit.js";
@@ -1088,6 +1089,12 @@ async function handleRequest(
       }
       if (repo) report = { ...report, repo };
     }
+    // A call into a granted workspace (AG-2a): both workspaces recorded.
+    if (report.crossWorkspace !== undefined) {
+      const crossed = recordCrossWorkspace(actor, report);
+      if (!crossed) return send400(res, "not a cross-workspace report");
+      return sendJson(res, { recorded: true, ts: crossed.ts });
+    }
     const entry = recordAgentRefusal(actor, report);
     return sendJson(res, { recorded: true, ts: entry.ts });
   }

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

@@ -11,7 +11,9 @@
  *                        target discovery and the owned-host check, nothing run
  *   /api/activity        the audit trail for one service (?address=repo/svc) or
  *                        repo (?repo=): execs and syncs, yours and agents',
- *                        newest first (the graph panel's Activity tab)
+ *                        newest first (the graph panel's Activity tab);
+ *                        ?address=workspace:<ws>, an agent's cross-workspace
+ *                        calls (a grant) into or out of workspace <ws>
  *
  * The MCP server's `stacks`, `edge_status` and `run_tests` (its security
  * pre-flight) read these. Collaborators are injectable for tests.
@@ -28,6 +30,7 @@ import {
 } from "../../shared/stacks/status.js";
 import { send400, sendJson } from "./http-helpers.js";
 import { recentActions, type AuditEntry } from "./audit.js";
+import { WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
 
 export interface SecurityPlanArgs {
   env: string;
@@ -97,6 +100,17 @@ export function activityFor(
   entries: AuditEntry[],
   target: { address?: string; repo?: string },
 ): AuditEntry[] {
+  // workspace:<ws>: a cross-workspace call has no repo or service; it is
+  // listed under the workspace it reached and the agent's own.
+  const ws = workspaceAddress(target.address);
+  if (ws !== null)
+    return entries
+      .filter(
+        (e) =>
+          e.targetWorkspace !== undefined &&
+          (e.targetWorkspace === ws || e.workspace === ws),
+      )
+      .reverse();
   // A repo-level entry ("core down (local)") is an attempt on the repo
   // without naming a service, as agents usually do: it shows for the repo
   // and for each of its services.
@@ -127,6 +141,12 @@ export function activityFor(
 }
 const MODES = ["baseline", "api", "full", "all"];
 
+/** The workspace a `workspace:<ws>` address names, else null. */
+function workspaceAddress(address: string | undefined): string | null {
+  const m = /^workspace:(.*)$/.exec(address ?? "");
+  return m && WORKSPACE_NAME_RE.test(m[1]) ? m[1] : null;
+}
+
 /** Handles the routes above; false when `pathname` is not one of them. */
 export async function handleReadonlyRoutes(
   req: http.IncomingMessage,
@@ -187,7 +207,10 @@ export async function handleReadonlyRoutes(
     const address = url.searchParams.get("address") ?? undefined;
     const repo = url.searchParams.get("repo") ?? undefined;
     const name = address ?? repo;
-    if (!name || !SAFE_NAME.test(name)) {
+    if (
+      !name ||
+      (!SAFE_NAME.test(name) && workspaceAddress(address) === null)
+    ) {
       send400(res, "address or repo is required");
       return true;
     }

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

@@ -41,6 +41,7 @@ import {
   syncJetBrainsWorkspaceSymlinks,
   DEN_SERVICES_DIR,
   DEN_WORKSPACES_DIR,
+  resolveWorkspaceDir,
 } from "../../shared/environment-manager/workspaces.js";
 import {
   checkServiceHealth,
@@ -517,21 +518,8 @@ export async function handleWorkspaceRoutes(
     const wsFile = readWorkspacesFile();
     const reposRoot = getReposRoot();
     const resolvedDirs: Record<string, string> = {};
-    for (const [name, ws] of Object.entries(wsFile.workspaces)) {
-      if (ws.directory) {
-        resolvedDirs[name] = path.resolve(ROOT, ws.directory);
-      } else {
-        const gwDir = path.join(DEN_WORKSPACES_DIR, name);
-        const legacyDir = path.join(reposRoot, name);
-        if (fs.existsSync(gwDir)) {
-          resolvedDirs[name] = gwDir;
-        } else if (fs.existsSync(legacyDir)) {
-          resolvedDirs[name] = legacyDir;
-        } else {
-          resolvedDirs[name] = reposRoot;
-        }
-      }
-    }
+    for (const [name, ws] of Object.entries(wsFile.workspaces))
+      resolvedDirs[name] = resolveWorkspaceDir(name, ws, reposRoot);
     const editor = readUserConfig().editor ?? "";
     const catalog = readCatalog();
     const codeWorkspacePaths: Record<string, string> = {};