@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/favicons.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A website's icon, fetched by the engine for the desktop transcript.
+ *
+ * The desktop window never fetches remote resources itself: its content security policy allows
+ * images from the app and `data:` URLs only, so a row that names a website asks the engine for the
+ * site's icon and draws the bytes it gets back. The engine fetches `https://<host>/favicon.ico`,
+ * then the icon the home page declares, and keeps the answer — an icon or the lack of one — for the
+ * life of the process, so a transcript that names one site forty times costs one fetch.
+ *
+ * Only a public DNS name is fetched, over HTTPS, and every redirect hop is held to the same rule: a
+ * host the model wrote into a tool call must not turn the engine into a reader of the loopback
+ * interface or the local network. Only real image bytes are returned, under a small cap.
+ */
+export interface Favicon {
+    mimeType: string;
+    dataBase64: string;
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * The host as a fetchable public DNS name, lowercased, or undefined.
+ *
+ * The rule is the shape of a public name — dotted labels ending in an alphabetic top-level label —
+ * so IP literals, single-label names (`localhost`, an intranet box) and the reserved local suffixes
+ * are all refused before any socket opens.
+ */
+export declare function publicHost(value: unknown): string | undefined;
+export declare function readFavicon(host: string, fetchImpl?: FetchLike): Promise<Favicon | undefined>;
+/** Forgets every remembered answer. Tests only: the engine keeps its answers for its lifetime. */
+export declare function clearFaviconCache(): void;
+/** The first `<link rel="…icon…" href="…">` of a page, as written. */
+export declare function declaredIcon(html: string): string | undefined;
+/**
+ * The image type the bytes are, by their signature. The server's content type is not trusted:
+ * plenty of sites answer a missing favicon with an HTML page and a 200.
+ */
+export declare function sniffImage(bytes: Uint8Array): string | undefined;
+export {};

package/dist/src/favicons.js

@@ -0,0 +1,216 @@
+/**
+ * A website's icon, fetched by the engine for the desktop transcript.
+ *
+ * The desktop window never fetches remote resources itself: its content security policy allows
+ * images from the app and `data:` URLs only, so a row that names a website asks the engine for the
+ * site's icon and draws the bytes it gets back. The engine fetches `https://<host>/favicon.ico`,
+ * then the icon the home page declares, and keeps the answer — an icon or the lack of one — for the
+ * life of the process, so a transcript that names one site forty times costs one fetch.
+ *
+ * Only a public DNS name is fetched, over HTTPS, and every redirect hop is held to the same rule: a
+ * host the model wrote into a tool call must not turn the engine into a reader of the loopback
+ * interface or the local network. Only real image bytes are returned, under a small cap.
+ */
+/** The largest icon kept. A favicon is a few kilobytes; anything far past that is not one. */
+const MAX_ICON_BYTES = 100 * 1024;
+/** How much of a home page is read looking for its icon link. The link is in the head. */
+const MAX_PAGE_BYTES = 256 * 1024;
+const REQUEST_TIMEOUT_MS = 5_000;
+const MAX_REDIRECTS = 3;
+/** Hosts remembered, oldest first out. Each entry is at most one capped icon. */
+const CACHE_LIMIT = 512;
+const cache = new Map();
+/**
+ * The host as a fetchable public DNS name, lowercased, or undefined.
+ *
+ * The rule is the shape of a public name — dotted labels ending in an alphabetic top-level label —
+ * so IP literals, single-label names (`localhost`, an intranet box) and the reserved local suffixes
+ * are all refused before any socket opens.
+ */
+export function publicHost(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const host = value.trim().toLowerCase().replace(/\.$/, '');
+    if (host.length > 253)
+        return undefined;
+    if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(host))
+        return undefined;
+    if (/\.(?:localhost|local|internal|test|invalid|example|lan|home\.arpa)$/.test(host))
+        return undefined;
+    return host;
+}
+export function readFavicon(host, fetchImpl = fetch) {
+    const name = publicHost(host);
+    if (name === undefined)
+        return Promise.resolve(undefined);
+    const cached = cache.get(name);
+    if (cached) {
+        cache.delete(name);
+        cache.set(name, cached);
+        return cached;
+    }
+    const pending = lookUp(name, fetchImpl).catch(() => undefined);
+    cache.set(name, pending);
+    while (cache.size > CACHE_LIMIT) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+    return pending;
+}
+/** Forgets every remembered answer. Tests only: the engine keeps its answers for its lifetime. */
+export function clearFaviconCache() {
+    cache.clear();
+}
+async function lookUp(host, fetchImpl) {
+    const conventional = await fetchIcon(`https://${host}/favicon.ico`, fetchImpl);
+    if (conventional)
+        return conventional;
+    const page = await fetchCapped(`https://${host}/`, fetchImpl, MAX_PAGE_BYTES);
+    if (!page)
+        return undefined;
+    const href = declaredIcon(new TextDecoder().decode(page.bytes));
+    if (href === undefined)
+        return undefined;
+    if (/^data:/i.test(href))
+        return fromDataUrl(href);
+    let target;
+    try {
+        target = new URL(href, page.url);
+    }
+    catch {
+        return undefined;
+    }
+    return fetchIcon(target.href, fetchImpl);
+}
+/** The first `<link rel="…icon…" href="…">` of a page, as written. */
+export function declaredIcon(html) {
+    for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
+        const tag = match[0];
+        const rel = attribute(tag, 'rel');
+        if (rel === undefined || !rel.toLowerCase().split(/\s+/).includes('icon') && !/apple-touch-icon/i.test(rel))
+            continue;
+        const href = attribute(tag, 'href');
+        if (href)
+            return href.replace(/&amp;/g, '&');
+    }
+    return undefined;
+}
+function attribute(tag, name) {
+    const match = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag);
+    return match ? (match[1] ?? match[2] ?? match[3]) : undefined;
+}
+async function fetchIcon(url, fetchImpl) {
+    const response = await fetchCapped(url, fetchImpl, MAX_ICON_BYTES);
+    if (!response)
+        return undefined;
+    const mimeType = sniffImage(response.bytes);
+    return mimeType === undefined ? undefined : { mimeType, dataBase64: Buffer.from(response.bytes).toString('base64') };
+}
+/**
+ * A GET whose every hop is an HTTPS URL on a public name, and whose body is read only up to the
+ * cap — a larger body is refused rather than truncated, since half an image is not an icon.
+ */
+async function fetchCapped(url, fetchImpl, cap) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        let parsed;
+        try {
+            parsed = new URL(current);
+        }
+        catch {
+            return undefined;
+        }
+        if (parsed.protocol !== 'https:' || parsed.username || parsed.password || publicHost(parsed.hostname) === undefined)
+            return undefined;
+        const response = await fetchImpl(parsed.href, {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: { accept: 'image/*,text/html;q=0.9,*/*;q=0.5' },
+        });
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            await response.body?.cancel().catch(() => { });
+            if (!location)
+                return undefined;
+            try {
+                current = new URL(location, parsed).href;
+            }
+            catch {
+                return undefined;
+            }
+            continue;
+        }
+        if (!response.ok || !response.body) {
+            await response.body?.cancel().catch(() => { });
+            return undefined;
+        }
+        const declared = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > cap) {
+            await response.body.cancel().catch(() => { });
+            return undefined;
+        }
+        const bytes = await readCapped(response.body, cap);
+        return bytes === undefined ? undefined : { url: parsed.href, bytes };
+    }
+    return undefined;
+}
+async function readCapped(body, cap) {
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel().catch(() => { });
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+/**
+ * The image type the bytes are, by their signature. The server's content type is not trusted:
+ * plenty of sites answer a missing favicon with an HTML page and a 200.
+ */
+export function sniffImage(bytes) {
+    const starts = (...signature) => signature.every((byte, index) => bytes[index] === byte);
+    if (bytes.length < 4)
+        return undefined;
+    if (starts(0x89, 0x50, 0x4e, 0x47))
+        return 'image/png';
+    if (starts(0x00, 0x00, 0x01, 0x00))
+        return 'image/x-icon';
+    if (starts(0x47, 0x49, 0x46, 0x38))
+        return 'image/gif';
+    if (starts(0xff, 0xd8, 0xff))
+        return 'image/jpeg';
+    if (starts(0x52, 0x49, 0x46, 0x46) && bytes.length >= 12
+        && String.fromCharCode(...bytes.subarray(8, 12)) === 'WEBP')
+        return 'image/webp';
+    // An SVG drawn through an <img> runs no script, so it is as safe to hand over as a bitmap.
+    const head = new TextDecoder().decode(bytes.subarray(0, 512)).trimStart().toLowerCase();
+    if (head.startsWith('<svg') || (head.startsWith('<?xml') && head.includes('<svg')))
+        return 'image/svg+xml';
+    return undefined;
+}
+function fromDataUrl(href) {
+    const match = /^data:([^;,]+)(;base64)?,(.*)$/is.exec(href);
+    if (!match)
+        return undefined;
+    const bytes = match[2] ? Buffer.from(match[3], 'base64') : Buffer.from(decodeURIComponent(match[3]), 'utf8');
+    if (bytes.byteLength > MAX_ICON_BYTES)
+        return undefined;
+    const mimeType = sniffImage(bytes);
+    return mimeType === undefined ? undefined : { mimeType, dataBase64: bytes.toString('base64') };
+}

package/dist/src/file-read-state.d.ts

@@ -0,0 +1,8 @@
+import type { ToolFileReadState, ToolRuntimeState } from './types.js';
+export declare const FILE_READ_CACHE_BYTES: number;
+export declare const FILE_READ_CACHE_ENTRIES = 256;
+export declare function matchesFileRead(snapshot: ToolFileReadState, content: string): boolean;
+/** All Read, mutation and complete CodeGraph snapshots share one bounded store. */
+export declare function storeFileRead(state: ToolRuntimeState, key: string, snapshot: ToolFileReadState & {
+    content: string;
+}): void;

package/dist/src/file-read-state.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+// Account for UTF-16 string storage, independently of the per-file UTF-8 repair limit.
+export const FILE_READ_CACHE_BYTES = 16 * 1024 * 1024;
+export const FILE_READ_CACHE_ENTRIES = 256;
+// Preserve exact JavaScript string equality, including any lone surrogate in a
+// mutation argument; UTF-8 would collapse it to the replacement character.
+const fingerprint = (content) => createHash('sha256').update(content, 'utf16le').digest('hex');
+export function matchesFileRead(snapshot, content) {
+    return snapshot.content !== undefined ? snapshot.content === content
+        : snapshot.contentHash !== undefined && snapshot.contentHash === fingerprint(content);
+}
+/** All Read, mutation and complete CodeGraph snapshots share one bounded store. */
+export function storeFileRead(state, key, snapshot) {
+    const entries = state.fileReads;
+    entries.delete(key);
+    entries.set(key, { ...snapshot, contentHash: fingerprint(snapshot.content) });
+    while (entries.size > FILE_READ_CACHE_ENTRIES)
+        entries.delete(entries.keys().next().value);
+    let retainedBytes = 0;
+    for (const entry of entries.values())
+        retainedBytes += (entry.content?.length ?? 0) * 2;
+    for (const entry of entries.values()) {
+        if (retainedBytes <= FILE_READ_CACHE_BYTES)
+            break;
+        if (entry.content === undefined)
+            continue;
+        retainedBytes -= entry.content.length * 2;
+        entry.contentHash ??= fingerprint(entry.content);
+        delete entry.content;
+    }
+}

package/dist/src/git-summary.d.ts

@@ -0,0 +1,67 @@
+import type { PanelChanges } from './side-panel.js';
+export interface GitChangeSummaryOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/**
+ * The environment a panel git read runs under: the caller's, with PATH entries inside the
+ * workspace removed and git's own background locking turned off.
+ *
+ * Display-only Git must not run a workspace-controlled program. `gitBranch` reads Git metadata
+ * directly for exactly this reason, and a spawned `git` resolved from the inherited PATH is the
+ * same hazard in a different shape: under `npm start`, `npx`, or any launcher that prepends the
+ * repository's `node_modules/.bin`, a file named `git` in the workspace would run on a panel
+ * refresh without a tool call or an approval. Every PATH entry that resolves inside the workspace
+ * - or inside the repository that contains it, where the workspace is a subdirectory - is dropped
+ * here, and {@link trustedGitPath} then resolves the executable to an absolute path, so neither
+ * the filtered PATH nor the child's working directory can reach a repository program. A workspace
+ * that genuinely hosts the user's Git loses the summary rather than running it.
+ * @param workspace - the directory the read is about.
+ * @param env - environment to filter; defaults to this process's.
+ * @returns a copy of the environment whose PATH excludes the workspace and its repository.
+ */
+export declare function trustedGitEnv(workspace: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * The canonical directories a display read must not run anything from: the workspace, and the
+ * repository that contains it (which `git -C` reaches, so its `bin` directories are controlled by
+ * the same author).
+ */
+export declare function excludedRoots(workspace: string): string[];
+/**
+ * The absolute path of the git a filtered environment may run, or undefined when it has none.
+ *
+ * The executable is resolved here rather than left to the spawn's own search for three reasons:
+ * an empty PATH makes a child-process search the current directory on POSIX, Windows searches the
+ * current directory before PATH, and the directory this process runs from is usually the
+ * workspace. Resolving the first existing candidate from the *filtered* PATH removes all three at
+ * once, and no candidates means the read is refused instead of executed.
+ *
+ * The candidate is canonicalized and checked against the excluded roots rather than against the
+ * directory that supplied it: a `git` symlink may legitimately live outside its PATH entry - a Nix
+ * profile's `bin/git` pointing into the store is the ordinary case - but it must not resolve into
+ * the workspace or its repository.
+ * @param env - environment whose PATH has already been filtered by {@link trustedGitEnv}.
+ * @param excluded - canonical roots the executable must stay out of; see {@link excludedRoots}.
+ * @returns the absolute executable path, or undefined.
+ */
+export declare function trustedGitPath(env?: NodeJS.ProcessEnv, excluded?: readonly string[]): string | undefined;
+/**
+ * Count the working tree's changed files and lines, bounded and read-only.
+ *
+ * This exists for the side panel, which refreshes while a run is writing files; it therefore
+ * never opens file contents (unlike the QA change detector, which synthesizes untracked diffs
+ * for review) and never blocks the CLI for longer than one git invocation's timeout. Untracked
+ * entries are counted but carry no line statistics: their content is not read, so a `+0` line
+ * total for a brand-new file would be a lie rather than a measurement.
+ *
+ * A read that could not be completed - no trusted git, the abort signal, the timeout, output
+ * past the cap, an unexpected nonzero exit - rejects instead of reporting a partial answer.
+ * `isGit: false` is reserved for a directory that genuinely has no repository, so a caller can
+ * publish that while keeping the last good reading for a failure.
+ * @param workspace - directory the git commands read.
+ * @param options - abort signal and per-command timeout for embedders that need their own.
+ * @returns the summary; `isGit: false` when the directory is not a repository, or the counts
+ *   withheld with `skipped` set when comparing the worktree would run a configured filter.
+ * @throws when no trusted git can be run or the read could not be completed.
+ */
+export declare function gitChangeSummary(workspace: string, options?: GitChangeSummaryOptions): Promise<PanelChanges>;