@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/interaction/cli.js

@@ -0,0 +1,358 @@
+import { createInterface } from 'node:readline';
+import { createTextRenderer, terminalText } from './renderer.js';
+const PAGE = 20;
+const HELP = 'Text: submit | /new [title] | /sessions [offset] | /use ID | /history [offset] | /diagnostics [offset] | /refresh | /more | /cancel | /quit\n';
+/** Caller owns the streams and session service. Detaching never cancels a turn. */
+export async function openCli(options) {
+    const { sessions, input, output } = options;
+    const help = options.catalog
+        ? 'Text: submit | /new [title] | /sessions [CURSOR] | /use ID | /info | /rename REV JSON_TITLE_OR_NULL | /history [CURSOR] | /diagnostics [offset] | /refresh | /more | /cancel | /quit\n'
+        : HELP;
+    const renderer = options.renderer ?? createTextRenderer();
+    let selected = options.initialSessionId ?? (await sessions.create('CLI session')).id;
+    let cursor = 0;
+    let closed = false;
+    let unsubscribe = () => { };
+    let unsubscribeDiagnostics = () => { };
+    let unsubscribeProgress = () => { };
+    let progressQueued = false;
+    let pendingProgress;
+    let diagnosticsQueued = false;
+    let refreshQueued = false;
+    let scheduled;
+    let queue = Promise.resolve();
+    let resolveDone;
+    const done = new Promise(resolve => { resolveDone = resolve; });
+    const lines = createInterface({ input, crlfDelay: Infinity, terminal: false });
+    const finish = (end) => {
+        if (closed)
+            return;
+        closed = true;
+        if (scheduled)
+            clearImmediate(scheduled);
+        unsubscribe();
+        try {
+            unsubscribeProgress();
+        }
+        catch (error) {
+            end.error ??= error;
+        }
+        try {
+            unsubscribeDiagnostics();
+        }
+        catch (error) {
+            end.error ??= error;
+        }
+        lines.close();
+        lines.off('error', inputError);
+        input.off('error', inputError);
+        output.off('error', displayError);
+        output.off('close', outputClose);
+        resolveDone(end);
+    };
+    const displayError = (error) => finish({ reason: 'display-error', error });
+    const inputError = (error) => finish({ reason: 'input-error', error });
+    const outputClose = () => displayError(new Error('Output closed'));
+    input.on('error', inputError);
+    lines.on('error', inputError);
+    output.on('error', displayError);
+    output.on('close', outputClose);
+    const write = async (text) => {
+        if (closed)
+            return;
+        // Await the callback rather than buffering an unbounded amount for slow terminals.
+        await new Promise(resolve => {
+            try {
+                output.write(text, error => {
+                    // Writable emits its error after this callback. Keep our error listener
+                    // installed until that event; removing it here causes an unhandled error.
+                    if (error)
+                        return resolve();
+                    resolve();
+                });
+            }
+            catch (error) {
+                displayError(error);
+                resolve();
+            }
+        });
+    };
+    const enqueue = (work) => {
+        queue = queue.then(async () => {
+            if (closed)
+                return;
+            try {
+                await work();
+            }
+            catch (error) {
+                await write(`[error] ${terminalText(error instanceof Error ? error.message : String(error))}\n`);
+            }
+        });
+    };
+    const diagnostics = async (offset) => {
+        if (!options.diagnostics) {
+            await write('[observation unavailable: no adapter configured]\n');
+            return;
+        }
+        try {
+            if (offset !== undefined) {
+                const page = await options.diagnostics.query(selected, offset, PAGE);
+                if (page.lines.length > PAGE)
+                    throw new Error('Observation page exceeds limit');
+                for (const line of page.lines)
+                    await write(`[observation] ${terminalText(line)}\n`);
+                if (page.nextOffset !== null)
+                    await write(`[next: /diagnostics ${page.nextOffset}]\n`);
+            }
+            await write(`[observation health; NOT execution state] ${terminalText(await options.diagnostics.health())}\n`);
+        }
+        catch (error) {
+            await write(`[observation unavailable] ${terminalText(error instanceof Error ? error.message : String(error))}\n`);
+        }
+    };
+    const refresh = async () => {
+        const page = await sessions.read(selected, cursor, PAGE);
+        if (closed)
+            return;
+        if (page.records.length > PAGE || !Number.isSafeInteger(page.cursor) || page.cursor < cursor
+            || (page.hasMore && page.cursor <= cursor))
+            throw new Error('Invalid display page progress');
+        let previous = cursor;
+        for (const record of page.records) {
+            const id = record.kind === 'event' ? record.event.sessionId : record.sessionId;
+            if (id !== selected || !Number.isSafeInteger(record.cursor) || record.cursor <= previous || record.cursor > page.cursor) {
+                throw new Error('Invalid display record identity/order');
+            }
+            // Renderer is also an optional display adapter, never an execution sink.
+            let rendered;
+            try {
+                rendered = renderer.record(record);
+            }
+            catch (error) {
+                displayError(error);
+                return;
+            }
+            await write(rendered);
+            if (closed)
+                return;
+            previous = record.cursor;
+            cursor = record.cursor;
+        }
+        if (page.cursor !== previous)
+            throw new Error('Display cursor skipped records');
+        if (page.diagnostic)
+            await write(`[diagnostic] ${terminalText(page.diagnostic)}\n`);
+        if (page.hasMore)
+            scheduleRefresh();
+    };
+    const scheduleRefresh = () => {
+        if (closed || refreshQueued || scheduled)
+            return;
+        scheduled = setImmediate(() => {
+            scheduled = undefined;
+            refreshQueued = true;
+            enqueue(async () => {
+                refreshQueued = false;
+                await refresh();
+            });
+        });
+    };
+    const select = async (id) => {
+        // Validate the target before losing the current selection.
+        await sessions.read(id, 0, 1);
+        if (closed)
+            return;
+        unsubscribe();
+        selected = id;
+        cursor = 0;
+        // Subscribe before reading so changes concurrent with the read are not missed.
+        unsubscribe = sessions.subscribe(selected, scheduleRefresh);
+        await write(`[selected ${terminalText(selected, 200)}; replay]\n`);
+        await refresh();
+    };
+    const offset = (argument) => {
+        if (!argument)
+            return 0;
+        if (!/^\d+$/.test(argument) || !Number.isSafeInteger(Number(argument)))
+            throw new Error('Expected a non-negative offset');
+        return Number(argument);
+    };
+    const command = async (line) => {
+        if (line.length > 65536)
+            throw new Error('Input exceeds 65536 characters');
+        const match = /^\/(\S+)(?:\s+(.*))?$/.exec(line.trim());
+        if (!match) {
+            if (!line.trim())
+                return;
+            const scope = await sessions.submit(selected, line);
+            await write(`[submitted ${terminalText(scope.turnId, 100)}]\n`);
+            scheduleRefresh();
+            return;
+        }
+        const arg = (match[2] ?? '').trim();
+        switch (match[1]) {
+            case 'help':
+                await write(help);
+                break;
+            case 'new': {
+                const item = await sessions.create(arg || 'CLI session');
+                if (!closed)
+                    await select(item.id);
+                break;
+            }
+            case 'use':
+                if (!arg)
+                    throw new Error('Usage: /use ID');
+                await select(arg);
+                break;
+            case 'sessions': {
+                if (options.catalog) {
+                    const page = await options.catalog.listSessions({ limit: PAGE, ...(arg ? { cursor: arg } : {}) });
+                    for (const item of page.items)
+                        await write(`${terminalText(item.sessionId, 200)} ${terminalText(item.title ?? '(untitled)', 400)} [metadata revision ${item.metadataRevision}]\n`);
+                    if (page.nextCursor !== null)
+                        await write(`[next: /sessions ${terminalText(page.nextCursor, 4096)}]\n`);
+                    break;
+                }
+                const page = await sessions.list(offset(arg), PAGE);
+                if (page.sessions.length > PAGE)
+                    throw new Error('Session page exceeds limit');
+                for (const item of page.sessions)
+                    await write(`${terminalText(item.id, 200)} ${terminalText(item.title, 200)}\n`);
+                if (page.nextOffset !== null)
+                    await write(`[next: /sessions ${page.nextOffset}]\n`);
+                break;
+            }
+            case 'history': {
+                if (options.catalog) {
+                    const page = await options.catalog.readHistory(selected, { limit: PAGE, ...(arg ? { cursor: arg } : {}) });
+                    await write(`[history facts ${terminalText(selected, 200)} revision ${page.revision}; not execution context]\n`);
+                    for (const item of page.records) {
+                        let text;
+                        try {
+                            text = renderer.record({ kind: 'event', cursor: item.revision, event: item.event });
+                        }
+                        catch (error) {
+                            displayError(error);
+                            return;
+                        }
+                        await write(`[fact ${item.revision}] ${text}`);
+                    }
+                    if (page.nextCursor !== null)
+                        await write(`[next: /history ${terminalText(page.nextCursor, 4096)}]\n`);
+                    break;
+                }
+                const page = await sessions.history(selected, offset(arg), PAGE);
+                if (page.messages.length > PAGE)
+                    throw new Error('History page exceeds limit');
+                await write(`[history ${terminalText(selected, 200)} offset ${offset(arg)}]\n`);
+                for (const message of page.messages) {
+                    try {
+                        await write(renderer.message(message));
+                    }
+                    catch (error) {
+                        displayError(error);
+                        return;
+                    }
+                }
+                if (page.nextOffset !== null)
+                    await write(`[next: /history ${page.nextOffset}]\n`);
+                break;
+            }
+            case 'info':
+                if (!options.catalog || arg)
+                    throw new Error('Usage: /info requires a catalog');
+                await write(`[session info] ${terminalText(JSON.stringify(await options.catalog.getSessionInfo(selected)), 8192)}\n`);
+                break;
+            case 'rename': {
+                const rename = /^(\d+)\s+(.+)$/u.exec(arg);
+                if (!options.catalog || !rename || !Number.isSafeInteger(Number(rename[1])))
+                    throw new Error('Usage: /rename EXPECTED_METADATA_REVISION JSON_TITLE_OR_NULL');
+                let title;
+                try {
+                    title = JSON.parse(rename[2]);
+                }
+                catch {
+                    throw new Error('Expected JSON string or null title');
+                }
+                if (title !== null && typeof title !== 'string')
+                    throw new Error('Expected JSON string or null title');
+                const saved = await options.catalog.renameSession(selected, title, Number(rename[1]));
+                await write(`[session renamed] ${terminalText(JSON.stringify(saved), 8192)}\n`);
+                break;
+            }
+            case 'diagnostics':
+                await diagnostics(offset(arg));
+                break;
+            case 'refresh':
+                cursor = 0;
+                await write('[replay from session facts]\n');
+                await refresh();
+                break;
+            case 'more':
+                await refresh();
+                break;
+            case 'cancel': {
+                const page = await sessions.read(selected, cursor, 1);
+                if (closed)
+                    return;
+                const accepted = page.activeTurnId !== null && await sessions.cancel({ sessionId: selected, turnId: page.activeTurnId });
+                await write(accepted ? '[cancel requested; awaiting actual terminal]\n' : '[no matching active turn]\n');
+                break;
+            }
+            case 'quit':
+                finish({ reason: 'quit' });
+                break;
+            default: throw new Error('Unknown command; /help lists commands');
+        }
+    };
+    lines.on('line', line => enqueue(() => command(line)));
+    lines.on('close', () => {
+        // Let already accepted input lines finish on piped EOF.
+        enqueue(async () => finish({ reason: 'eof' }));
+    });
+    enqueue(async () => {
+        await write(help);
+        await select(selected);
+        if (closed)
+            return;
+        if (options.progress)
+            unsubscribeProgress = options.progress.subscribe(progress => {
+                if (closed || progress.sessionId !== selected)
+                    return;
+                const same = pendingProgress?.turnId === progress.turnId;
+                const text = (same ? pendingProgress.text : '') + progress.text;
+                pendingProgress = { ...progress, text: text.slice(0, 8192),
+                    omitted: text.length > 8192 || !!pendingProgress?.omitted || (!!pendingProgress && !same) };
+                if (progressQueued)
+                    return;
+                progressQueued = true;
+                enqueue(async () => {
+                    const next = pendingProgress;
+                    pendingProgress = undefined;
+                    progressQueued = false;
+                    if (next?.sessionId === selected) {
+                        await write(`[provisional ${terminalText(next.turnId, 100)}] ${terminalText(next.text)}${next.omitted ? ' [updates omitted]' : ''}\n`);
+                    }
+                });
+            });
+        if (!options.diagnostics)
+            return;
+        try {
+            unsubscribeDiagnostics = options.diagnostics.subscribe(() => {
+                if (closed || diagnosticsQueued)
+                    return;
+                diagnosticsQueued = true;
+                enqueue(async () => { diagnosticsQueued = false; await diagnostics(); });
+            });
+        }
+        catch (error) {
+            await write(`[observation unavailable] ${terminalText(error instanceof Error ? error.message : String(error))}\n`);
+        }
+    });
+    if (input.readableEnded)
+        enqueue(async () => finish({ reason: 'eof' }));
+    if (output.destroyed)
+        displayError(new Error('Output unavailable'));
+    return { done, close: () => finish({ reason: 'closed' }) };
+}

package/dist/nativeAgent/interaction/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/nativeAgent/interaction/index.js

@@ -0,0 +1,3 @@
+export { openCli } from './cli.js';
+export { createTextRenderer } from './renderer.js';
+export { createMemoryDemoSessions } from './memoryDemo.js';

package/dist/nativeAgent/interaction/memoryDemo.js

@@ -0,0 +1,115 @@
+import { createAgent } from '../index.js';
+/** Disposable fixture adapter, NOT the production session/persistence module. */
+export function createMemoryDemoSessions(options) {
+    const sessions = new Map();
+    const failures = new Map();
+    let nextSession = 0;
+    let nextTurn = 0;
+    let closing = false;
+    const get = (id) => {
+        const session = sessions.get(id);
+        if (!session)
+            throw new Error(`Unknown demo session: ${id}`);
+        return session;
+    };
+    const pageBounds = (offset, limit, length) => {
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset > length
+            || !Number.isInteger(limit) || limit < 1 || limit > 20)
+            throw new Error('Invalid page bounds');
+    };
+    const notify = (session) => {
+        for (const listener of session.listeners) {
+            try {
+                listener();
+            }
+            catch { /* Optional observer cannot reject recording or execution. */ }
+        }
+    };
+    const append = (session, event) => {
+        const snapshot = structuredClone(event);
+        session.records.push({ cursor: session.records.length + 1, kind: 'event', event: snapshot });
+        if (snapshot.data.type === 'message_appended')
+            session.messages.push(snapshot.data.message);
+        notify(session);
+    };
+    return {
+        get activeCount() { return [...sessions.values()].filter(session => session.active).length; },
+        async create(title) {
+            if (closing)
+                throw new Error('Demo sessions closed');
+            const summary = { id: `demo-session-${++nextSession}`, title: title.slice(0, 200) };
+            sessions.set(summary.id, { summary, messages: [], records: [], listeners: new Set() });
+            return { ...summary };
+        },
+        async list(offset, limit) {
+            const all = [...sessions.values()];
+            pageBounds(offset, limit, all.length);
+            return { sessions: all.slice(offset, offset + limit).map(session => ({ ...session.summary })),
+                nextOffset: offset + limit < all.length ? offset + limit : null };
+        },
+        async submit(sessionId, input) {
+            if (closing)
+                throw new Error('Demo sessions closed');
+            const session = get(sessionId);
+            if (session.active)
+                throw new Error('Session already running; cancel or select another session');
+            const scope = { sessionId, turnId: `demo-turn-${++nextTurn}` };
+            const abort = new AbortController();
+            const agent = createAgent({ ...options, recorder: { async record(event) { append(session, event); } } });
+            const history = structuredClone(session.messages);
+            // Defer execution until the active handle is installed, even for immediate providers.
+            const done = Promise.resolve().then(async () => {
+                try {
+                    await agent.runTurn({ ...scope, input, history, maxSteps: options.maxSteps ?? 8, signal: abort.signal });
+                }
+                catch (error) {
+                    // Unexpected/preflight rejection has no trustworthy execution terminal.
+                    // Preserve an explicit diagnostic, never fabricate an AgentEvent or replay.
+                    failures.set(sessionId, `Execution rejected; terminal unconfirmed; no automatic replay: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                finally {
+                    session.active = undefined;
+                    notify(session);
+                }
+            });
+            failures.delete(sessionId);
+            session.active = { scope, abort, done };
+            return { ...scope };
+        },
+        async cancel(scope) {
+            const active = get(scope.sessionId).active;
+            if (!active || active.scope.turnId !== scope.turnId)
+                return false;
+            active.abort.abort();
+            return true;
+        },
+        async read(id, after, limit) {
+            const session = get(id);
+            pageBounds(after, limit, session.records.length);
+            const records = structuredClone(session.records.slice(after, after + limit));
+            return { records, cursor: records.at(-1)?.cursor ?? after,
+                hasMore: after + records.length < session.records.length, activeTurnId: session.active?.scope.turnId ?? null,
+                diagnostic: failures.get(id) };
+        },
+        async history(id, offset, limit) {
+            const session = get(id);
+            pageBounds(offset, limit, session.messages.length);
+            return { messages: structuredClone(session.messages.slice(offset, offset + limit)),
+                nextOffset: offset + limit < session.messages.length ? offset + limit : null };
+        },
+        subscribe(id, listener) {
+            const session = get(id);
+            session.listeners.add(listener);
+            return () => { session.listeners.delete(listener); };
+        },
+        async close() {
+            closing = true;
+            const active = [...sessions.values()].flatMap(session => session.active ? [session.active] : []);
+            for (const turn of active)
+                turn.abort.abort();
+            await Promise.all(active.map(turn => turn.done));
+            for (const session of sessions.values())
+                session.listeners.clear();
+        },
+    };
+}

package/dist/nativeAgent/interaction/renderer.js

@@ -0,0 +1,34 @@
+/** Do not let model/tool output control the user's terminal (including OSC/CSI). */
+export function terminalText(value, limit = 2000) {
+    const clipped = value.slice(0, limit);
+    const safe = clipped.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return safe + (clipped.length < value.length ? ` [truncated ${value.length - clipped.length} chars]` : '');
+}
+export function createTextRenderer() {
+    const message = (item) => {
+        if (item.role === 'tool') {
+            const result = item.outcome.ok ? item.outcome.content
+                : `${item.outcome.error.code} (effect=${item.outcome.error.effect}): ${item.outcome.error.message}`;
+            return `[tool result ${terminalText(item.name, 100)} ${terminalText(item.toolCallId, 100)}] ${terminalText(result)}\n`;
+        }
+        const calls = item.role === 'assistant' ? item.toolCalls.map(call => `[tool call ${terminalText(call.name, 100)} ${terminalText(call.id, 100)}] ${terminalText(JSON.stringify(call.arguments))}\n`).join('') : '';
+        return `[message ${item.role}] ${terminalText(item.content)}\n${calls}`;
+    };
+    return {
+        message,
+        record(record) {
+            if (record.kind === 'text_delta') {
+                return `[provisional ${terminalText(record.turnId, 100)}] ${terminalText(record.text)}\n`;
+            }
+            const event = record.event;
+            switch (event.data.type) {
+                case 'message_appended': return message(event.data.message);
+                case 'turn_started': return `[turn ${terminalText(event.turnId, 100)} started]\n`;
+                case 'step_started': return `[step ${event.data.step} started]\n`;
+                case 'tool_started': return `[tool running ${terminalText(event.data.name, 100)} ${terminalText(event.data.toolCallId, 100)}]\n`;
+                case 'step_ended': return `[step ${event.data.step} ended]\n`;
+                case 'turn_ended': return `[ended: ${event.data.reason}]${event.data.errorCode ? ` ${terminalText(event.data.errorCode, 100)}` : ''}\n`;
+            }
+        },
+    };
+}