@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/product/runtime.js

@@ -0,0 +1,276 @@
+import { createAgent, createProjectGuidance, createContextBuilder, createExecutionOwner, createLocalObserver, createModelGateway, connectModelObservations, createInteractionDiagnostics, openCli, } from '../index.js';
+import { ProductError, containsCredential, createProductBinding, publicConfiguration } from './config.js';
+import { createProductTransport } from './transport.js';
+import { createProductTools } from './tools.js';
+import { openProductStore, storageFailure } from './storage.js';
+import { restoreProductLocation, createProductSession } from './location.js';
+import { createRuntimeFacts } from './facts.js';
+/** Product owns the streams' connection listeners, model dispatcher, store and owner.
+ * No hidden execution loop/catalog/policy: all execution goes through ExecutionOwner. */
+export async function runProductRuntime(invocation, credential) {
+    let { config } = invocation;
+    // Rebuild on EVERY open/resume from current explicit authority, never stored history.
+    // Same factory for all three capabilities; do not grant the shorthand's always-allow lease.
+    let binding;
+    const observer = createLocalObserver();
+    let store, owner, cli;
+    let selected = invocation.session;
+    let signalExit;
+    let outputFailed = false;
+    const displayedReceipts = new Set();
+    const guard = (value) => {
+        if (credential && containsCredential(value, credential)) {
+            throw new ProductError('agent_execution', 'credential', 'Credential found in conversation data; preserve saved facts, do not replay.');
+        }
+    };
+    const write = async (value, prefix = '') => {
+        guard(value);
+        if (outputFailed)
+            return;
+        await new Promise((resolve, reject) => {
+            process.stdout.write(`${prefix}${JSON.stringify(value)}\n`, error => {
+                if (error)
+                    reject(new ProductError('agent_output', 'stdout', 'Output disconnected; owned execution is being closed.'));
+                else
+                    resolve();
+            });
+        });
+    };
+    const outputError = () => { outputFailed = true; cli?.close(); void owner?.close(); };
+    const terminate = () => { signalExit = 143; cli?.close(); void owner?.close(); };
+    const interrupt = () => {
+        void (async () => {
+            if (selected && owner) {
+                const page = await owner.read(selected, 0, 1);
+                if (page.activeTurnId !== null) {
+                    await owner.cancel({ sessionId: selected, turnId: page.activeTurnId });
+                    if (invocation.command === 'run')
+                        signalExit = 130;
+                    return;
+                }
+            }
+            signalExit = 130;
+            cli?.close();
+            await owner?.close();
+        })().catch(() => { signalExit = 130; cli?.close(); void owner?.close(); });
+    };
+    process.stdout.on('error', outputError);
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', terminate);
+    // Explicit per-product dispatcher. Closing it cannot close a borrowed/global pool.
+    const network = createProductTransport();
+    try {
+        store = await openProductStore(config.stateDir, true);
+        if (selected) {
+            const location = await restoreProductLocation(store, selected, config);
+            config = { ...config, ...location };
+            invocation = { ...invocation, config };
+        }
+        binding = createProductBinding(invocation, credential);
+        const activeStore = store;
+        const selectedLocation = { root: config.root, cwd: config.cwd };
+        const admitLocation = async (id) => {
+            const location = await restoreProductLocation(activeStore, id, config);
+            guard(location);
+            if (location.root !== selectedLocation.root || location.cwd !== selectedLocation.cwd)
+                throw new ProductError('agent_config', 'location', 'This UI is bound to a different location. Close the settled process and reopen with --session ID and fresh grants.');
+            return location;
+        };
+        const provider = createModelGateway({
+            endpoint: config.endpoint, model: config.model,
+            account: credential ? { kind: 'bearer', token: credential } : { kind: 'none' },
+            stream: config.stream, retry: { maxElapsedMs: config.modelTimeoutMs },
+            onObservation: connectModelObservations(observer),
+            // Use a locally owned network pool; no global connection or account state.
+            transport: network.transport,
+        });
+        owner = createExecutionOwner({
+            store, maxSteps: config.maxSteps, observer,
+            ...(selected ? { sessions: [{ id: selected, title: 'Explicit selection' }] } : {}),
+            agent: async (recording) => {
+                // ExecutionOwner creates this Agent for the admitted Turn. Bind to the
+                // recording's identity, never the UI's mutable selected Session.
+                const sessionId = recording.lastReceipt.sessionId;
+                const location = await admitLocation(sessionId);
+                const currentInvocation = { ...invocation, config: { ...config, ...location } };
+                const currentBinding = createProductBinding(currentInvocation, credential);
+                const guidance = createProjectGuidance({ ...location, sessionId });
+                const facts = createRuntimeFacts(currentInvocation, currentBinding.binding, sessionId, credential);
+                return createAgent({
+                    toolExecutor: createProductTools(currentBinding, guidance, currentInvocation, sessionId),
+                    contextBuilder: createContextBuilder({ sources: [facts, guidance.source] }),
+                    contextBudget: { capacity: config.contextBytes, reserveOutput: config.outputReserveBytes },
+                    observer,
+                    provider: { async complete(request, signal) {
+                            guard(request);
+                            const response = await provider.complete(request, signal);
+                            guard(response); // Do not persist/execute a credential echoed by the model.
+                            return response;
+                        } },
+                    recorder: { async record(event) { guard(event); await recording.record(event); } },
+                });
+            },
+        });
+        if (selected) {
+            try {
+                const saved = await store.load(selected);
+                guard(saved);
+                if (saved.recovery.disposition !== 'ready')
+                    throw new Error();
+            }
+            catch {
+                throw new ProductError('agent_storage', 'session', 'Select an existing ready Session in this state directory; inspect unsettled/unknown facts without replay.');
+            }
+        }
+        else
+            selected = (await createProductSession(owner, store, 'Agent session', selectedLocation)).id;
+        if (signalExit !== undefined || outputFailed)
+            return signalExit ?? 1;
+        if (invocation.command === 'run') {
+            await owner.submit(selected, invocation.input);
+            const evidence = await owner.settle(selected);
+            if (!evidence?.result || evidence.failure || evidence.result.recording.status !== 'recorded') {
+                await write({ status: 'not_fully_saved', lastConfirmedReceipt: evidence?.receipt,
+                    error: { code: 'agent_storage', field: 'recording',
+                        nextAction: 'Inspect the last confirmed receipt and stored facts. No automatic retry.' } });
+                return 1;
+            }
+            const saved = await store.load(selected).catch(() => undefined);
+            const confirmed = saved && evidence.result.recording.status === 'recorded'
+                && evidence.receipt?.digest === saved.digest && evidence.receipt.revision === saved.revision;
+            // Failure evidence is not a full-turn save receipt.
+            if (!confirmed) {
+                await write({ status: 'receipt_verification_failed', lastConfirmedReceipt: evidence.receipt,
+                    error: { code: 'agent_storage', field: 'recording',
+                        nextAction: 'Preserve the state directory and inspect confirmed facts.' } });
+                return 1;
+            }
+            await write({ configuration: publicConfiguration(config), binding: binding.binding,
+                projectAuthority: { allowMemoryWrite: invocation.allowMemoryWrite },
+                result: evidence.result, receipt: evidence.receipt,
+                observations: observer.query().records });
+            return signalExit ?? (evidence.result.reason === 'completed' ? 0 : evidence.result.reason === 'cancelled'
+                ? 130 : evidence.result.reason === 'budget_exhausted' ? 3 : 1);
+        }
+        const activeOwner = owner;
+        const catalogSafe = async (operation) => {
+            try {
+                const value = await operation();
+                guard(value);
+                return value;
+            }
+            catch (error) {
+                throw storageFailure(error);
+            }
+        };
+        const catalog = {
+            listSessions: options => catalogSafe(() => activeStore.listSessions(options)),
+            getSessionInfo: id => catalogSafe(() => activeStore.getSessionInfo(id)),
+            readHistory: (id, options) => catalogSafe(() => activeStore.readHistory(id, options)),
+            async renameSession(id, title, expected) {
+                guard(title);
+                return catalogSafe(() => activeStore.renameSession(id, title, expected));
+            },
+        };
+        const safe = async (operation) => {
+            try {
+                const value = await operation();
+                guard(value);
+                return value;
+            }
+            catch (error) {
+                if (error instanceof ProductError)
+                    throw error;
+                throw storageFailure(error);
+            }
+        };
+        const port = {
+            async create(title) {
+                guard(title);
+                if (!title.trim() || [...title.trim()].length > 200 || /[\p{Cc}\p{Cs}]/u.test(title))
+                    throw new ProductError('agent_config', 'title', 'Use 1..200 Unicode characters without controls.');
+                const item = await createProductSession(activeOwner, activeStore, title, selectedLocation);
+                await catalog.renameSession(item.id, title, 0);
+                return item;
+            },
+            list: (offset, limit) => safe(() => activeOwner.list(offset, limit)),
+            async submit(id, input) {
+                guard(input);
+                await admitLocation(id);
+                const scope = await safe(() => activeOwner.submit(id, input));
+                selected = id;
+                return scope;
+            },
+            cancel: scope => safe(() => activeOwner.cancel(scope)),
+            history: (id, offset, limit) => safe(() => activeOwner.history(id, offset, limit)),
+            subscribe: (id, callback) => activeOwner.subscribe(id, callback),
+            async read(id, after, limit) {
+                await admitLocation(id);
+                const page = await safe(() => activeOwner.read(id, after, limit));
+                selected = id;
+                // Replay is a read, never a join of the current execution promise.
+                // Historical terminal IDs cannot select another Turn's live evidence.
+                for (const record of page.records) {
+                    if (record.kind !== 'event' || record.event.data.type !== 'turn_ended')
+                        continue;
+                    const evidence = activeOwner.getSettledEvidence({ sessionId: id, turnId: record.event.turnId });
+                    if (!evidence?.receipt || evidence.result?.recording.status !== 'recorded' || evidence.failure
+                        || displayedReceipts.has(evidence.receipt.digest))
+                        continue;
+                    const saved = await activeStore.load(id);
+                    if (saved.digest === evidence.receipt.digest && saved.revision === evidence.receipt.revision) {
+                        displayedReceipts.add(evidence.receipt.digest);
+                        await write(evidence.receipt, '[saved receipt] ');
+                    }
+                }
+                return page;
+            },
+        };
+        await write({ configuration: publicConfiguration(config), binding: binding.binding,
+            projectAuthority: { allowMemoryWrite: invocation.allowMemoryWrite },
+            sessionId: selected, mode: 'local-tool-binding',
+            note: 'Original root/cwd are persisted atomically. Cross-location selection requires settled close and explicit reopen with fresh authority. Not an OS sandbox.' }, '[agent] ');
+        cli = await openCli({ sessions: port, catalog, input: process.stdin, output: process.stdout,
+            initialSessionId: selected, diagnostics: createInteractionDiagnostics(observer) });
+        if (signalExit !== undefined || outputFailed)
+            cli.close();
+        const ended = await cli.done;
+        // EOF/quit detaches UI only; the product owner must cancel/drain the actual
+        // execution before acknowledging shutdown or closing storage/network pools.
+        await owner.close();
+        const finalEvidence = await owner.settle(selected);
+        if (finalEvidence?.receipt && !displayedReceipts.has(finalEvidence.receipt.digest)) {
+            const saved = await store.load(selected).catch(() => undefined);
+            if (finalEvidence.result?.recording.status === 'recorded' && !finalEvidence.failure
+                && saved?.digest === finalEvidence.receipt.digest && saved.revision === finalEvidence.receipt.revision) {
+                await write(finalEvidence.receipt, '[saved receipt on close] ');
+            }
+            else
+                await write({ status: 'not_fully_saved', lastConfirmedReceipt: finalEvidence.receipt,
+                    nextAction: 'Inspect saved facts; no automatic retry.' }, '[agent close] ');
+        }
+        return signalExit ?? (['display-error', 'input-error'].includes(ended.reason) || outputFailed ? 1 : 0);
+    }
+    finally {
+        cli?.close();
+        try {
+            await owner?.close();
+        }
+        finally {
+            try {
+                await store?.close();
+            }
+            finally {
+                observer.close();
+                try {
+                    network.close();
+                }
+                finally {
+                    process.stdout.off('error', outputError);
+                    process.off('SIGINT', interrupt);
+                    process.off('SIGTERM', terminate);
+                }
+            }
+        }
+    }
+}

package/dist/nativeAgent/product/storage.js

@@ -0,0 +1,49 @@
+import { mkdir, chmod, lstat, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createSessionStore, createSqliteSessionBackend, SessionError, SessionMetadataSaveError } from '../index.js';
+import { ProductError } from './config.js';
+import { SessionSaveError } from '../session/index.js';
+/** Only fixed producer codes reach diagnostics; never title/cursor/cause text. */
+export function storageFailure(error) {
+    if (error instanceof ProductError)
+        return error;
+    const codes = ['cursor_stale', 'invalid_cursor', 'not_found', 'revision_conflict',
+        'read_failed', 'unsupported_format', 'corrupt_session', 'invalid_title', 'closed', 'metadata_save_failed', 'save_failed'];
+    const field = error instanceof SessionError && codes.includes(error.code) ? error.code : 'catalog';
+    const next = field === 'cursor_stale' || field === 'invalid_cursor'
+        ? 'Restart from the first page with the same store, Session ID and page limit.'
+        : error instanceof SessionSaveError
+            ? `Inspect getSessionInfo and load for Session ${error.sessionId}; preserve unknown effects, never blindly create again or switch IDs.`
+            : error instanceof SessionMetadataSaveError
+                ? `Read Session ${error.sessionId}'s exact title and metadata revision before another write; do not blindly retry.`
+                : 'Inspect the exact selected store and Session facts; no automatic retry or replay.';
+    return new ProductError('agent_storage', field, next, error instanceof SessionMetadataSaveError || error instanceof SessionSaveError ? 'unknown' : undefined, error instanceof SessionMetadataSaveError || error instanceof SessionSaveError ? error.sessionId : undefined);
+}
+/** A browsing command opens an existing file only; execution may create it.
+ * Both use the real producer's supported migration chain, never another ledger. */
+export async function openProductStore(directory, create) {
+    let store;
+    try {
+        if (create)
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error();
+        const filename = join(await realpath(directory), 'sessions.sqlite');
+        if (!create) {
+            const file = await lstat(filename);
+            if (!file.isFile() || file.isSymbolicLink())
+                throw new Error();
+        }
+        store = createSessionStore(createSqliteSessionBackend(filename));
+        if (create)
+            await chmod(filename, 0o600);
+        return store;
+    }
+    catch (error) {
+        await store?.close();
+        if (error instanceof SessionError)
+            throw storageFailure(error);
+        throw new ProductError('agent_storage', 'stateDir', 'Select a controlled state directory with a supported Agent database; browsing never creates one.');
+    }
+}

package/dist/nativeAgent/product/tools.js

@@ -0,0 +1,47 @@
+import { createToolExecutor } from '../index.js';
+/** Compose public capabilities, not producer-private registries.
+ * Coding calls retain the original factory's exact live lease and permission.
+ * Ordinary project tools acquire no coding resource/authority. */
+export function createProductTools(binding, guidance, invocation, sessionId) {
+    const codingNames = new Set(binding.tools.map(tool => tool.definition.name));
+    const tools = binding.tools.map(tool => ({
+        definition: tool.definition,
+        validate: args => tool.validate(args),
+        async execute(args, scope, signal, lease) {
+            if (lease === undefined)
+                return { ok: false, error: {
+                        code: 'missing_coding_environment', message: 'Coding resource was not acquired', effect: 'none'
+                    } };
+            return tool.execute(args, scope, signal, lease);
+        },
+    }));
+    tools.push(...guidance.tools);
+    return createToolExecutor({
+        tools: tools.filter(tool => invocation.config.tools.includes(tool.definition.name)),
+        environment: {
+            async acquire(call, signal) {
+                if (codingNames.has(call.call.name))
+                    return binding.environment.acquire(call, signal);
+                return { value: undefined, async release() { } };
+            },
+        },
+        permission: {
+            async check(call, lease, signal) {
+                if (codingNames.has(call.call.name)) {
+                    return lease === undefined ? { allowed: false, reason: 'Coding resource required' }
+                        : binding.permission.check(call, lease, signal);
+                }
+                if (signal.aborted || lease !== undefined || call.identity.sessionId !== sessionId)
+                    return { allowed: false, reason: 'Project Session scope does not match' };
+                const args = call.call.arguments;
+                const action = args !== null && typeof args === 'object' && !Array.isArray(args) ? args.action : undefined;
+                if (call.call.name === 'project_context' && ['inspect', 'load_skill', 'reference'].includes(String(action)))
+                    return { allowed: true };
+                if (call.call.name === 'project_memory' && (action === 'read'
+                    || (invocation.allowMemoryWrite && (action === 'replace' || action === 'delete'))))
+                    return { allowed: true };
+                return { allowed: false, reason: 'Project memory modification requires --allow-memory-write on this invocation' };
+            },
+        },
+    });
+}

package/dist/nativeAgent/product/transport.js

@@ -0,0 +1,54 @@
+import { Agent as HttpAgent, request as httpRequest } from 'node:http';
+import { Agent as HttpsAgent, request as httpsRequest } from 'node:https';
+import { Readable, addAbortSignal } from 'node:stream';
+/** One product-owned pool, no global fetch dispatcher. No redirects or retries.
+ * Gateway owns each Response reader; cancelling it destroys its Node response.
+ * Closing the pool after execution has settled releases idle owned sockets. */
+export function createProductTransport() {
+    const http = new HttpAgent({ keepAlive: true, maxSockets: 1 });
+    const https = new HttpsAgent({ keepAlive: true, maxSockets: 1 });
+    let closed = false;
+    return {
+        transport(endpoint, init) {
+            return new Promise((resolve, reject) => {
+                if (closed) {
+                    reject(new Error('Product transport closed'));
+                    return;
+                }
+                const secure = new URL(endpoint).protocol === 'https:';
+                const request = (secure ? httpsRequest : httpRequest)(endpoint, {
+                    method: init.method, headers: init.headers, signal: init.signal, agent: secure ? https : http,
+                }, response => {
+                    addAbortSignal(init.signal, response);
+                    try {
+                        const headers = new Headers();
+                        for (const [key, value] of Object.entries(response.headers)) {
+                            if (value !== undefined)
+                                headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+                        }
+                        const status = response.statusCode ?? 500;
+                        // Response forbids bodies on these statuses. Release the actual body
+                        // regardless; Gateway will classify the empty response truthfully.
+                        if ([204, 205, 304].includes(status)) {
+                            response.destroy();
+                            resolve(new Response(null, { status, headers }));
+                        }
+                        else
+                            resolve(new Response(Readable.toWeb(response), { status, headers }));
+                    }
+                    catch (error) {
+                        response.destroy();
+                        reject(error);
+                    }
+                });
+                request.on('error', reject);
+                request.end(init.body);
+            });
+        },
+        close() { if (!closed) {
+            closed = true;
+            http.destroy();
+            https.destroy();
+        } },
+    };
+}