ahead-pi 0.7.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "AHEAD workflow enforcement and context for Pi",
   "keywords": [
     "ahead",
@@ -45,6 +45,9 @@
     "verify": "npm run build && npm run format:check && npm run lint && node --test ./test/*.test.mjs",
     "test": "npm run verify && npm run pack:verify"
   },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.84.4"
+  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",

package/src/examples.ts

@@ -0,0 +1,143 @@
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface FieldExamplesInput {
+  workflowTitle: string;
+  phaseTitle: string;
+  runTitle: string;
+  fields: string[];
+}
+
+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.
+ *
+ * The model is called without repository context on purpose: the examples are
+ * creative sparks to react to, not guidance the human should trust. They are
+ * rendered as HTML comments inside the field so form validation still treats
+ * an untouched field as empty.
+ */
+export async function draftFieldExamples(
+  ctx: ExtensionCommandContext,
+  input: FieldExamplesInput,
+): Promise<FieldExamplesResult> {
+  const model = ctx.model;
+  if (!model) {
+    return { skipped: "no-model" };
+  }
+
+  const prompt = [
+    "You are helping a human begin a short written artifact in a software workflow.",
+    `Run title: ${input.runTitle}`,
+    `Workflow: ${input.workflowTitle} · Phase: ${input.phaseTitle}`,
+    "",
+    "You have NO access to the codebase or real project details. For each numbered field, write exactly 2 short example answers that are creative sparks only — plausibly generic and concrete, never claimed as fact about this project. Keep each line under 15 words.",
+    "",
+    "Output format, nothing else:",
+    "1: <example line>",
+    "1: <example line>",
+    "2: <example line>",
+    "2: <example line>",
+    "...one pair per field, in order.",
+    "",
+    "Fields:",
+    ...input.fields.map((field, index) => `${index + 1}. ${field}`),
+  ].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 { skipped: "no-auth" };
+    }
+    const message = await Promise.race([
+      completeSimple(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: auth.auth.apiKey,
+          headers: auth.auth.headers,
+          env: auth.env,
+          reasoning: "minimal",
+        },
+      ),
+      new Promise<undefined>((resolve) => {
+        setTimeout(() => resolve(undefined), EXAMPLES_TIMEOUT_MS);
+      }),
+    ]);
+    if (!message) {
+      return { skipped: "failed" };
+    }
+    const examples = parseExampleLines(message, input.fields.length);
+    if (!examples) {
+      return { skipped: "failed" };
+    }
+    return { examples };
+  } catch {
+    return { skipped: "failed" };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function textBlocks(content: unknown): string[] {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+  const blocks: string[] = [];
+  for (const block of content) {
+    if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+      blocks.push(block.text);
+    }
+  }
+  return blocks;
+}
+
+/** 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 }, () => []);
+  for (const line of text.split("\n")) {
+    const match = /^\s*(\d+)\s*:\s*(.+)$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const fieldIndex = Number.parseInt(match[1] ?? "", 10) - 1;
+    const example = match[2]?.trim();
+    if (
+      Number.isInteger(fieldIndex) &&
+      fieldIndex >= 0 &&
+      fieldIndex < fieldCount &&
+      example &&
+      perField[fieldIndex].length < 2
+    ) {
+      perField[fieldIndex].push(example);
+    }
+  }
+  if (perField.every((examples) => examples.length === 0)) {
+    return undefined;
+  }
+  return perField;
+}

package/src/guidance.ts

@@ -532,6 +532,32 @@ export function buildArtifactTemplate(
   ].join("\n");
 }
 
+/**
+ * Insert inspiration-only example lines into each field as HTML comments.
+ * Validation strips comments, so an untouched field still counts as empty.
+ */
+export function insertFieldExamples(template: string, perField: string[][]): string {
+  let updated = template;
+  for (const [index, examples] of perField.entries()) {
+    if (!examples || examples.length === 0) {
+      continue;
+    }
+    const marker = `<!-- AHEAD-FIELD:${index + 1}:BEGIN -->`;
+    if (!updated.includes(marker)) {
+      continue;
+    }
+    updated = updated.replace(
+      marker,
+      [
+        marker,
+        "<!-- Examples — inspiration only, not requirements. Delete them and write your own answer. -->",
+        ...examples.map((example) => `<!-- ~ ${example} ~ -->`),
+      ].join("\n"),
+    );
+  }
+  return updated;
+}
+
 export function validateArtifactForm(content: string, prompts: string[]): string[] {
   const errors: string[] = [];
   for (const [index, prompt] of prompts.entries()) {

package/src/index.ts

@@ -14,12 +14,14 @@ import { AheadEngine, AheadEngineError } from "./engine.js";
 import {
   buildArtifactTemplate,
   buildHeaderLines,
+  insertFieldExamples,
   nextAction,
   phaseGuide,
   phasePosition,
   promptsForArtifact,
   validateArtifactForm,
 } from "./guidance.js";
+import { draftFieldExamples } from "./examples.js";
 import {
   findReference,
   loadReferenceIndex,
@@ -740,6 +742,35 @@ async function openAheadMode(
     });
   }
 
+  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",
@@ -1475,8 +1506,8 @@ async function startRun(ctx: ExtensionCommandContext, request: string): Promise<
     linkedTitle ||
     (ctx.hasUI
       ? await ctx.ui.input(
-          `Enter AHEAD mode · ${workflow.title}`,
-          `Short name for this work — e.g. ${titleExample(workflow.id)}`,
+          `AHEAD · ${workflow.title} · Name this work — e.g. ${titleExample(workflow.id)}`,
+          "",
         )
       : parsed.workItemUrl);
   if (!title?.trim()) {
@@ -1569,7 +1600,31 @@ async function recordHumanArtifact(
     );
   }
 
-  const template = await humanArtifactTemplate(store, state, run, artifact.kind, artifact.title);
+  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) {
+    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 (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`,
     template,
@@ -1581,10 +1636,7 @@ async function recordHumanArtifact(
     // Keep the form open until validation passes or the human explicitly cancels,
     // so partial input is never discarded by a validation failure.
     while (true) {
-      const formErrors = validateArtifactForm(
-        content,
-        promptsForArtifact(state.workflow_id, state.phase.id, artifact.kind),
-      );
+      const formErrors = validateArtifactForm(content, prompts);
       if (formErrors.length === 0) {
         break;
       }