@ikarmic/forge-core 5.3.0 → 5.4.0

package/dist/tools/shared.js

@@ -1,4 +1,5 @@
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { checkPolicyViolation } from './policy.js';
 /**
@@ -15,11 +16,82 @@ export function resolveSafePath(inputPath, ctx, options = {}) {
     if (!options.allowOutside) {
         // Lexically, then for real: a symlink or junction inside the workspace can point anywhere on disk.
         if (escapes(ctx.cwd, resolved) || escapes(realPath(ctx.cwd), realPath(resolved))) {
-            throw new Error(`Path "${inputPath}" resolves outside of the working directory (${ctx.cwd}).`);
+            // A read may also reach a folder this run was explicitly given (a repository it cloned), never anything else.
+            if (options.read && inReadRoot(resolved, ctx))
+                return resolved;
+            throw new OutsideWorkspaceError(`Path "${inputPath}" resolves outside of the working directory (${ctx.cwd}).`);
         }
     }
     return resolved;
 }
+/** A path that leads outside the working directory: the one error a host may answer by asking (G16). */
+export class OutsideWorkspaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OutsideWorkspaceError';
+    }
+}
+/** Is `resolved` inside one of the run's extra read roots, judged by where it really is after links (RB-20)? */
+function inReadRoot(resolved, ctx) {
+    const real = realPath(resolved);
+    return (ctx.readRoots ?? []).some((root) => !escapes(realPath(root), real));
+}
+const SENSITIVE_DIRS = new Set(['.ssh', '.aws', '.gnupg', '.kube', '.azure', '.docker', '.password-store', 'credentials', 'protect', 'user data']);
+/** Why a directory must not be offered for reading, or undefined: too broad to be a choice, or holds credentials. */
+function notOfferable(dir) {
+    if (path.parse(dir).root === dir)
+        return 'it is the top of a drive, too broad to open';
+    let home;
+    try {
+        home = realpathSync.native(homedir());
+    }
+    catch {
+        home = undefined;
+    }
+    // The home folder and everything above it would open the credential folders inside it.
+    if (home && !escapes(dir, home))
+        return 'it is your home folder or a folder above it, too broad to open';
+    const key = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+    if (path.normalize(dir).split(path.sep).some((part) => SENSITIVE_DIRS.has(key(part))))
+        return 'it holds credentials';
+    return undefined;
+}
+/**
+ * `resolveAndCheckPath` for a READ tool, with one more way to succeed: when the path leads outside the project and the host
+ * can ask, the person is asked about the real directory (links resolved), once per directory per run. A yes opens that
+ * directory and below to read tools; a no, or a directory that is too broad or holds credentials, is a refusal.
+ */
+export async function resolveReadPath(inputPath, ctx) {
+    try {
+        return resolveAndCheckPath(inputPath, ctx, { read: true });
+    }
+    catch (err) {
+        if (!(err instanceof OutsideWorkspaceError) || !ctx.askReadOutside)
+            throw err;
+        const resolved = path.isAbsolute(inputPath) ? path.normalize(inputPath) : path.resolve(ctx.cwd, inputPath);
+        const real = realPath(resolved);
+        let isDir = false;
+        try {
+            isDir = statSync(real).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        const dir = isDir ? real : path.dirname(real);
+        const key = process.platform === 'win32' ? dir.toLowerCase() : dir;
+        if (ctx.deniedReadDirs?.has(key))
+            throw err;
+        const why = notOfferable(dir);
+        if (why)
+            throw new OutsideWorkspaceError(`Path "${inputPath}" is outside the working directory, and Forge will not offer to open ${dir}: ${why}.`);
+        if (!(await ctx.askReadOutside(dir))) {
+            (ctx.deniedReadDirs ??= new Set()).add(key);
+            throw new OutsideWorkspaceError(`Path "${inputPath}" is outside the working directory, and reading in ${dir} was not allowed.`);
+        }
+        (ctx.readRoots ??= []).push(dir);
+        return resolveAndCheckPath(inputPath, ctx, { read: true });
+    }
+}
 /**
  * For a `path.relative(root, target)` result: does it lead out of `root`? `..` itself or `../…` does; a name that merely
  * starts with two dots (`..notes.md`) does not. Use this instead of `rel.startsWith('..')`.
@@ -53,8 +125,8 @@ function realPath(p) {
  * tools call this instead of `resolveSafePath` directly so the sandbox is
  * applied uniformly.
  */
-export function resolveAndCheckPath(inputPath, ctx) {
-    const resolved = resolveSafePath(inputPath, ctx);
+export function resolveAndCheckPath(inputPath, ctx, options = {}) {
+    const resolved = resolveSafePath(inputPath, ctx, options);
     const violation = checkPolicyViolation(ctx.policy, { cwd: ctx.cwd, resolvedPath: resolved });
     if (violation)
         throw new Error(`[sandbox] ${violation}`);

package/dist/tools/shell.d.ts

@@ -0,0 +1,27 @@
+export type ShellKind = 'pwsh' | 'powershell' | 'bash' | 'cmd' | 'sh';
+/** What a person can ask for. */
+export type ShellPreference = 'auto' | 'pwsh' | 'powershell' | 'bash' | 'cmd';
+export interface ShellChoice {
+    kind: ShellKind;
+    /** The program to start; absent for cmd.exe and sh, which `spawn(..., { shell: true })` finds itself. */
+    file?: string;
+}
+export interface ChooseShellInput {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    preference?: ShellPreference;
+    /** Tests: does this file exist? */
+    exists?: (file: string) => boolean;
+    /** Tests: where is this program on PATH? */
+    find?: (name: string) => string | undefined;
+    /** Tests: Git Bash, when known. */
+    gitBash?: string | undefined;
+}
+export declare function chooseShell(input: ChooseShellInput): ShellChoice;
+/** The program and arguments that run `command` in `shell`. `file` is undefined for cmd.exe and sh: use `shell: true`. */
+export declare function shellInvocation(shell: ShellChoice, command: string): {
+    file: string | undefined;
+    args: string[];
+};
+/** The shell for this machine, looked up once per preference. */
+export declare function runnerShell(preference?: ShellPreference | undefined, platform?: NodeJS.Platform): ShellChoice;

package/dist/tools/shell.js

@@ -0,0 +1,80 @@
+/**
+ * Which shell Forge's own command runner uses (G11). On Windows `cmd.exe` has no `ls`, `cat` or `grep`, and models
+ * write worse commands for it, so the runner prefers `pwsh`, then Windows PowerShell, then Git Bash, then `cmd.exe`.
+ * Elsewhere it stays `/bin/sh`. In VS Code the command runs in the integrated terminal instead and this is not used.
+ *
+ * RB-24 still holds: a shell started in the workspace must not run a program the repository ships. cmd.exe is
+ * handled by `shellEnv`; PowerShell and bash look in PATH only (a script in the current folder needs `.\`).
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveOnPath } from '../lsp/client.js';
+/** `bash.exe` of a Git for Windows install, found from `git` on PATH. Never `System32\bash.exe`, which starts WSL. */
+function findGitBash(input, find, exists) {
+    if (input.gitBash !== undefined)
+        return input.gitBash;
+    const git = find('git');
+    if (!git)
+        return undefined;
+    const root = path.dirname(path.dirname(git));
+    for (const rel of [['bin', 'bash.exe'], ['usr', 'bin', 'bash.exe']]) {
+        const candidate = path.join(root, ...rel);
+        if (exists(candidate) && !/system32/i.test(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+export function chooseShell(input) {
+    if (input.platform !== 'win32')
+        return { kind: 'sh' };
+    const exists = input.exists ?? existsSync;
+    const find = input.find ?? ((n) => resolveOnPath(n, input.env, 'win32'));
+    const pwsh = find('pwsh');
+    const powershell = find('powershell');
+    const bash = findGitBash(input, find, exists);
+    const available = {
+        pwsh: pwsh ? { kind: 'pwsh', file: pwsh } : undefined,
+        powershell: powershell ? { kind: 'powershell', file: powershell } : undefined,
+        bash: bash ? { kind: 'bash', file: bash } : undefined,
+        cmd: { kind: 'cmd' },
+    };
+    const pref = input.preference ?? 'auto';
+    if (pref !== 'auto' && available[pref])
+        return available[pref];
+    // Asked for a shell that is not installed: fall through the usual order.
+    return available.pwsh ?? available.powershell ?? available.bash ?? available.cmd;
+}
+/**
+ * `powershell -Command` ends with exit code 1 when the last command failed, whatever the code of a native program was.
+ * This keeps the program's own code (node, git and npm tell apart failures by it) with the status of the LAST command,
+ * as sh and cmd report it: a native failure followed by a cmdlet that works is a success. The tail is on its own line
+ * so a trailing comment in the command cannot swallow it.
+ */
+function withExitCode(command) {
+    return `$global:LASTEXITCODE = $null\n${command}\nif (-not $?) { if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { exit $LASTEXITCODE } else { exit 1 } }`;
+}
+/** The program and arguments that run `command` in `shell`. `file` is undefined for cmd.exe and sh: use `shell: true`. */
+export function shellInvocation(shell, command) {
+    switch (shell.kind) {
+        case 'pwsh':
+            return { file: shell.file, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', withExitCode(command)] };
+        case 'powershell':
+            // Windows PowerShell writes the console code page (not UTF-8) to a pipe, which mangles accents and CJK text.
+            return { file: shell.file, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `[Console]::OutputEncoding=[System.Text.Encoding]::UTF8\n${withExitCode(command)}`] };
+        case 'bash':
+            return { file: shell.file, args: ['-c', command] };
+        default:
+            return { file: undefined, args: [] };
+    }
+}
+const cache = new Map();
+/** The shell for this machine, looked up once per preference. */
+export function runnerShell(preference = 'auto', platform = process.platform) {
+    const key = `${platform}:${preference}`;
+    let found = cache.get(key);
+    if (!found) {
+        found = chooseShell({ platform, env: process.env, preference });
+        cache.set(key, found);
+    }
+    return found;
+}

package/dist/tools/sub-agent.js

@@ -107,7 +107,9 @@ const DEFAULT_MAX_ITERATIONS = 10;
  *    passing `allowSubAgent: true` via context if you really want it)
  *  - nothing else: the sub-agent gets the full built-in toolset.
  */
-const FORBIDDEN_TOOLS = new Set(['sub_agent', 'sub_agent_wait']);
+// A child has no one to approve a command and no run of its own to stop a process when it ends, so it gets no
+// background processes either (RB-14).
+const FORBIDDEN_TOOLS = new Set(['sub_agent', 'sub_agent_wait', 'bg_start', 'bg_read', 'bg_stop', 'schedule_wakeup', 'cancel_wakeup', 'repo_clone', 'suggest_plan']);
 /**
  * Delegate a task to a child agent. The child runs synchronously and its
  * final text + run statistics are returned to the parent. Useful for

package/dist/tools/suggest-plan.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const params: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+export interface SuggestPlanResult {
+    /** True when the chat will ask the person; the model should then stop. */
+    suggested: boolean;
+    reason?: string;
+    note: string;
+}
+/**
+ * `suggest_plan`: the model says a request is big or unclear enough to plan before changing anything. It only signals.
+ * The chat reads the result after the run and asks the person ("Plan first / Just do it"); "Just do it" runs the request
+ * again with `planDeclined` set, so the model cannot ask twice. Where no chat can ask, it says to carry on.
+ */
+export declare const suggestPlanTool: ToolDefinition<z.infer<typeof params>, SuggestPlanResult>;
+export {};

package/dist/tools/suggest-plan.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+const params = z.object({
+    reason: z.string().min(1).describe('One sentence on why this needs a plan first, for the person to read.'),
+});
+/**
+ * `suggest_plan`: the model says a request is big or unclear enough to plan before changing anything. It only signals.
+ * The chat reads the result after the run and asks the person ("Plan first / Just do it"); "Just do it" runs the request
+ * again with `planDeclined` set, so the model cannot ask twice. Where no chat can ask, it says to carry on.
+ */
+export const suggestPlanTool = {
+    name: 'suggest_plan',
+    description: 'Suggest planning first when a request asks for a whole system or feature, a redesign or rewrite, or work of more than about ten steps or five files. ' +
+        'The person is asked whether to plan first. Call it as your first action, before reading or editing anything, then stop and reply with one short sentence. Not for a simple edit, a question, or when they asked for a plan or told you to just do it.',
+    parameters: params,
+    execute: async (args, ctx) => {
+        if (ctx.planDeclined) {
+            return { suggested: false, note: 'The person already chose to go ahead without a plan. Carry on with the task.' };
+        }
+        if (!ctx.suggestPlan) {
+            return { suggested: false, note: 'Nobody can be asked here. Carry on with the task, and state your plan in a sentence or two first.' };
+        }
+        return {
+            suggested: true,
+            reason: args.reason,
+            note: 'The person is being asked whether to plan first. Stop now: do not change any file or run any command, and reply with one short sentence saying you suggested planning first.',
+        };
+    },
+};

package/dist/types.d.ts

@@ -117,6 +117,35 @@ export interface ToolContext {
     shownFolderInstructions?: Set<string>;
     /** Longest output `run_command` returns per stream before cutting the middle (`AgentConfig.maxToolOutputChars`). */
     maxOutputChars?: number;
+    /**
+     * Folders outside the project that READ tools may also reach: a repository this run cloned with `repo_clone`.
+     * Added to by that tool only; write tools never see them (shared.ts `resolveSafePath` `read` option). Not handed to a child.
+     */
+    readRoots?: string[];
+    /**
+     * Asks whether a directory outside the project may be read (G16). Given the real directory, after links. Absent: such a
+     * path is refused. Not handed to a child, which has no one to ask.
+     */
+    askReadOutside?: (dir: string) => boolean | Promise<boolean>;
+    /** Directories the person already refused in this run, so they are not asked again. */
+    deniedReadDirs?: Set<string>;
+    /** Where `repo_clone` keeps repositories (default `~/.forge/cache/repos`). `testGitConfig` is for tests only. */
+    repoCache?: {
+        root: string;
+        testGitConfig?: string[];
+    };
+    /** A chat can ask the person about planning first (`AgentConfig.suggestPlan`). */
+    suggestPlan?: boolean;
+    /** The person already chose "just do it" for this request (`AgentConfig.planDeclined`). */
+    planDeclined?: boolean;
+    /** Which shell the default `run_command` runner uses (`AgentConfig.shell`). */
+    shell?: import('./tools/shell.js').ShellPreference;
+    /** The chat's wakeup scheduler (`AgentConfig.wakeups`); never handed to a child. */
+    wakeups?: import('./wakeup/wakeup.js').WakeupScheduler;
+    /** The run's background processes (`bg_start`); the agent stops them when the run ends. Never handed to a child. */
+    processes?: import('./tools/background-process.js').BackgroundProcesses;
+    /** Language servers for `get_diagnostics` (`AgentConfig.verify.lsp` when it is an object). */
+    lspConfig?: import('./lsp/index.js').LspConfig;
     /** Asks the person a question (`ask_user`); absent when no surface can answer. */
     askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
     /**
@@ -186,6 +215,16 @@ export interface CommandSandbox {
     network: boolean;
     /** More folders commands may write to (a package manager's cache, say). */
     extraWritable?: string[];
+    /**
+     * With the network off: hosts Forge's own network tools (fetch_url, repo_clone, the browser, GitHub, web search with `*`) may still
+     * reach. Exact names, `*.example.com`, or `*`. Shell commands are all or nothing and ignore it (F13).
+     */
+    allowedHosts?: string[];
+    /**
+     * The surface told the person this system cannot confine commands (Windows has no sandbox tool) and they go on anyway.
+     * Without it such a command is refused rather than run unconfined in silence.
+     */
+    allowUnconfined?: boolean;
 }
 /**
  * Executes one shell command on behalf of `run_command`. Return `null` to decline
@@ -665,6 +704,7 @@ export interface AgentConfig {
     maskOldResults?: boolean | {
         keepRecentTurns?: number;
         minChars?: number;
+        protectTokens?: number;
     };
     /**
      * Model to use for the summarizer. Defaults to the agent's own model.
@@ -717,6 +757,10 @@ export interface AgentConfig {
         extensions?: string[];
         minScore?: number;
         defaultLimit?: number;
+        /** Asked before code is sent to a remote embedder (F12). Absent: no question. */
+        consent?: import('./semantic/semantic-index.js').SemanticOptions['consent'];
+        /** Progress of the index, for a status item. */
+        onStatus?: import('./semantic/semantic-index.js').SemanticOptions['onStatus'];
     };
     /**
      * After the model finishes a run that edited files, run these commands and
@@ -754,6 +798,31 @@ export interface AgentConfig {
      * linter commands) and append any problems to the tool result so the model fixes them.
      */
     autoLint?: import('./lint/auto-lint.js').AutoLintConfig;
+    /**
+     * After a file is written, run the person's formatter for its type on it (`prettier --write`), before auto-lint, and tell
+     * the model when the file changed. The commands run on every edit without asking, so they come from the person only (RB-12).
+     */
+    autoFormat?: import('./format/auto-format.js').AutoFormatConfig;
+    /** The surface shows a "plan first?" card after a run that called `suggest_plan`. Without it the tool says to carry on. */
+    suggestPlan?: boolean;
+    /** The person already answered "just do it": `suggest_plan` says to carry on instead of asking again. */
+    planDeclined?: boolean;
+    /** Folders outside the project that read tools may reach from the start of the run: what the person allowed earlier in this chat (G16). */
+    readRoots?: string[];
+    /** Asks the person whether a directory outside the project may be read; absent = such a path is refused. */
+    askReadOutside?: (dir: string) => boolean | Promise<boolean>;
+    /** Which shell Forge's own `run_command` runner uses on Windows. Default `auto`: pwsh, Windows PowerShell, Git Bash, cmd.exe. */
+    shell?: import('./tools/shell.js').ShellPreference;
+    /**
+     * The shell commands really run in when a surface supplies its own runner (VS Code's terminal), so the prompt can say so
+     * (RB-27). Without it a custom runner is described as the platform default.
+     */
+    runnerShell?: import('./tools/shell.js').ShellKind;
+    /**
+     * The chat's scheduler for `schedule_wakeup` / `cancel_wakeup`. Lives longer than a run: the surface creates it once per
+     * chat, delivers a due wakeup as an automatic message, and disposes it. Absent = the tools are not offered.
+     */
+    wakeups?: import('./wakeup/wakeup.js').WakeupScheduler;
     /**
      * Stop the run (`reason: 'budget_exceeded'`) once the running USD cost reaches
      * this cap. Checked before each model call, so one in-flight turn can overshoot.
@@ -944,6 +1013,11 @@ export interface AgentRunResult {
      * across turns (used by the REPL).
      */
     messages: ModelMessage[];
+    /**
+     * This run's own messages: its user message and everything added after it, untouched by compaction (RB-58).
+     * Append them to a display transcript; `messages` is what the next turn should send.
+     */
+    turnMessages: ModelMessage[];
 }
 /** Public alias for the AI SDK language model handle. */
 export type AnyLanguageModel = LanguageModel;

package/dist/wakeup/wakeup-tools.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+declare const scheduleParams: z.ZodObject<{
+    reason: z.ZodString;
+    delay: z.ZodOptional<z.ZodString>;
+    when: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const scheduleWakeupTool: ToolDefinition<z.infer<typeof scheduleParams>, {
+    id: string;
+    dueAt: string;
+    notice?: string;
+    note: string;
+}>;
+declare const cancelParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const cancelWakeupTool: ToolDefinition<z.infer<typeof cancelParams>, {
+    id: string;
+    cancelled: boolean;
+}>;
+export {};

package/dist/wakeup/wakeup-tools.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+function scheduler(ctx) {
+    if (!ctx.wakeups)
+        throw new Error('Scheduled wakeups are not available here.');
+    return ctx.wakeups;
+}
+const scheduleParams = z.object({
+    reason: z.string().min(1).describe('Why you want to be woken, in one sentence. You will see it again when the time comes.'),
+    delay: z.string().optional().describe('How long to wait: a number of seconds, or 30s, 5m, 2h, 1d. Give this or when.'),
+    when: z.string().optional().describe('An exact time as ISO date and time, for example 2026-10-27T15:30:00. Give this or delay.'),
+    prompt: z.string().optional().describe('What you will do when woken, in your own words.'),
+});
+export const scheduleWakeupTool = {
+    name: 'schedule_wakeup',
+    description: 'Ask to be woken once, later, for example to check on a build or a background process. At the time you get an automatic message with your reason. ' +
+        'It works only while the editor is open (a closed editor wakes you when it is next opened), one time per call, at least 10 seconds and at most 7 days ahead, and a chat holds at most 10.',
+    parameters: scheduleParams,
+    execute: async (args, ctx) => {
+        const w = await scheduler(ctx).schedule(args);
+        return {
+            id: w.id,
+            dueAt: new Date(w.dueAt).toISOString(),
+            ...(w.notice ? { notice: w.notice } : {}),
+            note: 'Scheduled. Finish what you are doing now; do not wait for it.',
+        };
+    },
+};
+const cancelParams = z.object({ id: z.string().describe('The id returned by schedule_wakeup.') });
+export const cancelWakeupTool = {
+    name: 'cancel_wakeup',
+    description: 'Cancel a wakeup you scheduled with schedule_wakeup, before it fires.',
+    parameters: cancelParams,
+    execute: async (args, ctx) => ({ id: args.id, cancelled: await scheduler(ctx).cancel(args.id) }),
+};

package/dist/wakeup/wakeup.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Scheduled wakeups: the model asks to be woken later ("check the build in 10 minutes") and the chat delivers an
+ * automatic message when the time comes. The scheduler belongs to the chat, not to a run, and works only while the
+ * editor is open. Caps follow Kilo's wakeup/schema.ts; recurring (cron) wakeups are not offered.
+ */
+/** A delay under this is raised to it; an absolute time is honoured as given. */
+export declare const MIN_DELAY_MS = 10000;
+/** A wakeup never fires further out than seven days. */
+export declare const MAX_HORIZON_MS: number;
+/** One chat holds at most this many pending wakeups. */
+export declare const MAX_PER_SESSION = 10;
+export interface Wakeup {
+    id: string;
+    /** Why the model wants to be woken; shown to the model again and to the person. */
+    reason: string;
+    /** What to do when woken, in the model's own words. */
+    prompt?: string;
+    /** Epoch milliseconds. */
+    dueAt: number;
+    created: number;
+}
+/** Where pending wakeups are kept so they survive a reload of the editor. */
+export interface WakeupStore {
+    load(): Promise<Wakeup[]>;
+    save(wakeups: Wakeup[]): Promise<void>;
+}
+/** When a wakeup is due, with the clamp that applied (as a sentence for the model), or an error naming the problem. */
+export declare function resolveWakeupTime(input: {
+    delay?: string;
+    when?: string;
+}, now?: number): {
+    dueAt: number;
+    notice?: string;
+};
+export interface WakeupSchedulerOptions {
+    /** Deliver a due wakeup. Return false when the chat is busy: it is offered again after `retryMs`. */
+    onDue: (wakeup: Wakeup) => Promise<boolean>;
+    store?: WakeupStore;
+    retryMs?: number;
+}
+export declare class WakeupScheduler {
+    private readonly options;
+    private readonly pending;
+    private readonly timers;
+    private nextId;
+    private disposed;
+    private readonly retryMs;
+    constructor(options: WakeupSchedulerOptions);
+    list(): Wakeup[];
+    schedule(input: {
+        delay?: string;
+        when?: string;
+        reason: string;
+        prompt?: string;
+    }): Promise<Wakeup & {
+        notice?: string;
+    }>;
+    cancel(id: string): Promise<boolean>;
+    cancelAll(): Promise<void>;
+    /** Load what a previous window left; anything already due fires on the next tick. */
+    restore(): Promise<void>;
+    /** Stop every timer without forgetting what is stored (the editor is closing, or the chat was deleted elsewhere). */
+    dispose(): void;
+    private arm;
+    private disarm;
+    private fire;
+    private save;
+}
+/**
+ * The automatic message a due wakeup becomes. It is a user-role message, so it says what it is and that the person's
+ * own words win: the first wording of the todo nudge ("carry on now") overrode "wait for my go-ahead" in live runs (RB-44).
+ */
+export declare function wakeupMessage(w: Pick<Wakeup, 'reason' | 'prompt' | 'created' | 'dueAt'> & {
+    id?: string;
+}): string;