elanous 0.2.0 → 0.2.5

package/src/market/signed-index.ts

@@ -0,0 +1,156 @@
+import { createHash, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+
+export interface MarketplaceIndex {
+  name: string;
+  interface: { displayName: string };
+  sequence: number;
+  generatedAt?: string;
+  plugins: Array<{
+    name: string;
+    source: { source: string; [key: string]: unknown };
+    policy?: { installation: string; authentication: string };
+    category?: string;
+    version: string;
+    description?: string;
+    artifact: { sha256: string; bytes: number; key: string };
+    'ai.elanous': {
+      capabilities: string[];
+      connectors: Array<{ id: string; kind: string; userConfig: Array<{ key: string; label: string; secret: boolean }> }>;
+      graphs?: string[];
+      vocab?: string[];
+      requires?: { elanous?: string; tools?: string[] };
+      pricing: { model: 'free' | 'one-time' | 'subscription'; amount?: number; currency?: string; period?: string };
+    };
+  }>;
+}
+
+export type VerifyIndexResult =
+  | { ok: true; keyId: string; sequence: number; index: MarketplaceIndex }
+  | { ok: false; reason: 'bad-signature' | 'unknown-key' | 'sequence-rollback' | 'malformed'; detail: string };
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function string(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(string);
+}
+
+function rawBase64(value: unknown, length: number): Buffer | null {
+  if (!string(value) || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) return null;
+  const bytes = Buffer.from(value, 'base64');
+  return bytes.length === length && bytes.toString('base64') === value ? bytes : null;
+}
+
+function invalidIndex(value: unknown): string | null {
+  if (!record(value)) return 'index: expected object';
+  if (!string(value.name)) return 'name: expected string';
+  if (!record(value.interface) || !string(value.interface.displayName)) return 'interface.displayName: expected string';
+  if (!Number.isSafeInteger(value.sequence) || (value.sequence as number) < 0) return 'sequence: expected non-negative integer';
+  if (value.generatedAt !== undefined && !string(value.generatedAt)) return 'generatedAt: expected string';
+  if (!Array.isArray(value.plugins)) return 'plugins: expected array';
+
+  for (const [i, plugin] of value.plugins.entries()) {
+    const field = (name: string) => `plugins[${i}] (${record(plugin) && string(plugin.name) ? plugin.name : 'unnamed'}).${name}`;
+    if (!record(plugin)) return field('expected object');
+    if (!string(plugin.name)) return field('name: expected string');
+    if (!record(plugin.source) || !string(plugin.source.source)) return field('source.source: expected string');
+    if (plugin.policy !== undefined && (!record(plugin.policy) || !string(plugin.policy.installation) || !string(plugin.policy.authentication))) return field('policy: expected installation and authentication strings');
+    if (plugin.category !== undefined && !string(plugin.category)) return field('category: expected string');
+    if (!string(plugin.version)) return field('version: expected string');
+    if (plugin.description !== undefined && !string(plugin.description)) return field('description: expected string');
+    if (!record(plugin.artifact)) return field('artifact: expected object');
+    if (!string(plugin.artifact.sha256) || !/^[a-fA-F0-9]{64}$/.test(plugin.artifact.sha256)) return field('artifact.sha256: expected 64 hex characters');
+    if (!Number.isSafeInteger(plugin.artifact.bytes) || (plugin.artifact.bytes as number) < 0) return field('artifact.bytes: expected non-negative integer');
+    if (!string(plugin.artifact.key)) return field('artifact.key: expected string');
+    const ai = plugin['ai.elanous'];
+    if (!record(ai)) return field('ai.elanous: expected object');
+    if (!stringArray(ai.capabilities)) return field('ai.elanous.capabilities: expected string array');
+    if (!Array.isArray(ai.connectors)) return field('ai.elanous.connectors: expected array');
+    for (const [j, connector] of ai.connectors.entries()) {
+      if (!record(connector) || !string(connector.id) || !string(connector.kind) || !Array.isArray(connector.userConfig)) return field(`ai.elanous.connectors[${j}]: expected id, kind, userConfig`);
+      for (const [k, config] of connector.userConfig.entries()) {
+        if (!record(config) || !string(config.key) || !string(config.label) || typeof config.secret !== 'boolean') return field(`ai.elanous.connectors[${j}].userConfig[${k}]: expected key, label, secret`);
+      }
+    }
+    if (ai.graphs !== undefined && !stringArray(ai.graphs)) return field('ai.elanous.graphs: expected string array');
+    if (ai.vocab !== undefined && !stringArray(ai.vocab)) return field('ai.elanous.vocab: expected string array');
+    if (ai.requires !== undefined && (!record(ai.requires) || (ai.requires.elanous !== undefined && !string(ai.requires.elanous)) || (ai.requires.tools !== undefined && !stringArray(ai.requires.tools)))) return field('ai.elanous.requires: expected elanous string and tools string array');
+    if (!record(ai.pricing) || !['free', 'one-time', 'subscription'].includes(ai.pricing.model as string)) return field('ai.elanous.pricing.model: expected free, one-time or subscription');
+    if (ai.pricing.amount !== undefined && (typeof ai.pricing.amount !== 'number' || !Number.isFinite(ai.pricing.amount))) return field('ai.elanous.pricing.amount: expected number');
+    if (ai.pricing.currency !== undefined && !string(ai.pricing.currency)) return field('ai.elanous.pricing.currency: expected string');
+    if (ai.pricing.period !== undefined && !string(ai.pricing.period)) return field('ai.elanous.pricing.period: expected string');
+  }
+  return null;
+}
+
+export function verifyIndex(input: {
+  marketplaceBytes: Uint8Array;
+  signatureText: string;
+  trustedKeys: ReadonlyArray<{ keyId: string; publicKey: string }>;
+  lastSequence?: number;
+}): VerifyIndexResult {
+  const malformed = (detail: string): VerifyIndexResult => ({ ok: false, reason: 'malformed', detail });
+  let envelope: unknown;
+  try {
+    if (input.signatureText.includes('\n') || input.signatureText.includes('\r')) return malformed('index.sig: expected one JSON line');
+    envelope = JSON.parse(input.signatureText);
+  } catch {
+    return malformed('index.sig: invalid JSON');
+  }
+  if (!record(envelope) || !string(envelope.keyId) || !/^[a-fA-F0-9]{8}$/.test(envelope.keyId) || envelope.alg !== 'ed25519') {
+    return malformed('index.sig: expected 8-hex keyId and ed25519 alg');
+  }
+  const trusted = input.trustedKeys.find(key => key.keyId === envelope.keyId);
+  if (!trusted) return { ok: false, reason: 'unknown-key', detail: `index.sig.keyId: ${envelope.keyId}` };
+  const signature = rawBase64(envelope.sig, 64);
+  if (!signature) return malformed('index.sig.sig: expected base64 64-byte signature');
+  const publicKey = rawBase64(trusted.publicKey, 32);
+  if (!publicKey) return malformed(`trustedKeys[${envelope.keyId}].publicKey: expected base64 32-byte key`);
+  let valid: boolean;
+  try {
+    const key = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, publicKey]), format: 'der', type: 'spki' });
+    valid = verify(null, input.marketplaceBytes, key, signature);
+  } catch {
+    return malformed(`trustedKeys[${envelope.keyId}].publicKey: invalid Ed25519 key`);
+  }
+  if (!valid) return { ok: false, reason: 'bad-signature', detail: 'marketplace.json: signature verification failed' };
+
+  let index: unknown;
+  try {
+    index = JSON.parse(decoder.decode(input.marketplaceBytes));
+  } catch {
+    return malformed('marketplace.json: invalid UTF-8 or JSON');
+  }
+  const error = invalidIndex(index);
+  if (error) return malformed(`marketplace.json.${error}`);
+  const parsed = index as MarketplaceIndex;
+  if (input.lastSequence !== undefined && parsed.sequence < input.lastSequence) {
+    return { ok: false, reason: 'sequence-rollback', detail: `sequence ${parsed.sequence} < lastSequence ${input.lastSequence}` };
+  }
+  return { ok: true, keyId: envelope.keyId, sequence: parsed.sequence, index: parsed };
+}
+
+export function signIndex(marketplaceBytes: Uint8Array, privateKeyPem: string, keyId: string): string {
+  if (!/^[a-fA-F0-9]{8}$/.test(keyId)) throw new Error('keyId: expected 8 hex characters');
+  const signature = sign(null, marketplaceBytes, privateKeyPem);
+  return JSON.stringify({ keyId, alg: 'ed25519', sig: signature.toString('base64') });
+}
+
+export function generateIndexKeyPair(): { keyId: string; publicKey: string; privateKeyPem: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const der = publicKey.export({ format: 'der', type: 'spki' });
+  const raw = der.subarray(ED25519_SPKI_PREFIX.length);
+  return {
+    keyId: createHash('sha256').update(raw).digest('hex').slice(0, 8),
+    publicKey: raw.toString('base64'),
+    privateKeyPem: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString(),
+  };
+}

package/src/market/tgz.ts

@@ -0,0 +1,121 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { gzipSync } from 'node:zlib';
+
+const BLOCK = 512;
+const EXCLUDED = new Set(['.git', 'node_modules', '.DS_Store']);
+const excluded = (name: string) => EXCLUDED.has(name) || name.startsWith('.env');
+
+type Entry = { path: string; source: string; executable: boolean };
+
+function tarPath(path: string): { name: string; prefix: string } {
+  if (Buffer.byteLength(path) <= 100) return { name: path, prefix: '' };
+  for (let slash = path.lastIndexOf('/', path.length - 2); slash > 0; slash = path.lastIndexOf('/', slash - 1)) {
+    const prefix = path.slice(0, slash);
+    const name = path.slice(slash + 1);
+    if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) return { name, prefix };
+  }
+  throw new Error(`tar path exceeds ustar limits: ${path}`);
+}
+
+function text(header: Buffer, offset: number, width: number, value: string): void {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.length > width) throw new Error(`tar field exceeds ${width} bytes: ${value}`);
+  bytes.copy(header, offset);
+}
+
+function octal(header: Buffer, offset: number, width: number, value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0 || value.toString(8).length > width - 1) {
+    throw new Error(`tar numeric field exceeds ${width} bytes: ${value}`);
+  }
+  text(header, offset, width, value.toString(8).padStart(width - 1, '0'));
+}
+
+function headerFor(entry: Entry, size: number): Buffer {
+  const header = Buffer.alloc(BLOCK);
+  const { name, prefix } = tarPath(entry.path);
+  text(header, 0, 100, name);
+  octal(header, 100, 8, entry.executable ? 0o755 : 0o644);
+  octal(header, 108, 8, 0);
+  octal(header, 116, 8, 0);
+  octal(header, 124, 12, size);
+  octal(header, 136, 12, 0);
+  header.fill(0x20, 148, 156);
+  text(header, 156, 1, '0');
+  text(header, 257, 6, 'ustar');
+  text(header, 263, 2, '00');
+  text(header, 345, 155, prefix);
+  const checksum = header.reduce((sum, byte) => sum + byte, 0);
+  text(header, 148, 8, `${checksum.toString(8).padStart(6, '0')}\0 `);
+  return header;
+}
+
+/** Pack a directory as a reproducible ustar gzip archive; archive paths are relative to its root. */
+export function packDirDeterministic(dir: string, opts?: {
+  exclude?: RegExp;
+  extraDirs?: ReadonlyArray<{ from: string; as: string }>;
+}): Uint8Array {
+  const root = lstatSync(dir);
+  if (!root.isDirectory() || root.isSymbolicLink()) throw new Error(`not a directory: ${dir}`);
+  const entries: Entry[] = [];
+  function walk(source: string, relative: string, normalizeSkill?: string): void {
+    for (const name of readdirSync(source)) {
+      if (excluded(name)) continue;
+      const path = relative ? `${relative}/${name}` : name;
+      if (opts?.exclude) {
+        opts.exclude.lastIndex = 0;
+        if (opts.exclude.test(path)) continue;
+      }
+      const child = join(source, name);
+      const stat = lstatSync(child);
+      if (stat.isSymbolicLink()) throw new Error(`cannot pack symbolic link: ${path}`);
+      if (stat.isDirectory()) {
+        walk(child, path);
+      } else if (stat.isFile()) {
+        // Compare real directory entries: on a case-insensitive disk (macOS) existsSync('SKILL.md') is true for skill.md.
+        const archivePath = normalizeSkill && name === 'skill.md' && relative === normalizeSkill &&
+          !readdirSync(source).includes('SKILL.md') ? `${relative}/SKILL.md` : path;
+        entries.push({ path: archivePath, source: child, executable: (stat.mode & 0o111) !== 0 });
+      } else {
+        throw new Error(`cannot pack non-regular file: ${path}`);
+      }
+    }
+  }
+  walk(dir, '');
+  const destinations: string[] = [];
+  for (const { from, as } of opts?.extraDirs ?? []) {
+    if (!as || posix.isAbsolute(as) || as.split('/').some(part => !part || part === '.' || part === '..' || excluded(part)) || as.includes('\\')) {
+      throw new Error(`bundle-conflict: invalid destination ${as}`);
+    }
+    if (destinations.some(path => as === path || as.startsWith(`${path}/`) || path.startsWith(`${as}/`)) ||
+        existsSync(join(dir, ...as.split('/'))) ||
+        entries.some(entry => entry.path === as || entry.path.startsWith(`${as}/`) || as.startsWith(`${entry.path}/`))) {
+      throw new Error(`bundle-conflict: ${as}`);
+    }
+    const stat = lstatSync(from);
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) throw new Error(`not a directory or file: ${from}`);
+    destinations.push(as);
+    // A single file (e.g. a graph declaration) lands at exactly `as`.
+    if (stat.isFile()) entries.push({ path: as, source: from, executable: (stat.mode & 0o111) !== 0 });
+    else walk(from, as, as);
+  }
+  entries.sort((a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path)));
+  for (let i = 1; i < entries.length; i++) {
+    if (entries[i]?.path === entries[i - 1]?.path) throw new Error(`bundle-conflict: ${entries[i]?.path}`);
+  }
+  const blocks: Buffer[] = [];
+  for (const entry of entries) {
+    const contents = readFileSync(entry.source);
+    blocks.push(headerFor(entry, contents.length));
+    if (contents.length) {
+      blocks.push(contents);
+      const padding = (BLOCK - (contents.length % BLOCK)) % BLOCK;
+      if (padding) blocks.push(Buffer.alloc(padding));
+    }
+  }
+  blocks.push(Buffer.alloc(BLOCK * 2));
+  const gzip = gzipSync(Buffer.concat(blocks));
+  gzip.fill(0, 4, 8);
+  gzip[9] = 255;
+  return gzip;
+}

package/src/mcp/client.ts

@@ -529,7 +529,7 @@ export interface McpClientOpts {
 
 // ─── Internal shapes ─────────────────────────────────────────────
 
-const CLIENT_INFO = { name: 'monad-agent', version: '0.1.0' };
+const CLIENT_INFO = { name: 'elanous-agent', version: '0.1.0' };
 /** MCP Apps 확장(SEP-1865 · Final)을 «우리가 실제로 하는 만큼» 선언한다.
  *
  *  ⛔⭐ `mimeTypes` 는 스펙이 «필수»로 요구한다 — 빈 객체로 선언하면

package/src/mcp/mcp-oauth.ts

@@ -27,7 +27,7 @@ import { debug } from '../debug/log.js';
 const REFRESH_BUFFER_MS = 120_000;
 const AUTH_MODE = 'mcp-oauth';
 const DEFAULT_REDIRECT_URI = 'http://127.0.0.1/oauth/callback';
-const CLIENT_NAME = 'monad-agent';
+const CLIENT_NAME = 'elanous-agent';
 
 export type McpOAuthErrorCode =
   | 'discovery'
@@ -79,6 +79,8 @@ export interface AuthorizationServerMetadata {
 export interface ClientRegistration {
   clientId: string;
   clientSecret?: string;
+  /** 동적 등록 때 쓴 redirect_uri. 옛 등록에는 없다. */
+  redirectUri?: string;
 }
 
 export interface AuthorizationRequest {
@@ -131,6 +133,8 @@ export interface McpOAuthAuthorization {
 export interface PrepareMcpOAuthAuthorizationOpts extends McpOAuthRuntimeOpts {
   resourceMetadataUrl: string;
   scope?: string;
+  /** 저장된 등록의 포트를 못 열었을 때 새 client_id 로 다시 등록한다. */
+  forceReregister?: boolean;
 }
 
 /** ⛔⭐⭐ MCP 자격은 «우주를 따라가지 않는다» — 격리 매뉴얼 §6 의 전역 사용자 자산이다.
@@ -172,6 +176,7 @@ function loadIssuerState(
       authMode: AUTH_MODE,
       ...(stranded.accountUuid ? { accountUuid: stranded.accountUuid } : {}),
       ...(stranded.organizationUuid ? { organizationUuid: stranded.organizationUuid } : {}),
+      ...(stranded.redirectUri ? { redirectUri: stranded.redirectUri } : {}),
       mirrorCodex: false,
     },
     path,
@@ -402,9 +407,11 @@ function registrationFromState(state: ProviderAuthState | null): ClientRegistrat
   const clientId = state?.accountUuid?.trim();
   if (!state || !clientId) return null;
   const clientSecret = state.organizationUuid?.trim();
+  const redirectUri = state.redirectUri?.trim();
   return {
     clientId,
     ...(clientSecret ? { clientSecret } : {}),
+    ...(redirectUri ? { redirectUri } : {}),
   };
 }
 
@@ -426,12 +433,32 @@ function persistRegistration(
         : existing?.organizationUuid
           ? { organizationUuid: existing.organizationUuid }
           : {}),
+      ...(registration.redirectUri ? { redirectUri: registration.redirectUri } : {}),
       mirrorCodex: false,
     },
     path,
   );
 }
 
+/** 루프백 redirect_uri 의 TCP 포트. 없거나 기본 포트(생략)면 null. */
+export function loopbackRedirectPort(redirectUri: string | undefined): number | null {
+  if (!redirectUri?.trim()) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(redirectUri);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+  if (parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost' && parsed.hostname !== '[::1]') {
+    return null;
+  }
+  if (!parsed.port) return null;
+  const port = Number(parsed.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  return port;
+}
+
 export function loadStoredRegistration(
   issuer: string,
   opts: McpOAuthRuntimeOpts = {},
@@ -441,11 +468,14 @@ export function loadStoredRegistration(
 
 export async function ensureClientRegistration(
   metadata: AuthorizationServerMetadata,
-  opts: McpOAuthRuntimeOpts = {},
+  opts: McpOAuthRuntimeOpts & { forceReregister?: boolean } = {},
 ): Promise<ClientRegistration> {
   const path = storePath(opts);
-  const stored = loadStoredRegistration(metadata.issuer, { storePath: path });
-  if (stored) return stored;
+  if (!opts.forceReregister) {
+    const stored = loadStoredRegistration(metadata.issuer, { storePath: path });
+    // 옛 등록은 redirect_uri 기록이 없다 — 재사용하면 포트 불일치로 영원히 막힌다.
+    if (stored?.redirectUri) return stored;
+  }
   if (!metadata.registrationEndpoint) {
     throw new McpOAuthError(
       'registration',
@@ -489,6 +519,7 @@ export async function ensureClientRegistration(
   const registration: ClientRegistration = {
     clientId,
     ...(clientSecret ? { clientSecret } : {}),
+    redirectUri,
   };
   persistRegistration(metadata.issuer, registration, path);
   return registration;
@@ -642,6 +673,7 @@ function persistTokens(
       authMode: AUTH_MODE,
       ...(clientId ? { accountUuid: clientId } : {}),
       ...(clientSecret ? { organizationUuid: clientSecret } : {}),
+      ...(existing?.redirectUri ? { redirectUri: existing.redirectUri } : {}),
       mirrorCodex: false,
     },
     path,
@@ -769,7 +801,10 @@ export async function prepareMcpOAuthAuthorization(
   opts: PrepareMcpOAuthAuthorizationOpts,
 ): Promise<McpOAuthAuthorization> {
   const { resource, metadata } = await discoverMcpOAuth(opts.resourceMetadataUrl, opts);
-  const registration = await ensureClientRegistration(metadata, opts);
+  const registration = await ensureClientRegistration(metadata, {
+    ...opts,
+    ...(opts.forceReregister ? { forceReregister: true } : {}),
+  });
   const request = buildAuthorizationRequest(metadata, registration, {
     scope: opts.scope,
     resource: resource.resource,

package/src/mcp/server.ts

@@ -25,6 +25,10 @@ import { dispatchToolByName, listToolRuntimes, getToolRuntime } from '../tool-ru
 import { findNativeTool } from '../native-tool-catalog.js';
 import { debug } from '../debug/log.js';
 import { userIntentLogger } from '../user-intent/index.js';
+import { buildCliAgentTools } from '../cli/agent-cli.js';
+import { getUserConfig } from '../user-config.js';
+import type { TokenScope } from '../auth/scope.js';
+import { filterToolsForScope, isToolAllowedForScope } from '../nexus/api/mcp-public-allowlist.js';
 
 // ─── JSON-RPC shapes ─────────────────────────────────────────────
 
@@ -71,7 +75,7 @@ export function negotiateMcpProtocolVersion(
   return MCP_PROTOCOL_VERSION_LATEST;
 }
 
-const SERVER_INFO = { name: 'monad-agent', version: '0.1.0' };
+const SERVER_INFO = { name: 'elanous-agent', version: '0.1.0' };
 
 // ─── Handler ─────────────────────────────────────────────────────
 
@@ -91,6 +95,11 @@ export interface McpServerContext {
    *  Unset = emit is skipped (preserves backward-compat for any caller
    *  not yet origin-aware). */
   origin?: 'mcp-http' | 'mcp-stdio' | 'rest';
+  /** Filled from `initialize.params.clientInfo.name` on a stdio
+   *  connection; forwarded to tools as `ctx.mcpClient`. */
+  clientName?: string;
+  /** Authenticated HTTP token scope; absent on stdio and other trusted transports. */
+  tokenScope?: TokenScope;
 }
 
 /** Emit a `system.mcp.proxy_call` user-intent event for a single
@@ -130,7 +139,9 @@ export async function handleMcpRequest(
   const base = { jsonrpc: '2.0' as const, id };
   try {
     switch (req.method) {
-      case 'initialize':
+      case 'initialize': {
+        const clientInfo = req.params?.clientInfo as { name?: unknown } | undefined;
+        if (typeof clientInfo?.name === 'string' && clientInfo.name.trim()) ctx.clientName = clientInfo.name.trim().slice(0, 80);
         return {
           ...base,
           result: {
@@ -139,22 +150,30 @@ export async function handleMcpRequest(
             serverInfo: SERVER_INFO,
           },
         };
+      }
 
       case 'initialized':
       case 'notifications/initialized':
         return { ...base, result: {} };
 
       case 'tools/list': {
+        await preloadCoreTools();
         ensureDefaultMcpToolRuntimes();
         const surface = ctx.surface ?? 'mcp';
         const runtimes = listToolRuntimes(surface);
         logMcpToolsList(runtimes, surface, ctx.origin);
-        return { ...base, result: { tools: runtimes.map(runtimeToMcpTool) } };
+        const tools = runtimes.map(rt => runtimeToMcpTool(rt, surface));
+        return { ...base, result: { tools: ctx.tokenScope ? filterToolsForScope(tools, ctx.tokenScope) : tools } };
       }
 
       case 'tools/call': {
+        await preloadCoreTools();
         ensureDefaultMcpToolRuntimes();
         const name = typeof req.params?.name === 'string' ? req.params.name : '';
+        if (ctx.tokenScope && !isToolAllowedForScope(name, ctx.tokenScope)) {
+          emitProxyCallIntent(name, ctx.origin, false, 'unknown_tool');
+          return { ...base, error: { code: -32601, message: `unknown tool: ${name}` } };
+        }
         const args = (req.params?.arguments as Record<string, unknown>) ?? {};
         const surface = ctx.surface ?? 'mcp';
         const rt = getToolRuntime(name);
@@ -167,7 +186,32 @@ export async function handleMcpRequest(
           };
         }
         try {
-          const out = await dispatchToolByName(name, args, { surface });
+          const isMcpAgent = surface === 'mcp' && rt.id === 'agent';
+          const agentArgs = isMcpAgent
+            ? { ...args, run_in_background: args.run_in_background ?? true }
+            : args;
+          const agentConfig = isMcpAgent ? getUserConfig() : undefined;
+          const agentCwd = typeof args.cwd === 'string' ? args.cwd : process.cwd();
+          const agentTools = agentConfig
+            ? buildCliAgentTools(agentConfig, undefined, agentCwd)
+            : undefined;
+          const out = await dispatchToolByName(name, agentArgs, {
+            surface,
+            ...(ctx.clientName ? { mcpClient: ctx.clientName } : {}),
+            ...(agentTools ? {
+              agentHostTools: agentTools.specs,
+              agentCwd,
+              agentDispatchTool: agentTools.dispatch,
+              buildChildToolCatalog: (childCwd: string) => buildCliAgentTools(agentConfig, undefined, childCwd),
+            } : {}),
+          });
+          if (isMcpAgent && 'taskId' in out && typeof out.taskId === 'string') {
+            debug.log('mcp.agent', 'spawned', {
+              taskId: out.taskId,
+              client: ctx.clientName,
+              background: agentArgs.run_in_background === true,
+            });
+          }
           emitProxyCallIntent(name, ctx.origin, true);
           return { ...base, result: toMcpToolCallResult(out) };
         } catch (err) {
@@ -192,6 +236,13 @@ export async function handleMcpRequest(
   }
 }
 
+let preloaded: Promise<unknown> | null = null;
+
+async function preloadCoreTools(): Promise<void> {
+  preloaded ??= import('../domains/core-tools.js').catch(() => {});
+  await preloaded;
+}
+
 /** Ensure direct MCP transports expose elanous-owned runtimes even before
  * the daemon's broader boot sequence has registered them. Registration is
  * idempotent, so externally registered proxy runtimes remain untouched. */
@@ -221,11 +272,28 @@ function logMcpToolsList(
   } catch { /* observability must not break JSON-RPC */ }
 }
 
-function runtimeToMcpTool(rt: ToolRuntime): Record<string, unknown> {
+function runtimeToMcpTool(rt: ToolRuntime, surface: ToolSurface) {
+  const inputSchema = surface === 'mcp' && rt.id === 'agent'
+    ? {
+        ...rt.spec.parameters,
+        properties: {
+          ...(rt.spec.parameters.properties as Record<string, unknown>),
+          cwd: {
+            type: 'string',
+            description: 'Optional MCP working directory for the child. Defaults to the MCP server process cwd.',
+          },
+        },
+      }
+    : rt.spec.parameters;
+  // Over MCP the agent tool runs in the background unless the caller says otherwise (client tool
+  // timeouts are short) — say so in the description the MCP client shows its model (#21088 review).
+  const description = surface === 'mcp' && rt.id === 'agent'
+    ? `${rt.spec.description} Over MCP this returns immediately with a taskId (run_in_background defaults to true); collect the result with AgentOutput(taskId, block: true) and cancel with AgentStop(taskId). Pass cwd to run the child in a specific project folder.`
+    : rt.spec.description;
   return {
     name: rt.spec.name,
-    description: rt.spec.description,
-    inputSchema: rt.spec.parameters,
+    description,
+    inputSchema,
   };
 }