@zq-silk/yui 2.1.0 → 2.2.0

package/dist/nativeAgent/product/config.js

@@ -0,0 +1,295 @@
+import { open, lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve, parse, relative, sep } from 'node:path';
+import { createLocalToolBinding } from '../index.js';
+export class ProductError extends Error {
+    code;
+    field;
+    nextAction;
+    effect;
+    sessionId;
+    constructor(code, field, nextAction, effect, sessionId) {
+        super(`${code}: ${field}; ${nextAction}`);
+        this.code = code;
+        this.field = field;
+        this.nextAction = nextAction;
+        this.effect = effect;
+        this.sessionId = sessionId;
+    }
+}
+export function productFailure(error) {
+    // Never format arbitrary thrown messages, causes, argv or HTTP response bodies.
+    return error instanceof ProductError
+        ? { code: error.code, field: error.field, nextAction: error.nextAction,
+            ...(error.effect ? { effect: error.effect } : {}),
+            ...(error.sessionId ? { sessionId: error.sessionId } : {}) }
+        : { code: 'agent_execution', field: 'runtime', nextAction: 'Inspect saved facts; do not replay uncertain effects.' };
+}
+const invalid = (field, action = 'Provide a supported explicit value and restart.') => {
+    throw new ProductError('agent_config', field, action);
+};
+const fields = ['adapter', 'endpoint', 'model', 'credentialRef', 'root', 'cwd', 'stateDir', 'tools',
+    'maxSteps', 'contextBytes', 'outputReserveBytes', 'modelTimeoutMs', 'stream', 'command'];
+const options = {
+    '--adapter': 'adapter', '--endpoint': 'endpoint', '--model': 'model', '--credential-ref': 'credentialRef',
+    '--root': 'root', '--cwd': 'cwd', '--state-dir': 'stateDir', '--tools': 'tools', '--max-steps': 'maxSteps',
+    '--context-bytes': 'contextBytes', '--output-reserve-bytes': 'outputReserveBytes',
+    '--model-timeout-ms': 'modelTimeoutMs', '--stream': 'stream', '--command-config': 'command',
+};
+export const productConfigurationOptions = [...Object.keys(options), '--config',
+    '--allow-write', '--allow-command', '--allow-memory-write', '--allow-http'];
+const environment = {
+    adapter: 'NATIVE_AGENT_ADAPTER', endpoint: 'NATIVE_AGENT_ENDPOINT', model: 'NATIVE_AGENT_MODEL',
+    credentialRef: 'NATIVE_AGENT_CREDENTIAL_REF', root: 'NATIVE_AGENT_ROOT', cwd: 'NATIVE_AGENT_CWD', stateDir: 'NATIVE_AGENT_STATE_DIR',
+    tools: 'NATIVE_AGENT_TOOLS', maxSteps: 'NATIVE_AGENT_MAX_STEPS', contextBytes: 'NATIVE_AGENT_CONTEXT_BYTES',
+    outputReserveBytes: 'NATIVE_AGENT_OUTPUT_RESERVE_BYTES', modelTimeoutMs: 'NATIVE_AGENT_MODEL_TIMEOUT_MS',
+    stream: 'NATIVE_AGENT_STREAM', command: 'NATIVE_AGENT_COMMAND_CONFIG',
+};
+const toolNames = ['read', 'list', 'find', 'search', 'write', 'edit', 'command', 'project_context', 'project_memory'];
+function text(value, field, max = 4096) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x1f\x7f]/u.test(value))
+        return invalid(field);
+    return value;
+}
+function integer(value, field, minimum, maximum) {
+    const number = typeof value === 'string' && /^\d+$/u.test(value) ? Number(value) : value;
+    if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < minimum || number > maximum)
+        return invalid(field);
+    return number;
+}
+async function configurationFile(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        if (!(await handle.stat()).isFile())
+            return invalid('config');
+        const buffer = Buffer.alloc(65537);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+        }
+        if (length > 65536)
+            return invalid('config', 'Use a JSON configuration no larger than 64 KiB.');
+        const object = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, length)));
+        if (!object || typeof object !== 'object' || Array.isArray(object) || object.schemaVersion !== 1
+            || Object.keys(object).some(key => key !== 'schemaVersion' && !fields.includes(key)))
+            return invalid('config');
+        return object;
+    }
+    catch {
+        return invalid('config', 'Select a readable, valid version-1 JSON configuration.');
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** Data-only explicit file; no discovery, scripts, account lookup or Yui configuration. */
+export async function resolveProductArguments(args, env, launchCwd) {
+    const [command, ...tail] = args;
+    if (!['check-config', 'start', 'run'].includes(command))
+        return invalid('command', 'Use check-config, start or run; see yui agent --help.');
+    const cli = {};
+    const seen = new Set();
+    let filePath, session, input;
+    let allowWrite = false, allowCommand = false, allowMemoryWrite = false, allowHttp = false;
+    for (let index = 0; index < tail.length; index++) {
+        const key = tail[index];
+        if (seen.has(key))
+            return invalid('arguments', 'Do not repeat options.');
+        seen.add(key);
+        if (key === '--json')
+            continue;
+        if (key === '--allow-write') {
+            allowWrite = true;
+            continue;
+        }
+        if (key === '--allow-command') {
+            allowCommand = true;
+            continue;
+        }
+        if (key === '--allow-memory-write') {
+            allowMemoryWrite = true;
+            continue;
+        }
+        if (key === '--allow-http') {
+            allowHttp = true;
+            continue;
+        }
+        if (!Object.hasOwn(options, key) && !['--config', '--session', '--input'].includes(key))
+            return invalid('arguments');
+        const value = tail[++index];
+        if (value === undefined)
+            return invalid('arguments');
+        if (key === '--config')
+            filePath = resolve(launchCwd, text(value, 'config'));
+        else if (key === '--session')
+            session = text(value, 'session', 128);
+        else if (key === '--input') {
+            if (!value.trim() || Buffer.byteLength(value) > 65536)
+                return invalid('input');
+            input = value;
+        }
+        else
+            cli[options[key]] = value;
+    }
+    if (command === 'start' && seen.has('--json'))
+        return invalid('arguments', 'Use run for JSON results; start is a line UI.');
+    if ((command === 'run') !== (input !== undefined))
+        return invalid('input', 'run requires --input; start/check-config do not accept it.');
+    if (session !== undefined && !/^[A-Za-z0-9_-]{1,128}$/u.test(session))
+        return invalid('session');
+    if (command === 'check-config' && session !== undefined)
+        return invalid('session');
+    const file = filePath ? await configurationFile(filePath) : {};
+    const defaults = { adapter: 'chat-completions', cwd: launchCwd,
+        tools: ['read', 'list', 'find', 'search', 'project_context', 'project_memory'], maxSteps: 8, contextBytes: 1048576,
+        outputReserveBytes: 0, modelTimeoutMs: 30000, stream: false };
+    const values = {};
+    const sources = {};
+    for (const field of fields) {
+        const environmentValue = env[environment[field]];
+        sources[field] = cli[field] !== undefined ? 'cli' : environmentValue !== undefined ? 'environment'
+            : file[field] !== undefined ? 'file' : 'default';
+        values[field] = sources[field] === 'cli' ? cli[field] : sources[field] === 'environment' ? environmentValue
+            : sources[field] === 'file' ? file[field] : defaults[field];
+    }
+    if (values.adapter !== 'chat-completions')
+        return invalid('adapter', 'Only chat-completions is supported.');
+    const endpoint = text(values.endpoint, 'endpoint');
+    try {
+        const url = new URL(endpoint);
+        if (url.username || url.password || url.search || url.hash
+            || !(url.protocol === 'https:' || (allowHttp && url.protocol === 'http:'
+                && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))))
+            return invalid('endpoint');
+    }
+    catch {
+        return invalid('endpoint', 'Use an exact HTTPS URL without userinfo/query/fragment, or explicit --allow-http for loopback fixtures.');
+    }
+    const credentialRef = text(values.credentialRef, 'credentialRef', 256);
+    if (credentialRef !== 'anonymous' && !/^env:[A-Za-z_][A-Za-z0-9_]*$/u.test(credentialRef))
+        return invalid('credentialRef', 'Use env:VARIABLE_NAME or explicit anonymous.');
+    const path = (field) => {
+        const value = text(values[field], field);
+        if (sources[field] === 'environment' && !isAbsolute(value))
+            return invalid(field, 'Environment paths must be absolute.');
+        return resolve(sources[field] === 'file' ? dirname(filePath) : launchCwd, value);
+    };
+    // Keep explicit provenance. On resume, absent paths must be replaced by the
+    // stored location BEFORE any filesystem admission (not launch-cwd defaults).
+    const cwd = path('cwd');
+    const root = sources.root === 'default' ? cwd : path('root');
+    if (!session)
+        await validateProductLocation({ root, cwd });
+    const stateDir = path('stateDir');
+    const selected = typeof values.tools === 'string' ? values.tools.split(',') : values.tools;
+    if (!Array.isArray(selected) || selected.length > toolNames.length
+        || selected.some(tool => !toolNames.includes(tool)) || new Set(selected).size !== selected.length)
+        return invalid('tools');
+    if (selected.some(tool => ['write', 'edit'].includes(tool)) && !allowWrite)
+        return invalid('tools', 'Pass --allow-write explicitly on this invocation to select write/edit.');
+    if (selected.includes('command') && !allowCommand)
+        return invalid('tools', 'Pass --allow-command explicitly on this invocation to select command; this is not a sandbox.');
+    const stream = values.stream === 'true' ? true : values.stream === 'false' ? false : values.stream;
+    if (typeof stream !== 'boolean')
+        return invalid('stream');
+    const contextBytes = integer(values.contextBytes, 'contextBytes', 1, 1048576);
+    const outputReserveBytes = integer(values.outputReserveBytes, 'outputReserveBytes', 0, contextBytes - 1);
+    let reviewedCommand = values.command;
+    if (typeof reviewedCommand === 'string') {
+        try {
+            if (Buffer.byteLength(reviewedCommand) > 65536)
+                return invalid('command');
+            reviewedCommand = JSON.parse(reviewedCommand);
+        }
+        catch {
+            return invalid('command', 'Provide a bounded JSON object containing explicit env and reviewed exact specs.');
+        }
+    }
+    if (reviewedCommand !== undefined && (!reviewedCommand || typeof reviewedCommand !== 'object'
+        || Array.isArray(reviewedCommand)))
+        return invalid('command');
+    return {
+        command: command, allowWrite, allowMemoryWrite,
+        ...(session ? { session } : {}), ...(input !== undefined ? { input } : {}),
+        config: { adapter: 'chat-completions', endpoint, model: text(values.model, 'model', 256), credentialRef,
+            root, cwd, stateDir, tools: [...selected], sources, stream, contextBytes, outputReserveBytes,
+            ...(reviewedCommand !== undefined ? { command: reviewedCommand } : {}),
+            maxSteps: integer(values.maxSteps, 'maxSteps', 1, 100),
+            modelTimeoutMs: integer(values.modelTimeoutMs, 'modelTimeoutMs', 1, 300000) },
+    };
+}
+/** Existence and symlink checks belong to this consumer, not stored metadata.
+ * Controlled local directories only; this is not a hostile-race OS sandbox. */
+export async function validateProductLocation(location) {
+    for (const field of ['root', 'cwd']) {
+        const value = location[field];
+        try {
+            if (!isAbsolute(value) || resolve(value) !== value || Buffer.byteLength(value) > 4096
+                || /[\p{Cc}\p{Cs}]/u.test(value))
+                throw new Error();
+            let current = value;
+            for (;;) {
+                if ((await lstat(current)).isSymbolicLink())
+                    throw new Error();
+                const parent = dirname(current);
+                if (current === parse(current).root)
+                    break;
+                current = parent;
+            }
+            if (!(await lstat(value)).isDirectory() || await realpath(value) !== value)
+                throw new Error();
+        }
+        catch {
+            return invalid(field, 'Select an existing canonical controlled directory without symlinks.');
+        }
+    }
+    const within = relative(location.root, location.cwd);
+    if (within === '..' || within.startsWith(`..${sep}`) || isAbsolute(within))
+        return invalid('cwd', 'cwd must be inside the explicitly selected root.');
+}
+/** One real producer factory owns tools, permission and live environments.
+ * The selected data is not authority until current invocation opt-ins admit it. */
+export function createProductBinding(invocation, credential) {
+    try {
+        const { config } = invocation;
+        return createLocalToolBinding({
+            root: config.root, cwd: config.cwd, allowWrite: invocation.allowWrite,
+            allowCommand: config.tools.includes('command'), command: config.command,
+            ...(credential ? { redact: [credential] } : {}),
+        });
+    }
+    catch {
+        return invalid('binding', 'Select a canonical controlled directory and valid reviewed command executable/argv/effect/env; settle old execution before rebuilding.');
+    }
+}
+/** Specs/argv and environment values are caller data, not public diagnostics. */
+export function publicConfiguration(config) {
+    const { command: _command, ...configuration } = config;
+    return configuration;
+}
+/** Resolved only in memory. Never returned in configuration, receipts or diagnostics. */
+export function resolveCredential(config, env) {
+    const token = resolveCredentialReference(config.credentialRef, env);
+    if (token && containsCredential(config, token))
+        return invalid('credentialRef', 'Keep the credential value separate from public configuration.');
+    return token;
+}
+export function resolveCredentialReference(ref, env) {
+    if (ref === 'anonymous')
+        return undefined;
+    if (!/^env:[A-Za-z_][A-Za-z0-9_]*$/u.test(ref))
+        return invalid('credentialRef');
+    const token = env[ref.slice(4)];
+    if (!token?.trim() || token.length > 4096 || /[\x00-\x1f\x7f]/u.test(token))
+        return invalid('credentialRef', 'Set the referenced credential environment variable to a valid nonempty value.');
+    return token;
+}
+/** Exact configured secret protection, not heuristic detection of arbitrary user secrets. */
+export function containsCredential(value, token) {
+    return typeof value === 'string' ? value.includes(token)
+        : value !== null && typeof value === 'object' && Object.entries(value)
+            .some(([key, child]) => key.includes(token) || containsCredential(child, token));
+}

package/dist/nativeAgent/product/facts.js

@@ -0,0 +1,30 @@
+import { createHash } from 'node:crypto';
+import { containsCredential, ProductError } from './config.js';
+/** Only validated current-invocation facts. No env values, credentials, account,
+ * persisted grants or command authority tokens. The real 82 check still rules. */
+export function createRuntimeFacts(invocation, binding, sessionId, credential) {
+    const facts = {
+        type: 'runtime-facts', sessionId, root: binding.root, cwd: binding.cwd,
+        tools: [...invocation.config.tools],
+        grants: { allowWrite: binding.allowWrite, allowCommand: binding.allowCommand,
+            allowMemoryWrite: invocation.allowMemoryWrite },
+        commands: binding.allowCommand ? (invocation.config.command?.specs ?? [])
+            .filter(spec => spec.effect === 'read' || binding.allowWrite)
+            .map(spec => ({ executable: spec.executable, argv: [...spec.argv], effect: spec.effect })) : [],
+    };
+    if (credential && containsCredential(facts, credential))
+        throw new ProductError('agent_config', 'runtimeFacts', 'Keep the configured credential separate from runtime facts.');
+    const content = JSON.stringify(facts);
+    const revision = createHash('sha256').update(content).digest('hex');
+    return {
+        id: 'product-runtime',
+        async load(scope, signal) {
+            if (signal.aborted || scope.sessionId !== sessionId)
+                throw new Error('Runtime fact scope unavailable');
+            // Data -> user material: configuration arguments never become system
+            // instructions. Required budget admission cannot silently drop these facts.
+            return [{ id: 'current-invocation', kind: 'data', source: 'product-runtime',
+                    content, revision, required: true }];
+        },
+    };
+}

package/dist/nativeAgent/product/index.js

@@ -0,0 +1,62 @@
+import { runProductRuntime } from './runtime.js';
+import { ProductError, resolveCredential, resolveProductArguments, createProductBinding, publicConfiguration } from './config.js';
+import { catalogCommands, runCatalogCommand } from './catalog.js';
+export { productFailure } from './config.js';
+export const productHelp = `Independent coding Agent (no Controller or Yui Home)
+  yui agent check-config [options]
+  yui agent start [options] [--session ID]
+  yui agent run [options] --input TEXT [--session ID]
+  yui agent sessions --state-dir PATH [--limit N] [--cursor CURSOR]
+  yui agent session-info|history --state-dir PATH --session ID [history: --limit N --cursor CURSOR]
+  yui agent rename --state-dir PATH --session ID --title JSON_STRING_OR_NULL --expected-metadata-revision N
+
+Required: --endpoint COMPLETE_URL --model NAME --credential-ref env:NAME|anonymous --state-dir PATH
+Optional: --config FILE --root PATH --cwd PATH --adapter chat-completions
+          --tools read,list,find,search,project_context,project_memory --max-steps 8
+          --context-bytes 1048576 --output-reserve-bytes 0
+          --model-timeout-ms 30000 --stream true|false
+Explicit opt-ins on EVERY invocation: --allow-write --allow-command --allow-memory-write --allow-http
+Only loopback HTTP is allowed. --command-config JSON supplies explicit env and reviewed specs.
+Command authorization is exact executable/argv/cwd/effect; no arbitrary model scripts.
+Complete env permits only PATH/LANG/LC_ALL/TZ; nothing is inherited.
+start uses the existing line UI: text, /cancel, /sessions [CURSOR], /history [CURSOR], /info,
+/rename EXPECTED_METADATA_REVISION JSON_STRING_OR_NULL, /use ID, /new, /quit.
+Ctrl-C cancels the active turn (or exits when idle); SIGTERM/EOF close owned execution.
+run emits result + exact save receipt; exit 0 completed, 1 error, 3 budget, 130 cancelled.
+CLI > NATIVE_AGENT_* environment > explicit version-1 JSON file > safe defaults.
+No automatic config discovery, account fallback, tool replay or inherited grants.
+Real local tools/permission/environment are created together; reopen rebuilds current authority.
+Project guidance is required; Skills load completely on request as project/user data.
+project_memory reads .agents/MEMORY.md; replace/delete need --allow-memory-write, not --allow-write.
+Catalog commands need only the existing state directory; reads never start execution.
+Duplicate titles are not identities. Stale cursors require an explicit first-page refresh.
+New Sessions atomically persist root/cwd (root defaults to cwd).
+Resume uses the saved location; explicit conflicts and legacy missing locations are refused.
+Paths must exist without symlinks, with cwd inside root. Saved paths grant no authority.
+`;
+export async function runProductCommand(args) {
+    const helpArguments = args.filter(argument => argument !== '--json');
+    if (helpArguments.length === 0 || (helpArguments.length === 1 && ['help', '--help', '-h'].includes(helpArguments[0]))) {
+        process.stdout.write(args.includes('--json') ? `${JSON.stringify({ help: productHelp })}\n` : productHelp);
+        return 0;
+    }
+    if (catalogCommands.some(command => command === args[0]))
+        return runCatalogCommand(args, process.env, process.cwd());
+    const invocation = await resolveProductArguments(args, process.env, process.cwd());
+    const credential = resolveCredential(invocation.config, process.env);
+    if (credential && invocation.input?.includes(credential)) {
+        throw new ProductError('agent_config', 'input', 'Do not submit the configured credential as conversation text.');
+    }
+    if (credential && invocation.session?.includes(credential)) {
+        throw new ProductError('agent_config', 'session', 'Do not use the configured credential as a Session identity.');
+    }
+    if (invocation.command === 'check-config') {
+        const binding = createProductBinding(invocation, credential);
+        process.stdout.write(`${JSON.stringify({ configuration: publicConfiguration(invocation.config),
+            binding: binding.binding, projectAuthority: { allowMemoryWrite: invocation.allowMemoryWrite },
+            credential: 'resolved-in-memory',
+            network: 'not-contacted', state: 'not-opened' })}\n`);
+        return 0;
+    }
+    return runProductRuntime(invocation, credential);
+}

package/dist/nativeAgent/product/location.js

@@ -0,0 +1,44 @@
+import { SessionSaveError } from '../session/index.js';
+import { ProductError, validateProductLocation } from './config.js';
+import { storageFailure } from './storage.js';
+/** A bounded detail is a location fact, never permission or execution history. */
+export async function restoreProductLocation(store, id, config) {
+    let detail;
+    try {
+        detail = await store.getSessionInfo(id);
+    }
+    catch (error) {
+        throw storageFailure(error);
+    }
+    if (!detail.location)
+        throw new ProductError('agent_storage', 'location', 'Saved location is missing; choose a new Session explicitly. Never guess or retrofit the old location.', undefined, id);
+    for (const field of ['root', 'cwd']) {
+        if (config.sources[field] !== 'default' && config[field] !== detail.location[field])
+            throw new ProductError('agent_config', field, 'Explicit location conflicts with this Session; select the original location or a new Session.');
+    }
+    await validateProductLocation(detail.location);
+    return detail.location;
+}
+/** Creation stays in the unique owner. A lost acknowledgment stops this attempt;
+ * reconcile reads by the attempted ID, never retry create or run effects here. */
+export async function createProductSession(owner, store, title, location) {
+    try {
+        return await owner.create(title, location);
+    }
+    catch (error) {
+        if (!(error instanceof SessionSaveError) || error.expectedRevision !== null)
+            throw storageFailure(error);
+        let confirmed = false;
+        try {
+            const detail = await store.getSessionInfo(error.sessionId);
+            const saved = await store.load(error.sessionId);
+            confirmed = detail.location?.root === location.root && detail.location.cwd === location.cwd
+                && saved.revision === 0 && detail.revision === 0 && detail.digest === saved.digest
+                && saved.recovery.disposition === 'ready';
+        }
+        catch { /* Read failure/not-found is not proof that no commit occurred. */ }
+        throw new ProductError('agent_storage', 'creation', confirmed
+            ? `Same-ID detail and load confirm empty Session ${error.sessionId} and original location. No execution started; explicitly reopen this Session ID.`
+            : `Creation of Session ${error.sessionId} remains unknown. Preserve this ID and inspect same-ID detail plus load; do not blindly recreate, switch IDs or replay.`, 'unknown', error.sessionId);
+    }
+}