@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/trajectory.d.ts

@@ -0,0 +1,34 @@
+import type { ModelAdapter, ModelRequestContext, RuntimeEvent } from './types.js';
+export type TrajectoryContext = ModelRequestContext;
+export interface TrajectoryOptions {
+    sessionId?: string;
+    /** Tests/embedding only; CLI storage is anchored to the installed package. */
+    directory?: string;
+    secrets?: readonly string[];
+    /**
+     * Extra facts recorded into the opening record, such as the `--debug` session banner.
+     * Values pass the same redaction as every other record.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * The session's file was opened by an earlier conversation: the opening record says
+     * `session.reopened` rather than `session.started`. The CLI passes nothing (one file per
+     * conversation); the app-server appends every run of a session to one file and says which
+     * process opened it each time.
+     */
+    reopened?: boolean;
+    onError?: (message: string) => void;
+}
+export interface SessionTrajectory {
+    sessionId: string;
+    path: string;
+    addSecrets(values: readonly string[]): void;
+    sanitize(value: unknown): unknown;
+    recordEvent(event: RuntimeEvent): Promise<void>;
+    /** Append one arbitrary sanitized record; `--debug` command accounting is written this way. */
+    record(type: string, data: Record<string, unknown>): Promise<void>;
+    wrap(adapter: ModelAdapter, context?: () => TrajectoryContext): ModelAdapter;
+    flush(): Promise<void>;
+}
+/** One adapter-level trajectory per CLI conversation, including all of its runs. */
+export declare function createSessionTrajectory(options?: TrajectoryOptions): Promise<SessionTrajectory>;

package/dist/src/trajectory.js

@@ -0,0 +1,426 @@
+import { randomUUID } from 'node:crypto';
+import { appendFile, chmod, mkdir, open, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+import { redactSecrets } from './memory/redaction.js';
+import { browserEventArguments, isBrowserToolName } from './browser-session.js';
+const credentialKey = /(?:api[_-]?key|token|secret|password|passwd|authorization|cookie|credential|private[_-]?key)/i;
+const privateReasoningKey = /^(?:reasoningContent|reasoning_content|reasoning|thinking|signature|thinkingSignature|providerContinuation)$/i;
+const MAX_STRUCTURE_DEPTH = 64;
+const STRUCTURE_LIMIT = '[REDACTED: structure exceeds sanitization limit]';
+function hasDuplicateJsonKeys(source) {
+    // JSON.parse discards earlier duplicate members. Returning the original text
+    // would restore those uninspected values, potentially including credentials.
+    // The input is already valid JSON; tokenize strings and container boundaries
+    // to compare decoded keys within each object without reimplementing parsing.
+    const scopes = [];
+    const tokens = /"(?:\\[\s\S]|[^"\\])*"|[{}\[\]]/g;
+    for (const token of source.matchAll(tokens)) {
+        if (token[0] === '{')
+            scopes.push(new Set());
+        else if (token[0] === '[')
+            scopes.push(undefined);
+        else if (token[0] === '}' || token[0] === ']')
+            scopes.pop();
+        else {
+            let next = token.index + token[0].length;
+            while (next < source.length && /[ \t\r\n]/.test(source[next]))
+                next++;
+            if (source[next] !== ':')
+                continue;
+            const keys = scopes.at(-1);
+            const key = JSON.parse(token[0]);
+            if (keys.has(key))
+                return true;
+            keys.add(key);
+        }
+    }
+    return false;
+}
+function serializeSanitizedJson(source, parsed, sanitized) {
+    // Parsing is required to inspect nested secrets, but serialization alone can
+    // change model-visible whitespace, numeric spelling, escapes and key order.
+    // Preserve the exact original evidence whenever sanitation made no change.
+    if (!isDeepStrictEqual(parsed, sanitized))
+        return JSON.stringify(sanitized);
+    if (hasDuplicateJsonKeys(source))
+        return '[REDACTED: duplicate JSON keys cannot be sanitized]';
+    return source;
+}
+/**
+ * Discard a JSONL record left half-written by a terminated process before a resumed run
+ * appends its opening marker. Reading backwards in bounded blocks avoids loading an entire
+ * long-lived session into memory. Never rewrite complete lines or change the live CLI path
+ * (which starts a fresh trajectory and does not pass `reopened`).
+ */
+async function repairTrajectoryTail(path) {
+    const handle = await open(path, 'r+');
+    try {
+        const size = (await handle.stat()).size;
+        if (size === 0)
+            return;
+        const chunk = Buffer.allocUnsafe(8192);
+        let end = size;
+        while (end > 0) {
+            const start = Math.max(0, end - chunk.length);
+            const length = end - start;
+            const { bytesRead } = await handle.read(chunk, 0, length, start);
+            if (bytesRead !== length)
+                throw new Error('Could not read the trajectory tail');
+            const lastLine = chunk.subarray(0, length).lastIndexOf(10); // LF
+            if (lastLine !== -1) {
+                const complete = start + lastLine + 1;
+                if (complete !== size)
+                    await handle.truncate(complete);
+                return;
+            }
+            end = start;
+        }
+        // The only line was interrupted before its newline; retain no invalid prefix.
+        await handle.truncate(0);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** One adapter-level trajectory per CLI conversation, including all of its runs. */
+export async function createSessionTrajectory(options = {}) {
+    const sessionId = options.sessionId ?? randomUUID();
+    if (sessionId !== sessionId.trim() || !/^[a-zA-Z0-9_-]{1,64}$/.test(sessionId))
+        throw new Error('Invalid trajectory session ID');
+    const modulePath = await realpath(fileURLToPath(import.meta.url));
+    const directory = options.directory ?? join(resolve(dirname(modulePath), '..', '..'), '.andorracode', 'trajectories');
+    const path = join(directory, `${sessionId}.jsonl`);
+    let secrets = [...new Set([
+            ...Object.entries(process.env).filter(([key]) => credentialKey.test(key)).map(([, value]) => value ?? ''),
+            ...(options.secrets ?? []),
+        ].filter(Boolean))].sort((a, b) => b.length - a.length);
+    // Browser inputs are private even when they are too short for the ambient
+    // credential heuristics. Keep them local to this conversation, never global.
+    const browserSecrets = new Set();
+    const browserInputSecrets = new Set();
+    function rememberBrowserSecret(value) {
+        if (!value || browserInputSecrets.has(value))
+            return;
+        browserInputSecrets.add(value);
+        // A model can quote an input inside prose/code fences, where whole-string
+        // JSON parsing cannot recover it. Track escaped forms through the same
+        // bounded encoding depth as structured sanitation, without the delimiters.
+        for (let depth = 0; depth <= 8; depth++) {
+            browserSecrets.add(value);
+            if (depth === 8 || value.length > 8 * 1024 * 1024)
+                break;
+            const escaped = JSON.stringify(value).slice(1, -1);
+            if (escaped === value || escaped.length > 8 * 1024 * 1024)
+                break;
+            value = escaped;
+        }
+    }
+    function collectBrowserSecrets(value, browser = false, privateValue = false, jsonDepth = 0, depth = 0, seen = new WeakSet()) {
+        if (depth >= MAX_STRUCTURE_DEPTH)
+            return;
+        if (typeof value === 'string') {
+            if (privateValue)
+                rememberBrowserSecret(value);
+            const first = value.trimStart()[0];
+            if (jsonDepth < 8 && value.length <= 8 * 1024 * 1024 && ['{', '[', '"'].includes(first)) {
+                try {
+                    collectBrowserSecrets(JSON.parse(value), browser, privateValue, jsonDepth + 1, depth + 1, seen);
+                }
+                catch { /* Invalid arguments are replaced by the existing projection. */ }
+            }
+            return;
+        }
+        if (!value || typeof value !== 'object' || seen.has(value))
+            return;
+        seen.add(value);
+        try {
+            const isBrowserCall = typeof value.name === 'string' && isBrowserToolName(value.name);
+            for (const [key, entry] of Object.entries(value)) {
+                collectBrowserSecrets(entry, browser || (isBrowserCall && key === 'arguments'), privateValue || (browser && key === 'value'), jsonDepth, depth + 1, seen);
+            }
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    function redactBrowserSecrets(value) {
+        for (const secret of [...browserSecrets].sort((a, b) => b.length - a.length))
+            value = value.split(secret).join('[REDACTED]');
+        return value;
+    }
+    const activeContainers = new WeakSet();
+    function sanitizeBrowserArguments(value, jsonDepth, structureDepth) {
+        if (structureDepth >= MAX_STRUCTURE_DEPTH)
+            return STRUCTURE_LIMIT;
+        if (typeof value === 'string') {
+            if (jsonDepth >= 8 || value.length > 8 * 1024 * 1024)
+                return '[REDACTED: browser arguments exceed sanitization limit]';
+            let parsed;
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                // A truncated/malformed call can still contain a credential. Without a
+                // parsed object we cannot safely identify the input value to remove.
+                return '[REDACTED: invalid browser arguments]';
+            }
+            if (parsed && typeof parsed === 'object') {
+                return serializeSanitizedJson(value, parsed, sanitizeBrowserArguments(parsed, jsonDepth + 1, structureDepth + 1));
+            }
+            return sanitize(browserEventArguments(value), jsonDepth, structureDepth);
+        }
+        // Use the same recursive projection as raw run events. Generic `value`
+        // keys outside browser arguments remain ordinary diagnostic data.
+        return sanitize(browserEventArguments(value), jsonDepth, structureDepth);
+    }
+    function isBrowserSnapshot(value) {
+        return !!value && typeof value === 'object' && !Array.isArray(value)
+            && typeof value.sessionId === 'string'
+            && Array.isArray(value.elements);
+    }
+    function isBrowserTabList(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return false;
+        const data = value;
+        return Object.keys(data).length === 2 && typeof data.sessionId === 'string' && Array.isArray(data.tabs)
+            && data.tabs.every(tab => tab && typeof tab === 'object' && !Array.isArray(tab)
+                && Object.keys(tab).length === 4 && typeof tab.tabId === 'string' && typeof tab.active === 'boolean'
+                && typeof tab.url === 'string' && typeof tab.title === 'string');
+    }
+    function sanitizeBrowserOutput(value, jsonDepth, structureDepth) {
+        if (structureDepth >= MAX_STRUCTURE_DEPTH)
+            return STRUCTURE_LIMIT;
+        const invalid = '[REDACTED: invalid browser observation]';
+        const project = (parsed) => {
+            if (isBrowserSnapshot(parsed))
+                return sanitize(parsed, jsonDepth + 1, structureDepth + 1);
+            if (isBrowserTabList(parsed))
+                return sanitize(parsed, jsonDepth + 1, structureDepth + 1);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return invalid;
+            const data = parsed;
+            const keys = Object.keys(data);
+            const exact = (expected) => keys.length === expected.length && expected.every(key => Object.hasOwn(data, key));
+            const withOptionalTab = (expected) => exact(expected)
+                || (exact([...expected, 'tabId']) && typeof data.tabId === 'string');
+            const screenshot = withOptionalTab(['sessionId', 'screenshotId', 'bytes', 'width', 'height'])
+                && typeof data.screenshotId === 'string'
+                && ['bytes', 'width', 'height'].every(key => Number.isSafeInteger(data[key]) && data[key] > 0);
+            const closed = withOptionalTab(['sessionId', 'closed']) && data.closed === true;
+            // Event projections contain only host metadata. Any extra page-controlled
+            // field or wrong-shaped JSON must not fall back to generic sanitation.
+            const eventMetadata = exact(['sessionId']) || (exact(['sessionId', 'screenshotId']) && typeof data.screenshotId === 'string');
+            return typeof data.sessionId === 'string' && (screenshot || closed || eventMetadata)
+                ? sanitize(parsed, jsonDepth + 1, structureDepth + 1) : invalid;
+        };
+        if (typeof value !== 'string')
+            return project(value);
+        if (jsonDepth >= 8 || value.length > 8 * 1024 * 1024)
+            return '[REDACTED: browser observation exceeds sanitization limit]';
+        try {
+            const parsed = JSON.parse(value);
+            const projected = project(parsed);
+            return projected === invalid ? invalid : serializeSanitizedJson(value, parsed, projected);
+        }
+        catch {
+            return '[REDACTED: invalid browser observation]';
+        }
+    }
+    function sanitizeMessages(value, jsonDepth, structureDepth) {
+        if (structureDepth >= MAX_STRUCTURE_DEPTH)
+            return STRUCTURE_LIMIT;
+        if (!Array.isArray(value))
+            return sanitize(value, jsonDepth, structureDepth);
+        const browserCalls = new Set();
+        return value.map(message => {
+            // Call IDs are unique only within one assistant response. Rebuild the
+            // association at each assistant boundary so later reuse cannot redact
+            // unrelated observations (or retroactively classify earlier ones).
+            if (message?.role === 'assistant') {
+                browserCalls.clear();
+                for (const call of Array.isArray(message.toolCalls) ? message.toolCalls : []) {
+                    if (typeof call?.name === 'string' && isBrowserToolName(call.name))
+                        browserCalls.add(call.id);
+                }
+            }
+            if (message?.role === 'tool' && browserCalls.has(message.toolCallId)) {
+                return sanitize({ ...message, content: sanitizeBrowserOutput(message.content, jsonDepth, structureDepth + 2) }, jsonDepth, structureDepth + 1);
+            }
+            return sanitize(message, jsonDepth, structureDepth + 1);
+        });
+    }
+    function sanitize(value, jsonDepth = 0, structureDepth = 0) {
+        // JSON decoding depth alone does not bound nested arrays/objects within one
+        // payload. Replace only the over-deep branch, keeping this and future
+        // records writable; never return the uninspected live value.
+        if (structureDepth >= MAX_STRUCTURE_DEPTH)
+            return STRUCTURE_LIMIT;
+        if (typeof value === 'string') {
+            // Compaction embeds JSON observations inside a serialized history object,
+            // and previous summaries may add more serialization layers. Traverse all
+            // JSON containers/encoded strings, not only top-level browser snapshots.
+            // Fail closed on oversized or excessively encoded data, rather than
+            // retaining an uninspected payload or doing unbounded repeated parsing.
+            const first = value.trimStart()[0];
+            if (first === '{' || first === '[' || first === '"') {
+                if (jsonDepth >= 8 || value.length > 8 * 1024 * 1024)
+                    return '[REDACTED: JSON exceeds sanitization limit]';
+                let parsed;
+                let isJson = false;
+                try {
+                    parsed = JSON.parse(value);
+                    isJson = true;
+                }
+                catch { /* Ordinary diagnostic text is not JSON. */ }
+                if (isJson)
+                    return redactBrowserSecrets(serializeSanitizedJson(value, parsed, sanitize(parsed, jsonDepth + 1, structureDepth + 1)));
+            }
+            let text = redactBrowserSecrets(value);
+            for (const secret of secrets) {
+                // Short placeholder env values (e.g. "no") must not corrupt identifiers.
+                if (secret.length < 4)
+                    text = text.replace(new RegExp(`(?<![A-Za-z0-9_])${secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_])`, 'g'), '[REDACTED]');
+                else
+                    text = text.split(secret).join('[REDACTED]');
+            }
+            return redactSecrets(text).text;
+        }
+        if (value && typeof value === 'object') {
+            if (isBrowserTabList(value)) {
+                // A page can reflect private input in its title or URL. Preserve only
+                // host-owned tab identities and selection, even in copied histories.
+                return {
+                    sessionId: sanitize(value.sessionId, jsonDepth, structureDepth + 1),
+                    tabs: value.tabs.map(tab => ({ tabId: sanitize(tab.tabId, jsonDepth, structureDepth + 2), active: tab.active })),
+                    pageContent: '[REDACTED]',
+                };
+            }
+            if (isBrowserSnapshot(value)) {
+                // A filled value can be reflected anywhere by page script: body text,
+                // URLs, titles, errors, labels, selectors, or newly added fields. Keep
+                // only host-owned identity/count metadata in persisted observations.
+                // This projection also protects copied/compacted snapshots when the
+                // originating fill or tool call is no longer present in the history.
+                // Live tool results and provider requests retain their exact content.
+                return {
+                    sessionId: sanitize(value.sessionId, jsonDepth, structureDepth + 1),
+                    observation: 'browser_snapshot',
+                    elementCount: value.elements.length,
+                    errorCount: Array.isArray(value.errors) ? value.errors.length : 0,
+                    pageContent: '[REDACTED]',
+                };
+            }
+            // Retain the existing visible error for genuinely unserializable cycles,
+            // rather than confusing them with a valid but deeply nested JSON value.
+            if (activeContainers.has(value))
+                throw new TypeError('Circular trajectory data');
+            activeContainers.add(value);
+            try {
+                if (Array.isArray(value))
+                    return value.map(entry => sanitize(entry, jsonDepth, structureDepth + 1));
+                return Object.fromEntries(Object.entries(value)
+                    // Envelope-only private metadata may be omitted, but removal from encoded
+                    // model-visible JSON must leave a marker so exact replay fails closed.
+                    .filter(([key, entry]) => jsonDepth > 0 || (!privateReasoningKey.test(key) && (key !== 'images' || typeof entry === 'number')))
+                    .map(([key, entry]) => [jsonDepth > 0 ? redactBrowserSecrets(key) : key, privateReasoningKey.test(key) || (key === 'images' && typeof entry !== 'number') ? '[REDACTED: private metadata]'
+                        : credentialKey.test(key) && !/Tokens$/.test(key) ? '[REDACTED]'
+                            : key === 'arguments' && typeof value.name === 'string' && isBrowserToolName(value.name) ? sanitizeBrowserArguments(entry, jsonDepth, structureDepth + 1)
+                                : ['messages', 'retiredMessages', 'latestRetainedEvidence'].includes(key) ? sanitizeMessages(entry, jsonDepth, structureDepth + 1)
+                                    : key === 'output' && typeof value.name === 'string' && isBrowserToolName(value.name) ? sanitizeBrowserOutput(entry, jsonDepth, structureDepth + 1)
+                                        : sanitize(entry, jsonDepth, structureDepth + 1)]));
+            }
+            finally {
+                activeContainers.delete(value);
+            }
+        }
+        return value;
+    }
+    let unavailable = false;
+    const report = (error) => {
+        if (unavailable)
+            return;
+        unavailable = true;
+        const message = `Session trajectory unavailable at ${path}: ${sanitize(error instanceof Error ? error.message : String(error))}`;
+        try {
+            (options.onError ?? (text => process.stderr.write(`${text}\n`)))(message);
+        }
+        catch {
+            process.stderr.write(`${message}\n`);
+        }
+    };
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await appendFile(path, '', { mode: 0o600 });
+        if (options.reopened === true)
+            await repairTrajectoryTail(path);
+        // POSIX modes are best effort on Windows; inherited Windows ACLs still apply.
+        await chmod(path, 0o600).catch(() => undefined);
+    }
+    catch (error) {
+        report(error);
+    }
+    let pending = Promise.resolve();
+    function record(type, data) {
+        let entry;
+        try {
+            // Discover inputs before serializing any sibling text (or earlier message
+            // in the same history). Projection alone cannot protect later echoes.
+            // Keep learning for live consumers even when disk recording has failed.
+            collectBrowserSecrets(data);
+            if (unavailable)
+                return pending;
+            entry = JSON.stringify(sanitize({ type, time: new Date().toISOString(), sessionId, ...data })) + '\n';
+        }
+        catch (error) {
+            report(error);
+            return pending;
+        }
+        pending = pending.then(async () => {
+            if (!unavailable)
+                await appendFile(path, entry, { mode: 0o600 });
+        }).catch(report);
+        return pending;
+    }
+    await record(options.reopened === true ? 'session.reopened' : 'session.started', options.meta ?? {});
+    return {
+        sessionId, path,
+        sanitize,
+        addSecrets(values) { secrets = [...new Set([...secrets, ...values.filter(Boolean)])].sort((a, b) => b.length - a.length); },
+        recordEvent: event => record('runtime.event', { event }),
+        record: (type, data) => record(type, data),
+        flush: () => pending,
+        wrap(adapter, context = () => ({})) {
+            return {
+                ...(adapter.listModels ? { listModels: (signal) => adapter.listModels(signal) } : {}),
+                async generate(request) {
+                    const requestId = randomUUID();
+                    // Snapshot primitive context before the first await: shared adapters can
+                    // serve graph branches concurrently and finish them in either order.
+                    const { context: requestContext } = request;
+                    const metadata = { ...context(), ...requestContext, requestId, model: request.model };
+                    await record('model.request', { ...metadata, messages: request.messages, tools: request.tools });
+                    const started = performance.now();
+                    try {
+                        // The request travels whole: `context` is the invocation identity the
+                        // inner layers read — the reasoning wrapper stamps it on the reasoning
+                        // events it publishes — not provider payload, which the wire body builds
+                        // from explicit fields. Only the record above consumes the snapshot.
+                        const response = await adapter.generate(request);
+                        const { text, toolCalls, usage, stopReason } = response;
+                        await record('model.response', { ...metadata, durationMs: performance.now() - started, text, toolCalls, usage, stopReason });
+                        return response;
+                    }
+                    catch (error) {
+                        await record('model.error', {
+                            ...metadata, durationMs: performance.now() - started, aborted: request.signal.aborted,
+                            error: { name: error instanceof Error ? error.name : 'Error', message: error instanceof Error ? error.message : String(error) },
+                        });
+                        throw error;
+                    }
+                },
+            };
+        },
+    };
+}

package/dist/src/transcript.d.ts

@@ -0,0 +1,45 @@
+import type { RuntimeEvent } from './types.js';
+import { type ToolCallStamp } from './tool-call-clock.js';
+/**
+ * Render an event-supplied duration for display without ever printing `NaN` or `undefined`.
+ *
+ * The transcript is both a user surface and a log: an absent or unusable `durationMs` must leave
+ * the line byte-identical to the output produced before durations existed, so the caller appends
+ * the rendered text only when this returns a non-empty suffix.
+ */
+export declare function formatDurationSuffix(data: Record<string, unknown>): string;
+/** Describe the action without dumping file contents or graph handoff payloads. */
+export declare function describeTool(name: string, value: unknown): string;
+export interface TranscriptEntry {
+    text: string;
+    detail?: string;
+    toolCall?: ToolCallStamp;
+}
+/**
+ * Colors are selected from trusted presentation markers, never provider ANSI.
+ *
+ * Returns a 256-color index for neutral and semantic tones, or a ready SGR sequence for
+ * the brand accent, which needs truecolor on supporting terminals.
+ * @param text - one rendered transcript line.
+ * @returns a paint color: a palette index or an SGR parameter string.
+ */
+export declare function transcriptColor(text: string): number | string;
+export interface RunResultView {
+    id: string;
+    status: string;
+    summary: string;
+    tests?: readonly string[];
+}
+/**
+ * Render a finished run for the transcript: the completion summary as rendered markdown, the
+ * checks the agent reports under their own heading, and the run line last.
+ *
+ * The summary is the agent's final answer and is written in markdown like every other agent
+ * message, so it goes through the same renderer — a fence or heading printed verbatim reads as
+ * a broken response. Each check is one line (the model is told to keep it so; a stray newline is
+ * folded), and the heading is only drawn when there is a check to put under it. A collapsed code
+ * block returns the full rendering as `detail`, with the same checks and run line, so Ctrl+O
+ * shows the whole answer in place.
+ */
+export declare function formatRunResult(result: RunResultView): TranscriptEntry;
+export declare function formatEvent(event: RuntimeEvent): TranscriptEntry | undefined;