ahead-pi 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",

package/src/examples.ts

@@ -8,7 +8,14 @@ export interface FieldExamplesInput {
   fields: string[];
 }
 
-const EXAMPLES_TIMEOUT_MS = 25_000;
+const EXAMPLES_TIMEOUT_MS = 12_000;
+
+export type FieldExamplesSkipped = "no-model" | "no-auth" | "failed";
+
+export interface FieldExamplesResult {
+  examples?: string[][];
+  skipped?: FieldExamplesSkipped;
+}
 
 /**
  * Draft two inspiration-only example lines per artifact field.
@@ -21,10 +28,10 @@ const EXAMPLES_TIMEOUT_MS = 25_000;
 export async function draftFieldExamples(
   ctx: ExtensionCommandContext,
   input: FieldExamplesInput,
-): Promise<string[][] | undefined> {
+): Promise<FieldExamplesResult> {
   const model = ctx.model;
   if (!model) {
-    return undefined;
+    return { skipped: "no-model" };
   }
 
   const prompt = [
@@ -46,9 +53,13 @@ export async function draftFieldExamples(
   ].join("\n");
 
   try {
+    // getProviderAuth returning undefined means no usable credential of any
+    // kind could be resolved — only then is a heads-up accurate. A resolved
+    // auth object without an apiKey (e.g. OAuth) may still succeed through
+    // the adapter's own credential resolution, so we attempt the call.
     const auth = await ctx.modelRegistry.getProviderAuth(model.provider);
     if (!auth) {
-      return undefined;
+      return { skipped: "no-auth" };
     }
     const message = await Promise.race([
       completeSimple(
@@ -74,11 +85,15 @@ export async function draftFieldExamples(
       }),
     ]);
     if (!message) {
-      return undefined;
+      return { skipped: "failed" };
+    }
+    const examples = parseExampleLines(message, input.fields.length);
+    if (!examples) {
+      return { skipped: "failed" };
     }
-    return parseExampleLines(message, input.fields.length);
+    return { examples };
   } catch {
-    return undefined;
+    return { skipped: "failed" };
   }
 }
 
@@ -99,7 +114,8 @@ function textBlocks(content: unknown): string[] {
   return blocks;
 }
 
-function parseExampleLines(message: unknown, fieldCount: number): string[][] | undefined {
+/** Exported for unit testing; the wire shape is validated defensively at runtime. */
+export function parseExampleLines(message: unknown, fieldCount: number): string[][] | undefined {
   const text = textBlocks(isRecord(message) ? message.content : undefined).join("\n");
 
   const perField: string[][] = Array.from({ length: fieldCount }, () => []);

package/src/index.ts

@@ -648,186 +648,200 @@ async function openAheadMode(
     run = await linkWorkItem(ctx, store, run, workItemFromUrl(args));
   }
 
-  await refreshUi(ctx, run);
   if (!ctx.hasUI) {
     ctx.ui.notify(formatState(engine.deriveState(run)), "info");
     return;
   }
 
-  const state = engine.deriveState(run);
-  const workflow = engine.getWorkflow(run.workflow_id);
-  const guidance = phaseGuide(run.workflow_id, state.phase.id);
-  const action = nextAction(state, workflow);
-  const actions: GuidedAction[] = [];
-  const missingRequired = state.artifacts.filter(
-    (artifact) => artifact.required && !artifact.present,
-  );
-  if (action.artifactKind) {
-    const actionArtifact = state.artifacts.find(
-      (artifact) => artifact.kind === action.artifactKind,
+  // Action-menu loop: the run is reloaded and the state re-derived after
+  // every action, then the menu reappears — help screens and completed
+  // actions never strand the user. Escaping the menu, or an action that
+  // clears the run, leaves the wizard.
+  while (true) {
+    const current = await store.loadCurrent();
+    if (!current) {
+      return;
+    }
+    run = current;
+    await refreshUi(ctx, run);
+    const state = engine.deriveState(run);
+    const workflow = engine.getWorkflow(run.workflow_id);
+    const guidance = phaseGuide(run.workflow_id, state.phase.id);
+    const action = nextAction(state, workflow);
+    const actions: GuidedAction[] = [];
+    const missingRequired = state.artifacts.filter(
+      (artifact) => artifact.required && !artifact.present,
     );
-    actions.push({
-      label: action.label,
-      run:
-        action.actor === "ai"
-          ? state.phase.id === "ai-review"
-            ? async () => openReviewWorkbench(pi, ctx)
-            : async () => requestAiAssistance(pi, state, action.artifactKind)
-          : async () => recordHumanArtifact(ctx, action.artifactKind ?? ""),
-    });
-    if (action.actor === "ai" && actionArtifact?.actor === "any") {
+    if (action.artifactKind) {
+      const actionArtifact = state.artifacts.find(
+        (artifact) => artifact.kind === action.artifactKind,
+      );
       actions.push({
-        label: `Write ${actionArtifact.title} yourself`,
-        run: async () => recordHumanArtifact(ctx, actionArtifact.kind),
+        label: action.label,
+        run:
+          action.actor === "ai"
+            ? state.phase.id === "ai-review"
+              ? async () => openReviewWorkbench(pi, ctx)
+              : async () => requestAiAssistance(pi, state, action.artifactKind)
+            : async () => recordHumanArtifact(ctx, action.artifactKind ?? ""),
       });
+      if (action.actor === "ai" && actionArtifact?.actor === "any") {
+        actions.push({
+          label: `Write ${actionArtifact.title} yourself`,
+          run: async () => recordHumanArtifact(ctx, actionArtifact.kind),
+        });
+      }
     }
-  }
 
-  if (action.optional) {
-    const nextHumanArtifact = missingRequired.find((artifact) => artifact.actor !== "ai");
-    if (nextHumanArtifact) {
+    if (action.optional) {
+      const nextHumanArtifact = missingRequired.find((artifact) => artifact.actor !== "ai");
+      if (nextHumanArtifact) {
+        actions.push({
+          label: `Continue without optional AI challenge · Write ${nextHumanArtifact.title}`,
+          run: async () => recordHumanArtifact(ctx, nextHumanArtifact.kind),
+        });
+      } else if (missingRequired.length === 0) {
+        actions.push({
+          label: `Continue without optional AI contribution · Accept ${state.gate.title}`,
+          run: async () => acceptAndContinue(ctx),
+        });
+      }
+    }
+
+    if (state.work_item_required_for_next_phase && state.gate.accepted) {
       actions.push({
-        label: `Continue without optional AI challenge · Write ${nextHumanArtifact.title}`,
-        run: async () => recordHumanArtifact(ctx, nextHumanArtifact.kind),
+        label: action.label,
+        run: async () => manageWorkItem(ctx, ""),
       });
-    } else if (missingRequired.length === 0) {
+    } else if (missingRequired.length === 0 && !action.artifactKind) {
       actions.push({
-        label: `Continue without optional AI contribution · Accept ${state.gate.title}`,
+        label: state.gate.accepted ? action.label : `Accept and continue · ${state.gate.title}`,
         run: async () => acceptAndContinue(ctx),
       });
     }
-  }
 
-  if (state.work_item_required_for_next_phase && state.gate.accepted) {
-    actions.push({
-      label: action.label,
-      run: async () => manageWorkItem(ctx, ""),
-    });
-  } else if (missingRequired.length === 0 && !action.artifactKind) {
-    actions.push({
-      label: state.gate.accepted ? action.label : `Accept and continue · ${state.gate.title}`,
-      run: async () => acceptAndContinue(ctx),
-    });
-  }
+    if (
+      state.allowed_ai_capabilities.length > 0 &&
+      action.actor !== "ai" &&
+      !missingRequired.some((artifact) => artifact.actor === "ai") &&
+      state.phase.id !== "implement"
+    ) {
+      actions.push({
+        label: `Ask AI to assist · ${state.phase.title}`,
+        run: async () => requestAiAssistance(pi, state),
+      });
+    }
 
-  if (
-    state.allowed_ai_capabilities.length > 0 &&
-    action.actor !== "ai" &&
-    !missingRequired.some((artifact) => artifact.actor === "ai") &&
-    state.phase.id !== "implement"
-  ) {
-    actions.push({
-      label: `Ask AI to assist · ${state.phase.title}`,
-      run: async () => requestAiAssistance(pi, state),
-    });
-  }
+    if (state.phase.id === "implement") {
+      if (!state.artifacts.some((artifact) => artifact.kind === "changeset" && artifact.present)) {
+        actions.push({
+          label: "Save this ready-to-implement run for a later sprint",
+          run: async () => saveImplementationHandoff(ctx),
+        });
+      }
+      actions.push({
+        label: "Ask AI for help understanding or solving a problem",
+        run: async () => askImplementationQuestion(pi, ctx, state),
+      });
+    }
 
-  if (state.phase.id === "implement") {
-    if (!state.artifacts.some((artifact) => artifact.kind === "changeset" && artifact.present)) {
+    if (state.phase.id === "ai-review" || state.phase.id === "human-review") {
       actions.push({
-        label: "Save this ready-to-implement run for a later sprint",
-        run: async () => saveImplementationHandoff(ctx),
+        label: "Open the changeset review workbench",
+        run: async () => openReviewWorkbench(pi, ctx),
       });
     }
-    actions.push({
-      label: "Ask AI for help understanding or solving a problem",
-      run: async () => askImplementationQuestion(pi, ctx, state),
-    });
-  }
 
-  if (state.phase.id === "ai-review" || state.phase.id === "human-review") {
-    actions.push({
-      label: "Open the changeset review workbench",
-      run: async () => openReviewWorkbench(pi, ctx),
-    });
-  }
+    if (
+      state.allowed_ai_capabilities.length > 0 &&
+      state.artifacts.some(
+        (artifact) => artifact.present && artifact.recorded_by?.kind === "human" && artifact.path,
+      )
+    ) {
+      actions.push({
+        label: "Ask AI to challenge the latest artifact",
+        run: async () => {
+          const artifact = [...state.artifacts]
+            .toReversed()
+            .find(
+              (candidate) =>
+                candidate.present && candidate.recorded_by?.kind === "human" && candidate.path,
+            );
+          if (!artifact?.path) {
+            return;
+          }
+          pi.sendUserMessage(
+            [
+              `AHEAD mode: challenge my ${artifact.title} artifact before I accept the gate.`,
+              `Read ${artifact.path} and name the 2-3 weakest points: missing risks, vague claims, or things that would not survive implementation.`,
+              "Be specific and brief. Do not rewrite the artifact; I stay the author.",
+            ].join("\n"),
+          );
+        },
+      });
+    }
+
+    if (state.return_targets.length > 0) {
+      actions.push({
+        label: "Return to an earlier phase",
+        run: async () => returnToEarlierPhase(ctx, ""),
+      });
+    }
+
+    if (!state.work_item_required_for_next_phase || !state.gate.accepted) {
+      actions.push({
+        label: state.work_item
+          ? "View or replace the linked work item"
+          : "Link or create a work item",
+        run: async () => manageWorkItem(ctx, ""),
+      });
+    }
 
-  if (
-    state.allowed_ai_capabilities.length > 0 &&
-    state.artifacts.some(
-      (artifact) => artifact.present && artifact.recorded_by?.kind === "human" && artifact.path,
-    )
-  ) {
     actions.push({
-      label: "Ask AI to challenge the latest artifact",
+      label: "Help · policy, guidance, skills, phase explanation",
       run: async () => {
-        const artifact = [...state.artifacts]
-          .toReversed()
-          .find(
-            (candidate) =>
-              candidate.present && candidate.recorded_by?.kind === "human" && candidate.path,
+        // "← Back" and escaping both return to the action-menu loop above.
+        const helpChoice = await ctx.ui.select("Help · pick one", [
+          "← Back to action menu",
+          "Configure project AHEAD policy for future runs",
+          "Read AHEAD framework guidance for this phase",
+          "Inspect optional skills reviewed for this phase",
+          "Explain this phase and its expectations",
+        ]);
+        if (helpChoice === "Configure project AHEAD policy for future runs") {
+          await manageProjectConfig(ctx);
+        } else if (helpChoice === "Read AHEAD framework guidance for this phase") {
+          await showAheadGuide(ctx, "");
+        } else if (helpChoice === "Inspect optional skills reviewed for this phase") {
+          await showRecommendedSkills(ctx);
+        } else if (helpChoice === "Explain this phase and its expectations") {
+          ctx.ui.notify(
+            [
+              state.phase.title,
+              `Goal: ${guidance.objective}`,
+              `You: ${guidance.human}`,
+              `AI: ${guidance.ai}`,
+              `Gate: ${state.gate.title}`,
+            ].join("\n"),
+            "info",
           );
-        if (!artifact?.path) {
-          return;
         }
-        pi.sendUserMessage(
-          [
-            `AHEAD mode: challenge my ${artifact.title} artifact before I accept the gate.`,
-            `Read ${artifact.path} and name the 2-3 weakest points: missing risks, vague claims, or things that would not survive implementation.`,
-            "Be specific and brief. Do not rewrite the artifact; I stay the author.",
-          ].join("\n"),
-        );
       },
     });
-  }
-
-  if (state.return_targets.length > 0) {
-    actions.push({
-      label: "Return to an earlier phase",
-      run: async () => returnToEarlierPhase(ctx, ""),
-    });
-  }
 
-  if (!state.work_item_required_for_next_phase || !state.gate.accepted) {
     actions.push({
-      label: state.work_item
-        ? "View or replace the linked work item"
-        : "Link or create a work item",
-      run: async () => manageWorkItem(ctx, ""),
+      label: "Stop AHEAD mode",
+      run: async () => stopAheadMode(ctx),
     });
-  }
-
-  actions.push({
-    label: "Help · policy, guidance, skills, phase explanation",
-    run: async () => {
-      const helpChoice = await ctx.ui.select("Help · pick one", [
-        "Configure project AHEAD policy for future runs",
-        "Read AHEAD framework guidance for this phase",
-        "Inspect optional skills reviewed for this phase",
-        "Explain this phase and its expectations",
-      ]);
-      if (helpChoice === "Configure project AHEAD policy for future runs") {
-        await manageProjectConfig(ctx);
-      } else if (helpChoice === "Read AHEAD framework guidance for this phase") {
-        await showAheadGuide(ctx, "");
-      } else if (helpChoice === "Inspect optional skills reviewed for this phase") {
-        await showRecommendedSkills(ctx);
-      } else if (helpChoice === "Explain this phase and its expectations") {
-        ctx.ui.notify(
-          [
-            state.phase.title,
-            `Goal: ${guidance.objective}`,
-            `You: ${guidance.human}`,
-            `AI: ${guidance.ai}`,
-            `Gate: ${state.gate.title}`,
-          ].join("\n"),
-          "info",
-        );
-      }
-    },
-  });
 
-  actions.push({
-    label: "Stop AHEAD mode",
-    run: async () => stopAheadMode(ctx),
-  });
-
-  const selected = await ctx.ui.select(
-    `AHEAD mode · ${state.phase.title}\nNext (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
-    actions.map((candidate) => candidate.label),
-  );
-  const chosen = actions.find((candidate) => candidate.label === selected);
-  if (chosen) {
+    const selected = await ctx.ui.select(
+      `AHEAD mode · ${state.phase.title}\nNext (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
+      actions.map((candidate) => candidate.label),
+    );
+    const chosen = actions.find((candidate) => candidate.label === selected);
+    if (!chosen) {
+      return;
+    }
     await chosen.run();
   }
 }
@@ -1555,7 +1569,7 @@ function titleExample(workflowId: string): string {
     case "product-change":
       return "“Add audit log viewer page”";
     case "internal-improvement":
-      return "“Reduce cola-api cold-start time”";
+      return "“Reduce cold-start time”";
     case "corrective-debugging":
       return "“Fix race in worker claim loop”";
     case "operational-stabilization":
@@ -1603,15 +1617,27 @@ async function recordHumanArtifact(
   const prompts = promptsForArtifact(state.workflow_id, state.phase.id, artifact.kind);
   let template = await humanArtifactTemplate(store, state, run, artifact.kind, artifact.title);
   if (ctx.hasUI && artifact.kind !== "review-disposition" && prompts.length > 0) {
-    const examples = await draftFieldExamples(ctx, {
+    if (ctx.model) {
+      ctx.ui.notify("Drafting two example prompts per field (inspiration only)…", "info");
+    }
+    const draft = await draftFieldExamples(ctx, {
       workflowTitle: engine.getWorkflow(state.workflow_id).title,
       phaseTitle: state.phase.title,
       runTitle: run.title,
       fields: prompts,
     });
-    if (examples) {
-      template = insertFieldExamples(template, examples);
+    if (draft.examples) {
+      template = insertFieldExamples(template, draft.examples);
+    } else if (draft.skipped === "no-auth") {
+      ctx.ui.notify(
+        "Example prompts unavailable: no usable model credential could be resolved for this session.",
+        "info",
+      );
+    } else if (draft.skipped === "no-model") {
+      ctx.ui.notify("Example prompts unavailable: no active model in this session.", "info");
     }
+    // "failed" (timeout, unparseable output, transient error) stays silent:
+    // the plain template is the fallback and needs no apology.
   }
   let content = await ctx.ui.editor(
     `AHEAD mode · ${artifact.title} · write in your own words`,