@zgeoff/atc 2.10.4 → 2.12.0

package/src/daemon/target-access.ts

@@ -0,0 +1,36 @@
+/**
+ * A target a session runs on, as the name it holds and the identity the
+ * session is bound to there.
+ */
+export interface TargetGrant {
+  readonly target: string;
+  readonly targetIdentity: string;
+}
+
+/**
+ * The targets a principal may use, each as a name and an identity: a
+ * session on a granted name whose identity differs is outside the grant.
+ */
+export class TargetAccess {
+  private readonly grants: ReadonlyMap<string, TargetGrant>;
+
+  constructor(grants: readonly TargetGrant[]) {
+    this.grants = new Map(grants.map((grant) => [buildGrantKey(grant), grant]));
+  }
+
+  canUse(grant: TargetGrant): boolean {
+    return this.grants.has(buildGrantKey(grant));
+  }
+
+  /**
+   * The grants both accesses hold, so a principal on a narrowed connection
+   * never reaches past the connection.
+   */
+  merge(other: TargetAccess): TargetAccess {
+    return new TargetAccess([...this.grants.values()].filter((grant) => other.canUse(grant)));
+  }
+}
+
+function buildGrantKey(grant: TargetGrant): string {
+  return JSON.stringify([grant.target, grant.targetIdentity]);
+}

package/src/mcp/answer-mcp-request.ts

@@ -4,6 +4,7 @@ import type { GrantScope } from '../shared/grant-scope';
 import { normalizeClientName } from '../shared/normalize-client-name';
 import { isRecord } from '../shared/report';
 import { answerRPCRequest } from './answer-rpc-request';
+import { buildPrincipalCaller } from './build-principal-caller';
 import { deriveTokenHash } from './derive-token-hash';
 import { findClientName } from './find-client-name';
 import { isSupportedProtocolVersion } from './is-supported-protocol-version';
@@ -21,7 +22,8 @@ interface MCPHTTPRequest {
  * database, so a revoked grant loses access at once, and a token bound to any
  * other resource is refused. A tool call outside the token's scopes is a 403
  * that names the missing scope. A message the client sends is always from the
- * client's own name.
+ * client's own name, and every request acts as the client's id, so the
+ * daemon limits it to the targets that principal may use.
  */
 export async function answerMCPRequest(
   ctx: HTTPServerContext,
@@ -65,7 +67,7 @@ export async function answerMCPRequest(
   }
 
   const outcome = await answerRPCRequest(message, {
-    caller: ctx.caller,
+    caller: buildPrincipalCaller(ctx.caller, access.clientID),
     build: ctx.build,
     toolContext: { callerSessionID: null, sender: { kind: 'fixed', name: access.clientName } },
     scopes: access.scopes,
@@ -95,12 +97,13 @@ export async function answerMCPRequest(
 }
 
 interface VerifiedAccess {
+  readonly clientID: string;
   readonly clientName: string;
   readonly scopes: readonly GrantScope[];
 }
 
-// An inactive, unknown, or revoked token, or one bound to another resource,
-// verifies to null. Verifying stamps when the token's grant was last used.
+// An inactive, unknown, or revoked token, one bound to another resource, or
+// one without a client id verifies to null. Verifying stamps when the token's grant was last used.
 async function verifyAccessToken(
   ctx: HTTPServerContext,
   token: string,
@@ -124,11 +127,16 @@ async function verifyAccessToken(
   const granted = typeof payload['scope'] === 'string' ? payload['scope'].split(' ') : [];
   const clientID = typeof payload['client_id'] === 'string' ? payload['client_id'] : '';
 
+  if (clientID === '') {
+    return null;
+  }
+
   await upsertGrantUse(ctx, token);
 
   const storedName = await findClientName(ctx.store.db, clientID);
 
   return {
+    clientID,
     clientName: normalizeClientName(storedName, 'remote'),
     scopes: GRANT_SCOPES.filter((scope) => granted.includes(scope)),
   };

package/src/mcp/answer-rpc-request.ts

@@ -1,7 +1,9 @@
 import { match } from 'ts-pattern';
+import { z } from 'zod';
 import { DaemonError } from '../protocol/daemon-error';
 import type { GrantScope } from '../shared/grant-scope';
 import { isRecord } from '../shared/report';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { buildToolList } from './build-tool-list';
 import { MCP_TOOLS } from './mcp-tools';
 import { pickProtocolVersion } from './pick-protocol-version';
@@ -57,10 +59,16 @@ export async function answerRPCRequest(message: unknown, deps: RPCDeps): Promise
       }),
     }))
     .with('ping', () => ({ kind: 'reply' as const, body: buildRPCResult(id, {}) }))
-    .with('tools/list', () => ({
-      kind: 'reply' as const,
-      body: buildRPCResult(id, { tools: buildToolList() }),
-    }))
+    .with('tools/list', async () => {
+      const features = await deps.caller.readFeatures();
+
+      const agents = features.has('agents.list') ? await tryReadAgents(deps) : null;
+
+      return {
+        kind: 'reply' as const,
+        body: buildRPCResult(id, { tools: buildToolList(features, agents) }),
+      };
+    })
     .with('tools/call', async () => {
       const result = await answerToolCall(deps, params);
 
@@ -93,6 +101,29 @@ function findMissingScope(
   return scopes.includes(needed) ? null : needed;
 }
 
+// The part of an agents.list answer the spawn descriptions read.
+const ROSTER_AGENT_SCHEMA = z.object({ id: z.string(), installed: z.boolean() });
+const AGENT_ROSTER_SCHEMA = z.object({ agents: z.array(ROSTER_AGENT_SCHEMA) });
+
+// The registered agents, or null when the daemon cannot answer, so the tool
+// list still builds with descriptions that name no agent. A caller without
+// the read scope gets null too, since listing agents is a read.
+async function tryReadAgents(deps: RPCDeps): Promise<RegisteredAgent[] | null> {
+  if (deps.scopes !== undefined && !deps.scopes.includes('read')) {
+    return null;
+  }
+
+  try {
+    const answer = await deps.caller.sendRequest('agents.list');
+
+    const parsed = AGENT_ROSTER_SCHEMA.safeParse(answer);
+
+    return parsed.success ? parsed.data.agents : null;
+  } catch {
+    return null;
+  }
+}
+
 async function answerToolCall(
   deps: RPCDeps,
   params: Readonly<Record<string, unknown>>,
@@ -101,9 +132,12 @@ async function answerToolCall(
   const args = isRecord(params['arguments']) ? params['arguments'] : {};
 
   try {
-    const text = await runTool(deps.caller, name, args, deps.toolContext);
+    const result = await runTool(deps.caller, name, args, deps.toolContext);
 
-    return { content: [{ type: 'text', text }] };
+    return {
+      content: [{ type: 'text', text: result.text }],
+      ...(result.structured === null ? {} : { structuredContent: result.structured }),
+    };
   } catch (error) {
     return { content: [{ type: 'text', text: formatToolError(error) }], isError: true };
   }

package/src/mcp/build-principal-caller.ts

@@ -0,0 +1,15 @@
+import type { FleetCaller } from './types';
+
+/**
+ * The caller every request of one remote MCP client rides: each request acts
+ * as the client's principal, whatever principal it asked for, and goes only
+ * to a daemon that limits a request to its principal's targets, so a daemon
+ * that would ignore the principal never answers it with the owner's reach.
+ */
+export function buildPrincipalCaller(caller: FleetCaller, principal: string): FleetCaller {
+  return {
+    sendRequest: (m, p, required = []) =>
+      caller.sendRequest(m, p, [...required, 'request.principal'], principal),
+    readFeatures: () => caller.readFeatures(),
+  };
+}

package/src/mcp/build-spawn-descriptions.ts

@@ -0,0 +1,45 @@
+/**
+ * One agent as the spawn descriptions list it: its id and whether its binary
+ * resolves on the daemon's host.
+ */
+export interface RegisteredAgent {
+  readonly id: string;
+  readonly installed: boolean;
+}
+
+interface SpawnDescriptions {
+  readonly tool: string;
+  readonly agent: string;
+}
+
+/**
+ * The `atc_session_spawn` description and its `agent` field description,
+ * naming the agents the daemon registered when the tool list was built. Only
+ * a registered id appears, and a registered agent whose binary is missing is
+ * marked not installed. null leaves every agent unnamed, for a tool list
+ * built while the daemon could not answer. Both point at `atc_agents_list`
+ * for the current list.
+ */
+export function buildSpawnDescriptions(
+  agents: readonly RegisteredAgent[] | null,
+): SpawnDescriptions {
+  const roster =
+    agents === null
+      ? ''
+      : ` When this tool list was built, the host registered: ${formatRoster(agents)}.`;
+
+  return {
+    tool: `Spawn a new session in a directory. Optional agent is a registered agent id; omitted agent is always Claude, never the TUI last-used value.${roster} atc_agents_list returns the current agents, whether each is installed, and the model and effort each takes. An unregistered agent, a registered agent that is not installed, and a model or effort the agent does not take are refused before anything spawns. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.`,
+    agent: `Registered agent id to spawn; defaults to claude.${roster} atc_agents_list returns the current list.`,
+  };
+}
+
+function formatRoster(agents: readonly RegisteredAgent[]): string {
+  if (agents.length === 0) {
+    return 'no agents';
+  }
+
+  return agents
+    .map((agent) => (agent.installed ? agent.id : `${agent.id} (not installed)`))
+    .join(', ');
+}

package/src/mcp/build-tool-list.ts

@@ -1,9 +1,14 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { isRecord } from '../shared/report';
+import { buildSpawnDescriptions } from './build-spawn-descriptions';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { MCP_TOOLS } from './mcp-tools';
 
 interface MCPTool {
   readonly name: string;
   readonly description: string;
   readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
   readonly annotations: {
     readonly readOnlyHint: boolean;
     readonly destructiveHint: boolean;
@@ -11,11 +16,87 @@ interface MCPTool {
   };
 }
 
-export function buildToolList(): readonly MCPTool[] {
-  return MCP_TOOLS.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    annotations: tool.annotations,
-  }));
+/**
+ * The tools `tools/list` returns for a daemon announcing the given
+ * features. A tool the daemon cannot serve is left out, and a tool it serves
+ * in an older form is listed without the output schema and input properties
+ * that form lacks, so a client never sees an option the daemon would ignore.
+ * The spawn tool's description and its agent field's description name the
+ * registered agents; null leaves them unnamed. No schema depends on which
+ * agents the host registers or installs.
+ */
+export function buildToolList(
+  features: ReadonlySet<DaemonFeature>,
+  agents: readonly RegisteredAgent[] | null,
+): readonly MCPTool[] {
+  const spawn = buildSpawnDescriptions(agents);
+
+  return MCP_TOOLS.flatMap((tool) => {
+    const requires = tool.requires ?? {};
+
+    if (requires.tool !== undefined && !features.has(requires.tool)) {
+      return [];
+    }
+
+    const gated = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+    const isSpawn = tool.name === 'atc_session_spawn';
+    const description = isSpawn ? spawn.tool : tool.description;
+    const inputSchema = isSpawn ? buildAgentFieldSchema(gated, spawn.agent) : gated;
+
+    return [
+      tool.outputSchema === undefined ||
+      (requires.output !== undefined && !features.has(requires.output))
+        ? {
+            name: tool.name,
+            description,
+            inputSchema,
+            annotations: tool.annotations,
+          }
+        : {
+            name: tool.name,
+            description,
+            inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: tool.annotations,
+          },
+    ];
+  });
+}
+
+function buildInputSchema(
+  schema: Readonly<Record<string, unknown>>,
+  inputs: Readonly<Record<string, DaemonFeature>>,
+  features: ReadonlySet<DaemonFeature>,
+): Readonly<Record<string, unknown>> {
+  const withheld = Object.entries(inputs).flatMap(([name, feature]) =>
+    features.has(feature) ? [] : [name],
+  );
+
+  const properties = schema['properties'];
+
+  if (withheld.length === 0 || !isRecord(properties)) {
+    return schema;
+  }
+
+  return {
+    ...schema,
+    properties: Object.fromEntries(
+      Object.entries(properties).filter(([name]) => !withheld.includes(name)),
+    ),
+  };
+}
+
+// The input schema with only the agent field's description replaced.
+function buildAgentFieldSchema(
+  schema: Readonly<Record<string, unknown>>,
+  description: string,
+): Readonly<Record<string, unknown>> {
+  const properties = schema['properties'];
+  const agent = isRecord(properties) ? properties['agent'] : undefined;
+
+  if (!isRecord(properties) || !isRecord(agent)) {
+    return schema;
+  }
+
+  return { ...schema, properties: { ...properties, agent: { ...agent, description } } };
 }