@yagni-app/code-staging 1.2.3-staging.1575.1 → 1.2.3-staging.1580.1

package/dist/extension/index.d.ts

@@ -166,6 +166,8 @@ export type { MakeRecordContextToolOptions } from "./recordContextTool.js";
 export { makeRecordDecisionTool } from "./recordDecisionTool.js";
 export type { MakeRecordDecisionToolOptions } from "./recordDecisionTool.js";
 export { makeSuggestNextWorkTool, defaultNextAction } from "./nextWorkTool.js";
+export { makePrototypeCreateTool, makePrototypeAttachTool, makePrototypeReadTool, makePrototypeDraftTool, makePrototypeVerificationTool, makePrototypeReviseTool, makePrototypeListTool, makePrototypeShareTool, } from "./prototypeTool.js";
+export type { MakePrototypeToolOptions, PrototypeSummary } from "./prototypeTool.js";
 export type { MakeNextWorkToolOptions, DefaultNextAction, NextActionOption, } from "./nextWorkTool.js";
 export { recordDecision } from "./recordDecisionTool.js";
 export type { RecordDecisionParams } from "./recordDecisionTool.js";

package/dist/extension/index.js

@@ -13,8 +13,10 @@ import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js
 import { makeReviewBusinessMatchTool } from "./reviewTool.js";
 import { registerCmuxBridge } from "./cmux/index.js";
 import { makeRecordEngineeringContextTool } from "./recordContextTool.js";
+import { makePrototypeVerifyTool } from "./prototypeVerify.js";
 import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
+import { makePrototypeCreateTool, makePrototypeAttachTool, makePrototypeReadTool, makePrototypeDraftTool, makePrototypeVerificationTool, makePrototypeReviseTool, makePrototypeListTool, makePrototypeShareTool, } from "./prototypeTool.js";
 import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_DRIVER_GROUNDING_FREE, YAGNI_IDENTITY_GROUNDING_FREE, YAGNI_IDENTITY_ULTRA, YAGNI_IDENTITY_ULTRA_GROUNDING_FREE } from "./branding.js";
 import { claudeRulesSection } from "./claudeRules.js";
 import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadOwnerRootFor, scratchpadSection } from "./scratchpad.js";
@@ -408,6 +410,25 @@ export async function registerYagni(pi, deps = {}) {
             onRecorded: (id) => recordedThisSession.add(id),
         }));
     }
+    if (!evalMode) {
+        // Prototypes v1: create/revise/list/share runnable single-file HTML
+        // Prototypes through the app's REST API. Workspace writes, so gated out of
+        // eval mode with the other external-side-effect tools.
+        pi.registerTool(makePrototypeReadTool(toolOpts));
+        pi.registerTool(makePrototypeDraftTool({ ...toolOpts, getSessionId: () => env.YAGNI_SESSION_ID }));
+        pi.registerTool(makePrototypeVerificationTool(toolOpts));
+        pi.registerTool(makePrototypeVerifyTool(toolOpts));
+        pi.registerTool(makePrototypeCreateTool({ ...toolOpts, getSessionId: () => env.YAGNI_SESSION_ID }));
+        pi.registerTool(makePrototypeAttachTool(toolOpts));
+        pi.registerTool(makePrototypeReviseTool(toolOpts));
+        pi.registerTool(makePrototypeListTool(toolOpts));
+        pi.registerTool(makePrototypeShareTool(toolOpts));
+    }
+    else if (env.YAGNI_MISSION_DIR && env.YAGNI_RUN_ID) {
+        // The server authorizes only exact revisions in this Run's approved packet.
+        pi.registerTool(makePrototypeReadTool(toolOpts));
+        pi.registerTool(makePrototypeVerifyTool(toolOpts));
+    }
     // YAG-574: the silent-turn reminder, driver-only. A child/subagent/advisor
     // process has no direct user to answer, so it is never nudged (same gating
     // as the delegation identity in branding.ts); eval mode is untouched so its
@@ -444,6 +465,7 @@ export async function registerYagni(pi, deps = {}) {
     // map → plan → implement → review → fix, each child grounded by inheritance.
     registerGoCommand(pi, {
         childUsage,
+        canPrepareDesign: () => !evalMode && modeHolder.get() === "auto",
         attribution,
         // The grounding switch threads into every /go run: `grounded: false`
         // selects the existing blind personas + blind lens clauses (the M6
@@ -2029,6 +2051,8 @@ export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 export { makeRecordDecisionTool } from "./recordDecisionTool.js";
 export { makeSuggestNextWorkTool, defaultNextAction } from "./nextWorkTool.js";
+// Prototypes v1: the four prototype tools (create/revise/list/share).
+export { makePrototypeCreateTool, makePrototypeAttachTool, makePrototypeReadTool, makePrototypeDraftTool, makePrototypeVerificationTool, makePrototypeReviseTool, makePrototypeListTool, makePrototypeShareTool, } from "./prototypeTool.js";
 export { recordDecision } from "./recordDecisionTool.js";
 // Onramp Door B (as amended by ADR-0033): the first-run welcome (write-free,
 // free text first-class) + the explicit /setup-team drafting flow.

package/dist/extension/permission/gate.js

@@ -51,9 +51,9 @@ export function createModeHolder(initial = "auto") {
     };
 }
 export const DEFAULT_PERMISSION_POLICY = {
-    planBlockTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status"],
-    reviewConfirmTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status"],
-    alwaysConfirmTools: ["file_ticket", "update_ticket_status"],
+    planBlockTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status", "prototype_share", "prototype_create", "prototype_attach", "prototype_revise", "prototype_draft", "prototype_verification", "prototype_verify"],
+    reviewConfirmTools: ["write", "edit", "bash", "file_ticket", "update_ticket_status", "prototype_share", "prototype_create", "prototype_attach", "prototype_revise", "prototype_draft", "prototype_verification", "prototype_verify"],
+    alwaysConfirmTools: ["file_ticket", "update_ticket_status", "prototype_share"],
 };
 export function allowRuleFloorVerdict(toolName, params, mode, policy) {
     // Floor 0 — plan mode: the mode's contract (no mutations without Guardian

package/dist/extension/pipeline/goCommand.d.ts

@@ -60,6 +60,7 @@
  */
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import type { SpendResponse } from "../costHud.js";
+import { draftPrototype } from "../prototypeTool.js";
 import { type CrashReporter } from "../crashReport.js";
 import { runFinish as defaultRunFinish } from "./finish.js";
 import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
@@ -144,6 +145,8 @@ export interface RegisterGoDeps {
      * test) simply means "not ultra", which is today's behavior.
      */
     isUltra?: () => boolean;
+    canPrepareDesign?: () => boolean;
+    draftPrototype?: typeof draftPrototype;
     /**
      * The boot-time `grounding` settings switch, threaded into the orchestrator's
      * `grounded` flag: false runs the whole pipeline on the existing blind

package/dist/extension/pipeline/goCommand.js

@@ -69,6 +69,7 @@ import { RunState } from "./runState.js";
 import { aggregateRunUsage } from "./budget.js";
 import { formatRunCostTable } from "./runCostTable.js";
 import { makeCombinedCheckpointStore, makeFileCheckpointStore, makePiJournalCheckpointStore, } from "./checkpoint.js";
+import { absoluteUrl, draftPrototype } from "../prototypeTool.js";
 import { getToken as defaultGetToken, resolveBaseUrl } from "../config.js";
 import { makeCrashReporter } from "../crashReport.js";
 import { logEvent } from "../errorSink.js";
@@ -785,6 +786,35 @@ export function registerGoCommand(pi, deps = {}) {
                     let result = await runPipeline(ticket, {
                         cwd: runCwd,
                         signal: runSignal,
+                        // Interactive /go tracks no backend work item (#2134), so the draft
+                        // is private to this session and keyed on the run: a resumed run
+                        // reuses its prototype instead of drafting a second one.
+                        ...(deps.canPrepareDesign?.() ? {
+                            prepareDesign: async ({ ticket: designTicket, exploration, signal }) => {
+                                if (!deps.canPrepareDesign?.())
+                                    return undefined;
+                                const baseUrl = deps.baseUrl ?? resolveBaseUrl();
+                                try {
+                                    const draft = await (deps.draftPrototype ?? draftPrototype)({ baseUrl, getToken: deps.getToken ?? defaultGetToken }, {
+                                        title: designTicket.slice(0, 160), spec: `${designTicket}\n\nRepository exploration:\n${exploration}`,
+                                        sessionId: (deps.env ?? process.env).YAGNI_SESSION_ID,
+                                        automatic: true, requestKey: `go:${sessionKey}`,
+                                    }, signal);
+                                    if (draft.reference) {
+                                        notify(`Prototype ready: ${absoluteUrl(baseUrl, draft.prototype?.url ?? draft.reference.url ?? `/prototypes/${draft.reference.prototypeId}`)}`, "info");
+                                        return `## Prototype design reference\n${JSON.stringify(draft.reference)}\nRead this exact revision with prototype_read. Review it with the plan. Implement with the repository's real components. Preserve this reference through implementation and review. Run prototype_verify against the implemented local app with agreed interaction states; it captures mobile/desktop screenshots and records observed checks or explicitly unverified when no browser is available. Visually inspect those screenshots against this design and document intentional departures. Document intentional departures. Never substitute a newer revision or share automatically.`;
+                                    }
+                                    if (draft.status === "failed")
+                                        notify("Prototype drafting failed. Continue without it or retry with prototype_draft before approving the plan.", "warning");
+                                    return undefined;
+                                }
+                                catch {
+                                    if (!signal?.aborted)
+                                        notify("Prototype drafting unavailable. Continue without it or retry before plan approval.", "warning");
+                                    return undefined;
+                                }
+                            },
+                        } : {}),
                         fanout: fanoutMode,
                         grounded: goGrounded,
                         ...(isUltra ? { isUltra } : {}),

package/dist/extension/pipeline/orchestrator.d.ts

@@ -32,6 +32,12 @@ import { type VerifyOutcome, type WorkstreamCheckResult, type WorkstreamCheckTar
 import { snapshotWorkspace as defaultSnapshotWorkspace } from "./workspace.js";
 import { type CheckpointStore, type FanoutBudgetVerdict, type FanoutMode, type PipelineStage, type JsonEvent, type PipelineProgress, type PipelineResult, type ResiliencePolicy, type ResumePlan, type StageId, type StageResult, type StageTag } from "./types.js";
 export interface RunPipelineDeps {
+    /** Bounded external design preparation; never runs inside the read-only planner or approved missions. */
+    prepareDesign?: (input: {
+        ticket: string;
+        exploration: string;
+        signal?: AbortSignal;
+    }) => Promise<string | undefined>;
     cwd: string;
     signal?: AbortSignal;
     runStage?: typeof defaultRunStage;

package/dist/extension/pipeline/orchestrator.js

@@ -335,6 +335,11 @@ export async function runPipeline(ticket, deps) {
     const rounds = resume ? [...resume.priorRounds] : [];
     let round = resume ? resume.round : 1;
     let reviewInput = resume ? resume.reviewInput : "";
+    const designMarker = "## Pinned design context";
+    const resumedDesignOffset = reviewInput.indexOf(designMarker);
+    let designContext = mission?.plan
+        ? `${designMarker}\nApproved mission plan (preserve exact prototype references):\n${mission.plan}`
+        : resumedDesignOffset >= 0 ? reviewInput.slice(resumedDesignOffset) : undefined;
     let stopReason = "clean";
     // P4: honest note carried out when the verify gate could not give a verdict on
     // the final round (no command / unrunnable), so /go never claims a build it did
@@ -749,6 +754,12 @@ export async function runPipeline(ticket, deps) {
         baselinePaths = parseChangedPaths(beforeBuild.status);
         // Sequential build half — stop at the first failure (mirrors the chain).
         for (const stage of buildStages) {
+            if (stage.id === "plan" && !mission && deps.prepareDesign && !deps.signal?.aborted && !overBudget()) {
+                const prepared = await deps.prepareDesign({ ticket: promptTicket, exploration: previous ?? "", signal: deps.signal });
+                designContext = prepared ? `${designMarker}\n${prepared}` : undefined;
+                if (designContext)
+                    previous = `${previous ?? ""}\n\n${designContext}`;
+            }
             progress({ kind: "stage_start", stageId: stage.id });
             stageEvent(stage.id, "start");
             // The implement stage is a DIAMOND (partition → parallel builders →
@@ -839,12 +850,12 @@ export async function runPipeline(ticket, deps) {
             progress({ kind: "stage_done", stageId: stage.id });
             // The plan finish carries its finalOutput so /go can record the plan onto the
             // work item; no other boundary streams the full stage text.
-            stageEvent(stage.id, "finish", stage.id === "plan" ? { output: r.finalOutput } : undefined);
+            stageEvent(stage.id, "finish", stage.id === "plan" ? { output: designContext ? `${r.finalOutput}\n\n${designContext}` : r.finalOutput } : undefined);
             // The map brief is the partitioner's repo context on an interactive run
             // (mission runs skip map and hand it the injected memo instead).
             if (stage.id === "map")
                 mapBrief = r.finalOutput;
-            previous = r.finalOutput;
+            previous = designContext ? `${r.finalOutput}\n\n${designContext}` : r.finalOutput;
             // R3-b: stop honestly if the build half alone blew the run budget.
             const over = overBudget();
             if (over) {
@@ -1064,7 +1075,7 @@ export async function runPipeline(ticket, deps) {
         const fixStartedAt = clock();
         progress({ kind: "stage_start", stageId: "fix", round });
         stageEvent("fix", "start", { round });
-        const fixResult = await runStageFn(fix, { ticket: promptTicket, previous: serializeBlocking(findings), grounded }, stageDepsFor({ stageId: "fix", round }));
+        const fixResult = await runStageFn(fix, { ticket: promptTicket, previous: designContext ? `${serializeBlocking(findings)}\n\n${designContext}` : serializeBlocking(findings), grounded }, stageDepsFor({ stageId: "fix", round }));
         observedMs.fix = clock() - fixStartedAt;
         stages.push(fixResult);
         log("stage_done", { stageId: "fix", exitCode: fixResult.exitCode });
@@ -1114,8 +1125,8 @@ export async function runPipeline(ticket, deps) {
         // crash now can resume at the NEXT round against this fix's output. Snapshot
         // the post-fix tree as the resume consistency key.
         const afterFix = await snapshotFn(deps.cwd, deps.signal);
-        writeCheckpoint(mkRecord("round_done", { round, reviewInput: fixResult.finalOutput, findings, snapshot: afterFix, usage: currentUsage() }));
-        reviewInput = fixResult.finalOutput;
+        reviewInput = designContext ? `${fixResult.finalOutput}\n\n${designContext}` : fixResult.finalOutput;
+        writeCheckpoint(mkRecord("round_done", { round, reviewInput, findings, snapshot: afterFix, usage: currentUsage() }));
         round += 1;
     }
     log("pipeline_stop", { reason: stopReason, round });

package/dist/extension/pipeline/stages.js

@@ -41,9 +41,9 @@ export const REVIEW_LENSES = ["correctness", "business_fit", "does_it_hold"];
  */
 export const REQUIRED_LENSES = ["correctness"];
 /** Read-only recon + grounding tools shared by scout and reviewer. */
-const READ_TOOLS = ["read", "grep", "find", "ls", "bash"];
+const READ_TOOLS = ["read", "grep", "find", "ls", "bash", "prototype_read"];
 /** Full write tools for the worker stages. */
-const WRITE_TOOLS = ["read", "write", "edit", "bash", "grep", "find", "ls"];
+const WRITE_TOOLS = ["read", "write", "edit", "bash", "grep", "find", "ls", "prototype_read", "prototype_verification", "prototype_verify"];
 const TICKET_CONTEXT = "Follow the approved plan and its explicit constraints, including approved answers. " +
     "Prior summaries and review findings do not authorize expanding scope or publication " +
     "permissions. Report conflicts requiring a scope change for approval.\n\n" +
@@ -65,7 +65,7 @@ export const PIPELINE_V1 = [
         // Read-only recon (read/grep/find/ls) so the planner can actually navigate
         // instead of flailing on a single `read` and ending mid-exploration; NO bash
         // (it must not build/run), and ask_yagni for grounding.
-        tools: ["read", "grep", "find", "ls", "ask_yagni"],
+        tools: ["read", "grep", "find", "ls", "ask_yagni", "prototype_read"],
         taskTemplate: "Turn the ticket and the repo map into an ordered, grounded implementation " +
             "plan. Call ask_yagni before inferring a convention.\n\n" +
             "Ticket: {ticket}\n\nRepo map:\n{previous}",
@@ -78,7 +78,7 @@ export const PIPELINE_V1 = [
         taskTemplate: TICKET_CONTEXT +
             "Implement the plan. Write the code against it, and call record_decision " +
             "only for a consequential product-intent or architecture call the plan did " +
-            "not settle (never for taste, naming, or formatting).\n\nPlan:\n{previous}",
+            "not settle (never for taste, naming, or formatting). If the plan names a prototype revision, read that exact revision with prototype_read, implement with the repository components, then call prototype_verify against the local app with the agreed interaction states. Inspect its mobile/desktop screenshots against the design and document departures; unavailable browser checks remain unverified.\n\nPlan:\n{previous}",
     },
     {
         id: "review",
@@ -95,7 +95,7 @@ export const PIPELINE_V1 = [
         tools: [...WRITE_TOOLS, "ask_yagni"],
         taskTemplate: TICKET_CONTEXT +
             "Reconcile ONLY the blocking review findings against the plan. Leave " +
-            "non-blocking findings alone.\n\nBlocking findings:\n{previous}",
+            "non-blocking findings alone. When fixing a prototype-backed UI, run prototype_verify again against the pinned revision and inspect the captured screenshots; never substitute a newer design.\n\nBlocking findings:\n{previous}",
     },
 ];
 /** The single review stage the orchestrator fans out across REVIEW_LENSES. */

package/dist/extension/prototypeTool.d.ts

@@ -0,0 +1,151 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+/**
+ * Prototype tools (Prototypes v1): create, revise, list, and share runnable
+ * single-file HTML impressions of a UI through the token-authed YAGNI Code
+ * proxy (`/api/yagni-code/prototypes`, same contract as the session-authed
+ * `/api/prototypes` — the extension's device token only works on the
+ * yagni-code surface). A Prototype renders live in the app at
+ * `/prototypes/:id` and is throwaway by design: it proposes what to build,
+ * never ships as the build, and touches no product code.
+ *
+ * Sharing from here is the HUMAN path: the developer typed the ask in their own
+ * terminal, so the share is a direct REST call that takes effect immediately
+ * (recorded actor + time, revocable in-app). The agent-in-app path stages a
+ * Decision instead; that lives server-side, not in this client.
+ *
+ * These are single-purpose tools (create/revise/list/share), matching the
+ * extension's one-tool-per-verb idiom (ask_yagni, suggest_next_work, ...).
+ */
+/** Options shared by the four prototype tool factories. */
+export interface MakePrototypeToolOptions {
+    getSessionId?: () => string | undefined;
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+}
+/** The summary fields of a Prototype the tools read back and print. */
+export interface PrototypeSummary {
+    id: string;
+    title: string;
+    currentRevision: number;
+    /** In-app path stamped by the backend mapper (`/prototypes/:id`). */
+    url: string;
+}
+/** Resolve the backend's in-app path against the base URL so the terminal shows a clickable link. */
+export declare function absoluteUrl(baseUrl: string, url: string): string;
+declare const createParameters: Type.TObject<{
+    title: Type.TString;
+    html: Type.TString;
+    workItemId: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `prototype_create` tool.
+ *
+ * Creates a Prototype from a title and one complete single-file HTML document
+ * and prints the in-app URL where it renders.
+ */
+export declare function makePrototypeCreateTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof createParameters, {
+    prototype: PrototypeSummary | null;
+}>;
+declare const reviseParameters: Type.TObject<{
+    expectedRevision: Type.TOptional<Type.TInteger>;
+    prototypeId: Type.TString;
+    edits: Type.TOptional<Type.TArray<Type.TObject<{
+        find: Type.TString;
+        replace: Type.TString;
+    }>>>;
+    html: Type.TOptional<Type.TString>;
+    note: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `prototype_revise` tool.
+ *
+ * Writes a new revision: targeted `edits` (each `find` must match exactly once
+ * in the current HTML) or a full `html` replacement, with an optional `note`
+ * shown on the revision timeline. A 422 edit miss surfaces as a retryable error
+ * naming the failed find so the model can adjust and call again.
+ */
+export declare function makePrototypeReviseTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof reviseParameters, {
+    prototype: PrototypeSummary | null;
+}>;
+declare const listParameters: Type.TObject<{
+    workItemId: Type.TOptional<Type.TString>;
+}>;
+/**
+ * Build the `prototype_list` tool.
+ *
+ * Lists the workspace's Prototypes (optionally filtered to one work item) with
+ * their current revision and in-app URL.
+ */
+export declare function makePrototypeListTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof listParameters, {
+    prototypes: PrototypeSummary[];
+}>;
+declare const shareParameters: Type.TObject<{
+    prototypeId: Type.TString;
+}>;
+/**
+ * Build the `prototype_share` tool.
+ *
+ * Mints a revocable public share link for a Prototype. This is the HUMAN share
+ * path (the developer asked in their own terminal), so it is a direct REST call
+ * with immediate effect; the in-app agent path stages a Decision instead.
+ */
+export declare function makePrototypeShareTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof shareParameters, {
+    shareUrl: string | null;
+}>;
+declare const readParameters: Type.TObject<{
+    prototypeId: Type.TString;
+    revision: Type.TInteger;
+}>;
+export declare function makePrototypeReadTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof readParameters>;
+declare const draftParameters: Type.TObject<{
+    title: Type.TString;
+    spec: Type.TString;
+    workItemId: Type.TOptional<Type.TString>;
+    automatic: Type.TBoolean;
+    requestKey: Type.TOptional<Type.TString>;
+}>;
+export interface PrototypeDraftResult {
+    status: "created" | "reused" | "skipped" | "failed";
+    prototype?: PrototypeSummary;
+    reference?: {
+        prototypeId: string;
+        revision: number;
+        url?: string;
+        [key: string]: unknown;
+    };
+    reason?: string;
+}
+export declare function draftPrototype(opts: MakePrototypeToolOptions, params: {
+    title: string;
+    spec: string;
+    workItemId?: string;
+    sessionId?: string;
+    automatic: boolean;
+    requestKey?: string;
+}, signal?: AbortSignal): Promise<PrototypeDraftResult>;
+export declare function makePrototypeDraftTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof draftParameters>;
+declare const verificationParameters: Type.TObject<{
+    prototypeId: Type.TString;
+    revision: Type.TInteger;
+    status: Type.TUnion<[Type.TLiteral<"passed">, Type.TLiteral<"failed">, Type.TLiteral<"unverified">]>;
+    summary: Type.TString;
+    checks: Type.TArray<Type.TObject<{
+        name: Type.TString;
+        status: Type.TUnion<[Type.TLiteral<"passed">, Type.TLiteral<"failed">, Type.TLiteral<"unverified">]>;
+        detail: Type.TOptional<Type.TString>;
+    }>>;
+    screenshots: Type.TArray<Type.TObject<{
+        label: Type.TString;
+        url: Type.TString;
+    }>>;
+}>;
+export declare function makePrototypeVerificationTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof verificationParameters>;
+declare const attachParameters: Type.TObject<{
+    prototypeId: Type.TString;
+    workItemId: Type.TString;
+}>;
+export declare function makePrototypeAttachTool(opts: MakePrototypeToolOptions): ToolDefinition<typeof attachParameters>;
+export {};
+//# sourceMappingURL=prototypeTool.d.ts.map

package/dist/extension/prototypeTool.js

@@ -0,0 +1,330 @@
+import { Type } from "typebox";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+const MAX_FAILED_FIND = 200;
+/** Resolve the backend's in-app path against the base URL so the terminal shows a clickable link. */
+export function absoluteUrl(baseUrl, url) {
+    return /^https?:\/\//.test(url) ? url : `${baseUrl}${url}`;
+}
+function authHeaders(opts) {
+    return {
+        "content-type": "application/json",
+        authorization: `Bearer ${opts.getToken() ?? ""}`,
+    };
+}
+const createParameters = Type.Object({
+    title: Type.String(),
+    html: Type.String(),
+    workItemId: Type.Optional(Type.String()),
+});
+/**
+ * Build the `prototype_create` tool.
+ *
+ * Creates a Prototype from a title and one complete single-file HTML document
+ * and prints the in-app URL where it renders.
+ */
+export function makePrototypeCreateTool(opts) {
+    return {
+        name: "prototype_create",
+        label: "Create prototype",
+        description: "Create a YAGNI Prototype: a runnable, throwaway impression of a UI, rendered live in the " +
+            "YAGNI app. Pass a `title` and the COMPLETE single-file HTML document (inline CSS and JS, " +
+            "no external requests; it runs in a sandboxed iframe). Optionally pass `workItemId` to " +
+            "attach it to the work item it explores. Returns the in-app URL where it renders.",
+        promptSnippet: "prototype_create: create a runnable single-file HTML Prototype in the YAGNI app (returns its URL).",
+        promptGuidelines: [
+            "A Prototype is a single self-contained HTML file: inline all CSS and JS, no external requests.",
+            "Attach the Prototype to the work item it explores via `workItemId` when one is in play.",
+            "Show the user the returned in-app URL so they can open the rendered Prototype.",
+        ],
+        parameters: createParameters,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Creating the Prototype in YAGNI…" }],
+                details: { prototype: null },
+            });
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes`, {
+                method: "POST",
+                headers: authHeaders(opts),
+                body: JSON.stringify({
+                    title: params.title,
+                    html: params.html,
+                    sessionId: opts.getSessionId?.(),
+                    ...(params.workItemId ? { workItemId: params.workItemId } : {}),
+                }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("prototype_create", res));
+            }
+            const data = (await res.json());
+            const url = absoluteUrl(opts.baseUrl, data.prototype.url);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Created Prototype "${data.prototype.title}" (revision ${data.prototype.currentRevision}).\n` +
+                            `Open: ${url}`,
+                    },
+                ],
+                details: { prototype: data.prototype },
+            };
+        },
+    };
+}
+const reviseParameters = Type.Object({
+    expectedRevision: Type.Optional(Type.Integer({ minimum: 1 })),
+    prototypeId: Type.String(),
+    edits: Type.Optional(Type.Array(Type.Object({
+        find: Type.String(),
+        replace: Type.String(),
+    }))),
+    html: Type.Optional(Type.String()),
+    note: Type.Optional(Type.String()),
+});
+/**
+ * Build the `prototype_revise` tool.
+ *
+ * Writes a new revision: targeted `edits` (each `find` must match exactly once
+ * in the current HTML) or a full `html` replacement, with an optional `note`
+ * shown on the revision timeline. A 422 edit miss surfaces as a retryable error
+ * naming the failed find so the model can adjust and call again.
+ */
+export function makePrototypeReviseTool(opts) {
+    return {
+        name: "prototype_revise",
+        label: "Revise prototype",
+        description: "Revise an existing YAGNI Prototype as a new revision. Prefer targeted `edits` (each `find` " +
+            "must match the current HTML exactly once) over sending the full `html` again; pass `html` " +
+            "only for a full replacement. Add a short `note` describing the change; it labels the " +
+            "revision timeline. Returns the in-app URL of the updated Prototype.",
+        promptSnippet: "prototype_revise: apply find/replace edits (or full html) to a Prototype as a new revision.",
+        promptGuidelines: [
+            "Prefer small `edits` over resending full `html`; each `find` must match exactly once.",
+            "If prototype_revise reports a failed find, adjust the find text so it matches exactly once and try again.",
+            "Pass a short `note` with each revision so the design timeline stays readable.",
+        ],
+        parameters: reviseParameters,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Revising the Prototype in YAGNI…" }],
+                details: { prototype: null },
+            });
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(params.prototypeId)}/revisions`, {
+                method: "POST",
+                headers: authHeaders(opts),
+                body: JSON.stringify({
+                    ...(params.expectedRevision !== undefined ? { expectedRevision: params.expectedRevision } : {}),
+                    ...(params.edits ? { edits: params.edits } : {}),
+                    ...(params.html !== undefined ? { html: params.html } : {}),
+                    ...(params.note ? { note: params.note } : {}),
+                }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            // A 422 is an edit miss, not a transport failure: the backend rejected the
+            // whole batch because one `find` did not match exactly once, and wrote no
+            // revision. Name the failed find so the model can fix it and try again.
+            if (res.status === 422) {
+                let failedFind;
+                try {
+                    const body = (await res.json());
+                    failedFind = body.failedFind;
+                }
+                catch {
+                    /* body unreadable; fall through to the generic message */
+                }
+                const shown = failedFind && failedFind.length > MAX_FAILED_FIND
+                    ? `${failedFind.slice(0, MAX_FAILED_FIND)} ...`
+                    : failedFind;
+                throw new Error("prototype_revise could not apply the edits: each `find` must match exactly once in the " +
+                    `current HTML, and this one did not${shown ? `: "${shown}"` : ""}. No revision was ` +
+                    "written. Adjust the find text (or send the full `html` instead) and try again.");
+            }
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("prototype_revise", res));
+            }
+            const data = (await res.json());
+            const url = absoluteUrl(opts.baseUrl, data.prototype.url);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Revised Prototype "${data.prototype.title}" to revision ${data.revision.seq}.\n` +
+                            `Open: ${url}`,
+                    },
+                ],
+                details: { prototype: data.prototype },
+            };
+        },
+    };
+}
+const listParameters = Type.Object({
+    workItemId: Type.Optional(Type.String()),
+});
+/**
+ * Build the `prototype_list` tool.
+ *
+ * Lists the workspace's Prototypes (optionally filtered to one work item) with
+ * their current revision and in-app URL.
+ */
+export function makePrototypeListTool(opts) {
+    return {
+        name: "prototype_list",
+        label: "List prototypes",
+        description: "List the workspace's YAGNI Prototypes with their current revision and in-app URL. " +
+            "Optionally pass `workItemId` to list only the Prototypes attached to that work item. " +
+            "Use it to find an existing Prototype to revise instead of creating a duplicate.",
+        promptSnippet: "prototype_list: list the workspace's Prototypes (optionally by work item), with URLs.",
+        promptGuidelines: [
+            "Before creating a Prototype for a work item, call prototype_list to check whether one already exists to revise.",
+        ],
+        parameters: listParameters,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Listing Prototypes…" }],
+                details: { prototypes: [] },
+            });
+            const query = params.workItemId
+                ? `?workItemId=${encodeURIComponent(params.workItemId)}`
+                : "";
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes${query}`, { method: "GET", headers: authHeaders(opts) }, { fetchImpl: opts.fetchImpl, signal });
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("prototype_list", res));
+            }
+            const data = (await res.json());
+            const prototypes = data.prototypes ?? [];
+            const text = prototypes.length === 0
+                ? "No Prototypes found."
+                : prototypes
+                    .map((p) => `- "${p.title}" (revision ${p.currentRevision}): ${absoluteUrl(opts.baseUrl, p.url)}`)
+                    .join("\n");
+            return {
+                content: [{ type: "text", text }],
+                details: { prototypes },
+            };
+        },
+    };
+}
+const shareParameters = Type.Object({
+    prototypeId: Type.String(),
+});
+/**
+ * Build the `prototype_share` tool.
+ *
+ * Mints a revocable public share link for a Prototype. This is the HUMAN share
+ * path (the developer asked in their own terminal), so it is a direct REST call
+ * with immediate effect; the in-app agent path stages a Decision instead.
+ */
+export function makePrototypeShareTool(opts) {
+    return {
+        name: "prototype_share",
+        label: "Share prototype",
+        description: "Mint a public share link for a YAGNI Prototype so someone outside the workspace can view " +
+            "it. Sharing is an explicit act: it records who shared and when, and the link can be " +
+            "revoked from the Prototype's page in the app. Returns the share URL and the in-app URL.",
+        promptSnippet: "prototype_share: mint a revocable public share link for a Prototype.",
+        promptGuidelines: [
+            "Only call prototype_share when the user asks to send a Prototype outside the workspace; sharing is an explicit, recorded act.",
+            "Give the user both links: the share URL to send out and the in-app URL where the share can be revoked.",
+        ],
+        parameters: shareParameters,
+        async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+            onUpdate?.({
+                content: [{ type: "text", text: "Minting a share link…" }],
+                details: { shareUrl: null },
+            });
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(params.prototypeId)}/share`, { method: "POST", headers: authHeaders(opts) }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok) {
+                throw new Error(await friendlyFetchError("prototype_share", res));
+            }
+            const data = (await res.json());
+            const shareUrl = absoluteUrl(opts.baseUrl, data.shareUrl);
+            const inAppUrl = absoluteUrl(opts.baseUrl, `/prototypes/${params.prototypeId}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Share link minted. Anyone with the link can view this Prototype until it is revoked.\n" +
+                            `Share: ${shareUrl}\n` +
+                            `Open: ${inAppUrl}`,
+                    },
+                ],
+                details: { shareUrl },
+            };
+        },
+    };
+}
+const readParameters = Type.Object({ prototypeId: Type.String(), revision: Type.Integer({ minimum: 1 }) });
+export function makePrototypeReadTool(opts) {
+    return {
+        name: "prototype_read", label: "Read prototype revision",
+        description: "Read the exact prototype revision, HTML, feedback and design provenance. Use the approved revision, never substitute the latest revision.",
+        parameters: readParameters,
+        async execute(_id, params, signal) {
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(params.prototypeId)}/read?revision=${params.revision}`, { headers: authHeaders(opts) }, { fetchImpl: opts.fetchImpl, signal });
+            if (!res.ok)
+                throw new Error(await friendlyFetchError("prototype_read", res));
+            const data = await res.json();
+            return { content: [{ type: "text", text: JSON.stringify(data) }], details: data };
+        },
+    };
+}
+const draftParameters = Type.Object({
+    title: Type.String(), spec: Type.String(), workItemId: Type.Optional(Type.String()),
+    automatic: Type.Boolean({ default: false }), requestKey: Type.Optional(Type.String()),
+});
+export async function draftPrototype(opts, params, signal) {
+    const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/draft`, {
+        method: "POST", headers: authHeaders(opts), body: JSON.stringify({ ...params, sessionId: params.sessionId ?? opts.getSessionId?.() }),
+    }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+    if (!res.ok)
+        throw new Error(await friendlyFetchError("prototype_draft", res));
+    return await res.json();
+}
+export function makePrototypeDraftTool(opts) {
+    return {
+        name: "prototype_draft", label: "Draft grounded prototype",
+        description: "Draft one private interactive UI prototype using repository design context and synthetic examples. Use for new screens, multi-step flows or uncertain interactions before plan approval. Pass automatic=true only for automatic planning; the server enforces eligibility, feature flag, budget and deduplication. Never replace an approved design. Returns created, reused, skipped or failed with a reason.",
+        parameters: draftParameters,
+        async execute(_id, params, signal) {
+            const data = await draftPrototype(opts, params, signal);
+            return { content: [{ type: "text", text: JSON.stringify(data) }], details: data };
+        },
+    };
+}
+const verificationStatus = Type.Union([Type.Literal("passed"), Type.Literal("failed"), Type.Literal("unverified")]);
+const verificationParameters = Type.Object({
+    prototypeId: Type.String(), revision: Type.Integer({ minimum: 1 }), status: verificationStatus, summary: Type.String(),
+    checks: Type.Array(Type.Object({ name: Type.String(), status: verificationStatus, detail: Type.Optional(Type.String()) })),
+    screenshots: Type.Array(Type.Object({ label: Type.String(), url: Type.String() })),
+});
+export function makePrototypeVerificationTool(opts) {
+    return {
+        name: "prototype_verification", label: "Record design verification",
+        description: "Record observed browser visual and interaction checks against the approved prototype revision. Use credential-free browser tools, compare agreed states, and document intentional departures. Use status=unverified when browser checks are unavailable; never report passed without observed results. Screenshots must be real captured evidence. Build the production UI using repository components, not prototype HTML.",
+        parameters: verificationParameters,
+        async execute(_id, params, signal) {
+            const { prototypeId, ...body } = params;
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(prototypeId)}/verification`, { method: "POST", headers: authHeaders(opts), body: JSON.stringify(body) }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok)
+                throw new Error(await friendlyFetchError("prototype_verification", res));
+            const data = await res.json();
+            return { content: [{ type: "text", text: JSON.stringify(data) }], details: data };
+        },
+    };
+}
+const attachParameters = Type.Object({ prototypeId: Type.String(), workItemId: Type.String() });
+export function makePrototypeAttachTool(opts) {
+    return {
+        name: "prototype_attach", label: "Attach prototype to work item",
+        description: "Attach an existing session prototype to a work item so people can review it beside the plan. The server derives its audience from the work item and revokes existing public links. This does not select a revision or approve a plan.",
+        parameters: attachParameters,
+        async execute(_id, params, signal) {
+            const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(params.prototypeId)}/attach`, {
+                method: "POST", headers: authHeaders(opts), body: JSON.stringify({ workItemId: params.workItemId }),
+            }, { fetchImpl: opts.fetchImpl, signal, policy: METERED_POST_FETCH_POLICY });
+            if (!res.ok)
+                throw new Error(await friendlyFetchError("prototype_attach", res));
+            const data = await res.json();
+            return { content: [{ type: "text", text: `Attached prototype to work item ${params.workItemId}.` }], details: data };
+        },
+    };
+}
+//# sourceMappingURL=prototypeTool.js.map

package/dist/extension/prototypeVerify.d.ts

@@ -0,0 +1,77 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { MakePrototypeToolOptions } from "./prototypeTool.js";
+interface Action {
+    action: "click" | "fill";
+    role: string;
+    name: string;
+    value?: string;
+}
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface VerificationInput {
+    prototypeId: string;
+    revision: number;
+    url: string;
+    checks: {
+        name: string;
+        actions?: Action[];
+        expectText: string;
+    }[];
+    viewports?: Viewport[];
+}
+interface VerificationPage {
+    navigate(url: string): Promise<void>;
+    act(action: Action): Promise<void>;
+    hasText(text: string): Promise<boolean>;
+    screenshot(): Promise<Buffer>;
+    close(): Promise<void>;
+}
+export interface VerificationBrowser {
+    open(viewport: Viewport, allowRequest: (url: string) => boolean): Promise<VerificationPage>;
+    close(): Promise<void>;
+}
+interface VerifyOptions extends MakePrototypeToolOptions {
+    launchBrowser?: (cwd: string) => Promise<VerificationBrowser>;
+    timeoutMs?: number;
+}
+type Status = "passed" | "failed" | "unverified";
+interface VerificationResult {
+    revision: number;
+    status: Status;
+    summary: string;
+    checks: {
+        name: string;
+        status: Status;
+        detail?: string;
+    }[];
+    screenshots: {
+        label: string;
+        url: string;
+    }[];
+}
+export declare function verifyPrototype(opts: VerifyOptions, input: VerificationInput, cwd: string, signal?: AbortSignal): Promise<VerificationResult>;
+declare const parameters: Type.TObject<{
+    prototypeId: Type.TString;
+    revision: Type.TInteger;
+    url: Type.TString;
+    checks: Type.TArray<Type.TObject<{
+        name: Type.TString;
+        expectText: Type.TString;
+        actions: Type.TOptional<Type.TArray<Type.TObject<{
+            action: Type.TUnion<[Type.TLiteral<"click">, Type.TLiteral<"fill">]>;
+            role: Type.TString;
+            name: Type.TString;
+            value: Type.TOptional<Type.TString>;
+        }>>>;
+    }>>;
+    viewports: Type.TOptional<Type.TArray<Type.TObject<{
+        width: Type.TInteger;
+        height: Type.TInteger;
+    }>>>;
+}>;
+export declare function makePrototypeVerifyTool(opts: VerifyOptions): ToolDefinition<typeof parameters>;
+export {};
+//# sourceMappingURL=prototypeVerify.d.ts.map

package/dist/extension/prototypeVerify.js

@@ -0,0 +1,219 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { Type } from "typebox";
+import { friendlyFetchError, METERED_POST_FETCH_POLICY, resilientFetch } from "./resilientFetch.js";
+import { logEvent } from "./errorSink.js";
+async function launchProjectBrowser(cwd) {
+    const require = createRequire(join(cwd, "package.json"));
+    let runtime;
+    try {
+        runtime = require("playwright");
+    }
+    catch {
+        runtime = require("@playwright/test");
+    }
+    const browser = await runtime.chromium.launch({ headless: true, timeout: 10_000 });
+    return {
+        async open(viewport, allow) {
+            const context = await browser.newContext({ viewport, serviceWorkers: "block", permissions: [], acceptDownloads: false });
+            await context.route("**/*", async (route) => {
+                if (allow(route.request().url()))
+                    await route.continue();
+                else
+                    await route.abort();
+            });
+            // Block sockets too; request routing alone does not cover WebSockets.
+            await context.routeWebSocket("**/*", socket => socket.close());
+            const page = await context.newPage();
+            return {
+                async navigate(url) {
+                    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 10_000 });
+                    if (!allow(page.url()))
+                        throw new Error("Navigation left the verification origin");
+                },
+                async act(action) {
+                    const target = page.getByRole(action.role, { name: action.name, exact: true });
+                    if (action.action === "click")
+                        await target.click({ timeout: 3_000 });
+                    else
+                        await target.fill(action.value ?? "", { timeout: 3_000 });
+                    if (!allow(page.url()))
+                        throw new Error("Navigation left the verification origin");
+                },
+                async hasText(text) {
+                    try {
+                        await page.getByText(text, { exact: false }).first().waitFor({ state: "visible", timeout: 3_000 });
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+                screenshot: () => page.screenshot({ type: "png", fullPage: false, timeout: 3_000 }),
+                close: () => context.close(),
+            };
+        },
+        close: () => browser.close(),
+    };
+}
+function loopbackOrigin(value) {
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol) || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || url.username || url.password) {
+        throw new Error("Prototype verification requires a credential-free loopback http(s) URL");
+    }
+    return url.origin;
+}
+/** Race an operation against the run's deadline, so a hung browser call cannot outlive it. */
+function boundedBy(deadline) {
+    return async (operation) => {
+        if (deadline.aborted) {
+            void operation.catch(() => { });
+            deadline.throwIfAborted();
+        }
+        let rejectAbort;
+        try {
+            return await Promise.race([operation, new Promise((_resolve, reject) => {
+                    rejectAbort = () => reject(deadline.reason);
+                    deadline.addEventListener("abort", rejectAbort, { once: true });
+                })]);
+        }
+        finally {
+            if (rejectAbort)
+                deadline.removeEventListener("abort", rejectAbort);
+        }
+    };
+}
+/** One viewport: navigate, run each check's actions, then the screenshot the reviewer compares. */
+async function verifyViewport(page, input, label, bounded, checkCancelled) {
+    const checks = [];
+    await bounded(page.navigate(input.url));
+    for (const check of input.checks) {
+        checkCancelled();
+        let passed = false;
+        try {
+            for (const action of check.actions ?? []) {
+                checkCancelled();
+                await bounded(page.act(action));
+            }
+            passed = await bounded(page.hasText(check.expectText));
+        }
+        catch {
+            checkCancelled();
+        }
+        checks.push({ name: `${label}: ${check.name}`, status: passed ? "passed" : "failed", detail: passed ? "Expected text observed after the requested interactions." : "Requested interaction or visible text did not match." });
+    }
+    checkCancelled();
+    const png = await bounded(page.screenshot());
+    if (png.length > 2 * 1024 * 1024)
+        throw new Error("Screenshot exceeds the upload limit");
+    return { checks, png };
+}
+function errorReason(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").slice(0, 200);
+}
+export async function verifyPrototype(opts, input, cwd, signal) {
+    const origin = loopbackOrigin(input.url);
+    if (!Number.isInteger(input.revision) || input.revision < 1 || input.checks.length < 1 || input.checks.length > 8 || input.checks.some(check => (check.actions?.length ?? 0) > 8))
+        throw new Error("Verification requires a revision and 1–8 bounded checks");
+    const viewports = input.viewports ?? [{ width: 390, height: 844 }, { width: 1280, height: 800 }];
+    if (viewports.length < 1 || viewports.length > 3 || viewports.some(v => !Number.isInteger(v.width) || !Number.isInteger(v.height) || v.width < 320 || v.width > 1920 || v.height < 320 || v.height > 1200))
+        throw new Error("Invalid verification viewports");
+    const result = { revision: input.revision, status: "unverified", summary: "Browser verification unavailable.", checks: [], screenshots: [] };
+    const allow = (url) => { try {
+        return new URL(url).origin === origin;
+    }
+    catch {
+        return false;
+    } };
+    const deadline = new AbortController();
+    const post = async (suffix, body) => {
+        const response = await resilientFetch(`${opts.baseUrl}/api/yagni-code/prototypes/${encodeURIComponent(input.prototypeId)}/${suffix}`, {
+            method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${opts.getToken() ?? ""}` }, body: JSON.stringify(body),
+        }, { fetchImpl: opts.fetchImpl, signal: suffix === "verification" ? signal : deadline.signal, policy: METERED_POST_FETCH_POLICY });
+        if (!response.ok)
+            throw new Error(await friendlyFetchError("prototype_verify", response));
+        return await response.json();
+    };
+    let browser;
+    let timedOut = false;
+    let closing;
+    const close = () => { if (browser && !closing)
+        closing = browser.close().catch(() => { }); };
+    const abort = () => { deadline.abort(signal?.reason); close(); };
+    const timer = setTimeout(() => { timedOut = true; deadline.abort(new Error("Verification timed out")); close(); }, Math.min(opts.timeoutMs ?? 45_000, 45_000));
+    signal?.addEventListener("abort", abort, { once: true });
+    const bounded = boundedBy(deadline.signal);
+    const checkCancelled = () => {
+        signal?.throwIfAborted();
+        if (timedOut)
+            throw new Error("Verification timed out");
+    };
+    try {
+        checkCancelled();
+        const activeBrowser = await bounded((opts.launchBrowser ?? launchProjectBrowser)(cwd).then(launched => {
+            if (deadline.signal.aborted)
+                void launched.close().catch(() => { });
+            return launched;
+        }));
+        browser = activeBrowser;
+        checkCancelled();
+        for (const viewport of viewports) {
+            checkCancelled();
+            const page = await bounded(activeBrowser.open(viewport, allow));
+            try {
+                const label = `${viewport.width}x${viewport.height}`;
+                const { checks, png } = await verifyViewport(page, input, label, bounded, checkCancelled);
+                result.checks.push(...checks);
+                const uploaded = await post("screenshots", { revision: input.revision, label, pngBase64: png.toString("base64") });
+                if (!uploaded.url)
+                    throw new Error("Screenshot upload returned no evidence URL");
+                result.screenshots.push({ label, url: uploaded.url });
+            }
+            finally {
+                await bounded(page.close()).catch(() => { });
+            }
+        }
+        checkCancelled();
+        result.status = result.checks.every(check => check.status === "passed") && result.screenshots.length === viewports.length ? "passed" : "failed";
+        result.summary = result.status === "passed" ? "Requested interactions and visible text passed at every viewport; screenshots captured for visual review." : "One or more requested browser checks failed; review the captured screenshots.";
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        // Every failure records the same honest status, but keeps its cause: a
+        // missing Playwright, a crashed browser and a failed upload need
+        // different fixes.
+        const reason = errorReason(error);
+        logEvent({ source: "tool", level: "warn", event: "prototype_verify.unavailable", fields: { timedOut, reason } });
+        result.status = "unverified";
+        result.summary = timedOut
+            ? "Browser verification exceeded its time limit; incomplete checks remain unverified."
+            : `Browser, local app, or screenshot evidence unavailable (${reason}); verification is incomplete.`;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        close();
+        if (closing)
+            await Promise.race([closing, new Promise(resolve => { const cleanupTimer = setTimeout(resolve, 2_000); cleanupTimer.unref(); })]);
+    }
+    signal?.throwIfAborted();
+    await post("verification", result);
+    return result;
+}
+const parameters = Type.Object({
+    prototypeId: Type.String(), revision: Type.Integer({ minimum: 1 }), url: Type.String(),
+    checks: Type.Array(Type.Object({ name: Type.String(), expectText: Type.String(), actions: Type.Optional(Type.Array(Type.Object({ action: Type.Union([Type.Literal("click"), Type.Literal("fill")]), role: Type.String(), name: Type.String(), value: Type.Optional(Type.String()) }), { maxItems: 8 })) }), { minItems: 1, maxItems: 8 }),
+    viewports: Type.Optional(Type.Array(Type.Object({ width: Type.Integer({ minimum: 320, maximum: 1920 }), height: Type.Integer({ minimum: 320, maximum: 1200 }) }), { minItems: 1, maxItems: 3 })),
+});
+export function makePrototypeVerifyTool(opts) {
+    return {
+        name: "prototype_verify", label: "Verify prototype implementation",
+        description: "Run real browser interaction checks on the implemented local app against an exact prototype revision and capture desktop/mobile screenshots for visual review. Supply agreed state checks from prototype_read and synthetic fill values only. Uses existing project Playwright without installing anything, in a fresh credential-free context restricted to the local app origin. Records passed/failed observed checks or explicitly unverified when the browser/app/evidence is unavailable. Screenshots support human visual comparison; passing text checks does not prove visual equivalence.",
+        parameters,
+        async execute(_id, input, signal, _update, context) {
+            const result = await verifyPrototype(opts, input, context.cwd, signal);
+            return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+        },
+    };
+}
+//# sourceMappingURL=prototypeVerify.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.2.3-staging.1575.1",
+  "version": "1.2.3-staging.1580.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "ce56b0f74cd9190953e1fc22901d340ff765793a"
+  "yagniSourceSha": "8592117c432a85b840ac26dd74f48e84d6bb3a1a"
 }