poly-weaver 0.8.1 → 0.9.0

package/dist/agents/interviewers/handler.d.ts

@@ -0,0 +1,21 @@
+import type { BaseStep, RetryFn, RoleHandler, StepContext, StepSignal } from "../../flow/types.js";
+import type { InterviewerDriver } from "./types.js";
+/** Thrown by the validation step inside the retry closure — retryable. */
+export declare class InterviewerValidationError extends Error {
+    constructor(message: string);
+}
+export declare class InterviewerRoleHandler implements RoleHandler {
+    private driver;
+    constructor(driver: InterviewerDriver);
+    execute(step: BaseStep, ctx: StepContext, retry: RetryFn): Promise<StepSignal>;
+    /**
+     * If a prior interviewer session exists (sidecar > snapshot) and its
+     * on-disk file is still present, set `ctx.sessionIds[sessionKey]` and
+     * return the validated session file path. Returning the path lets the
+     * caller hand it to driver.run() so the runner's resume fast path
+     * skips session-file discovery.
+     */
+    private maybeRestoreSessionId;
+    private findRestorableSessionIdFromSnapshots;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/agents/interviewers/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/interviewers/handler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,QAAQ,EACR,OAAO,EACP,WAAW,EACX,WAAW,EACX,UAAU,EACX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAoCD,qBAAa,sBAAuB,YAAW,WAAW;IAC5C,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEvC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;IAwHtB;;;;;;OAMG;YACW,qBAAqB;IAuDnC,OAAO,CAAC,oCAAoC;CAsB7C"}

package/dist/agents/interviewers/handler.js

@@ -0,0 +1,217 @@
+import { existsSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { bindSessionReporter, bindDriverRuntime, bindPtyBufferReporter, bindAttemptFailureReporter } from "../runner.js";
+/** Thrown by the validation step inside the retry closure — retryable. */
+export class InterviewerValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InterviewerValidationError";
+    }
+}
+async function readLiveSidecar(path) {
+    try {
+        const text = await readFile(path, "utf8");
+        const parsed = JSON.parse(text);
+        if (parsed &&
+            typeof parsed === "object" &&
+            typeof parsed.sessionId === "string" &&
+            typeof parsed.driver === "string" &&
+            typeof parsed.sessionKey === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        /* missing / unreadable — fine */
+    }
+    return undefined;
+}
+async function readFileMaybe(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export class InterviewerRoleHandler {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+    }
+    async execute(step, ctx, retry) {
+        const agentStep = step;
+        const sessionKey = agentStep.sessionShareKey ?? step.id;
+        const taskFile = ctx.artifacts.getFile(step.reads.task);
+        if (!taskFile) {
+            throw new Error("InterviewerRoleHandler: task artifact missing");
+        }
+        const specKey = step.writes.spec;
+        if (!specKey) {
+            throw new Error("InterviewerRoleHandler: step.writes.spec missing");
+        }
+        const specFile = join(ctx.sessionDir, "spec.md");
+        const markerFile = join(ctx.sessionDir, "spec.done");
+        const feedbackFile = step.reads.feedback
+            ? ctx.artifacts.getFile(step.reads.feedback)
+            : undefined;
+        bindSessionReporter(this.driver, ctx.lastStepSessionFilePaths);
+        bindPtyBufferReporter(this.driver, ctx);
+        bindAttemptFailureReporter(this.driver, ctx);
+        bindDriverRuntime(this.driver, {
+            output: ctx.output,
+            terminalHost: ctx.terminalHost,
+        });
+        const sidecarPath = ctx.persistentDir
+            ? join(ctx.persistentDir, "interviewer.live.json")
+            : undefined;
+        if (sidecarPath) {
+            this.driver.setLiveSidecar(sidecarPath, {
+                driver: agentStep.driver,
+                sessionKey,
+            });
+        }
+        const restoredSessionFile = await this.maybeRestoreSessionId(agentStep, ctx, sessionKey, sidecarPath);
+        let currentSessionId = ctx.sessionIds.get(sessionKey);
+        // Mode selection: (resumed?) × (feedback?). The chosen prompt always
+        // includes specFile/markerFile because cross-process resume rebuilds
+        // `sessionDir` under a fresh UUID — the new paths must overwrite the
+        // now-stale paths in the resumed conversation history. (In-process
+        // resume passes the same paths a second time, which is harmless.)
+        const initialMode = currentSessionId
+            ? (feedbackFile ? "revise" : "continue")
+            : (feedbackFile ? "rehydrate" : "initial");
+        let prevFailure;
+        const result = await retry("interviewer", async (attempt) => {
+            await rm(markerFile, { force: true });
+            let mode;
+            if (attempt === 1) {
+                mode = initialMode;
+            }
+            else if (prevFailure === "missing-spec") {
+                mode = "retry-missing-spec";
+            }
+            else {
+                mode = initialMode;
+            }
+            let driverRes;
+            try {
+                driverRes = await this.driver.run({
+                    mode,
+                    taskFile,
+                    specFile,
+                    markerFile,
+                    feedbackFile,
+                    resumeSessionId: currentSessionId,
+                    // First attempt only: feed the just-validated path back to the
+                    // runner so its resume fast path skips snapshot/discovery (the
+                    // provider appends to the existing file — no new file appears).
+                    resumeSessionFilePath: attempt === 1 && currentSessionId ? restoredSessionFile : undefined,
+                });
+            }
+            finally {
+                currentSessionId =
+                    (await this.driver.resolveCurrentSessionId()) ?? currentSessionId;
+                await this.driver.flushPendingSidecar();
+            }
+            const specText = (await readFileMaybe(specFile)) ?? "";
+            if (specText.trim().length === 0) {
+                prevFailure = "missing-spec";
+                throw new InterviewerValidationError("spec.md missing or empty");
+            }
+            prevFailure = undefined;
+            return { driverRes, specText };
+        });
+        const finalSessionId = currentSessionId ?? result.driverRes.sessionId;
+        if (finalSessionId) {
+            ctx.sessionIds.set(sessionKey, finalSessionId);
+        }
+        if (result.driverRes.sessionFilePath) {
+            ctx.lastStepSessionFilePaths?.push(result.driverRes.sessionFilePath);
+        }
+        ctx.artifacts.set(specKey, {
+            file: specFile,
+            text: result.specText,
+            meta: {
+                driver: this.driver.name,
+                iteration: ctx.totalIterations,
+                source: "interviewer",
+            },
+        });
+        if (sidecarPath) {
+            await rm(sidecarPath, { force: true }).catch(() => { });
+        }
+        return { kind: "continue" };
+    }
+    /**
+     * If a prior interviewer session exists (sidecar > snapshot) and its
+     * on-disk file is still present, set `ctx.sessionIds[sessionKey]` and
+     * return the validated session file path. Returning the path lets the
+     * caller hand it to driver.run() so the runner's resume fast path
+     * skips session-file discovery.
+     */
+    async maybeRestoreSessionId(step, ctx, sessionKey, sidecarPath) {
+        if (!step.restoreSessionIdsOnResume)
+            return undefined;
+        if (ctx.sessionIds.has(sessionKey))
+            return undefined;
+        if (sidecarPath) {
+            const sidecar = await readLiveSidecar(sidecarPath);
+            if (sidecar) {
+                if (sidecar.sessionKey !== sessionKey) {
+                    // stale sidecar from a different interviewer step — silent skip
+                }
+                else if (sidecar.driver !== step.driver) {
+                    ctx.output?.warn("interviewer: prior session unavailable (driver changed), starting fresh");
+                }
+                else {
+                    const path = this.driver.predictSessionFile?.(sidecar.sessionId);
+                    if (!path) {
+                        ctx.output?.warn("interviewer: provider does not support resume by id, starting fresh");
+                    }
+                    else if (!existsSync(path)) {
+                        ctx.output?.warn("interviewer: prior session file missing, starting fresh");
+                    }
+                    else {
+                        ctx.sessionIds.set(sessionKey, sidecar.sessionId);
+                        return path;
+                    }
+                }
+            }
+        }
+        const priorId = this.findRestorableSessionIdFromSnapshots(step, ctx, sessionKey);
+        if (!priorId)
+            return undefined;
+        const path = this.driver.predictSessionFile?.(priorId);
+        if (!path) {
+            ctx.output?.warn("interviewer: provider does not support resume by id, starting fresh");
+            return undefined;
+        }
+        if (!existsSync(path)) {
+            ctx.output?.warn("interviewer: prior session file missing, starting fresh");
+            return undefined;
+        }
+        ctx.sessionIds.set(sessionKey, priorId);
+        return path;
+    }
+    findRestorableSessionIdFromSnapshots(step, ctx, sessionKey) {
+        if (!ctx.completedSnapshots)
+            return undefined;
+        const seqsDesc = [...ctx.completedSnapshots.keys()].sort((a, b) => b - a);
+        for (const seq of seqsDesc) {
+            const snap = ctx.completedSnapshots.get(seq);
+            if (snap.role !== "interviewer")
+                continue;
+            const priorId = snap.sessionIds?.[sessionKey];
+            if (!priorId)
+                continue;
+            if (snap.driver !== step.driver) {
+                ctx.output?.warn(`interviewer: prior session unavailable (driver changed ${snap.driver} → ${step.driver}), starting fresh`);
+                return undefined;
+            }
+            return priorId;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=handler.js.map

package/dist/agents/interviewers/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/agents/interviewers/handler.ts"],"names":[],"mappings":"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"}

package/dist/agents/interviewers/index.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderStrategy } from "../../providers/types.js";
+import type { DriverName } from "../../flow/types.js";
+import type { InterviewerDriver, InterviewerPromptSet } from "./types.js";
+export { interviewer } from "./dsl.js";
+export { InterviewerRoleHandler } from "./handler.js";
+export { defaultInterviewerPrompts } from "./prompts.js";
+export type { InterviewerDriver, InterviewerMode, InterviewerPromptSet, InterviewerRunOpts, InterviewResult, InterviewerLiveSidecarMeta, } from "./types.js";
+export type InterviewerFactory = (workdir: string, prompts?: InterviewerPromptSet) => InterviewerDriver;
+export declare const registerProvider: (name: DriverName, strategy: ProviderStrategy) => void;
+export declare const registerFactory: (name: string, factory: InterviewerFactory) => void, availableDrivers: () => string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/interviewers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/interviewers/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,oBAAoB,KAC3B,iBAAiB,CAAC;AAiBvB,eAAO,MAAM,gBAAgB,EAA2B,CACtD,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,gBAAgB,KACvB,IAAI,CAAC;AACV,eAAO,MAAQ,eAAe,uDAAE,gBAAgB,gBAAQ,CAAC"}

package/dist/agents/interviewers/index.js

@@ -0,0 +1,16 @@
+import { InterviewerAdapter } from "./adapter.js";
+import { InterviewerRoleHandler } from "./handler.js";
+import { createRoleModule } from "../registry.js";
+import { defaultInterviewerPrompts } from "./prompts.js";
+export { interviewer } from "./dsl.js";
+export { InterviewerRoleHandler } from "./handler.js";
+export { defaultInterviewerPrompts } from "./prompts.js";
+const mod = createRoleModule({
+    roleName: "interviewer",
+    fromFactory: (factory, workdir) => factory(workdir, defaultInterviewerPrompts),
+    fromProvider: (strategy, workdir, opts) => new InterviewerAdapter(strategy, workdir, defaultInterviewerPrompts, opts?.yolo, opts?.model, opts?.effort),
+    toHandler: (driver) => new InterviewerRoleHandler(driver),
+});
+export const registerProvider = mod.registerProvider;
+export const { registerFactory, availableDrivers } = mod;
+//# sourceMappingURL=index.js.map

package/dist/agents/interviewers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/interviewers/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAezD,MAAM,GAAG,GAAG,gBAAgB,CAAwC;IAClE,QAAQ,EAAE,aAAa;IACvB,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC9E,YAAY,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CACxC,IAAI,kBAAkB,CACpB,QAAQ,EACR,OAAO,EACP,yBAAyB,EACzB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,MAAM,CACb;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,sBAAsB,CAAC,MAAM,CAAC;CAC1D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,gBAG3B,CAAC;AACV,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,GAAG,CAAC"}

package/dist/agents/interviewers/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { InterviewerPromptSet } from "./types.js";
+export declare const defaultInterviewerPrompts: InterviewerPromptSet;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/agents/interviewers/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/agents/interviewers/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA2FvD,eAAO,MAAM,yBAAyB,EAAE,oBAMvC,CAAC"}

package/dist/agents/interviewers/prompts.js

@@ -0,0 +1,73 @@
+const INTERVIEW_GUIDELINES = [
+    "Conduct a requirements interview or bug clarification with the user. Your job is to understand WHAT they want or what is broken - not HOW to fix or build it.",
+    "Ask focused questions until you understand the user's goal, the success criteria, the in/out of scope boundary, and any constraints. You decide the cadence and how many questions to ask per turn.",
+    "Keep grilling until the requirements are clear.",
+    "For bug-fix tasks, attempt to reproduce the bug locally before writing the spec; reproduction steps and observed behavior belong in the spec.",
+].join(" ");
+const GUARDRAILS = [
+    "Strict rules:",
+    "- Do not propose a design, implementation, file edits, or code changes.",
+    "- Do not edit any source files. The only file you may write is the spec and the marker file.",
+    "- Do not ask the user meta questions (\"want me to revise?\", \"does this look good?\", \"should I continue?\") or ask the user to review, approve, or confirm the spec before writing the marker file - the user reviews the spec externally after the interview ends.",
+    "- Do not write the marker file while any open questions remain. The spec as it exists on disk at the moment you write the marker file is the final committed answer. Make sure it is complete before writing the marker.",
+    "- End your turn immediately after writing the marker file. No follow-up commentary.",
+].join("\n");
+function initial(taskFile, specFile, markerFile) {
+    return [
+        `Read the user's task: ${taskFile}`,
+        `Write a requirements spec to: ${specFile}`,
+        "",
+        INTERVIEW_GUIDELINES,
+        "",
+        "You may rewrite the spec on disk as the conversation progresses.",
+        "",
+        `When - and only when - the requirements are fully clear, write the marker file at: ${markerFile}`,
+        "The marker may be empty; its presence signals you are done.",
+        "",
+        GUARDRAILS,
+    ].join("\n");
+}
+function continueInterview(specFile, markerFile) {
+    return [
+        "Continue the interview.",
+        "",
+        `Current spec file: ${specFile}`,
+        `When the spec reflects the user's intent, write the marker file at: ${markerFile} and end your turn.`,
+    ].join("\n");
+}
+function retryMissingSpec(specFile, markerFile) {
+    return [
+        `Your previous turn wrote the marker file but the spec file at ${specFile} is missing or empty.`,
+        "",
+        `Write the complete spec to ${specFile}, then re-write the marker file at ${markerFile}.`,
+    ].join("\n");
+}
+function revise(feedbackFile, specFile, markerFile) {
+    return [
+        `The user reviewed the spec and left feedback: ${feedbackFile}`,
+        "",
+        `Revise the spec at ${specFile} to address the feedback.`,
+        `When done, write the marker file at: ${markerFile} and end your turn.`,
+    ].join("\n");
+}
+function rehydrate(taskFile, specFile, markerFile, feedbackFile) {
+    const lines = [
+        "You are resuming a requirements interview that was interrupted.",
+        "",
+        `Original task: ${taskFile}`,
+        `Current requirements spec on disk: ${specFile} (may be partial or empty)`,
+    ];
+    if (feedbackFile) {
+        lines.push(`User feedback on the prior spec: ${feedbackFile}`);
+    }
+    lines.push("", INTERVIEW_GUIDELINES, "", "Read those files, then continue the interview from where it left off. You may update the spec on disk as the conversation progresses.", `When the spec is complete, write the marker file at: ${markerFile} and end your turn.`, "", GUARDRAILS);
+    return lines.join("\n");
+}
+export const defaultInterviewerPrompts = {
+    initial,
+    continueInterview,
+    retryMissingSpec,
+    revise,
+    rehydrate,
+};
+//# sourceMappingURL=prompts.js.map

package/dist/agents/interviewers/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/agents/interviewers/prompts.ts"],"names":[],"mappings":"AAEA,MAAM,oBAAoB,GAAG;IAC3B,+JAA+J;IAC/J,qMAAqM;IACrM,iDAAiD;IACjD,+IAA+I;CAChJ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,MAAM,UAAU,GAAG;IACjB,eAAe;IACf,yEAAyE;IACzE,8FAA8F;IAC9F,yQAAyQ;IACzQ,0NAA0N;IAC1N,qFAAqF;CACtF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,SAAS,OAAO,CAAC,QAAgB,EAAE,QAAgB,EAAE,UAAkB;IACrE,OAAO;QACL,yBAAyB,QAAQ,EAAE;QACnC,iCAAiC,QAAQ,EAAE;QAC3C,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,kEAAkE;QAClE,EAAE;QACF,sFAAsF,UAAU,EAAE;QAClG,6DAA6D;QAC7D,EAAE;QACF,UAAU;KACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAgB,EAAE,UAAkB;IAC7D,OAAO;QACL,yBAAyB;QACzB,EAAE;QACF,sBAAsB,QAAQ,EAAE;QAChC,uEAAuE,UAAU,qBAAqB;KACvG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB,EAAE,UAAkB;IAC5D,OAAO;QACL,iEAAiE,QAAQ,uBAAuB;QAChG,EAAE;QACF,8BAA8B,QAAQ,sCAAsC,UAAU,GAAG;KAC1F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CACb,YAAoB,EACpB,QAAgB,EAChB,UAAkB;IAElB,OAAO;QACL,iDAAiD,YAAY,EAAE;QAC/D,EAAE;QACF,sBAAsB,QAAQ,2BAA2B;QACzD,wCAAwC,UAAU,qBAAqB;KACxE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAChB,QAAgB,EAChB,QAAgB,EAChB,UAAkB,EAClB,YAAgC;IAEhC,MAAM,KAAK,GAAG;QACZ,iEAAiE;QACjE,EAAE;QACF,kBAAkB,QAAQ,EAAE;QAC5B,sCAAsC,QAAQ,4BAA4B;KAC3E,CAAC;IACF,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,oCAAoC,YAAY,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,KAAK,CAAC,IAAI,CACR,EAAE,EACF,oBAAoB,EACpB,EAAE,EACF,uIAAuI,EACvI,wDAAwD,UAAU,qBAAqB,EACvF,EAAE,EACF,UAAU,CACX,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAyB;IAC7D,OAAO;IACP,iBAAiB;IACjB,gBAAgB;IAChB,MAAM;IACN,SAAS;CACV,CAAC"}

package/dist/agents/interviewers/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Modes the handler can drive the interviewer into. The adapter selects
+ * the prompt by mode; freshFallbackPrompt selection (see adapter) handles
+ * the resume-failure path.
+ */
+export type InterviewerMode = "initial" | "continue" | "retry-missing-spec" | "revise" | "rehydrate";
+export interface InterviewerPromptSet {
+    initial: (taskFile: string, specFile: string, markerFile: string) => string;
+    continueInterview: (specFile: string, markerFile: string) => string;
+    retryMissingSpec: (specFile: string, markerFile: string) => string;
+    revise: (feedbackFile: string, specFile: string, markerFile: string) => string;
+    rehydrate: (taskFile: string, specFile: string, markerFile: string, feedbackFile: string | undefined) => string;
+}
+export interface InterviewerLiveSidecarMeta {
+    driver: string;
+    sessionKey: string;
+}
+export interface InterviewerRunOpts {
+    mode: InterviewerMode;
+    taskFile: string;
+    specFile: string;
+    markerFile: string;
+    feedbackFile?: string;
+    resumeSessionId?: string;
+    /**
+     * Known on-disk session file path for `resumeSessionId`. When the handler
+     * has just validated a provider-predicted file before driver.run(), it
+     * passes the path here so the runner can skip session-file discovery
+     * (which otherwise hangs waiting for a *new* file that never appears when
+     * the provider appends to the existing one).
+     */
+    resumeSessionFilePath?: string;
+}
+export interface InterviewResult {
+    sessionId: string;
+    sessionFilePath?: string;
+    rawText?: string;
+    agentUsed: string;
+}
+export interface InterviewerDriver {
+    readonly name: string;
+    run(opts: InterviewerRunOpts): Promise<InterviewResult>;
+    getSessionId(): string | undefined;
+    /** Resolve session id even if `run()` threw — delegates to provider extractSessionId. */
+    resolveCurrentSessionId(): Promise<string | undefined>;
+    /** Register sidecar destination. Adapter chains the write into its existing callback. */
+    setLiveSidecar(sidecarPath: string, meta: InterviewerLiveSidecarMeta): void;
+    /** Await any in-flight sidecar write (called by handler `finally` so Ctrl+C can't lose it). */
+    flushPendingSidecar(): Promise<void>;
+    /** Optional: predict the on-disk session file path for an id. */
+    predictSessionFile?(sessionId: string): string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/interviewers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agents/interviewers/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,UAAU,GACV,oBAAoB,GACpB,QAAQ,GACR,WAAW,CAAC;AAEhB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5E,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACpE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACnE,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/E,SAAS,EAAE,CACT,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GAAG,SAAS,KAC7B,MAAM,CAAC;CACb;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACxD,YAAY,IAAI,MAAM,GAAG,SAAS,CAAC;IACnC,yFAAyF;IACzF,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvD,yFAAyF;IACzF,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC5E,+FAA+F;IAC/F,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,iEAAiE;IACjE,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC5D"}

package/dist/agents/interviewers/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/interviewers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agents/interviewers/types.ts"],"names":[],"mappings":""}

package/dist/agents/planners/adapter.d.ts

@@ -12,7 +12,7 @@ type PlannerRunOptions = {
 export declare function selectPlannerPrompt(taskFile: string, opts: PlannerRunOptions, prompts?: PlannerPromptSet): string;
 export declare class PlannerAdapter extends BaseAdapter implements PlannerDriver {
     private readonly prompts?;
-    constructor(strategy: ProviderStrategy, workdir: string, prompts?: PlannerPromptSet | undefined, yolo?: boolean);
+    constructor(strategy: ProviderStrategy, workdir: string, prompts?: PlannerPromptSet | undefined, yolo?: boolean, model?: string, effort?: string);
     run(taskFile: string, opts: PlannerRunOptions): Promise<PlanResult>;
 }
 export {};

package/dist/agents/planners/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,gBAAwC,GAChD,MAAM,CAmCR;AAED,qBAAa,cAAe,SAAQ,WAAY,YAAW,aAAa;IAIpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,EACE,OAAO,CAAC,EAAE,gBAAgB,YAAA,EAC3C,IAAI,CAAC,EAAE,OAAO;IAKV,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC;CAoDvB"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,KAAK,iBAAiB,GAAG;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,gBAAwC,GAChD,MAAM,CAmCR;AAED,qBAAa,cAAe,SAAQ,WAAY,YAAW,aAAa;IAIpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAFzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,EACE,OAAO,CAAC,EAAE,gBAAgB,YAAA,EAC3C,IAAI,CAAC,EAAE,OAAO,EACd,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM;IAKX,GAAG,CACP,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,UAAU,CAAC;CAoDvB"}

package/dist/agents/planners/adapter.js

@@ -19,8 +19,8 @@ export function selectPlannerPrompt(taskFile, opts, prompts = defaultPlannerProm
 }
 export class PlannerAdapter extends BaseAdapter {
     prompts;
-    constructor(strategy, workdir, prompts, yolo) {
-        super(strategy, workdir, yolo);
+    constructor(strategy, workdir, prompts, yolo, model, effort) {
+        super(strategy, workdir, yolo, model, effort);
         this.prompts = prompts;
     }
     async run(taskFile, opts) {

package/dist/agents/planners/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/agents/planners/adapter.ts"],"names":[],"mappings":"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"}

package/dist/agents/planners/dsl.d.ts

@@ -2,7 +2,11 @@ import { type WhenCondition, type PhaseLabelSpec } from "../../flow/dsl.js";
 import type { AgentStep } from "../../flow/types.js";
 export declare function plan(opts: {
     driver: string;
-    reads: Record<string, string>;
+    reads: Record<string, string> & {
+        task?: string;
+        spec?: string;
+        verdict?: string;
+    };
     writes: Record<string, string>;
     id?: string;
     feedbackToTask?: boolean;

package/dist/agents/planners/dsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,wBAAgB,IAAI,CAAC,IAAI,EAAE;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B,GAAG,SAAS,CAMZ"}
+{"version":3,"file":"dsl.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/dsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,wBAAgB,IAAI,CAAC,IAAI,EAAE;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B,GAAG,SAAS,CAMZ"}

package/dist/agents/planners/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAQ7B,qBAAa,kBAAmB,YAAW,WAAW;IAGxC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,WAAW,CAAK;gBAEJ,MAAM,EAAE,aAAa;IAEnC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;CA2FvB"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/agents/planners/handler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAQ7B,qBAAa,kBAAmB,YAAW,WAAW;IAGxC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,WAAW,CAAK;gBAEJ,MAAM,EAAE,aAAa;IAEnC,OAAO,CACX,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,UAAU,CAAC;CAiHvB"}

package/dist/agents/planners/handler.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { appendClarifications } from "../../prompts.js";
 import { readPlanFromContract, removeFileIfExists, } from "../../orchestrator.js";
 import { TASK, } from "../../flow/types.js";
-import { bindSessionReporter, bindDriverRuntime, bindPtyBufferReporter } from "../runner.js";
+import { bindSessionReporter, bindDriverRuntime, bindPtyBufferReporter, bindAttemptFailureReporter } from "../runner.js";
 /** Return the plan file path for a given version (1-based). */
 function planFileForVersion(root, version) {
     return join(root, `plan-v${version}.md`);
@@ -15,9 +15,10 @@ export class PlannerRoleHandler {
         this.driver = driver;
     }
     async execute(step, ctx, retry) {
-        const taskFile = ctx.artifacts.getFile(step.reads.task);
-        if (!taskFile)
-            throw new Error("PlannerRoleHandler: task artifact missing");
+        const specFile = (step.reads.spec && ctx.artifacts.getFile(step.reads.spec))
+            ?? (step.reads.task && ctx.artifacts.getFile(step.reads.task));
+        if (!specFile)
+            throw new Error("PlannerRoleHandler: spec or task artifact missing");
         // Read feedback from verdict artifact (set by incorporateFeedback)
         const verdictArtifact = step.reads.verdict
             ? ctx.artifacts.get(step.reads.verdict) : undefined;
@@ -36,14 +37,20 @@ export class PlannerRoleHandler {
             ctx.sessionIds.delete(sessionKey);
         }
         const resumeSessionId = ctx.sessionIds.get(sessionKey);
-        const implReplan = step.reads.task !== TASK;
+        // implReplan is the "impl-review revising the plan" case: a planner step
+        // whose task input is remapped to something other than TASK (and whose
+        // input is therefore not the original task). Spec-driven planning still
+        // reads `spec`, NOT a remapped task, so it must NOT be flagged as
+        // impl-replan.
+        const implReplan = !step.reads.spec && step.reads.task !== undefined && step.reads.task !== TASK;
         bindSessionReporter(this.driver, ctx.lastStepSessionFilePaths);
         bindPtyBufferReporter(this.driver, ctx);
+        bindAttemptFailureReporter(this.driver, ctx);
         bindDriverRuntime(this.driver, { output: ctx.output, terminalHost: ctx.terminalHost });
         const { planResult, planText, actualPlanFile } = await retry("planner", async (attempt) => {
             if (attempt > 1)
                 await removeFileIfExists(outputPlanFile);
-            const planResult = await this.driver.run(taskFile, {
+            const planResult = await this.driver.run(specFile, {
                 outputPlanFile,
                 resumeSessionId: attempt === 1 ? resumeSessionId : undefined,
                 planFile: feedbackSource ? prevPlanFile : undefined,
@@ -69,25 +76,37 @@ export class PlannerRoleHandler {
         if (planResult.sessionId) {
             ctx.sessionIds.set(sessionKey, planResult.sessionId);
         }
-        // Merge in-planning clarifications (AskUserQuestion Q&A)
-        // Only write back to the actual task artifact, not remapped inputs like "plan".
-        if (planResult.clarifications?.length && step.reads.task === TASK) {
-            const taskArtifact = ctx.artifacts.get(step.reads.task);
-            let taskContent = taskArtifact?.text ?? "";
-            const entries = planResult.clarifications.map((c) => ({
-                type: "qa",
-                clarification: c,
-            }));
-            const result = appendClarifications(taskContent, entries, ctx.nextClarificationNumber);
-            taskContent = result.content;
-            ctx.nextClarificationNumber = result.nextNumber;
-            ctx.artifacts.set(step.reads.task, {
-                ...taskArtifact,
-                text: taskContent,
-                file: taskArtifact?.file,
-            });
-            if (taskArtifact?.file) {
-                await writeFile(taskArtifact.file, taskContent, "utf-8");
+        // Merge in-planning clarifications (AskUserQuestion Q&A) into the
+        // planner's input baseline: spec if present, task otherwise.
+        if (planResult.clarifications?.length) {
+            const specKey = step.reads.spec;
+            const taskKey = step.reads.task;
+            const specArtifact = specKey ? ctx.artifacts.get(specKey) : undefined;
+            const baseline = specArtifact?.text != null
+                ? { key: specKey, artifact: specArtifact }
+                : (() => {
+                    if (!taskKey || taskKey !== TASK)
+                        return null;
+                    const taskArtifact = ctx.artifacts.get(taskKey);
+                    return taskArtifact?.text != null
+                        ? { key: taskKey, artifact: taskArtifact }
+                        : null;
+                })();
+            if (baseline) {
+                const entries = planResult.clarifications.map((c) => ({
+                    type: "qa",
+                    clarification: c,
+                }));
+                const result = appendClarifications(baseline.artifact.text, entries, ctx.nextClarificationNumber);
+                ctx.nextClarificationNumber = result.nextNumber;
+                ctx.artifacts.set(baseline.key, {
+                    ...baseline.artifact,
+                    text: result.content,
+                    file: baseline.artifact.file,
+                });
+                if (baseline.artifact.file) {
+                    await writeFile(baseline.artifact.file, result.content, "utf-8");
+                }
             }
         }
         return { kind: "continue" };