specpi 0.11.2 → 0.13.0

package/extensions/browser/interactions.ts

@@ -0,0 +1,118 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import type { Locator, Page } from "playwright";
+import { boundedInteger } from "./diagnostics.ts";
+import { normalizeBrowserUrl } from "./core.mjs";
+
+const Target = Type.String({
+    minLength: 1,
+    maxLength: 2000,
+    description: "CSS selector, exact text= locator, or current snapshot ref. First match is used.",
+});
+const Timeout = Type.Optional(
+    Type.Integer({
+        minimum: 1,
+        maximum: 30000,
+        description: "Whole-operation deadline in milliseconds; default 5000.",
+    }),
+);
+export const PressParams = Type.Object(
+    { target: Type.Optional(Target), key: Type.String({ minLength: 1, maxLength: 80 }), timeoutMs: Timeout },
+    { additionalProperties: false },
+);
+export const SelectionParams = Type.Object(
+    {
+        target: Target,
+        options: Type.Array(
+            Type.Object(
+                {
+                    value: Type.Optional(Type.String({ maxLength: 1000 })),
+                    label: Type.Optional(Type.String({ maxLength: 1000 })),
+                    index: Type.Optional(Type.Integer({ minimum: 0, maximum: 10000 })),
+                },
+                { additionalProperties: false },
+            ),
+            { minItems: 1, maxItems: 50 },
+        ),
+        timeoutMs: Timeout,
+    },
+    { additionalProperties: false },
+);
+export const WaitParams = Type.Object(
+    {
+        condition: StringEnum(["attached", "detached", "visible", "hidden", "text", "url"] as const),
+        target: Type.Optional(Target),
+        text: Type.Optional(Type.String({ maxLength: 2000 })),
+        url: Type.Optional(Type.String({ minLength: 1, maxLength: 2000 })),
+        timeoutMs: Timeout,
+    },
+    { additionalProperties: false },
+);
+
+export function interactionTimeout(value?: number): number {
+    return boundedInteger(value, 5000, 30000);
+}
+
+export function validateKey(key: string): void {
+    const parts = key.split("+");
+    // A literal plus key is also supported; chords use Playwright key names.
+    const final = key === "+" ? "+" : parts.pop()!;
+    if (key === "+") {
+        parts.length = 0;
+    }
+
+    if (
+        parts.some((part) => !["Control", "ControlOrMeta", "Alt", "Shift", "Meta"].includes(part)) ||
+        new Set(parts).size !== parts.length ||
+        !(
+            Array.from(final).length === 1 ||
+            /^(?:Tab|Enter|Escape|Backspace|Delete|ArrowUp|ArrowDown|ArrowLeft|ArrowRight|Home|End|PageUp|PageDown|Space|Insert|F(?:[1-9]|1[0-2]))$/u.test(
+                final,
+            )
+        ) ||
+        /[\u0000-\u001f\u007f]/u.test(key)
+    ) {
+        throw new Error("Unsupported browser key or chord.");
+    }
+}
+
+export function selectionOptions(params: Static<typeof SelectionParams>) {
+    for (const option of params.options) {
+        if (Object.keys(option).length !== 1) {
+            throw new Error("Each option must specify exactly one of value, label, or index.");
+        }
+    }
+
+    return params.options;
+}
+
+export function validateWait(params: Static<typeof WaitParams>): void {
+    if (params.condition === "url") {
+        if (params.url === undefined || params.target !== undefined || params.text !== undefined) {
+            throw new Error("URL waits require only url, not target or text.");
+        }
+    } else if (
+        !params.target?.trim() ||
+        params.url !== undefined ||
+        (params.condition === "text") !== (params.text !== undefined)
+    ) {
+        throw new Error("Element waits require target; only text waits require text. Do not supply url.");
+    }
+}
+
+export async function waitForCondition(
+    page: Page,
+    locator: Locator | undefined,
+    params: Static<typeof WaitParams>,
+    timeout: number,
+): Promise<void> {
+    if (params.condition === "url") {
+        const expected = normalizeBrowserUrl(params.url!);
+        await page.waitForURL((url) => url.href === expected, { timeout, waitUntil: "commit" });
+    } else if (params.condition === "text") {
+        const literal = params.text!.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+        await locator!.filter({ hasText: new RegExp(`^${literal}$`, "u") }).waitFor({ state: "attached", timeout });
+    } else {
+        await locator!.waitFor({ state: params.condition, timeout });
+    }
+}

package/extensions/browser/lifecycle.ts

@@ -0,0 +1,28 @@
+export const CLEANUP_TIMEOUT_MS = 1000;
+
+export class BrowserCleanupError extends Error {
+    constructor() {
+        super(
+            "Browser cleanup failed or did not settle within 1000ms. The context was detached and diagnostics discarded, but a browser process may remain; inspect local browser processes before continuing.",
+        );
+        this.name = "BrowserCleanupError";
+    }
+}
+
+/** Bound settlement without claiming that an unresponsive external process was terminated. */
+export async function settleBrowserCleanup(operations: Promise<unknown>[]): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+        const result = await Promise.race([
+            Promise.allSettled(operations),
+            new Promise<never>((_resolve, reject) => {
+                timer = setTimeout(() => reject(new BrowserCleanupError()), CLEANUP_TIMEOUT_MS);
+            }),
+        ]);
+        if (result.some((entry) => entry.status === "rejected")) {
+            throw new BrowserCleanupError();
+        }
+    } finally {
+        clearTimeout(timer);
+    }
+}

package/extensions/command-guard/index.ts

@@ -18,6 +18,7 @@ type State = {
     categories: Record<string, number>;
     rules: Record<string, number>;
     criticalRule?: string;
+    onModeChanged?: () => void;
 };
 
 function validRecord(value: unknown): value is Record<string, unknown> {
@@ -138,12 +139,17 @@ function decisionPrompt(decision: any, cwd: string, affected: string): string {
     return boundedReason(fields, 1200);
 }
 
+function lockSession(state: State): void {
+    state.mode = "locked";
+    state.generation += 1;
+    state.sessionApprovals.clear();
+    state.onModeChanged?.();
+}
+
 function deny(state: State, reason: string, critical = false): { block: true; reason: string } {
     state.blocks += 1;
     if (critical) {
-        state.mode = "locked";
-        state.generation += 1;
-        state.sessionApprovals.clear();
+        lockSession(state);
     }
 
     return { block: true, reason: boundedReason(reason) };
@@ -175,6 +181,34 @@ export default function registerCommandGuard(
         categories: {},
         rules: {},
     };
+    state.onModeChanged = () => pi.events?.emit("specpi:guard-policy-changed", { reason: "guard policy changed" });
+    let guardStateSubscription: (() => void) | undefined;
+    const subscribeGuardState = () => {
+        if (!guardStateSubscription) {
+            guardStateSubscription = pi.events?.on?.("specpi:guard-state", (request: any) => {
+                request.reply({ mode: state.ready && !state.startupFailed ? state.mode : undefined });
+            });
+        }
+    };
+
+    subscribeGuardState();
+    const delegationPolicy = (input: unknown): { fingerprint: string; summary: string } | undefined => {
+        let replies = 0;
+        let policy: any;
+        pi.events?.emit("specpi:delegation-policy", {
+            input,
+            reply(value: any) {
+                replies += 1;
+                policy = value;
+            },
+        });
+        if (replies !== 1 || !/^[a-f0-9]{64}$/u.test(policy?.fingerprint) || typeof policy?.summary !== "string") {
+            return undefined;
+        }
+
+        return { fingerprint: policy.fingerprint, summary: boundedReason(policy.summary, 1600) };
+    };
+
     const reset = () => {
         clearAnalysisCache();
         state.mode = "guard";
@@ -192,10 +226,17 @@ export default function registerCommandGuard(
 
     pi.on("session_start", async (_event, ctx) => {
         reset();
+        const startupGeneration = state.generation;
         try {
+            subscribeGuardState();
             const choice = ctx.hasUI ? await startupChoice(ctx, startupTimeoutMs) : undefined;
+            if (state.generation !== startupGeneration) {
+                return;
+            }
+
+            let mode: "guard" | "strict" | "off" = "guard";
             if (choice === "Strict") {
-                state.mode = "strict";
+                mode = "strict";
             } else if (choice === "Off for this session") {
                 const confirmed = ctx.hasUI
                     ? await withTimeout(
@@ -207,10 +248,15 @@ export default function registerCommandGuard(
                           startupTimeoutMs,
                       )
                     : false;
-                state.mode = confirmed ? "off" : "guard";
+                if (state.generation !== startupGeneration) {
+                    return;
+                }
+
+                mode = confirmed ? "off" : "guard";
             }
 
-            state.baseMode = state.mode;
+            state.mode = mode;
+            state.baseMode = mode;
             state.ready = true;
             state.startupFailed = false;
             updateStatus(ctx, state);
@@ -221,6 +267,10 @@ export default function registerCommandGuard(
                 state.mode === "off" ? "warning" : "info",
             );
         } catch {
+            if (state.generation !== startupGeneration) {
+                return;
+            }
+
             state.startupFailed = true;
             state.ready = false;
             try {
@@ -232,6 +282,11 @@ export default function registerCommandGuard(
     });
     pi.on("session_shutdown", (_event, ctx) => {
         reset();
+        if (typeof guardStateSubscription === "function") {
+            guardStateSubscription();
+            guardStateSubscription = undefined;
+        }
+
         try {
             ctx.ui.setStatus("specpi-command-guard", undefined);
         } catch {
@@ -256,6 +311,12 @@ export default function registerCommandGuard(
                 return;
             }
 
+            if (!["guard", "strict", "off", "unlock", "clear-approvals"].includes(action)) {
+                ctx.ui.notify("Usage: /guard [status|guard|strict|off|unlock|clear-approvals]", "error");
+
+                return;
+            }
+
             if (state.mode === "locked" && action !== "unlock") {
                 ctx.ui.notify(
                     "The command guard is locked. Use /guard unlock after reviewing the critical rule.",
@@ -268,6 +329,7 @@ export default function registerCommandGuard(
             if (action === "clear-approvals") {
                 state.sessionApprovals.clear();
                 state.generation += 1;
+                state.onModeChanged?.();
                 ctx.ui.notify("Session approvals cleared.", "info");
 
                 return;
@@ -280,6 +342,7 @@ export default function registerCommandGuard(
                     return;
                 }
 
+                const approvalGeneration = state.generation;
                 const ok =
                     ctx.hasUI &&
                     (await withTimeout(
@@ -290,11 +353,12 @@ export default function registerCommandGuard(
                         false,
                         approvalTimeoutMs,
                     ));
-                if (ok) {
+                if (ok && state.generation === approvalGeneration) {
                     state.mode = state.baseMode;
                     state.generation += 1;
                     state.sessionApprovals.clear();
                     state.criticalRule = undefined;
+                    state.onModeChanged?.();
                     updateStatus(ctx, state);
                     ctx.ui.notify(`Command guard unlocked in ${state.baseMode} mode.`, "warning");
                 }
@@ -303,6 +367,11 @@ export default function registerCommandGuard(
             }
 
             if (action === "off") {
+                if (state.mode === "off") {
+                    return;
+                }
+
+                const approvalGeneration = state.generation;
                 if (
                     !ctx.hasUI ||
                     !(await withTimeout(
@@ -312,7 +381,8 @@ export default function registerCommandGuard(
                         ),
                         false,
                         approvalTimeoutMs,
-                    ))
+                    )) ||
+                    state.generation !== approvalGeneration
                 ) {
                     return;
                 }
@@ -321,24 +391,31 @@ export default function registerCommandGuard(
                 state.baseMode = "off";
                 state.generation += 1;
                 state.sessionApprovals.clear();
+                state.onModeChanged?.();
                 updateStatus(ctx, state);
 
                 return;
             }
 
             if (action === "strict" || action === "guard") {
+                if (state.mode === action) {
+                    return;
+                }
+
+                const approvalGeneration = state.generation;
                 if (
-                    action === "guard" &&
-                    state.mode === "strict" &&
-                    (!ctx.hasUI ||
-                        !(await withTimeout(
-                            ctx.ui.confirm(
-                                "Switch to Guard mode?",
-                                "This weakens protection for the rest of this session.",
-                            ),
-                            false,
-                            approvalTimeoutMs,
-                        )))
+                    (action === "guard" &&
+                        state.mode === "strict" &&
+                        (!ctx.hasUI ||
+                            !(await withTimeout(
+                                ctx.ui.confirm(
+                                    "Switch to Guard mode?",
+                                    "This weakens protection for the rest of this session.",
+                                ),
+                                false,
+                                approvalTimeoutMs,
+                            )))) ||
+                    state.generation !== approvalGeneration
                 ) {
                     return;
                 }
@@ -347,12 +424,11 @@ export default function registerCommandGuard(
                 state.baseMode = action;
                 state.generation += 1;
                 state.sessionApprovals.clear();
+                state.onModeChanged?.();
                 updateStatus(ctx, state);
 
                 return;
             }
-
-            ctx.ui.notify("Usage: /guard [status|guard|strict|off|unlock|clear-approvals]", "error");
         },
     });
 
@@ -462,9 +538,7 @@ export default function registerCommandGuard(
                     }
 
                     if (answer === "Lock session") {
-                        state.mode = "locked";
-                        state.generation += 1;
-                        state.sessionApprovals.clear();
+                        lockSession(state);
                         updateStatus(ctx, state);
 
                         return deny(state, "The session was locked by command-guard approval.");
@@ -557,9 +631,7 @@ export default function registerCommandGuard(
                     }
 
                     if (answer === "Lock session") {
-                        state.mode = "locked";
-                        state.generation += 1;
-                        state.sessionApprovals.clear();
+                        lockSession(state);
                         updateStatus(ctx, state);
 
                         return deny(state, "The session was locked by command-guard approval.");
@@ -573,7 +645,15 @@ export default function registerCommandGuard(
 
             if (state.mode === "strict") {
                 recordDecision(state, { category: "unknown", ruleIds: ["tool.unknown-capability"] });
-                const approvalFingerprint = toolFingerprint(name, input, ctx.cwd, state.mode);
+                const capability = name === "delegate" ? delegationPolicy(input) : undefined;
+                if (name === "delegate" && !capability) {
+                    return deny(state, "Delegation policy is unavailable or ambiguous; execution is denied.");
+                }
+
+                const effectiveInput = capability
+                    ? { input, delegationPolicyFingerprint: capability.fingerprint }
+                    : input;
+                const approvalFingerprint = toolFingerprint(name, effectiveInput, ctx.cwd, state.mode);
                 if (!approvalFingerprint) {
                     return deny(state, "Unknown-tool approval input is malformed or exceeds the safety bound.");
                 }
@@ -589,7 +669,7 @@ export default function registerCommandGuard(
                 const approvalGeneration = state.generation;
                 const answer = await withTimeout(
                     ctx.ui.select(
-                        `Unknown tool approval — name: ${boundedReason(name, 96)}; mode: ${state.mode}; capability is not in the reviewed command-guard catalog.`,
+                        `Unknown tool approval — name: ${boundedReason(name, 96)}; mode: ${state.mode}; ${capability?.summary ?? "capability is not in the reviewed command-guard catalog."}`,
                         ["Deny (Recommended)", "Allow once", "Allow exact call for session", "Lock session"],
                     ),
                     undefined,
@@ -598,7 +678,14 @@ export default function registerCommandGuard(
                 if (
                     state.generation !== approvalGeneration ||
                     state.mode === "locked" ||
-                    toolFingerprint(name, input, ctx.cwd, state.mode) !== approvalFingerprint
+                    toolFingerprint(
+                        name,
+                        capability
+                            ? { input, delegationPolicyFingerprint: delegationPolicy(input)?.fingerprint }
+                            : input,
+                        ctx.cwd,
+                        state.mode,
+                    ) !== approvalFingerprint
                 ) {
                     return deny(state, "Command-guard state or input changed during approval; execution is denied.");
                 }
@@ -619,9 +706,7 @@ export default function registerCommandGuard(
                 }
 
                 if (answer === "Lock session") {
-                    state.mode = "locked";
-                    state.generation += 1;
-                    state.sessionApprovals.clear();
+                    lockSession(state);
                     updateStatus(ctx, state);
                 }