@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/specs/store.js

@@ -134,6 +134,12 @@ export class SpecStore {
     draftDir(id) {
         return path.join(this.root, DRAFTS_DIR, id);
     }
+    /**
+     * A draft may be created before its tasks exist: the journey's Spec stage
+     * writes requirements and design, and `tasks.md` arrives from the ImplPlan
+     * stage behind its own gate (`writeDraftTasks`). The one-shot `/spec` path
+     * passes all three and is unaffected.
+     */
     async createDraft(id, task, sections) {
         assertSafeSpecId(id);
         const dir = this.draftDir(id);
@@ -142,11 +148,24 @@ export class SpecStore {
         await mkdir(dir, { recursive: true });
         await writeFile(path.join(dir, 'requirements.md'), sections.requirements, 'utf8');
         await writeFile(path.join(dir, 'design.md'), sections.design, 'utf8');
-        await writeFile(path.join(dir, 'tasks.md'), sections.tasks, 'utf8');
+        if (sections.tasks !== undefined)
+            await writeFile(path.join(dir, 'tasks.md'), sections.tasks, 'utf8');
         const createdAt = new Date().toISOString();
         await writeFile(path.join(dir, DRAFT_FILENAME), JSON.stringify({ id, task, createdAt }, null, 2), 'utf8');
         return { id, task, createdAt, dir };
     }
+    /**
+     * Write (or replace) a draft's `tasks.md`, which is the ImplPlan stage's
+     * artefact. `writeFile` truncates, so running the stage again after the person
+     * chose "Revise them" replaces the list rather than appending to it.
+     */
+    async writeDraftTasks(id, tasks) {
+        assertSafeSpecId(id);
+        const draft = await this.getDraft(id);
+        if (!draft)
+            throw new Error(`no draft ${id}`);
+        await writeFile(path.join(draft.dir, 'tasks.md'), tasks, 'utf8');
+    }
     async getDraft(id) {
         if (!isSafeSpecId(id))
             return null;
@@ -187,6 +206,12 @@ export class SpecStore {
         // Finish the spec inside the draft folder, then move it into place with one rename,
         // so a spec directory never exists half-written.
         const tasksPath = path.join(draft.dir, 'tasks.md');
+        // A journey draft has no tasks until the ImplPlan stage has run. Approving
+        // then would produce a spec the Specs tree shows with nothing to run, so say
+        // what is missing instead.
+        if (!existsSync(tasksPath)) {
+            throw new Error(`draft ${id} has no tasks.md: the implementation plan stage has not run yet`);
+        }
         await writeFile(tasksPath, convertToCheckboxes(await readFile(tasksPath, 'utf8')), 'utf8');
         const summary = { id, task: draft.task, approvedAt: new Date().toISOString(), dir: specDir };
         await writeFile(path.join(draft.dir, MANIFEST_FILENAME), JSON.stringify(summary, null, 2), 'utf8');

package/dist/specs/types.d.ts

@@ -4,6 +4,17 @@ export interface SpecSections {
     design: string;
     tasks: string;
 }
+/**
+ * A draft mid-journey. The Spec stage writes requirements and design; `tasks`
+ * arrives later, from the ImplPlan stage, behind its own gate. `SpecSections`
+ * deliberately stays all-required: the one-shot `/spec` path produces all three
+ * at once and nothing about it changes.
+ */
+export interface SpecDraftSections {
+    requirements: string;
+    design: string;
+    tasks?: string;
+}
 /** An unapproved spec in `.forge/specs/.drafts/<id>/`. */
 export interface SpecDraft {
     id: string;

package/dist/steering/extra-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export declare function buildExtraInstructionsBlock(cwd: string, entries: readonly string[], deps?: {
+    fetch?: typeof fetch;
+}): Promise<string>;

package/dist/steering/extra-instructions.js

@@ -0,0 +1,104 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { pathMatchesGlob } from './glob.js';
+const PER_SOURCE_BYTES = 12_000;
+const TOTAL_BYTES = 48_000;
+const MAX_WALK_FILES = 5_000;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'out', 'build', '.next', 'target']);
+const URL_TIMEOUT_MS = 10_000;
+const isGlob = (s) => /[*?[]/.test(s);
+const isUrl = (s) => /^[a-z][a-z0-9+.-]*:\/\//i.test(s);
+async function walk(root) {
+    const out = [];
+    async function visit(dir, rel, depth) {
+        if (depth > 8 || out.length >= MAX_WALK_FILES)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (out.length >= MAX_WALK_FILES)
+                return;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    await visit(path.join(dir, e.name), r, depth + 1);
+            }
+            else if (e.isFile())
+                out.push(r);
+        }
+    }
+    await visit(root, '', 0);
+    return out;
+}
+const clip = (text) => (text.length > PER_SOURCE_BYTES ? `${text.slice(0, PER_SOURCE_BYTES)}\n…(truncated)` : text);
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export async function buildExtraInstructionsBlock(cwd, entries, deps = {}) {
+    const sources = [];
+    const seen = new Set();
+    const addFile = (label, abs) => {
+        const key = path.resolve(abs);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        sources.push({ label, read: () => readFile(abs, 'utf8') });
+    };
+    let walked;
+    for (const raw of entries) {
+        const entry = raw.trim();
+        if (!entry)
+            continue;
+        if (isUrl(entry)) {
+            if (!/^https?:\/\//i.test(entry) || seen.has(entry))
+                continue;
+            seen.add(entry);
+            sources.push({
+                label: entry,
+                read: async () => {
+                    const res = await (deps.fetch ?? fetch)(entry, { signal: AbortSignal.timeout(URL_TIMEOUT_MS) });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return (await res.text()).slice(0, PER_SOURCE_BYTES * 2);
+                },
+            });
+        }
+        else if (isGlob(entry) && !path.isAbsolute(entry) && !entry.startsWith('~')) {
+            walked ??= await walk(cwd);
+            for (const rel of walked.filter((f) => pathMatchesGlob(entry, f)))
+                addFile(rel, path.join(cwd, rel));
+        }
+        else {
+            const abs = entry.startsWith('~') ? path.join(homedir(), entry.slice(1)) : path.resolve(cwd, entry);
+            addFile(entry, abs);
+        }
+    }
+    const blocks = [];
+    let total = 0;
+    for (const s of sources) {
+        if (total >= TOTAL_BYTES)
+            break;
+        let text;
+        try {
+            text = (await s.read()).trim();
+        }
+        catch {
+            continue;
+        }
+        if (!text)
+            continue;
+        const body = clip(text);
+        total += body.length;
+        blocks.push(`<instructions source="${s.label.replace(/"/g, '')}">\n${body}\n</instructions>`);
+    }
+    return blocks.join('\n\n');
+}

package/dist/steering/folder-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `AGENTS.md` of every folder between the workspace root and the file just read (nearest first), each shown
+ * once per run. The root one is already in the system prompt, so it is never repeated here.
+ */
+export declare function folderInstructionsFor(filePath: string, cwd: string, shown: Set<string>): Promise<Array<{
+    file: string;
+    text: string;
+}> | undefined>;

package/dist/steering/folder-instructions.js

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_BYTES = 8_000;
+/**
+ * The `AGENTS.md` of every folder between the workspace root and the file just read (nearest first), each shown
+ * once per run. The root one is already in the system prompt, so it is never repeated here.
+ */
+export async function folderInstructionsFor(filePath, cwd, shown) {
+    const root = path.resolve(cwd);
+    let dir = path.dirname(path.resolve(filePath));
+    const out = [];
+    while (dir !== root && dir.startsWith(root + path.sep)) {
+        const abs = path.join(dir, 'AGENTS.md');
+        if (!shown.has(abs)) {
+            try {
+                const text = (await readFile(abs, 'utf8')).trim();
+                shown.add(abs);
+                if (text)
+                    out.push({ file: path.relative(root, abs), text: text.length > MAX_BYTES ? `${text.slice(0, MAX_BYTES)}\n…(truncated)` : text });
+            }
+            catch {
+                shown.add(abs);
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return out.length ? out : undefined;
+}

package/dist/steering/select.js

@@ -4,6 +4,7 @@
  */
 import path from 'node:path';
 import { pathMatchesGlob } from './glob.js';
+import { isOutsideRel } from '../tools/shared.js';
 export const START_BUDGET_BYTES = 12_000;
 export const TOOL_DOC_BYTES = 8_000;
 export const MAX_TOOL_INJECTIONS = 3;
@@ -19,7 +20,7 @@ export function stripSteering(text) {
 export function toWorkspaceRelative(cwd, p) {
     const abs = path.resolve(cwd, p);
     const rel = path.relative(cwd, abs);
-    if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+    if (!rel || isOutsideRel(rel))
         return null;
     return rel.split(path.sep).join('/');
 }

package/dist/timed-fetch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wraps `fetch` with the two timeouts Kilo calls `timeout` and `chunkTimeout`:
+ * - `timeoutMs`: how long to wait for the response to start (headers). It stops counting once the answer begins,
+ *   so a slow stream is never cut short by it.
+ * - `chunkTimeoutMs`: how long a streamed answer may stay silent. A stalled stream is aborted with a clear error
+ *   instead of hanging forever (a connection can stay open while the provider has stopped sending).
+ */
+export interface FetchTimeouts {
+    timeoutMs?: number;
+    chunkTimeoutMs?: number;
+}
+export declare function withTimeouts(base: typeof fetch, opts: FetchTimeouts): typeof fetch;

package/dist/timed-fetch.js

@@ -0,0 +1,83 @@
+export function withTimeouts(base, opts) {
+    const { timeoutMs, chunkTimeoutMs } = opts;
+    if (!timeoutMs && !chunkTimeoutMs)
+        return base;
+    return (async (input, init) => {
+        const controller = new AbortController();
+        const outer = init?.signal;
+        if (outer?.aborted)
+            controller.abort();
+        else
+            outer?.addEventListener('abort', () => controller.abort(), { once: true });
+        let reason;
+        const host = (() => {
+            try {
+                return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).host;
+            }
+            catch {
+                return 'the provider';
+            }
+        })();
+        const fail = (message) => {
+            reason = new Error(message);
+            controller.abort();
+        };
+        const headerTimer = timeoutMs ? setTimeout(() => fail(`The request to ${host} timed out after ${timeoutMs} ms.`), timeoutMs) : undefined;
+        let res;
+        try {
+            res = await base(input, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            throw reason ?? err;
+        }
+        finally {
+            if (headerTimer)
+                clearTimeout(headerTimer);
+        }
+        if (!chunkTimeoutMs || !res.body)
+            return res;
+        const reader = res.body.getReader();
+        let idle;
+        const arm = (onIdle) => {
+            if (idle)
+                clearTimeout(idle);
+            idle = setTimeout(onIdle, chunkTimeoutMs);
+        };
+        const body = new ReadableStream({
+            start(stream) {
+                arm(() => {
+                    fail(`No data for ${chunkTimeoutMs} ms from ${host}.`);
+                    stream.error(reason);
+                });
+            },
+            async pull(stream) {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (idle)
+                            clearTimeout(idle);
+                        stream.close();
+                        return;
+                    }
+                    arm(() => {
+                        fail(`No data for ${chunkTimeoutMs} ms from ${host}.`);
+                        stream.error(reason);
+                        void reader.cancel().catch(() => undefined);
+                    });
+                    stream.enqueue(value);
+                }
+                catch (err) {
+                    if (idle)
+                        clearTimeout(idle);
+                    stream.error(reason ?? err);
+                }
+            },
+            cancel(why) {
+                if (idle)
+                    clearTimeout(idle);
+                return reader.cancel(why);
+            },
+        });
+        return new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+    });
+}

package/dist/tools/apply-patch.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const params: z.ZodObject<{
+    patch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    patch: string;
+}, {
+    patch: string;
+}>;
+export type PatchOp = {
+    kind: 'add';
+    path: string;
+    content: string;
+} | {
+    kind: 'delete';
+    path: string;
+} | {
+    kind: 'update';
+    path: string;
+    hunks: Array<{
+        lines: Array<{
+            tag: ' ' | '-' | '+';
+            text: string;
+        }>;
+    }>;
+};
+/** Parse the patch text into operations. Throws on a malformed patch. */
+export declare function parsePatch(text: string): PatchOp[];
+/** Every path a patch touches, once each; empty when the text is not a valid patch (callers then fall back to the broadest target). */
+export declare function patchedPaths(patch: string): string[];
+export interface PatchPreview {
+    path: string;
+    /** Text before the patch; null when the file does not exist yet. */
+    before: string | null;
+    /** Text after the patch; null when the patch deletes the file. */
+    after: string | null;
+    /** Why this file's change could not be worked out (a hunk that does not match). */
+    error?: string;
+}
+/**
+ * What an `apply_patch` call would leave in each file, worked out in memory so it can be shown before it is approved.
+ * Never writes. Throws only for a patch that cannot be parsed at all.
+ */
+export declare function previewPatch(patch: string, read: (path: string) => Promise<string | null>): Promise<PatchPreview[]>;
+export interface ApplyPatchResult {
+    files: Array<{
+        action: 'add' | 'update' | 'delete';
+        path: string;
+    }>;
+}
+export declare const applyPatchTool: ToolDefinition<z.infer<typeof params>, ApplyPatchResult>;
+export {};

package/dist/tools/apply-patch.js

@@ -0,0 +1,197 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { resolveAndCheckPath } from './shared.js';
+import { decodeText, encodeText } from './text-encoding.js';
+const params = z.object({
+    patch: z
+        .string()
+        .min(1)
+        .describe('The patch. Starts with "*** Begin Patch", ends with "*** End Patch". Between them, per file: "*** Add File: path" followed by lines starting with +; "*** Delete File: path"; or "*** Update File: path" followed by hunks that begin with "@@" and whose lines start with a space (kept), - (removed) or + (added).'),
+});
+/** Parse the patch text into operations. Throws on a malformed patch. */
+export function parsePatch(text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    while (lines.length && lines[0].trim() === '')
+        lines.shift();
+    while (lines.length && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    if (lines[0]?.trim() !== '*** Begin Patch' || lines[lines.length - 1]?.trim() !== '*** End Patch') {
+        throw new Error('A patch must start with "*** Begin Patch" and end with "*** End Patch".');
+    }
+    const body = lines.slice(1, -1);
+    const ops = [];
+    let i = 0;
+    while (i < body.length) {
+        const line = body[i];
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+        const add = /^\*\*\* Add File: (.+)$/.exec(line);
+        const del = /^\*\*\* Delete File: (.+)$/.exec(line);
+        const upd = /^\*\*\* Update File: (.+)$/.exec(line);
+        if (add) {
+            const content = [];
+            i++;
+            while (i < body.length && !body[i].startsWith('*** ')) {
+                const l = body[i];
+                if (!l.startsWith('+'))
+                    throw new Error(`Add File ${add[1]}: every line must start with + (got "${l.slice(0, 40)}").`);
+                content.push(l.slice(1));
+                i++;
+            }
+            ops.push({ kind: 'add', path: add[1].trim(), content: content.length ? `${content.join('\n')}\n` : '' });
+        }
+        else if (del) {
+            ops.push({ kind: 'delete', path: del[1].trim() });
+            i++;
+        }
+        else if (upd) {
+            const hunks = [];
+            i++;
+            while (i < body.length && !body[i].startsWith('*** ')) {
+                if (body[i].startsWith('@@')) {
+                    hunks.push({ lines: [] });
+                    i++;
+                    continue;
+                }
+                const l = body[i];
+                const tag = l[0];
+                if (tag !== ' ' && tag !== '-' && tag !== '+')
+                    throw new Error(`Update File ${upd[1]}: bad hunk line "${l.slice(0, 40)}" (start with space, - or +).`);
+                if (hunks.length === 0)
+                    hunks.push({ lines: [] });
+                hunks[hunks.length - 1].lines.push({ tag, text: l.slice(1) });
+                i++;
+            }
+            if (hunks.length === 0)
+                throw new Error(`Update File ${upd[1]} has no hunks.`);
+            ops.push({ kind: 'update', path: upd[1].trim(), hunks });
+        }
+        else {
+            throw new Error(`Unknown patch directive: "${line.slice(0, 60)}"`);
+        }
+    }
+    if (ops.length === 0)
+        throw new Error('The patch has no operations.');
+    return ops;
+}
+/** Every path a patch touches, once each; empty when the text is not a valid patch (callers then fall back to the broadest target). */
+export function patchedPaths(patch) {
+    try {
+        return [...new Set(parsePatch(patch).map((o) => o.path))];
+    }
+    catch {
+        return [];
+    }
+}
+function indexOfSeq(hay, needle, from, norm) {
+    if (needle.length === 0)
+        return from;
+    outer: for (let s = from; s <= hay.length - needle.length; s++) {
+        for (let k = 0; k < needle.length; k++)
+            if (norm(hay[s + k]) !== norm(needle[k]))
+                continue outer;
+        return s;
+    }
+    return -1;
+}
+/** Apply update hunks to file text, in order, each searching after the previous one. Exact match first, then ignoring trailing whitespace. */
+function applyHunks(file, original, hunks) {
+    const eol = original.includes('\r\n') ? '\r\n' : '\n';
+    const endsWithNewline = original.endsWith('\n');
+    const lines = original.replace(/\r\n/g, '\n').split('\n');
+    if (endsWithNewline)
+        lines.pop();
+    let cursor = 0;
+    for (const [n, hunk] of hunks.entries()) {
+        const oldSeq = hunk.lines.filter((l) => l.tag !== '+').map((l) => l.text);
+        const newSeq = hunk.lines.filter((l) => l.tag !== '-').map((l) => l.text);
+        let at = indexOfSeq(lines, oldSeq, cursor, (s) => s);
+        if (at === -1)
+            at = indexOfSeq(lines, oldSeq, cursor, (s) => s.trimEnd());
+        if (at === -1)
+            throw new Error(`Hunk ${n + 1} of ${file} did not match the file. Re-read it and make the context lines exact.`);
+        lines.splice(at, oldSeq.length, ...newSeq);
+        cursor = at + newSeq.length;
+    }
+    return lines.join(eol) + (endsWithNewline ? eol : '');
+}
+/**
+ * What an `apply_patch` call would leave in each file, worked out in memory so it can be shown before it is approved.
+ * Never writes. Throws only for a patch that cannot be parsed at all.
+ */
+export async function previewPatch(patch, read) {
+    const out = [];
+    for (const op of parsePatch(patch)) {
+        const before = await read(op.path);
+        if (op.kind === 'add')
+            out.push({ path: op.path, before, after: op.content });
+        else if (op.kind === 'delete')
+            out.push({ path: op.path, before, after: null });
+        else if (before === null)
+            out.push({ path: op.path, before, after: null, error: `File not found: ${op.path}` });
+        else {
+            try {
+                out.push({ path: op.path, before, after: applyHunks(op.path, before, op.hunks) });
+            }
+            catch (err) {
+                out.push({ path: op.path, before, after: null, error: err.message });
+            }
+        }
+    }
+    return out;
+}
+export const applyPatchTool = {
+    name: 'apply_patch',
+    description: 'Change several files in one step with a patch: add files, delete files, or update files by hunks of context and changed lines. All or nothing: if one hunk does not match, no file is touched. Prefer edit_file for a single small change.',
+    parameters: params,
+    destructive: false,
+    execute: async (args, ctx) => {
+        const ops = parsePatch(args.patch);
+        // Plan every change in memory first, so a bad hunk leaves the workspace as it was.
+        const writes = new Map();
+        const encodings = new Map();
+        const deletes = new Set();
+        const files = [];
+        for (const op of ops) {
+            const abs = resolveAndCheckPath(op.path, ctx);
+            const rel = op.path.split(String.fromCharCode(92)).join('/');
+            if (op.kind === 'add') {
+                const exists = await readFile(abs, 'utf8').then(() => true, () => false);
+                if ((exists && !deletes.has(abs)) || writes.has(abs))
+                    throw new Error(`Cannot add ${op.path}: it already exists.`);
+                writes.set(abs, op.content);
+                files.push({ action: 'add', path: rel });
+            }
+            else if (op.kind === 'delete') {
+                await readFile(abs, 'utf8').catch(() => {
+                    throw new Error(`Cannot delete ${op.path}: file not found.`);
+                });
+                deletes.add(abs);
+                writes.delete(abs);
+                files.push({ action: 'delete', path: rel });
+            }
+            else {
+                let current = writes.get(abs);
+                if (current === undefined) {
+                    const decoded = await readFile(abs).then(decodeText, () => {
+                        throw new Error(`Cannot update ${op.path}: file not found.`);
+                    });
+                    current = decoded.text;
+                    encodings.set(abs, decoded.encoding);
+                }
+                writes.set(abs, applyHunks(op.path, current, op.hunks));
+                files.push({ action: 'update', path: rel });
+            }
+        }
+        for (const abs of deletes)
+            await rm(abs);
+        for (const [abs, content] of writes) {
+            await mkdir(path.dirname(abs), { recursive: true });
+            await writeFile(abs, encodeText(content, encodings.get(abs) ?? 'utf8'));
+        }
+        return { files };
+    },
+};

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+/**
+ * Ask the person a question with optional choices. The agent only offers this tool when a surface can answer
+ * (AgentConfig.askUser) and the run is not autonomous; if it is called anyway, or the run is stopped while the
+ * question is open, it returns a result that tells the model to carry on with the safest option.
+ */
+declare const params: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowCustom: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    options?: string[] | undefined;
+    allowCustom?: boolean | undefined;
+}, {
+    question: string;
+    options?: string[] | undefined;
+    allowCustom?: boolean | undefined;
+}>;
+export interface AskUserResult {
+    answer: string;
+    unavailable?: boolean;
+    note?: string;
+}
+export declare const askUserTool: ToolDefinition<z.infer<typeof params>, AskUserResult>;
+export {};

package/dist/tools/ask-user.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * Ask the person a question with optional choices. The agent only offers this tool when a surface can answer
+ * (AgentConfig.askUser) and the run is not autonomous; if it is called anyway, or the run is stopped while the
+ * question is open, it returns a result that tells the model to carry on with the safest option.
+ */
+const params = z.object({
+    question: z.string().min(1).max(1000).describe('One clear question.'),
+    options: z.array(z.string().min(1).max(200)).max(8).optional().describe('Suggested answers to pick from.'),
+    allowCustom: z.boolean().optional().describe('Let the person type their own answer. Default true.'),
+});
+const UNAVAILABLE = {
+    answer: '',
+    unavailable: true,
+    note: 'No user is available. Choose the safest reasonable option and say what you assumed.',
+};
+/**
+ * A guided journey asks at most four questions. The budget is enforced here
+ * rather than in prompt text for the same reason stage gates live in the tool
+ * sandbox: a limit the model is merely told about is a limit it will exceed,
+ * and one bad extra question is what makes an interview feel like an
+ * interrogation (spec anti-goal 3).
+ */
+const BUDGET_SPENT = {
+    answer: '',
+    unavailable: true,
+    note: 'The question budget for this journey is spent: no more questions. Proceed with what you have and say what you assumed.',
+};
+export const askUserTool = {
+    name: 'ask_user',
+    description: 'Ask the user a clarifying question when you cannot proceed safely without their answer. Give a few options when you can. Do not ask for permission to run tools; approvals are handled separately.',
+    parameters: params,
+    noApproval: true,
+    execute: async (args, ctx) => {
+        if (!ctx.askUser || ctx.auto)
+            return UNAVAILABLE;
+        const signal = ctx.abortSignal;
+        if (signal?.aborted)
+            return UNAVAILABLE;
+        // Counted only once the question is actually put to a surface, so a refused
+        // or impossible question never spends part of the budget.
+        if (ctx.askBudget) {
+            if (ctx.askBudget.used >= ctx.askBudget.max)
+                return BUDGET_SPENT;
+            ctx.askBudget.used += 1;
+        }
+        const budget = ctx.askBudget;
+        const answered = ctx.askUser(args, signal).then((answer) => {
+            // A question the person dismissed resolves to an empty answer and must not
+            // cost part of the budget: four dismissals would otherwise end an interview
+            // without a single question being answered. Refunding keeps the budget a
+            // count of questions actually answered.
+            if (budget && answer.trim() === '')
+                budget.used = Math.max(0, budget.used - 1);
+            return { answer };
+        });
+        const aborted = new Promise((resolve) => signal?.addEventListener('abort', () => resolve(UNAVAILABLE), { once: true }));
+        return Promise.race([answered, aborted]);
+    },
+};