pi-better-goal 0.4.0 → 0.4.1

package/README.md

@@ -13,7 +13,8 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal; paused goals are never poked.
+- `escape` pauses the active goal and your next message resumes it; `/goal pause` stays paused until `/goal resume`. Paused goals are never poked.
+- Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
 - A progress-aware follow-up loop that holds after repeated identical outcomes.
@@ -30,6 +31,15 @@ metadata:
 
 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 it manually). Completing an active goal also releases ownership.
 
+A skill that is only an alias of a coordinator declares the target instead of a role:
+
+```yaml
+metadata:
+  workflow-alias-of: rush-issues
+```
+
+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.
+
 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.4.0",
+  "version": "0.4.1",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/src/goal-state.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { GoalCommandBinding } from "./command-binding.js";
 
-import { EXTENSION_NAME, type GoalSnapshot, type GoalStatus } from "./types.js";
+import { EXTENSION_NAME, type GoalPauseReason, type GoalSnapshot, type GoalStatus } from "./types.js";
 
 const LEGACY_GOAL_ENTRY_TYPE = "pi-codex-goal";
 const MAX_OBJECTIVE_CHARS = 8000;
@@ -17,6 +17,7 @@ interface GoalLike {
   objective: string;
   command?: unknown;
   status: GoalStatus;
+  pauseReason?: unknown;
   tokenBudget?: number | null;
   usage?: { tokensUsed?: number; activeSeconds?: number };
   createdAt?: number;
@@ -64,6 +65,10 @@ function isGoalStatus(value: unknown): value is GoalStatus {
   return value === "active" || value === "paused" || value === "budgetLimited" || value === "complete";
 }
 
+function isPauseReason(value: unknown): value is GoalPauseReason {
+  return value === "interrupt";
+}
+
 function isGoalLike(value: unknown): value is GoalLike {
   if (!value || typeof value !== "object") {
     return false;
@@ -119,6 +124,7 @@ function normalizeGoal(goal: GoalLike): GoalSnapshot {
     objective: goal.objective,
     ...(isCommandBinding(goal.command) ? { command: goal.command } : {}),
     status: goal.status,
+    ...(goal.status === "paused" && isPauseReason(goal.pauseReason) ? { pauseReason: goal.pauseReason } : {}),
     tokenBudget: typeof goal.tokenBudget === "number" ? goal.tokenBudget : null,
     usage: {
       tokensUsed: typeof goal.usage?.tokensUsed === "number" ? goal.usage.tokensUsed : 0,
@@ -209,7 +215,10 @@ export function goalWithStatus(
   goal: GoalSnapshot,
   status: GoalStatus,
   now = unixSeconds(),
+  pauseReason?: GoalPauseReason,
 ): GoalSnapshot {
+  const { pauseReason: _previousReason, ...rest } = goal;
+  goal = rest;
   const accruedActiveSeconds =
     goal.status === "active" && goal.activeStartedAt !== null
       ? Math.max(0, now - goal.activeStartedAt)
@@ -233,6 +242,7 @@ export function goalWithStatus(
   return {
     ...goal,
     status,
+    ...(status === "paused" && pauseReason ? { pauseReason } : {}),
     usage,
     updatedAt: now,
     activeStartedAt: null,

package/src/index.ts

@@ -45,6 +45,7 @@ import {
   EXTENSION_VERSION,
   type ActivitySnapshot,
   type BackgroundActivityProvider,
+  type BackgroundWorkItem,
   type GoalSnapshot,
 } from "./types.js";
 
@@ -63,6 +64,14 @@ const MAX_NO_PROGRESS_RETRIES = parseRetryLimit(
   DEFAULT_MAX_NO_PROGRESS_RETRIES,
 );
 
+/**
+ * Tools that block the foreground turn until the user answers. Background
+ * completions that arrive meanwhile queue behind the answer (Pi only drains
+ * steering after the whole tool batch, and callback batches are follow-ups
+ * that wait for the entire run), so the goal harvests them explicitly.
+ */
+const BLOCKING_QUESTION_TOOLS: ReadonlySet<string> = new Set(["ask_user_question"]);
+
 const GOAL_ACTIONS: readonly AutocompleteItem[] = [
   { value: "pause", label: "pause", description: "Pause the active goal" },
   { value: "resume", label: "resume", description: "Resume the paused goal" },
@@ -112,6 +121,46 @@ function wasTurnAborted(messages: readonly unknown[]): boolean {
   return false;
 }
 
+function activeItemsByKey(snapshot: ActivitySnapshot): Map<string, BackgroundWorkItem> {
+  const items = new Map<string, BackgroundWorkItem>();
+  for (const provider of snapshot.providers) {
+    for (const item of provider.items) {
+      if (item.active) items.set(`${provider.providerId}:${item.id}`, item);
+    }
+  }
+  return items;
+}
+
+/** Items that were active when a question started and are no longer active now. */
+export function finishedSinceQuestion(
+  activeAtStart: ReadonlyMap<string, BackgroundWorkItem>,
+  snapshot: ActivitySnapshot,
+): BackgroundWorkItem[] {
+  const stillActive = activeItemsByKey(snapshot);
+  const current = new Map<string, BackgroundWorkItem>();
+  for (const provider of snapshot.providers) {
+    for (const item of provider.items) current.set(`${provider.providerId}:${item.id}`, item);
+  }
+  const finished: BackgroundWorkItem[] = [];
+  for (const [key, started] of activeAtStart) {
+    if (stillActive.has(key)) continue;
+    finished.push(current.get(key) ?? { ...started, active: false, status: "unknown" });
+  }
+  return finished;
+}
+
+function questionHarvestPrompt(finished: readonly BackgroundWorkItem[]): string {
+  const rows = finished.map((item) => {
+    const label = item.label ? `${item.label} (${item.id})` : item.id;
+    return `- ${label}: ${item.status}`;
+  });
+  return [
+    `${finished.length} background item${finished.length === 1 ? "" : "s"} finished while you were waiting on the user's answer:`,
+    ...rows,
+    "Inspect and integrate these results now (for example with subagent_result or bg_task_status) before acting on the answer; their completion notices may still arrive later as a batch.",
+  ].join("\n");
+}
+
 function continuationPrompt(goal: GoalSnapshot, owner: ReturnType<typeof currentWorkflowOwner> = null): string {
   return [
     "Continue working toward the active thread goal.",
@@ -188,12 +237,15 @@ export default function (pi: ExtensionAPI): void {
   let idleContinuationSignature = "";
   let refreshGoalWidget: ((force?: boolean) => void) | undefined;
   let lastAgentEvidence: ContinuationEvidence | null = null;
+  /** Background items active when each pending blocking question started, keyed by tool call id. */
+  const pendingQuestions = new Map<string, Map<string, BackgroundWorkItem>>();
 
   const getGoal = (ctx: ExtensionContext): GoalSnapshot | null => currentGoalSnapshot(ctx);
   const getWorkflow = (ctx: ExtensionContext) => currentWorkflowOwner(ctx.sessionManager.getBranch());
+  const registeredSkillPath = (name: string): string | undefined =>
+    pi.getCommands?.().find((item) => item.name === `skill:${name}` && item.source === "skill")?.sourceInfo.path;
   const workflowAvailable = (owner: NonNullable<ReturnType<typeof currentWorkflowOwner>>): boolean => {
-    const command = pi.getCommands?.().find((item) => item.name === `skill:${owner.name}` && item.source === "skill");
-    if (command?.sourceInfo.path !== owner.path) return false;
+    if (registeredSkillPath(owner.name) !== owner.path) return false;
     try {
       return workflowOwnerFromSkill(owner.name, owner.path)?.planOwner === owner.planOwner;
     } catch {
@@ -268,13 +320,30 @@ export default function (pi: ExtensionAPI): void {
     refreshGoalWidget?.(wasVisible);
   };
 
+  /**
+   * An interrupt (escape, or anything else that aborts the running turn) is a
+   * soft pause: it stops autonomous continuation now, and the user's next
+   * conversational message resumes the goal once that exchange settles. Only
+   * `/goal pause` (or an unavailable command/workflow) is a sticky pause.
+   */
   const pauseGoalOnInterrupt = (ctx: ExtensionContext): void => {
     const goal = getGoal(ctx);
     if (!isPokeable(goal)) {
       return;
     }
-    setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
-    notifyGoal(ctx, "Goal paused (interrupted).");
+    setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
+    notifyGoal(ctx, "Goal paused (interrupted). Send a message to resume it after that exchange, or use /goal pause to keep it paused.");
+  };
+
+  /** Why a paused goal cannot become active again, or null when it can. */
+  const resumeBlocker = (goal: GoalSnapshot): string | null => {
+    if (!goal.command && skillCommandName(goal.objective)) {
+      return "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.";
+    }
+    if (goal.command && !commandAvailable(pi, goal.command)) {
+      return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
+    }
+    return null;
   };
 
   const boundCommandReady = (goal: GoalSnapshot, ctx: ExtensionContext): boolean => {
@@ -392,7 +461,7 @@ export default function (pi: ExtensionAPI): void {
     }
     const goal = createGoalSnapshot(objective.trim(), tokenBudget, undefined, command ?? undefined);
     const owner = command?.source === "skill"
-      ? workflowOwnerFromSkill(command.name.slice("skill:".length), command.path)
+      ? workflowOwnerFromSkill(command.name.slice("skill:".length), command.path, registeredSkillPath)
       : null;
     if (getWorkflow(ctx)) recordWorkflow(null);
     setGoal(goal, ctx, source);
@@ -441,7 +510,13 @@ export default function (pi: ExtensionAPI): void {
         foregroundRunning,
         backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
       });
-      const status = snapshot.backgroundRunning
+      let waitingOnAnswer = 0;
+      for (const activeAtStart of pendingQuestions.values()) {
+        waitingOnAnswer += finishedSinceQuestion(activeAtStart, snapshot).length;
+      }
+      const status = waitingOnAnswer > 0
+        ? `${waitingOnAnswer} background done; waiting on your answer`
+        : snapshot.backgroundRunning
         ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
         : continuation?.blocked
           ? "waiting: no progress"
@@ -604,12 +679,9 @@ export default function (pi: ExtensionAPI): void {
           notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
           return;
         }
-        if (!current.command && skillCommandName(current.objective)) {
-          notifyGoal(ctx, "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.", "error");
-          return;
-        }
-        if (current.command && !commandAvailable(pi, current.command)) {
-          notifyGoal(ctx, `Cannot resume: /${current.command.name} is no longer registered at its original source.`, "error");
+        const blocker = resumeBlocker(current);
+        if (blocker) {
+          notifyGoal(ctx, blocker, "error");
           return;
         }
         const goal = goalWithStatus(current, "active");
@@ -794,7 +866,7 @@ export default function (pi: ExtensionAPI): void {
       const command = pi.getCommands?.().find((item) => item.name === `skill:${skillName}` && item.source === "skill");
       if (command) {
         try {
-          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path);
+          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path, registeredSkillPath);
           if (owner) recordWorkflow(owner);
         } catch (error) {
           notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
@@ -803,6 +875,22 @@ export default function (pi: ExtensionAPI): void {
       }
     }
     const goal = getGoal(ctx);
+    if (goal?.status === "paused" && goal.pauseReason === "interrupt") {
+      // Conversational input after an interrupt means the user has taken the
+      // wheel, not stopped the goal: reactivate it so continuation resumes once
+      // this exchange settles. Pi's built-in commands (/settings, /model, ...)
+      // and extension commands never reach this handler.
+      const blocker = resumeBlocker(goal);
+      if (blocker) {
+        notifyGoal(ctx, `Goal stays paused. ${blocker}`, "warning");
+        return;
+      }
+      const resumed = goalWithStatus(goal, "active");
+      setGoal(resumed, ctx, "runtime");
+      resetContinuationState(resumed);
+      notifyGoal(ctx, "Goal resumed; it continues after this exchange.");
+      return;
+    }
     if (goal?.status === "active") {
       resetContinuationState(goal);
     }
@@ -817,6 +905,10 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
 
+    const questionInstruction = snapshot.backgroundRunning
+      ? " A blocking user question (ask_user_question) holds this whole turn until the user answers, and background completions wait behind it. Harvest finished background results before asking, and ask only when the answer is needed to proceed."
+      : "";
+
     if (owner) {
       if (!workflowAvailable(owner)) {
         if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
@@ -832,7 +924,8 @@ export default function (pi: ExtensionAPI): void {
       }
       return {
         systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
-          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : ""),
+          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
+          (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
       };
     }
 
@@ -843,7 +936,7 @@ export default function (pi: ExtensionAPI): void {
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}`,
+        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}`,
     };
   });
 
@@ -875,6 +968,32 @@ export default function (pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("tool_execution_start", async (event, ctx) => {
+    if (!BLOCKING_QUESTION_TOOLS.has(event.toolName)) return;
+    currentCtx = ctx;
+    const snapshot = await publishSnapshot(ctx);
+    const active = activeItemsByKey(snapshot);
+    if (active.size > 0) pendingQuestions.set(event.toolCallId, active);
+  });
+
+  pi.on("tool_execution_end", async (event, ctx) => {
+    const activeAtStart = pendingQuestions.get(event.toolCallId);
+    if (!activeAtStart) return;
+    pendingQuestions.delete(event.toolCallId);
+    currentCtx = ctx;
+    const snapshot = await publishSnapshot(ctx);
+    const finished = finishedSinceQuestion(activeAtStart, snapshot);
+    if (finished.length === 0) return;
+    // Steering is drained right after this tool batch, so the model sees the
+    // finished work together with the user's answer instead of after the run.
+    pi.sendMessage({
+      customType: EXTENSION_NAME,
+      content: questionHarvestPrompt(finished),
+      display: false,
+      details: { kind: "question-harvest", toolCallId: event.toolCallId, finished: finished.map((item) => ({ id: item.id, status: item.status })) },
+    }, { deliverAs: "steer", triggerTurn: true });
+  });
+
   pi.on("agent_settled", async (_event, ctx) => {
     currentCtx = ctx;
     foregroundRunning = false;
@@ -917,6 +1036,7 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_shutdown", async (_event, ctx) => {
     stopPolling();
     foregroundRunning = false;
+    pendingQuestions.clear();
     clearIdleContinuation();
     currentCtx = undefined;
     latestSnapshot = null;

package/src/types.ts

@@ -65,6 +65,14 @@ export interface ActivitySnapshot {
 
 export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
 
+/**
+ * Why a paused goal is paused. `interrupt` marks a soft pause from escape (or
+ * any other abort of the running turn): the user's next conversational message
+ * resumes it. A paused goal without a reason (`/goal pause`, an unavailable
+ * command or workflow) stays paused until `/goal resume`.
+ */
+export type GoalPauseReason = "interrupt";
+
 export interface GoalUsage {
   tokensUsed: number;
   activeSeconds: number;
@@ -75,6 +83,8 @@ export interface GoalSnapshot {
   objective: string;
   command?: GoalCommandBinding;
   status: GoalStatus;
+  /** Present only while `status` is "paused". */
+  pauseReason?: GoalPauseReason;
   tokenBudget: number | null;
   usage: GoalUsage;
   createdAt: number;

package/src/workflow.ts

@@ -16,7 +16,12 @@ interface SessionEntryLike {
   data?: unknown;
 }
 
-export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwner | null {
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Resolves a registered skill's name to its SKILL.md path, or undefined when it is not registered. */
+export type SkillPathResolver = (name: string) => string | undefined;
+
+function skillMetadata(path: string): Record<string, unknown> | null {
   const source = readFileSync(path, "utf8");
   const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
   if (!match) return null;
@@ -24,9 +29,34 @@ export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwne
   if (!frontmatter || typeof frontmatter !== "object") return null;
   const metadata = (frontmatter as { metadata?: unknown }).metadata;
   if (!metadata || typeof metadata !== "object") return null;
-  const fields = metadata as Record<string, unknown>;
+  return metadata as Record<string, unknown>;
+}
+
+/**
+ * Reads a skill's workflow declaration. A coordinator declares `workflow-role: coordinator`.
+ * An alias declares `workflow-alias-of: <skill>` and resolves, through the registered skill
+ * commands, to that coordinator: the recorded owner is the target (its name and path), so
+ * invoking the alias is indistinguishable from invoking the coordinator. Aliases do not chain.
+ */
+export function workflowOwnerFromSkill(name: string, path: string, resolveSkillPath?: SkillPathResolver): WorkflowOwner | null {
+  const fields = skillMetadata(path);
+  if (!fields) return null;
   const role = fields["workflow-role"];
   const legacyRole = fields["pi-better-plan-workflow"];
+  const aliasOf = fields["workflow-alias-of"];
+  if (aliasOf !== undefined) {
+    if (typeof aliasOf !== "string" || !SKILL_NAME.test(aliasOf) || aliasOf === name ||
+        role !== undefined || legacyRole !== undefined) {
+      throw new Error(`Invalid workflow metadata in ${path}. Expected workflow-alias-of: <coordinator skill name> without workflow-role.`);
+    }
+    const targetPath = resolveSkillPath?.(aliasOf);
+    if (!targetPath) throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is not a registered skill.`);
+    const target = workflowOwnerFromSkill(aliasOf, targetPath, () => {
+      throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is itself an alias; aliases do not chain.`);
+    });
+    if (!target) throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is not a workflow coordinator.`);
+    return target;
+  }
   if (role === undefined && legacyRole === undefined) {
     if (fields["pi-better-workflow-role"] !== undefined || fields["pi-better-plan-owner"] !== undefined) {
       throw new Error(`Outdated workflow metadata in ${path}. Use workflow-role: coordinator.`);