pi-better-harness 0.3.11 → 0.3.12

package/node_modules/pi-better-goal/README.md

@@ -28,7 +28,7 @@ metadata:
   workflow-role: coordinator
 ```
 
-Invoke the skill with Pi's `/skill:name` command. The goal extension checks Pi's skill-command provenance, persists the owner on the session branch, and restores its instructions on resumed turns. It does not infer ownership from ordinary text or skill names. A goal such as `/goal /skill:name task` is rejected; invoke `/skill:name task` directly and use `/goal` only for a plain-language objective. Legacy slash-shaped goals pause on resume rather than running without the skill. `/workflow` shows the 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.
+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.
 
 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.
 

package/node_modules/pi-better-goal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -42,7 +42,7 @@
     "verify": "npm run typecheck && npm test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
@@ -58,8 +58,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.82.0",
-    "@earendil-works/pi-tui": "^0.82.0",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@types/node": "^25.0.0",
     "tsx": "^4.22.3",
     "typebox": "^1.1.39",

package/node_modules/pi-better-goal/src/command-binding.ts

@@ -0,0 +1,37 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+
+export interface GoalCommandBinding {
+  name: string;
+  source: "skill" | "prompt" | "extension";
+  path: string;
+  args: string;
+}
+
+export function leadingCommand(text: string): { name: string; args: string } | null {
+  const match = /^\/([^\s/]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+  return match ? { name: match[1]!, args: match[2]?.trim() ?? "" } : null;
+}
+
+export function resolveGoalCommand(pi: ExtensionAPI, text: string): GoalCommandBinding | null {
+  const parsed = leadingCommand(text);
+  if (!parsed) return null;
+  if (parsed.name === "goal") throw new Error("A goal cannot invoke /goal recursively.");
+  const command = pi.getCommands().find((item) => item.name === parsed.name);
+  if (!command) throw new Error(`Unknown command /${parsed.name}.`);
+  if (!command.sourceInfo.path) throw new Error(`Command /${parsed.name} has no stable source path.`);
+  return { name: command.name, source: command.source, path: command.sourceInfo.path, args: parsed.args };
+}
+
+export function commandAvailable(pi: ExtensionAPI, binding: GoalCommandBinding): boolean {
+  return (binding.source === "extension" || existsSync(binding.path)) &&
+    pi.getCommands().some((command) => command.name === binding.name &&
+    command.source === binding.source && command.sourceInfo.path === binding.path);
+}
+
+export function commandInvocation(binding: GoalCommandBinding, continuation = false): string {
+  const args = continuation
+    ? `${binding.args ? `${binding.args}\n\n` : ""}Continue the existing goal using the current session state. Do not restart completed work.`
+    : binding.args;
+  return `/${binding.name}${args ? ` ${args}` : ""}`;
+}

package/node_modules/pi-better-goal/src/goal-state.ts

@@ -1,4 +1,5 @@
 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";
 
@@ -14,6 +15,7 @@ interface SessionEntryLike {
 interface GoalLike {
   goalId: string;
   objective: string;
+  command?: unknown;
   status: GoalStatus;
   tokenBudget?: number | null;
   usage?: { tokensUsed?: number; activeSeconds?: number };
@@ -96,6 +98,14 @@ function unixSeconds(): number {
   return Math.floor(Date.now() / 1000);
 }
 
+function isCommandBinding(value: unknown): value is GoalCommandBinding {
+  if (!value || typeof value !== "object") return false;
+  const binding = value as Partial<GoalCommandBinding>;
+  return typeof binding.name === "string" && binding.name.length > 0 &&
+    (binding.source === "skill" || binding.source === "prompt" || binding.source === "extension") &&
+    typeof binding.path === "string" && binding.path.length > 0 && typeof binding.args === "string";
+}
+
 function nextGoalId(): string {
   return `goal_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -107,6 +117,7 @@ function normalizeGoal(goal: GoalLike): GoalSnapshot {
   return {
     goalId: goal.goalId,
     objective: goal.objective,
+    ...(isCommandBinding(goal.command) ? { command: goal.command } : {}),
     status: goal.status,
     tokenBudget: typeof goal.tokenBudget === "number" ? goal.tokenBudget : null,
     usage: {
@@ -134,10 +145,12 @@ export function createGoalSnapshot(
   objective: string,
   tokenBudget: number | null = null,
   now = unixSeconds(),
+  command?: GoalCommandBinding,
 ): GoalSnapshot {
   return {
     goalId: nextGoalId(),
     objective,
+    ...(command ? { command } : {}),
     status: "active",
     tokenBudget,
     usage: { tokensUsed: 0, activeSeconds: 0 },

package/node_modules/pi-better-goal/src/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { Type } from "typebox";
+import { commandAvailable, commandInvocation, resolveGoalCommand } from "./command-binding.js";
 
 import {
   collectActivitySnapshot,
@@ -276,22 +277,35 @@ export default function (pi: ExtensionAPI): void {
     notifyGoal(ctx, "Goal paused (interrupted).");
   };
 
-  const queueGoalContinuation = (goal: GoalSnapshot): void => {
+  const boundCommandReady = (goal: GoalSnapshot, ctx: ExtensionContext): boolean => {
+    if (!goal.command || commandAvailable(pi, goal.command)) return true;
+    setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
+    notifyGoal(ctx, `Goal paused: /${goal.command.name} is no longer registered at its original source.`, "error");
+    return false;
+  };
+
+  const sendGoalContinuation = (goal: GoalSnapshot, content: string, kind: string, snapshot?: ActivitySnapshot): void => {
+    if (goal.command?.source === "skill" || goal.command?.source === "prompt") {
+      pi.sendUserMessage(`${commandInvocation(goal.command, true)}\n\n${content}`, {
+        deliverAs: "followUp", expandPromptTemplates: true,
+      });
+    } else {
+      pi.sendMessage({
+        customType: EXTENSION_NAME, content, display: false,
+        details: snapshot ? { kind, snapshot } : { kind, goalId: goal.goalId },
+      }, { triggerTurn: true, deliverAs: "followUp" });
+    }
+  };
+
+  const queueGoalContinuation = (goal: GoalSnapshot, ctx: ExtensionContext): void => {
     if (!isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
     }
+    if (!boundCommandReady(goal, ctx)) return;
     clearIdleContinuation();
     continuationQueuedFor = goal.goalId;
     resetContinuationState(goal);
-    pi.sendMessage(
-      {
-        customType: EXTENSION_NAME,
-        content: continuationPrompt(goal, currentCtx ? getWorkflow(currentCtx) : null),
-        display: false,
-        details: { kind: "continuation", goalId: goal.goalId },
-      },
-      { triggerTurn: true, deliverAs: "followUp" },
-    );
+    sendGoalContinuation(goal, continuationPrompt(goal, getWorkflow(ctx)), "continuation");
   };
 
   function clearIdleContinuation(): void {
@@ -338,6 +352,7 @@ export default function (pi: ExtensionAPI): void {
     if (!isPokeable(goal) || goal.goalId !== goalId || continuationQueuedFor === goal.goalId || foregroundRunning) {
       return;
     }
+    if (!boundCommandReady(goal, ctx)) return;
     const snapshot = await collectActivitySnapshot(ctx, providers.values(), foregroundRunning);
     latestSnapshot = snapshot;
     pi.events.emit(EVENT_ACTIVITY, snapshot);
@@ -354,17 +369,7 @@ export default function (pi: ExtensionAPI): void {
       ? "Background activity for the active goal is no longer running. Inspect any subagent callbacks or final results, then continue the completion audit before marking the goal complete.\n\n" +
         continuationPrompt(goal, getWorkflow(ctx))
       : continuationPrompt(goal, getWorkflow(ctx));
-    pi.sendMessage(
-      {
-        customType: EXTENSION_NAME,
-        content,
-        display: false,
-        details: kind === "background-drained"
-          ? { kind, snapshot: priorSnapshot ?? snapshot }
-          : { kind, goalId: goal.goalId },
-      },
-      { triggerTurn: true, deliverAs: "followUp" },
-    );
+    sendGoalContinuation(goal, content, kind, kind === "background-drained" ? priorSnapshot ?? snapshot : undefined);
   };
 
   const startOrReplaceGoal = (
@@ -373,9 +378,6 @@ export default function (pi: ExtensionAPI): void {
     ctx: ExtensionContext,
     source: "command",
   ): GoalSnapshot => {
-    if (skillCommandName(objective)) {
-      throw new Error("A skill command cannot be a goal objective. Invoke /skill:name directly so Pi loads the skill, then set a plain-language goal if needed.");
-    }
     const objectiveError = validateObjective(objective);
     if (objectiveError) {
       throw new Error(objectiveError);
@@ -384,9 +386,23 @@ export default function (pi: ExtensionAPI): void {
     if (budgetError) {
       throw new Error(budgetError);
     }
-    const goal = createGoalSnapshot(objective.trim(), tokenBudget);
+    const command = resolveGoalCommand(pi, objective);
+    if (command && !commandAvailable(pi, command)) {
+      throw new Error(`Command /${command.name} is unavailable at its registered source.`);
+    }
+    const goal = createGoalSnapshot(objective.trim(), tokenBudget, undefined, command ?? undefined);
+    const owner = command?.source === "skill"
+      ? workflowOwnerFromSkill(command.name.slice("skill:".length), command.path)
+      : null;
+    if (getWorkflow(ctx)) recordWorkflow(null);
     setGoal(goal, ctx, source);
-    queueGoalContinuation(goal);
+    if (command) {
+      if (owner) recordWorkflow(owner);
+      pi.sendUserMessage(commandInvocation(command), { deliverAs: "followUp", expandPromptTemplates: true });
+      if (command.source === "extension") scheduleIdleContinuation(goal, ctx, "continuation");
+    } else {
+      queueGoalContinuation(goal, ctx);
+    }
     return goal;
   };
 
@@ -588,13 +604,17 @@ export default function (pi: ExtensionAPI): void {
           notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
           return;
         }
-        if (skillCommandName(current.objective)) {
+        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");
+          return;
+        }
         const goal = goalWithStatus(current, "active");
         setGoal(goal, ctx, "command");
-        queueGoalContinuation(goal);
+        queueGoalContinuation(goal, ctx);
         notifyGoal(ctx, "Goal resumed.");
         return;
       }
@@ -752,7 +772,7 @@ export default function (pi: ExtensionAPI): void {
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
     const restoredGoal = getGoal(ctx);
-    if (restoredGoal?.status === "active" && skillCommandName(restoredGoal.objective)) {
+    if (restoredGoal?.status === "active" && !restoredGoal.command && skillCommandName(restoredGoal.objective)) {
       setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
       notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
     }
@@ -760,6 +780,9 @@ export default function (pi: ExtensionAPI): void {
     installGoalWidget(ctx);
     latestSnapshot = await publishSnapshot(ctx);
     syncPollingState();
+    if (restoredGoal?.status === "active" && restoredGoal.command && boundCommandReady(restoredGoal, ctx) && !foregroundRunning && !latestSnapshot.backgroundRunning) {
+      scheduleIdleContinuation(restoredGoal, ctx, "continuation");
+    }
   });
 
   pi.on("input", async (event, ctx) => {

package/node_modules/pi-better-goal/src/types.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GoalCommandBinding } from "./command-binding.js";
 
 export const EXTENSION_NAME = "pi-better-goal";
 export const EXTENSION_VERSION = "0.1.0";
@@ -72,6 +73,7 @@ export interface GoalUsage {
 export interface GoalSnapshot {
   goalId: string;
   objective: string;
+  command?: GoalCommandBinding;
   status: GoalStatus;
   tokenBudget: number | null;
   usage: GoalUsage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "pi-better-background-tasks": "0.2.13",
-    "pi-better-goal": "0.3.1",
+    "pi-better-goal": "0.4.0",
     "pi-better-plan": "0.2.1",
     "pi-better-sandbox": "0.3.0",
     "pi-better-ssh": "0.1.1",