@mjasnikovs/pi-task 0.2.0 → 0.2.2

package/dist/task/auto-prompts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Prompts for /task-auto's two feature-level child calls. These produce a task
+ * LIST only; all research/spec depth is /task's job, run per-title later.
+ */
+/**
+ * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
+ * single numbered question followed by a "SUGGESTED: <default>" line, or the
+ * literal token NONE when no clarification remains. priorQA carries the
+ * questions already answered so each next question adapts to them.
+ */
+export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) => string;
+/**
+ * Decompose: output a markdown checkbox list of task titles (one line each).
+ */
+export declare const AUTO_DECOMPOSE_PROMPT: (feature: string, clarifications: string) => string;

package/dist/task/auto-prompts.js

@@ -0,0 +1,66 @@
+/**
+ * Prompts for /task-auto's two feature-level child calls. These produce a task
+ * LIST only; all research/spec depth is /task's job, run per-title later.
+ */
+/**
+ * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
+ * single numbered question followed by a "SUGGESTED: <default>" line, or the
+ * literal token NONE when no clarification remains. priorQA carries the
+ * questions already answered so each next question adapts to them.
+ */
+export const AUTO_CLARIFY_PROMPT = (feature, priorQA) => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
+
+FEATURE REQUEST:
+${feature.trim()}
+
+ANSWERS SO FAR:
+${priorQA.trim() || '(none yet)'}
+
+You may use the read tool to inspect the repo and any referenced docs so your
+question and recommendation are grounded in what already exists.
+
+Output the SINGLE most important clarifying question that REMAINS — the one whose
+answer would most change HOW this feature is split into tasks (scope boundaries,
+which subsystems are in/out, ordering, the cross-cutting technical choices that
+fork the breakdown). Account for the answers so far:
+- Never re-ask something already answered above.
+- If an answer introduced a new fork or contradicts an assumption (for example,
+  the user chose a framework or tool the request did not anticipate), ask about
+  the most important consequence of that choice next — how it is built, what
+  extra dependencies it pulls in, how it changes the other subsystems.
+- When the feature spans multiple subsystems, work through its forks one at a
+  time (file/blob storage, client/rendering strategy, auth and session model,
+  real-time vs polling transport, search, deployment).
+- Skip anything /task will naturally resolve per-task during its own research.
+
+Also propose the single most sensible default answer for this question, inferred
+from the repo, the referenced docs, and any stated philosophy or constraints —
+concrete and decisive, shown to the user as a recommendation they can accept or
+override.
+
+OUTPUT FORMAT (exact):
+- One clarifying question as a single numbered line: "1. ...".
+- On the NEXT line (never inline), a line that begins with "SUGGESTED: <your recommended default>".
+- Put the core question in **bold**, followed by a short one-line rationale in plain prose. Backticks around code/identifiers are fine. Avoid other markdown (headings, bullet lists, links).
+- Only when the spec already pins down every choice that would change the task breakdown — nothing decision-changing is left to ask — output exactly:
+NONE`;
+/**
+ * Decompose: output a markdown checkbox list of task titles (one line each).
+ */
+export const AUTO_DECOMPOSE_PROMPT = (feature, clarifications) => `Split this feature into an ordered list of implementation tasks. Each task
+will be handed, by its title, to a separate pipeline that does its own research
+and writes its own spec — so here you produce TITLES ONLY, not specs.
+
+FEATURE REQUEST:
+${feature.trim()}
+
+CLARIFICATIONS:
+${clarifications.trim() || '(none)'}
+
+RULES:
+- One task per line, as a markdown checkbox: "- [ ] <title>".
+- Each title is a short imperative phrase; optionally add " — <one key detail>".
+- Order tasks so earlier ones unblock later ones (foundations first).
+- Each task should be independently implementable as a single /task run.
+- Prefer a handful of substantial tasks over many trivial ones.
+- Output the checkbox list and NOTHING else (no preamble, no numbering).`;

package/dist/task/inline-markdown.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Inline-markdown helpers for the clarify/grill question dialogs.
+ *
+ * The model often wraps the core question in **bold** (and code in backticks)
+ * because it makes the question easier to read at a glance. ctx.ui.input titles
+ * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
+ * displayed prompt, and STRIP them to plain text for the editable input default
+ * and the persisted task file (which must stay ANSI-free).
+ */
+/** Minimal theme surface we need; ExtensionCommandContext['ui'].theme satisfies it. */
+export interface InlineMarkdownTheme {
+    bold(text: string): string;
+    fg(color: 'mdCode', text: string): string;
+}
+/** Render **bold** and `code` spans to themed terminal styling for display. */
+export declare function renderInlineMarkdown(text: string, theme: InlineMarkdownTheme): string;
+/** Strip **bold** and `code` markers to plain text (for defaults and storage). */
+export declare function stripInlineMarkdown(text: string): string;

package/dist/task/inline-markdown.js

@@ -0,0 +1,28 @@
+/**
+ * Inline-markdown helpers for the clarify/grill question dialogs.
+ *
+ * The model often wraps the core question in **bold** (and code in backticks)
+ * because it makes the question easier to read at a glance. ctx.ui.input titles
+ * accept ANSI styling, so we RENDER those spans to terminal bold/code for the
+ * displayed prompt, and STRIP them to plain text for the editable input default
+ * and the persisted task file (which must stay ANSI-free).
+ */
+const BOLD_SPAN = /\*\*(.+?)\*\*/g;
+const CODE_SPAN = /`([^`]+)`/g;
+/** Render **bold** and `code` spans to themed terminal styling for display. */
+export function renderInlineMarkdown(text, theme) {
+    return text
+        .replace(BOLD_SPAN, (_, b) => theme.bold(b))
+        .replace(CODE_SPAN, (_, c) => theme.fg('mdCode', c))
+        .replace(/\*\*/g, '') // drop stray/unbalanced bold markers
+        .replace(/`/g, ''); // drop stray backticks
+}
+/** Strip **bold** and `code` markers to plain text (for defaults and storage). */
+export function stripInlineMarkdown(text) {
+    return text
+        .replace(BOLD_SPAN, '$1')
+        .replace(CODE_SPAN, '$1')
+        .replace(/\*\*/g, '')
+        .replace(/`/g, '')
+        .trim();
+}

package/dist/task/orchestrator.d.ts

@@ -51,4 +51,32 @@ export declare class TaskRunner {
     run(): Promise<void>;
     private _deliverSpec;
 }
+export interface RunSingleTaskOptions {
+    /** Await the session going idle after the spec is delivered, so the caller
+     *  blocks until the agent has implemented it. Default false. */
+    waitForImplementation?: boolean;
+    /** Test seam: spawn function forwarded to TaskRunner. */
+    spawnFn?: SpawnFn;
+}
+export interface RunSingleTaskResult {
+    taskId: string;
+    ok: boolean;
+    sessionCancelled: boolean;
+    /**
+     * The session context the caller must use for any work after this call. A
+     * successful run replaces the session via ctx.newSession(), which leaves the
+     * caller's original ctx stale — this is the fresh replacement ctx and callers
+     * MUST adopt it (using the original throws "stale ctx"). On cancellation no
+     * replacement happened, so this is the original, still-live ctx. Optional
+     * only so test fakes that don't model session replacement can omit it.
+     */
+    ctx?: ExtensionCommandContext;
+}
+/**
+ * Run one prompt through the full single-task pipeline in a fresh session and
+ * deliver its spec. With waitForImplementation, block until the agent finishes
+ * implementing the delivered spec. Success is read off the produced task file's
+ * front-matter state (TaskRunner.run never throws).
+ */
+export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, opts?: RunSingleTaskOptions): Promise<RunSingleTaskResult>;
 export declare function registerTask(pi: ExtensionAPI): void;

package/dist/task/orchestrator.js

@@ -256,6 +256,46 @@ export class TaskRunner {
         }
     }
 }
+/**
+ * Run one prompt through the full single-task pipeline in a fresh session and
+ * deliver its spec. With waitForImplementation, block until the agent finishes
+ * implementing the delivered spec. Success is read off the produced task file's
+ * front-matter state (TaskRunner.run never throws).
+ */
+export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
+    let taskId = '';
+    // The newSession replacement ctx, captured so the caller can keep driving the
+    // UI after the original ctx is torn down. Defaults to the original for the
+    // cancellation path (where no replacement occurs).
+    let freshCtx = ctx;
+    const result = await ctx.newSession({
+        withSession: async (newCtx) => {
+            freshCtx = newCtx;
+            const runner = new TaskRunner(newCtx, cwd, rawPrompt, undefined, async (spec) => {
+                await newCtx.sendUserMessage(spec);
+                if (opts.waitForImplementation)
+                    await newCtx.waitForIdle();
+            }, opts.spawnFn);
+            await runner.run();
+            taskId = runner.taskId;
+        }
+    });
+    if (result.cancelled) {
+        // No replacement happened — the original ctx is still live.
+        return { taskId, ok: false, sessionCancelled: true, ctx };
+    }
+    let ok = false;
+    if (taskId) {
+        try {
+            const { frontMatter } = await readTaskFile(cwd, taskId);
+            ok = frontMatter.state === 'completed';
+        }
+        catch {
+            ok = false;
+        }
+    }
+    return { taskId, ok, sessionCancelled: false, ctx: freshCtx };
+}
 // ─── Command handlers ────────────────────────────────────────────────────────
 async function handleTask(args, ctx) {
     await ctx.waitForIdle();
@@ -266,15 +306,8 @@ async function handleTask(args, ctx) {
         ctx.ui.notify('Type your prompt after /task (use @ for file completion).', 'info');
         return;
     }
-    const result = await ctx.newSession({
-        withSession: async (newCtx) => {
-            const runner = new TaskRunner(newCtx, cwd, raw, undefined, async (spec) => {
-                await newCtx.sendUserMessage(spec);
-            });
-            await runner.run();
-        }
-    });
-    if (result.cancelled) {
+    const { sessionCancelled } = await runSingleTask(ctx, cwd, raw);
+    if (sessionCancelled) {
         ctx.ui.notify('Could not start a fresh session for /task.', 'warning');
     }
 }

package/dist/task/parsers.d.ts

@@ -15,10 +15,17 @@ export type AutoAnswer = {
     suggested?: string;
     raw: string;
 };
+/** One /task-auto clarify question with its model-recommended default answer. */
+export interface ClarifyQuestion {
+    question: string;
+    suggested?: string;
+}
 export declare const GRILL_LINE_RE: RegExp;
+export declare const SUGGESTED_LINE_RE: RegExp;
 export declare const TITLE_MAX_CHARS = 120;
 export declare function parseVerifyBlock(spec: string): VerifyCommand[] | null;
 export declare function parseGrillQuestions(raw: string): string[];
+export declare function parseClarifyList(raw: string): ClarifyQuestion[];
 export declare function parseAutoAnswer(raw: string): AutoAnswer;
 export declare function parseVerifyToolingOutput(output: string): {
     verified: string[];
@@ -28,5 +35,14 @@ export declare function parseVerifyToolingOutput(output: string): {
     }>;
 };
 export declare function isCritiqueClean(text: string): boolean;
+/**
+ * Drop any preamble the model emitted before the spec's GOAL header. The
+ * thinking model sometimes narrates ("Now I have all the context. Here's the
+ * rewritten spec:") before GOAL — the prompts forbid it, but the critique
+ * validator only checks for a VERIFY block, so it leaked into the delivered
+ * spec. We slice from the first line that begins a GOAL section so the spec
+ * starts at GOAL. No GOAL line → returned unchanged (validation then flags it).
+ */
+export declare function stripSpecPreamble(spec: string): string;
 export declare function validateSpecShape(spec: string): string | null;
 export declare function deriveTitle(refined: string): string;

package/dist/task/parsers.js

@@ -6,6 +6,7 @@
 import { MAX_GRILL_QUESTIONS } from './phases.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const GRILL_LINE_RE = /^\s*\d+[.)]\s+(.+)$/;
+export const SUGGESTED_LINE_RE = /^\s*SUGGESTED:\s*(.*)$/i;
 export const TITLE_MAX_CHARS = 120;
 // ─── Verify block parser ─────────────────────────────────────────────────────
 export function parseVerifyBlock(spec) {
@@ -49,6 +50,53 @@ export function parseGrillQuestions(raw) {
     }
     return out;
 }
+// ─── Clarify (/task-auto) parser ─────────────────────────────────────────────
+// Matches a "SUGGESTED:" marker anywhere in a string (not just line-start), so
+// we can recover a recommendation the model wrote inline on the question line
+// (e.g. "1. ...so this must be resolved. SUGGESTED: use polling.") rather than
+// on its own line.
+const INLINE_SUGGESTED_RE = /\bSUGGESTED:\s*/i;
+/** Split a question line's text into the question and any inline SUGGESTED default. */
+function splitInlineSuggested(text) {
+    const m = INLINE_SUGGESTED_RE.exec(text);
+    if (!m)
+        return { question: text.trim() };
+    const question = text.slice(0, m.index).trim();
+    const suggested = text.slice(m.index + m[0].length).trim();
+    return suggested.length > 0 ? { question, suggested } : { question };
+}
+// Parses the /task-auto clarify output: a numbered question list where each
+// question carries a "SUGGESTED: <default>" recommendation — either on its own
+// line below the question, or inline at the end of the question line. The first
+// SUGGESTED for a question wins; later ones are ignored. The literal token NONE
+// (its own line) means "no clarification needed" → [].
+//
+// Question/suggested text is returned VERBATIM (markdown intact). Inline
+// markdown is rendered for display / stripped for storage at the call site via
+// the helpers in inline-markdown.ts.
+export function parseClarifyList(raw) {
+    if (/^\s*NONE\s*$/m.test(raw))
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const q = GRILL_LINE_RE.exec(line);
+        if (q) {
+            if (out.length >= MAX_GRILL_QUESTIONS)
+                break;
+            out.push(splitInlineSuggested(q[1].trim()));
+            continue;
+        }
+        const s = SUGGESTED_LINE_RE.exec(line);
+        if (s && out.length > 0) {
+            const suggested = s[1].trim();
+            const last = out[out.length - 1];
+            if (suggested.length > 0 && last.suggested === undefined) {
+                last.suggested = suggested;
+            }
+        }
+    }
+    return out;
+}
 // ─── Auto-answer parser ──────────────────────────────────────────────────────
 export function parseAutoAnswer(raw) {
     const lines = raw
@@ -120,6 +168,28 @@ export function isCritiqueClean(text) {
     return /^CLEAN[.!]?$/i.test(firstLine);
 }
 // ─── Spec shape validator ────────────────────────────────────────────────────
+/**
+ * Drop any preamble the model emitted before the spec's GOAL header. The
+ * thinking model sometimes narrates ("Now I have all the context. Here's the
+ * rewritten spec:") before GOAL — the prompts forbid it, but the critique
+ * validator only checks for a VERIFY block, so it leaked into the delivered
+ * spec. We slice from the first line that begins a GOAL section so the spec
+ * starts at GOAL. No GOAL line → returned unchanged (validation then flags it).
+ */
+export function stripSpecPreamble(spec) {
+    const lines = spec.split('\n');
+    const idx = lines.findIndex(l => /^GOAL\b/i.test(l));
+    if (idx <= 0)
+        return spec;
+    // Only strip plain narration. If the lead-in is a markdown fence or a
+    // cat-heredoc wrapper, leave it untouched — that's a malformation
+    // validateSpecShape must reject (and compose must retry on), not something
+    // to silently unwrap into a passing spec.
+    const preamble = lines.slice(0, idx);
+    if (preamble.some(l => /^\s*```/.test(l) || /^\s*cat\s*<</.test(l)))
+        return spec;
+    return lines.slice(idx).join('\n');
+}
 export function validateSpecShape(spec) {
     const trimmed = spec.trim();
     if (trimmed.length === 0)

package/dist/task/phases.d.ts

@@ -6,11 +6,12 @@ import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { docsRaw, docsFocused } from '../workers/docs-core.js';
 import { fetchRaw, fetchFocused } from '../workers/fetch-core.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
+import { MAX_GRILL_QUESTIONS } from './prompts.js';
 import { type PhaseName } from './task-file.js';
 import { type WidgetState } from './widget.js';
 import { type AutoAnswer } from './parsers.js';
 import { type PhaseDeps } from './child-runner.js';
-export { MAX_GRILL_QUESTIONS } from './prompts.js';
+export { MAX_GRILL_QUESTIONS };
 export interface PhaseContext {
     cwd: string;
     id: string;