@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/agent-mcp.js

@@ -0,0 +1,859 @@
+import { randomUUID } from 'node:crypto';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { configDirectory, loadConfig } from './config.js';
+import { graphStorageDirectory } from './graph-account.js';
+import { GraphSync } from './graph-sync.js';
+import { stampGraphProviderProfiles } from './graph-provider-portability.js';
+import { getAuthStatus } from './auth/index.js';
+import { getMembership, PaidMembershipRequiredError } from './membership.js';
+import { FREE_CUSTOM_GRAPH_LIMIT, FREE_GRAPH_LIMIT_MESSAGE, FreeTierLimitError, readGraphQuota, saveFreeTierGraph } from './graph-quota.js';
+import { GraphConflictError, listGraphs, loadGraph, migrateGraphForEditor, nodeOutcomes, saveGraph, validateGraph } from './graphs.js';
+import { getAgentSession, listAgentProjects, queryAgentSessions, scanAgentSessions, SessionQueryError } from './session-monitor.js';
+import { canonicalWorkspace, MAX_SUBAGENT_TASK_CHARS, SubagentInvalidArgumentError, SubagentProviderNotSetError, SubagentRunInProgressError, SubagentRunner, SubagentSelectionError } from './subagent-run.js';
+import { reconcileInterruptedRuns } from './run-records.js';
+export const GRAPH_AGENT_GUIDE = [
+    '# Andorra Code Graph Agent Architecture (MCP)',
+    '',
+    'Graph IDs and node IDs are safe identifiers (letters/numbers/underscore/dash; at most 80 chars).',
+    'A published graph is immutable by revision. Always open an editing draft, then publish once complete.',
+    'Never edit a graph snapshot or its latest pointer directly. If a revision conflict occurs, reopen latest and reapply changes.',
+    '',
+    '## Editing sequence',
+    '1. andorra_providers_list and andorra_graphs_list discover provider IDs and existing graphs.',
+    '2. andorra_graph_begin mode=create with id and name, or mode=edit with id. The reply gives a draftId.',
+    '3. andorra_graph_node_upsert creates full nodes; andorra_graph_node_patch changes settings, prompts or provider.',
+    '4. andorra_graph_edge_upsert links the exact source outcome to a target node.',
+    '5. andorra_graph_patch sets entry, name, limits, widgets and schemas.',
+    '6. andorra_graph_validate returns all missing-provider and missing-path issues plus the structural validator error.',
+    '7. andorra_graph_publish validates and saves an optimistic, immutable revision. Fix issues; do not suppress them.',
+    '8. andorra_graph_discard abandons a draft. Drafts are process-local, expire after an hour and are not published until saved.',
+    '',
+    '## Node types and edge routing',
+    'agent: runs a prompt/instruction/systemPrompt using an explicitly configured provider ID and optional model.',
+    '  completion single has one outcome (default completed); completion outcomes lists named ports (for example pass, fail).',
+    '  For multi-outcome agents supply completion: {mode: "outcomes", outcomes: ["pass", "fail"]}.',
+    '  Every declared outcome must have an outgoing edge unless completion.requireRoutes is explicitly false.',
+    '  Agents created or modified through MCP must set provider; never assume the active provider is inherited.',
+    'condition: requires condition {source, path, equals}; ports true and false; source must run before it on every path.',
+    'loop: requires loop {maxIterations}; ports body and done. A body edge may return to the loop.',
+    '  Node visits are unlimited unless the graph sets graph.limits.maxNodeVisits; 0 means unlimited there too.',
+    '  A cycle still needs a ceiling: graph.limits.maxNodeVisits or graph.limits.wallTimeMs, one of the two.',
+    '  A finite graph.limits.maxNodeVisits must be large enough for loop maxIterations plus reentry.',
+    'approval: ports approved and rejected. The live runtime asks the person before advancing.',
+    'join: join {mode:"all"|"any"}. Join all must not wait on mutually exclusive outcome branches.',
+    'parallel: fan-out; connect its completed port to downstream work.',
+    'action: action {kind:"command"|"tests"|"git",command:"..."}; graph capability constraints still apply.',
+    'end: terminal node; no outgoing ports. Every graph needs an End and 2-100 nodes (plus optional Orchestrator).',
+    'All nodes must be reachable from entry. Every edge source/target must exist; outcome must match a source port.',
+    'A graph with a version-3 Orchestrator needs that Orchestrator as entry and it cannot have incoming edges.',
+    '',
+    '## Example: two-outcome QA workflow',
+    'Begin graph id=qa-flow name="QA Flow". Add agent id=check, provider=<configured id>,',
+    'completion={mode:"outcomes",outcomes:["pass","fail"]}, instruction="Run checks and report pass or fail".',
+    'Add end nodes id=accepted and id=review. Set entry=check.',
+    'Create edge check -> accepted outcome=pass, and check -> review outcome=fail.',
+    'If fail is missing: NODE_ROUTE_MISSING includes nodeId="check" and port="fail".',
+    '',
+    '## Errors',
+    'Tool replies are JSON with ok=true/data or ok=false/error containing code, message, nodeId, port, edgeId, issues.',
+    'NODE_PROVIDER_MISSING: set node.provider to an ID from andorra_providers_list.',
+    'NODE_PROVIDER_INVALID: provider was removed or never configured; select a valid profile.',
+    'NODE_ROUTE_MISSING: create an edge for that nodeId and named outcome.',
+    'EDGE_OUTCOME_INVALID: match one of the valid source ports.',
+    'GRAPH_INVALID: correct structural graph validation errors (cycles, unreachable nodes, Join dependencies, schemas).',
+    'STORAGE_ERROR: local filesystem data cannot be accessed; check installation directory and permissions.',
+    'BACKEND_ERROR: MCP request could not complete; check local configuration and logs, then retry.',
+    'REVISION_CONFLICT: another editor/device saved first; reopen the latest graph, reapply, and publish.',
+    '',
+    '## Sessions and monitoring',
+    'andorra_projects_list enumerates registered and discovered session workspaces.',
+    'andorra_sessions_list filters by projectName/projectPath, status, updatedAfter, updatedBefore, lookbackMinutes.',
+    'Status values: completed, pending (no task yet), running (live run), required_input (question/approval or',
+    'needs_clarification), incomplete (interrupted/cancelled/exhausted/infrastructure error or orphaned running marker).',
+    'andorra_sessions_attention returns required_input and incomplete sessions; poll it from an external agent.',
+    'andorra_session_get returns selected turn summaries and IDs without reading arbitrary files.',
+    'MCP is a local stdio process; it does not send notifications on its own or expose a public listener.',
+    'The local app-server records pending questions and approvals. A CLI-only live input prompt may not have a sidecar;',
+    'a completed needs_clarification outcome is still observable.',
+    '',
+    '## Subagent runs',
+    'andorra_subagent_start runs exactly the bundled Software Engineer graph (single agent, no graph selection).',
+    'A provider/model is mandatory: name provider and model in the call, or rely on the saved /subagent setting.',
+    'PROVIDER_NOT_SET replies list every configured provider with its models — present that list to the user, ask',
+    'which pair to use, and retry the call with provider and model. Runs write files unless permissions=read-only;',
+    'one run at a time per process (RUN_IN_PROGRESS). Poll andorra_subagent_status, collect with',
+    'andorra_subagent_result, abort with andorra_subagent_cancel.',
+].join('\n');
+export class AgentMcpError extends Error {
+    code;
+    info;
+    constructor(code, message, info = {}) {
+        super(message);
+        this.code = code;
+        this.info = info;
+        this.name = 'AgentMcpError';
+    }
+}
+const ident = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/;
+const safeId = (value) => typeof value === 'string' && ident.test(value) && !['__proto__', 'prototype', 'constructor'].includes(value);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function argsRecord(value) {
+    if (!record(value))
+        throw new AgentMcpError('INVALID_ARGUMENTS', 'Tool arguments must be an object.');
+    return value;
+}
+function field(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || !value.trim())
+        throw new AgentMcpError('INVALID_ARGUMENTS', key + ' must be a nonempty string.');
+    return value;
+}
+function draftId(args) {
+    const value = field(args, 'draftId');
+    if (!/^[a-f0-9-]{36}$/i.test(value))
+        throw new AgentMcpError('INVALID_DRAFT', 'draftId must be the UUID returned by andorra_graph_begin.');
+    return value;
+}
+const knownTypes = ['agent', 'end', 'join', 'parallel', 'condition', 'loop', 'action', 'approval'];
+/** Used only inside the canonical graph validator's catch block. */
+const graphValidationIssue = (error) => ({ code: 'GRAPH_INVALID', message: error instanceof Error ? error.message : 'Graph validation failed.' });
+/** Ordinary backend and storage failures are not evidence of malformed graph topology.
+ * Do not echo raw OS exception messages: they can contain private local paths. */
+function backendIssue(error) {
+    const code = error && typeof error === 'object' && 'code' in error
+        ? error.code : undefined;
+    const storageCodes = ['EACCES', 'EPERM', 'EROFS', 'EIO', 'ENOSPC', 'EBUSY', 'EMFILE', 'ENFILE', 'ENOENT', 'ENOTDIR'];
+    return typeof code === 'string' && storageCodes.includes(code)
+        ? { code: 'STORAGE_ERROR', message: 'Andorra Code could not access its local data. Check the installation directory and filesystem permissions, then retry.' }
+        : { code: 'BACKEND_ERROR', message: 'Andorra Code could not complete this MCP request. Check the local configuration and logs, then retry.' };
+}
+/** Single source of truth: the published graph validator remains authoritative for all topology rules. */
+function graphIssues(graph, providers, defaultProvider, authoredAgents = new Set()) {
+    const issues = [];
+    for (const [id, node] of Object.entries(graph.nodes)) {
+        if (!record(node))
+            continue;
+        if (node.type === 'agent') {
+            if (!node.provider && authoredAgents.has(id))
+                issues.push({ code: 'NODE_PROVIDER_MISSING', nodeId: id,
+                    message: 'Node ' + id + ': Provider not set. Please select a valid provider.' });
+            else if (node.provider && !providers.some(item => item.id === node.provider))
+                issues.push({ code: 'NODE_PROVIDER_INVALID', nodeId: id,
+                    message: 'Node ' + id + ': Provider "' + node.provider + '" is invalid. Please select a valid provider.' });
+        }
+        if (!knownTypes.includes(String(node.type)))
+            continue;
+        let ports;
+        try {
+            ports = nodeOutcomes(node);
+        }
+        catch {
+            continue;
+        } // Let the canonical validator explain invalid modifier structures.
+        for (const port of ports) {
+            if (node.completion?.mode === 'outcomes' && node.completion.requireRoutes === false)
+                continue;
+            if (!graph.edges.some(edge => edge.source === id && (edge.outcome ?? 'completed') === port)) {
+                issues.push({ code: 'NODE_ROUTE_MISSING', nodeId: id, port,
+                    message: 'Node ' + id + ': ' + port + ' does not have a valid path. Please set a valid path for ' + port + '.' });
+            }
+        }
+    }
+    if (graph.entry && !Object.hasOwn(graph.nodes, graph.entry)) {
+        issues.push({ code: 'ENTRY_NOT_FOUND', message: 'Graph entry "' + graph.entry + '" does not name an existing node. Set entry to a valid node ID.' });
+    }
+    else if (!graph.entry) {
+        issues.push({ code: 'ENTRY_NOT_FOUND', message: 'Graph entry is not set. Set entry to a valid node ID.' });
+    }
+    else {
+        const seen = new Set(), queue = [graph.entry];
+        while (queue.length) {
+            const id = queue.pop();
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            for (const edge of graph.edges)
+                if (edge.source === id && Object.hasOwn(graph.nodes, edge.target))
+                    queue.push(edge.target);
+        }
+        for (const id of Object.keys(graph.nodes))
+            if (!seen.has(id))
+                issues.push({
+                    code: 'NODE_UNREACHABLE', nodeId: id, message: 'Node ' + id + ' is unreachable from entry ' + graph.entry + '. Connect an incoming path or remove it.',
+                });
+    }
+    if (Object.keys(graph.nodes).length > 0 && !Object.values(graph.nodes).some(node => node?.type === 'end')) {
+        issues.push({ code: 'END_NODE_MISSING', message: 'Graph must contain at least one End node. Add an End node and connect a valid path.' });
+    }
+    // The full validator also checks schemas, cycles and Join dependencies. Run it
+    // even while there are missing ports: otherwise the agent learns about an
+    // invalid schema only after another round trip to repair an unrelated edge.
+    try {
+        validateGraph(graph, { providers, defaultProvider, spawnAvailable: true });
+    }
+    catch (error) {
+        const issue = graphValidationIssue(error);
+        // Required routes have already been reported with nodeId/port above.
+        // Avoid burying a useful diagnosis under the validator's duplicate prose.
+        if (!issues.some(item => item.code === 'NODE_ROUTE_MISSING'
+            && issue.message.includes(`node ${item.nodeId}: required outcome ${item.port} has no route`))
+            && !(issues.some(item => item.code === 'ENTRY_NOT_FOUND') && /entry must reference an existing node/.test(issue.message))
+            && !(issues.some(item => item.code === 'NODE_UNREACHABLE') && /all nodes must be reachable from the entry/.test(issue.message)))
+            issues.push(issue);
+    }
+    return issues;
+}
+export class AgentMcpBackend {
+    options;
+    directory;
+    drafts = new Map();
+    sync;
+    accessKey;
+    /** An account's first snapshot reconciliation must finish before any reader sees its graphs. */
+    initialSync;
+    /** Subagent runs this process owns; one at a time, like every other engine surface. */
+    subagent;
+    /**
+     * The starts that are preparing and have published no run id yet.
+     *
+     * A count, not a flag: a second start that is refused while the first is still preparing
+     * releases its own reservation, and a flag it cleared would take the first start's with it.
+     */
+    starting = 0;
+    /** Set when the connection closed: a start that begins after it must not launch a run. */
+    closed = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.directory = options.directory ?? configDirectory();
+        // The run's records belong to the home this backend was built for, not to whichever
+        // installation happens to sit on the machine.
+        this.subagent = new SubagentRunner({
+            directory: this.directory,
+            // The injected provider reader keeps embedded hosts and tests on their own configuration;
+            // production reads the installation directory this backend was built for.
+            loadConfig: directory => this.options.providerConfig ? this.options.providerConfig() : loadConfig(directory),
+        });
+        // Attempts a previous process left in flight are classified before this one starts: a host
+        // that only ever talks to the MCP server would otherwise keep its own crashed runs marked
+        // `running` until an unrelated interactive CLI or app-server was opened. Best effort: a
+        // damaged home must not block the server.
+        // Another engine in this process may have a live run in this home — an app-server, or a
+        // second backend. A record this process is running is not this backend's to classify, so the
+        // sweep leaves it alone.
+        this.recovery = reconcileInterruptedRuns(this.directory, undefined, { skipOwnProcess: true }).then(() => undefined).catch(() => undefined);
+    }
+    /** The startup recovery, finished before the first subagent start is accepted. */
+    recovery;
+    /**
+     * The run a control call is about.
+     *
+     * One backend can serve several requesters, and a new run may start as soon as the previous one
+     * has finished. A call that names the run it means is refused when that run is no longer the
+     * current one: a delayed result would otherwise report the next run's state, and a delayed
+     * cancellation would stop it.
+     */
+    assertSubagentRun(runId) {
+        if (typeof runId !== 'string' || !runId) {
+            throw new AgentMcpError('INVALID_ARGUMENTS', 'runId must be the id the start returned.');
+        }
+        const status = this.subagent.status();
+        const current = status.runId;
+        // A start that is still preparing has published no id: a control call cannot name the run it
+        // is about, and an id it made up would cancel a run whose id the caller never had.
+        if (current === undefined && this.starting > 0) {
+            throw new AgentMcpError('INVALID_ARGUMENTS', 'The run is still starting and has published no id yet.');
+        }
+        // A replacement is preparing while the run that was current has already finished. A control
+        // call that names the finished run is stale, and the runner would read it as a cancellation
+        // of the replacement — a run whose id the caller never received.
+        if (current !== undefined && this.starting > 0 && status.state !== 'running') {
+            throw new AgentMcpError('INVALID_ARGUMENTS', 'That run has finished and a replacement is starting; the run it named is not the one this process owns.');
+        }
+        // No run is live: the id the caller names cannot have come from a start, and answering about
+        // whatever the process happens to hold would let a stale caller read a different run's state.
+        if (current === undefined) {
+            throw new AgentMcpError('NO_RUN', 'No run is live in this process; the run it named has finished.');
+        }
+        if (current !== runId) {
+            throw new AgentMcpError('INVALID_ARGUMENTS', 'That run is no longer the one this process owns; the run it named has finished.');
+        }
+    }
+    async close() {
+        // The connection is gone: a start that is still preparing must not become a run, and the
+        // runner refuses one from here on.
+        this.closed = true;
+        this.drafts.clear();
+        // The run this process owns ends with it: a provider request or a full-access tool call
+        // that outlived the connection would keep a supposedly closed process alive.
+        await this.subagent.shutdown();
+        await this.initialSync?.catch(() => { });
+        await this.sync?.close();
+        this.sync = undefined;
+        this.initialSync = undefined;
+        this.accessKey = undefined;
+    }
+    async graphAccess() {
+        let access;
+        if (this.options.graphAccess)
+            access = await this.options.graphAccess();
+        else {
+            const authStatus = this.options.authStatus ?? getAuthStatus;
+            const before = await authStatus();
+            if (!before.signedIn || !before.subject)
+                throw new AgentMcpError('AUTH_REQUIRED', 'Sign in to your Andorra Code account to edit graphs.');
+            if (!/^[A-Za-z0-9-]{1,128}$/.test(before.subject))
+                throw new AgentMcpError('AUTH_REQUIRED', 'The signed-in account has an invalid graph storage identity. Sign in again.');
+            // A paid verdict is scoped to the exact subject returned by /me. Checking
+            // paid first and reading whichever account is current afterwards would let
+            // a concurrent login switch open another account's graph directory.
+            const membership = await (this.options.membershipStatus ?? getMembership)();
+            // A free account edits its one custom graph; the allowance is enforced when a draft is published.
+            if (!membership.paid && !membership.subject)
+                throw new PaidMembershipRequiredError();
+            if (!membership.subject || membership.subject !== before.subject)
+                throw new AgentMcpError('AUTH_CHANGED', 'Account changed while checking membership. Retry graph access with the current account.');
+            const after = await authStatus();
+            if (!after.signedIn || after.subject !== membership.subject)
+                throw new AgentMcpError('AUTH_CHANGED', 'Account changed while checking membership. Retry graph access with the current account.');
+            const directory = await graphStorageDirectory(this.directory, membership.subject, true);
+            const confirmed = await authStatus();
+            if (!confirmed.signedIn || confirmed.subject !== membership.subject)
+                throw new AgentMcpError('AUTH_CHANGED', 'Account changed while opening graph storage. Retry graph access with the current account.');
+            access = { directory, subject: membership.subject, free: !membership.paid };
+        }
+        const key = access.directory + '\0' + (access.subject ?? '');
+        if (this.accessKey !== key) {
+            // Set up the *shared* initialization promise synchronously before any await.
+            // Concurrent list/get requests must all observe the same completed sync, not
+            // treat a matching accessKey as proof that cloud restore finished.
+            const previous = this.sync;
+            this.accessKey = key;
+            this.drafts.clear();
+            const next = access.subject && (!this.options.graphAccess || this.options.graphSyncFactory)
+                ? this.options.graphSyncFactory?.(access.directory, access.subject)
+                    ?? new GraphSync(access.directory, access.subject)
+                : undefined;
+            this.sync = next;
+            this.initialSync = (async () => {
+                await previous?.close();
+                if (this.accessKey !== key)
+                    throw new AgentMcpError('AUTH_CHANGED', 'Graph account changed during synchronization. Retry with the current account.');
+                if (next) {
+                    await next.start();
+                    await next.waitForSync();
+                    if (this.accessKey !== key)
+                        throw new AgentMcpError('AUTH_CHANGED', 'Graph account changed during synchronization. Retry with the current account.');
+                }
+            })();
+        }
+        const initialization = this.initialSync;
+        try {
+            await initialization;
+        }
+        catch (error) {
+            // An initialization failure must not poison this account for the lifetime
+            // of the MCP process. Concurrent callers share the same rejected promise,
+            // but only the owner of that promise clears it and closes the failed sync.
+            if (this.accessKey === key && this.initialSync === initialization) {
+                const failedSync = this.sync;
+                this.accessKey = undefined;
+                this.initialSync = undefined;
+                this.sync = undefined;
+                await failedSync?.close().catch(() => { });
+            }
+            throw error;
+        }
+        if (this.accessKey !== key)
+            throw new AgentMcpError('AUTH_CHANGED', 'Graph account changed during synchronization. Retry with the current account.');
+        if (!this.options.graphAccess) {
+            const current = await (this.options.authStatus ?? getAuthStatus)();
+            if (!current.signedIn || current.subject !== access.subject)
+                throw new AgentMcpError('AUTH_CHANGED', 'Account changed during graph synchronization. Retry with the current account.');
+        }
+        return access;
+    }
+    /** Graph storage is account-owned. Verify identity again after filesystem awaits
+     * and before releasing any graph data to an MCP caller. */
+    async assertGraphIdentity(access) {
+        if (this.options.graphAccess)
+            return;
+        const current = await (this.options.authStatus ?? getAuthStatus)();
+        if (!current.signedIn || current.subject !== access.subject)
+            throw new AgentMcpError('AUTH_CHANGED', 'Account changed while reading graph storage. Retry with the current account.');
+    }
+    obtainDraft(id, access) {
+        const now = Date.now();
+        for (const [key, draft] of this.drafts)
+            if (now - draft.touched > 60 * 60_000 && !draft.publishing)
+                this.drafts.delete(key);
+        const draft = this.drafts.get(id);
+        if (!draft || draft.directory !== access.directory || draft.subject !== access.subject)
+            throw new AgentMcpError('DRAFT_NOT_FOUND', 'Draft not found. Start a new draft with andorra_graph_begin.');
+        if (draft.publishing)
+            throw new AgentMcpError('DRAFT_BUSY', 'Draft is publishing. Retry after the save finishes.');
+        draft.touched = now;
+        return draft;
+    }
+    async providers() {
+        const config = await (this.options.providerConfig ? this.options.providerConfig() : loadConfig(this.directory));
+        return { providers: config.providers.map(({ id, model, type }) => ({ id, model, type })), active: config.provider };
+    }
+    /** Missing graph identity is not a broken graph. Tell the agent to list or create it. */
+    async readGraph(id, directory, revision) {
+        try {
+            return await loadGraph(id, revision, directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new AgentMcpError('GRAPH_NOT_FOUND', 'Graph "' + id + '"' + (revision === undefined ? '' : ' revision ' + revision)
+                    + ' was not found. Use andorra_graphs_list to choose an existing ID, or andorra_graph_begin mode=create to create it.');
+            throw error;
+        }
+    }
+    upsertNode(draft, value, providerIds) {
+        if (!record(value) || !safeId(value.id) || typeof value.name !== 'string' || !value.name.trim()
+            || !knownTypes.includes(String(value.type)))
+            throw new AgentMcpError('NODE_INVALID', 'Node requires a safe id, nonempty name and one of: ' + knownTypes.join(', ') + '.');
+        const node = structuredClone(value);
+        if (node.type === 'agent') {
+            if (!node.provider)
+                throw new AgentMcpError('NODE_PROVIDER_MISSING', 'Node ' + node.id + ': Provider not set. Please select a valid provider.', { nodeId: node.id });
+            if (!providerIds.includes(node.provider))
+                throw new AgentMcpError('NODE_PROVIDER_INVALID', 'Node ' + node.id + ': Provider "' + node.provider + '" is invalid. Please select a valid provider.', { nodeId: node.id });
+        }
+        const proposedNodes = { ...draft.graph.nodes, [node.id]: node };
+        const hasOrchestrator = draft.graph.schemaVersion === 3
+            && Object.values(proposedNodes).some(item => item.type === 'agent' && item.agentRole === 'orchestrator');
+        if (Object.keys(proposedNodes).length > (hasOrchestrator ? 101 : 100))
+            throw new AgentMcpError('NODE_LIMIT', 'A graph supports at most 100 nodes plus one version-3 Orchestrator. Remove a node before adding another.');
+        draft.graph.nodes[node.id] = node;
+        if (node.type === 'agent')
+            draft.authoredAgents.add(node.id);
+        else
+            draft.authoredAgents.delete(node.id);
+        return { node, nodeCount: Object.keys(draft.graph.nodes).length };
+    }
+    upsertEdge(draft, value) {
+        if (!record(value) || !safeId(value.source) || !safeId(value.target))
+            throw new AgentMcpError('EDGE_INVALID', 'Edge requires safe source and target node IDs.');
+        const source = draft.graph.nodes[value.source];
+        const target = draft.graph.nodes[value.target];
+        if (!source)
+            throw new AgentMcpError('EDGE_SOURCE_MISSING', 'Source node ' + value.source + ' does not exist.', { nodeId: value.source });
+        if (!target)
+            throw new AgentMcpError('EDGE_TARGET_MISSING', 'Target node ' + value.target + ' does not exist.', { nodeId: value.target });
+        const ports = nodeOutcomes(source);
+        const outcome = value.outcome === undefined ? ports.length === 1 ? ports[0] : undefined : value.outcome;
+        if (typeof outcome !== 'string' || !ports.includes(outcome))
+            throw new AgentMcpError('EDGE_OUTCOME_INVALID', 'Node ' + source.id + ': specify a valid outcome (' + ports.join(', ') + ').', { nodeId: source.id, port: typeof outcome === 'string' ? outcome : undefined });
+        const id = value.id === undefined ? randomUUID() : value.id;
+        if (!safeId(id))
+            throw new AgentMcpError('EDGE_INVALID', 'Edge id must be a safe identifier.');
+        const edge = structuredClone({ ...value, id, outcome });
+        if (draft.graph.edges.some(other => other.id !== id && other.source === edge.source
+            && (other.outcome ?? 'completed') === edge.outcome && other.target === edge.target))
+            throw new AgentMcpError('EDGE_DUPLICATE', 'Duplicate route from ' + edge.source + ' (' + edge.outcome + ') to ' + edge.target + '.', { nodeId: edge.source, port: edge.outcome, edgeId: id });
+        const index = draft.graph.edges.findIndex(item => item.id === id);
+        if (index < 0)
+            draft.graph.edges.push(edge);
+        else
+            draft.graph.edges[index] = edge;
+        return { edge, edgeCount: draft.graph.edges.length };
+    }
+    async call(name, rawArgs = {}) {
+        try {
+            return { ok: true, data: await this.dispatch(name, argsRecord(rawArgs)) };
+        }
+        catch (error) {
+            if (error instanceof GraphConflictError)
+                return { ok: false, error: { code: 'REVISION_CONFLICT',
+                        message: error.message + ' Reopen the latest graph with andorra_graph_begin mode=edit, reapply your edits, then publish.' } };
+            if (error instanceof SessionQueryError)
+                return { ok: false, error: { code: error.code, message: error.message } };
+            if (error instanceof FreeTierLimitError)
+                return { ok: false, error: { code: error.code, message: error.message } };
+            if (error instanceof PaidMembershipRequiredError) {
+                const status = await getAuthStatus().catch(() => undefined);
+                return { ok: false, error: status?.signedIn
+                        ? { code: 'MEMBERSHIP_REQUIRED', message: 'Graph access requires a paid Andorra membership. Check the active account, subscription and connectivity.' }
+                        : { code: 'AUTH_REQUIRED', message: 'Sign in to Andorra Code and verify your paid membership before editing graphs.' } };
+            }
+            if (error instanceof AgentMcpError) {
+                return { ok: false, error: { code: error.code, message: error.message,
+                        ...error.info } };
+            }
+            // These failures can come from non-graph MCP tools (project/session/provider
+            // discovery). Only graphIssues should label a validation exception GRAPH_INVALID.
+            return { ok: false, error: backendIssue(error) };
+        }
+    }
+    async dispatch(name, args) {
+        if (name === 'andorra_graph_guide')
+            return { architecture: GRAPH_AGENT_GUIDE, resourceUri: 'andorra://graph/architecture' };
+        if (name === 'andorra_projects_list')
+            return { projects: await listAgentProjects(this.directory) };
+        if (name === 'andorra_sessions_list')
+            return await queryAgentSessions(this.directory, args);
+        if (name === 'andorra_sessions_attention') {
+            const query = { ...args };
+            if (args.status !== undefined)
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'andorra_sessions_attention does not take status; it returns all sessions needing attention.');
+            // One locked snapshot and crash index for the entire paged scan. A
+            // concurrent query's pruning cannot change what later pages report.
+            const { sessions, truncated } = await scanAgentSessions(this.directory, query, {
+                ...(this.options.sessionStore === undefined ? {} : { store: this.options.sessionStore }),
+                pageSize: 100, maxSessions: 500,
+                include: session => ['required_input', 'incomplete'].includes(session.status),
+            });
+            return { sessions: sessions.slice(0, 500), truncated,
+                note: 'required_input denotes human input or approval. incomplete denotes stopped work that may need review.' };
+        }
+        if (name === 'andorra_session_get') {
+            const id = field(args, 'sessionId');
+            const limit = args.historyLimit === undefined ? 5 : args.historyLimit;
+            const offset = args.historyOffset === undefined ? 0 : args.historyOffset;
+            if (typeof limit !== 'number' || typeof offset !== 'number')
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'historyLimit and historyOffset must be integers.');
+            return getAgentSession(this.directory, id, limit, offset);
+        }
+        if (name === 'andorra_providers_list')
+            return this.providers();
+        // Subagent runs need no account or membership: they execute the bundled Software Engineer
+        // harness with a locally configured provider, the same tier as provider discovery.
+        if (name === 'andorra_subagent_start') {
+            const task = field(args, 'prompt');
+            // The prompt is bounded before the open record and the session are created: an accidentally
+            // enormous one would otherwise fill the installation's storage and the model's context.
+            if (task.length > MAX_SUBAGENT_TASK_CHARS) {
+                throw new AgentMcpError('INVALID_ARGUMENTS', `The task must be at most ${MAX_SUBAGENT_TASK_CHARS} characters.`);
+            }
+            const provider = args.provider === undefined ? undefined : field(args, 'provider');
+            const model = args.model === undefined ? undefined : field(args, 'model');
+            if (model !== undefined && provider === undefined)
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'model requires provider. Retry with both provider and model.');
+            const permissions = args.permissions === undefined || args.permissions === 'full-access' ? 'full-access'
+                : args.permissions === 'read-only' ? 'read-only' : undefined;
+            if (permissions === undefined)
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'permissions must be full-access or read-only.');
+            const requested = args.workspace === undefined ? this.options.subagentWorkspace ?? process.cwd() : field(args, 'workspace');
+            let workspace;
+            try {
+                workspace = await canonicalWorkspace(requested);
+            }
+            catch (error) {
+                throw new AgentMcpError('INVALID_ARGUMENTS', error instanceof Error ? error.message : String(error));
+            }
+            try {
+                // The startup recovery finishes first: a start must not land beside a crashed attempt that
+                // still claims to be live.
+                await this.recovery;
+                // The connection may have closed while this call was preparing. A run that begins now
+                // would outlive the connection that asked for it.
+                if (this.closed)
+                    throw new AgentMcpError('INVALID_ARGUMENTS', 'The connection to Andorra closed before the run started.');
+                this.starting += 1;
+                try {
+                    return await this.subagent.start({
+                        task, workspace, permissions,
+                        ...(provider === undefined ? {} : { provider }),
+                        ...(model === undefined ? {} : { model }),
+                        ...(this.options.subagentAdapterFactory === undefined ? {} : { adapterFactory: this.options.subagentAdapterFactory }),
+                    });
+                }
+                finally {
+                    this.starting -= 1;
+                }
+            }
+            catch (error) {
+                if (error instanceof SubagentProviderNotSetError)
+                    throw new AgentMcpError('PROVIDER_NOT_SET', error.message, { providers: error.providers });
+                // The caller's own choice was wrong, and it can read that: a generic backend error
+                // would leave it guessing which identifier to correct.
+                if (error instanceof SubagentSelectionError)
+                    throw new AgentMcpError('INVALID_ARGUMENTS', error.message);
+                // A value the run itself refuses — a permission outside the two modes, a model id longer
+                // than the configured ones may be — is the caller's own mistake, and the code says so.
+                if (error instanceof SubagentInvalidArgumentError)
+                    throw new AgentMcpError('INVALID_ARGUMENTS', error.message);
+                if (error instanceof SubagentRunInProgressError)
+                    throw new AgentMcpError('RUN_IN_PROGRESS', error.message);
+                throw error;
+            }
+        }
+        if (name === 'andorra_subagent_status') {
+            this.assertSubagentRun(args.runId);
+            return this.subagent.status();
+        }
+        if (name === 'andorra_subagent_result') {
+            const waitMs = args.waitMs === undefined ? 0 : args.waitMs;
+            if (typeof waitMs !== 'number' || !Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 60_000)
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'waitMs must be an integer from 0 to 60000 milliseconds.');
+            this.assertSubagentRun(args.runId);
+            if (this.subagent.status().state === 'idle')
+                throw new AgentMcpError('NO_RUN', 'No subagent run has been started in this process. Call andorra_subagent_start first.');
+            const outcome = await this.subagent.result(waitMs);
+            // The id the caller asked about, not the one the process holds now: a run that started while
+            // this one was being awaited would label this answer with the wrong run.
+            return { ...outcome, runId: args.runId };
+        }
+        if (name === 'andorra_subagent_cancel') {
+            this.assertSubagentRun(args.runId);
+            const cancelled = this.subagent.cancel();
+            return cancelled ? { cancelled: true } : { cancelled: false, note: 'No subagent run is active in this process.' };
+        }
+        const access = await this.graphAccess();
+        if (name === 'andorra_graphs_list') {
+            const graphs = await listGraphs(access.directory);
+            await this.assertGraphIdentity(access);
+            return { graphs: graphs.map(graph => ({
+                    id: graph.id, name: graph.name, revision: graph.revision, entry: graph.entry, nodes: Object.keys(graph.nodes).length,
+                    edges: graph.edges.length, description: graph.metadata?.description ?? '',
+                })), sync: this.sync?.status ?? null };
+        }
+        if (name === 'andorra_graph_get') {
+            const revision = args.revision;
+            if (revision !== undefined && (!Number.isSafeInteger(revision) || typeof revision !== 'number' || revision < 1))
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'revision must be a positive safe integer when supplied.');
+            const graph = await this.readGraph(field(args, 'id'), access.directory, revision);
+            // Read tools return the exact published revision, not an editor migration.
+            // Recheck account identity *after* the awaited account-owned filesystem read.
+            await this.assertGraphIdentity(access);
+            return { graph };
+        }
+        if (name === 'andorra_graph_begin') {
+            const mode = field(args, 'mode');
+            const id = field(args, 'id');
+            if (!safeId(id))
+                throw new AgentMcpError('INVALID_GRAPH_ID', 'Graph id must be a safe identifier of 1-80 characters.');
+            if (id === 'default')
+                throw new AgentMcpError('BUNDLED_GRAPH', 'The bundled Default graph cannot be modified. Duplicate it under a new ID first.');
+            for (const [key, draft] of this.drafts)
+                if (Date.now() - draft.touched > 60 * 60_000 && !draft.publishing)
+                    this.drafts.delete(key);
+            if (this.drafts.size >= 24)
+                throw new AgentMcpError('DRAFT_LIMIT', 'Too many drafts open. Discard an unused draft first.');
+            let graph;
+            let expectedRevision;
+            if (mode === 'edit') {
+                graph = migrateGraphForEditor(await this.readGraph(id, access.directory), { addOrchestrator: !access.free });
+                expectedRevision = graph.revision;
+            }
+            else if (mode === 'create') {
+                if (id === 'default')
+                    throw new AgentMcpError('BUNDLED_GRAPH', 'The bundled Default graph cannot be overwritten; choose another id.');
+                const nameValue = field(args, 'name');
+                try {
+                    await loadGraph(id, undefined, access.directory);
+                    throw new AgentMcpError('GRAPH_EXISTS', 'Graph ' + id + ' already exists. Use mode=edit to change the latest revision.');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                // A free account at its graph limit learns so before it builds a draft it cannot publish.
+                if (access.free && (await readGraphQuota(access.directory)).customGraphs >= FREE_CUSTOM_GRAPH_LIMIT)
+                    throw new FreeTierLimitError(FREE_GRAPH_LIMIT_MESSAGE);
+                graph = { schemaVersion: 3, id, name: nameValue, revision: 0, entry: '', nodes: {}, edges: [] };
+                expectedRevision = null;
+            }
+            else
+                throw new AgentMcpError('INVALID_ARGUMENTS', 'mode must be create or edit.');
+            // Edit/create reads account-owned graph data too. A user who signs out
+            // during these awaits may not retain a draft containing that graph.
+            await this.assertGraphIdentity(access);
+            // Awaited graph reads can finish concurrently. Recheck immediately before
+            // insertion (no await between check and set) to enforce the 24-draft cap.
+            for (const [expiredId, draft] of this.drafts)
+                if (Date.now() - draft.touched > 60 * 60_000 && !draft.publishing)
+                    this.drafts.delete(expiredId);
+            if (this.drafts.size >= 24)
+                throw new AgentMcpError('DRAFT_LIMIT', 'Too many drafts open. Discard an unused draft first.');
+            const key = randomUUID();
+            this.drafts.set(key, { graph, expectedRevision, directory: access.directory, subject: access.subject,
+                publishing: false, touched: Date.now(), authoredAgents: new Set() });
+            return { draftId: key, graph, expectedRevision, note: 'This draft is local to this MCP process until published.' };
+        }
+        if (name === 'andorra_graph_discard') {
+            const key = draftId(args);
+            this.obtainDraft(key, access);
+            this.drafts.delete(key);
+            return { discarded: true };
+        }
+        const draft = this.obtainDraft(draftId(args), access);
+        // Publishing becomes exclusive before the first async provider read. Concurrent mutation
+        // requests must never edit a draft while a snapshot is being validated or saved.
+        const publishing = name === 'andorra_graph_publish';
+        if (publishing)
+            draft.publishing = true;
+        try {
+            if (name === 'andorra_graph_node_upsert') {
+                const profiles = await this.providers();
+                // Recheck after the await: the draft may have been discarded or entered
+                // publication while provider config was loading.
+                const current = this.obtainDraft(draftId(args), access);
+                return this.upsertNode(current, args.node, profiles.providers.map(item => item.id));
+            }
+            if (name === 'andorra_graph_node_patch') {
+                const id = field(args, 'nodeId');
+                if (!record(args.patch) || Object.keys(args.patch).some(key => key === 'id' || key === 'type'))
+                    throw new AgentMcpError('INVALID_ARGUMENTS', 'patch must be a node settings object without id or type.');
+                const profiles = await this.providers();
+                // Always reread the node after the asynchronous provider lookup. Two
+                // concurrently submitted patches then each merge with the latest node,
+                // preserving unrelated fields instead of overwriting a stale snapshot.
+                const currentDraft = this.obtainDraft(draftId(args), access);
+                const currentNode = currentDraft.graph.nodes[id];
+                if (!currentNode)
+                    throw new AgentMcpError('NODE_NOT_FOUND', 'Node ' + id + ' does not exist.', { nodeId: id });
+                return this.upsertNode(currentDraft, { ...currentNode, ...args.patch }, profiles.providers.map(item => item.id));
+            }
+            if (name === 'andorra_graph_node_remove') {
+                const id = field(args, 'nodeId');
+                if (!Object.hasOwn(draft.graph.nodes, id))
+                    throw new AgentMcpError('NODE_NOT_FOUND', 'Node ' + id + ' does not exist.', { nodeId: id });
+                if (id === draft.graph.entry)
+                    throw new AgentMcpError('ENTRY_NODE', 'Node ' + id + ' is the entry. Select another entry with andorra_graph_patch before removing it.', { nodeId: id });
+                delete draft.graph.nodes[id];
+                draft.authoredAgents.delete(id);
+                const before = draft.graph.edges.length;
+                draft.graph.edges = draft.graph.edges.filter(edge => edge.source !== id && edge.target !== id);
+                return { removedNodeId: id, removedEdges: before - draft.graph.edges.length };
+            }
+            if (name === 'andorra_graph_edge_upsert')
+                return this.upsertEdge(draft, args.edge);
+            if (name === 'andorra_graph_edge_remove') {
+                const id = field(args, 'edgeId');
+                const index = draft.graph.edges.findIndex(edge => edge.id === id);
+                if (index < 0)
+                    throw new AgentMcpError('EDGE_NOT_FOUND', 'Edge ' + id + ' does not exist.', { edgeId: id });
+                draft.graph.edges.splice(index, 1);
+                return { removedEdgeId: id };
+            }
+            if (name === 'andorra_graph_patch') {
+                if (!record(args.patch) || Object.keys(args.patch).some(key => !['name', 'entry', 'limits', 'metadata', 'widgets', 'inputSchema', 'stateSchema'].includes(key)))
+                    throw new AgentMcpError('INVALID_ARGUMENTS', 'Graph patch permits only name, entry, limits, metadata, widgets, inputSchema, stateSchema.');
+                const patch = structuredClone(args.patch);
+                if (patch.entry !== undefined && (!safeId(patch.entry) || !Object.hasOwn(draft.graph.nodes, patch.entry)))
+                    throw new AgentMcpError('ENTRY_NOT_FOUND', 'entry must be the id of an existing node.');
+                Object.assign(draft.graph, patch);
+                return { graphId: draft.graph.id, entry: draft.graph.entry, name: draft.graph.name };
+            }
+            if (name === 'andorra_graph_validate' || name === 'andorra_graph_publish') {
+                const profiles = await this.providers();
+                const issues = graphIssues(draft.graph, profiles.providers, profiles.active, draft.authoredAgents);
+                if (name === 'andorra_graph_validate')
+                    return { valid: issues.length === 0, issues };
+                if (issues.length)
+                    throw new AgentMcpError(issues[0].code, issues[0].message, { nodeId: issues[0].nodeId, port: issues[0].port, edgeId: issues[0].edgeId, issues });
+                if (Buffer.byteLength(JSON.stringify(draft.graph)) > 512 * 1024)
+                    throw new AgentMcpError('GRAPH_TOO_LARGE', 'Graph exceeds 512 KiB. Reduce prompt or schema size before publishing.');
+                // Refresh the account-scoped graph snapshots before the compare-and-swap. A remote
+                // editor may have published after the draft began; this lets its latest revision
+                // participate in the same local CAS that protects two editors on one machine.
+                await this.sync?.sync();
+                // Provider configuration can be edited by another process during a network
+                // sync. Validate again against the *current* provider list before publishing.
+                if (this.drafts.get(draftId(args)) !== draft)
+                    throw new AgentMcpError('DRAFT_NOT_FOUND', 'Draft was closed during synchronization. Start a new graph draft.');
+                // An account switch can also happen during a long pre-publish cloud sync.
+                // Rebind entitlement before touching the immutable revision on disk.
+                const freshAccess = await this.graphAccess();
+                if (freshAccess.directory !== access.directory || freshAccess.subject !== access.subject)
+                    throw new AgentMcpError('AUTH_CHANGED', 'Account changed during graph synchronization. Reopen the draft for the current account.');
+                if (this.drafts.get(draftId(args)) !== draft)
+                    throw new AgentMcpError('DRAFT_NOT_FOUND', 'Draft was closed during synchronization. Start a new graph draft.');
+                const latestProfiles = await this.providers();
+                // Reloading provider config is asynchronous; another process can switch
+                // accounts during that read. Recheck immediately before the local save.
+                const finalAccess = await this.graphAccess();
+                if (finalAccess.directory !== access.directory || finalAccess.subject !== access.subject)
+                    throw new AgentMcpError('AUTH_CHANGED', 'Account changed while verifying providers. Retry with the current account.');
+                if (this.drafts.get(draftId(args)) !== draft)
+                    throw new AgentMcpError('DRAFT_NOT_FOUND', 'Draft was closed while verifying providers. Start a new graph draft.');
+                const currentIssues = graphIssues(draft.graph, latestProfiles.providers, latestProfiles.active, draft.authoredAgents);
+                if (currentIssues.length)
+                    throw new AgentMcpError(currentIssues[0].code, currentIssues[0].message, { nodeId: currentIssues[0].nodeId, port: currentIssues[0].port,
+                        edgeId: currentIssues[0].edgeId, issues: currentIssues });
+                const normalized = validateGraph(draft.graph, { providers: latestProfiles.providers,
+                    defaultProvider: latestProfiles.active, spawnAvailable: true });
+                // Stamping can add profile entries after the submitted graph already passed the size checks.
+                const stamped = stampGraphProviderProfiles(normalized, latestProfiles);
+                if (Buffer.byteLength(JSON.stringify(stamped)) > 512 * 1024)
+                    throw new AgentMcpError('VALIDATION_FAILED', 'Graph exceeds 512 KiB after portable provider identities are recorded.');
+                const saved = finalAccess.free ? await saveFreeTierGraph(stamped, draft.expectedRevision, access.directory)
+                    : await saveGraph(stamped, draft.expectedRevision, access.directory);
+                draft.graph = saved;
+                draft.expectedRevision = saved.revision;
+                void this.sync?.sync();
+                return { graph: saved, revision: saved.revision, sync: this.sync?.status ?? null,
+                    note: 'Revision saved locally. Cloud synchronization may still be pending.' };
+            }
+            throw new AgentMcpError('UNKNOWN_TOOL', 'Unknown tool "' + name + '". Retrieve tools/list for supported operations.');
+        }
+        finally {
+            if (publishing)
+                draft.publishing = false;
+        }
+    }
+}
+const obj = (properties, required = []) => ({ type: 'object',
+    properties, required, additionalProperties: false });
+const str = { type: 'string' };
+const num = { type: 'integer', minimum: 0 };
+const graphDraftSchema = { draftId: str };
+const graphReference = { draftId: str, nodeId: str };
+const searchFilters = { projectName: str, projectPath: str,
+    lookbackMinutes: num, updatedAfter: str, updatedBefore: str, includeArchived: { type: 'boolean' } };
+const catalog = [
+    { name: 'andorra_graph_guide', description: 'Read Andorra graph architecture, node types, outcome routes, loops and save error contracts.', inputSchema: obj({}) },
+    { name: 'andorra_providers_list', description: 'List valid graph provider IDs and models without credentials.', inputSchema: obj({}) },
+    { name: 'andorra_graphs_list', description: 'List available graphs, names and revisions.', inputSchema: obj({}) },
+    { name: 'andorra_graph_get', description: 'Read one published graph, optionally by revision.', inputSchema: obj({ id: str, revision: { type: 'integer', minimum: 1 } }, ['id']) },
+    { name: 'andorra_graph_begin', description: 'Open an ephemeral graph draft. mode=create needs a new id and name; mode=edit opens latest.', inputSchema: obj({ mode: { type: 'string', enum: ['create', 'edit'] }, id: str, name: str }, ['mode', 'id']) },
+    { name: 'andorra_graph_node_upsert', description: 'Create or replace a node in a draft. Agent nodes require a configured provider ID.', inputSchema: obj({ draftId: str, node: { type: 'object' } }, ['draftId', 'node']) },
+    { name: 'andorra_graph_node_patch', description: 'Change an existing node prompt, instruction, model, provider, completion, etc. without replacing other fields.', inputSchema: obj({ ...graphReference, patch: { type: 'object' } }, ['draftId', 'nodeId', 'patch']) },
+    { name: 'andorra_graph_node_remove', description: 'Remove a non-entry node and its incident edges from a draft.', inputSchema: obj(graphReference, ['draftId', 'nodeId']) },
+    { name: 'andorra_graph_edge_upsert', description: 'Create or replace an edge. Outcome must match a source node port (pass/fail, true/false, body/done...).', inputSchema: obj({ draftId: str, edge: { type: 'object' } }, ['draftId', 'edge']) },
+    { name: 'andorra_graph_edge_remove', description: 'Remove an edge by ID from a draft.', inputSchema: obj({ ...graphDraftSchema, edgeId: str }, ['draftId', 'edgeId']) },
+    { name: 'andorra_graph_patch', description: 'Set graph entry, name, limits, schemas, widgets or metadata in a draft.', inputSchema: obj({ draftId: str, patch: { type: 'object' } }, ['draftId', 'patch']) },
+    { name: 'andorra_graph_validate', description: 'Validate a draft; report all missing provider and outcome paths, plus graph topology issues.', inputSchema: obj(graphDraftSchema, ['draftId']) },
+    { name: 'andorra_graph_publish', description: 'Validate and atomically publish the next immutable graph revision; optimistic concurrency guards other editors.', inputSchema: obj(graphDraftSchema, ['draftId']) },
+    { name: 'andorra_graph_discard', description: 'Discard an unpublished local graph draft.', inputSchema: obj(graphDraftSchema, ['draftId']) },
+    { name: 'andorra_projects_list', description: 'List registered projects and discovered session workspaces.', inputSchema: obj({}) },
+    { name: 'andorra_sessions_list', description: 'Search sessions by project, status and last X minutes (lookbackMinutes). Supports paginated results.', inputSchema: obj({ ...searchFilters, status: { type: 'string', enum: ['completed', 'pending', 'running', 'required_input', 'incomplete'] },
+            offset: num, limit: { type: 'integer', minimum: 1, maximum: 100 } }) },
+    { name: 'andorra_session_get', description: 'Read session metadata and up to 20 recent turn excerpts; no filesystem access.', inputSchema: obj({ sessionId: str,
+            historyLimit: { type: 'integer', minimum: 0, maximum: 20 }, historyOffset: num }, ['sessionId']) },
+    { name: 'andorra_sessions_attention', description: 'Find sessions requiring human feedback or review: required_input and incomplete; supports project and time filters.', inputSchema: obj(searchFilters) },
+    { name: 'andorra_subagent_start', description: 'Run the bundled Software Engineer graph once as an Andorra subagent. Requires a provider/model: pass provider and model, or the saved /subagent setting. On PROVIDER_NOT_SET, show the listed providers and models to your user, ask which to use, then retry with provider and model. Writes are allowed unless permissions is read-only.', inputSchema: obj({ prompt: str, provider: str, model: str, permissions: { type: 'string', enum: ['full-access', 'read-only'] }, workspace: str }, ['prompt']) },
+    { name: 'andorra_subagent_status', description: 'Poll the subagent run: state, current node and recent events. The runId must be the one the start returned, so the answer is about that run.', inputSchema: obj({ runId: str }, ['runId']) },
+    { name: 'andorra_subagent_result', description: 'Read the subagent run outcome. waitMs (0-60000) waits for completion within the call; otherwise returns running immediately when unfinished. The finished reply carries the full run result including completion summary and status. The runId must be the one the start returned.', inputSchema: obj({ waitMs: { type: 'integer', minimum: 0, maximum: 60000 }, runId: str }, ['runId']) },
+    { name: 'andorra_subagent_cancel', description: 'Cancel the subagent run. The runId must be the one the start returned, so a delayed cancellation cannot stop a run that replaced it.', inputSchema: obj({ runId: str }, ['runId']) },
+];
+export async function runAgentMcpServer() {
+    const backend = new AgentMcpBackend();
+    const server = new Server({ name: 'andorra-code-agent-control', version: '1.0.0' }, { capabilities: { tools: {}, resources: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: catalog }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const reply = await backend.call(request.params.name, request.params.arguments ?? {});
+        return { isError: !reply.ok, content: [{ type: 'text', text: JSON.stringify(reply) }] };
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [{ uri: 'andorra://graph/architecture', name: 'Andorra Graph Architecture',
+                description: 'Node, edge, loop, prompt/provider and error contracts for agent-authored graphs.',
+                mimeType: 'text/markdown' }],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        if (request.params.uri !== 'andorra://graph/architecture')
+            throw new Error('Unknown resource');
+        return { contents: [{ uri: request.params.uri, mimeType: 'text/markdown', text: GRAPH_AGENT_GUIDE }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    await new Promise(resolve => { process.stdin.once('end', resolve); });
+    await server.close();
+    await backend.close();
+    return 0;
+}