@pinet/agent-goal 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @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.
+
+The worker runs normally and stops when its current pass is finished. Ordinary settled runs continue automatically without spending a second model call. Independent evaluation runs only when the worker requests `complete` or `blocked`, at an optional periodic checkpoint, or on the final budget turn. Completed, blocked, budget-limited, paused, and cleared goals do not continue.
+
+## Install
+
+```bash
+pi install npm:@pinet/agent-goal
+```
+
+For local development:
+
+```bash
+pi -e ./agent-goal/index.ts
+```
+
+## Commands and UI
+
+```text
+/goal <objective>  Create and immediately start a goal
+/goal              Inspect this session's goal
+/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 persistent goal dashboard
+/goal show         Show the persistent goal dashboard
+```
+
+Pi's footer shows the status and budget usage. A compact widget below the editor shows the objective, turns, tokens, last evaluator decision, continuation state, and available commands. `/goal` remains a textual fallback 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:
+
+- `create_goal` — create its own bounded, user-aligned durable goal
+- `get_goal` — inspect the current objective, status, and budget
+- `update_goal` — submit `complete` or `blocked` as a candidate for independent verification
+
+An agent-created goal cannot replace an existing goal. Its first automatic continuation starts after the creating run settles, so work performed before goal creation is not incorrectly charged to the goal budget.
+
+## Budgets
+
+Goals default to 25 settled iterations. Optional token and runtime limits are supported:
+
+```text
+PI_AGENT_GOAL_MAX_ITERATIONS=25
+PI_AGENT_GOAL_MAX_TOKENS=200000
+PI_AGENT_GOAL_MAX_RUNTIME_MS=14400000
+PI_AGENT_GOAL_EVALUATION_INTERVAL=0
+```
+
+Iteration and runtime limits are always reliable. Token accounting uses usage reported by Pi providers. `PI_AGENT_GOAL_EVALUATION_INTERVAL` defaults to `0`, which disables periodic checkpoints; set it to a positive number to evaluate every N settled runs. The evaluator always reviews the final allowed turn so a completed goal is not incorrectly classified as budget-limited; only another continuation is prevented.
+
+## Persistence and recovery
+
+The default adapter stores goals and continuation claims in SQLite at:
+
+```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.
+
+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. Started claims schedule an expiry wake, remain until the next agent run begins, and recover safely after interruption or session resume. Evaluator and 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.
+
+## 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`.
+
+```ts
+import { registerAgentGoal } from "@pinet/agent-goal";
+
+registerAgentGoal(pi, {
+  storage: myStorage,
+  evaluator: myEvaluator,
+  continuation: myAtomicContinuationAdapter,
+  eventSink: myEventSink,
+  defaultBudget: { maxIterations: 20, maxTokens: 150_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.
+
+## Worker-directed evaluation
+
+The extension registers model-visible `create_goal`, `get_goal`, and `update_goal` tools. The worker can establish its own user-aligned goal, inspect it, and call `update_goal` with `complete` only after verifying the full objective or with `blocked` for a genuine external impasse. `update_goal` records a terminal candidate rather than mutating goal state directly. When the run reaches `agent_settled`, the independent evaluator verifies that candidate. If the worker stops without calling `update_goal`, the runtime accounts the run and continues the same session without an evaluator call.
+
+Evaluation is also forced at configured periodic checkpoints and on the final budget turn. 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.
+
+Continuation prompts explicitly treat the objective as user-provided task data, never as higher-priority instructions.

package/dist/dashboard.d.ts

@@ -0,0 +1,3 @@
+import type { AgentGoal, GoalContinuationClaim } from "./domain.js";
+export declare function formatGoalStatus(goal: AgentGoal): string;
+export declare function formatGoalDashboard(goal: AgentGoal, claim?: GoalContinuationClaim): string[];

package/dist/dashboard.js

@@ -0,0 +1,42 @@
+function displayText(value, maxLength) {
+    const normalized = value
+        .replaceAll("\n", " ")
+        .replaceAll("\r", " ")
+        .replaceAll("\u001b", "")
+        .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 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(" · ");
+    const lines = [
+        `Goal · ${goal.status} · v${goal.version}`,
+        displayText(goal.objective, 120),
+        usage,
+    ];
+    if (goal.lastEvaluation) {
+        lines.push(`Last ${goal.lastEvaluation.outcome.toUpperCase()}: ${displayText(goal.lastEvaluation.reason, 100)}`);
+    }
+    if (goal.blockedReason)
+        lines.push(`Reason: ${displayText(goal.blockedReason, 100)}`);
+    if (claim)
+        lines.push(`Continuation: ${claim.state} · attempt ${claim.attempt}`);
+    lines.push("/goal pause · resume · complete · clear · hide");
+    return lines;
+}

package/dist/domain.d.ts

@@ -0,0 +1,199 @@
+export type GoalStatus = "active" | "paused" | "blocked" | "budget_limited" | "complete";
+export interface GoalBudget {
+    maxIterations: number;
+    maxTokens?: number;
+    maxRuntimeMs?: number;
+}
+export interface GoalUsage {
+    iterations: number;
+    tokens: number;
+}
+export interface GoalEvaluationRecord {
+    id: string;
+    outcome: GoalEvaluation["outcome"];
+    reason: string;
+    at: string;
+}
+export interface AgentGoal {
+    id: string;
+    scopeId: string;
+    objective: string;
+    status: GoalStatus;
+    blockedReason?: string;
+    budget: GoalBudget;
+    usage: GoalUsage;
+    lastSettledAt?: string;
+    lastEvaluation?: GoalEvaluationRecord;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export type GoalEvaluation = {
+    outcome: "continue";
+    reason: string;
+} | {
+    outcome: "complete";
+    reason: string;
+} | {
+    outcome: "blocked";
+    reason: string;
+};
+export interface GoalTerminalCandidate {
+    outcome: "complete" | "blocked";
+    reason: string;
+}
+export interface GoalTerminalCandidateRecord extends GoalTerminalCandidate {
+    scopeId: string;
+    goalId: string;
+    goalVersion: number;
+    candidateId: string;
+    createdAt: string;
+}
+export interface GoalProgress {
+    latestOutput: string;
+    tokenDelta?: number;
+    terminalCandidate?: GoalTerminalCandidate;
+}
+export type GoalContinuationClaimState = "claimed" | "deferred" | "started";
+export interface GoalPendingEvaluation {
+    scopeId: string;
+    goalId: string;
+    goalVersion: number;
+    evaluationId: string;
+    iterationsDelta: number;
+    progress: GoalProgress;
+    attempt: number;
+    availableAt: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalContinuationClaim {
+    scopeId: string;
+    goalId: string;
+    goalVersion: number;
+    claimId: string;
+    state: GoalContinuationClaimState;
+    reason: string;
+    attempt: number;
+    availableAt: string;
+    expiresAt: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GoalStorage {
+    get(scopeId: string): Promise<AgentGoal | undefined>;
+    create(goal: AgentGoal): Promise<void>;
+    replace(goal: AgentGoal, expectedVersion: number): Promise<boolean>;
+    delete(scopeId: string, expectedVersion: number): Promise<boolean>;
+    getPendingEvaluation(scopeId: string): Promise<GoalPendingEvaluation | undefined>;
+    appendPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;
+    putPendingEvaluation(pending: GoalPendingEvaluation): Promise<boolean>;
+    replacePendingEvaluation(pending: GoalPendingEvaluation, expectedEvaluationId: string): Promise<boolean>;
+    deletePendingEvaluation(scopeId: string, expectedEvaluationId: string): Promise<boolean>;
+    commitEvaluation(goal: AgentGoal, expectedGoalVersion: number, expectedEvaluationId: string): Promise<boolean>;
+    getTerminalCandidate(scopeId: string): Promise<GoalTerminalCandidateRecord | undefined>;
+    putTerminalCandidate(candidate: GoalTerminalCandidateRecord): Promise<boolean>;
+    deleteTerminalCandidate(scopeId: string, expectedCandidateId: string): Promise<boolean>;
+    getContinuationClaim(scopeId: string): Promise<GoalContinuationClaim | undefined>;
+    createContinuationClaim(claim: GoalContinuationClaim): Promise<boolean>;
+    replaceContinuationClaim(claim: GoalContinuationClaim, expectedClaimId: string): Promise<boolean>;
+    deleteContinuationClaim(scopeId: string, expectedClaimId: string): Promise<boolean>;
+    close(): void;
+}
+export interface GoalEvaluator {
+    evaluate(goal: AgentGoal, progress: GoalProgress): Promise<GoalEvaluation>;
+}
+export type GoalContinuationResult = {
+    status: "started";
+    continuationId?: string;
+} | {
+    status: "busy" | "unavailable" | "rejected";
+    reason: string;
+    retryAfterMs?: number;
+};
+export interface GoalContinuationRequest {
+    claimId: string;
+    idempotencyKey: string;
+    expectedGoalVersion: number;
+    reason: string;
+}
+export interface GoalContinuation {
+    continueIfIdle(goal: AgentGoal, request: GoalContinuationRequest): Promise<GoalContinuationResult>;
+}
+export interface GoalRetryPolicy {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+export interface GoalWakeScheduler {
+    schedule(scopeId: string, wakeAt: string, wake: () => void): void;
+    cancel(scopeId: string): void;
+    close(): void;
+}
+export type GoalEvent = {
+    type: "goal.created";
+    goal: AgentGoal;
+} | {
+    type: "goal.status_changed";
+    goal: AgentGoal;
+    previousStatus: GoalStatus;
+} | {
+    type: "goal.progress_accounted";
+    goal: AgentGoal;
+    tokenDelta: number;
+} | {
+    type: "goal.evaluated";
+    goal: AgentGoal;
+    evaluation: GoalEvaluation;
+} | {
+    type: "goal.auto_continued";
+    goal: AgentGoal;
+} | {
+    type: "goal.terminal_candidate_requested";
+    goal: AgentGoal;
+    candidate: GoalTerminalCandidateRecord;
+} | {
+    type: "goal.continuation_claimed";
+    goal: AgentGoal;
+    claim: GoalContinuationClaim;
+} | {
+    type: "goal.continuation_started";
+    goal: AgentGoal;
+    claim: GoalContinuationClaim;
+} | {
+    type: "goal.continuation_deferred";
+    goal: AgentGoal;
+    claim: GoalContinuationClaim;
+} | {
+    type: "goal.retry_scheduled";
+    scopeId: string;
+    goalId: string;
+    operation: "evaluator" | "continuation";
+    attempt: number;
+    availableAt: string;
+    error: string;
+    claimId?: string;
+} | {
+    type: "goal.retry_exhausted";
+    scopeId: string;
+    goalId: string;
+    operation: "evaluator" | "continuation";
+    attempt: number;
+    error: string;
+    claimId?: string;
+} | {
+    type: "goal.recovered";
+    goal: AgentGoal;
+} | {
+    type: "goal.cleared";
+    goal: AgentGoal;
+} | {
+    type: "goal.error";
+    operation: string;
+    error: string;
+};
+export interface GoalEventSink {
+    record(event: GoalEvent): Promise<void> | void;
+}

package/dist/domain.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+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 { formatGoalDashboard, formatGoalStatus } from "./dashboard.js";
+export { MemoryGoalStorage } from "./memory-storage.js";
+export { parseGoalEvaluation, PiGoalEvaluator } from "./pi-evaluator.js";
+export { countGoalProgressTokens, formatGoalProgress, type GoalProgressMessage, } from "./progress.js";
+export { GoalRuntime, type GoalRuntimeOptions } from "./runtime.js";
+export { SqliteGoalStorage } from "./sqlite-storage.js";
+export { TimerGoalWakeScheduler } from "./wake-scheduler.js";
+export interface AgentGoalExtensionOptions {
+    storage?: GoalStorage;
+    evaluator?: GoalEvaluator;
+    continuation?: GoalContinuation;
+    eventSink?: GoalEventSink;
+    defaultBudget?: GoalBudget;
+    retryPolicy?: GoalRetryPolicy;
+    databasePath?: string;
+    evaluationInterval?: number;
+    wakeScheduler?: GoalWakeScheduler;
+}
+export declare function registerAgentGoal(pi: ExtensionAPI, options?: AgentGoalExtensionOptions): void;
+export default function agentGoal(pi: ExtensionAPI): void;