@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable

package/dist/sdk/sessions/compactionCheckpoint.js

@@ -2,7 +2,8 @@ import { renderCompactionCheckpoint } from "../prompt/compile.js";
 import { TODO_WRITE } from "../tools/todo.js";
 import { todoItemSchema, MAX_TODO_ITEMS } from "./contracts.js";
 export const COMPACTION_CHECKPOINT_EXTENSION = 'compaction-checkpoint';
-function validatedTodo(value) {
+/** A todo list as `todo_write` received it, validated; `null` when any item is unusable. */
+export function validatedTodo(value) {
     if (!Array.isArray(value) || value.length > MAX_TODO_ITEMS)
         return null;
     const items = [];

package/dist/sdk/sessions/completionCheck.d.ts

@@ -0,0 +1,49 @@
+export type CheckVerdictKind = 'done' | 'continue';
+export interface CheckVerdict {
+    verdict: CheckVerdictKind;
+    reason: string;
+    /** The next concrete step, for `continue`. */
+    next: string;
+}
+/** What the check sends; kept small so a check costs a fraction of a round. */
+export declare const MAX_CHECK_TRANSCRIPT = 24000;
+export declare const CHECK_TIMEOUT_MS = 60000;
+/** The fixed instructions of the check. Answering is all it does: it has no tools. */
+export declare const CHECK_SYSTEM_PROMPT = "You verify whether an AI coding agent has achieved a goal a person gave it. You do not do the work and you have no tools. You read the goal objective and a transcript of what the agent did and said, and you answer with one JSON object and nothing else:\n\n{\"verdict\":\"done\"|\"continue\",\"reason\":\"one or two sentences\",\"next\":\"the next concrete step, for continue\"}\n\nTreat completion as unproven. Derive the concrete requirements from the objective and from any file, plan or spec it points to that the transcript shows. For every explicit requirement, numbered item, named artifact, command, test, gate and deliverable, look in the transcript for evidence that it was achieved and checked: command output, test results, file contents the agent read or wrote. Evidence that is weak, indirect or missing counts as not achieved. The agent saying the goal is complete is not evidence. Match the scope of the check to the scope of the requirement: a narrow check does not support a broad claim.\n\nAnswer \"done\" only when every requirement has evidence in the transcript. Quote the key evidence in \"reason\". Answer \"continue\" when any requirement is unmet, unchecked or unclear; name the unmet requirements in \"reason\" and the next step in \"next\". If the transcript does not contain clear evidence that the objective is met, answer \"continue\" with the reason \"insufficient evidence in transcript\".\n\nJudge only from the objective and the transcript. Keep \"reason\" and \"next\" short and specific.";
+/**
+ * The reply's transcript: from the person's request onward, clipped to `limit` with the newest
+ * messages kept. The request is found as the last user message that contains its opening text;
+ * without it, the tail of the conversation stands in.
+ */
+export declare function replyTranscript(messages: readonly unknown[], request: string, limit?: number): string;
+/** The check's user message. */
+export declare function checkPrompt(objective: string, transcript: string): string;
+/** The verdict in the check's text, or `null` when there is none: the first JSON object that parses. */
+export declare function parseVerdict(text: string): CheckVerdict | null;
+/** A model answer as the check needs it: its text, and what it cost for the run's usage. */
+export interface CheckAnswer {
+    text: string;
+    /** The provider's message, passed to the usage recorder unchanged. */
+    message?: unknown;
+}
+/** Asks a model once. Implemented over Pi's model registry by the caller. */
+export type CheckModel = (system: string, user: string, signal: AbortSignal) => Promise<CheckAnswer>;
+/**
+ * Runs one check. Never throws: a timeout, an error or an answer without a verdict returns
+ * `{ verdict: null }`, and the claim is accepted as it stands.
+ */
+export declare function runCompletionCheck(ask: CheckModel, input: {
+    objective: string;
+    messages: readonly unknown[];
+}, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<{
+    verdict: CheckVerdict | null;
+    answer: CheckAnswer | null;
+    error?: string;
+}>;
+/** The text of a model's answer message. */
+export declare function answerText(message: unknown): string;
+/** `XINGULAR_STOP_GATE=off` / `XINGULAR_COMPLETION_CHECK=off` at launch switch a layer off, for experiments. The second one accepts every goal claim unchecked. */
+export declare function launchSwitchOff(name: 'XINGULAR_STOP_GATE' | 'XINGULAR_COMPLETION_CHECK'): boolean;

package/dist/sdk/sessions/completionCheck.js

@@ -0,0 +1,143 @@
+/** What the check sends; kept small so a check costs a fraction of a round. */
+export const MAX_CHECK_TRANSCRIPT = 24_000;
+const MAX_TOOL_RESULT = 600;
+const MAX_TOOL_ARGS = 300;
+const MAX_TEXT = 2_000;
+export const CHECK_TIMEOUT_MS = 60_000;
+/** The fixed instructions of the check. Answering is all it does: it has no tools. */
+export const CHECK_SYSTEM_PROMPT = `You verify whether an AI coding agent has achieved a goal a person gave it. You do not do the work and you have no tools. You read the goal objective and a transcript of what the agent did and said, and you answer with one JSON object and nothing else:
+
+{"verdict":"done"|"continue","reason":"one or two sentences","next":"the next concrete step, for continue"}
+
+Treat completion as unproven. Derive the concrete requirements from the objective and from any file, plan or spec it points to that the transcript shows. For every explicit requirement, numbered item, named artifact, command, test, gate and deliverable, look in the transcript for evidence that it was achieved and checked: command output, test results, file contents the agent read or wrote. Evidence that is weak, indirect or missing counts as not achieved. The agent saying the goal is complete is not evidence. Match the scope of the check to the scope of the requirement: a narrow check does not support a broad claim.
+
+Answer "done" only when every requirement has evidence in the transcript. Quote the key evidence in "reason". Answer "continue" when any requirement is unmet, unchecked or unclear; name the unmet requirements in "reason" and the next step in "next". If the transcript does not contain clear evidence that the objective is met, answer "continue" with the reason "insufficient evidence in transcript".
+
+Judge only from the objective and the transcript. Keep "reason" and "next" short and specific.`;
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit - 1)}…`);
+const textOf = (content) => {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.filter((part) => part?.type === 'text' && typeof part.text === 'string').map((part) => part.text).join('\n');
+};
+/** One message as the check reads it: visible text, tool calls and clipped tool results. Thinking is left out. */
+function renderMessage(message) {
+    if (message.role === 'user') {
+        const text = textOf(message.content);
+        // The goal's own continuation prompts repeat the same long audit text; the check needs only the objective.
+        if (text.startsWith('Continue working toward the active thread goal.'))
+            return '';
+        return `[User or harness]: ${clip(text, MAX_TEXT)}`;
+    }
+    if (message.role === 'toolResult')
+        return `[Tool result${message.toolName ? ` ${message.toolName}` : ''}${message.isError ? ', error' : ''}]: ${clip(textOf(message.content), MAX_TOOL_RESULT)}`;
+    if (message.role === 'assistant') {
+        const parts = Array.isArray(message.content) ? message.content : [];
+        const lines = [];
+        for (const part of parts) {
+            if (part?.type === 'text' && part.text)
+                lines.push(`[Agent]: ${clip(part.text, MAX_TEXT)}`);
+            else if (part?.type === 'toolCall')
+                lines.push(`[Agent tool call] ${part.name ?? 'tool'}(${clip(JSON.stringify(part.arguments ?? {}), MAX_TOOL_ARGS)})`);
+        }
+        return lines.join('\n');
+    }
+    return '';
+}
+/**
+ * The reply's transcript: from the person's request onward, clipped to `limit` with the newest
+ * messages kept. The request is found as the last user message that contains its opening text;
+ * without it, the tail of the conversation stands in.
+ */
+export function replyTranscript(messages, request, limit = MAX_CHECK_TRANSCRIPT) {
+    const list = messages;
+    const probe = request.trim().slice(0, 80);
+    let start = 0;
+    if (probe) {
+        for (let index = list.length - 1; index >= 0; index -= 1) {
+            if (list[index]?.role === 'user' && textOf(list[index].content).includes(probe)) {
+                start = index;
+                break;
+            }
+        }
+    }
+    const rendered = list.slice(start).map(renderMessage).filter(Boolean);
+    const kept = [];
+    let size = 0;
+    for (let index = rendered.length - 1; index >= 0; index -= 1) {
+        const line = rendered[index];
+        if (size + line.length + 1 > limit) {
+            kept.unshift('[…earlier messages of this reply omitted…]');
+            break;
+        }
+        kept.unshift(line);
+        size += line.length + 1;
+    }
+    return kept.join('\n');
+}
+/** The check's user message. */
+export function checkPrompt(objective, transcript) {
+    return [
+        `## The goal's objective\n${clip(objective.trim() || '(not recorded)', 4_000)}`,
+        `## What the agent did\n${transcript || '(nothing recorded)'}`,
+        '## Your answer\nOne JSON object: verdict, reason, next.'
+    ].join('\n\n');
+}
+/** The verdict in the check's text, or `null` when there is none: the first JSON object that parses. */
+export function parseVerdict(text) {
+    const starts = [];
+    for (let index = text.indexOf('{'); index >= 0; index = text.indexOf('{', index + 1))
+        starts.push(index);
+    for (const start of starts) {
+        for (let end = text.indexOf('}', start); end >= 0; end = text.indexOf('}', end + 1)) {
+            try {
+                const value = JSON.parse(text.slice(start, end + 1));
+                const verdict = value.verdict;
+                if (verdict !== 'done' && verdict !== 'continue')
+                    continue;
+                return {
+                    verdict,
+                    reason: clip(typeof value.reason === 'string' ? value.reason.trim() : '', 500),
+                    next: clip(typeof value.next === 'string' ? value.next.trim() : '', 500)
+                };
+            }
+            catch {
+                // Not a complete object yet; try a longer span.
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Runs one check. Never throws: a timeout, an error or an answer without a verdict returns
+ * `{ verdict: null }`, and the claim is accepted as it stands.
+ */
+export async function runCompletionCheck(ask, input, options = {}) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, options.timeoutMs ?? CHECK_TIMEOUT_MS);
+    try {
+        const user = checkPrompt(input.objective, replyTranscript(input.messages, ''));
+        const answer = await ask(CHECK_SYSTEM_PROMPT, user, controller.signal);
+        return { verdict: parseVerdict(answer.text), answer };
+    }
+    catch (error) {
+        return { verdict: null, answer: null, error: controller.signal.aborted ? 'the completion check timed out' : error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}
+/** The text of a model's answer message. */
+export function answerText(message) {
+    return textOf(message?.content);
+}
+/** `XINGULAR_STOP_GATE=off` / `XINGULAR_COMPLETION_CHECK=off` at launch switch a layer off, for experiments. The second one accepts every goal claim unchecked. */
+export function launchSwitchOff(name) {
+    const value = process.env[name]?.trim().toLowerCase();
+    return value === 'off' || value === '0' || value === 'false';
+}

package/dist/sdk/sessions/continuation.js

@@ -3,7 +3,7 @@
 // run with `continueFrom`, tells the model where the earlier one stopped.
 import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
 import { todoOf, describeTodo } from "../tools/todo.js";
-import { checkpointOf, describeCheckpoint } from "../tools/checkpoint.js";
+import { checkpointOf, describeCheckpoint } from "./checkpoint.js";
 import { isActiveStatus } from "./contracts.js";
 import { findHistory } from "./history.js";
 import { findRun, pendingDecisions, readEvents, recordedSubagents } from "./runStore.js";

package/dist/sdk/sessions/contracts.d.ts

@@ -310,6 +310,8 @@ export declare const runStopCodeSchema: z.ZodEnum<{
     user_abort: "user_abort";
     slice_budget: "slice_budget";
     compaction_thrash: "compaction_thrash";
+    needs_person: "needs_person";
+    unfinished: "unfinished";
     provider_error: "provider_error";
     stalled: "stalled";
     owner_gone: "owner_gone";
@@ -690,6 +692,8 @@ export declare const runEventPayloadSchemas: {
             user_abort: "user_abort";
             slice_budget: "slice_budget";
             compaction_thrash: "compaction_thrash";
+            needs_person: "needs_person";
+            unfinished: "unfinished";
             provider_error: "provider_error";
             stalled: "stalled";
             owner_gone: "owner_gone";
@@ -754,6 +758,44 @@ export type RunEvent = z.infer<typeof runEventSchema>;
  * the harness stores and returns them, and reads only `mode` (`chat` is an agent's own
  * conversation, `code` is a session in a project).
  */
+/** A run's /goal as the run record keeps it (ADR-0072). */
+export interface GoalModeRecord {
+    goalId: string;
+    objective: string;
+    status: 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
+    limits: {
+        rounds: number;
+        hours: number;
+    };
+    rounds: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+    claimed: boolean;
+    lastReason: string;
+}
+export declare const goalModeSchema: z.ZodObject<{
+    goalId: z.ZodString;
+    objective: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        active: "active";
+        paused: "paused";
+        usage_limited: "usage_limited";
+        budget_limited: "budget_limited";
+        complete: "complete";
+    }>;
+    limits: z.ZodObject<{
+        rounds: z.ZodNumber;
+        hours: z.ZodNumber;
+    }, z.core.$strip>;
+    rounds: z.ZodNumber;
+    timeUsedSeconds: z.ZodNumber;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    claimed: z.ZodBoolean;
+    lastReason: z.ZodString;
+}, z.core.$strip>;
 export interface RunRecord {
     resumedFromRunId: string | null;
     /** Opaque run lineage supplied by the embedding application. */
@@ -776,6 +818,8 @@ export interface RunRecord {
     workspaceRoot?: string | null;
     worktreeId: string | null;
     goal: string | null;
+    /** The run's /goal (ADR-0072): its objective, status, rounds and time. Absent for a run without one. */
+    goalMode?: GoalModeRecord | null;
     attachmentCount: number;
     startedAt: string;
     endedAt: string | null;
@@ -826,6 +870,8 @@ export declare const runRecordSchema: z.ZodObject<{
         user_abort: "user_abort";
         slice_budget: "slice_budget";
         compaction_thrash: "compaction_thrash";
+        needs_person: "needs_person";
+        unfinished: "unfinished";
         provider_error: "provider_error";
         stalled: "stalled";
         owner_gone: "owner_gone";
@@ -833,7 +879,7 @@ export declare const runRecordSchema: z.ZodObject<{
         terminal_attention: "terminal_attention";
         terminal_closed: "terminal_closed";
         parent_stopped: "parent_stopped";
-    }>>>, z.ZodTransform<"completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null, "completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null | undefined>>;
+    }>>>, z.ZodTransform<"completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "needs_person" | "unfinished" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null, "completed" | "failed" | "user_abort" | "slice_budget" | "compaction_thrash" | "needs_person" | "unfinished" | "provider_error" | "stalled" | "owner_gone" | "harness_restart" | "terminal_attention" | "terminal_closed" | "parent_stopped" | null | undefined>>;
     id: z.ZodString;
     projectId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     mode: z.ZodString;
@@ -849,6 +895,56 @@ export declare const runRecordSchema: z.ZodObject<{
     workspaceRoot: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>>;
     worktreeId: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
     goal: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    goalMode: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        goalId: z.ZodString;
+        objective: z.ZodString;
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            active: "active";
+            paused: "paused";
+            usage_limited: "usage_limited";
+            budget_limited: "budget_limited";
+            complete: "complete";
+        }>;
+        limits: z.ZodObject<{
+            rounds: z.ZodNumber;
+            hours: z.ZodNumber;
+        }, z.core.$strip>;
+        rounds: z.ZodNumber;
+        timeUsedSeconds: z.ZodNumber;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        claimed: z.ZodBoolean;
+        lastReason: z.ZodString;
+    }, z.core.$strip>>>, z.ZodTransform<{
+        goalId: string;
+        objective: string;
+        status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
+        limits: {
+            rounds: number;
+            hours: number;
+        };
+        rounds: number;
+        timeUsedSeconds: number;
+        createdAt: number;
+        updatedAt: number;
+        claimed: boolean;
+        lastReason: string;
+    } | null, {
+        goalId: string;
+        objective: string;
+        status: "blocked" | "active" | "paused" | "usage_limited" | "budget_limited" | "complete";
+        limits: {
+            rounds: number;
+            hours: number;
+        };
+        rounds: number;
+        timeUsedSeconds: number;
+        createdAt: number;
+        updatedAt: number;
+        claimed: boolean;
+        lastReason: string;
+    } | null | undefined>>>;
     attachmentCount: z.ZodDefault<z.ZodNumber>;
     startedAt: z.ZodString;
     endedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;

package/dist/sdk/sessions/contracts.js

@@ -382,6 +382,10 @@ export const runStopCodeSchema = z.enum([
     'slice_budget',
     /** Three compactions in one reply ended it. */
     'compaction_thrash',
+    /** The completion check found that the work left needs the person (ADR-0071). */
+    'needs_person',
+    /** The reply ended with work left after the stop gate's nudges ran out or produced no work (ADR-0069, ADR-0071). */
+    'unfinished',
     /** The model request failed (auth, quota, rate limit, network, unsupported model). */
     'provider_error',
     /** The run stopped reporting progress or heartbeats. */
@@ -461,6 +465,18 @@ export const runEventSchema = z
         context.addIssue({ code: 'custom', path: ['payload'], message: `Invalid payload for ${event.type}` });
     }
 });
+export const goalModeSchema = z.object({
+    goalId: z.string(),
+    objective: z.string(),
+    status: z.enum(['active', 'paused', 'blocked', 'usage_limited', 'budget_limited', 'complete']),
+    limits: z.object({ rounds: z.number().int().positive(), hours: z.number().positive() }),
+    rounds: z.number().int().nonnegative(),
+    timeUsedSeconds: z.number().nonnegative(),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    claimed: z.boolean(),
+    lastReason: z.string()
+});
 const text = z.string().nullish().transform((value) => value ?? null);
 export const runRecordSchema = z.object({
     resumedFromRunId: text,
@@ -480,6 +496,7 @@ export const runRecordSchema = z.object({
     workspaceRoot: text.optional(),
     worktreeId: text,
     goal: text,
+    goalMode: goalModeSchema.nullish().transform((value) => value ?? null).optional(),
     attachmentCount: z.number().int().nonnegative().default(0),
     startedAt: z.string(),
     endedAt: text,

package/dist/sdk/sessions/goal.d.ts

@@ -0,0 +1,145 @@
+import type { ToolSpec } from "../tools/types.js";
+export declare const GET_GOAL = "get_goal";
+export declare const UPDATE_GOAL = "update_goal";
+export declare const GOAL_TOOLS: readonly ["get_goal", "update_goal"];
+export declare const GOAL_CUSTOM_TYPE = "xingular-goal";
+export declare const GOAL_STATE_ENTRY = "xingular-goal-state";
+/** Codex limits a goal objective to this many characters. */
+export declare const MAX_GOAL_OBJECTIVE = 4000;
+export declare const DEFAULT_GOAL_ROUNDS = 30;
+export declare const DEFAULT_GOAL_HOURS = 8;
+/** Consecutive automatic rounds without activity, or with only failed commands, before a goal is blocked. */
+export declare const GOAL_STRIKES = 3;
+export type GoalStatus = 'active' | 'paused' | 'blocked' | 'usage_limited' | 'budget_limited' | 'complete';
+export interface GoalLimits {
+    rounds: number;
+    hours: number;
+}
+export interface GoalState {
+    /** Changes when a goal is replaced, kept when its objective is edited. */
+    goalId: string;
+    objective: string;
+    status: GoalStatus;
+    limits: GoalLimits;
+    /** Automatic continuations started so far. */
+    rounds: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+    /** The model called update_goal(complete) and the harness has not checked the claim yet. */
+    claimed: boolean;
+    /** The latest verdict on a completion claim, while it matters. */
+    lastReason: string;
+}
+/** Thrown for a call the model may not make; the message goes back to the model as the tool result. */
+export declare class GoalError extends Error {
+}
+export declare const withLimits: (limits?: Partial<GoalLimits>) => GoalLimits;
+/** `59s`, `1m`, `1h 30m`, `2d 23h 42m`: Codex's elapsed-time format. */
+export declare function formatElapsed(seconds: number): string;
+export declare const continuationPrompt: (goal: GoalState) => string;
+export declare const budgetLimitPrompt: (goal: GoalState) => string;
+export declare const objectiveUpdatedPrompt: (goal: GoalState) => string;
+/** The goal as the model's tools report it. */
+export declare function goalReport(goal: GoalState | null): Record<string, unknown>;
+/** The text a goal-aware session shows after it ends in `complete`. */
+export declare const completionReport: (goal: GoalState) => string;
+/** What one finished round did, as the loop saw it. */
+export interface RoundOutcome {
+    /** The round produced text, reasoning, or a tool call. */
+    activity: boolean;
+    /** A command failed and no tool succeeded in the round. */
+    failedCommands: boolean;
+    /** The round ended with a provider error (not a usage limit). */
+    error?: boolean;
+    /** The round ended with a usage-limit error. */
+    usageLimit?: boolean;
+}
+export interface GoalControllerOptions {
+    now?: () => number;
+    /** Called after every change with the new state (null once cleared), to persist and show it. */
+    onChange?: (state: GoalState | null) => void;
+}
+/**
+ * One session's goal. All changes go through it, so the status rules live in one place:
+ * the model may only claim `complete`, report `blocked` or, on the person's word, `paused`;
+ * the person sets, edits, pauses, resumes and clears; the system alone limits.
+ */
+export declare class GoalController {
+    private readonly options;
+    private state;
+    private idleStrikes;
+    private failureStrikes;
+    private startedAt;
+    private readonly now;
+    private readonly listeners;
+    constructor(options?: GoalControllerOptions);
+    get(): GoalState | null;
+    active(): boolean;
+    /** Restores a persisted goal; the in-memory strike counters start fresh. */
+    restore(state: GoalState | null): void;
+    /** Hears every change (a persisted copy, the footer, the model's tools). Returns the way to stop. */
+    subscribe(listener: (state: GoalState | null) => void): () => void;
+    private changed;
+    private touch;
+    /** The person sets a goal. Replaces a finished one; the caller confirms replacing an unfinished one. */
+    set(objective: string, limits?: Partial<GoalLimits>): GoalState;
+    /** The person edits the objective: the same goal, its usage kept. A finished goal becomes active again. */
+    edit(objective: string): GoalState;
+    pause(): GoalState | null;
+    resume(): GoalState;
+    clear(): boolean;
+    /** A round (a turn charged to the goal) begins. */
+    beginRound(): void;
+    /** Charges the round's wall time to the goal. Called at every stop, so an idle gap is not billed. */
+    endRound(): void;
+    /** The model's `update_goal`. Returns the tool result. */
+    update(status: string): {
+        text: string;
+        goal: GoalState;
+    };
+    /** The claim was checked and holds. */
+    accept(reason?: string): GoalState;
+    /** The claim was checked and does not hold: the goal stays active with the reason. */
+    reject(reason: string): GoalState;
+    /** The system limits the goal. */
+    limit(status: 'budget_limited' | 'usage_limited' | 'blocked', reason?: string): GoalState;
+    /** Counts one automatic round; returns the status the system moved the goal to, if any. */
+    settleRound(outcome: RoundOutcome): GoalStatus | null;
+    /** True once the goal has used its rounds or hours. */
+    overLimit(): boolean;
+    /** Starts the next automatic round. */
+    nextRound(): GoalState;
+}
+export declare function goalTools(goal: () => GoalController | null): ToolSpec[];
+export type GoalCommand = {
+    kind: 'show';
+} | {
+    kind: 'set';
+    objective: string;
+    limits: Partial<GoalLimits>;
+} | {
+    kind: 'edit';
+    objective: string | null;
+} | {
+    kind: 'pause';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'clear';
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare const GOAL_USAGE = "Usage: /goal [<objective>|edit|pause|resume|clear]";
+/**
+ * Parses the argument of `/goal`. Subcommands match only as the whole text, so "pause now" is
+ * an objective. `--rounds N` and `--hours H` before the objective set this goal's caps.
+ */
+export declare function parseGoalCommand(argument: string): GoalCommand;
+/** The text of a bare `/goal`. */
+export declare function goalSummary(goal: GoalState | null): string;
+/** The footer label (Codex's wording, with rounds in place of tokens). */
+export declare function goalFooter(goal: GoalState | null): string | null;
+/** The hidden message that records who changed the goal, so a pause can be checked as the person's. */
+export declare function provenanceText(action: 'set' | 'paused' | 'cleared' | 'resumed' | 'edited', goal: GoalState | null): string;