@itaila/archetype 0.3.30

package/dist/builder/sandbox.js

@@ -0,0 +1,294 @@
+/**
+ * Sandbox — the low-level confined-execution primitive every coder-
+ * persona builder needs.
+ *
+ * Contract:
+ * — `exec`   one-shot command, awaits completion, returns result.
+ * — `spawn`  long-running command with ready-pattern detection
+ *            (for local HTTP servers, watchers, etc.).
+ * — `cleanup` terminate any still-running children.
+ *
+ * What belongs here (the archetype layer):
+ * — `Sandbox` interface
+ * — `SrtSandbox` default impl wrapping `@anthropic-ai/sandbox-runtime`
+ *   (binary path is passed in — archetype does not resolve it)
+ * — `buildSandboxConfig` + `createAllowlistedEnv` helpers so host
+ *   apps can compose per-preset configurations.
+ *
+ * What does NOT belong here:
+ * — Benchmark-specific presets (workspace-build, local-start, etc.)
+ *   — those encode product decisions about what each tool should do.
+ * — Trusted-toolchain resolution (node/npm/eslint binary paths) — the
+ *   host app owns which binaries are trusted.
+ * — Evidence file writing, telemetry, metric emission — orchestration
+ *   layer, not runtime layer.
+ *
+ * Node-only: uses `node:child_process` + `node:fs`. Consumers that only
+ * need browser-safe archetype features (personas, actions, memory)
+ * should not reach for this module.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const execFileAsync = promisify(execFile);
+/**
+ * Default list of environment variables the sandbox never forwards to
+ * child processes. Prevents credential leakage + shell-history pollution.
+ */
+export const DEFAULT_BLOCKED_ENV_KEYS = new Set([
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GEMINI_API_KEY',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_ACCESS_KEY_ID',
+    'GOOGLE_API_KEY',
+    'SSH_AUTH_SOCK',
+    'HISTFILE',
+    'HISTFILESIZE',
+    'HISTSIZE',
+]);
+export class SrtSandbox {
+    workspaceRoot;
+    srtBinary;
+    sandboxTempRoot;
+    trustedReadPaths;
+    blockedEnvKeys;
+    settingsDir;
+    activeChildren = new Set();
+    constructor(options) {
+        this.workspaceRoot = path.resolve(options.workspaceRoot);
+        this.srtBinary = options.srtBinary;
+        this.sandboxTempRoot = path.resolve(options.sandboxTempRoot ?? path.join(this.workspaceRoot, '.sandbox-tmp'));
+        this.trustedReadPaths = options.trustedReadPaths ?? [];
+        this.blockedEnvKeys = new Set(DEFAULT_BLOCKED_ENV_KEYS);
+        for (const key of options.extraBlockedEnvKeys ?? [])
+            this.blockedEnvKeys.add(key);
+        this.settingsDir = path.resolve(options.settingsDir ?? this.sandboxTempRoot);
+        fs.mkdirSync(this.sandboxTempRoot, { recursive: true });
+        fs.mkdirSync(this.settingsDir, { recursive: true });
+    }
+    async exec(options) {
+        const { args, settingsPath, env, fullCommand, cwd } = this.prepareCall(options);
+        return execFileAsync(this.srtBinary, args, {
+            cwd,
+            env: env,
+            timeout: options.timeoutMs ?? 120_000,
+            maxBuffer: 1024 * 1024,
+        }).then(value => ({
+            ok: true,
+            exitCode: 0,
+            stdout: value.stdout,
+            stderr: value.stderr,
+            command: fullCommand,
+            settingsPath,
+            timedOut: false,
+        }), error => ({
+            ok: false,
+            exitCode: typeof error.code === 'number'
+                ? error.code
+                : 1,
+            stdout: error.stdout ?? '',
+            stderr: error.stderr ?? String(error),
+            command: fullCommand,
+            settingsPath,
+            timedOut: error.killed === true,
+        }));
+    }
+    async spawn(options) {
+        const { args, settingsPath, env, fullCommand, cwd } = this.prepareCall(options);
+        const child = spawn(this.srtBinary, args, {
+            cwd,
+            env: env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // Track for cleanup: stays in the set until the child actually exits
+        // (whether by ready→background-running, or by error, or by SIGTERM
+        // from cleanup()). The exit handler is the only place that removes.
+        this.activeChildren.add(child);
+        child.on('exit', () => {
+            this.activeChildren.delete(child);
+        });
+        let stdout = '';
+        let stderr = '';
+        let readyMatch = null;
+        let resolved = false;
+        return new Promise((resolve) => {
+            const finalize = (result) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(result);
+            };
+            const timeout = setTimeout(() => {
+                if (!child.killed)
+                    child.kill('SIGTERM');
+                finalize({
+                    ok: false,
+                    exitCode: 124,
+                    stdout,
+                    stderr: `${stderr}\nSpawn did not reach ready state before timeout.`.trim(),
+                    command: fullCommand,
+                    settingsPath,
+                    timedOut: true,
+                    readyMatch,
+                });
+            }, options.readyTimeoutMs ?? options.timeoutMs ?? 20_000);
+            child.stdout?.on('data', chunk => {
+                stdout += chunk.toString();
+                if (options.readyPattern && !readyMatch) {
+                    const m = stdout.match(options.readyPattern);
+                    if (m) {
+                        readyMatch = m[1] ?? m[0];
+                        clearTimeout(timeout);
+                        // Child stays running in the background. Caller is expected
+                        // to call cleanup() when done (or call spawn() again for a
+                        // different long-running process, which also triggers the
+                        // caller's own cleanup).
+                        finalize({
+                            ok: true,
+                            exitCode: 0,
+                            stdout,
+                            stderr,
+                            command: fullCommand,
+                            settingsPath,
+                            timedOut: false,
+                            readyMatch,
+                        });
+                    }
+                }
+            });
+            child.stderr?.on('data', chunk => {
+                stderr += chunk.toString();
+            });
+            child.on('exit', code => {
+                if (readyMatch)
+                    return;
+                clearTimeout(timeout);
+                finalize({
+                    ok: false,
+                    exitCode: code ?? 1,
+                    stdout,
+                    stderr,
+                    command: fullCommand,
+                    settingsPath,
+                    timedOut: false,
+                    readyMatch,
+                });
+            });
+        });
+    }
+    async cleanup() {
+        for (const child of this.activeChildren) {
+            if (!child.killed)
+                child.kill('SIGTERM');
+        }
+        this.activeChildren.clear();
+    }
+    prepareCall(options) {
+        const cwd = path.resolve(options.cwd ?? this.workspaceRoot);
+        const config = buildSandboxConfig({
+            workspaceRoot: this.workspaceRoot,
+            sandboxTempRoot: this.sandboxTempRoot,
+            trustedReadPaths: this.trustedReadPaths,
+            extraReadPaths: options.extraReadPaths,
+            extraWritePaths: options.extraWritePaths,
+            allowedNetworkDomains: options.allowedNetworkDomains,
+            allowLocalBinding: options.allowLocalBinding ?? false,
+        });
+        const settingsPath = path.join(this.settingsDir, `srt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2));
+        const env = createAllowlistedEnv(this.sandboxTempRoot, this.blockedEnvKeys);
+        const command = this.materializeInlineCommand(options.command);
+        const commandString = shellQuoteCommand(command);
+        const args = ['--settings', settingsPath, '-c', commandString];
+        const fullCommand = [this.srtBinary, ...args];
+        return { args, settingsPath, env, fullCommand, cwd };
+    }
+    materializeInlineCommand(command) {
+        const [binary, mode, script, ...rest] = command;
+        if (!binary || !mode || typeof script !== 'string')
+            return [...command];
+        const base = path.basename(binary);
+        if ((base === 'sh' || base === 'bash' || binary.endsWith('/sh') || binary.endsWith('/bash')) && mode === '-c') {
+            const scriptPath = this.writeInlineScript(script, 'sh');
+            return [binary, scriptPath, ...rest];
+        }
+        if ((mode === '-e' || mode === '--eval') && (base === 'node' || binary.endsWith('/node'))) {
+            const scriptPath = this.writeInlineScript(script, 'cjs');
+            return [binary, scriptPath, ...rest];
+        }
+        return [...command];
+    }
+    writeInlineScript(content, extension) {
+        const filePath = path.join(this.sandboxTempRoot, `inline-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${extension}`);
+        fs.writeFileSync(filePath, content, 'utf8');
+        return filePath;
+    }
+}
+function shellQuoteCommand(argv) {
+    return argv.map(shellQuoteArg).join(' ');
+}
+function shellQuoteArg(value) {
+    if (value.length === 0)
+        return "''";
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build an SRT settings object from the knobs archetype exposes. Host
+ * apps can call this directly if they want to assemble settings without
+ * going through `SrtSandbox` (tests, one-off invocations).
+ *
+ * Default deny-read list covers sensitive host paths (home dir, /tmp,
+ * kernel mounts). Allow-read is workspace + sandbox temp + caller-
+ * supplied trusted paths + per-call extras.
+ */
+export function buildSandboxConfig(input) {
+    const denyRead = [os.homedir(), '/tmp', '/private/tmp', '/proc', '/sys', '/dev'];
+    const allowRead = [
+        input.workspaceRoot,
+        input.sandboxTempRoot,
+        ...(input.trustedReadPaths ?? []),
+        ...(input.extraReadPaths ?? []),
+    ];
+    const allowWrite = [
+        input.workspaceRoot,
+        input.sandboxTempRoot,
+        ...(input.extraWritePaths ?? []),
+    ];
+    return {
+        network: {
+            allowedDomains: input.allowedNetworkDomains ?? [],
+            deniedDomains: [],
+            allowUnixSockets: [],
+            allowLocalBinding: input.allowLocalBinding ?? false,
+        },
+        filesystem: {
+            denyRead,
+            allowRead,
+            allowWrite,
+            denyWrite: [],
+        },
+    };
+}
+/**
+ * Build a minimal allowlisted child-process env. Copies only
+ * PATH/HOME/LANG/LC_ALL/TERM from the parent, redirects TMPDIR/TMP/TEMP
+ * to the sandbox temp root, and blocks everything in `blockedKeys`.
+ */
+export function createAllowlistedEnv(tmpDir, blockedKeys = DEFAULT_BLOCKED_ENV_KEYS) {
+    const env = {};
+    for (const key of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TERM']) {
+        const value = process.env[key];
+        if (value && !blockedKeys.has(key))
+            env[key] = value;
+    }
+    env.TMPDIR = tmpDir;
+    env.TMP = tmpDir;
+    env.TEMP = tmpDir;
+    return env;
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/builder/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/builder/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/builder/workspace-files.d.ts

@@ -0,0 +1,63 @@
+export interface WorkspaceFileEntry {
+    path: string;
+    bytes: number;
+    lines: number | null;
+    /** Present when entries come from workspace mounts. */
+    writable?: boolean;
+}
+export interface WorkspaceMount {
+    /**
+     * Virtual path prefix exposed to the model, e.g. "spec" or "artifact".
+     * Use "" only for a legacy single-root workspace.
+     */
+    prefix: string;
+    /** Absolute filesystem root backing this virtual prefix. */
+    root: string;
+    /** Defaults to true. Set false for spec/reference mounts. */
+    writable?: boolean;
+    /** Compact factual purpose of this mount, e.g. "implementation artifact". */
+    purpose?: string;
+}
+export interface ListWorkspaceFileEntriesOptions {
+    ignoreHidden?: boolean;
+    ignoreDirs?: readonly string[];
+    maxEntries?: number;
+}
+export interface RenderWorkspaceMountFileTreeOptions extends ListWorkspaceFileEntriesOptions {
+    /**
+     * Deprecated: mounted workspaces expose one canonical visible path per file.
+     * Kept only so older callers do not fail type-checks; rendering does not
+     * create a second "default" alias.
+     */
+    defaultMountPrefix?: string;
+}
+export interface RenderWorkspaceMountFileContentsOptions {
+    maxBytesPerFile?: number;
+}
+export declare function listWorkspaceFileEntries(workspaceRoot: string, options?: ListWorkspaceFileEntriesOptions): WorkspaceFileEntry[];
+export declare function renderWorkspaceFileEntries(entries: readonly WorkspaceFileEntry[]): string[];
+export declare function renderWorkspaceMountFileTree(mounts: readonly WorkspaceMount[], options?: RenderWorkspaceMountFileTreeOptions): string[];
+export declare function renderWorkspaceMountFileContents(mounts: readonly WorkspaceMount[], visiblePaths: readonly string[], options?: RenderWorkspaceMountFileContentsOptions): string;
+export interface ResolvedWorkspaceMountPath {
+    mount: WorkspaceMount;
+    /** Absolute path on disk. */
+    absolutePath: string;
+    /** Path relative to the selected mount root. */
+    relativePath: string;
+    /** Path as it should appear in prompts and action outcomes. */
+    visiblePath: string;
+}
+export declare function normalizeWorkspaceMounts(mounts: readonly WorkspaceMount[]): WorkspaceMount[];
+export declare function listWorkspaceMountFileEntries(mounts: readonly WorkspaceMount[], options?: ListWorkspaceFileEntriesOptions): WorkspaceFileEntry[];
+export declare function resolveWorkspaceMountPath(input: {
+    mounts: readonly WorkspaceMount[];
+    requestPath: string;
+    /**
+     * Deprecated. Mounted workspaces now use canonical visible paths only.
+     * A prefixed path such as artifact/index.html resolves to artifact; an
+     * unprefixed path resolves only when a mount with prefix "" exists.
+     */
+    defaultMountPrefix?: string;
+}): ResolvedWorkspaceMountPath;
+export declare function isWorkspaceMountPathWritable(resolved: ResolvedWorkspaceMountPath): boolean;
+//# sourceMappingURL=workspace-files.d.ts.map

package/dist/builder/workspace-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-files.d.ts","sourceRoot":"","sources":["../../src/builder/workspace-files.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,+BAA+B;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,mCAAoC,SAAQ,+BAA+B;IAC1F;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,uCAAuC;IACtD,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,+BAAoC,GAC5C,kBAAkB,EAAE,CAoCtB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAS3F;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,mCAAwC,GAChD,MAAM,EAAE,CAsBV;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,GAAE,uCAA4C,GACpD,MAAM,CA0CR;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,cAAc,CAAA;IACrB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,EAAE,CAa5F;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,+BAAoC,GAC5C,kBAAkB,EAAE,CAStB;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,GAAG,0BAA0B,CAyB7B;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,0BAA0B,GAAG,OAAO,CAE1F"}

package/dist/builder/workspace-files.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function listWorkspaceFileEntries(workspaceRoot, options = {}) {
+    const ignoreHidden = options.ignoreHidden ?? true;
+    const ignoreDirs = new Set(options.ignoreDirs ?? ['node_modules', 'dist']);
+    const maxEntries = options.maxEntries ?? 500;
+    const entries = [];
+    const walk = (dir, prefix) => {
+        if (entries.length >= maxEntries)
+            return;
+        let items = [];
+        try {
+            items = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        items.sort((left, right) => left.name.localeCompare(right.name));
+        for (const item of items) {
+            if (entries.length >= maxEntries)
+                break;
+            if (ignoreHidden && item.name.startsWith('.'))
+                continue;
+            if (ignoreDirs.has(item.name))
+                continue;
+            const full = path.join(dir, item.name);
+            const relPath = prefix ? `${prefix}/${item.name}` : item.name;
+            if (item.isDirectory()) {
+                walk(full, relPath);
+                continue;
+            }
+            const stat = fs.statSync(full);
+            entries.push({
+                path: relPath,
+                bytes: stat.size,
+                lines: countTextLines(full),
+            });
+        }
+    };
+    walk(workspaceRoot, '');
+    return entries;
+}
+export function renderWorkspaceFileEntries(entries) {
+    if (entries.length === 0)
+        return ['(empty)'];
+    return entries.map(entry => {
+        const linePart = entry.lines == null ? 'binary/unknown lines' : `${entry.lines} lines`;
+        const accessPart = typeof entry.writable === 'boolean'
+            ? `, ${entry.writable ? 'writable' : 'read-only'}`
+            : '';
+        return `${entry.path} — ${linePart}, ${entry.bytes} bytes${accessPart}`;
+    });
+}
+export function renderWorkspaceMountFileTree(mounts, options = {}) {
+    const normalized = normalizeWorkspaceMounts(mounts);
+    if (normalized.length === 0)
+        return ['(empty)'];
+    const lines = [];
+    for (const mount of normalized) {
+        const entries = listWorkspaceFileEntries(mount.root, options);
+        const label = mount.prefix ? `${mount.prefix}/` : './';
+        const access = mount.writable === false ? 'read-only' : 'writable';
+        const purposeNote = mount.purpose?.trim() ? `, ${mount.purpose.trim()}` : '';
+        const emptyNote = entries.length === 0 ? ', empty' : '';
+        lines.push(`${label} — ${access}${purposeNote}${emptyNote}`);
+        if (entries.length > 0) {
+            const visibleEntries = entries.map(entry => ({
+                ...entry,
+                path: mount.prefix ? `${mount.prefix}/${entry.path}` : entry.path,
+            }));
+            lines.push(...renderWorkspaceFileEntries(visibleEntries).map(entry => `  ${entry}`));
+        }
+    }
+    return lines;
+}
+export function renderWorkspaceMountFileContents(mounts, visiblePaths, options = {}) {
+    const maxBytesPerFile = options.maxBytesPerFile ?? 8_000;
+    const sections = [];
+    for (const visiblePath of visiblePaths) {
+        let resolved;
+        try {
+            resolved = resolveWorkspaceMountPath({ mounts, requestPath: visiblePath });
+        }
+        catch {
+            continue;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(resolved.absolutePath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const lines = countTextLines(resolved.absolutePath);
+        if (lines == null) {
+            sections.push(`## ${resolved.visiblePath}\n(binary file, ${stat.size} bytes; use readFile only if this file has a text representation)`);
+            continue;
+        }
+        if (stat.size > maxBytesPerFile) {
+            sections.push(`## ${resolved.visiblePath}\n${lines} lines, ${stat.size} bytes; content not inlined because it exceeds ${maxBytesPerFile} bytes. Use readFile if exact contents are needed.`);
+            continue;
+        }
+        const content = fs.readFileSync(resolved.absolutePath, 'utf8');
+        sections.push([
+            `## ${resolved.visiblePath}`,
+            `${lines} lines, ${stat.size} bytes`,
+            '```text',
+            content.replace(/\s+$/u, ''),
+            '```',
+        ].join('\n'));
+    }
+    return sections.join('\n\n');
+}
+export function normalizeWorkspaceMounts(mounts) {
+    const seen = new Set();
+    return mounts.map(mount => {
+        const prefix = normalizeMountPrefix(mount.prefix);
+        if (seen.has(prefix))
+            throw new Error(`Duplicate workspace mount prefix: ${prefix}`);
+        seen.add(prefix);
+        return {
+            ...mount,
+            prefix,
+            root: path.resolve(mount.root),
+            writable: mount.writable ?? true,
+        };
+    });
+}
+export function listWorkspaceMountFileEntries(mounts, options = {}) {
+    const normalized = normalizeWorkspaceMounts(mounts);
+    return normalized.flatMap(mount => listWorkspaceFileEntries(mount.root, options).map(entry => ({
+        ...entry,
+        path: mount.prefix ? `${mount.prefix}/${entry.path}` : entry.path,
+        writable: mount.writable !== false,
+    })));
+}
+export function resolveWorkspaceMountPath(input) {
+    const mounts = normalizeWorkspaceMounts(input.mounts);
+    if (mounts.length === 0)
+        throw new Error('No workspace mounts configured');
+    const requestPath = normalizeRequestPath(input.requestPath);
+    const explicitMount = mounts
+        .filter(mount => mount.prefix.length > 0)
+        .sort((left, right) => right.prefix.length - left.prefix.length)
+        .find(mount => requestPath === mount.prefix || requestPath.startsWith(`${mount.prefix}/`));
+    const rootMount = mounts.find(item => item.prefix.length === 0);
+    const mount = explicitMount ?? rootMount;
+    if (!mount) {
+        const visibleRoots = mounts.map(item => item.prefix ? `${item.prefix}/` : './').join(', ');
+        throw new Error(`Path "${requestPath}" is not a canonical visible workspace path. Use a visible path from FILES exactly as shown, including its mount prefix (${visibleRoots}).`);
+    }
+    const relativePath = explicitMount
+        ? requestPath.slice(explicitMount.prefix.length).replace(/^\/+/u, '')
+        : requestPath;
+    const absolutePath = resolveInsideRoot(mount.root, relativePath);
+    return {
+        mount,
+        absolutePath,
+        relativePath,
+        visiblePath: mount.prefix ? `${mount.prefix}/${relativePath}` : relativePath,
+    };
+}
+export function isWorkspaceMountPathWritable(resolved) {
+    return resolved.mount.writable !== false;
+}
+function normalizeMountPrefix(prefix) {
+    return prefix.replace(/^\/+|\/+$/gu, '');
+}
+function normalizeRequestPath(requestPath) {
+    const normalized = requestPath.replace(/^\.\/+/u, '').replace(/^\/+/u, '');
+    return normalized === '.' ? '' : normalized;
+}
+function resolveInsideRoot(root, relativePath) {
+    const resolved = path.resolve(root, relativePath);
+    const relative = path.relative(root, resolved);
+    if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
+        return resolved;
+    }
+    throw new Error(`Refusing to access outside workspace: ${relativePath}. Use a visible path from FILES, such as input/file.md or artifact/file.js; do not use ../ to cross mounts.`);
+}
+function countTextLines(filePath) {
+    const buffer = fs.readFileSync(filePath);
+    if (buffer.subarray(0, 512).includes(0))
+        return null;
+    const text = buffer.toString('utf8');
+    return text.length === 0 ? 0 : text.split(/\r?\n/u).length;
+}
+//# sourceMappingURL=workspace-files.js.map

package/dist/builder/workspace-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-files.js","sourceRoot":"","sources":["../../src/builder/workspace-files.ts"],"names":[],"mappings":"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"}

package/dist/core/actions.d.ts

@@ -0,0 +1,55 @@
+import type { ActionDefinition, PeerConsultation, PromptContractStyle, PromptMode } from '../types.js';
+/**
+ * Build the actions rules section of the system prompt from action definitions.
+ * Each action's description IS a behavioral nudge (per playbook §4).
+ */
+export declare function buildActionsBlock(actions: Record<string, ActionDefinition> | undefined, promptMode?: PromptMode, contractStyle?: PromptContractStyle): string;
+/**
+ * Build an annotation string for a completed action (for history storage).
+ * Annotations are appended to stored messages so the AI doesn't re-process.
+ */
+export declare function buildActionAnnotation(actionName: string, params: Record<string, unknown>): string;
+/**
+ * Build a combined annotation string for multiple actions.
+ */
+export declare function buildAnnotations(actions: Array<{
+    name: string;
+    params: Record<string, unknown>;
+}>): string[];
+/**
+ * Annotate a message with outcome notes and raw action annotations for storage.
+ *
+ * Two-layer annotation system:
+ * - `---outcomes:` — AI-written outcome notes, preserved in LLM history so the AI
+ *   knows what it did on previous turns. Not shown to the user.
+ * - `---actions:` — Raw action data for debugging and UI pills. Stripped before
+ *   the AI sees history (to prevent API format leakage into future turns).
+ *
+ * Ordering matters: outcomes BEFORE actions, so stripping ---actions: preserves outcomes.
+ */
+export declare function annotateMessage(message: string, annotations: string[], outcomeNotes?: string[]): string;
+/**
+ * Build annotation text for peer consultations that occurred mid-turn.
+ * Appended to the assistant message so the persona sees consultation context
+ * in its history on subsequent turns.
+ */
+export declare function buildPeerAnnotation(consultations: PeerConsultation[]): string;
+/**
+ * Strip all annotation markers from a message for user-facing display.
+ * Removes both `---outcomes:` and `---actions:` — the user sees neither.
+ * Use this when returning stored messages to the frontend.
+ */
+export declare function stripAnnotationsForDisplay(content: string): string;
+/**
+ * Strip `---actions:` suffixes from assistant messages in history.
+ * Preserves `---outcomes:` so the AI knows what it did on previous turns.
+ *
+ * The raw action data is stripped to prevent API format leakage — the AI
+ * must not learn action names or param schemas from historical messages.
+ * Outcome notes are safe because they're AI-written natural language.
+ */
+export declare function stripActionAnnotations<T extends {
+    role: string;
+    content: string;
+}>(history: T[]): T[];
+//# sourceMappingURL=actions.d.ts.map

package/dist/core/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/core/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAoB,gBAAgB,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AA6HxH;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACrD,UAAU,GAAE,UAA2B,EACvC,aAAa,GAAE,mBAA4B,GAC1C,MAAM,CA8FR;AAcD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAChE,MAAM,EAAE,CAEV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAQ7E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAChF,OAAO,EAAE,CAAC,EAAE,GACX,CAAC,EAAE,CAOL"}