@pinet/agent-goal 0.2.13 → 0.2.15

package/README.md

@@ -1,8 +1,8 @@
 # @pinet/agent-goal
 
-A standalone Pi extension that keeps one agent session working toward one durable, bounded goal. It does not require Pinet, the Pinet broker, RALPH, or Slack.
+A standalone Pi extension that keeps one agent session working toward one durable goal. It does not require Pinet, the broker, RALPH, or Slack.
 
-The worker runs normally and stops when its current pass is finished. Every settled active-goal run is independently evaluated as `continue`, `complete`, or `blocked`; the worker does not need to make a special terminal request. Completed, blocked, budget-limited, paused, and cleared goals do not continue.
+The worker runs normally. Every settled active-goal run is independently evaluated as `continue`, `complete`, or `blocked`. A continuation starts only while the goal remains active, unsnoozed, and within any operator-enabled limits.
 
 ## Install
 
@@ -10,95 +10,71 @@ The worker runs normally and stops when its current pass is finished. Every sett
 pi install npm:@pinet/agent-goal
 ```
 
-For local development:
+For local development: `pi -e ./agent-goal/index.ts`.
 
-```bash
-pi -e ./agent-goal/index.ts
-```
-
-## Commands and UI
+## Commands and terminal UI
 
 ```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
-/goal clear        Delete the goal
-/goal hide         Hide the compact persistent goal status
-/goal show         Show the compact persistent goal status
+/goal <idea>                         Ask the agent to refine a possible goal with you
+/goal demo                           Start an agent-guided walkthrough
+/goal                                Open the create/details overlay
+/goal update                         Open the edit form
+/goal update <objective>             Apply a new objective to the next continuation
+/goal update name <name>             Rename immediately
+/goal update objective <objective>   Apply a new objective to the next continuation
+/goal update budget turns <n>        Set an optional total-turn limit
+/goal update budget runtime <2h>     Set an optional total-runtime limit
+/goal update budget off              Disable continuation limits
+/goal snooze <30m|2h|1d>             Snooze, then continue automatically
+/goal close                          Complete and clear the current goal
+/goal clear                          Clear the current goal immediately
+/goal hide | /goal show              Hide or show compact 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. 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.
+`/goal <idea>` starts a normal agent turn to clarify the outcome, scope, constraints, completion evidence, and optional limits; it does not create anything until you confirm the resulting goal. The persistent row is deliberately compact: `🎯 name elapsed`. `/goal` opens a terminal-native overlay. An empty session gets a create form; an existing goal gets details and `e` edit, `b` limits, `s` timed snooze, and `x` close controls. Escape cancels a form or closes the details overlay; Ctrl+C also closes the overlay. Closing a goal requires confirmation and remains available for blocked and budget-limited goals.
+
+`/goal demo` asks the agent to walk through a small example, checkpointing, inspection, and verified completion. Demo and idea discussions require a session without an existing goal; otherwise the command reports an error without starting a turn. The walkthrough asks for consent before creating its example goal.
+
+Name changes are visible immediately. Objective changes are fenced from stale evaluations and are used by the next continuation. Snooze is timed only: there is no indefinite pause or manual resume action, and a compare-and-swap wake prevents duplicate continuation.
+
+Only one current goal may exist per Pi session. A verified completion clears that current goal so another can be created; `/goal close` records completion before clearing, while `/goal clear` removes it immediately. Clearing removes its persisted checkpoints as well.
 
-Only one goal may exist per Pi session. Clear the existing goal before creating another.
+## Agent tools and checkpoints
 
-The agent also receives four model-visible tools:
+The extension registers five 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
+- `create_goal` — create a user-aligned goal with a short name and objective
+- `checkpoint_goal` — append progress with optional evidence, next step, or blocker
+- `update_goal_budget` — set optional turn/runtime continuation limits or turn them off
+- `get_goal` — inspect current durable state
+- `update_goal` — attach a `complete` or `blocked` candidate for independent evaluation
 
-An agent-created goal cannot replace an existing goal. The creating run is evaluated when it settles, but its iteration and token usage are not charged because some work may predate goal creation. A `continue` decision starts the first charged goal iteration.
+Checkpoints are agent-reported progress records, not recovery snapshots. They persist with the goal. The overlay initially shows the newest three checkpoints. Tab/Shift+Tab selects across the full history; Enter opens the selected checkpoint's full summary, evidence, next step, and blocker. Use ↑/↓ to scroll and Escape to return. The headless dashboard shows the newest three and `… and X more`.
 
-## Budgets
+## Optional continuation limits
 
-Goals default to 25 settled iterations. Optional token and runtime limits are supported:
+New goals are unlimited by default. Turns and runtime limits are opt-in and only decide whether a future continuation may start; they never interrupt in-flight work. Existing usage is preserved when limits change or are disabled. Configured environment values remain hard ceilings/defaults when present:
 
 ```text
 PI_AGENT_GOAL_MAX_ITERATIONS=25
-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. 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.
+Legacy token limits and accounted token usage remain readable and enforceable for stored goals, but token controls are omitted from the new UX because provider accounting is not reliably comparable.
 
-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.
+The evaluator reviews every settled run, including the final allowed turn, before a goal becomes budget-limited. Increasing or disabling exhausted limits reactivates the same goal when continuation capacity exists.
 
 ## Persistence and recovery
 
-The default adapter stores goals and continuation claims in SQLite at:
+SQLite storage defaults to `~/.pi/agent/agent-goals.sqlite`; set `PI_AGENT_GOAL_DB` to override it. Schema upgrades add nullable name/snooze fields and durable checkpoints without discarding legacy goals or token data. Legacy goals derive their display name from their objective.
 
-```text
-~/.pi/agent/agent-goals.sqlite
-```
-
-Set `PI_AGENT_GOAL_DB` to use another path. The stable Pi session ID is the storage scope, so resuming a session restores its goal. Optimistic goal versions reject stale mutations.
+Optimistic versions reject stale mutations. Metadata/limit edits atomically advance pending evaluation, candidate, and continuation-claim versions. Evaluation commit updates lifecycle and usage fields only, so an old result cannot overwrite a newer name, objective, limit, or snooze. Settlements arriving during evaluation are aggregated and charged exactly once.
 
-Every continuation first acquires a durable, idempotent per-session claim. Busy sessions persist a deferred claim and schedule an in-process wake for their retry time without consuming failure attempts. Started claims schedule an expiry wake, remain until the next agent run begins, and recover safely after interruption or session resume. Evaluator and unavailable/rejected continuation failures use bounded exponential retries; exhausted retries block the goal with a diagnostic reason.
-
-Settlements that arrive during an in-flight evaluation are atomically aggregated in storage. Every settled iteration and token delta is charged, while the evaluator receives the newest bounded progress and any preserved terminal candidate. Event sinks receive `goal.evaluated` for every committed evaluation; a no-hint `continue` also retains the compatibility `goal.auto_continued` event.
+Every continuation acquires a durable per-session claim. Busy sessions defer with an in-process wake. Timed snooze uses the same scheduler; expiry clears the snooze with compare-and-swap before continuation, so duplicate timer callbacks cannot produce duplicate wakes. Failures use bounded retries and eventually block with a diagnostic reason.
 
 ## Architecture
 
-The domain and runtime depend on ports rather than Pi, Pinet, or SQLite:
-
-```ts
-interface GoalEvaluator {
-  evaluate(goal: AgentGoal, progress: GoalProgress): Promise<GoalEvaluation>;
-}
-
-interface GoalContinuation {
-  continueIfIdle(
-    goal: AgentGoal,
-    request: GoalContinuationRequest,
-  ): Promise<GoalContinuationResult>;
-}
-
-interface GoalEventSink {
-  record(event: GoalEvent): Promise<void> | void;
-}
-
-interface GoalWakeScheduler {
-  schedule(scopeId: string, wakeAt: string, wake: () => void): void;
-  cancel(scopeId: string): void;
-  close(): void;
-}
-```
-
-`GoalStorage` includes optimistic goal mutation, atomic pending-settlement aggregation, and durable continuation-claim operations. `TimerGoalWakeScheduler` is the default process-local wake adapter and can be replaced through `GoalRuntimeOptions`. The package exports `GoalRuntime`, both storage adapters, the wake adapter, `PiGoalEvaluator`, dashboard formatters, lifecycle event types, and `registerAgentGoal`.
+The runtime depends on ports for evaluation, continuation, events, wake scheduling, and storage. `GoalStorage` owns optimistic goal mutations, checkpoints, pending-settlement aggregation, terminal candidates, and continuation claims. The package exports `GoalRuntime`, memory/SQLite storage, `TimerGoalWakeScheduler`, `PiGoalEvaluator`, dashboard formatters, and `registerAgentGoal`.
 
 ```ts
 import { registerAgentGoal } from "@pinet/agent-goal";
@@ -108,26 +84,10 @@ registerAgentGoal(pi, {
   evaluator: myEvaluator,
   continuation: myAtomicContinuationAdapter,
   eventSink: myEventSink,
-  defaultBudget: { maxIterations: 20, maxTokens: 150_000 },
+  defaultBudget: { maxIterations: 20, maxRuntimeMs: 14_400_000 },
 });
 ```
 
-The continuation adapter owns the final idle check and idempotent enqueue. Pi's current API does not expose Codex's exact `start_turn_if_idle` primitive, so the default adapter performs the closest safe operation: it rechecks session identity, idle state, and pending messages immediately before submitting a follow-up. A future Pi or Pinet adapter can provide a truly atomic implementation without changing `GoalRuntime`.
-
-A future Pinet integration can use broker storage and evaluation plus RALPH recovery through these ports, without introducing multi-agent decomposition.
-
-## Automatic evaluation
-
-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:
-
-- `continue` with the next required work
-- `complete` with completion evidence
-- `blocked` with a specific unavailable external dependency
-
-The standalone in-process evaluator receives bounded recent assistant and tool evidence plus any terminal candidate. Its output is strictly parsed. Newer settled progress supersedes an older in-flight result. Invalid output and provider failures are retried within policy, then recorded as a blocked goal rather than allowing an unverified terminal decision.
-
-The standalone evaluator intentionally remains a zero-process, zero-runtime-dependency baseline. A future Pinet broker adapter can replace storage, evaluation, continuation, and events to add authoritative evidence inspection, atomic wake scheduling, and watchdog recovery. Subagent evaluators remain optional adapters; tmux and spawned Pi processes are not required.
+Pi's current API does not expose Codex's exact `start_turn_if_idle` primitive. The default adapter rechecks session identity, idle state, and pending messages immediately before follow-up submission. A Pinet adapter can replace these ports without changing `GoalRuntime`.
 
-Continuation prompts explicitly treat the objective as user-provided task data, never as higher-priority instructions.
+Continuation prompts treat the objective as user-provided task data, never as higher-priority instructions.

package/dist/dashboard.d.ts

@@ -1,4 +1,6 @@
-import type { AgentGoal, GoalContinuationClaim } from "./domain.js";
+import type { AgentGoal, GoalCheckpoint, GoalContinuationClaim } from "./domain.js";
 export declare function displayGoalText(value: string, maxLength: number): string;
-export declare function formatGoalStatus(goal: AgentGoal): string;
-export declare function formatGoalDashboard(goal: AgentGoal, claim?: GoalContinuationClaim): string[];
+export declare function goalDisplayName(goal: AgentGoal): string;
+export declare function formatElapsed(milliseconds: number): string;
+export declare function formatGoalStatus(goal: AgentGoal, now?: number): string;
+export declare function formatGoalDashboard(goal: AgentGoal, claim?: GoalContinuationClaim, checkpoints?: GoalCheckpoint[]): string[];

package/dist/dashboard.js

@@ -1,35 +1,48 @@
+import { stripVTControlCharacters } from "node:util";
 export function displayGoalText(value, maxLength) {
-    const normalized = value
-        .replaceAll("\n", " ")
-        .replaceAll("\r", " ")
-        .replaceAll("\u001b", "")
+    const normalized = Array.from(stripVTControlCharacters(value).replaceAll(/\r?\n/g, " "))
+        .filter((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code >= 32 && (code < 127 || code > 159);
+    })
+        .join("")
         .trim();
     return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 3)}...` : normalized;
 }
-export function formatGoalStatus(goal) {
-    const iterations = `${goal.usage.iterations}/${goal.budget.maxIterations}`;
-    const tokens = goal.budget.maxTokens
-        ? ` · ${goal.usage.tokens}/${goal.budget.maxTokens} tok`
-        : "";
-    return `goal: ${goal.status} · ${iterations} turns${tokens}`;
+export function goalDisplayName(goal) {
+    return displayGoalText(goal.name ?? goal.objective, 72);
 }
-export function formatGoalDashboard(goal, claim) {
-    const usage = [
-        `Turns ${goal.usage.iterations}/${goal.budget.maxIterations}`,
-        goal.budget.maxTokens === undefined
-            ? `Tokens ${goal.usage.tokens}`
-            : `Tokens ${goal.usage.tokens}/${goal.budget.maxTokens}`,
-        goal.budget.maxRuntimeMs === undefined
-            ? undefined
-            : `Runtime limit ${Math.round(goal.budget.maxRuntimeMs / 60_000)}m`,
-    ]
-        .filter((value) => value !== undefined)
-        .join(" · ");
+export function formatElapsed(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1_000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${seconds % 60}s`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${minutes % 60}m`;
+}
+export function formatGoalStatus(goal, now = Date.now()) {
+    const end = goal.status === "active" ? now : Date.parse(goal.updatedAt);
+    return `🎯 ${goalDisplayName(goal)} ${formatElapsed(end - Date.parse(goal.createdAt))}`;
+}
+export function formatGoalDashboard(goal, claim, checkpoints = []) {
     const lines = [
         `Goal · ${goal.status} · v${goal.version}`,
+        goalDisplayName(goal),
         displayGoalText(goal.objective, 120),
-        usage,
     ];
+    const limits = [
+        goal.budget.maxIterations === undefined
+            ? undefined
+            : `Turns ${goal.usage.iterations}/${goal.budget.maxIterations}`,
+        goal.budget.maxRuntimeMs === undefined
+            ? undefined
+            : `Runtime ${Math.round(goal.budget.maxRuntimeMs / 60_000)}m`,
+    ].filter((value) => value !== undefined);
+    lines.push(limits.length ? `Limits: ${limits.join(" · ")}` : "Limits: off");
+    if (goal.snoozedUntil)
+        lines.push(`Snoozed until ${goal.snoozedUntil}`);
     if (goal.lastEvaluation) {
         lines.push(`Last ${goal.lastEvaluation.outcome.toUpperCase()}: ${displayGoalText(goal.lastEvaluation.reason, 100)}`);
     }
@@ -37,6 +50,11 @@ 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 budget turns=<n> tokens=<n> · pause · resume · complete · clear · hide");
+    for (const checkpoint of checkpoints.slice(0, 3)) {
+        lines.push(`Checkpoint ${checkpoint.createdAt}: ${displayGoalText(checkpoint.summary, 90)}`);
+    }
+    if (checkpoints.length > 3)
+        lines.push(`… and ${checkpoints.length - 3} more checkpoints`);
+    lines.push("/goal update · snooze <duration> · close · hide");
     return lines;
 }

package/dist/domain.d.ts

@@ -1,6 +1,7 @@
 export type GoalStatus = "active" | "paused" | "blocked" | "budget_limited" | "complete";
 export interface GoalBudget {
-    maxIterations: number;
+    maxIterations?: number;
+    /** @deprecated Token usage is provider-reported and is retained for stored-goal compatibility only. */
     maxTokens?: number;
     maxRuntimeMs?: number;
 }
@@ -10,8 +11,21 @@ export interface GoalUsage {
 }
 export interface GoalBudgetUpdate {
     maxIterations?: number;
+    maxRuntimeMs?: number;
+    disabled?: boolean;
+    /** @deprecated Retained for compatibility with previously stored goals. */
     maxTokens?: number;
 }
+export interface GoalCheckpoint {
+    id: string;
+    scopeId: string;
+    goalId: string;
+    summary: string;
+    evidence?: string;
+    nextStep?: string;
+    blocker?: string;
+    createdAt: string;
+}
 export interface GoalEvaluationRecord {
     id: string;
     outcome: GoalEvaluation["outcome"];
@@ -21,9 +35,12 @@ export interface GoalEvaluationRecord {
 export interface AgentGoal {
     id: string;
     scopeId: string;
+    /** Legacy goals derive their display name from the objective until first edited. */
+    name?: string;
     objective: string;
     status: GoalStatus;
     blockedReason?: string;
+    snoozedUntil?: string;
     budget: GoalBudget;
     usage: GoalUsage;
     lastSettledAt?: string;
@@ -91,6 +108,8 @@ export interface GoalStorage {
     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>;
@@ -152,6 +171,20 @@ export type GoalEvent = {
     type: "goal.budget_changed";
     goal: AgentGoal;
     previousBudget: GoalBudget;
+} | {
+    type: "goal.updated";
+    goal: AgentGoal;
+} | {
+    type: "goal.checkpoint_added";
+    goal: AgentGoal;
+    checkpoint: GoalCheckpoint;
+} | {
+    type: "goal.snoozed";
+    goal: AgentGoal;
+    snoozedUntil: string;
+} | {
+    type: "goal.snooze_expired";
+    goal: AgentGoal;
 } | {
     type: "goal.evaluated";
     goal: AgentGoal;

package/dist/goal-window.d.ts

@@ -1,11 +1,29 @@
 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 GoalWindowLifecycleAction = "pause" | "resume" | "complete" | "clear" | "close";
-export type GoalWindowAction = GoalWindowLifecycleAction | {
+import type { AgentGoal, GoalCheckpoint, GoalContinuationClaim } from "./domain.js";
+export type GoalWindowAction = "close" | "closeGoal"
+/** @deprecated Parsed only for compatibility with older integrations; not exposed in the UI. */
+ | "pause"
+/** @deprecated Parsed only for compatibility with older integrations; not exposed in the UI. */
+ | "resume" | {
+    type: "create";
+    name: string;
+    objective: string;
+    maxIterations?: number;
+    maxRuntimeMs?: number;
+} | {
+    type: "edit";
+    name?: string;
+    objective?: string;
+} | {
     type: "budget";
-    maxIterations: number;
+    maxIterations?: number;
+    maxRuntimeMs?: number;
     maxTokens?: number;
+    disabled?: boolean;
+} | {
+    type: "snooze";
+    durationMs: number;
 };
 export declare class GoalWindow implements Component {
     private readonly goal;
@@ -15,14 +33,33 @@ export declare class GoalWindow implements Component {
     private readonly requestRender;
     private readonly now;
     private readonly actionError?;
-    private pendingConfirmation;
+    private readonly checkpoints;
+    private mode;
+    private textField;
+    private name;
+    private objective;
+    private initialName;
+    private initialObjective;
     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);
+    private budgetRuntime;
+    private snoozeDuration;
+    private inputError;
+    private confirmClose;
+    private selectedCheckpoint;
+    private checkpointOffset;
+    private checkpointLineCount;
+    private refreshTimer;
+    constructor(goal: AgentGoal | undefined, claim: GoalContinuationClaim | undefined, theme: Theme, onAction: (action: GoalWindowAction) => void, requestRender?: () => void, now?: () => number, actionError?: string | undefined, checkpoints?: GoalCheckpoint[], initialMode?: "details" | "edit");
     handleInput(data: string): void;
+    private openTextForm;
+    private handleTextForm;
+    private openBudgetForm;
+    private handleBudgetForm;
+    private handleSnoozeForm;
     render(width: number): string[];
+    private finish;
     invalidate(): void;
+    dispose(): void;
 }
+export declare function parseDuration(value: string): number | undefined;