@pinet/agent-goal 0.2.10 → 0.2.12

package/README.md

@@ -21,6 +21,7 @@ pi -e ./agent-goal/index.ts
 ```text
 /goal <objective>  Create and immediately start a goal
 /goal              Open the minimal goal window (text in headless modes)
+/goal budget turns=<n> [tokens=<n>]  Change total turn/token ceilings
 /goal pause        Pause automatic evaluation and continuation
 /goal resume       Resume and immediately continue
 /goal complete     Mark complete manually
@@ -29,13 +30,14 @@ pi -e ./agent-goal/index.ts
 /goal show         Show the compact persistent goal status
 ```
 
-Pi's footer is the only persistent goal UI and shows compact status and budget usage without duplicating the detailed dashboard. In interactive mode, `/goal` opens the detailed control window with the objective, lifecycle state, budget bars, latest evaluator guidance, and continuation state. Its visible keyboard actions pause or resume the goal, mark it complete, clear it, or close the window; complete and clear require a second keypress, and the window refreshes after state changes. Press Escape, `q`, or Ctrl+C to close it. `/goal` retains the detailed textual dashboard in headless sessions.
+Pi's footer is the only persistent goal UI and shows compact status and budget usage without duplicating the detailed dashboard. In interactive mode, `/goal` opens the detailed control window with the objective, lifecycle state, budget bars, latest evaluator guidance, and continuation state. Press `b` to edit total turn and token ceilings in place; digits edit the selected field, Tab switches fields, Enter saves, and Escape cancels. Other visible keyboard actions pause or resume the goal, mark it complete, clear it, or close the window; complete and clear require a second keypress, and validation errors remain visible in the open window. Press Escape, `q`, or Ctrl+C to close it. `/goal` retains the detailed textual dashboard in headless sessions.
 
 Only one goal may exist per Pi session. Clear the existing goal before creating another.
 
-The agent also receives three model-visible tools:
+The agent also receives four model-visible tools:
 
 - `create_goal` — create its own bounded, user-aligned durable goal
+- `update_goal_budget` — change the current goal's total turn or token ceiling
 - `get_goal` — inspect the current objective, status, and budget
 - `update_goal` — optionally attach a `complete` or `blocked` hint for independent verification
 
@@ -51,7 +53,9 @@ PI_AGENT_GOAL_MAX_TOKENS=200000
 PI_AGENT_GOAL_MAX_RUNTIME_MS=14400000
 ```
 
-Iteration and runtime limits are always reliable. Token accounting uses usage reported by Pi providers. The evaluator reviews every settled run, including the final allowed turn, so a completed goal is not incorrectly classified as budget-limited; only another continuation is prevented. The former `PI_AGENT_GOAL_EVALUATION_INTERVAL` setting is accepted for configuration compatibility but no longer changes evaluation frequency.
+Iteration and runtime limits are always reliable. Token accounting uses usage reported by Pi providers. Operators and the goal-bearing agent may update total turn and token ceilings without recreating the goal. Changes are optimistic and atomic, cannot reduce a ceiling below accounted usage, must reserve capacity for a currently active turn, and cannot exceed a configured default ceiling when one exists. Increasing an exhausted budget reactivates the same goal when capacity is available; no budget change alters the objective or erases usage.
+
+The evaluator reviews every settled run, including the final allowed turn, so a completed goal is not incorrectly classified as budget-limited; only another continuation is prevented. The former `PI_AGENT_GOAL_EVALUATION_INTERVAL` setting is accepted for configuration compatibility but no longer changes evaluation frequency.
 
 ## Persistence and recovery
 
@@ -114,7 +118,7 @@ A future Pinet integration can use broker storage and evaluation plus RALPH reco
 
 ## Automatic evaluation
 
-The extension registers model-visible `create_goal`, `get_goal`, and `update_goal` tools. The worker can establish its own user-aligned goal and inspect it. `update_goal` is optional: it records a terminal hint rather than mutating goal state directly. Every `agent_settled` event accounts the run and invokes the independent evaluator whether or not the worker supplied that hint.
+The extension registers model-visible `create_goal`, `update_goal_budget`, `get_goal`, and `update_goal` tools. The worker can establish its own user-aligned goal, inspect it, and adjust its bounded capacity. `update_goal` is optional: it records a terminal hint rather than mutating goal state directly. Every `agent_settled` event accounts the run and invokes the independent evaluator whether or not the worker supplied that hint.
 
 The evaluator returns one of:
 

package/dist/dashboard.js

@@ -37,6 +37,6 @@ export function formatGoalDashboard(goal, claim) {
         lines.push(`Reason: ${displayGoalText(goal.blockedReason, 100)}`);
     if (claim)
         lines.push(`Continuation: ${claim.state} · attempt ${claim.attempt}`);
-    lines.push("/goal pause · resume · complete · clear · hide");
+    lines.push("/goal budget turns=<n> tokens=<n> · pause · resume · complete · clear · hide");
     return lines;
 }

package/dist/domain.d.ts

@@ -8,6 +8,10 @@ export interface GoalUsage {
     iterations: number;
     tokens: number;
 }
+export interface GoalBudgetUpdate {
+    maxIterations?: number;
+    maxTokens?: number;
+}
 export interface GoalEvaluationRecord {
     id: string;
     outcome: GoalEvaluation["outcome"];
@@ -86,6 +90,7 @@ export interface GoalStorage {
     get(scopeId: string): Promise<AgentGoal | undefined>;
     create(goal: AgentGoal): Promise<void>;
     replace(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
+    updateBudget(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
     delete(scopeId: string, expectedVersion: number): Promise<boolean>;
     getPendingEvaluation(scopeId: string): Promise<GoalPendingEvaluation | undefined>;
     appendPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;
@@ -143,6 +148,10 @@ export type GoalEvent = {
     type: "goal.progress_accounted";
     goal: AgentGoal;
     tokenDelta: number;
+} | {
+    type: "goal.budget_changed";
+    goal: AgentGoal;
+    previousBudget: GoalBudget;
 } | {
     type: "goal.evaluated";
     goal: AgentGoal;

package/dist/goal-window.d.ts

@@ -1,7 +1,12 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component } from "@earendil-works/pi-tui";
 import type { AgentGoal, GoalContinuationClaim } from "./domain.js";
-export type GoalWindowAction = "pause" | "resume" | "complete" | "clear" | "close";
+export type GoalWindowLifecycleAction = "pause" | "resume" | "complete" | "clear" | "close";
+export type GoalWindowAction = GoalWindowLifecycleAction | {
+    type: "budget";
+    maxIterations: number;
+    maxTokens?: number;
+};
 export declare class GoalWindow implements Component {
     private readonly goal;
     private readonly claim;
@@ -9,8 +14,14 @@ export declare class GoalWindow implements Component {
     private readonly onAction;
     private readonly requestRender;
     private readonly now;
+    private readonly actionError?;
     private pendingConfirmation;
-    constructor(goal: AgentGoal | undefined, claim: GoalContinuationClaim | undefined, theme: Theme, onAction: (action: GoalWindowAction) => void, requestRender?: () => void, now?: () => number);
+    private budgetField;
+    private budgetTurns;
+    private budgetTokens;
+    private replaceBudgetValue;
+    private budgetInputError;
+    constructor(goal: AgentGoal | undefined, claim: GoalContinuationClaim | undefined, theme: Theme, onAction: (action: GoalWindowAction) => void, requestRender?: () => void, now?: () => number, actionError?: string | undefined);
     handleInput(data: string): void;
     render(width: number): string[];
     invalidate(): void;

package/dist/goal-window.js

@@ -20,14 +20,21 @@ export class GoalWindow {
     onAction;
     requestRender;
     now;
+    actionError;
     pendingConfirmation;
-    constructor(goal, claim, theme, onAction, requestRender = () => undefined, now = Date.now) {
+    budgetField;
+    budgetTurns = "";
+    budgetTokens = "";
+    replaceBudgetValue = false;
+    budgetInputError;
+    constructor(goal, claim, theme, onAction, requestRender = () => undefined, now = Date.now, actionError) {
         this.goal = goal;
         this.claim = claim;
         this.theme = theme;
         this.onAction = onAction;
         this.requestRender = requestRender;
         this.now = now;
+        this.actionError = actionError;
     }
     handleInput(data) {
         const key = data.toLowerCase();
@@ -40,6 +47,11 @@ export class GoalWindow {
                 this.pendingConfirmation = undefined;
                 this.requestRender();
             }
+            else if (this.budgetField) {
+                this.budgetField = undefined;
+                this.budgetInputError = undefined;
+                this.requestRender();
+            }
             else {
                 this.onAction("close");
             }
@@ -47,6 +59,49 @@ export class GoalWindow {
         }
         if (!this.goal)
             return;
+        if (this.budgetField) {
+            if (matchesKey(data, "tab") || matchesKey(data, "up") || matchesKey(data, "down")) {
+                this.budgetField = this.budgetField === "turns" ? "tokens" : "turns";
+                this.replaceBudgetValue = true;
+                this.budgetInputError = undefined;
+            }
+            else if (matchesKey(data, "backspace")) {
+                const value = this.budgetField === "turns" ? this.budgetTurns : this.budgetTokens;
+                if (this.budgetField === "turns")
+                    this.budgetTurns = value.slice(0, -1);
+                else
+                    this.budgetTokens = value.slice(0, -1);
+                this.replaceBudgetValue = false;
+                this.budgetInputError = undefined;
+            }
+            else if (matchesKey(data, "enter")) {
+                const maxIterations = Number(this.budgetTurns);
+                if (!Number.isInteger(maxIterations) || maxIterations <= 0) {
+                    this.budgetInputError = "Turns must be a positive integer";
+                }
+                else {
+                    const maxTokens = this.budgetTokens ? Number(this.budgetTokens) : undefined;
+                    this.onAction({ type: "budget", maxIterations, maxTokens });
+                    return;
+                }
+            }
+            else if (/^\d+$/.test(data)) {
+                const value = this.replaceBudgetValue
+                    ? data
+                    : `${this.budgetField === "turns" ? this.budgetTurns : this.budgetTokens}${data}`;
+                if (this.budgetField === "turns")
+                    this.budgetTurns = value;
+                else
+                    this.budgetTokens = value;
+                this.replaceBudgetValue = false;
+                this.budgetInputError = undefined;
+            }
+            else {
+                return;
+            }
+            this.requestRender();
+            return;
+        }
         if (this.pendingConfirmation) {
             const confirmationKey = this.pendingConfirmation === "complete" ? "c" : "x";
             if (key === confirmationKey) {
@@ -58,7 +113,16 @@ export class GoalWindow {
             }
             return;
         }
-        if (key === "p" && this.goal.status === "active") {
+        if (key === "b" && this.goal.status !== "complete") {
+            this.budgetField = "turns";
+            this.budgetTurns = String(this.goal.budget.maxIterations);
+            this.budgetTokens =
+                this.goal.budget.maxTokens === undefined ? "" : String(this.goal.budget.maxTokens);
+            this.replaceBudgetValue = true;
+            this.budgetInputError = undefined;
+            this.requestRender();
+        }
+        else if (key === "p" && this.goal.status === "active") {
             this.onAction("pause");
         }
         else if (key === "r" && (this.goal.status === "paused" || this.goal.status === "blocked")) {
@@ -132,16 +196,27 @@ export class GoalWindow {
         if (this.claim) {
             lines.push(row(` ${this.theme.fg("muted", "Continuation")} ${this.claim.state} · attempt ${this.claim.attempt}`));
         }
+        if (this.budgetField) {
+            const turns = `${this.budgetField === "turns" ? "›" : " "} Turns  ${this.budgetTurns || "_"}`;
+            const tokens = `${this.budgetField === "tokens" ? "›" : " "} Tokens ${this.budgetTokens || "unchanged"}`;
+            lines.push(row(), row(` ${this.theme.fg("accent", "Edit budget")}`), row(` ${turns}`), row(` ${tokens}`));
+        }
+        const error = this.budgetInputError ?? this.actionError;
+        if (error)
+            lines.push(row(` ${this.theme.fg("error", displayGoalText(error, contentWidth))}`));
         const actions = [
             this.goal.status === "active" ? "p pause" : undefined,
             this.goal.status === "paused" || this.goal.status === "blocked" ? "r resume" : undefined,
+            this.goal.status !== "complete" ? "b budget" : undefined,
             this.goal.status !== "complete" ? "c complete" : undefined,
             "x clear",
             "q close",
         ].filter((action) => action !== undefined);
         const footer = this.pendingConfirmation
             ? `${this.pendingConfirmation === "complete" ? "c" : "x"} again to confirm ${this.pendingConfirmation} · esc cancel`
-            : actions.join(" · ");
+            : this.budgetField
+                ? "digits edit · tab field · enter save · esc cancel"
+                : actions.join(" · ");
         lines.push(row(), row(` ${this.theme.fg("dim", footer)}`));
         lines.push(border(`╰${"─".repeat(innerWidth)}╯`));
         return lines;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { GoalBudget, GoalContinuation, GoalEvaluator, GoalEventSink, GoalRetryPolicy, GoalStorage, GoalWakeScheduler } from "./domain.js";
 export type { AgentGoal, GoalBudget, GoalContinuation, GoalContinuationClaim, GoalContinuationRequest, GoalContinuationResult, GoalEvaluation, GoalEvaluationRecord, GoalEvaluator, GoalEvent, GoalEventSink, GoalPendingEvaluation, GoalProgress, GoalRetryPolicy, GoalStatus, GoalStorage, GoalTerminalCandidate, GoalTerminalCandidateRecord, GoalUsage, GoalWakeScheduler, } from "./domain.js";
 export { displayGoalText, formatGoalDashboard, formatGoalStatus } from "./dashboard.js";
-export { GoalWindow, type GoalWindowAction } from "./goal-window.js";
+export { GoalWindow, type GoalWindowAction, type GoalWindowLifecycleAction, } from "./goal-window.js";
 export { MemoryGoalStorage } from "./memory-storage.js";
 export { parseGoalEvaluation, PiGoalEvaluator } from "./pi-evaluator.js";
 export { countGoalProgressTokens, formatGoalProgress, type GoalProgressMessage, } from "./progress.js";

package/dist/index.js

@@ -1,13 +1,13 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { formatGoalDashboard, formatGoalStatus } from "./dashboard.js";
-import { GoalWindow } from "./goal-window.js";
+import { GoalWindow, } from "./goal-window.js";
 import { PiGoalEvaluator } from "./pi-evaluator.js";
 import { countGoalProgressTokens, formatGoalProgress, } from "./progress.js";
 import { GoalRuntime } from "./runtime.js";
 import { SqliteGoalStorage } from "./sqlite-storage.js";
 export { displayGoalText, formatGoalDashboard, formatGoalStatus } from "./dashboard.js";
-export { GoalWindow } from "./goal-window.js";
+export { GoalWindow, } from "./goal-window.js";
 export { MemoryGoalStorage } from "./memory-storage.js";
 export { parseGoalEvaluation, PiGoalEvaluator } from "./pi-evaluator.js";
 export { countGoalProgressTokens, formatGoalProgress, } from "./progress.js";
@@ -44,7 +44,7 @@ export function registerAgentGoal(pi, options = {}) {
                 if (!ctx || ctx.sessionManager.getSessionId() !== goal.scopeId) {
                     return { status: "unavailable", reason: "The goal session is not active" };
                 }
-                if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+                if (!ctx.isIdle()) {
                     return { status: "busy", reason: "The goal session is busy", retryAfterMs: 1_000 };
                 }
                 api.sendMessage({
@@ -78,6 +78,13 @@ export function registerAgentGoal(pi, options = {}) {
         ctx.ui.setWidget(WIDGET_KEY, undefined);
     };
     const applyGoalAction = async (scopeId, action) => {
+        if (typeof action === "object") {
+            await runtime.updateBudget(scopeId, {
+                maxIterations: action.maxIterations,
+                maxTokens: action.maxTokens,
+            });
+            return;
+        }
         switch (action) {
             case "pause":
                 await runtime.setStatus(scopeId, "paused");
@@ -208,6 +215,53 @@ export function registerAgentGoal(pi, options = {}) {
             };
         },
     });
+    pi.registerTool({
+        name: "update_goal_budget",
+        label: "Update goal budget",
+        description: "Adjust this session goal's bounded turn or token ceiling without replacing the goal. Changes remain constrained by configured limits and cannot discard accounted usage.",
+        promptSnippet: "Adjust the active session goal's bounded turn or token budget.",
+        promptGuidelines: [
+            "Only change a goal budget when more or less capacity is genuinely needed for the existing user-aligned objective.",
+            "Never use budget changes to broaden the objective or evade configured hard limits.",
+            "Inspect the current goal first and keep requested capacity proportionate to the remaining work.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                maxTurns: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: defaultBudget.maxIterations,
+                    description: "New total settled-turn ceiling, including turns already accounted.",
+                },
+                maxTokens: {
+                    type: "number",
+                    exclusiveMinimum: 0,
+                    ...(defaultBudget.maxTokens === undefined ? {} : { maximum: defaultBudget.maxTokens }),
+                    description: "New total token ceiling, including tokens already accounted.",
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, rawParams, _signal, _onUpdate, rawCtx) {
+            const params = rawParams;
+            const ctx = rawCtx;
+            const goal = await runtime.updateBudget(ctx.sessionManager.getSessionId(), {
+                maxIterations: params.maxTurns,
+                maxTokens: params.maxTokens,
+            });
+            await refreshUi(ctx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Updated goal budget to ${goal.budget.maxIterations} turns${goal.budget.maxTokens === undefined ? "" : ` and ${goal.budget.maxTokens} tokens`}.`,
+                    },
+                ],
+                details: { goal },
+            };
+        },
+    });
     pi.registerTool({
         name: "get_goal",
         label: "Get goal",
@@ -283,7 +337,7 @@ export function registerAgentGoal(pi, options = {}) {
         },
     });
     pi.registerCommand("goal", {
-        description: "Create, inspect, pause, resume, complete, clear, show, or hide this session's goal",
+        description: "Create, inspect, adjust budget, pause, resume, complete, clear, show, or hide this session's goal",
         handler: async (args, rawCtx) => {
             const ctx = rawCtx;
             activeContext = ctx;
@@ -292,12 +346,13 @@ export function registerAgentGoal(pi, options = {}) {
             try {
                 if (!input) {
                     let openedWindow = false;
+                    let actionError;
                     while (true) {
                         const goal = await runtime.get(scopeId);
                         const claim = await runtime.getContinuationClaim(scopeId);
                         const action = await ctx.ui.custom((tui, theme, _keybindings, done) => {
                             openedWindow = true;
-                            return new GoalWindow(goal, claim, theme, done, () => tui.requestRender());
+                            return new GoalWindow(goal, claim, theme, done, () => tui.requestRender(), Date.now, actionError);
                         }, {
                             overlay: true,
                             overlayOptions: {
@@ -320,11 +375,42 @@ export function registerAgentGoal(pi, options = {}) {
                         }
                         if (!action || action === "close")
                             return;
-                        await applyGoalAction(scopeId, action);
-                        await refreshUi(ctx);
+                        try {
+                            await applyGoalAction(scopeId, action);
+                            actionError = undefined;
+                            await refreshUi(ctx);
+                        }
+                        catch (error) {
+                            actionError = error instanceof Error ? error.message : String(error);
+                        }
                     }
                 }
                 const command = input.toLowerCase();
+                if (command === "budget" || command.startsWith("budget ")) {
+                    const update = {};
+                    for (const token of input.slice("budget".length).trim().split(/\s+/).filter(Boolean)) {
+                        const separator = token.indexOf("=");
+                        if (separator < 1)
+                            throw new Error(`Invalid goal budget argument: ${token}`);
+                        const key = token.slice(0, separator).toLowerCase();
+                        const value = Number(token.slice(separator + 1));
+                        if (key === "turns" || key === "maxturns" || key === "iterations") {
+                            update.maxIterations = value;
+                        }
+                        else if (key === "tokens" || key === "maxtokens") {
+                            update.maxTokens = value;
+                        }
+                        else {
+                            throw new Error(`Unknown goal budget field: ${key}`);
+                        }
+                    }
+                    const goal = await runtime.updateBudget(scopeId, update);
+                    await refreshUi(ctx);
+                    if (ctx.hasUI) {
+                        ctx.ui.notify(`Goal budget: ${goal.budget.maxIterations} turns${goal.budget.maxTokens === undefined ? "" : ` · ${goal.budget.maxTokens} tokens`}`, "info");
+                    }
+                    return;
+                }
                 switch (command) {
                     case "pause":
                     case "resume":

package/dist/memory-storage.d.ts

@@ -7,6 +7,7 @@ export declare class MemoryGoalStorage implements GoalStorage {
     get(scopeId: string): Promise<AgentGoal | undefined>;
     create(goal: AgentGoal): Promise<void>;
     replace(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
+    updateBudget(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
     delete(scopeId: string, expectedVersion: number): Promise<boolean>;
     getPendingEvaluation(scopeId: string): Promise<GoalPendingEvaluation | undefined>;
     appendPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;

package/dist/memory-storage.js

@@ -27,6 +27,25 @@ export class MemoryGoalStorage {
         this.goals.set(goal.scopeId, cloneGoal(goal));
         return true;
     }
+    async updateBudget(goal, expectedVersion) {
+        const current = this.goals.get(goal.scopeId);
+        if (!current || current.version !== expectedVersion || current.id !== goal.id)
+            return false;
+        this.goals.set(goal.scopeId, cloneGoal(goal));
+        const pending = this.pendingEvaluations.get(goal.scopeId);
+        if (pending?.goalId === goal.id && pending.goalVersion === expectedVersion) {
+            this.pendingEvaluations.set(goal.scopeId, { ...pending, goalVersion: goal.version });
+        }
+        const candidate = this.terminalCandidates.get(goal.scopeId);
+        if (candidate?.goalId === goal.id && candidate.goalVersion === expectedVersion) {
+            this.terminalCandidates.set(goal.scopeId, { ...candidate, goalVersion: goal.version });
+        }
+        const claim = this.claims.get(goal.scopeId);
+        if (claim?.goalId === goal.id && claim.goalVersion === expectedVersion) {
+            this.claims.set(goal.scopeId, { ...claim, goalVersion: goal.version });
+        }
+        return true;
+    }
     async delete(scopeId, expectedVersion) {
         const current = this.goals.get(scopeId);
         if (!current || current.version !== expectedVersion)
@@ -52,14 +71,13 @@ export class MemoryGoalStorage {
     }
     async appendPendingEvaluation(pending) {
         const goal = this.goals.get(pending.scopeId);
-        if (!goal || goal.id !== pending.goalId || goal.version !== pending.goalVersion)
+        if (!goal || goal.id !== pending.goalId || goal.status !== "active")
             return false;
         const stored = this.pendingEvaluations.get(pending.scopeId);
-        const existing = stored?.goalId === pending.goalId && stored.goalVersion === pending.goalVersion
-            ? stored
-            : undefined;
+        const existing = stored?.goalId === pending.goalId && stored.goalVersion === goal.version ? stored : undefined;
         this.pendingEvaluations.set(pending.scopeId, {
             ...pending,
+            goalVersion: goal.version,
             iterationsDelta: pending.iterationsDelta + (existing?.iterationsDelta ?? 0),
             progress: {
                 ...pending.progress,
@@ -149,9 +167,16 @@ export class MemoryGoalStorage {
     }
     async replaceContinuationClaim(claim, expectedClaimId) {
         const current = this.claims.get(claim.scopeId);
-        if (!current || current.claimId !== expectedClaimId)
+        const goal = this.goals.get(claim.scopeId);
+        if (!current ||
+            current.claimId !== expectedClaimId ||
+            current.goalId !== claim.goalId ||
+            !goal ||
+            goal.id !== claim.goalId ||
+            goal.status !== "active") {
             return false;
-        this.claims.set(claim.scopeId, { ...claim });
+        }
+        this.claims.set(claim.scopeId, { ...claim, goalVersion: goal.version });
         return true;
     }
     async deleteContinuationClaim(scopeId, expectedClaimId) {

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { AgentGoal, GoalBudget, GoalContinuation, GoalContinuationClaim, GoalEvaluator, GoalEventSink, GoalProgress, GoalRetryPolicy, GoalStatus, GoalStorage, GoalTerminalCandidate, GoalTerminalCandidateRecord, GoalWakeScheduler } from "./domain.js";
+import type { AgentGoal, GoalBudget, GoalBudgetUpdate, GoalContinuation, GoalContinuationClaim, GoalEvaluator, GoalEventSink, GoalProgress, GoalRetryPolicy, GoalStatus, GoalStorage, GoalTerminalCandidate, GoalTerminalCandidateRecord, GoalWakeScheduler } from "./domain.js";
 export interface GoalRuntimeOptions {
     defaultBudget?: GoalBudget;
     retryPolicy?: GoalRetryPolicy;
@@ -29,6 +29,7 @@ export declare class GoalRuntime {
     getContinuationClaim(scopeId: string): Promise<GoalContinuationClaim | undefined>;
     getTerminalCandidate(scopeId: string): Promise<GoalTerminalCandidateRecord | undefined>;
     create(scopeId: string, objective: string, budget?: GoalBudget): Promise<AgentGoal>;
+    updateBudget(scopeId: string, update: GoalBudgetUpdate): Promise<AgentGoal>;
     setStatus(scopeId: string, status: Extract<GoalStatus, "active" | "paused" | "complete">): Promise<AgentGoal>;
     clear(scopeId: string): Promise<boolean>;
     requestTerminalCandidate(scopeId: string, candidate: GoalTerminalCandidate): Promise<GoalTerminalCandidateRecord>;

package/dist/runtime.js

@@ -88,6 +88,65 @@ export class GoalRuntime {
         await this.record({ type: "goal.created", goal });
         return goal;
     }
+    async updateBudget(scopeId, update) {
+        const current = await this.requireGoal(scopeId);
+        if (current.status === "complete")
+            throw new Error("Cannot change a complete goal budget");
+        if (update.maxIterations === undefined && update.maxTokens === undefined) {
+            throw new Error("A goal budget update requires maxIterations or maxTokens");
+        }
+        if (update.maxIterations !== undefined &&
+            (!Number.isInteger(update.maxIterations) || update.maxIterations <= 0)) {
+            throw new Error("Goal maxIterations must be a positive integer");
+        }
+        if (update.maxTokens !== undefined &&
+            (!Number.isFinite(update.maxTokens) || update.maxTokens <= 0)) {
+            throw new Error("Goal maxTokens must be a positive finite number");
+        }
+        if (update.maxIterations !== undefined && update.maxIterations > this.budget.maxIterations) {
+            throw new Error(`Goal maxIterations cannot exceed the configured limit of ${this.budget.maxIterations}`);
+        }
+        if (update.maxTokens !== undefined &&
+            this.budget.maxTokens !== undefined &&
+            update.maxTokens > this.budget.maxTokens) {
+            throw new Error(`Goal maxTokens cannot exceed the configured limit of ${this.budget.maxTokens}`);
+        }
+        const minimumIterations = current.status === "active" ? current.usage.iterations + 1 : current.usage.iterations;
+        if (update.maxIterations !== undefined && update.maxIterations < minimumIterations) {
+            throw new Error(current.status === "active"
+                ? `Goal maxIterations must leave capacity for the current turn (${minimumIterations} minimum)`
+                : `Goal maxIterations cannot be lower than ${current.usage.iterations} accounted turns`);
+        }
+        const minimumTokens = current.status === "active" ? current.usage.tokens + 1 : current.usage.tokens;
+        if (update.maxTokens !== undefined && update.maxTokens < minimumTokens) {
+            throw new Error(current.status === "active"
+                ? `Goal maxTokens must leave capacity beyond ${current.usage.tokens} accounted tokens`
+                : `Goal maxTokens cannot be lower than ${current.usage.tokens} accounted tokens`);
+        }
+        const nextBudget = {
+            ...current.budget,
+            ...(update.maxIterations === undefined ? {} : { maxIterations: update.maxIterations }),
+            ...(update.maxTokens === undefined ? {} : { maxTokens: update.maxTokens }),
+        };
+        const candidate = {
+            ...current,
+            budget: nextBudget,
+            version: current.version + 1,
+            updatedAt: this.now().toISOString(),
+        };
+        const exhausted = this.budgetExhausted(candidate);
+        const next = current.status === "budget_limited" && !exhausted
+            ? { ...candidate, status: "active", blockedReason: undefined }
+            : candidate;
+        if (!(await this.storage.updateBudget(next, current.version))) {
+            throw new Error("Goal changed while its budget was being updated; retry the command");
+        }
+        await this.record({ type: "goal.budget_changed", goal: next, previousBudget: current.budget });
+        if (current.status === "budget_limited" && next.status === "active") {
+            await this.continueWithClaim(next, "Continue with the expanded goal budget.");
+        }
+        return next;
+    }
     async setStatus(scopeId, status) {
         const current = await this.requireGoal(scopeId);
         const transitionAllowed = (status === "active" && (current.status === "paused" || current.status === "blocked")) ||
@@ -459,6 +518,22 @@ export class GoalRuntime {
         for (let attempt = claim.attempt + 1; attempt <= this.retryPolicy.maxAttempts; attempt += 1) {
             const currentGoal = await this.storage.get(goal.scopeId);
             const currentClaim = await this.storage.getContinuationClaim(goal.scopeId);
+            if (currentGoal?.id === goal.id &&
+                currentGoal.status === "active" &&
+                currentGoal.version !== goal.version &&
+                currentClaim?.claimId === claim.claimId) {
+                if (currentClaim.state === "started") {
+                    this.scheduleRecovery(goal.scopeId, currentClaim.expiresAt);
+                }
+                else if (currentClaim.state === "deferred" &&
+                    Date.parse(currentClaim.availableAt) > this.now().getTime()) {
+                    this.scheduleRecovery(goal.scopeId, currentClaim.availableAt);
+                }
+                else {
+                    await this.runContinuationClaim(currentGoal, currentClaim);
+                }
+                return;
+            }
             if (!currentGoal ||
                 currentGoal.id !== goal.id ||
                 currentGoal.version !== goal.version ||

package/dist/sqlite-storage.d.ts

@@ -5,6 +5,7 @@ export declare class SqliteGoalStorage implements GoalStorage {
     get(scopeId: string): Promise<AgentGoal | undefined>;
     create(goal: AgentGoal): Promise<void>;
     replace(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
+    updateBudget(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
     delete(scopeId: string, expectedVersion: number): Promise<boolean>;
     getPendingEvaluation(scopeId: string): Promise<GoalPendingEvaluation | undefined>;
     appendPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;

package/dist/sqlite-storage.js

@@ -179,6 +179,41 @@ export class SqliteGoalStorage {
             .run(goal.objective, goal.status, goal.blockedReason ?? null, goal.budget.maxIterations, goal.budget.maxTokens ?? null, goal.budget.maxRuntimeMs ?? null, goal.usage.iterations, goal.usage.tokens, goal.lastSettledAt ?? null, goal.lastEvaluation?.id ?? null, goal.lastEvaluation?.outcome ?? null, goal.lastEvaluation?.reason ?? null, goal.lastEvaluation?.at ?? null, goal.version, goal.updatedAt, goal.scopeId, goal.id, expectedVersion);
         return result.changes === 1;
     }
+    async updateBudget(goal, expectedVersion) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = this.db
+                .prepare(`UPDATE agent_goals SET objective = ?, status = ?, blocked_reason = ?,
+           max_iterations = ?, max_tokens = ?, max_runtime_ms = ?, iterations_used = ?,
+           tokens_used = ?, last_settled_at = ?, last_evaluation_id = ?,
+           last_evaluation_outcome = ?, last_evaluation_reason = ?, last_evaluation_at = ?,
+           version = ?, updated_at = ?
+           WHERE scope_id = ? AND id = ? AND version = ?`)
+                .run(goal.objective, goal.status, goal.blockedReason ?? null, goal.budget.maxIterations, goal.budget.maxTokens ?? null, goal.budget.maxRuntimeMs ?? null, goal.usage.iterations, goal.usage.tokens, goal.lastSettledAt ?? null, goal.lastEvaluation?.id ?? null, goal.lastEvaluation?.outcome ?? null, goal.lastEvaluation?.reason ?? null, goal.lastEvaluation?.at ?? null, goal.version, goal.updatedAt, goal.scopeId, goal.id, expectedVersion);
+            if (result.changes !== 1) {
+                this.db.exec("ROLLBACK");
+                return false;
+            }
+            this.db
+                .prepare(`UPDATE agent_goal_pending_evaluations SET goal_version = ?
+           WHERE scope_id = ? AND goal_id = ? AND goal_version = ?`)
+                .run(goal.version, goal.scopeId, goal.id, expectedVersion);
+            this.db
+                .prepare(`UPDATE agent_goal_terminal_candidates SET goal_version = ?
+           WHERE scope_id = ? AND goal_id = ? AND goal_version = ?`)
+                .run(goal.version, goal.scopeId, goal.id, expectedVersion);
+            this.db
+                .prepare(`UPDATE agent_goal_continuations SET goal_version = ?
+           WHERE scope_id = ? AND goal_id = ? AND goal_version = ?`)
+                .run(goal.version, goal.scopeId, goal.id, expectedVersion);
+            this.db.exec("COMMIT");
+            return true;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
     async delete(scopeId, expectedVersion) {
         const result = this.db
             .prepare("DELETE FROM agent_goals WHERE scope_id = ? AND version = ?")
@@ -217,10 +252,9 @@ export class SqliteGoalStorage {
          (scope_id, goal_id, goal_version, evaluation_id, iterations_delta, latest_output,
           token_delta, candidate_outcome, candidate_reason, attempt, available_at, last_error,
           created_at, updated_at)
-         SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
-         WHERE EXISTS (
-           SELECT 1 FROM agent_goals WHERE scope_id = ? AND id = ? AND version = ?
-         )
+         SELECT ?, ?, goal.version, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+         FROM agent_goals AS goal
+         WHERE goal.scope_id = ? AND goal.id = ? AND goal.status = 'active'
          ON CONFLICT(scope_id) DO UPDATE SET goal_id = excluded.goal_id,
            goal_version = excluded.goal_version, evaluation_id = excluded.evaluation_id,
            iterations_delta = CASE
@@ -253,7 +287,7 @@ export class SqliteGoalStorage {
               AND agent_goal_pending_evaluations.goal_version = excluded.goal_version
              THEN agent_goal_pending_evaluations.created_at ELSE excluded.created_at END,
            updated_at = excluded.updated_at`)
-            .run(pending.scopeId, pending.goalId, pending.goalVersion, pending.evaluationId, pending.iterationsDelta, pending.progress.latestOutput, pending.progress.tokenDelta ?? 0, pending.progress.terminalCandidate?.outcome ?? null, pending.progress.terminalCandidate?.reason ?? null, pending.attempt, pending.availableAt, pending.lastError ?? null, pending.createdAt, pending.updatedAt, pending.scopeId, pending.goalId, pending.goalVersion);
+            .run(pending.scopeId, pending.goalId, pending.evaluationId, pending.iterationsDelta, pending.progress.latestOutput, pending.progress.tokenDelta ?? 0, pending.progress.terminalCandidate?.outcome ?? null, pending.progress.terminalCandidate?.reason ?? null, pending.attempt, pending.availableAt, pending.lastError ?? null, pending.createdAt, pending.updatedAt, pending.scopeId, pending.goalId);
         return result.changes === 1;
     }
     async putPendingEvaluation(pending) {
@@ -402,10 +436,14 @@ export class SqliteGoalStorage {
     }
     async replaceContinuationClaim(claim, expectedClaimId) {
         const result = this.db
-            .prepare(`UPDATE agent_goal_continuations SET goal_id = ?, goal_version = ?, claim_id = ?,
-         state = ?, reason = ?, attempt = ?, available_at = ?, expires_at = ?,
-         last_error = ?, updated_at = ? WHERE scope_id = ? AND claim_id = ?`)
-            .run(claim.goalId, claim.goalVersion, claim.claimId, claim.state, claim.reason, claim.attempt, claim.availableAt, claim.expiresAt, claim.lastError ?? null, claim.updatedAt, claim.scopeId, expectedClaimId);
+            .prepare(`UPDATE agent_goal_continuations SET goal_id = ?,
+         goal_version = (SELECT version FROM agent_goals WHERE scope_id = ? AND id = ?),
+         claim_id = ?, state = ?, reason = ?, attempt = ?, available_at = ?, expires_at = ?,
+         last_error = ?, updated_at = ? WHERE scope_id = ? AND claim_id = ?
+         AND goal_id = ? AND EXISTS (
+           SELECT 1 FROM agent_goals WHERE scope_id = ? AND id = ? AND status = 'active'
+         )`)
+            .run(claim.goalId, claim.scopeId, claim.goalId, claim.claimId, claim.state, claim.reason, claim.attempt, claim.availableAt, claim.expiresAt, claim.lastError ?? null, claim.updatedAt, claim.scopeId, expectedClaimId, claim.goalId, claim.scopeId, claim.goalId);
         return result.changes === 1;
     }
     async deleteContinuationClaim(scopeId, expectedClaimId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/agent-goal",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "type": "module",
   "description": "Standalone single-agent durable goal loop for Pi",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",