pi-better-goal 0.8.3 → 0.9.0

package/README.md

@@ -44,7 +44,7 @@ metadata:
   workflow-role: coordinator
 ```
 
-Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator, preserving its objective and incomplete status. Reinvoke the skill explicitly before `/goal resume`; automatic continuation cannot reacquire ownership. Unrelated ordinary Goals are unchanged. Completing an active goal also releases ownership.
+Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner. When the workflow is done, complete the goal (`update_goal`), which also releases ownership. When it hands back unfinished work, call `release_workflow`, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator as a handback, preserving its objective and incomplete status. Resuming that Goal (`/goal resume`, `alt+g`, or, with conversational resume on, the user's go-ahead such as "continue") rebinds the coordinator it was created with, provided the skill is still registered at its original source; automatic continuation and synthetic input never reacquire ownership. Unrelated ordinary Goals are unchanged.
 
 A skill that is only an alias of a coordinator declares the target instead of a role:
 
@@ -55,6 +55,8 @@ metadata:
 
 Invoking the alias (`/skill:resolve-issues`, or `/goal /skill:resolve-issues task`) records the target coordinator, with the target's registered path, as the workflow owner, so its task plan, continuation instructions, and plan tools behave exactly as if the target had been invoked. The target must be a registered `workflow-role: coordinator` skill; an unregistered target, a non-coordinator target, or a chain of aliases is refused with a notice.
 
+After every successful context compaction (Pi's `session_compact` event) while a coordinator owns the session, the goal extension re-injects the skill so the model sees it before its next step; the compaction summary keeps run state but not the skill's rules, and the summary itself is left unchanged. If the skill directory ships `scripts/rehydrate.mjs` (checked first) or `rehydrate.mjs`, it runs as `node <script> --cwd <session cwd>` (no shell, 10-second timeout, stderr ignored) and its trimmed stdout becomes the message; empty output injects nothing, so the script decides whether a run is in progress. Without a script, or when it fails or times out, the message is: "Your context was just compacted while you coordinate the `<name>` workflow. Before your next step, read `<SKILL.md path>` in full, with no line limit." The message is a `workflow-rehydrate` custom message: inside a running agent loop (or before an overflow retry) it steers the next model call; otherwise it is appended without starting a turn.
+
 When `pi-better-plan` is installed, it defers its prompt, checklist, and `update_plan` tool to a skill-owned task plan. Skills without this metadata retain normal goal and plan behavior. The skill itself owns its planning format and worker policy; the harness does not enumerate skills or impose a shared workflow schema. The former `pi-better-plan-workflow: coordinator` metadata remains supported for installed skills.
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/src/goal-state.ts

@@ -66,7 +66,7 @@ function isGoalStatus(value: unknown): value is GoalStatus {
 }
 
 function isPauseReason(value: unknown): value is GoalPauseReason {
-  return value === "interrupt" || value === "permission-blocker";
+  return value === "interrupt" || value === "permission-blocker" || value === "handback";
 }
 
 function isGoalLike(value: unknown): value is GoalLike {

package/src/index.ts

@@ -40,6 +40,7 @@ import {
 import { createRenderScheduler } from "./shared-render-scheduler.js";
 import { collectSubagentActivity } from "./subagents.js";
 import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
+import { workflowRehydrateMessage, WORKFLOW_REHYDRATE_MESSAGE_TYPE } from "./rehydrate.js";
 import {
   EVENT_ACTIVITY,
   EVENT_READY,
@@ -87,7 +88,8 @@ const GOAL_RESUME_RULE =
 
 /** True when the agent may resume this goal with `goal_resume`. */
 export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
-  return conversationalResume && goal?.status === "paused" && goal.pauseReason === "interrupt";
+  return conversationalResume && goal?.status === "paused" &&
+    (goal.pauseReason === "interrupt" || goal.pauseReason === "handback");
 }
 
 /** Footer status for a paused goal, telling the user how to resume it. */
@@ -98,7 +100,9 @@ export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true
 
 function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
   return [
-    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    goal.pauseReason === "handback"
+      ? `Pi Better Goal is paused because its workflow handed back unfinished work for the user's answer. Goal: ${goal.objective}`
+      : `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
     "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
     conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
@@ -309,6 +313,8 @@ export default function (pi: ExtensionAPI): void {
   let snapshotSequence = 0;
   let lastAppliedSnapshotSequence = 0;
   let foregroundRunning = false;
+  /** True between agent_start and agent_end: the agent loop will call the model again without a new prompt. */
+  let agentLoopActive = false;
   let pollTimer: ReturnType<typeof setInterval> | undefined;
   let collecting = false;
   let collectionPending = false;
@@ -456,15 +462,21 @@ export default function (pi: ExtensionAPI): void {
       return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
     }
     if (goal.command?.source === "skill") {
-      const owner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
-      const activeOwner = getWorkflow(ctx);
-      if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) {
-        return `Reinvoke /${goal.command.name} before resuming its workflow goal.`;
+      try {
+        goalWorkflowOwner(goal);
+      } catch (error) {
+        return `Cannot resume: ${error instanceof Error ? error.message : String(error)} Reinvoke /${goal.command.name}.`;
       }
     }
     return null;
   };
 
+  /** The workflow a skill-bound goal owns, re-resolved from its registered skill; null for other goals. */
+  const goalWorkflowOwner = (goal: GoalSnapshot): ReturnType<typeof currentWorkflowOwner> =>
+    goal.command?.source === "skill"
+      ? workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath)
+      : null;
+
   /**
    * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
    * reactivate a paused goal or reopen an active no-progress hold.
@@ -498,6 +510,11 @@ export default function (pi: ExtensionAPI): void {
       }
       pi.appendEntry(EXTENSION_NAME, permissionRecord(current.goalId, "permission-release"));
     }
+    // Resuming a skill-bound goal is explicit re-entry into its workflow: rebind the owner the
+    // goal was created with (released by a handback) before the continuation runs.
+    const owner = goalWorkflowOwner(current);
+    const activeOwner = getWorkflow(ctx);
+    if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) recordWorkflow(owner);
     setGoal(goal, ctx, source);
     queueGoalContinuation(goal, ctx);
     return { ok: true, goal };
@@ -1049,8 +1066,8 @@ export default function (pi: ExtensionAPI): void {
     name: GOAL_RESUME_TOOL,
     label: "Resume Goal",
     description:
-      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
-    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+      "Resume the goal the user paused with escape, or one its workflow handed back, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused or handed-back goal, only on the user's clear go-ahead.",
     parameters: Type.Object({
       reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
     }),
@@ -1115,7 +1132,7 @@ export default function (pi: ExtensionAPI): void {
   pi.registerTool({
     name: "release_workflow",
     label: "Release Workflow",
-    description: "Release the active skill-owned workflow after its final handoff and completion audit. Its bound active Goal pauses; explicitly reinvoke the skill before resuming that Goal.",
+    description: "Release the active skill-owned workflow when it hands back unfinished work (a blocked unit awaiting the human). Its bound active Goal pauses; /goal resume rebinds the workflow. When the workflow is done, call update_goal complete instead, which also releases it.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = getWorkflow(ctx);
@@ -1125,13 +1142,13 @@ export default function (pi: ExtensionAPI): void {
       if (goal?.status === "active" && goal.command?.source === "skill") {
         const boundOwner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
         if (boundOwner?.name === owner.name && boundOwner.path === owner.path) {
-          setGoal(goalWithStatus(goal, "paused"), ctx, "tool");
+          setGoal(goalWithStatus(goal, "paused", undefined, "handback"), ctx, "tool");
           resumeCommand = goal.command.name;
         }
       }
       recordWorkflow(null);
       return {
-        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete. Reinvoke /${resumeCommand} before /goal resume.` : ""}` }],
+        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete; the user's go-ahead or /goal resume rebinds /${resumeCommand}.` : ""}` }],
         details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
       };
     },
@@ -1172,6 +1189,7 @@ export default function (pi: ExtensionAPI): void {
     collectionPending = false;
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    agentLoopActive = false;
     try {
       preferences = readGoalPreferences();
     } catch (error) {
@@ -1261,7 +1279,7 @@ export default function (pi: ExtensionAPI): void {
     if (permissionPrompt && goal?.status === "paused") {
       return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
     }
-    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && goal.pauseReason === "interrupt"
+    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && (goal.pauseReason === "interrupt" || goal.pauseReason === "handback")
       ? pausedGoalPrompt(goal, preferences.conversationalResume) : "");
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
@@ -1320,6 +1338,7 @@ export default function (pi: ExtensionAPI): void {
     agentGeneration = executionGeneration;
     currentCtx = ctx;
     foregroundRunning = true;
+    agentLoopActive = true;
     clearIdleContinuation();
     continuationQueuedFor = null;
     lastAgentEvidence = null;
@@ -1341,6 +1360,7 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("agent_end", async (event, ctx) => {
+    agentLoopActive = false;
     lastAgentEvidence = agentGeneration === executionGeneration ? continuationEvidence(event.messages) : null;
     // Only an observed editor Escape with pause disabled exempts this abort.
     // Unknown interrupt sources retain the safety fallback on every host.
@@ -1469,6 +1489,29 @@ export default function (pi: ExtensionAPI): void {
     scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
   });
 
+  // A compaction summary keeps run state but drops the coordinator skill's rules. Re-inject them
+  // (or the skill's own rehydrate script output) so the model sees them before its next step.
+  pi.on("session_compact", async (event, ctx) => {
+    const owner = getWorkflow(ctx);
+    if (!owner) return;
+    const content = await workflowRehydrateMessage(owner, ctx.cwd);
+    if (!content) return;
+    // Inside a running agent loop (mid-run compaction or an overflow retry) steer it into the next
+    // model call. Otherwise append it without triggering a turn: the next turn, whatever starts it,
+    // sees it. Steering after the loop ended would start an unprompted continuation.
+    const options = agentLoopActive || event.willRetry ? { deliverAs: "steer" as const } : { triggerTurn: false };
+    try {
+      pi.sendMessage({
+        customType: WORKFLOW_REHYDRATE_MESSAGE_TYPE,
+        content,
+        display: true,
+        details: { workflow: owner.name, path: owner.path, reason: event.reason },
+      }, options);
+    } catch {
+      // Best effort: never fail or block the session over a rehydrate notice.
+    }
+  });
+
   pi.on("session_shutdown", async (_event, ctx) => {
     if (typeof unsubscribeSettingsRequest === "function") unsubscribeSettingsRequest();
 

package/src/rehydrate.ts

@@ -0,0 +1,57 @@
+import { execFile } from "node:child_process";
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { WorkflowOwner } from "./workflow.js";
+
+export const WORKFLOW_REHYDRATE_MESSAGE_TYPE = "workflow-rehydrate";
+export const REHYDRATE_TIMEOUT_MS = 10_000;
+
+/** Script locations a coordinator skill may ship, in precedence order, relative to its SKILL.md directory. */
+const REHYDRATE_SCRIPTS = [join("scripts", "rehydrate.mjs"), "rehydrate.mjs"];
+
+export function rehydrateFallbackMessage(owner: WorkflowOwner): string {
+  return `Your context was just compacted while you coordinate the ${owner.name} workflow. ` +
+    `Before your next step, read ${owner.path} in full, with no line limit.`;
+}
+
+/** The first rehydrate script the owner's skill ships, or undefined when it ships none. */
+export function findRehydrateScript(owner: WorkflowOwner): string | undefined {
+  const skillDir = dirname(owner.path);
+  for (const relative of REHYDRATE_SCRIPTS) {
+    const candidate = join(skillDir, relative);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // Missing or unreadable: try the next location.
+    }
+  }
+  return undefined;
+}
+
+function runScript(script: string, cwd: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile("node", [script, "--cwd", cwd], { cwd, timeout: timeoutMs, encoding: "utf8", windowsHide: true },
+      (error, stdout) => (error ? reject(error) : resolve(stdout)));
+  });
+}
+
+/**
+ * The message to inject after a compaction while `owner` coordinates the session, or null for none.
+ * A skill's rehydrate script decides the text (empty output means no run is in progress); without
+ * a script, or when it fails or times out, the model is told to re-read SKILL.md. Never throws.
+ */
+export async function workflowRehydrateMessage(
+  owner: WorkflowOwner,
+  cwd: string,
+  options: { timeoutMs?: number } = {},
+): Promise<string | null> {
+  try {
+    const script = findRehydrateScript(owner);
+    if (!script) return rehydrateFallbackMessage(owner);
+    const stdout = (await runScript(script, cwd, options.timeoutMs ?? REHYDRATE_TIMEOUT_MS)).trim();
+    return stdout.length > 0 ? stdout : null;
+  } catch {
+    return rehydrateFallbackMessage(owner);
+  }
+}

package/src/types.ts

@@ -75,7 +75,8 @@ export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
  * requires those human controls, and releases just one same-scope retry while
  * keeping its separate blocker/release history.
  */
-export type GoalPauseReason = "interrupt" | "permission-blocker";
+/** Why a goal paused: escape, a permission hold, or a workflow handing back unfinished work for the user's answer. */
+export type GoalPauseReason = "interrupt" | "permission-blocker" | "handback";
 
 export interface GoalUsage {
   tokensUsed: number;