@monster-orange/den 0.2.7 → 0.2.8

package/src/ui/cli/org-command.ts

@@ -9,6 +9,9 @@
 import chalk from "chalk";
 import { product } from "../../shared/product.js";
 import { listOrgs } from "../../shared/manifest/service-links.js";
+import { githubOwnersOf } from "../../shared/org-sources.js";
+import { readDenConfig } from "../../shared/den-config.js";
+import { isConfigError } from "../../shared/config-error.js";
 import {
   defaultOrg,
   githubOrgFor,
@@ -107,10 +110,17 @@ export function registerOrg(
   ctx?: OrgContext,
 ): string | undefined {
   let org = orgArg?.trim();
-  if (!org) {
+  if (org) {
+    // ORG-1d: an org id names its first GitHub source's owner; an org with
+    // no GitHub source has nothing to list.
+    org = githubOwnersOf(org, (ctx?.config ?? readDenConfig()).orgs)[0];
+    if (!org) return undefined;
+  } else {
     try {
       org = githubOrgFor(workspace, ctx);
-    } catch {
+    } catch (e) {
+      // No org is "nothing to register"; a config that fails validation is not.
+      if (isConfigError(e)) throw e;
       return undefined;
     }
   }

package/src/ui/cli/up-args.ts

@@ -0,0 +1,15 @@
+/**
+ * `up -w <ws>` with no repo, no `-a` and no service repo under the cwd
+ * (0.2.8-dev.1). `-w` only picks the workspace; it does not say what in it
+ * to start, so the plan used to come back "No services specified and no
+ * invocation target resolvable". It is a usage error naming the two forms
+ * that do: a repo, or `-a` for the whole workspace.
+ */
+export function upNeedsTarget(cli: string, ws: string, plan: boolean): string {
+  const name = /^[A-Za-z0-9._-]{1,64}$/.test(ws) ? ws : "<workspace>";
+  const p = plan ? " --plan" : "";
+  return (
+    `up -w ${name} needs what to start: \`${cli} up -a${p} -w ${name}\` ` +
+    `for the whole workspace, or \`${cli} up <repo>${p} -w ${name}\` for one repo and its dependencies.`
+  );
+}

package/src/ui/mcp/scope.ts

@@ -0,0 +1,277 @@
+/**
+ * A scoped MCP server (AG-2a-core): `<cli> mcp --workspace <ws> --actor
+ * agent:<id>`. It pins one workspace, refuses any call that names another,
+ * 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).
+ *
+ * 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 { DenApi } from "./api.js";
+import { Refusal } from "./guards.js";
+
+export interface McpScope {
+  /** The one workspace this server serves. */
+  workspace: string;
+  /** Who acts: `agent:<id>`. */
+  actor: string;
+}
+
+/** A call reached outside the scoped workspace. Always reported (F2). */
+export class ScopeRefusal extends Refusal {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScopeRefusal";
+  }
+}
+
+/** `--workspace` / `--actor` were given wrongly: a usage error (exit 2). */
+export class ScopeUsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScopeUsageError";
+  }
+}
+
+const FLAGS: Record<string, "workspace" | "actor"> = {
+  "--workspace": "workspace",
+  "-w": "workspace",
+  "--actor": "actor",
+};
+
+/**
+ * Take `--workspace <ws>` (or `-w`) and `--actor agent:<id>` out of `argv`,
+ * also in the `--flag=value` form. Both or neither: a scope without an actor
+ * would act unattributed, an actor without a scope would look bound when it
+ * is not. Returns the scope (null when neither is given) and the rest of
+ * argv, unchanged otherwise.
+ */
+export function parseScopeFlags(argv: readonly string[]): {
+  scope: McpScope | null;
+  rest: string[];
+} {
+  const got: Partial<Record<"workspace" | "actor", string>> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.indexOf("=");
+    const name = a.startsWith("-") && eq !== -1 ? a.slice(0, eq) : a;
+    const key = FLAGS[name];
+    if (!key) {
+      rest.push(a);
+      continue;
+    }
+    let value: string | undefined;
+    if (name !== a) value = a.slice(eq + 1);
+    else {
+      value = argv[i + 1];
+      if (value === undefined || value.startsWith("-"))
+        throw new ScopeUsageError(`${name} needs a value`);
+      i++;
+    }
+    if (got[key] !== undefined && got[key] !== value)
+      throw new ScopeUsageError(`--${key} given twice`);
+    got[key] = value;
+  }
+  if (got.workspace === undefined && got.actor === undefined)
+    return { scope: null, rest };
+  if (got.workspace === undefined)
+    throw new ScopeUsageError(
+      "--actor needs --workspace: a scoped server serves one workspace",
+    );
+  if (got.actor === undefined)
+    throw new ScopeUsageError(
+      "--workspace needs --actor agent:<id>: a scoped server says who acts",
+    );
+  if (!WORKSPACE_NAME_RE.test(got.workspace))
+    throw new ScopeUsageError(
+      `--workspace "${printable(got.workspace)}" is not a workspace name ` +
+        "(letters, digits, dots, dashes, underscores; at most 64)",
+    );
+  if (!AGENT_ACTOR_RE.test(got.actor))
+    throw new ScopeUsageError(
+      `--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 };
+}
+
+/** A value echoed back in an error: one printable line, bounded. */
+function printable(v: string): string {
+  return v.replace(/[^\x20-\x7e]/g, "?").slice(0, 80);
+}
+
+/** The refusal for a call that names `other`. */
+export function otherWorkspace(
+  tool: string,
+  scope: McpScope,
+  other: string,
+): 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.`,
+  );
+}
+
+/**
+ * A tool's arguments with the workspace pinned: absent, it becomes the
+ * scoped one; another one is refused before anything is asked of the API.
+ */
+export function pinWorkspace(
+  tool: string,
+  args: Record<string, unknown>,
+  scope: McpScope,
+): Record<string, unknown> {
+  const ws = args.workspace;
+  if (ws !== undefined && ws !== null && ws !== "" && ws !== scope.workspace)
+    throw otherWorkspace(tool, scope, String(ws));
+  return { ...args, workspace: scope.workspace };
+}
+
+/** What /api/workspaces answers (the fields the scope reads). */
+interface WorkspacesBody {
+  active?: unknown;
+  focus?: unknown;
+  workspaces?: unknown;
+  [k: string]: unknown;
+}
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+  v && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : {};
+
+/**
+ * /api/workspaces narrowed to the scoped workspace: only its entry, its
+ * resolved directory and code-workspace path, `active` holding it or empty,
+ * and `focus` only when it is the focus. Everything else is left out.
+ */
+export function filterWorkspacesBody(
+  body: unknown,
+  scope: McpScope,
+): Record<string, unknown> {
+  const b = asRecord(body) as WorkspacesBody;
+  const ws = scope.workspace;
+  const only = (v: unknown): Record<string, unknown> => {
+    const r = asRecord(v);
+    return ws in r ? { [ws]: r[ws] } : {};
+  };
+  return {
+    active: Array.isArray(b.active) ? b.active.filter((n) => n === ws) : [],
+    ...(b.focus === ws ? { focus: ws } : {}),
+    workspaces: only(b.workspaces),
+    ...(b.resolvedDirs !== undefined
+      ? { resolvedDirs: only(b.resolvedDirs) }
+      : {}),
+    ...(b.codeWorkspacePaths !== undefined
+      ? { codeWorkspacePaths: only(b.codeWorkspacePaths) }
+      : {}),
+    scope: { workspace: ws, actor: scope.actor },
+  };
+}
+
+/** The workspace /api/workspaces says is focused (focus, else active[0]). */
+function focusedOf(body: unknown): string | null {
+  const b = asRecord(body) as WorkspacesBody;
+  if (typeof b.focus === "string" && b.focus) return b.focus;
+  if (Array.isArray(b.active) && typeof b.active[0] === "string")
+    return b.active[0];
+  return null;
+}
+
+/**
+ * Throws unless the scoped workspace exists in this distribution. A missing
+ * one must not fall through to the web server's "no workspace" defaults,
+ * which list services outside any workspace.
+ */
+export async function assertScopeExists(
+  api: DenApi,
+  scope: McpScope,
+): Promise<unknown> {
+  const body = await api.get("/api/workspaces");
+  if (!(scope.workspace in asRecord(asRecord(body).workspaces)))
+    throw new ScopeRefusal(
+      `this MCP server is scoped to workspace "${scope.workspace}", which does not exist in this distribution.`,
+    );
+  return body;
+}
+
+/**
+ * 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.
+ */
+export async function assertScopeFocused(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+): Promise<void> {
+  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.`,
+    );
+}
+
+/** The fields of an /api/services entry the scope checks read. */
+interface ScopedEntry {
+  repo?: unknown;
+  service?: unknown;
+  repoPath?: unknown;
+}
+
+async function scopedEntries(
+  api: DenApi,
+  scope: McpScope,
+): Promise<ScopedEntry[]> {
+  const list = await api.get("/api/services", {
+    env: "local",
+    workspace: scope.workspace,
+  });
+  return Array.isArray(list) ? (list as ScopedEntry[]) : [];
+}
+
+/** Every `repo/service` must be one of the scoped workspace's services. */
+export async function assertServicesInScope(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  targets: readonly { repo: string; service: string }[],
+): Promise<void> {
+  const entries = await scopedEntries(api, scope);
+  const have = new Set(entries.map((e) => `${e.repo}/${e.service}`));
+  const outside = targets
+    .map((t) => `${t.repo}/${t.service}`)
+    .filter((t) => !have.has(t));
+  if (outside.length)
+    throw new ScopeRefusal(
+      `${tool}: ${outside.map(printable).join(", ")} ${outside.length === 1 ? "is" : "are"} not a service ` +
+        `of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+    );
+}
+
+/** A manifest path must be absolute and inside one of the workspace's repos. */
+export async function assertPathInScope(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  p: string,
+): Promise<void> {
+  if (!path.isAbsolute(p))
+    throw new ScopeRefusal(
+      `${tool}: a scoped MCP server takes an absolute path inside workspace "${scope.workspace}"'s repos (or the manifest content).`,
+    );
+  const target = path.resolve(p);
+  const roots = (await scopedEntries(api, scope))
+    .map((e) => e.repoPath)
+    .filter((r): r is string => typeof r === "string" && r.length > 0)
+    .map((r) => path.resolve(r));
+  if (!roots.some((r) => target === r || target.startsWith(r + path.sep)))
+    throw new ScopeRefusal(
+      `${tool}: ${printable(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+    );
+}

package/src/ui/mcp/server.ts

@@ -22,6 +22,7 @@ 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";
 
 export interface DenMcpOptions {
   cfg: ResolvedMcpConfig;
@@ -33,6 +34,8 @@ export interface DenMcpOptions {
   /** For tests: an API in place of the HTTP client. */
   api?: DenApi;
   log?: (line: string) => void;
+  /** `--workspace` + `--actor`: one workspace, one agent (AG-2a-core). */
+  scope?: McpScope;
 }
 
 export function createDenMcpServer(opts: DenMcpOptions): McpServer {
@@ -48,7 +51,11 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
         `through the running ${p.title} web server (\`${opts.cli} web up\`). ` +
         (opts.cfg.actions.length
           ? `Actions enabled: ${opts.cfg.actions.join(", ")}.`
-          : "Read-only: the org has enabled no actions (mcp.actions)."),
+          : "Read-only: the org has enabled no actions (mcp.actions).") +
+        (opts.scope
+          ? ` Scoped to workspace "${opts.scope.workspace}" as ${opts.scope.actor}: ` +
+            "a call naming another workspace is refused, and lists show this one only."
+          : ""),
     },
   );
 
@@ -67,9 +74,15 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
           clientVersion: client()?.version ?? "unknown",
           mcpPid: opts.pid ?? process.pid,
           session,
+          ...scopeInfo(opts.scope),
         }),
     });
-  const ctx: ToolContext = { api, cfg: opts.cfg, cli: opts.cli };
+  const ctx: ToolContext = {
+    api,
+    cfg: opts.cfg,
+    cli: opts.cli,
+    ...(opts.scope ? { scope: opts.scope } : {}),
+  };
 
   for (const t of tools) {
     server.registerTool(
@@ -90,6 +103,9 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
           const who = client();
           log(
             `[mcp] ${t.name} ${r.isError ? "refused/failed" : "ok"} · ` +
+              (opts.scope
+                ? `${opts.scope.actor} in ${opts.scope.workspace} · `
+                : "") +
               `${who?.name ?? "unknown"} ${who?.version ?? ""} · session ${session}` +
               (r.isError ? ` · ${r.text.split("\n")[0]}` : ""),
           );
@@ -104,6 +120,14 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
   return server;
 }
 
+/** The audit fields a scope adds to every call's headers (none unscoped). */
+function scopeInfo(scope: McpScope | undefined): {
+  agent?: string;
+  workspace?: string;
+} {
+  return scope ? { agent: scope.actor, workspace: scope.workspace } : {};
+}
+
 function parsePort(argv: string[]): number | undefined {
   const i = argv.indexOf("--port");
   const raw =
@@ -122,6 +146,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> [...]`,
     "",
     `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;`,
@@ -130,6 +155,11 @@ export const MCP_USAGE = (cli: string): string =>
     "--list prints the tool names; --call runs one tool through the same guards,",
     "prints its text result and exits 1 if the tool reports an error.",
     "",
+    "--workspace + --actor (both, or neither) scope the server to one workspace:",
+    "a call naming another is refused, lists show that one only, and every call",
+    "is recorded as agent:<id>. It binds cooperating agents only: the web",
+    "server's HTTP API does not check the scope yet.",
+    "",
     `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
@@ -167,6 +197,7 @@ export interface OneShotOptions {
   cfg: ResolvedMcpConfig;
   cli: string;
   api: DenApi;
+  scope?: McpScope;
   out?: (text: string) => void;
   err?: (text: string) => void;
 }
@@ -185,7 +216,12 @@ export async function runOneShot(
     out(names.length ? `${names.join("\n")}\n` : "");
     return 0;
   }
-  const ctx: ToolContext = { api: opts.api, cfg: opts.cfg, cli: opts.cli };
+  const ctx: ToolContext = {
+    api: opts.api,
+    cfg: opts.cfg,
+    cli: opts.cli,
+    ...(opts.scope ? { scope: opts.scope } : {}),
+  };
   // The stdio server validates arguments against each tool's schema (the
   // SDK does it); a one-shot must too, and strictly: it is typed by hand, so
   // an unknown or misspelt key is an error, not silently dropped.
@@ -214,12 +250,25 @@ export async function runOneShot(
 }
 
 /** Run `<cli> mcp` until stdin closes (or one `--call` / `--list`). */
-export async function runMcp(argv: string[]): Promise<void> {
+export async function runMcp(rawArgv: string[]): Promise<void> {
   const cli = product().cli;
-  if (argv.includes("-h") || argv.includes("--help")) {
+  if (rawArgv.includes("-h") || rawArgv.includes("--help")) {
     process.stderr.write(`${MCP_USAGE(cli)}\n`);
     return;
   }
+  let scope: McpScope | null;
+  let argv: string[];
+  try {
+    ({ scope, rest: argv } = parseScopeFlags(rawArgv));
+  } catch (e) {
+    if (!(e instanceof ScopeUsageError)) throw e;
+    process.stderr.write(
+      `${cli} mcp: ${e.message}\n` +
+        `Usage: ${cli} mcp --workspace <ws> --actor agent:<id> [--port <n>] [--list | --call <tool> ['<json>']]\n`,
+    );
+    process.exitCode = 2;
+    return;
+  }
   let port = parsePort(argv);
   if (port === undefined) {
     try {
@@ -244,15 +293,28 @@ export async function runMcp(argv: string[]): Promise<void> {
           clientVersion: engineVersion() ?? "unknown",
           mcpPid: process.pid,
           session,
+          ...scopeInfo(scope ?? undefined),
         }),
     });
-    process.exitCode = await runOneShot(shot, { cfg, cli, api });
+    process.exitCode = await runOneShot(shot, {
+      cfg,
+      cli,
+      api,
+      ...(scope ? { scope } : {}),
+    });
     return;
   }
-  const server = createDenMcpServer({ cfg, baseUrl, cli });
+  const server = createDenMcpServer({
+    cfg,
+    baseUrl,
+    cli,
+    ...(scope ? { scope } : {}),
+  });
   await server.connect(new StdioServerTransport());
   process.stderr.write(
     `${cli} mcp: ${plural(toolsFor(cfg).length, "tool")} ` +
-      `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}\n`,
+      `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}` +
+      (scope ? ` · scoped to ${scope.workspace} as ${scope.actor}` : "") +
+      "\n",
   );
 }