@astrosheep/pi-goal-next 0.1.8 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # pi-goal
 
-`pi-goal` (published by this manifest as `pi-goal-next`) is a Pi 0.85.1 extension that adds a long-running `/goal`. It follows the Codex Goal semantics: the same model that performs the work audits its own progress and declares `complete` or `blocked` with `update_goal`. There is no independent auditor or human approval step.
+`pi-goal` (published by this manifest as `pi-goal-next`) is a Pi 0.85.1 extension that adds a long-running `/goal`. It follows the Codex Goal semantics: the same model that performs the work audits its own progress and declares `complete`, `blocked`, or — at the user's explicit request — `paused` with `update_goal`. There is no independent auditor or human approval step.
 
 ## Installation
 
@@ -35,7 +35,7 @@ With no goal, or when the current goal is complete, `/goal <objective>` creates
 
 - `get_goal` returns the current snapshot plus `remainingBudget` and `elapsedSeconds`, or reports that no goal exists.
 - `create_goal` creates an active goal after an explicit request. It accepts `objective` and optional `token_budget` (a positive integer).
-- `update_goal` accepts only `complete` or `blocked` after the model's self-audit. `complete` is permitted from `active` and `budget_limited`, not `paused` or `blocked`; the host does not validate the declaration. On `complete` the result reports the final token usage.
+- `update_goal` accepts `complete`, `blocked`, or `paused` after the model's self-audit. `paused` is honored only at the user's explicit request (prompt-level rule; the host enforces only the state machine). `complete` is permitted from `active` and `budget_limited`, not `paused` or `blocked`; the host does not validate declarations. On `complete` the result reports the final token usage.
 
 The prompt text is copied byte-for-byte from Codex Goal (`continuation.md`, `budget_limit.md`, `objective_updated.md`); the only deletion is Codex's `update_plan` "Progress visibility" paragraph, because Pi has no `update_plan` tool. Continuation prompts state the objective inside `<objective>` as user-provided data and carry the budget, evidence, fidelity, completion-audit, and blocked-audit rules. The three-consecutive-turn blocked audit is prompt-level guidance; the runtime does not enforce it.
 
@@ -70,7 +70,7 @@ The prompt text is copied byte-for-byte from Codex Goal (`continuation.md`, `bud
 
 ## Completion and blocking contract
 
-The model calls `update_goal` after auditing the current goal against the Codex completion audit carried in every continuation prompt. The host accepts `complete` and `blocked` at face value and performs no independent verification; the prompt is the only guard. `complete` may transition an `active` or `budget_limited` goal and reports final token usage; it is prohibited from `paused` and `blocked`. `blocked` is meant to follow three consecutive turns with the same blocker. `paused` is user-only (`/goal pause`). Runtime accounting may instead move an active goal to `budget_limited`; the model cannot declare that state, and the transition triggers one `budget_limit.md` steering message.
+The model calls `update_goal` after auditing the current goal against the Codex completion audit carried in every continuation prompt. The host accepts `complete` and `blocked` at face value and performs no independent verification; the prompt is the only guard. `paused` via the tool requires the user's explicit request and is otherwise indistinguishable from a user `/goal pause`. `complete` may transition an `active` or `budget_limited` goal and reports final token usage; it is prohibited from `paused` and `blocked`. `blocked` is meant to follow three consecutive turns with the same blocker. Runtime accounting may instead move an active goal to `budget_limited`; the model cannot declare that state, and the transition triggers one `budget_limit.md` steering message.
 
 Automatic continuation waits for a fresh normal assistant completion and for the entire Pi run to settle, including tools, retries, compaction, and queued input. Errors, cancellation (including cancellation after text finishes), and runs ending at a tool boundary do not trigger continuation or budget steering. Ordinary user input has no continuation attached; once the response to that input finishes normally, an active goal may continue.
 

package/docs/architecture.md

@@ -10,7 +10,7 @@ Pi 0.85.1 extension package adding a long-running `/goal`. Behavior follows Code
 
 `active | paused | blocked | budget_limited | complete`
 
-- Model's `update_goal` accepts only: `complete` | `blocked`. `complete` is permitted from `active` and `budget_limited`, but not from `paused` or `blocked`. The model self-audits; the host does not validate the declaration.
+- Model's `update_goal` accepts only: `complete` | `blocked` | `paused` (paused at the user's explicit request, prompt-level only). `complete` is permitted from `active` and `budget_limited`, but not from `paused` or `blocked`. The model self-audits; the host does not validate the declaration.
 - `budget_limited` is set only by runtime/system paths (accounting).
 - `clear` is a journal entry `goal.cleared`; `fold()` yields null. Deletion is semantic.
 - One goal per session branch. `create_goal` refuses when an unfinished goal exists.
@@ -25,7 +25,7 @@ Pi 0.85.1 extension package adding a long-running `/goal`. Behavior follows Code
 | `accounting.ts` | usage attribution keyed by **message id** (assistant and toolResult separately), `settleTurn() → verdict: ok \| budget_limited`, `summary()` | triggering continuation, editing goal state directly (returns verdict; lifecycle commits it) |
 | `continuation.ts` | `generation` lease, `agent_settled` decision, commit-then-sendMessage, stale handling. The ONLY sender of continuation messages. | building UI, reading store, deciding acceptance |
 | `prompts.ts` | Pure: the three Codex-verbatim goal templates — `continuationPrompt(goal)`, `budgetLimitPrompt(goal)`, `objectiveUpdatedPrompt(goal)`; `escapeXmlText` applies to the objective only. | IO, model calls, host-side validation |
-| `tools.ts` | Codex-verbatim tool descriptions, TypeBox schema → `goalCommit.commit` → tool result. Three tools: get_goal / create_goal / update_goal. `update_goal` accepts only complete\|blocked and reports final usage on complete. | writing rules text, touching store/continuation |
+| `tools.ts` | Codex-verbatim tool descriptions, TypeBox schema → `goalCommit.commit` → tool result. Three tools: get_goal / create_goal / update_goal. `update_goal` accepts complete\|blocked\|paused and reports final usage on complete. | writing rules text, touching store/continuation |
 | `commands.ts` | `/goal` subcommands → goal-commit. | direct store access |
 | `lifecycle.ts` | Event ordering, live-message identities, run cancellation signal, and input/settlement fences. Session/branch/compaction policies plus budget-limit steering, see below. | holding Goal state |
 | `ui.ts` | status/widget text from `current()` + `accounting.summary()`. Read-only. | writes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-goal-next",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Persistent autonomous goals for pi, with Codex-verbatim goal semantics: continuation prompts, self-audited completion, budgets, and CAS-journaled state.",
   "type": "module",
   "files": [

package/src/goal.ts

@@ -67,8 +67,8 @@ export function transition(state: Goal | null, intent: Intent): Goal | null {
   }
   if (intent.type === "transition") {
     if (!statuses.includes(intent.to)) throw new GoalError("invalid", "unknown status");
-    if (intent.to === "paused" && !intent.userRequest?.trim()) throw new GoalError("forbidden", "paused requires user request evidence");
-    if (intent.by === "agent" && !["complete", "blocked"].includes(intent.to)) throw new GoalError("forbidden", "agent cannot set this status");
+    if (intent.to === "paused" && intent.by === "user" && !intent.userRequest?.trim()) throw new GoalError("forbidden", "paused requires user request evidence");
+    if (intent.by === "agent" && !["complete", "blocked", "paused"].includes(intent.to)) throw new GoalError("forbidden", "agent cannot set this status");
     if (intent.by === "agent" && intent.to === "complete" && !["active", "budget_limited"].includes(state.status)) throw new GoalError("forbidden", "agent can complete only an active or budget-limited goal");
     const reset = intent.resetContinuations === true;
     if (reset && (intent.by !== "user" || intent.to !== "active")) throw new GoalError("forbidden", "only user resume can reset continuations");

package/src/tools.ts

@@ -9,7 +9,7 @@ export type PiLike = { registerTool(tool: any): void };
 
 const text = (value: unknown) => typeof value === "string" ? value : JSON.stringify(value);
 const tokensUsed = (goal: Goal) => goal.usage.input + goal.usage.output + goal.usage.cacheRead + goal.usage.cacheWrite;
-function result(message: string, terminate = false): any { return { content: [{ type: "text", text: message }], ...(terminate ? { terminate: true } : {}) }; }
+function result(message: string): any { return { content: [{ type: "text", text: message }] }; }
 function commitMessage(r: CommitResult): string {
   if (r.kind === "conflict") return "Goal update conflict: goal changed; retry with the current goal.";
   if (r.kind === "error") return `Goal update failed: ${r.error instanceof Error ? r.error.message : text(r.error)}`;
@@ -48,20 +48,21 @@ export function registerGoalTools(piLike: PiLike, deps: GoalToolDeps): void {
   });
   piLike.registerTool({
     name: "update_goal", label: "Update goal",
-    description: "Update the existing goal.\nUse this tool only to mark the goal achieved or genuinely blocked.\nSet status to `complete` only when the objective has actually been achieved and no required work remains.\nSet status to `blocked` only when the same blocking condition has repeated for at least three consecutive goal turns, counting the original/user-triggered turn and any automatic continuations, and the agent cannot make meaningful progress without user input or an external-state change.\nIf the user resumes a goal that was previously marked `blocked`, treat the resumed run as a fresh blocked audit. If the same blocking condition then repeats for at least three consecutive resumed goal turns, set status to `blocked` again.\nOnce the blocked threshold is satisfied, do not keep reporting that you are still blocked while leaving the goal active; set status to `blocked`.\nDo not use `blocked` merely because the work is hard, slow, uncertain, incomplete, or would benefit from clarification.\nDo not mark a goal complete merely because its budget is nearly exhausted or because you are stopping work.\nYou cannot use this tool to pause, resume, budget-limit, or usage-limit a goal; those status changes are controlled by the user or system.\nWhen marking a budgeted goal achieved with status `complete`, report the final token usage from the tool result to the user.",
-    parameters: Type.Object({ status: Type.Union([Type.Literal("complete"), Type.Literal("blocked")], { description: "Required. Set to `complete` only when the objective is achieved and no required work remains. Set to `blocked` only after the same blocking condition has recurred for at least three consecutive goal turns and the agent is at an impasse. After a previously blocked goal is resumed, the resumed run starts a fresh blocked audit." }) }),
+    description: "Update the existing goal.\nSet status to `paused` only at the user's explicit request to pause this goal, never on your own initiative. Ask if unclear; a later resume revokes that request. Report the returned status and stop goal work. Budget limits take precedence over pausing.\nSet status to `complete` only when the objective has actually been achieved and no required work remains.\nSet status to `blocked` only when the same blocking condition has repeated for at least three consecutive goal turns, counting the original/user-triggered turn and any automatic continuations, and the agent cannot make meaningful progress without user input or an external-state change.\nIf the user resumes a goal that was previously marked `blocked`, treat the resumed run as a fresh blocked audit. If the same blocking condition then repeats for at least three consecutive resumed goal turns, set status to `blocked` again.\nOnce the blocked threshold is satisfied, do not keep reporting that you are still blocked while leaving the goal active; set status to `blocked`.\nDo not use `blocked` merely because the work is hard, slow, uncertain, incomplete, or would benefit from clarification.\nDo not mark a goal complete merely because its budget is nearly exhausted or because you are stopping work.\nYou cannot use this tool to resume, budget-limit, or usage-limit a goal; those status changes are controlled by the user or system.\nWhen marking a budgeted goal achieved with status `complete`, report the final token usage from the tool result to the user.",
+    parameters: Type.Object({ status: Type.Union([Type.Literal("complete"), Type.Literal("blocked"), Type.Literal("paused")], { description: "Required. `paused` requires an explicit user request. Set to `complete` only when the objective is achieved and no required work remains. Set to `blocked` only after the same blocking condition has recurred for at least three consecutive goal turns and the agent is at an impasse. After a previously blocked goal is resumed, the resumed run starts a fresh blocked audit." }) }),
     execute: async (_id: string, params: any) => {
       const status = params?.status as Status;
-      const expected = status === "complete" || status === "blocked";
+      const expected = status === "complete" || status === "blocked" || status === "paused";
       const current = goalCommit.current();
       if (!current) return result("Goal update failed: no goal exists.");
       if (!expected) return result(`Invalid status: ${text(params?.status)} is not complete or blocked.`);
       const r = await goalCommit.commit({ type: "transition", to: status, by: "agent" }, current.revision);
-      if (r.kind !== "ok") return result(commitMessage(r), expected);
-      if (status === "blocked") return result("Goal marked blocked.", true);
+      if (r.kind !== "ok") return result(commitMessage(r));
+      if (status === "blocked") return result("Goal marked blocked.");
+      if (status === "paused") return result("Goal marked paused.");
       const u = (r.snapshot?.goal ?? current.goal).usage;
       const total = u.input + u.output + u.cacheRead + u.cacheWrite;
-      return result(`Goal marked complete. Final token usage: input=${u.input} output=${u.output} cacheRead=${u.cacheRead} cacheWrite=${u.cacheWrite} (total=${total}).`, true);
+      return result(`Goal marked complete. Final token usage: input=${u.input} output=${u.output} cacheRead=${u.cacheRead} cacheWrite=${u.cacheWrite} (total=${total}).`);
     }
   });
 }