pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/extension-observation.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { appendBrowserTransition, artifactChanges, } from "../browser-transcript.js";
+import { appendBrowserRecord, hasPublishedBrowserJournal, } from "../browser-journal.js";
+import { isPlainTextInspectionArgs } from "../runtime.js";
+import { isBooleanFlagEnabled } from "../argv-grammar.js";
+import { isRecord } from "../parsing.js";
+import { mergeBrowserRunArtifactManifest } from "./browser-run/artifact-merge.js";
+import { getPersistentSessionArtifactStore } from "./browser-run/session-state.js";
+import { isSessionArtifactManifest } from "../results/artifact-manifest.js";
+import { renderAgentBrowserObservation } from "../results/presentation/large-output.js";
+import { invocationArtifactManifest } from "./extension-result-state.js";
+function observationDetails(result) {
+    const details = isRecord(result.details) ? result.details : {};
+    if (result.isError === true && details.error === undefined) {
+        details.error =
+            details.validationError ??
+                details.summary ??
+                result.content
+                    .filter((item) => item.type === "text")
+                    .map((item) => item.text)
+                    .join("\n");
+    }
+    return details;
+}
+function observedResult(observation, manifest) {
+    return {
+        ...observation.result,
+        details: {
+            ...observation.details,
+            browserEventVersion: 1,
+            ...(manifest ? { artifactManifest: manifest.value } : {}),
+        },
+    };
+}
+class ObservationPublication {
+    resources;
+    context;
+    constructor(resources, context) {
+        this.resources = resources;
+        this.context = context;
+    }
+    async render(result, params) {
+        const details = observationDetails(result);
+        const priorManifest = isSessionArtifactManifest(details.artifactManifest)
+            ? details.artifactManifest
+            : undefined;
+        const renderOptions = {
+            content: result.content,
+            details,
+            json: "code" in params || isBooleanFlagEnabled([...(params.args ?? [])], "--json"),
+            succeeded: result.isError !== true,
+            persistentArtifactStore: this.context.branch.isCurrent()
+                ? getPersistentSessionArtifactStore(this.context.ctx)
+                : undefined,
+            withArtifactWrite: (write) => this.resources.queue.run(() => {
+                if (!this.context.branch.isCurrent()) {
+                    renderOptions.persistentArtifactStore = undefined;
+                }
+                return write();
+            }),
+        };
+        const rendered = await renderAgentBrowserObservation(renderOptions);
+        return {
+            result: {
+                ...result,
+                content: rendered.content,
+                structuredContent: rendered.structuredContent,
+            },
+            details,
+            priorManifest,
+            renderedManifest: rendered.artifactManifest,
+        };
+    }
+    async persistChanges(observation, changes) {
+        const { ctx, branch } = this.context;
+        if (!changes || !hasPublishedBrowserJournal(ctx.sessionManager)) {
+            return true;
+        }
+        const record = {
+            event: {
+                version: 1,
+                phase: "state",
+                operationId: randomUUID(),
+                toolCallId: "observation",
+                commandIndex: 0,
+                isError: observation.result.isError === true,
+                state: {},
+                artifacts: changes,
+            },
+        };
+        return ((await appendBrowserRecord(ctx.sessionManager, () => appendBrowserTransition(this.resources.pi, record), record, branch)) && branch.isCurrent());
+    }
+    async publish(observation) {
+        if (!this.context.branch.isCurrent()) {
+            return observedResult(observation, { value: observation.renderedManifest });
+        }
+        const before = this.resources.manifest;
+        const merged = mergeBrowserRunArtifactManifest(before, observation.priorManifest, observation.renderedManifest);
+        if (!(await this.persistChanges(observation, artifactChanges(before, merged)))) {
+            return observedResult(observation, { value: observation.renderedManifest });
+        }
+        this.resources.commit(observation.priorManifest, observation.renderedManifest);
+        return observedResult(observation, {
+            value: invocationArtifactManifest(this.resources.manifest, before, observation.details, observation.priorManifest),
+        });
+    }
+    async run(result, params) {
+        if ("args" in params && params.args && isPlainTextInspectionArgs([...params.args])) {
+            return result;
+        }
+        const observation = await this.render(result, params);
+        if (!observation.priorManifest && !observation.renderedManifest) {
+            return observedResult(observation);
+        }
+        return this.resources.queue.run(() => this.publish(observation));
+    }
+}
+export function finalizeObservation(resources, result, params, context) {
+    return new ObservationPublication(resources, context).run(result, params);
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-prompt.js

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PROJECT_RULE_PROMPT, ADVANCED_TOOL_PROMPT_GUIDELINES, QUICK_START_GUIDELINES, SHARED_BROWSER_PLAYBOOK_GUIDELINES, WEB_SEARCH_TOOL_PROMPT_GUIDELINES, WRAPPER_TAB_RECOVERY_BEHAVIOR, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "../playbook.js";
+import { isRecord } from "../parsing.js";
+import { buildPromptPolicy, getLatestUserMessage, getMessageText } from "../prompt-policy.js";
+import { AGENT_BROWSER_INSTRUCTION_GROUP, AGENT_BROWSER_TOOL_INVENTORY } from "../tool-surface.js";
+import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "../config.js";
+import { createAgentBrowserWebSearchTool } from "../web-search.js";
+import { isDirectAgentBrowserBashAllowed, isHarmlessAgentBrowserInspectionCommand, looksLikeDirectAgentBrowserBash, } from "../bash-guard.js";
+export function isBashToolCallEvent(event) {
+    return (isRecord(event) &&
+        event.toolName === "bash" &&
+        isRecord(event.input) &&
+        typeof event.input.command === "string");
+}
+export function findPackageRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+            if (isRecord(packageJson) && packageJson.name === "pi-agent-browser-native") {
+                return currentDir;
+            }
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return startDir;
+        }
+        currentDir = parentDir;
+    }
+}
+export function getInstalledDocsPaths() {
+    const root = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+    return {
+        readmePath: join(root, "README.md"),
+        commandReferencePath: join(root, "docs", "COMMAND_REFERENCE.md"),
+        toolContractPath: join(root, "docs", "TOOL_CONTRACT.md"),
+    };
+}
+export function hasArgvFlag(argv, longFlag, shortFlag) {
+    return argv.includes(longFlag) || argv.includes(shortFlag);
+}
+export function shouldIncludeProjectConfig(ctx, argv = process.argv) {
+    return !hasArgvFlag(argv, "--no-approve", "-na") && ctx.isProjectTrusted();
+}
+/** Owns prompt caching and companion registration, never browser or artifact state. */
+export class BrowserPrompt {
+    pi;
+    state;
+    webSearchToolRegistered = false;
+    constructor(pi) {
+        this.pi = pi;
+    }
+    restore(ctx) {
+        this.state = {
+            sessionId: ctx.sessionManager.getSessionId(),
+            message: getLatestUserMessage(ctx.sessionManager),
+        };
+        return this.state;
+    }
+    policy(ctx) {
+        const state = this.state?.sessionId === ctx.sessionManager.getSessionId() ? this.state : this.restore(ctx);
+        // Keep the native message reference: later transforms must be reflected in policy.
+        const text = getMessageText(state.message?.content);
+        if (!state.policy || state.text !== text) {
+            state.text = text;
+            state.policy = buildPromptPolicy(text);
+        }
+        return state.policy;
+    }
+    registerWebSearch(config) {
+        if (this.webSearchToolRegistered || !canRegisterWebSearchTool(config)) {
+            return;
+        }
+        this.pi.registerTool({
+            ...createAgentBrowserWebSearchTool(config, {
+                loadConfigState(ctx) {
+                    return loadAgentBrowserConfigSync({
+                        cwd: ctx.cwd,
+                        includeProjectConfig: shouldIncludeProjectConfig(ctx),
+                    });
+                },
+            }),
+        });
+        this.webSearchToolRegistered = true;
+    }
+    instructions(ctx) {
+        const config = loadAgentBrowserConfigSync({
+            cwd: ctx.cwd,
+            includeProjectConfig: shouldIncludeProjectConfig(ctx),
+        });
+        const guidance = [
+            config.browserExecutablePathScope === "project"
+                ? buildBrowserExecutablePathGuideline(config.browserExecutablePath)
+                : undefined,
+            config.browserDefaultProfileScope === "project"
+                ? buildBrowserDefaultProfileGuideline(config.browserDefaultProfile)
+                : undefined,
+        ].filter((line) => typeof line === "string" && line.length > 0);
+        const configPrompt = guidance.length > 0
+            ? `\n\nProject agent_browser config guidance:\n${guidance.map((line) => `- ${line}`).join("\n")}`
+            : "";
+        const guidelines = [
+            ...buildToolPromptGuidelines({
+                browserDefaultProfile: config.trustedBrowserDefaultProfile,
+                browserExecutablePath: config.trustedBrowserExecutablePath,
+                includeWebSearch: this.webSearchToolRegistered,
+                docs: getInstalledDocsPaths(),
+            }),
+            ...QUICK_START_GUIDELINES,
+            ...SHARED_BROWSER_PLAYBOOK_GUIDELINES,
+            ...WRAPPER_TAB_RECOVERY_BEHAVIOR,
+            ...Object.values(ADVANCED_TOOL_PROMPT_GUIDELINES).flat(),
+            ...(this.webSearchToolRegistered ? WEB_SEARCH_TOOL_PROMPT_GUIDELINES : []),
+        ];
+        return `${PROJECT_RULE_PROMPT}\n\n${[...new Set(guidelines)].map((line) => `- ${line}`).join("\n")}${configPrompt}`;
+    }
+    registerCollector(data, setManaged) {
+        if (!isRecord(data) ||
+            typeof data.register !== "function" ||
+            typeof data.isManaged !== "function") {
+            throw new Error("Invalid Pi instruction-group collector.");
+        }
+        const register = data.register;
+        const isManaged = data.isManaged;
+        Reflect.apply(register, data, [
+            {
+                ...AGENT_BROWSER_INSTRUCTION_GROUP,
+                tools: [
+                    "agent_browser",
+                    "agent_browser_code",
+                    "agent_browser_tools",
+                    "agent_browser_web_search",
+                    ...Object.values(AGENT_BROWSER_TOOL_INVENTORY).map(({ name }) => name),
+                ],
+                instructions: (ctx) => this.instructions(ctx),
+            },
+        ]);
+        setManaged(() => {
+            const managed = Reflect.apply(isManaged, undefined, []);
+            if (typeof managed !== "boolean") {
+                throw new Error("Pi instruction-group ownership must be boolean.");
+            }
+            return managed;
+        });
+    }
+    register() {
+        let isInstructionsManaged = () => false;
+        this.pi.on("message_end", (event, ctx) => {
+            if (event.message.role === "user") {
+                this.state = { sessionId: ctx.sessionManager.getSessionId(), message: event.message };
+            }
+        });
+        this.pi.events.on("pi:instruction-groups", (data) => this.registerCollector(data, (managed) => {
+            isInstructionsManaged = managed;
+        }));
+        this.pi.on("before_agent_start", async (event, ctx) => {
+            if (!isInstructionsManaged()) {
+                event.systemPromptOptions.sections.agent_browser = this.instructions(ctx);
+            }
+        });
+        this.pi.on("tool_call", async (event, ctx) => {
+            if (!isBashToolCallEvent(event) ||
+                !looksLikeDirectAgentBrowserBash(event.input.command) ||
+                isHarmlessAgentBrowserInspectionCommand(event.input.command)) {
+                return;
+            }
+            if (!this.policy(ctx).allowLegacyAgentBrowserBash &&
+                !(await isDirectAgentBrowserBashAllowed(ctx.cwd))) {
+                return {
+                    block: true,
+                    reason: "Use the native agent_browser tool instead of bash for agent-browser in this environment.",
+                };
+            }
+            return;
+        });
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-recording.js

@@ -0,0 +1,290 @@
+import { extractUpstreamCommandTokens } from "../runtime.js";
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
+import { isRecord } from "../parsing.js";
+import { isCloseCommand } from "../command-taxonomy.js";
+import { applyNamespaceToNextActions, applySessionToNextActions, buildNextToolAction, } from "../results/next-actions.js";
+import { appendRecordingReservationTransition, applyRecordingArtifactsToReservations, retireRecordingReservation, restoreRecordingReservationStateFromBranch, } from "../recording-reservations.js";
+import { isResultFileArtifact, getResultFileArtifacts } from "./extension-result-state.js";
+const recordingPersistenceWarning = "Recording persistence warning: recording protection could not be saved to the Pi journal. Restart protection is not yet durable; keep recording destinations untouched until exact stop or close. The next browser operation retries journal persistence; cleanup remains available.";
+/** Owns the durable unbounded recording index separately from the bounded artifact manifest. */
+export class BrowserRecordingRegistry {
+    pi;
+    artifacts;
+    getCwd;
+    active = new Map();
+    terminal = new Map();
+    persistenceDirty = false;
+    constructor(pi, artifacts, getCwd) {
+        this.pi = pi;
+        this.artifacts = artifacts;
+        this.getCwd = getCwd;
+    }
+    get dirty() {
+        return this.persistenceDirty;
+    }
+    flush() {
+        if (!this.persistenceDirty) {
+            return;
+        }
+        try {
+            // A failed append may mask earlier reservations; republish the full current index.
+            for (const reservation of this.terminal.values()) {
+                appendRecordingReservationTransition(this.pi, { reservation, state: "closed" });
+            }
+            for (const reservation of this.active.values()) {
+                appendRecordingReservationTransition(this.pi, { reservation, state: "active" });
+            }
+            this.persistenceDirty = false;
+        }
+        catch {
+            // Keep the dirty index for the next operation's persistence retry.
+        }
+    }
+    append(transitions) {
+        for (const transition of transitions) {
+            const key = getAgentBrowserSessionIdentityKey(transition.reservation.sessionName, transition.reservation.namespace);
+            if (transition.state === "active") {
+                this.terminal.delete(key);
+            }
+            else {
+                this.terminal.set(key, transition.reservation);
+            }
+            if (this.persistenceDirty) {
+                continue;
+            }
+            try {
+                appendRecordingReservationTransition(this.pi, transition);
+            }
+            catch {
+                this.persistenceDirty = true;
+            }
+        }
+    }
+    applyArtifacts(artifacts) {
+        this.append(applyRecordingArtifactsToReservations(this.active, artifacts));
+    }
+    retire(sessionName, namespace, retireManifest = true) {
+        const reservation = retireRecordingReservation(this.active, sessionName, namespace);
+        const changed = retireManifest && this.artifacts.retireRecording(sessionName, namespace);
+        if (!reservation && !changed) {
+            return;
+        }
+        const terminal = reservation ?? {
+            absolutePath: "",
+            cwd: this.getCwd(),
+            namespace,
+            path: "",
+            sessionName,
+        };
+        this.append([{ reservation: terminal, state: "closed" }]);
+    }
+    restore(branch) {
+        const restored = restoreRecordingReservationStateFromBranch([...branch]);
+        for (const key of this.terminal.keys()) {
+            if (!restored.terminal.has(key)) {
+                this.persistenceDirty = true;
+            }
+        }
+        for (const [key, reservation] of restored.terminal) {
+            if (!this.active.has(key)) {
+                this.terminal.set(key, reservation);
+            }
+        }
+        for (const [key, reservation] of this.terminal) {
+            restored.active.delete(key);
+            this.artifacts.retireRecording(reservation.sessionName, reservation.namespace);
+        }
+        for (const [key, reservation] of this.active) {
+            if (recordingReservationChanged(restored.active.get(key), reservation)) {
+                this.persistenceDirty = true;
+            }
+            restored.active.set(key, reservation);
+        }
+        this.active = restored.active;
+    }
+    resetIfClean() {
+        if (!this.persistenceDirty) {
+            this.active = new Map();
+            this.terminal.clear();
+        }
+    }
+    syncResult(result) {
+        const details = isRecord(result.details) ? result.details : undefined;
+        const steps = Array.isArray(details?.batchSteps)
+            ? details.batchSteps
+            : undefined;
+        if (!steps) {
+            this.applyArtifacts(getResultFileArtifacts(result));
+            return new Set();
+        }
+        const fold = new RecordingBatchFold(this, typeof details?.sessionName === "string" ? details.sessionName : undefined, typeof details?.namespace === "string" ? details.namespace : undefined);
+        for (const step of steps) {
+            fold.apply(step);
+        }
+        return fold.finish();
+    }
+    retireManifest(sessionName, namespace) {
+        this.artifacts.retireRecording(sessionName, namespace);
+    }
+}
+function recordingReservationChanged(prior, current) {
+    return (prior?.absolutePath !== current.absolutePath ||
+        prior.cwd !== current.cwd ||
+        prior.recordingId !== current.recordingId ||
+        prior.startedAtMs !== current.startedAtMs ||
+        prior.contactSheetPath !== current.contactSheetPath);
+}
+function warningJson(text) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return isRecord(json) && typeof json.success === "boolean" ? json : undefined;
+}
+export function warnRecordingPersistence(dirty, result) {
+    if (!dirty) {
+        return result;
+    }
+    const content = [...result.content];
+    const first = content.at(0);
+    const json = first?.type === "text" ? warningJson(first.text) : undefined;
+    if (json) {
+        const warnings = Array.isArray(json.warnings) ? json.warnings : [];
+        content[0] = {
+            type: "text",
+            text: JSON.stringify({ ...json, warnings: [...warnings, recordingPersistenceWarning] }, null, 2),
+        };
+    }
+    else if (first?.type === "text") {
+        content[0] = { ...first, text: `${first.text}\n\n${recordingPersistenceWarning}` };
+    }
+    else {
+        content.push({ type: "text", text: recordingPersistenceWarning });
+    }
+    return {
+        ...result,
+        content,
+        details: { ...(isRecord(result.details) ? result.details : {}), recordingPersistenceWarning },
+    };
+}
+export function notifyRecordingPersistence(dirty, ctx) {
+    if (!dirty) {
+        return;
+    }
+    if (ctx?.hasUI === true) {
+        ctx.ui.notify(recordingPersistenceWarning, "warning");
+    }
+    else {
+        console.warn(recordingPersistenceWarning);
+    }
+}
+function recordingCleanupActions(reservation, cleanupOnly) {
+    const action = buildNextToolAction({
+        args: cleanupOnly ? ["close"] : ["record", "stop"],
+        id: cleanupOnly ? "close-pending-recording" : "stop-pending-recording",
+        reason: cleanupOnly
+            ? "Close this exact session to abandon the recording; its live daemon lacks current-instance provenance."
+            : "Stop the active recording so the requested video can be finalized and verified on disk.",
+        safety: cleanupOnly
+            ? "Close does not verify the WebM. The recording is abandoned/unverified, even if close leaves a file on disk."
+            : "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
+    });
+    return applyNamespaceToNextActions(applySessionToNextActions([action], reservation.sessionName), cleanupOnly ? (reservation.namespace ?? "") : reservation.namespace);
+}
+export function appendActiveRecordingCleanupAction(result, reservation) {
+    if (result.isError !== true) {
+        return result;
+    }
+    const details = isRecord(result.details) ? result.details : {};
+    const recordingRecovered = Boolean(details.recordingRecovery);
+    if (recordingRecovered) {
+        return result;
+    }
+    const cleanupOnly = details.managedSessionCleanupOnlyReason === "restore-disabled-daemon-without-provenance";
+    const existing = Array.isArray(details.nextActions)
+        ? details.nextActions
+        : [];
+    const nextActions = existing.filter((action) => !cleanupOnly || !isRecord(action) || action.id !== "stop-pending-recording");
+    const actionId = cleanupOnly ? "close-pending-recording" : "stop-pending-recording";
+    if (nextActions.some((action) => isRecord(action) && action.id === actionId)) {
+        return result;
+    }
+    nextActions.push(...(recordingCleanupActions(reservation, cleanupOnly) ?? []));
+    const notice = cleanupOnly
+        ? "This recording cannot be stopped through the unproven daemon. Use the exact close-pending-recording payload in details.nextActions; any WebM left by close is abandoned/unverified."
+        : "An active recording remains open. Use the exact stop-pending-recording payload in details.nextActions before leaving this session.";
+    const firstText = result.content.findIndex((item) => item.type === "text");
+    const content = result.content.map((item, index) => index === firstText && item.type === "text"
+        ? { ...item, text: `${item.text}\n\n${notice}` }
+        : item);
+    if (firstText < 0) {
+        content.push({ type: "text", text: notice });
+    }
+    return { ...result, content, details: { ...details, nextActions } };
+}
+function recordingStepCommand(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const tokens = value;
+    return tokens.every((token) => typeof token === "string") ? tokens : undefined;
+}
+class RecordingBatchFold {
+    registry;
+    sessionName;
+    namespace;
+    handled = new Set();
+    sessionClosed = false;
+    constructor(registry, sessionName, namespace) {
+        this.registry = registry;
+        this.sessionName = sessionName;
+        this.namespace = namespace;
+    }
+    closeRow(step, command) {
+        if (step.success !== true ||
+            command === undefined ||
+            command === "" ||
+            !isCloseCommand(command) ||
+            this.sessionName === undefined ||
+            this.sessionName === "") {
+            return false;
+        }
+        this.registry.retire(this.sessionName, this.namespace, false);
+        this.handled.add(getAgentBrowserSessionIdentityKey(this.sessionName, this.namespace));
+        this.sessionClosed = true;
+        return true;
+    }
+    apply(step) {
+        if (!isRecord(step)) {
+            return;
+        }
+        const command = recordingStepCommand(step.command);
+        const name = command ? extractUpstreamCommandTokens(command)[0] : undefined;
+        if (this.closeRow(step, name)) {
+            return;
+        }
+        if (this.sessionClosed && name === "record") {
+            return;
+        }
+        if (step.success === true && this.sessionClosed) {
+            this.sessionClosed = false;
+        }
+        const artifacts = Array.isArray(step.artifacts)
+            ? step.artifacts.filter(isResultFileArtifact)
+            : [];
+        this.registry.applyArtifacts(artifacts);
+    }
+    finish() {
+        for (const key of this.handled) {
+            if (!this.registry.active.has(key) &&
+                this.sessionName !== undefined &&
+                this.sessionName !== "") {
+                this.registry.retireManifest(this.sessionName, this.namespace);
+            }
+        }
+        return this.handled;
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/extension-resource-contracts.js

@@ -0,0 +1 @@
+export {};