@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/paged-transcript.js

@@ -0,0 +1,205 @@
+import { closeSync, ftruncateSync, mkdtempSync, openSync, readSync, rmSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const CACHE_ENTRIES = 8;
+const CACHE_CHARS = 512 * 1024;
+/** Session-only disk transcript: bodies are paged, small ordering/timing metadata remains live. */
+export class PagedTranscript {
+    options;
+    entries = [];
+    cache = new Map();
+    cachedChars = 0;
+    fd;
+    folder;
+    path;
+    offset = 0;
+    diskFailed = false;
+    closed = false;
+    omitted = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get diagnostics() {
+        return { entries: this.entries.length, cacheEntries: this.cache.size, cacheChars: this.cachedChars, path: this.path, omitted: this.omitted };
+    }
+    append(value) {
+        if (this.closed)
+            return;
+        const { text, detail, ...metadata } = value;
+        const body = { text, ...(detail === undefined ? {} : { detail }) };
+        const entry = { metadata, offset: this.offset, bytes: 0 };
+        try {
+            if (this.diskFailed)
+                throw new Error('spool unavailable');
+            if (this.fd === undefined) {
+                this.folder = mkdtempSync(join(this.options.temporaryDirectory ?? tmpdir(), 'andorra-transcript-'));
+                this.path = join(this.folder, 'session.jsonl');
+                this.fd = openSync(this.path, 'wx+', 0o600);
+            }
+            const bytes = Buffer.from(JSON.stringify(body) + '\n', 'utf8');
+            let written = 0;
+            while (written < bytes.length) {
+                const count = writeSync(this.fd, bytes, written, bytes.length - written, this.offset + written);
+                if (count <= 0)
+                    throw new Error('incomplete transcript write');
+                written += count;
+            }
+            entry.bytes = bytes.length;
+            this.offset += bytes.length;
+            this.entries.push(entry);
+            this.remember(entry, body);
+        }
+        catch {
+            this.diskFailed = true;
+            // Keep a bounded recent fallback when disk storage is unavailable.
+            const clipped = { text: text.slice(0, CACHE_CHARS / 2), ...(detail ? { detail: detail.slice(0, CACHE_CHARS / 2) } : {}) };
+            entry.fallback = clipped;
+            this.entries.push(entry);
+            let chars = 0;
+            for (let index = this.entries.length - 1; index >= 0; index--) {
+                const item = this.entries[index];
+                if (!item.fallback)
+                    continue;
+                chars += this.size(item.fallback);
+                if (chars > CACHE_CHARS || this.entries.length - index > CACHE_ENTRIES) {
+                    this.entries.splice(index, 1);
+                    this.omitted = true;
+                }
+            }
+            if (this.size(body) > this.size(clipped))
+                this.omitted = true;
+        }
+    }
+    size(body) { return body.text.length + (body.detail?.length ?? 0); }
+    remember(entry, body) {
+        const old = this.cache.get(entry);
+        if (old) {
+            this.cachedChars -= this.size(old);
+            this.cache.delete(entry);
+        }
+        if (this.size(body) > CACHE_CHARS)
+            return;
+        this.cache.set(entry, body);
+        this.cachedChars += this.size(body);
+        while (this.cache.size > CACHE_ENTRIES || this.cachedChars > CACHE_CHARS) {
+            const oldest = this.cache.keys().next().value;
+            this.cachedChars -= this.size(this.cache.get(oldest));
+            this.cache.delete(oldest);
+        }
+    }
+    materialize(entry) {
+        let body = entry.fallback ?? this.cache.get(entry);
+        if (!body) {
+            try {
+                if (this.fd === undefined)
+                    throw new Error('closed transcript');
+                const buffer = Buffer.alloc(entry.bytes);
+                let read = 0;
+                while (read < buffer.length) {
+                    const count = readSync(this.fd, buffer, read, buffer.length - read, entry.offset + read);
+                    if (count <= 0)
+                        throw new Error('incomplete transcript read');
+                    read += count;
+                }
+                const value = JSON.parse(buffer.toString('utf8'));
+                if (!value || typeof value !== 'object' || !('text' in value) || typeof value.text !== 'string')
+                    throw new Error('invalid transcript body');
+                body = { text: value.text, ...('detail' in value && typeof value.detail === 'string' ? { detail: value.detail } : {}) };
+            }
+            catch {
+                this.omitted = true;
+                body = { text: '[Transcript entry unavailable: session storage could not be read.]' };
+            }
+        }
+        if (!entry.fallback)
+            this.remember(entry, body);
+        return { ...entry.metadata, ...body };
+    }
+    window(options) {
+        if (this.closed)
+            return { rows: [], scroll: 0, total: 0 };
+        let total = options.prefix.length;
+        for (const entry of this.entries) {
+            const revision = options.revision?.(entry.metadata) ?? '';
+            if (entry.count === undefined || entry.key !== options.key || entry.revision !== revision) {
+                entry.count = options.render(this.materialize(entry)).length;
+                entry.key = options.key;
+                entry.revision = revision;
+            }
+            total += entry.count;
+        }
+        const height = Number.isFinite(options.height) ? Math.max(0, Math.floor(options.height)) : 0;
+        const scroll = Math.min(Math.max(0, Math.floor(options.scroll) || 0), Math.max(0, total - height));
+        const end = total - scroll, start = Math.max(0, end - height);
+        const rows = options.prefix.slice(start, end);
+        let cursor = options.prefix.length;
+        for (const entry of this.entries) {
+            const next = cursor + entry.count;
+            if (next > start && cursor < end) {
+                const rendered = options.render(this.materialize(entry));
+                rows.push(...rendered.slice(Math.max(0, start - cursor), Math.max(0, end - cursor)));
+            }
+            cursor = next;
+            if (cursor >= end)
+                break;
+        }
+        return { rows, scroll, total };
+    }
+    /**
+     * Drop every entry so the next render shows only the caller's prefix.
+     *
+     * This is the non-terminal counterpart of {@link close}: the spool file, its descriptor and the
+     * class's usability are all kept. Every entry is removed from the live list and the body cache,
+     * and the file itself is truncated back to zero, so the cleared bodies are not merely unreachable
+     * but gone from disk. Writes are positional `writeSync` calls at absolute offsets, so resetting
+     * the write offset together with the truncation is what keeps an entry appended after a clear
+     * from landing at a stale offset and being read back from the wrong bytes.
+     */
+    clear() {
+        if (this.closed)
+            return;
+        this.entries = [];
+        this.cache.clear();
+        this.cachedChars = 0;
+        this.offset = 0;
+        this.omitted = false;
+        // A healthy spool has nothing left to warn about once its entries and their bytes are gone. A
+        // failed disk is the one case that keeps the flag: the entries it silently dropped are gone for
+        // good, so the warning row has to survive the wipe rather than be reset by it.
+        if (this.diskFailed)
+            this.omitted = true;
+        // A spool that never opened needs no truncation, and one whose disk already failed has no file
+        // to truncate: both keep the state they were in, because screening the live list is a display
+        // decision and must not claim storage recovered.
+        else if (this.fd !== undefined) {
+            try {
+                ftruncateSync(this.fd, 0);
+            }
+            catch {
+                this.diskFailed = true;
+                this.omitted = true;
+            }
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.fd !== undefined) {
+            try {
+                closeSync(this.fd);
+            }
+            catch { /* best effort */ }
+            this.fd = undefined;
+        }
+        if (this.folder) {
+            try {
+                rmSync(this.folder, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+        this.entries = [];
+        this.cache.clear();
+        this.cachedChars = 0;
+    }
+}

package/dist/src/palette.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Andorra Code's terminal palette.
+ *
+ * The terminal is monochrome: gray and white carry the interface, and the accent is the
+ * brightest neutral rather than a hue. Red is reserved for errors and removals
+ * ({@link STATUS}), so a red mark on screen always means something went wrong, matching the
+ * desktop client and Graph Studio, which carry no accent hue either.
+ */
+/** Neutral text tones. The palette is gray and white; hue is reserved for status. */
+export declare const GRAY = 245;
+export declare const DIM = 252;
+export declare const FAINT = 242;
+export declare const SUBTLE = 250;
+/** Pure white (#FFFFFF) in the xterm-256 palette, for text that must read at full strength. */
+export declare const WHITE = 231;
+/** The accent: the brightest neutral, so emphasis reads as strength rather than color. */
+export declare const ACCENT_INDEX = 231;
+/**
+ * Semantic status colors, the only hues in the palette.
+ *
+ * These carry meaning (allowed vs. needs-approval, added vs. removed, failure) that the
+ * neutral accent cannot. `error` is the one red, kept for failures and removed lines.
+ */
+export declare const STATUS: {
+    readonly ok: 114;
+    readonly warn: 214;
+    readonly error: 203;
+    readonly added: 114;
+};
+/**
+ * A soft amber (#D7AF5F) for attachment tokens in the composer: an inline paste, image, or
+ * file reference must read as an object rather than as typed text. Muted below `warn` so a
+ * token never looks like a warning.
+ */
+export declare const ATTACHMENT_TOKEN = 179;
+/**
+ * Whether the terminal can render 24-bit color.
+ *
+ * `COLORTERM` is the conventional signal (`truecolor` or `24bit`). It is read at call
+ * time rather than cached at module load so tests and embedders can set it, and an unset
+ * value means "assume 256 colors", which always degrades safely.
+ * @param env - environment to inspect, defaulting to the process environment.
+ * @returns whether truecolor sequences may be emitted.
+ */
+export declare function supportsTruecolor(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * One foreground color sequence for the accent.
+ *
+ * The accent is a palette neutral that every 256-color terminal renders exactly, so no
+ * truecolor variant is needed; the parameter stays so callers need not change.
+ * @param _env - environment, unused while the accent is a palette entry.
+ * @returns the SGR parameter, `38;5;231`.
+ */
+export declare function accentSgr(_env?: NodeJS.ProcessEnv): string;
+/**
+ * Paint text in the accent.
+ * @param text - text to colorize.
+ * @param env - environment passed through to {@link accentSgr}.
+ * @returns the text wrapped in the accent sequence.
+ */
+export declare function accent(text: string, env?: NodeJS.ProcessEnv): string;

package/dist/src/palette.js

@@ -0,0 +1,63 @@
+/**
+ * Andorra Code's terminal palette.
+ *
+ * The terminal is monochrome: gray and white carry the interface, and the accent is the
+ * brightest neutral rather than a hue. Red is reserved for errors and removals
+ * ({@link STATUS}), so a red mark on screen always means something went wrong, matching the
+ * desktop client and Graph Studio, which carry no accent hue either.
+ */
+/** Neutral text tones. The palette is gray and white; hue is reserved for status. */
+export const GRAY = 245;
+export const DIM = 252;
+export const FAINT = 242;
+export const SUBTLE = 250;
+/** Pure white (#FFFFFF) in the xterm-256 palette, for text that must read at full strength. */
+export const WHITE = 231;
+/** The accent: the brightest neutral, so emphasis reads as strength rather than color. */
+export const ACCENT_INDEX = WHITE;
+/**
+ * Semantic status colors, the only hues in the palette.
+ *
+ * These carry meaning (allowed vs. needs-approval, added vs. removed, failure) that the
+ * neutral accent cannot. `error` is the one red, kept for failures and removed lines.
+ */
+export const STATUS = { ok: 114, warn: 214, error: 203, added: 114 };
+/**
+ * A soft amber (#D7AF5F) for attachment tokens in the composer: an inline paste, image, or
+ * file reference must read as an object rather than as typed text. Muted below `warn` so a
+ * token never looks like a warning.
+ */
+export const ATTACHMENT_TOKEN = 179;
+/**
+ * Whether the terminal can render 24-bit color.
+ *
+ * `COLORTERM` is the conventional signal (`truecolor` or `24bit`). It is read at call
+ * time rather than cached at module load so tests and embedders can set it, and an unset
+ * value means "assume 256 colors", which always degrades safely.
+ * @param env - environment to inspect, defaulting to the process environment.
+ * @returns whether truecolor sequences may be emitted.
+ */
+export function supportsTruecolor(env = process.env) {
+    const value = env.COLORTERM;
+    return value === 'truecolor' || value === '24bit';
+}
+/**
+ * One foreground color sequence for the accent.
+ *
+ * The accent is a palette neutral that every 256-color terminal renders exactly, so no
+ * truecolor variant is needed; the parameter stays so callers need not change.
+ * @param _env - environment, unused while the accent is a palette entry.
+ * @returns the SGR parameter, `38;5;231`.
+ */
+export function accentSgr(_env = process.env) {
+    return `38;5;${ACCENT_INDEX}`;
+}
+/**
+ * Paint text in the accent.
+ * @param text - text to colorize.
+ * @param env - environment passed through to {@link accentSgr}.
+ * @returns the text wrapped in the accent sequence.
+ */
+export function accent(text, env = process.env) {
+    return `\x1b[${accentSgr(env)}m${text}\x1b[0m`;
+}

package/dist/src/permissions.d.ts

@@ -0,0 +1,36 @@
+import type { ToolContext } from './types.js';
+export declare const PERMISSION_MODES: readonly ["read-only", "ask-for-approval", "approve-for-me", "full-access"];
+export type PermissionMode = typeof PERMISSION_MODES[number];
+export declare const PERMISSION_OPTIONS: readonly [{
+    readonly id: "read-only";
+    readonly label: "Read Only";
+    readonly description: "Read workspace files; approval required for edits or internet access.";
+}, {
+    readonly id: "ask-for-approval";
+    readonly label: "Ask for approval";
+    readonly description: "Read, edit and run commands in the workspace; approval required outside the sandbox or for internet access.";
+}, {
+    readonly id: "approve-for-me";
+    readonly label: "Approve for me";
+    readonly description: "Automatically allow sandboxed actions; ask for potentially unsafe actions outside the sandbox.";
+}, {
+    readonly id: "full-access";
+    readonly label: "Full Access";
+    readonly description: "Use with caution: access the host filesystem and internet without approval.";
+}];
+export declare function isPermissionMode(value: unknown): value is PermissionMode;
+/** Callers canonicalize through realpath first, so symlink aliases share a setting. */
+export declare function workspacePermissionKey(workspace: string): string;
+export declare function permissionMode(context: Pick<ToolContext, 'permissions' | 'yolo' | 'runControl' | 'pinFilePaths'>): PermissionMode | undefined;
+export declare function permissionLabel(mode: PermissionMode): string;
+/** Reject remote/device namespaces before any filesystem resolution can contact them. */
+export declare function assertLocalFilePath(name: string): void;
+export declare function protectedPermissionRoots(workspace: string): string[];
+/** Inspect local link objects without resolving or probing their destinations. */
+export declare function inspectLocalFileResolution(root: string, target: string): Promise<{
+    approvalRequired: boolean;
+    target: string;
+    link?: true;
+}>;
+/** Keep lexical roots and local aliases, without realpath contacting remote roots. */
+export declare function canonicalProtectedRoots(workspace: string): Promise<string[]>;

package/dist/src/permissions.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { lstat, readlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+export const PERMISSION_MODES = ['read-only', 'ask-for-approval', 'approve-for-me', 'full-access'];
+export const PERMISSION_OPTIONS = [
+    { id: 'read-only', label: 'Read Only', description: 'Read workspace files; approval required for edits or internet access.' },
+    { id: 'ask-for-approval', label: 'Ask for approval', description: 'Read, edit and run commands in the workspace; approval required outside the sandbox or for internet access.' },
+    { id: 'approve-for-me', label: 'Approve for me', description: 'Automatically allow sandboxed actions; ask for potentially unsafe actions outside the sandbox.' },
+    { id: 'full-access', label: 'Full Access', description: 'Use with caution: access the host filesystem and internet without approval.' },
+];
+export function isPermissionMode(value) {
+    return typeof value === 'string' && PERMISSION_MODES.includes(value);
+}
+/** Callers canonicalize through realpath first, so symlink aliases share a setting. */
+export function workspacePermissionKey(workspace) {
+    const normalized = path.resolve(workspace);
+    return createHash('sha256').update(process.platform === 'win32' ? normalized.toLowerCase() : normalized).digest('hex');
+}
+export function permissionMode(context) {
+    return context.pinFilePaths ? 'full-access' : context.runControl?.permissions ?? context.permissions ?? ((context.runControl?.yolo ?? context.yolo) ? 'full-access' : undefined);
+}
+export function permissionLabel(mode) {
+    return PERMISSION_OPTIONS.find(option => option.id === mode).label;
+}
+/** Reject remote/device namespaces before any filesystem resolution can contact them. */
+export function assertLocalFilePath(name) {
+    if (/^[\\/]{2}/.test(name) || /^\\(?:\?\?|Device|GLOBAL\?\?)\\/i.test(name)) {
+        throw new Error('Network and device paths are unavailable to restricted file tools');
+    }
+}
+export function protectedPermissionRoots(workspace) {
+    return ['.git', '.codex', '.andorracode', '.andorra'].map(name => path.join(workspace, name)).concat(process.env.ANDORRACODE_HOME || path.join(homedir(), '.andorracode'), process.env.CODEX_HOME || path.join(homedir(), '.codex'));
+}
+/** Inspect local link objects without resolving or probing their destinations. */
+export async function inspectLocalFileResolution(root, target) {
+    // Another drive may be a mapped share. Namespace checks must precede lstat,
+    // including when a local link has supplied the target spelling.
+    try {
+        assertLocalFilePath(target);
+    }
+    catch {
+        return { approvalRequired: true, target };
+    }
+    if (path.parse(target).root.toLowerCase() !== path.parse(root).root.toLowerCase()) {
+        return { approvalRequired: true, target };
+    }
+    const relative = path.relative(root, target);
+    let ancestor = relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) ? root : path.parse(target).root;
+    const components = path.relative(ancestor, target).split(path.sep).filter(Boolean);
+    for (const [index, component] of components.entries()) {
+        ancestor = path.join(ancestor, component);
+        let info;
+        try {
+            info = await lstat(ancestor);
+        }
+        catch (error) {
+            if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                break;
+            return { approvalRequired: true, target };
+        }
+        if (info.isSymbolicLink()) {
+            const destination = await readlink(ancestor);
+            return { approvalRequired: true, target: path.resolve(path.dirname(ancestor), destination, ...components.slice(index + 1)), link: true };
+        }
+    }
+    return { approvalRequired: false, target };
+}
+/** Keep lexical roots and local aliases, without realpath contacting remote roots. */
+export async function canonicalProtectedRoots(workspace) {
+    const roots = new Set(protectedPermissionRoots(workspace).map(root => path.resolve(root)));
+    for (const configured of [...roots]) {
+        const seen = new Set();
+        let current = configured;
+        let complete = false;
+        for (let links = 0; links < 40; links++) {
+            const key = process.platform === 'win32' ? current.toLowerCase() : current;
+            if (seen.has(key))
+                break;
+            seen.add(key);
+            const inspected = await inspectLocalFileResolution(workspace, current);
+            roots.add(inspected.target);
+            if (!inspected.link) {
+                complete = true;
+                break;
+            }
+            current = inspected.target;
+        }
+        if (!complete)
+            throw new Error('Protected metadata alias chain is cyclic or exceeds the resolution limit');
+    }
+    return [...roots];
+}

package/dist/src/powershell-pool.d.ts

@@ -0,0 +1,26 @@
+import { stopProcessTree, type ShellSandbox } from './shell.js';
+/** Internal command worker; constructor injection permits deterministic teardown tests. */
+export declare class PowerShellWorker {
+    readonly workspace: string;
+    private readonly onClose;
+    private readonly terminate;
+    private readonly child;
+    private readonly runId;
+    private readonly stdoutDecoder;
+    private readonly stderrDecoder;
+    private stdoutPending;
+    private active?;
+    private chain;
+    private idle?;
+    private closed;
+    /** Never discard the owned process until all descendants have been reaped. */
+    private disposal?;
+    get isClosing(): boolean;
+    constructor(workspace: string, onClose: () => void, terminate?: typeof stopProcessTree);
+    private append;
+    private onStdout;
+    execute(command: string, timeout: number, signal: AbortSignal, launchPolicy: () => ShellSandbox | undefined): Promise<string>;
+    dispose(error?: Error): Promise<void>;
+}
+export declare function runPooledPowerShell(command: string, workspace: string, timeout: number, signal: AbortSignal, launchPolicy: () => ShellSandbox | undefined): Promise<string>;
+export declare function disposePooledPowerShell(): Promise<void>;