@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/mcp/service.d.ts

@@ -0,0 +1,160 @@
+import type { SecretStore } from "../accounts/secrets.js";
+import type { Bus } from "../core/bus.js";
+import type { HarnessEnv } from "../core/env.js";
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { CallerContext } from "../core/caller.js";
+import type { ToolPolicy } from "../sessions/policy.js";
+import type { RunRegistry } from "../sessions/registry.js";
+import type { SessionBroker } from "../sessions/sessions.js";
+import type { ToolSession, ToolSpec } from "../tools/types.js";
+import { Connections } from "./connections.js";
+import type { AppOAuthClients, Connection, McpTrace } from "./types.js";
+/** A session's access to the broker. A terminal session presents `token`; an SDK session holds the object. */
+export interface BrokerSession {
+    token: string;
+    sessionId: string;
+    runId: string | null;
+    caller: CallerContext;
+    /** Only reads are permitted. */
+    readOnly: boolean;
+    depth: number;
+    /** The run's immutable tool and connector set. */
+    capabilities?: CapabilitySet;
+}
+export interface BrokerTool {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/** Tools the embedding application offers through the broker, beside connected apps. */
+export interface BrokeredTools {
+    list(session: BrokerSession): Promise<BrokerTool[]>;
+    has(name: string): boolean;
+    /** The tool's result as the application returns it: text, `{ text, image? }`, or structured data. */
+    call(session: BrokerSession, name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Changes whenever the offered tools may have changed. */
+    revision?(session: BrokerSession): Promise<unknown>;
+    /** A sentence added to the discovery tool's description, e.g. where the application lists the rest of its tools. */
+    discoveryNote?: string;
+}
+interface ListedTool extends BrokerTool {
+    connectionId: string;
+    tool: string;
+    origin?: 'app';
+}
+/**
+ * A tool listing a model can scan: a name and one line each. Input schemas are the bulk of a
+ * discovery reply, so they come back for one named tool at a time.
+ */
+export declare function compactTools<T extends BrokerTool>(tools: readonly T[], tool?: string): Array<Omit<T, 'inputSchema'> | T>;
+/** Most tools one listing returns. A server with hundreds of tools would otherwise make every discovery call a very large input. */
+export declare const TOOL_PAGE = 40;
+/**
+ * One page of a tool listing: names and summaries only, optionally filtered by a
+ * case-insensitive `query` over name and description. `more` and `nextOffset` appear when
+ * entries remain.
+ */
+export declare function pageTools<T extends BrokerTool>(tools: readonly T[], options?: {
+    query?: string;
+    offset?: number;
+    limit?: number;
+}): {
+    more?: number | undefined;
+    nextOffset?: number | undefined;
+    tools: (T | Omit<T, "inputSchema">)[];
+    total: number;
+};
+export interface ConnectedAppsOptions {
+    env: HarnessEnv;
+    stateDir: string;
+    secrets: SecretStore;
+    bus: Bus;
+    runs: RunRegistry;
+    policy: ToolPolicy;
+    /** The application's own registered OAuth clients, if it has any. */
+    oauthClients?: AppOAuthClients;
+}
+export declare class ConnectedApps implements SessionBroker {
+    private readonly options;
+    readonly toolNames: readonly ["mcp_list_tools", "mcp_call_tool"];
+    readonly connections: Connections;
+    private readonly manager;
+    private readonly oauth;
+    private readonly grants;
+    private readonly proposals;
+    private readonly calls;
+    private brokered;
+    constructor(options: ConnectedAppsOptions);
+    /** Loads what is needed to redact results. Call once before sessions start. */
+    start(): Promise<void>;
+    /** Lets the application offer its own tools through `mcp_list_tools` and `mcp_call_tool`. */
+    expose(tools: BrokeredTools): void;
+    /** Gives a session access to the broker. The token is what a process outside the harness presents. */
+    grant(input: Omit<BrokerSession, 'token'>): BrokerSession;
+    session(token: string): BrokerSession;
+    revokeSession(sessionId: string): void;
+    /** A run ended: its grants, previews, and open client sessions go with it. */
+    revokeRun(runId: string, sessionId: string): void;
+    private activeRun;
+    private valid;
+    private reachable;
+    /** A diagnostic lists only the selected server; it never calls a connector tool. */
+    diagnosticList(session: BrokerSession, connectionId: string, signal: AbortSignal): Promise<number>;
+    /** The application's tools and every reachable connection's tools, with the connections that could not be read. */
+    list(session: BrokerSession): Promise<{
+        tools: ListedTool[];
+        errors: {
+            connection: string;
+            message: string;
+        }[];
+    }>;
+    private connectionFailed;
+    /** Runs one tool by the name `list` gave it. */
+    invoke(session: BrokerSession, alias: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Checks scope, asks for approval when the call is not a read, and returns how to reach the connection. */
+    private authorize;
+    /** Records what an authorized call returned: a redacted trace with its sources, and the tool's outcome. */
+    private completed;
+    /** What a run retrieved from connected apps, in order. */
+    runContext(runId: string): McpTrace[];
+    /** Changes whenever what a session can discover may have changed. */
+    revision(session: BrokerSession): Promise<unknown>;
+    tools(session: ToolSession, options: {
+        readOnly: boolean;
+    }): ToolSpec[];
+    /** `mcp_list_tools` and `mcp_call_tool` bound to a granted session. */
+    brokerTools(session: BrokerSession): ToolSpec[];
+    save(input: Parameters<Connections['save']>[0]): Promise<Connection>;
+    remove(connectionId: string): Promise<void>;
+    private cancelConnection;
+    /** Connects once and records what the server offers, or why it could not be reached. */
+    test(connectionId: string): Promise<Connection>;
+    /** Signs in with the provider in a browser. Only a person starts this; a session that finds an expired sign-in reports it. */
+    signIn(connectionId: string): Promise<Connection>;
+    /** The catalog entries this application can sign in for, so a client need not be added by hand. */
+    appClients(): {
+        catalogIds: string[];
+    };
+    signOut(connectionId: string): Promise<Connection>;
+    /** Reads one retrieved source again from the Xingular Workspace connection it came from. */
+    refreshSource(runId: string, traceId: string, sourceUri: string): Promise<unknown>;
+    /** Gives one agent exactly these connections, if its creator may reach each of them. */
+    setAgentScope(creator: {
+        agentId?: string | null;
+        projectId?: string | null;
+    }, agentId: string, ids: readonly string[]): Connection[];
+    /**
+     * A call with no session and nobody to ask, made by a plugin's hook. It reaches a connection
+     * only when it is on for everyone, and a tool only when a person marked it to run without asking.
+     */
+    callUnattended(reference: string, tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    /** Switches one saved connection on or off for everyone, one agent, or one project. */
+    attach(connectionId: string, scope: {
+        agentId?: string | null;
+        projectId?: string | null;
+    }, on: boolean): void;
+    /** Forgets an agent that no longer exists. */
+    removeAgentScope(agentId: string): void;
+    close(): Promise<void>;
+}
+export {};

package/dist/sdk/mcp/service.js

@@ -0,0 +1,510 @@
+// Connected apps as sessions use them: which connections a session may reach, the two broker
+// tools every such session gets, approval of anything that is not a read, and a redacted record
+// of what each call returned.
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { newId, now, readJson, writeJson } from "../core/fs.js";
+import { charCount, takeChars } from "../core/text.js";
+import { findRun, runDir } from "../sessions/runStore.js";
+import { allowed, Connections, webUrl } from "./connections.js";
+import { isSignInRequired, McpManager, signInRequired } from "./manager.js";
+import { signIn } from "./oauth.js";
+const TOOL_SUMMARY_CHARS = 160;
+/**
+ * A tool listing a model can scan: a name and one line each. Input schemas are the bulk of a
+ * discovery reply, so they come back for one named tool at a time.
+ */
+export function compactTools(tools, tool) {
+    if (tool)
+        return tools.filter((entry) => entry.name === tool);
+    return tools.map(({ inputSchema: _schema, ...entry }) => ({
+        ...entry,
+        ...(entry.description && entry.description.length > TOOL_SUMMARY_CHARS ? { description: `${entry.description.slice(0, TOOL_SUMMARY_CHARS).trimEnd()}…` } : {})
+    }));
+}
+/** Most tools one listing returns. A server with hundreds of tools would otherwise make every discovery call a very large input. */
+export const TOOL_PAGE = 40;
+/**
+ * One page of a tool listing: names and summaries only, optionally filtered by a
+ * case-insensitive `query` over name and description. `more` and `nextOffset` appear when
+ * entries remain.
+ */
+export function pageTools(tools, options = {}) {
+    const query = options.query?.trim().toLowerCase();
+    const matching = query ? tools.filter((tool) => tool.name.toLowerCase().includes(query) || (tool.description ?? '').toLowerCase().includes(query)) : tools;
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const limit = Math.max(1, Math.min(Math.floor(options.limit ?? TOOL_PAGE), 100));
+    const page = compactTools(matching.slice(offset, offset + limit));
+    const next = offset + page.length;
+    return { tools: page, total: matching.length, ...(next < matching.length ? { more: matching.length - next, nextOffset: next } : {}) };
+}
+const WORKSPACE_READS = new Set([
+    'x_workspace_status', 'x_workspace_context', 'x_workspace_search', 'x_workspace_note_list', 'x_workspace_note_read', 'x_workspace_project_list', 'x_workspace_project_get',
+    'x_workspace_task_list', 'x_workspace_task_get', 'x_workspace_milestone_list', 'x_workspace_milestone_get', 'x_workspace_update_list', 'x_workspace_update_get',
+    'x_workspace_meeting_list', 'x_workspace_meeting_get', 'x_workspace_resource_list', 'x_workspace_resource_get', 'x_workspace_resource_preview'
+]);
+/** The scope a plugin hook's connections are opened under: they belong to no session. */
+const UNATTENDED_SCOPE = 'plugin-hooks';
+export class ConnectedApps {
+    options;
+    toolNames = ['mcp_list_tools', 'mcp_call_tool'];
+    connections;
+    manager;
+    oauth;
+    grants = new Map();
+    proposals = new Map();
+    calls = new Map();
+    brokered = null;
+    constructor(options) {
+        this.options = options;
+        this.connections = new Connections(options.stateDir, options.secrets, options.bus, () => options.env.root, options.oauthClients ?? null);
+        this.oauth = {
+            clientName: options.env.productName,
+            load: (id) => this.connections.oauthLoad(id),
+            save: (id, state) => this.connections.oauthSave(id, state),
+            openUrl: (url) => {
+                if (!webUrl(url))
+                    throw invalid('The sign-in page must be an https:// address.');
+                // The application shows the page; the harness never opens a browser by itself.
+                options.bus.emit({ type: 'connections.openUrl', url });
+            }
+        };
+        this.manager = new McpManager(this.oauth);
+    }
+    /** Loads what is needed to redact results. Call once before sessions start. */
+    start() {
+        return this.connections.refreshSecrets();
+    }
+    /** Lets the application offer its own tools through `mcp_list_tools` and `mcp_call_tool`. */
+    expose(tools) {
+        this.brokered = tools;
+    }
+    // ---- Grants -----------------------------------------------------------------------------
+    /** Gives a session access to the broker. The token is what a process outside the harness presents. */
+    grant(input) {
+        const session = { ...input, token: `${newId()}${newId()}` };
+        this.grants.set(session.token, session);
+        return session;
+    }
+    session(token) {
+        const session = this.grants.get(token);
+        if (!session)
+            throw new HarnessError('mcp_unauthorized', 'This MCP session is no longer authorized.');
+        return session;
+    }
+    revokeSession(sessionId) {
+        for (const [token, session] of this.grants)
+            if (session.sessionId === sessionId)
+                this.grants.delete(token);
+        for (const [key, proposal] of this.proposals)
+            if (proposal.sessionId === sessionId)
+                this.proposals.delete(key);
+    }
+    /** A run ended: its grants, previews, and open client sessions go with it. */
+    revokeRun(runId, sessionId) {
+        for (const [token, session] of this.grants)
+            if (session.runId === runId)
+                this.grants.delete(token);
+        for (const [key, proposal] of this.proposals)
+            if (proposal.runId === runId)
+                this.proposals.delete(key);
+        void this.manager.close(undefined, sessionId);
+    }
+    activeRun(session) {
+        const run = (session.runId ? this.options.runs.active(session.runId) : null) ?? this.options.runs.activeForSession(session.sessionId);
+        if (!run)
+            throw new HarnessError('run_not_active', 'The requesting run has ended.');
+        return run;
+    }
+    valid(session) {
+        if (this.grants.get(session.token) !== session)
+            throw new HarnessError('mcp_unauthorized', 'This MCP session is no longer authorized.');
+    }
+    // ---- What a session may reach ---------------------------------------------------------------
+    async reachable(session) {
+        const scoped = this.connections.forScope({ agentId: session.caller.agentId, projectId: session.caller.projectId });
+        const frozen = session.capabilities ? scoped.filter((connection) => session.capabilities.connectors.includes(connection.id)) : scoped;
+        const policy = this.options.policy.connections;
+        // Nothing to narrow: the application is not asked.
+        if (!policy || !frozen.length)
+            return frozen;
+        const ids = await policy({ sessionId: session.sessionId, runId: session.runId, caller: session.caller, connectionIds: frozen.map((connection) => connection.id) });
+        return frozen.filter((connection) => ids.includes(connection.id));
+    }
+    /** A diagnostic lists only the selected server; it never calls a connector tool. */
+    async diagnosticList(session, connectionId, signal) {
+        this.valid(session);
+        const connection = (await this.reachable(session)).find(item => item.id === connectionId);
+        if (!connection)
+            throw new HarnessError('doctor_blocked', 'The selected connector is outside this scope.');
+        signal.throwIfAborted();
+        const cancel = () => { void this.manager.close(connectionId, session.sessionId); };
+        signal.addEventListener('abort', cancel, { once: true });
+        try {
+            const config = await this.connections.launch(connection);
+            const client = await this.manager.client(session.sessionId, config);
+            signal.throwIfAborted();
+            return (await client.listTools({}, { signal, timeout: 15_000 })).tools.length;
+        }
+        finally {
+            signal.removeEventListener('abort', cancel);
+            await this.manager.close(connectionId, session.sessionId);
+        }
+    }
+    /** The application's tools and every reachable connection's tools, with the connections that could not be read. */
+    async list(session) {
+        const own = (await this.brokered?.list(session)) ?? [];
+        const discovered = await Promise.all((await this.reachable(session)).map(async (connection) => {
+            const tools = [];
+            let config = null;
+            try {
+                config = await this.connections.launch(connection);
+                const client = await this.manager.client(session.sessionId, config);
+                for (const tool of (await client.listTools({}, { timeout: 15000 })).tools) {
+                    const alias = `mcp_${createHash('sha256').update(`${connection.id}:${tool.name}`).digest('hex').slice(0, 12)}_${tool.name.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 40)}`;
+                    tools.push({ name: alias, description: `${connection.name}: ${tool.description ?? tool.name}`, inputSchema: tool.inputSchema, connectionId: connection.id, tool: tool.name });
+                }
+                if (client.getServerCapabilities()?.resources) {
+                    for (const operation of ['list', 'read']) {
+                        tools.push({
+                            name: `mcp_${connection.id.replace(/-/g, '').slice(0, 12)}_resources_${operation}`,
+                            description: `${connection.name}: ${operation} MCP resources`,
+                            inputSchema: { type: 'object', properties: operation === 'read' ? { uri: { type: 'string' } } : {}, ...(operation === 'read' ? { required: ['uri'] } : {}) },
+                            connectionId: connection.id,
+                            tool: `resources/${operation}`
+                        });
+                    }
+                }
+                return { tools, errors: [] };
+            }
+            catch (error) {
+                const unauthorized = isSignInRequired(error);
+                const message = unauthorized ? signInRequired(connection).message : `${connection.name} could not load its tools. Check its scope in Capability → Connectors.`;
+                if (unauthorized)
+                    await this.manager.close(connection.id, session.sessionId);
+                this.connectionFailed(connection.id, unauthorized);
+                return { tools: [], errors: [{ connection: connection.name, message }] };
+            }
+        }));
+        return {
+            tools: [...own.map((tool) => ({ ...tool, origin: 'app', connectionId: '__app__', tool: tool.name })), ...discovered.flatMap((entry) => entry.tools)],
+            errors: discovered.flatMap((entry) => entry.errors)
+        };
+    }
+    connectionFailed(connectionId, unauthorized) {
+        try {
+            this.connections.update(connectionId, (item) => {
+                if (item.auth === 'oauth' && unauthorized) {
+                    item.authState = 'expired';
+                    item.error = `${item.name} needs you to sign in again.`;
+                }
+                else if (item.kind === 'remote') {
+                    item.error = `${item.name} could not load its tools. Check its address and sign-in, then test or reconnect.`;
+                }
+                else {
+                    item.error = `${item.name} could not load its tools. Check its executable and arguments, then test or reconnect.`;
+                }
+            });
+            this.connections.changed();
+        }
+        catch {
+            // The connection was removed while it was being read.
+        }
+    }
+    // ---- Calling ------------------------------------------------------------------------------
+    /** Runs one tool by the name `list` gave it. */
+    async invoke(session, alias, args) {
+        if (this.brokered?.has(alias)) {
+            const result = await this.brokered.call(session, alias, args);
+            const output = result;
+            return {
+                content: [{ type: 'text', text: output?.text ?? (typeof result === 'string' ? result : JSON.stringify(result)) }, ...(output?.image ? [{ type: 'image', ...output.image }] : [])],
+                ...(!output?.image && result && typeof result === 'object' ? { structuredContent: Array.isArray(result) ? { result } : result } : {})
+            };
+        }
+        const tool = (await this.list(session)).tools.find((candidate) => candidate.name === alias);
+        if (!tool)
+            throw new HarnessError('mcp_tool_unavailable', 'This MCP tool is unavailable or its connection was disabled.');
+        const toolCallId = randomUUID();
+        const config = await this.authorize(session, tool.connectionId, tool.tool, args, toolCallId);
+        try {
+            const client = await this.manager.client(session.sessionId, config);
+            const result = tool.tool === 'resources/list' ? await client.listResources() : tool.tool === 'resources/read' ? await client.readResource({ uri: String(args.uri) }) : await client.callTool({ name: tool.tool, arguments: args }, { timeout: 60000 });
+            this.completed(toolCallId, tool.tool, { result });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'MCP call failed';
+            this.completed(toolCallId, tool.tool, { error: tool.tool === 'x_workspace_mutation_apply' ? 'Workspace apply did not return a confirmed result. Do not retry automatically; read the affected record to verify its state.' : message });
+            throw error;
+        }
+    }
+    /** Checks scope, asks for approval when the call is not a read, and returns how to reach the connection. */
+    async authorize(session, connectionId, tool, args, toolCallId) {
+        const run = this.activeRun(session);
+        const record = findRun(this.options.env.root, run.runId);
+        if (record) {
+            const scope = await this.options.policy.scope?.({ run: record, caller: session.caller, tool: 'connected_app', args });
+            if (scope && scope.automatic && !scope.allowed)
+                throw new HarnessError('outside_work_scope', scope.reason ?? 'Outside the approved work scope.');
+        }
+        const denied = () => new HarnessError('mcp_access_denied', 'This connection is disabled or unavailable to this agent.');
+        const connection = (await this.reachable(session)).find((item) => item.id === connectionId);
+        if (!connection)
+            throw denied();
+        const workspace = connection.kind === 'workspace';
+        const preview = workspace && tool === 'x_workspace_mutation_preview';
+        const apply = workspace && tool === 'x_workspace_mutation_apply';
+        const isRead = (workspace && WORKSPACE_READS.has(tool)) || (!apply && !preview && connection.readTools.includes(tool));
+        if (session.readOnly && !isRead)
+            throw new HarnessError('mcp_read_only', 'This session only permits reads from connected apps.');
+        let proposal;
+        if (apply) {
+            const approvalToken = typeof args.approvalToken === 'string' ? args.approvalToken : '';
+            const saved = this.proposals.get(approvalToken);
+            this.proposals.delete(approvalToken);
+            if (!saved)
+                throw new HarnessError('mcp_preview_required', 'Create a fresh preview in this run before applying.');
+            if (saved.sessionId !== session.sessionId || saved.runId !== run.runId || saved.connectionId !== connectionId || saved.expiresAt <= now())
+                throw new HarnessError('mcp_preview_required', 'This preview belongs to another run or has expired.');
+            proposal = saved.data;
+        }
+        run.emit('tool.started', { toolCallId, name: tool, summary: connection.name });
+        if (!isRead && !preview) {
+            const action = JSON.stringify(proposal ?? this.connections.scrub(args, connection.id), null, 2);
+            const decision = await run.requestApproval({ requestId: `mcp-${newId()}`, target: connection.name, action: `${tool}\n${action}`, standing: 'switch', timeoutMs: 300_000 });
+            if (decision !== 'approved') {
+                run.emit('tool.completed', { toolCallId, name: tool, ok: false });
+                throw new HarnessError('mcp_denied', 'The user denied the MCP operation or its approval expired.');
+            }
+        }
+        // Access may have been revoked, or the run ended, while the request was waiting.
+        const current = (await this.reachable(session)).find((item) => item.id === connectionId);
+        if (!current)
+            throw new HarnessError('mcp_access_denied', 'Connection access was revoked while waiting.');
+        this.valid(session);
+        this.activeRun(session);
+        this.calls.set(toolCallId, { session, connection: current, runId: run.runId });
+        return this.connections.launch(current);
+    }
+    /** Records what an authorized call returned: a redacted trace with its sources, and the tool's outcome. */
+    completed(toolCallId, tool, outcome) {
+        const call = this.calls.get(toolCallId);
+        if (!call)
+            return;
+        this.calls.delete(toolCallId);
+        const { connection, session, runId } = call;
+        const result = (outcome.result ?? null);
+        const structured = result?.structuredContent;
+        const live = this.grants.get(session.token) === session && this.options.runs.active(runId) !== null;
+        if (tool === 'x_workspace_mutation_preview' && live && typeof structured?.data?.approvalToken === 'string') {
+            this.proposals.set(structured.data.approvalToken, { runId, sessionId: session.sessionId, connectionId: connection.id, data: this.connections.scrub(structured.data, connection.id), expiresAt: typeof structured.data.expiresAt === 'string' ? structured.data.expiresAt : '' });
+        }
+        const ok = outcome.error === undefined && result?.isError !== true;
+        const cleaned = this.connections.scrub(result, connection.id);
+        const raw = outcome.error === undefined ? JSON.stringify(cleaned) : String(this.connections.scrub(outcome.error, connection.id));
+        const found = cleaned?.structuredContent?.sources;
+        const sources = (Array.isArray(found) ? found : [])
+            .flatMap((source) => {
+            if (!source || typeof source.id !== 'string' || typeof source.title !== 'string' || typeof source.uri !== 'string')
+                return [];
+            const value = { id: source.id, title: source.title, uri: source.uri, path: typeof source.path === 'string' ? source.path : null };
+            for (const field of ['revision', 'excerpt', 'projectId'])
+                if (typeof source[field] === 'string')
+                    value[field] = takeChars(source[field], 2000);
+            return [value];
+        })
+            .slice(0, 100);
+        const trace = { id: toolCallId, connectionId: connection.id, connectionName: connection.name, tool, at: now(), ok, summary: tool, result: takeChars(raw, 24000), sources, truncated: charCount(raw) > 24000 || structured?.truncated === true };
+        try {
+            const file = join(runDir(this.options.env.root, runId), 'mcp-context.json');
+            writeJson(file, [...(readJson(file) ?? []), trace]);
+        }
+        catch {
+            // The call happened; a trace that cannot be written does not undo it.
+        }
+        this.options.runs.active(runId)?.emit('tool.completed', { toolCallId, name: tool, ok });
+    }
+    /** What a run retrieved from connected apps, in order. */
+    runContext(runId) {
+        return readJson(join(runDir(this.options.env.root, runId), 'mcp-context.json')) ?? [];
+    }
+    /** Changes whenever what a session can discover may have changed. */
+    async revision(session) {
+        return { connections: this.connections.revision(), tools: (await this.brokered?.revision?.(session)) ?? null };
+    }
+    // ---- The two tools a session gets -------------------------------------------------------------
+    tools(session, options) {
+        const granted = this.grant({ sessionId: session.run.sessionId, runId: session.run.runId, caller: session.caller, readOnly: options.readOnly, depth: session.depth, capabilities: session.capabilities });
+        return this.brokerTools(granted);
+    }
+    /** `mcp_list_tools` and `mcp_call_tool` bound to a granted session. */
+    brokerTools(session) {
+        return [
+            {
+                name: 'mcp_list_tools',
+                label: 'App and connector tools',
+                description: `Discover enabled ${this.options.env.productName} app operations and connector tools by name. Pass tool to get one tool with its input schema.${this.brokered?.discoveryNote ? ` ${this.brokered.discoveryNote}` : ''}`,
+                parameters: (Type) => Type.Object({
+                    tool: Type.Optional(Type.String({ description: 'One tool name, to get its input schema.' })),
+                    query: Type.Optional(Type.String({ description: 'Only tools whose name or description contains this text.' })),
+                    offset: Type.Optional(Type.Integer({ minimum: 0, description: 'Where to continue a long list (nextOffset from the previous page).' }))
+                }),
+                execute: async (input) => {
+                    const listed = await this.list(session);
+                    const wanted = typeof input.tool === 'string' && input.tool ? input.tool : undefined;
+                    if (wanted)
+                        return JSON.stringify({ ...listed, tools: compactTools(listed.tools, wanted) });
+                    const page = pageTools(listed.tools, { query: typeof input.query === 'string' ? input.query : undefined, offset: typeof input.offset === 'number' ? input.offset : undefined });
+                    return JSON.stringify({ ...listed, ...page, note: `Names and summaries only. Call mcp_list_tools with tool for the input schema before the first call to that tool.${page.more ? ' More tools match: pass offset, and query to narrow the list.' : ''}` });
+                }
+            },
+            {
+                name: 'mcp_call_tool',
+                label: 'Use connector',
+                description: 'Invoke an enabled app or connector tool returned by mcp_list_tools. Current settings are checked on every call. Changes require approval.',
+                parameters: (Type) => Type.Object({ name: Type.String(), arguments: Type.Record(Type.String(), Type.Unknown()) }),
+                execute: async (input) => JSON.stringify(await this.invoke(session, String(input.name), (input.arguments ?? {})))
+            }
+        ];
+    }
+    // ---- What a person does on the Connections screen ---------------------------------------------
+    async save(input) {
+        const connection = await this.connections.save(input);
+        this.cancelConnection(connection.id);
+        return connection;
+    }
+    async remove(connectionId) {
+        await this.connections.remove(connectionId);
+        this.cancelConnection(connectionId);
+    }
+    cancelConnection(connectionId) {
+        for (const [key, proposal] of this.proposals)
+            if (proposal.connectionId === connectionId)
+                this.proposals.delete(key);
+        void this.manager.close(connectionId);
+    }
+    /** Connects once and records what the server offers, or why it could not be reached. */
+    async test(connectionId) {
+        const connection = this.connections.find(connectionId);
+        let probed = null;
+        let failure = null;
+        try {
+            probed = await this.manager.probe(await this.connections.launch(connection));
+        }
+        catch (error) {
+            failure = error;
+        }
+        if (JSON.stringify(this.connections.find(connectionId)) !== JSON.stringify(connection))
+            throw new HarnessError('mcp_config_changed', 'Connection changed during its test. Test the saved connection again.');
+        const updated = this.connections.update(connectionId, (item) => {
+            item.checkedAt = now();
+            if (probed) {
+                item.serverName = probed.serverName;
+                item.tools = probed.tools;
+                item.error = null;
+                if (item.kind === 'workspace' && !item.expectedVaultId)
+                    item.expectedVaultId = probed.vaultId;
+            }
+            else {
+                if (isSignInRequired(failure) && item.auth === 'oauth' && item.authState === 'signed_in')
+                    item.authState = 'expired';
+                item.error = failure instanceof Error ? failure.message : String(failure);
+                item.tools = [];
+            }
+        });
+        this.connections.changed();
+        return updated;
+    }
+    /** Signs in with the provider in a browser. Only a person starts this; a session that finds an expired sign-in reports it. */
+    async signIn(connectionId) {
+        const connection = this.connections.find(connectionId);
+        if (connection.kind !== 'remote' || connection.auth !== 'oauth')
+            throw invalid('This connection does not use browser sign-in.');
+        if (!(await this.connections.hasSignInClient(connection))) {
+            throw invalid(connection.oauthClient === 'app'
+                ? 'This connector has no app sign-in in this build. Enable its OAuth client or use your own client.'
+                : 'Add your OAuth client ID before signing in.');
+        }
+        await signIn(this.oauth, (await this.connections.launch(connection)));
+        const updated = this.connections.update(connectionId, (item) => Object.assign(item, { authState: 'signed_in', error: null }));
+        await this.manager.close(connectionId);
+        this.connections.changed();
+        return updated;
+    }
+    /** The catalog entries this application can sign in for, so a client need not be added by hand. */
+    appClients() {
+        return { catalogIds: this.connections.availableAppClients() };
+    }
+    async signOut(connectionId) {
+        const updated = await this.connections.signOut(connectionId);
+        this.cancelConnection(connectionId);
+        return updated;
+    }
+    /** Reads one retrieved source again from the Xingular Workspace connection it came from. */
+    async refreshSource(runId, traceId, sourceUri) {
+        const trace = this.runContext(runId).find((entry) => entry.id === traceId);
+        if (!trace)
+            throw notFound('Retrieved context');
+        const source = trace.sources.find((entry) => entry.uri === sourceUri);
+        if (!source)
+            throw notFound('Source');
+        const connection = this.connections.list().find((item) => item.enabled && item.kind === 'workspace' && item.id === trace.connectionId);
+        if (!connection)
+            throw new HarnessError('mcp_access_denied', 'Enable the original Xingular Workspace connection to refresh this source.');
+        const kind = sourceUri.split('/')[3] ?? '';
+        const [tool, args] = kind.startsWith('note')
+            ? ['x_workspace_note_read', { path: source.path ?? source.id }]
+            : kind.startsWith('task')
+                ? ['x_workspace_task_get', { id: source.id }]
+                : kind.startsWith('project')
+                    ? ['x_workspace_project_get', { id: source.id }]
+                    : kind.startsWith('resource')
+                        ? ['x_workspace_resource_get', { id: source.id }]
+                        : ['x_workspace_context', { query: source.title || source.id }];
+        return this.connections.scrub(await this.manager.readSource(await this.connections.launch(connection), tool, args), connection.id);
+    }
+    /** Gives one agent exactly these connections, if its creator may reach each of them. */
+    setAgentScope(creator, agentId, ids) {
+        const all = this.connections.list();
+        for (const id of ids) {
+            const connection = all.find((item) => item.id === id);
+            if (!connection)
+                throw notFound('Connection');
+            if (!allowed(connection, creator))
+                throw new HarnessError('required_connections_unavailable', `${connection.name} is disabled or outside your connection scope.`);
+        }
+        return this.connections.setAgentScope(agentId, ids);
+    }
+    /**
+     * A call with no session and nobody to ask, made by a plugin's hook. It reaches a connection
+     * only when it is on for everyone, and a tool only when a person marked it to run without asking.
+     */
+    async callUnattended(reference, tool, args = {}) {
+        const connection = this.connections.list().find((item) => item.id === reference || item.name === reference);
+        if (!connection || !allowed(connection, {}))
+            throw new HarnessError('mcp_access_denied', `There is no connected app called "${reference}" that is on for everyone.`);
+        // A change to the first-party workspace is previewed and approved by a person, never run from a hook.
+        if (!connection.readTools.includes(tool) || tool.startsWith('x_workspace_mutation')) {
+            throw new HarnessError('mcp_denied', `${connection.name} asks before running "${tool}". Mark it to run without asking in the connection's settings to let a plugin use it.`);
+        }
+        const client = await this.manager.client(UNATTENDED_SCOPE, await this.connections.launch(connection));
+        return client.callTool({ name: tool, arguments: args }, { timeout: 60000 });
+    }
+    /** Switches one saved connection on or off for everyone, one agent, or one project. */
+    attach(connectionId, scope, on) {
+        const connection = this.connections.find(connectionId);
+        if (!connection.enabled)
+            throw invalid(`${connection.name} is switched off. Switch it on in its own settings first.`);
+        this.connections.setScope(connectionId, scope, on);
+    }
+    /** Forgets an agent that no longer exists. */
+    removeAgentScope(agentId) {
+        this.connections.removeAgentScope(agentId);
+    }
+    async close() {
+        await this.manager.close(undefined, UNATTENDED_SCOPE).catch(() => undefined);
+        await this.manager.close();
+    }
+}