@zq-silk/yui 2.0.0 → 2.2.0

package/dist/nativeAgent/model/responses.js

@@ -0,0 +1,263 @@
+import { isDeepStrictEqual } from 'node:util';
+import { createChatCompletionsAdapter } from './chatCompletions.js';
+import { ModelGatewayError, object, parse, protocol } from './errors.js';
+import { argumentsObject, bounded, counts, id, index, jsonBody, result, sseFrames, text } from './wire.js';
+const classify = createChatCompletionsAdapter().classify;
+function failure(error) {
+    const e = object(error);
+    const code = classify(429, { error: { code: e.code, type: e.type === 'error' ? undefined : e.type } });
+    // A 200/in-band failure is not a proven rejection; the gateway never replays it.
+    throw new ModelGatewayError(code === 'http' ? 'incomplete' : code);
+}
+function itemSemantics(item) {
+    if (item.type === 'function_call') {
+        if (Object.keys(item).some(k => !['type', 'id', 'status', 'call_id', 'name', 'arguments',
+            'async', 'caller', 'namespace', 'created_by'].includes(k)))
+            return protocol();
+        if ((item.async !== undefined && item.async !== false) || item.namespace != null
+            || (item.caller != null && object(item.caller).type !== 'direct'))
+            return protocol();
+    }
+    else if (item.type !== 'message' || item.phase != null
+        || Object.keys(item).some(k => !['type', 'id', 'status', 'role', 'content', 'phase', 'created_by'].includes(k))) {
+        // The kernel does not store assistant phase or server execution context.
+        return protocol();
+    }
+}
+function usage(value) {
+    const base = counts(value, { input_tokens: 'inputTokens', output_tokens: 'outputTokens', total_tokens: 'totalTokens' });
+    if (value == null)
+        return base;
+    const details = counts(object(value).input_tokens_details, { cached_tokens: 'cachedInputTokens', cache_write_tokens: 'cacheWriteInputTokens' });
+    return base || details ? { ...base, ...details } : undefined;
+}
+function outputText(value) {
+    const part = object(value);
+    if (Object.keys(part).some(k => !['type', 'text', 'annotations', 'logprobs'].includes(k))
+        || part.type !== 'output_text' || (part.annotations != null
+        && (!Array.isArray(part.annotations) || part.annotations.length)))
+        return protocol();
+    return bounded(text(part.text));
+}
+function itemValue(raw) {
+    const item = object(raw);
+    id(item.id);
+    itemSemantics(item);
+    // Function-call status is optional; omission does not replace the response terminal.
+    if (item.status !== 'completed' && !(item.type === 'function_call' && item.status === undefined)) {
+        throw new ModelGatewayError('incomplete');
+    }
+    if (item.type === 'function_call') {
+        return { content: '', call: { id: id(item.call_id), name: id(item.name),
+                arguments: argumentsObject(text(item.arguments)) } };
+    }
+    if (item.type !== 'message' || item.role !== 'assistant' || !Array.isArray(item.content)
+        || !item.content.length)
+        return protocol();
+    return { content: bounded(item.content.map(outputText).join('')) };
+}
+function finish(root) {
+    if (root.error != null)
+        failure(root.error);
+    if (root.status !== 'completed')
+        throw new ModelGatewayError('incomplete');
+    if (root.error != null || root.incomplete_details != null || !Array.isArray(root.output) || !root.output.length)
+        return protocol();
+    id(root.id);
+    const ids = new Set(), calls = [];
+    let content = '';
+    for (const raw of root.output) {
+        const item = object(raw), key = id(item.id);
+        if (ids.has(key))
+            return protocol();
+        ids.add(key);
+        const value = itemValue(item);
+        content = bounded(content + value.content);
+        if (value.call)
+            calls.push(value.call);
+    }
+    return result(content, calls);
+}
+export function createResponsesAdapter() {
+    return {
+        protocol: 'responses',
+        classify,
+        encode(request, model, stream, options) {
+            const input = [];
+            for (const m of request.messages) {
+                if (m.role === 'tool')
+                    input.push({ type: 'function_call_output', call_id: m.toolCallId,
+                        output: JSON.stringify(m.outcome) });
+                else if (m.role === 'assistant') {
+                    if (m.content)
+                        input.push({ role: 'assistant', content: m.content });
+                    for (const c of m.toolCalls)
+                        input.push({ type: 'function_call', call_id: c.id, name: c.name,
+                            arguments: JSON.stringify(c.arguments) });
+                }
+                else
+                    input.push({ role: m.role, content: [{ type: 'input_text', text: m.content }] });
+            }
+            return { model, stream, store: false, truncation: 'disabled', input,
+                ...(options?.maxOutputTokens !== undefined ? { max_output_tokens: options.maxOutputTokens } : {}),
+                ...(request.tools.length ? { tools: request.tools.map(t => ({
+                        type: 'function', name: t.name, description: t.description, parameters: t.inputSchema, strict: false,
+                    })) } : {}) };
+        },
+        async decode(body, streaming, emit) {
+            if (!streaming) {
+                const root = await jsonBody(body);
+                const reported = usage(root.usage);
+                if (reported)
+                    emit({ type: 'usage', usage: reported });
+                return { response: finish(root), ...(reported ? { usage: reported } : {}) };
+            }
+            let responseId, sequence;
+            const slots = new Map();
+            const slotFor = (e) => {
+                const slot = slots.get(index(e.output_index));
+                if (!slot || slot.done || (e.item_id !== undefined && e.item_id !== slot.item.id))
+                    return protocol();
+                return slot;
+            };
+            for await (const frame of sseFrames(body)) {
+                const e = object(parse(frame.data)), type = text(e.type);
+                if (frame.event !== undefined && frame.event !== type)
+                    return protocol();
+                if (e.sequence_number !== undefined) {
+                    const n = index(e.sequence_number, Number.MAX_SAFE_INTEGER);
+                    if (sequence !== undefined && n !== sequence + 1)
+                        return protocol();
+                    sequence = n;
+                }
+                if (type === 'error' || type === 'response.failed' || type === 'response.incomplete') {
+                    if (type !== 'error' && (!responseId || object(e.response).id !== responseId))
+                        return protocol();
+                    const reported = type === 'error' ? undefined : usage(object(e.response).usage);
+                    if (reported)
+                        emit({ type: 'usage', usage: reported });
+                    if (type === 'error')
+                        failure(e);
+                    if (object(e.response).error != null)
+                        failure(object(e.response).error);
+                    throw new ModelGatewayError('incomplete');
+                }
+                if (type === 'response.created') {
+                    if (responseId)
+                        return protocol();
+                    const r = object(e.response);
+                    if (r.status !== 'in_progress' || !Array.isArray(r.output) || r.output.length || r.error != null)
+                        return protocol();
+                    responseId = id(r.id);
+                    continue;
+                }
+                if (!responseId || (e.response_id !== undefined && e.response_id !== responseId))
+                    return protocol();
+                if (type === 'response.in_progress') {
+                    const r = object(e.response);
+                    if (r.id !== responseId || r.status !== 'in_progress' || r.error != null)
+                        return protocol();
+                }
+                else if (type === 'response.output_item.added') {
+                    const i = index(e.output_index), item = object(e.item);
+                    if (i !== slots.size || slots.has(i) || [...slots.values()].some(s => s.item.id === item.id))
+                        return protocol();
+                    id(item.id);
+                    itemSemantics(item);
+                    if (item.status !== 'in_progress' && !(item.type === 'function_call' && item.status === undefined))
+                        return protocol();
+                    if (item.type === 'function_call') {
+                        id(item.call_id);
+                        id(item.name);
+                        bounded(text(item.arguments), 64 * 1024);
+                        emit({ type: 'tool_delta', index: i, id: item.call_id, name: item.name });
+                    }
+                    else if (item.type !== 'message' || item.role !== 'assistant' || !Array.isArray(item.content) || item.content.length)
+                        return protocol();
+                    slots.set(i, { item, arguments: item.type === 'function_call' ? text(item.arguments) : '',
+                        argumentsDone: false, parts: new Map() });
+                }
+                else if (type === 'response.function_call_arguments.delta' || type === 'response.function_call_arguments.done') {
+                    const slot = slotFor(e);
+                    if (slot.item.type !== 'function_call' || slot.argumentsDone)
+                        return protocol();
+                    if (type.endsWith('.delta')) {
+                        const delta = text(e.delta);
+                        slot.arguments = bounded(slot.arguments + delta, 64 * 1024);
+                        emit({ type: 'tool_delta', index: index(e.output_index), arguments: delta });
+                    }
+                    else {
+                        if (slot.arguments !== text(e.arguments))
+                            return protocol();
+                        slot.argumentsDone = true;
+                    }
+                }
+                else if (type === 'response.content_part.added') {
+                    const slot = slotFor(e), i = index(e.content_index);
+                    if (slot.item.type !== 'message' || i !== slot.parts.size)
+                        return protocol();
+                    slot.parts.set(i, { text: outputText(e.part), textDone: false, done: false });
+                }
+                else if (type === 'response.output_text.delta' || type === 'response.output_text.done' || type === 'response.content_part.done') {
+                    const slot = slotFor(e), part = slot.parts.get(index(e.content_index));
+                    if (slot.item.type !== 'message' || !part || part.done)
+                        return protocol();
+                    if (type === 'response.output_text.delta') {
+                        if (part.textDone)
+                            return protocol();
+                        const delta = text(e.delta);
+                        part.text = bounded(part.text + delta);
+                        emit({ type: 'text_delta', text: delta });
+                    }
+                    else if (type === 'response.output_text.done') {
+                        if (part.textDone || part.text !== text(e.text))
+                            return protocol();
+                        part.textDone = true;
+                    }
+                    else {
+                        if (!part.textDone || part.text !== outputText(e.part))
+                            return protocol();
+                        part.done = true;
+                    }
+                }
+                else if (type === 'response.output_item.done') {
+                    const slot = slotFor(e), item = object(e.item);
+                    if (slot.item.id !== item.id || slot.item.type !== item.type)
+                        return protocol();
+                    itemValue(item);
+                    if (item.type === 'function_call') {
+                        if (!slot.argumentsDone || slot.arguments !== item.arguments
+                            || slot.item.call_id !== item.call_id || slot.item.name !== item.name)
+                            return protocol();
+                    }
+                    else {
+                        if (!slot.parts.size || [...slot.parts.values()].some(p => !p.done)
+                            || !Array.isArray(item.content) || item.content.length !== slot.parts.size
+                            || item.content.some((p, i) => outputText(p) !== slot.parts.get(i)?.text))
+                            return protocol();
+                    }
+                    slot.done = item;
+                }
+                else if (type === 'response.completed') {
+                    const root = object(e.response);
+                    if (root.id !== responseId)
+                        return protocol();
+                    const reported = usage(root.usage);
+                    if (reported)
+                        emit({ type: 'usage', usage: reported });
+                    if (root.id !== responseId || !slots.size || !Array.isArray(root.output)
+                        || root.output.length !== slots.size || root.output.some((item, i) => {
+                        const done = slots.get(i)?.done;
+                        return !done || !isDeepStrictEqual(itemValue(item), itemValue(done))
+                            || object(item).id !== done.id;
+                    }))
+                        return protocol();
+                    return { response: finish(root), ...(reported ? { usage: reported } : {}) };
+                }
+                else
+                    return protocol();
+            }
+            throw new ModelGatewayError('incomplete');
+        },
+    };
+}

package/dist/nativeAgent/model/types.js

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

package/dist/nativeAgent/model/wire.js

@@ -0,0 +1,73 @@
+import { object, parse, protocol } from './errors.js';
+export function text(value) { return typeof value === 'string' ? value : protocol(); }
+export function id(value) { const s = text(value); return s.trim() ? s : protocol(); }
+export function index(value, limit = 1024) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value < limit ? value : protocol();
+}
+export function bounded(value, limit = 512 * 1024) {
+    return Buffer.byteLength(value) <= limit ? value : protocol();
+}
+export function argumentsObject(value) {
+    const args = object(typeof value === 'string' ? parse(bounded(value, 64 * 1024)) : value);
+    // The gateway additionally validates depth, JSON values and total response size.
+    if (Buffer.byteLength(JSON.stringify(args)) > 64 * 1024)
+        return protocol();
+    return args;
+}
+export function result(content, calls) {
+    if (calls.length > 8 || new Set(calls.map(c => c.id)).size !== calls.length)
+        return protocol();
+    return calls.length ? { kind: 'tool_calls', content, calls } : { kind: 'final', content };
+}
+export function counts(value, mapping) {
+    if (value == null)
+        return undefined;
+    const source = object(value), usage = {};
+    for (const [wire, key] of Object.entries(mapping)) {
+        const n = source[wire];
+        if (n == null)
+            continue;
+        if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0)
+            return protocol();
+        usage[key] = n;
+    }
+    return Object.keys(usage).length ? usage : undefined;
+}
+export async function jsonBody(body) {
+    let source = '';
+    for await (const part of body)
+        source = bounded(source + part, 4 * 1024 * 1024);
+    return object(parse(source));
+}
+/** Framing only: native lifecycle remains the responsibility of each codec. */
+export async function* sseFrames(body) {
+    let line = '', data = [], event, afterCR = false;
+    for await (const part of body) {
+        for (const char of part) {
+            if (afterCR) {
+                afterCR = false;
+                if (char === '\n')
+                    continue;
+            }
+            if (char === '\r' || char === '\n') {
+                if (!line) {
+                    if (data.length)
+                        yield { ...(event ? { event } : {}), data: data.join('\n') };
+                    data = [];
+                    event = undefined;
+                }
+                else if (line === 'data')
+                    data.push('');
+                else if (line.startsWith('data:'))
+                    data.push(line.slice(5).replace(/^ /, ''));
+                else if (line.startsWith('event:'))
+                    event = line.slice(6).replace(/^ /, '');
+                line = '';
+                afterCR = char === '\r';
+            }
+            else
+                line += char;
+        }
+    }
+    // Unterminated frames are not a native completion.
+}

package/dist/nativeAgent/observability/index.js

@@ -0,0 +1,220 @@
+const integer = (value, max = Number.MAX_SAFE_INTEGER) => {
+    if (!Number.isSafeInteger(value) || value < 0 || value > max)
+        throw new Error('Invalid observation number');
+    return value;
+};
+const label = (value) => {
+    // Opaque correlation labels, never user text, paths, credentials or error details.
+    if (typeof value !== 'string' || !value.length || Buffer.byteLength(value) > 256) {
+        throw new Error('Invalid observation label');
+    }
+    return value;
+};
+function choice(value, allowed) {
+    if (!allowed.includes(value))
+        throw new Error('Invalid observation tag');
+    return value;
+}
+const statuses = ['completed', 'error', 'cancelled', 'unknown'];
+const reasons = ['completed', 'error', 'cancelled', 'budget_exhausted'];
+const effects = ['none', 'unknown'];
+const scopeOf = (value) => ({ sessionId: label(value.sessionId), turnId: label(value.turnId) });
+function usageOf(usage) {
+    const result = {};
+    for (const key of ['inputTokens', 'outputTokens', 'cachedInputTokens', 'cacheWriteInputTokens', 'totalTokens']) {
+        if (usage[key] !== undefined)
+            result[key] = integer(usage[key]);
+    }
+    return Object.freeze(result);
+}
+/**
+ * A bounded local projection, not a durable database. The injected clock should
+ * be monotonic milliseconds; durations describe observation arrival, not provider
+ * wall time. Replay/cache never acquire synthetic durations.
+ */
+export function createLocalObserver(options = {}) {
+    const capacity = integer(options.capacity ?? 512, 10_000);
+    if (!capacity)
+        throw new Error('Observation capacity must be positive');
+    const clock = options.clock ?? (() => performance.now());
+    const records = [];
+    const subscribers = new Set();
+    const pending = new Set();
+    let cursor = 0, evicted = 0, rejected = 0, consumerDropped = 0, consumerFailures = 0;
+    let closed = false;
+    function duration(draft, source, now) {
+        if (source !== 'live')
+            return;
+        const startType = draft.type === 'turn_ended' ? 'turn_started'
+            : draft.type === 'step_ended' ? 'step_started'
+                : draft.kind === 'model' && draft.type === 'ended' ? 'started'
+                    : draft.kind === 'event' && draft.type === 'message_appended' && draft.role === 'tool' ? 'tool_started' : undefined;
+        if (!startType)
+            return;
+        for (let i = records.length - 1; i >= 0; i--) {
+            const prior = records[i];
+            if (prior.source !== 'live' || prior.kind !== draft.kind ||
+                prior.sessionId !== draft.sessionId || prior.turnId !== draft.turnId ||
+                prior.step !== draft.step || prior.requestId !== draft.requestId || prior.attempt !== draft.attempt ||
+                prior.toolCallId !== draft.toolCallId)
+                continue;
+            // Repeated terminal reports cannot create another measured interval.
+            if (prior.type === draft.type)
+                return;
+            if (prior.type === startType)
+                return now >= prior.observedAt ? now - prior.observedAt : undefined;
+        }
+    }
+    function append(make, source) {
+        if (closed)
+            return false;
+        try {
+            if (!['live', 'replay', 'cached'].includes(source))
+                throw new Error('Invalid source');
+            const draft = make();
+            const now = clock();
+            if (!Number.isFinite(now))
+                throw new Error('Invalid clock');
+            const elapsed = duration(draft, source, now);
+            const record = Object.freeze({
+                ...draft, source, observedAt: now, cursor: ++cursor,
+                ...(elapsed === undefined ? {} : { durationMs: elapsed }),
+            });
+            if (records.length === capacity) {
+                records.shift();
+                evicted++;
+            }
+            records.push(record);
+            for (const subscriber of subscribers) {
+                if (subscriber.busy || pending.size >= 32) {
+                    consumerDropped++;
+                    continue;
+                }
+                subscriber.busy = true;
+                pending.add(subscriber.controller);
+                void Promise.resolve().then(() => {
+                    if (!subscriber.controller.signal.aborted) {
+                        return subscriber.consumer.export(record, subscriber.controller.signal);
+                    }
+                }).catch(() => { consumerFailures++; }).finally(() => {
+                    subscriber.busy = false;
+                    pending.delete(subscriber.controller);
+                });
+            }
+            return true;
+        }
+        catch {
+            // Never leak exception text (which may contain credentials), nor reject the
+            // kernel's required fact sink. Failure remains visible in health().
+            rejected++;
+            return false;
+        }
+    }
+    const observer = {
+        observeEvent(event, source = 'live') {
+            return append(() => {
+                const data = event.data;
+                const record = {
+                    ...scopeOf(event), kind: 'event', completeness: 'event',
+                    type: choice(data.type, ['turn_started', 'step_started', 'message_appended', 'tool_started', 'step_ended', 'turn_ended']),
+                    eventSeq: integer(event.seq),
+                    ...('step' in data && data.step !== undefined ? { step: integer(data.step) } : {}),
+                };
+                if (data.type === 'turn_ended') {
+                    return { ...record, status: choice(data.reason, reasons), ...(data.errorCode ? { errorCode: label(data.errorCode) } : {}) };
+                }
+                if (data.type === 'tool_started') {
+                    return { ...record, toolCallId: label(data.toolCallId), name: label(data.name) };
+                }
+                if (data.type === 'message_appended') {
+                    const message = data.message;
+                    if (message.role === 'tool') {
+                        return { ...record, role: message.role, toolCallId: label(message.toolCallId), name: label(message.name),
+                            ...(message.outcome.ok ? { status: 'completed' } : {
+                                status: 'error', effect: choice(message.outcome.error.effect, effects), errorCode: label(message.outcome.error.code),
+                            }) };
+                    }
+                    return { ...record, role: choice(message.role, ['system', 'user', 'assistant']) };
+                }
+                return record;
+            }, source);
+        },
+        observeSnapshot(result, source = 'live') {
+            return append(() => ({
+                ...scopeOf(result), kind: 'snapshot', completeness: 'snapshot', type: 'turn_result',
+                status: choice(result.reason, reasons), messageCount: result.messages.length,
+                unknownEffects: result.messages.filter(m => m.role === 'tool' && !m.outcome.ok && m.outcome.error.effect === 'unknown').length,
+                ...(result.error ? { errorCode: label(result.error.code) } : {}),
+            }), source);
+        },
+        observeModel(model, source = 'live') {
+            return append(() => ({
+                ...scopeOf(model), kind: 'model', completeness: 'event', type: choice(model.phase, ['started', 'ended', 'retry']),
+                step: integer(model.step), requestId: label(model.requestId), attempt: integer(model.attempt),
+                ...(model.status ? { status: choice(model.status, statuses) } : {}),
+                ...(model.effect ? { effect: choice(model.effect, effects) } : {}),
+                ...(model.errorCode ? { errorCode: label(model.errorCode) } : {}),
+                ...(model.usage ? { usage: usageOf(model.usage) } : {}),
+                ...(model.retryAfterMs === undefined ? {} : { retryAfterMs: integer(model.retryAfterMs) }),
+                ...(model.clientRequestId === undefined ? {} : { clientRequestId: label(model.clientRequestId) }),
+                ...(model.providerRequestId === undefined ? {} : { providerRequestId: label(model.providerRequestId) }),
+                ...(model.httpStatus === undefined ? {} : { httpStatus: integer(model.httpStatus, 599) }),
+                ...(model.elapsedMs === undefined ? {} : { elapsedMs: (() => {
+                        if (!Number.isFinite(model.elapsedMs) || model.elapsedMs < 0)
+                            throw new Error('Invalid elapsed time');
+                        return model.elapsedMs;
+                    })() }),
+            }), source);
+        },
+        observeStream(stream, source = 'live') {
+            return append(() => ({
+                ...scopeOf(stream), kind: 'stream', completeness: 'provisional', type: 'text_delta',
+                step: integer(stream.step), textCharacters: stream.text.length,
+                ...(stream.requestId ? { requestId: label(stream.requestId) } : {}),
+            }), source);
+        },
+        observe(event) { observer.observeEvent(event); },
+        query(query = {}) {
+            const after = integer(query.after ?? 0);
+            const limit = integer(query.limit ?? 100, 1000);
+            if (!limit)
+                throw new Error('Query limit must be positive');
+            const matches = records.filter(record => record.cursor > after &&
+                (query.sessionId === undefined || record.sessionId === query.sessionId) &&
+                (query.turnId === undefined || record.turnId === query.turnId) &&
+                (query.requestId === undefined || record.requestId === query.requestId) &&
+                (query.toolCallId === undefined || record.toolCallId === query.toolCallId));
+            const page = Object.freeze(matches.slice(0, limit));
+            return { records: page, nextCursor: matches.length > limit ? page[page.length - 1].cursor : Math.max(cursor, after),
+                throughCursor: cursor, evicted, gap: after < (records[0]?.cursor ?? 1) - 1, closed };
+        },
+        health() {
+            return Object.freeze({ retained: records.length, evicted, rejected, closed, subscribers: subscribers.size,
+                inFlight: pending.size, consumerDropped, consumerFailures });
+        },
+        subscribe(consumer) {
+            if (closed || subscribers.size >= 32)
+                throw new Error('Observer closed or subscriber limit reached');
+            const subscriber = { consumer, controller: new AbortController(), busy: false };
+            subscribers.add(subscriber);
+            return () => { subscribers.delete(subscriber); subscriber.controller.abort(); };
+        },
+        close() {
+            closed = true;
+            for (const subscriber of subscribers)
+                subscriber.controller.abort();
+            subscribers.clear();
+            // Unsubscribed but unsettled consumers are still owned cancellation targets.
+            for (const controller of pending)
+                controller.abort();
+        },
+    };
+    return observer;
+}
+/** Caller owns the destination and its lifecycle; errors are isolated by subscribe. */
+export function createJsonlExporter(write) {
+    return { async export(record, signal) {
+            if (!signal.aborted)
+                await write(`${JSON.stringify(record)}\n`, signal);
+        } };
+}

package/dist/nativeAgent/product/catalog.js

@@ -0,0 +1,82 @@
+import { isAbsolute, resolve } from 'node:path';
+import { ProductError, containsCredential, resolveCredentialReference } from './config.js';
+import { openProductStore, storageFailure } from './storage.js';
+export const catalogCommands = ['sessions', 'session-info', 'rename', 'history'];
+export const catalogCommandOptions = (command) => ['--state-dir', '--credential-ref',
+    ...(command === 'sessions' || command === 'history' ? ['--limit', '--cursor'] : []),
+    ...(command !== 'sessions' ? ['--session'] : []),
+    ...(command === 'rename' ? ['--title', '--expected-metadata-revision'] : [])];
+/** Data-only catalog command: no provider, owner, tools, account fallback or cwd. */
+export async function runCatalogCommand(args, env, cwd) {
+    const [command, ...tail] = args;
+    const invalid = () => {
+        throw new ProductError('agent_config', 'catalog', 'Use explicit --state-dir, exact --session ID, opaque --cursor and bounded --limit; rename requires JSON --title and --expected-metadata-revision.');
+    };
+    if (!catalogCommands.some(name => name === command))
+        return invalid();
+    const allowed = catalogCommandOptions(command);
+    const values = new Map();
+    for (let i = 0; i < tail.length; i++) {
+        const key = tail[i];
+        if (key === '--json' && !values.has(key)) {
+            values.set(key, 'true');
+            continue;
+        }
+        const value = tail[++i];
+        if (!allowed.includes(key) || values.has(key) || value === undefined
+            || Buffer.byteLength(value) > 4096 || /[\x00-\x1f\x7f]/u.test(value))
+            return invalid();
+        values.set(key, value);
+    }
+    const directory = values.get('--state-dir') ?? env.NATIVE_AGENT_STATE_DIR;
+    if (!directory?.trim() || Buffer.byteLength(directory) > 4096 || /[\x00-\x1f\x7f]/u.test(directory)
+        || (!values.has('--state-dir') && !isAbsolute(directory)))
+        return invalid();
+    const id = values.get('--session');
+    if (command !== 'sessions' && (!id || !/^[A-Za-z0-9_-]{1,128}$/u.test(id)))
+        return invalid();
+    const integer = (text, maximum, minimum) => {
+        if (!text || !/^\d+$/u.test(text) || !Number.isSafeInteger(Number(text))
+            || Number(text) < minimum || Number(text) > maximum)
+            return invalid();
+        return Number(text);
+    };
+    const limit = integer(values.get('--limit') ?? '20', 100, 1);
+    const options = { limit, ...(values.has('--cursor') ? { cursor: values.get('--cursor') } : {}) };
+    let title = null, revision = 0;
+    if (command === 'rename') {
+        try {
+            title = JSON.parse(values.get('--title') ?? '');
+        }
+        catch {
+            return invalid();
+        }
+        if (title !== null && (typeof title !== 'string' || !title.trim()
+            || [...title.trim()].length > 200 || /[\p{Cc}\p{Cs}]/u.test(title)))
+            return invalid();
+        revision = integer(values.get('--expected-metadata-revision'), Number.MAX_SAFE_INTEGER, 0);
+    }
+    const ref = values.get('--credential-ref') ?? env.NATIVE_AGENT_CREDENTIAL_REF;
+    const credential = ref === undefined ? undefined : resolveCredentialReference(ref, env);
+    const guard = (value) => {
+        if (credential && containsCredential(value, credential))
+            throw new ProductError('agent_execution', 'credential', 'Configured credential found in catalog data; no output or automatic replay.');
+    };
+    guard({ directory, id, title, options });
+    const store = await openProductStore(resolve(cwd, directory), false);
+    try {
+        const result = command === 'sessions' ? await store.listSessions(options)
+            : command === 'session-info' ? await store.getSessionInfo(id)
+                : command === 'history' ? await store.readHistory(id, options)
+                    : await store.renameSession(id, title, revision);
+        guard(result);
+        await new Promise((done, fail) => process.stdout.write(`${JSON.stringify(result)}\n`, error => error ? fail(new ProductError('agent_output', 'stdout', 'Read saved facts; do not repeat an uncertain rename.')) : done()));
+        return 0;
+    }
+    catch (error) {
+        throw storageFailure(error);
+    }
+    finally {
+        await store.close();
+    }
+}