nexus-ai-pro 2.2.0 → 2.4.0

package/dist/protocols/acp.d.ts

@@ -0,0 +1,87 @@
+import type { Message } from '../types/messages.js';
+import type { Principal } from '../types/principal.js';
+import { type ProtocolGraph, type ProtocolInterrupt } from './shared.js';
+export type { ProtocolGraph, ProtocolInterrupt, ProtocolResult, ProtocolRunOptions } from './shared.js';
+/** The protocol version this module speaks. */
+export declare const ACP_PROTOCOL_VERSION = 1;
+/** What a tool call does, so the editor can show it: ACP's tool kinds. */
+export type AcpToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'other';
+/** Why a prompt's turn ended. */
+export type AcpStopReason = 'end_turn' | 'max_tokens' | 'max_turn_requests' | 'refusal' | 'cancelled';
+/** One block of a prompt: text, a file the editor embedded, or a link to one. */
+export interface AcpContentBlock {
+    /** `text`, `resource`, `resource_link`, or a kind this agent does not read, such as `image`. */
+    type: string;
+    /** A text block's text. */
+    text?: string;
+    /** A link's URI. */
+    uri?: string;
+    /** A link's name. */
+    name?: string;
+    /** An embedded file. */
+    resource?: {
+        uri: string;
+        text?: string;
+        mimeType?: string;
+    };
+}
+/** What the agent tells the editor during a turn: ACP's `session/update`. */
+export type AcpSessionUpdate = {
+    sessionUpdate: string;
+} & Record<string, unknown>;
+/** An editor session, as `input` sees it. */
+export interface AcpSessionInfo {
+    /** Its id, which is also the graph's thread. */
+    id: string;
+    /** The directory the editor opened the session in. */
+    cwd: string;
+    /** The MCP servers the editor offered. */
+    mcpServers: unknown[];
+}
+/** Where the agent reads and writes: `process.stdin` and `process.stdout`, or any pair like them. */
+export interface AcpStreams {
+    /** What the editor writes. */
+    input: AsyncIterable<Uint8Array | string>;
+    /** Where the agent writes. */
+    output: {
+        write(chunk: string): unknown;
+    };
+}
+/** Options for `serveAcp()`. */
+export interface AcpOptions {
+    /** The agent's name and version, as the editor shows them. */
+    agentInfo?: {
+        name: string;
+        version: string;
+        title?: string;
+    };
+    /**
+     * The graph input for a prompt. Defaults to `{ messages }`: the session's conversation and the
+     * prompt, which is what an agent from `createAgent()` takes.
+     */
+    input?: (prompt: string, session: AcpSessionInfo, history: Message[]) => unknown;
+    /**
+     * The answer the next prompt gives a question that is not a tool approval. Such a question is
+     * asked as the agent's message, and the turn ends. Defaults to the prompt's text.
+     */
+    answer?: (prompt: string, interrupt: ProtocolInterrupt) => unknown;
+    /** What a tool does, for the editor. Defaults to a guess from its name. */
+    kind?: (name: string, args: unknown) => AcpToolKind;
+    /** Who the agent acts for: the person at the editor. */
+    principal?: Principal;
+}
+/** A running ACP connection. */
+export interface AcpServer {
+    /** Resolves when the editor closes its end. */
+    closed: Promise<void>;
+    /** Stops every running prompt. */
+    close(): void;
+}
+/**
+ * Serves a graph to an editor over ACP. Run it as the agent's process:
+ *
+ * ```ts
+ * serveAcp(agent, { input: process.stdin, output: process.stdout }, { agentInfo: { name: 'reviewer', version: '1.0.0' } });
+ * ```
+ */
+export declare function serveAcp(graph: ProtocolGraph, streams: AcpStreams, options?: AcpOptions): AcpServer;

package/dist/protocols/acp.js

@@ -0,0 +1,322 @@
+import { answerOf, asText, messageOf, protocolId, toolCallOf, transcriptOf, } from './shared.js';
+export const ACP_PROTOCOL_VERSION = 1;
+export function serveAcp(graph, streams, options = {}) {
+    const sessions = new Map();
+    const waiting = new Map();
+    let requests = 0;
+    const write = (message) => streams.output.write(`${JSON.stringify(message)}\n`);
+    const notify = (sessionId, update) => write({ jsonrpc: '2.0', method: 'session/update', params: { sessionId, update } });
+    const request = (method, params, signal) => new Promise((resolve) => {
+        const id = `agent-${++requests}`;
+        const cancel = () => {
+            waiting.delete(id);
+            resolve({ result: { outcome: { outcome: 'cancelled' } } });
+        };
+        if (signal.aborted)
+            return cancel();
+        signal.addEventListener('abort', cancel, { once: true });
+        waiting.set(id, (message) => {
+            signal.removeEventListener('abort', cancel);
+            resolve(message);
+        });
+        write({ jsonrpc: '2.0', id, method, params });
+    });
+    const kind = options.kind ?? guessKind;
+    const answerText = options.answer ?? ((prompt) => prompt);
+    const permit = async (session, interrupt, signal) => {
+        const call = toolCallOf(interrupt);
+        const standing = session.always.get(call.name);
+        if (standing !== undefined)
+            return standing;
+        const response = await request('session/request_permission', {
+            sessionId: session.info.id,
+            toolCall: {
+                toolCallId: call.id,
+                title: interrupt.reason ?? titleOf(call.name, call.args),
+                kind: kind(call.name, call.args),
+                status: 'pending',
+                rawInput: call.args,
+            },
+            options: [
+                { optionId: 'allow_once', name: 'Allow', kind: 'allow_once' },
+                { optionId: 'allow_always', name: `Always allow ${call.name}`, kind: 'allow_always' },
+                { optionId: 'reject_once', name: 'Reject', kind: 'reject_once' },
+                { optionId: 'reject_always', name: `Always reject ${call.name}`, kind: 'reject_always' },
+            ],
+        }, signal);
+        const outcome = response.result?.outcome;
+        if (outcome?.outcome !== 'selected')
+            return 'cancelled';
+        const allowed = outcome.optionId?.startsWith('allow') ?? false;
+        if (outcome.optionId?.endsWith('always'))
+            session.always.set(call.name, allowed);
+        return allowed;
+    };
+    const prompt = async (session, blocks) => {
+        session.controller?.abort();
+        const controller = new AbortController();
+        session.controller = controller;
+        const id = session.info.id;
+        const text = promptText(blocks);
+        let spoke = false;
+        const calls = new Map();
+        const runOptions = {
+            threadId: id,
+            signal: controller.signal,
+            ...(options.principal ? { principal: options.principal } : {}),
+            onEvent: (event) => {
+                if (event.namespace)
+                    return;
+                if (event.type === 'message' && event.chunk.content) {
+                    spoke = true;
+                    notify(id, {
+                        sessionUpdate: event.chunk.kind === 'reasoning' ? 'agent_thought_chunk' : 'agent_message_chunk',
+                        content: { type: 'text', text: event.chunk.content },
+                    });
+                }
+                else if (event.type === 'tool') {
+                    spoke = false;
+                    for (const update of toolUpdates(event.tool, kind, calls))
+                        notify(id, update);
+                }
+            },
+        };
+        try {
+            return await turn(session, text, runOptions, controller.signal, () => spoke);
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                return 'cancelled';
+            throw error;
+        }
+    };
+    const turn = async (session, text, runOptions, signal, spoke) => {
+        const id = session.info.id;
+        const user = messageOf('user', text);
+        let result;
+        if (session.pending?.length) {
+            const answers = {
+                ...session.answered,
+                ...Object.fromEntries(session.pending.map((item) => [item.id, answerText(text, item)])),
+            };
+            session.pending = undefined;
+            session.answered = undefined;
+            session.history.push(user);
+            result = await graph.resumeInterruptsWith(id, answers, runOptions);
+        }
+        else {
+            const history = session.history;
+            result = await graph.invoke(options.input ? options.input(text, session.info, history) : { messages: [...history, user] }, runOptions);
+            session.history = [...history, user];
+        }
+        while (result.status === 'awaiting_input' && result.interrupts?.length) {
+            if (signal.aborted)
+                return 'cancelled';
+            const approvals = result.interrupts.filter((item) => toolCallOf(item));
+            const questions = result.interrupts.filter((item) => !toolCallOf(item));
+            const answers = {};
+            for (const interrupt of approvals) {
+                const decision = await permit(session, interrupt, signal);
+                if (decision === 'cancelled')
+                    return 'cancelled';
+                answers[interrupt.id] = decision;
+            }
+            if (questions.length) {
+                notify(id, {
+                    sessionUpdate: 'agent_message_chunk',
+                    content: { type: 'text', text: questions.map(questionOf).join('\n') },
+                });
+                session.pending = questions;
+                session.answered = answers;
+                return 'end_turn';
+            }
+            result = await graph.resumeInterruptsWith(id, answers, runOptions);
+        }
+        if (signal.aborted || result.status === 'interrupted')
+            return 'cancelled';
+        const answer = answerOf(result.state);
+        if (!spoke() && answer)
+            notify(id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: answer } });
+        session.history = transcriptOf(result.state, [...session.history, messageOf('assistant', answer)]);
+        return result.state?.stopReason === 'max_iterations'
+            ? 'max_turn_requests'
+            : 'end_turn';
+    };
+    const handle = async (message) => {
+        const params = message.params ?? {};
+        switch (message.method) {
+            case 'initialize':
+                return {
+                    protocolVersion: ACP_PROTOCOL_VERSION,
+                    agentCapabilities: {
+                        loadSession: false,
+                        promptCapabilities: { image: false, audio: false, embeddedContext: true },
+                    },
+                    authMethods: [],
+                    ...(options.agentInfo ? { agentInfo: options.agentInfo } : {}),
+                };
+            case 'authenticate':
+                return {};
+            case 'session/new': {
+                const info = {
+                    id: protocolId('session'),
+                    cwd: typeof params.cwd === 'string' ? params.cwd : '',
+                    mcpServers: Array.isArray(params.mcpServers) ? params.mcpServers : [],
+                };
+                sessions.set(info.id, { info, history: [], always: new Map() });
+                return { sessionId: info.id };
+            }
+            case 'session/prompt': {
+                const session = sessions.get(String(params.sessionId));
+                if (!session)
+                    throw Object.assign(new Error(`Session ${String(params.sessionId)} was not found`), { code: -32602 });
+                return {
+                    stopReason: await prompt(session, Array.isArray(params.prompt) ? params.prompt : []),
+                };
+            }
+            default:
+                throw Object.assign(new Error(`Method ${String(message.method)} is not supported`), { code: -32601 });
+        }
+    };
+    const receive = (message) => {
+        if (message.method === undefined) {
+            if (message.id !== undefined && message.id !== null)
+                waiting.get(message.id)?.(message);
+            waiting.delete(message.id);
+            return;
+        }
+        if (message.id === undefined || message.id === null) {
+            if (message.method === 'session/cancel')
+                sessions.get(String(message.params?.sessionId))?.controller?.abort();
+            return;
+        }
+        handle(message).then((result) => write({ jsonrpc: '2.0', id: message.id, result }), (error) => write({
+            jsonrpc: '2.0',
+            id: message.id,
+            error: { code: typeof error.code === 'number' ? error.code : -32603, message: error.message },
+        }));
+    };
+    const closed = (async () => {
+        const decoder = new TextDecoder();
+        let buffer = '';
+        for await (const chunk of streams.input) {
+            buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+            let newline = buffer.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line) {
+                    try {
+                        receive(JSON.parse(line));
+                    }
+                    catch {
+                        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'A line is not JSON' } });
+                    }
+                }
+                newline = buffer.indexOf('\n');
+            }
+        }
+    })();
+    return {
+        closed,
+        close() {
+            for (const session of sessions.values())
+                session.controller?.abort();
+        },
+    };
+}
+function toolUpdates(tool, kind, calls) {
+    const args = (tool.args ?? calls.get(tool.id) ?? {});
+    if (tool.phase === 'start') {
+        calls.set(tool.id, args);
+        const updates = [
+            {
+                sessionUpdate: 'tool_call',
+                toolCallId: tool.id,
+                title: titleOf(tool.name, args),
+                kind: kind(tool.name, args),
+                status: 'in_progress',
+                rawInput: args,
+                ...(typeof args.path === 'string' ? { locations: [{ path: args.path }] } : {}),
+            },
+        ];
+        if (tool.name === 'write_todos' && Array.isArray(args.todos)) {
+            updates.push({
+                sessionUpdate: 'plan',
+                entries: args.todos.map((todo) => ({
+                    content: String(todo.content ?? ''),
+                    priority: 'medium',
+                    status: todo.status === 'in_progress' || todo.status === 'completed' ? todo.status : 'pending',
+                })),
+            });
+        }
+        return updates;
+    }
+    if (tool.phase !== 'result' && tool.phase !== 'error')
+        return [];
+    const content = [];
+    if (tool.phase === 'result' && typeof args.path === 'string') {
+        const oldText = args.old_text ?? args.oldText;
+        const newText = args.new_text ?? args.newText ?? (tool.name === 'write_file' ? args.content : undefined);
+        if (typeof newText === 'string') {
+            content.push({ type: 'diff', path: args.path, oldText: typeof oldText === 'string' ? oldText : null, newText });
+        }
+    }
+    content.push({
+        type: 'content',
+        content: { type: 'text', text: tool.phase === 'result' ? asText(tool.result) : (tool.error ?? 'The tool failed') },
+    });
+    return [
+        {
+            sessionUpdate: 'tool_call_update',
+            toolCallId: tool.id,
+            status: tool.phase === 'result' ? 'completed' : 'failed',
+            content,
+            ...(tool.phase === 'result' ? { rawOutput: tool.result } : {}),
+        },
+    ];
+}
+function guessKind(name) {
+    const lower = name.toLowerCase();
+    if (lower === 'write_todos' || /think|plan/.test(lower))
+        return 'think';
+    if (/delete|remove|^rm$/.test(lower))
+        return 'delete';
+    if (/move|rename|^mv$/.test(lower))
+        return 'move';
+    if (/edit|write|patch|replace|create/.test(lower))
+        return 'edit';
+    if (/grep|glob|search|find|query/.test(lower))
+        return 'search';
+    if (/read|^ls$|list|cat|open|view/.test(lower))
+        return 'read';
+    if (/exec|shell|bash|run|command|terminal/.test(lower))
+        return 'execute';
+    if (/fetch|http|url|web|download|browse/.test(lower))
+        return 'fetch';
+    return 'other';
+}
+function titleOf(name, args) {
+    const values = (args ?? {});
+    const subject = [values.path, values.command, values.query, values.url, values.pattern].find((value) => typeof value === 'string');
+    return subject ? `${name} ${subject}` : name;
+}
+function questionOf(interrupt) {
+    return (interrupt.reason ??
+        (interrupt.payload === undefined ? 'The agent needs an answer to continue.' : asText(interrupt.payload)));
+}
+function promptText(blocks) {
+    return blocks
+        .map((block) => {
+        if (block.type === 'text')
+            return block.text ?? '';
+        if (block.type === 'resource' && typeof block.resource?.text === 'string') {
+            return `${block.resource.uri}\n\`\`\`\n${block.resource.text}\n\`\`\``;
+        }
+        if (block.type === 'resource_link' && block.uri)
+            return `@${block.uri}`;
+        return '';
+    })
+        .filter(Boolean)
+        .join('\n\n');
+}

package/dist/protocols/ag-ui.d.ts

@@ -0,0 +1,120 @@
+import type { Message } from '../types/messages.js';
+import type { Principal } from '../types/principal.js';
+import { type ProtocolGraph } from './shared.js';
+export type { ProtocolGraph, ProtocolInterrupt, ProtocolResult, ProtocolRunOptions } from './shared.js';
+/** A message in AG-UI's shape. */
+export interface AgUiMessage {
+    /** Its id. */
+    id: string;
+    /** `user`, `assistant`, `system`, `developer`, or `tool`; other roles are passed over. */
+    role: string;
+    /** Its text, or a list of parts with text. */
+    content?: unknown;
+    /** The tool calls an assistant message made. */
+    toolCalls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    /** The call a tool message answers. */
+    toolCallId?: string;
+}
+/** One answer to an interrupt, in a resumed run. */
+export interface AgUiResumeEntry {
+    /** The interrupt it answers. */
+    interruptId: string;
+    /** `resolved` with a payload, or `cancelled`. */
+    status: 'resolved' | 'cancelled';
+    /** The answer. */
+    payload?: unknown;
+}
+/** What a frontend sends to start or resume a run: AG-UI's `RunAgentInput`. */
+export interface AgUiRunInput {
+    /** The conversation. */
+    threadId: string;
+    /** This run. */
+    runId: string;
+    /** The run this one continues, when it does. */
+    parentRunId?: string;
+    /** The whole conversation so far. */
+    messages: AgUiMessage[];
+    /** Tools the frontend offers. Passed to `input` for an application that uses them. */
+    tools?: Array<{
+        name: string;
+        description: string;
+        parameters: unknown;
+    }>;
+    /** Extra context the frontend supplies. */
+    context?: Array<{
+        description: string;
+        value: string;
+    }>;
+    /** Shared state, when the frontend keeps any. */
+    state?: unknown;
+    /** Anything else the frontend forwards. */
+    forwardedProps?: unknown;
+    /** Answers to the questions a paused run asked. */
+    resume?: AgUiResumeEntry[];
+}
+/** A question a paused run asks, in AG-UI's shape. */
+export interface AgUiInterrupt {
+    /** Its id, which a resume entry names. */
+    id: string;
+    /** `tool_call` for an approval, `input_required` for anything else. */
+    reason: string;
+    /** The question, for a person. */
+    message?: string;
+    /** The tool call awaiting approval, when it is one. */
+    toolCallId?: string;
+    /** What the run asked about, whole. */
+    metadata?: Record<string, unknown>;
+}
+/** An AG-UI event, as the stream carries it. */
+export type AgUiEvent = {
+    type: string;
+    timestamp?: number;
+} & Record<string, unknown>;
+/** Options for `agUiEvents()` and `agUiHandler()`. */
+export interface AgUiOptions {
+    /**
+     * The graph input for a run. Defaults to `{ messages }`, the conversation as Nexus messages,
+     * which is what an agent from `createAgent()` takes.
+     */
+    input?: (run: AgUiRunInput, messages: Message[]) => unknown;
+    /** The answer a resume entry gives a question. Defaults to its payload, `true` when it has none, and `false` when cancelled. */
+    answer?: (entry: AgUiResumeEntry) => unknown;
+    /** Who the run is for, from the request: the place to authenticate a frontend's caller. */
+    principal?: (request: Request) => Principal | undefined | Promise<Principal | undefined>;
+    /** Adds a `STATE_SNAPSHOT` with the final state before the run finishes. Defaults to true. */
+    stateSnapshot?: boolean;
+}
+/** Options for `agUiEvents()`: everything `agUiHandler()` takes, with the caller already known. */
+export interface AgUiEventsOptions extends Omit<AgUiOptions, 'principal'> {
+    /** Stops the run. */
+    signal?: AbortSignal;
+    /** Who the run is for. */
+    principal?: Principal;
+}
+/** The conversation from a `RunAgentInput`, as Nexus messages. */
+export declare function agUiMessages(messages: readonly AgUiMessage[]): Message[];
+/**
+ * A run as AG-UI events, for any transport: Server-Sent Events, a WebSocket, a test. Events are
+ * produced as the graph emits them; the last is `RUN_FINISHED` or `RUN_ERROR`.
+ */
+export declare function agUiEvents(graph: ProtocolGraph, run: AgUiRunInput, options?: AgUiEventsOptions): AsyncGenerator<AgUiEvent>;
+/**
+ * An HTTP handler that serves a graph to AG-UI frontends: POST a `RunAgentInput`, read the run as
+ * Server-Sent Events. Mount it on any route, under any framework that speaks `Request` and
+ * `Response`.
+ *
+ * ```ts
+ * const handler = agUiHandler(agent);
+ * app.post('/agent', (request) => handler(request));
+ * ```
+ */
+export declare function agUiHandler(graph: ProtocolGraph, options?: AgUiOptions): (request: Request) => Promise<Response>;
+/** One event as a Server-Sent Event: `data: <json>` and a blank line. */
+export declare function encodeAgUiEvent(event: AgUiEvent): string;