@pinet/agent-goal 0.2.13 → 0.2.14

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, parseDuration } 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, parseDuration } from "./goal-window.js";
 export { MemoryGoalStorage } from "./memory-storage.js";
 export { parseGoalEvaluation, PiGoalEvaluator } from "./pi-evaluator.js";
 export { countGoalProgressTokens, formatGoalProgress, } from "./progress.js";
@@ -24,9 +24,8 @@ export function registerAgentGoal(pi, options = {}) {
     const hiddenScopes = new Set();
     const agentCreatedGoalScopes = new Set();
     const defaultBudget = options.defaultBudget ?? {
-        maxIterations: Number(process.env.PI_AGENT_GOAL_MAX_ITERATIONS ?? 25),
-        maxTokens: process.env.PI_AGENT_GOAL_MAX_TOKENS
-            ? Number(process.env.PI_AGENT_GOAL_MAX_TOKENS)
+        maxIterations: process.env.PI_AGENT_GOAL_MAX_ITERATIONS
+            ? Number(process.env.PI_AGENT_GOAL_MAX_ITERATIONS)
             : undefined,
         maxRuntimeMs: process.env.PI_AGENT_GOAL_MAX_RUNTIME_MS
             ? Number(process.env.PI_AGENT_GOAL_MAX_RUNTIME_MS)
@@ -78,27 +77,33 @@ 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,
-            });
+        if (action === "closeGoal") {
+            await runtime.closeGoal(scopeId);
             return;
         }
-        switch (action) {
-            case "pause":
-                await runtime.setStatus(scopeId, "paused");
-                break;
-            case "resume":
-                await runtime.setStatus(scopeId, "active");
+        if (action === "pause" || action === "resume") {
+            await runtime.setStatus(scopeId, action === "pause" ? "paused" : "active");
+            if (action === "resume")
                 await runtime.start(scopeId, "Resume the goal from current state.");
+            return;
+        }
+        switch (action.type) {
+            case "create":
+                await runtime.create(scopeId, action.objective, {
+                    ...defaultBudget,
+                    ...(action.maxIterations === undefined ? {} : { maxIterations: action.maxIterations }),
+                    ...(action.maxRuntimeMs === undefined ? {} : { maxRuntimeMs: action.maxRuntimeMs }),
+                }, action.name);
+                await runtime.start(scopeId);
+                break;
+            case "edit":
+                await runtime.updateDetails(scopeId, action);
                 break;
-            case "complete":
-                await runtime.setStatus(scopeId, "complete");
+            case "budget":
+                await runtime.updateBudget(scopeId, action);
                 break;
-            case "clear":
-                if (!(await runtime.clear(scopeId)))
-                    throw new Error("This session has no goal");
+            case "snooze":
+                await runtime.snooze(scopeId, action.durationMs);
                 break;
         }
     };
@@ -167,14 +172,8 @@ export function registerAgentGoal(pi, options = {}) {
         parameters: {
             type: "object",
             properties: {
+                name: { type: "string", description: "Short terminal-friendly goal name." },
                 objective: { type: "string", description: "The complete user-aligned outcome to achieve." },
-                maxIterations: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: defaultBudget.maxIterations,
-                },
-                maxTokens: { type: "number", exclusiveMinimum: 0 },
-                maxRuntimeMs: { type: "number", exclusiveMinimum: 0 },
             },
             required: ["objective"],
             additionalProperties: false,
@@ -183,25 +182,7 @@ export function registerAgentGoal(pi, options = {}) {
             const params = rawParams;
             const ctx = rawCtx;
             const scopeId = ctx.sessionManager.getSessionId();
-            if (params.maxIterations !== undefined &&
-                params.maxIterations > defaultBudget.maxIterations) {
-                throw new Error(`Goal maxIterations cannot exceed the configured limit of ${defaultBudget.maxIterations}`);
-            }
-            if (params.maxTokens !== undefined &&
-                defaultBudget.maxTokens !== undefined &&
-                params.maxTokens > defaultBudget.maxTokens) {
-                throw new Error(`Goal maxTokens cannot exceed the configured limit of ${defaultBudget.maxTokens}`);
-            }
-            if (params.maxRuntimeMs !== undefined &&
-                defaultBudget.maxRuntimeMs !== undefined &&
-                params.maxRuntimeMs > defaultBudget.maxRuntimeMs) {
-                throw new Error(`Goal maxRuntimeMs cannot exceed the configured limit of ${defaultBudget.maxRuntimeMs}`);
-            }
-            const goal = await runtime.create(scopeId, params.objective, {
-                maxIterations: params.maxIterations ?? defaultBudget.maxIterations,
-                maxTokens: params.maxTokens ?? defaultBudget.maxTokens,
-                maxRuntimeMs: params.maxRuntimeMs ?? defaultBudget.maxRuntimeMs,
-            });
+            const goal = await runtime.create(scopeId, params.objective, defaultBudget, params.name);
             agentCreatedGoalScopes.add(scopeId);
             await refreshUi(ctx);
             return {
@@ -217,9 +198,9 @@ 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.",
+        label: "Update goal limits",
+        description: "Set optional turns/runtime continuation limits, or turn limits off. Limits never interrupt in-flight work and changes preserve accounted usage.",
+        promptSnippet: "Adjust the active session goal's optional continuation limits.",
         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.",
@@ -231,15 +212,17 @@ export function registerAgentGoal(pi, options = {}) {
                 maxTurns: {
                     type: "integer",
                     minimum: 1,
-                    maximum: defaultBudget.maxIterations,
+                    ...(defaultBudget.maxIterations === undefined
+                        ? {}
+                        : { maximum: defaultBudget.maxIterations }),
                     description: "New total settled-turn ceiling, including turns already accounted.",
                 },
-                maxTokens: {
+                maxRuntimeMs: {
                     type: "number",
                     exclusiveMinimum: 0,
-                    ...(defaultBudget.maxTokens === undefined ? {} : { maximum: defaultBudget.maxTokens }),
-                    description: "New total token ceiling, including tokens already accounted.",
+                    description: "New total runtime ceiling in milliseconds.",
                 },
+                off: { type: "boolean", description: "Disable all continuation limits." },
             },
             additionalProperties: false,
         },
@@ -248,14 +231,15 @@ export function registerAgentGoal(pi, options = {}) {
             const ctx = rawCtx;
             const goal = await runtime.updateBudget(ctx.sessionManager.getSessionId(), {
                 maxIterations: params.maxTurns,
-                maxTokens: params.maxTokens,
+                maxRuntimeMs: params.maxRuntimeMs,
+                disabled: params.off,
             });
             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`}.`,
+                        text: `Updated goal limits: ${goal.budget.maxIterations ?? "unlimited"} turns, ${goal.budget.maxRuntimeMs ?? "unlimited"}ms runtime.`,
                     },
                 ],
                 details: { goal },
@@ -336,8 +320,32 @@ export function registerAgentGoal(pi, options = {}) {
             };
         },
     });
+    pi.registerTool({
+        name: "checkpoint_goal",
+        label: "Checkpoint goal",
+        description: "Record durable agent-reported progress, evidence, and the next step or blocker.",
+        promptSnippet: "Record a concise durable progress checkpoint for the active goal.",
+        parameters: {
+            type: "object",
+            properties: {
+                summary: { type: "string" },
+                evidence: { type: "string" },
+                nextStep: { type: "string" },
+                blocker: { type: "string" },
+            },
+            required: ["summary"],
+            additionalProperties: false,
+        },
+        async execute(_toolCallId, rawParams, _signal, _onUpdate, rawCtx) {
+            const checkpoint = await runtime.addCheckpoint(rawCtx.sessionManager.getSessionId(), rawParams);
+            return {
+                content: [{ type: "text", text: `Checkpoint recorded: ${checkpoint.summary}` }],
+                details: { checkpoint },
+            };
+        },
+    });
     pi.registerCommand("goal", {
-        description: "Create, inspect, adjust budget, pause, resume, complete, clear, show, or hide this session's goal",
+        description: "Create or inspect a goal; update its name, objective, or limits; snooze, close, show, or hide it",
         handler: async (args, rawCtx) => {
             const ctx = rawCtx;
             activeContext = ctx;
@@ -350,9 +358,10 @@ export function registerAgentGoal(pi, options = {}) {
                     while (true) {
                         const goal = await runtime.get(scopeId);
                         const claim = await runtime.getContinuationClaim(scopeId);
+                        const checkpoints = await runtime.listCheckpoints(scopeId);
                         const action = await ctx.ui.custom((tui, theme, _keybindings, done) => {
                             openedWindow = true;
-                            return new GoalWindow(goal, claim, theme, done, () => tui.requestRender(), Date.now, actionError);
+                            return new GoalWindow(goal, claim, theme, done, () => tui.requestRender(), Date.now, actionError, checkpoints);
                         }, {
                             overlay: true,
                             overlayOptions: {
@@ -367,7 +376,7 @@ export function registerAgentGoal(pi, options = {}) {
                             api.sendMessage({
                                 customType: "agent-goal.status",
                                 content: goal
-                                    ? formatGoalDashboard(goal, claim).join("\n")
+                                    ? formatGoalDashboard(goal, claim, checkpoints).join("\n")
                                     : "This session has no goal.",
                                 display: true,
                             }, { triggerTurn: false });
@@ -386,48 +395,46 @@ export function registerAgentGoal(pi, options = {}) {
                     }
                 }
                 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;
+                if (command.startsWith("update name ")) {
+                    await runtime.updateDetails(scopeId, { name: input.slice("update name ".length) });
+                }
+                else if (command.startsWith("update objective ")) {
+                    await runtime.updateDetails(scopeId, {
+                        objective: input.slice("update objective ".length),
+                    });
+                }
+                else if (command === "update budget off") {
+                    await runtime.updateBudget(scopeId, { disabled: true });
+                }
+                else if (command.startsWith("update budget turns ")) {
+                    await runtime.updateBudget(scopeId, {
+                        maxIterations: Number(input.slice("update budget turns ".length)),
+                    });
+                }
+                else if (command.startsWith("update budget runtime ")) {
+                    const duration = parseDuration(input.slice("update budget runtime ".length));
+                    if (duration === undefined)
+                        throw new Error("Runtime must use m, h, or d");
+                    await runtime.updateBudget(scopeId, { maxRuntimeMs: duration });
+                }
+                else if (command.startsWith("snooze ")) {
+                    const duration = parseDuration(input.slice("snooze ".length));
+                    if (duration === undefined)
+                        throw new Error("Snooze must use m, h, or d");
+                    await runtime.snooze(scopeId, duration);
+                }
+                else if (command === "close") {
+                    await runtime.closeGoal(scopeId);
+                }
+                else if (command === "hide") {
+                    hiddenScopes.add(scopeId);
+                }
+                else if (command === "show") {
+                    hiddenScopes.delete(scopeId);
                 }
-                switch (command) {
-                    case "pause":
-                    case "resume":
-                    case "complete":
-                    case "clear":
-                        await applyGoalAction(scopeId, command);
-                        break;
-                    case "hide":
-                        hiddenScopes.add(scopeId);
-                        break;
-                    case "show":
-                        hiddenScopes.delete(scopeId);
-                        break;
-                    default:
-                        await runtime.create(scopeId, input);
-                        await runtime.start(scopeId);
-                        break;
+                else {
+                    await runtime.create(scopeId, input);
+                    await runtime.start(scopeId);
                 }
                 await refreshUi(ctx);
                 if (ctx.hasUI)

package/dist/memory-storage.d.ts

@@ -1,13 +1,16 @@
-import type { AgentGoal, GoalContinuationClaim, GoalPendingEvaluation, GoalStorage, GoalTerminalCandidateRecord } from "./domain.js";
+import type { AgentGoal, GoalCheckpoint, GoalContinuationClaim, GoalPendingEvaluation, GoalStorage, GoalTerminalCandidateRecord } from "./domain.js";
 export declare class MemoryGoalStorage implements GoalStorage {
     private readonly goals;
     private readonly pendingEvaluations;
+    private readonly checkpoints;
     private readonly terminalCandidates;
     private readonly claims;
     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>;
+    addCheckpoint(checkpoint: GoalCheckpoint): Promise<boolean>;
+    listCheckpoints(scopeId: string): Promise<GoalCheckpoint[]>;
     delete(scopeId: string, expectedVersion: number): Promise<boolean>;
     getPendingEvaluation(scopeId: string): Promise<GoalPendingEvaluation | undefined>;
     appendPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;

package/dist/memory-storage.js

@@ -9,6 +9,7 @@ function cloneGoal(goal) {
 export class MemoryGoalStorage {
     goals = new Map();
     pendingEvaluations = new Map();
+    checkpoints = new Map();
     terminalCandidates = new Map();
     claims = new Map();
     async get(scopeId) {
@@ -46,6 +47,18 @@ export class MemoryGoalStorage {
         }
         return true;
     }
+    async addCheckpoint(checkpoint) {
+        const goal = this.goals.get(checkpoint.scopeId);
+        if (!goal || goal.id !== checkpoint.goalId || goal.status === "complete")
+            return false;
+        const checkpoints = this.checkpoints.get(checkpoint.scopeId) ?? [];
+        checkpoints.push({ ...checkpoint });
+        this.checkpoints.set(checkpoint.scopeId, checkpoints);
+        return true;
+    }
+    async listCheckpoints(scopeId) {
+        return (this.checkpoints.get(scopeId) ?? []).map((checkpoint) => ({ ...checkpoint })).reverse();
+    }
     async delete(scopeId, expectedVersion) {
         const current = this.goals.get(scopeId);
         if (!current || current.version !== expectedVersion)
@@ -53,6 +66,7 @@ export class MemoryGoalStorage {
         this.pendingEvaluations.delete(scopeId);
         this.terminalCandidates.delete(scopeId);
         this.claims.delete(scopeId);
+        this.checkpoints.delete(scopeId);
         return this.goals.delete(scopeId);
     }
     async getPendingEvaluation(scopeId) {
@@ -124,7 +138,13 @@ export class MemoryGoalStorage {
             pending?.evaluationId !== expectedEvaluationId) {
             return false;
         }
-        this.goals.set(goal.scopeId, cloneGoal(goal));
+        this.goals.set(goal.scopeId, {
+            ...cloneGoal(goal),
+            name: current.name,
+            objective: current.objective,
+            budget: { ...current.budget },
+            snoozedUntil: current.snoozedUntil,
+        });
         this.pendingEvaluations.delete(goal.scopeId);
         return true;
     }

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { AgentGoal, GoalBudget, GoalBudgetUpdate, GoalContinuation, GoalContinuationClaim, GoalEvaluator, GoalEventSink, GoalProgress, GoalRetryPolicy, GoalStatus, GoalStorage, GoalTerminalCandidate, GoalTerminalCandidateRecord, GoalWakeScheduler } from "./domain.js";
+import type { AgentGoal, GoalBudget, GoalCheckpoint, GoalBudgetUpdate, GoalContinuation, GoalContinuationClaim, GoalEvaluator, GoalEventSink, GoalProgress, GoalRetryPolicy, GoalStatus, GoalStorage, GoalTerminalCandidate, GoalTerminalCandidateRecord, GoalWakeScheduler } from "./domain.js";
 export interface GoalRuntimeOptions {
     defaultBudget?: GoalBudget;
     retryPolicy?: GoalRetryPolicy;
@@ -28,8 +28,21 @@ export declare class GoalRuntime {
     get(scopeId: string): Promise<AgentGoal | undefined>;
     getContinuationClaim(scopeId: string): Promise<GoalContinuationClaim | undefined>;
     getTerminalCandidate(scopeId: string): Promise<GoalTerminalCandidateRecord | undefined>;
-    create(scopeId: string, objective: string, budget?: GoalBudget): Promise<AgentGoal>;
+    listCheckpoints(scopeId: string): Promise<GoalCheckpoint[]>;
+    create(scopeId: string, objective: string, budget?: GoalBudget, name?: string): Promise<AgentGoal>;
     updateBudget(scopeId: string, update: GoalBudgetUpdate): Promise<AgentGoal>;
+    updateDetails(scopeId: string, update: {
+        name?: string;
+        objective?: string;
+    }): Promise<AgentGoal>;
+    addCheckpoint(scopeId: string, input: {
+        summary: string;
+        evidence?: string;
+        nextStep?: string;
+        blocker?: string;
+    }): Promise<GoalCheckpoint>;
+    snooze(scopeId: string, durationMs: number): Promise<AgentGoal>;
+    closeGoal(scopeId: string): 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>;