pi-agent-browser-native 0.2.77 → 0.5.0

package/dist/extensions/agent-browser/lib/process.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Execute the upstream agent-browser binary for the pi-agent-browser extension.
- * Responsibilities: Validate POSIX socket storage, spawn the agent-browser subprocess, forward parent environment variables plus wrapper overrides, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
- * Scope: Process execution only; argument planning, output formatting, and pi tool registration live elsewhere.
- * Usage: Called by the extension tool after argument validation and session planning are complete.
- * Invariants/Assumptions: The binary name is always `agent-browser`; Windows routes through PowerShell to invoke npm launchers with escaped argv; callers handle semantic success/error interpretation.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn } from "node:child_process";
 import { lstat, mkdir, readdir } from "node:fs/promises";
@@ -13,10 +6,11 @@ import { env as processEnv, platform as processPlatform } from "node:process";
 import { parseArgvDescriptor } from "./argv-descriptor.js";
 import { needsManagedSession } from "./command-policy.js";
 import { isKnownCommandToken } from "./command-taxonomy.js";
-import { getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
-import { canonicalizeOwnedManagedSessionCloseArgs, commitManagedSessionRestoreSuppression, getManagedSessionRestoreConfigEnv, getManagedSessionRestoreEnv, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, shouldOmitOwnedManagedSessionRestoreEnv, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
-import { getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, } from "./managed-session-state-policy.js";
+import { extractExplicitSessionName, getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, resolveAgentBrowserNamespace, } from "./argv-grammar.js";
+import { canonicalizeOwnedManagedSessionCloseArgs, commitManagedSessionRestoreSuppression, getManagedSessionRestoreConfigEnv, getManagedSessionRestoreEnv, getOwnedManagedSessionRestoreKey, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, shouldOmitOwnedManagedSessionRestoreEnv, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
+import { getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, invocationMayNavigateToLocalFile, } from "./managed-session-state-policy.js";
 import { getImplicitSessionIdleTimeoutMs, isPlainTextInspectionArgs } from "./runtime.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
 const MAX_BUFFERED_STDERR_CHARS = 32_000;
@@ -27,16 +21,29 @@ const AGENT_BROWSER_ARGS_ENV = "AGENT_BROWSER_ARGS";
 const AGENT_BROWSER_DEFAULT_TIMEOUT_ENV = "AGENT_BROWSER_DEFAULT_TIMEOUT";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
 const PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS";
+const PI_AGENT_BROWSER_SOCKET_DIR_ENV = "PI_AGENT_BROWSER_SOCKET_DIR";
 const DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX = "/tmp/piab";
+const TERMUX_PACKAGE_NAME_PATTERN = /^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/;
 export const SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS = 25_000;
 const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 35_000;
 /** Grace period after `exit` before resolving when `close` is delayed by inherited stdio handles. */
 const EXIT_STDIO_GRACE_MS = 100;
 const WINDOWS_AGENT_BROWSER_MISSING_MARKER = "PI_AGENT_BROWSER_COMMAND_NOT_FOUND:agent-browser.cmd";
+const UNTRUSTED_LOCAL_FILE_SESSION_MESSAGE = "Local file navigation requires a wrapper-managed local browser because caller-owned or attached sessions can retain unsafe file-access launch flags. Omit the explicit session or attachment and retry with sessionMode fresh.";
 const attachedBrowserSessionContext = new AsyncLocalStorage();
+const WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND = new Set([
+    "auth", "clipboard", "cookies", "dashboard", "device", "dialog", "diff", "find", "get", "is", "keyboard",
+    "mouse", "network", "plugin", "profiler", "react", "record", "session", "set", "skills", "state", "storage",
+    "stream", "tab", "trace", "window",
+]);
 export function withAttachedBrowserSessionContext(preserve, run) {
     return attachedBrowserSessionContext.run(preserve || attachedBrowserSessionContext.getStore() === true, run);
 }
+export function getWindowsExplicitDefaultNamespaceEnv(args, parentNamespace, platform = processPlatform) {
+    return platform === "win32" && resolveAgentBrowserNamespace(args, parentNamespace) === ""
+        ? { AGENT_BROWSER_NAMESPACE: "" }
+        : {};
+}
 function appendTail(text, addition, maxChars) {
     const combined = text + addition;
     return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
@@ -50,7 +57,12 @@ export function reorderWindowsLeadingGlobalArgs(args) {
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
         if (isKnownCommandToken(token)) {
-            return index === 0 ? args : [token, ...leadingGlobals, ...args.slice(index + 1)];
+            if (index === 0)
+                return args;
+            const firstPositional = args[index + 1];
+            return WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND.has(token) && firstPositional && !firstPositional.startsWith("-")
+                ? [token, firstPositional, ...leadingGlobals, ...args.slice(index + 2)]
+                : [token, ...leadingGlobals, ...args.slice(index + 1)];
         }
         if (!token.startsWith("-"))
             return args;
@@ -84,6 +96,13 @@ export function reorderWindowsLeadingGlobalArgs(args) {
             const value = args[index + 1];
             if (value === undefined)
                 return args;
+            // PowerShell -> .cmd drops empty argv values. Planning rejects empty
+            // caller --args; keep this defensive skip so an unexpected empty value
+            // cannot turn the next flag into its accidental value on native Windows.
+            if (value === "" && (flag === "--args" || flag === "--namespace")) {
+                index += 1;
+                continue;
+            }
             leadingGlobals.push(token, value);
             index += 1;
             continue;
@@ -110,9 +129,9 @@ export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUser
         return filtered;
     // Upstream's flag overrides only the active CDP target; the Chrome arg covers new tabs. Its --args parser splits commas/newlines.
     const browserArgs = wrapperCompatibilityUserAgent
-        ? `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`
-        : "";
-    return ["--args", browserArgs, "--allow-file-access", "false", ...filtered];
+        ? ["--args", `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`]
+        : [];
+    return [...browserArgs, "--allow-file-access", "false", ...filtered];
 }
 export function buildAgentBrowserSpawnCommand(args, platform = processPlatform) {
     if (platform !== "win32") {
@@ -223,33 +242,43 @@ function clampUpstreamDefaultTimeout(childEnv) {
 export function getAgentBrowserProcessTimeoutMs(env = processEnv) {
     return parsePositiveIntegerEnv(env[PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV]) ?? DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS;
 }
-export function getAgentBrowserSocketDir(platform = processPlatform, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+export function getAgentBrowserSocketDir(platform = processPlatform, uid = typeof process.getuid === "function" ? process.getuid() : undefined, termuxPackageName = processEnv.TERMUX_APP__PACKAGE_NAME) {
     if (platform === "win32") {
         return undefined;
     }
-    const prefix = platform === "darwin" ? "/private/tmp/piab" : DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX;
-    return `${prefix}${typeof uid === "number" ? `-${uid}` : ""}`;
+    const termuxAppRoot = platform === "android" && termuxPackageName && TERMUX_PACKAGE_NAME_PATTERN.test(termuxPackageName);
+    const prefix = platform === "darwin"
+        ? "/private/tmp/piab"
+        : termuxAppRoot
+            ? `/data/data/${termuxPackageName}/piab`
+            : DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX;
+    return `${prefix}${!termuxAppRoot && typeof uid === "number" ? `-${uid}` : ""}`;
+}
+export function isTrustedAndroidAppDataRoot(path, metadata, uid, platform = processPlatform) {
+    if (platform !== "android" || metadata.uid !== uid || metadata.isSymbolicLink() || !metadata.isDirectory() || (metadata.mode & 0o777) !== 0o700)
+        return false;
+    const parent = dirname(path);
+    return parent === "/data/data" || /^\/data\/user\/\d+$/.test(parent);
+}
+export function isTrustedSocketDirAncestor(metadata, uid, platform = processPlatform) {
+    if (metadata.isSymbolicLink())
+        return metadata.uid === 0;
+    if (!metadata.isDirectory())
+        return false;
+    const mode = metadata.mode & 0o7777;
+    if (platform === "android" && uid !== 0 && metadata.uid === uid && metadata.gid === uid)
+        return (mode & 0o002) === 0;
+    if (metadata.uid === uid && uid !== 0)
+        return (mode & 0o022) === 0;
+    return metadata.uid === 0 && ((mode & 0o022) === 0 || (mode & 0o1000) !== 0);
 }
 async function hasTrustedSocketDirAncestry(socketDir, uid) {
     for (let current = dirname(socketDir);;) {
         const metadata = await lstat(current);
-        if (metadata.isSymbolicLink()) {
-            if (metadata.uid !== 0)
-                return false;
-        }
-        else if (!metadata.isDirectory()) {
+        if (isTrustedAndroidAppDataRoot(current, metadata, uid))
+            return true;
+        if (!isTrustedSocketDirAncestor(metadata, uid))
             return false;
-        }
-        if (!metadata.isSymbolicLink()) {
-            const mode = metadata.mode & 0o7777;
-            if (metadata.uid === uid) {
-                if ((mode & 0o022) !== 0)
-                    return false;
-            }
-            else if (metadata.uid !== 0 || ((mode & 0o022) !== 0 && (mode & 0o1000) === 0)) {
-                return false;
-            }
-        }
         const parent = dirname(current);
         if (parent === current)
             return true;
@@ -280,28 +309,64 @@ async function socketDirEntriesAreOwned(socketDir, uid, visited = { count: 0 })
     }
     return true;
 }
-export async function ensureAgentBrowserSocketDir(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
-    if (!isAbsolute(socketDir) || typeof uid !== "number")
-        return false;
+export async function getAgentBrowserSocketDirValidationError(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+    if (!isAbsolute(socketDir))
+        return "the path is not absolute";
+    if (typeof uid !== "number")
+        return "POSIX ownership metadata is unavailable";
     try {
         if (!await hasTrustedSocketDirAncestry(socketDir, uid))
-            return false;
+            return "an ancestor is writable, foreign-owned, a non-directory, or an untrusted symlink";
         try {
             await mkdir(socketDir, { mode: 0o700 });
         }
         catch (error) {
             if (error.code !== "EEXIST")
-                return false;
+                return `the directory could not be created (${error.code ?? "unknown error"})`;
         }
         const metadata = await lstat(socketDir);
-        if (!metadata.isDirectory() || metadata.isSymbolicLink() || metadata.uid !== uid || (metadata.mode & 0o777) !== 0o700)
-            return false;
-        return await hasTrustedSocketDirAncestry(socketDir, uid) && await socketDirEntriesAreOwned(socketDir, uid);
+        if (!metadata.isDirectory())
+            return "the path is not a directory";
+        if (metadata.isSymbolicLink())
+            return "the directory is a symlink";
+        if (metadata.uid !== uid)
+            return `the directory is owned by uid ${metadata.uid}, not uid ${uid}`;
+        if ((metadata.mode & 0o777) !== 0o700)
+            return `the directory mode is ${(metadata.mode & 0o777).toString(8)}, not 700`;
+        if (!await hasTrustedSocketDirAncestry(socketDir, uid))
+            return "an ancestor became untrusted during validation";
+        if (!await socketDirEntriesAreOwned(socketDir, uid))
+            return "the directory contains a foreign-owned, symlink, special, or excessively deep entry";
+        return undefined;
     }
-    catch {
-        return false;
+    catch (error) {
+        return `the directory could not be inspected (${error.code ?? "unknown error"})`;
     }
 }
+export async function ensureAgentBrowserSocketDir(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+    return await getAgentBrowserSocketDirValidationError(socketDir, uid) === undefined;
+}
+export function getAgentBrowserSocketPathValidationError(options) {
+    if ((options.platform ?? processPlatform) === "win32")
+        return undefined;
+    const descriptor = parseArgvDescriptor(options.args);
+    const { command } = descriptor.commandInfo;
+    // Preflight commands that can start or navigate a browser. Follow-up reads and
+    // cleanup may target a daemon created by an earlier wrapper version, so let
+    // upstream inspect those identities instead of rejecting them from path math.
+    if (!command || !["batch", "connect", "goto", "navigate", "open", "visit"].includes(command))
+        return undefined;
+    const sessionName = extractExplicitSessionName(options.args);
+    if (!sessionName)
+        return undefined;
+    const namespace = resolveAgentBrowserNamespace(options.args, options.env?.AGENT_BROWSER_NAMESPACE);
+    const socketRoot = namespace ? join(options.socketDir, "namespaces", namespace, "run") : options.socketDir;
+    const socketPath = join(socketRoot, `${sessionName}.sock`);
+    const pathBytes = Buffer.byteLength(socketPath);
+    if (pathBytes <= 103)
+        return undefined;
+    return `Agent-browser Unix socket path would be ${pathBytes} bytes (max 103) for session ${JSON.stringify(sessionName)} under ${JSON.stringify(options.socketDir)}. Set PI_AGENT_BROWSER_SOCKET_DIR to a shorter absolute private directory such as /tmp/piab-<uid> with mode 0700; retrying sessionMode \"fresh\" cannot shorten this configured root.`;
+}
 export function buildAgentBrowserProcessEnv(baseEnv = processEnv, overrides = undefined) {
     const childEnv = {};
     for (const [name, value] of Object.entries(baseEnv)) {
@@ -332,6 +397,7 @@ function getManagedPreSpawnPolicyError(options, effectiveEnv, allowManagedSessio
         currentPageUrl,
         cwd: options.cwd,
         env: effectiveEnv ?? options.env,
+        managedSessionRestoreKey: getOwnedManagedSessionRestoreKey(),
         pageUrlUnknown,
         parentEnv: effectiveEnv ? {} : options.parentEnv ?? processEnv,
         stdin: options.stdin,
@@ -355,11 +421,24 @@ export async function runAgentBrowserProcess(options) {
     if (signal?.aborted) {
         return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
     }
+    if (invocationMayNavigateToLocalFile(args, stdin) && (!ownedManagedSession || preserveAttachedBrowserSession)) {
+        return {
+            aborted: false,
+            agentBrowserStarted: false,
+            exitCode: 1,
+            spawnError: new Error(UNTRUSTED_LOCAL_FILE_SESSION_MESSAGE),
+            stderr: "",
+            stdout: "",
+            timedOut: false,
+        };
+    }
+    const parentEnv = getAgentBrowserProcessEnvironment();
     const managedSessionRestoreOptions = {
         args,
         cwd,
         env,
         ownedManagedSession,
+        parentEnv,
         restoreState: managedSessionRestoreState,
         stdin,
     };
@@ -398,6 +477,7 @@ export async function runAgentBrowserProcess(options) {
         ...managedSessionRestoreConfigEnv,
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
         ...getOwnedManagedSessionNamespaceEnv(managedSessionRestoreOptions),
+        ...getWindowsExplicitDefaultNamespaceEnv(args, parentEnv.AGENT_BROWSER_NAMESPACE),
         ...ownedManagedSessionCompatibilityEnv,
         AGENT_BROWSER_ALLOW_FILE_ACCESS: undefined,
         [AGENT_BROWSER_ARGS_ENV]: undefined,
@@ -406,18 +486,21 @@ export async function runAgentBrowserProcess(options) {
     let effectiveEnv = explicitSocketDir === undefined ? { ...processOverrides, [AGENT_BROWSER_SOCKET_DIR_ENV]: undefined } : processOverrides;
     if (ownedManagedSessionClose)
         effectiveEnv = { ...effectiveEnv, AGENT_BROWSER_RESTORE: undefined };
-    const requestedSocketDir = explicitSocketDir ?? getAgentBrowserSocketDir();
+    const requestedSocketDir = explicitSocketDir ?? parentEnv[PI_AGENT_BROWSER_SOCKET_DIR_ENV] ?? getAgentBrowserSocketDir();
     if (requestedSocketDir !== undefined) {
-        const socketDirIsSecure = requestedSocketDir.length > 0 && await ensureAgentBrowserSocketDir(requestedSocketDir);
+        const socketDirError = requestedSocketDir.length > 0
+            ? await getAgentBrowserSocketDirValidationError(requestedSocketDir)
+            : "the configured path is empty";
         if (signal?.aborted) {
             return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
         }
-        if (!socketDirIsSecure) {
+        const socketPathError = socketDirError ? undefined : getAgentBrowserSocketPathValidationError({ args, env: effectiveEnv, socketDir: requestedSocketDir });
+        if (socketDirError || socketPathError) {
             return {
                 aborted: false,
                 agentBrowserStarted: false,
                 exitCode: 1,
-                spawnError: new Error("Agent-browser socket storage must be an absolute, non-symlink directory owned by the current user with mode 0700."),
+                spawnError: new Error(socketPathError ?? `Agent-browser socket storage ${JSON.stringify(requestedSocketDir)} is unusable: ${socketDirError}. Use an absolute directory owned by the current uid with mode 0700 and remove foreign, symlink, or special entries.`),
                 stderr: "",
                 stdout: "",
                 timedOut: false,
@@ -528,7 +611,7 @@ export async function runAgentBrowserProcess(options) {
                 });
             });
         };
-        const childEnv = buildAgentBrowserProcessEnv(processEnv, effectiveEnv);
+        const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
         const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, childEnv, allowManagedSessionTarget, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection, managedSessionRestoreConfigEnv.AGENT_BROWSER_CONFIG !== undefined);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });

package/dist/extensions/agent-browser/lib/prompt-policy.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Derive operator prompt constraints for browser-run preflight guards and legacy bash policy.
- * Responsibilities: Parse the latest user message into requested artifact paths and legacy bash allowance.
- * Scope: Pure prompt-text policy; enforcement lives in orchestration prompt-guards and the extension entrypoint.
- */
 const BROWSER_PROMPT_PATTERNS = [
     /\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
     /\b(?:react\s+(?:tree|inspect|renders|suspense)|web\s+vitals|core\s+web\s+vitals|pushstate)\b/i,
@@ -17,41 +12,190 @@ const LEGACY_BASH_ALLOW_PATTERNS = [
     /\bagent-browser\s+--(?:help|version)\b/i,
     /\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
 ];
-const PROMPT_ARTIFACT_PATH_PATTERN = /(?:^|[\s"'`(:])((?:\/[^\s"'`),;]+|[A-Za-z]:[\\/][^\s"'`),;]+|\.{1,2}[\\/][^\s"'`),;]+|[^\s"'`),;:\\/]+(?:[\\/][^\s"'`),;]+)+|[^\s"'`),;:\\/]+)\.(?:png|jpe?g|webp|gif|webm|mp4|har|pdf|trace|json))(?:[\s"'`),;.]|$)/gi;
-function inferPromptArtifactKind(line, path) {
+const PROMPT_ARTIFACT_PATH_PATTERN = /(?:^|[\s"'`(:])((?:\/[^\s"'`),;]+|[A-Za-z]:[\\/][^\s"'`),;]+|\.{1,2}[\\/][^\s"'`),;]+|[^\s"'`()[\],;:\\/]+(?:[\\/][^\s"'`()[\],;\\/]+)+|[^\s"'`()[\],;:\\/]+)\.(?:png|jpe?g|webp|gif|webm|mp4|har|pdf|trace|json))(?=[\s"'`),;.!?]|$)/gi;
+const PROMPT_ARTIFACT_COLON_OUTPUT_INTENT_PATTERN = /\b(?:capture|create|export|generate|output|record|render|save|screenshot|start|take|write)\s+(?:(?:a|an|another|the)\s+)?(?:short\s+)?(?:(?:full[- ]page|page|screen)\s+)?(?:image|page|recordings?|screenshots?|screen|video)\s*:\s*$/i;
+const PROMPT_ARTIFACT_OUTPUT_INTENT_PATTERN = /\b(?:capture|create|export|generate|output|record|render|save|screenshot|start|take|write)\s+(?:(?:a|an|another|the|this)\s+)?(?:short\s+)?(?:(?:full[- ]page|page|screen)\s+)?(?:image|page|recordings?|screenshots?|screen|video)\s+(?:directly\s+)?(?:\b(?:at|as|to)\b\s*[:=-]?|\bhere\b(?:\s+(?:if|when)\s+(?:recordings?\s+)?(?:(?:are|is)\s+)?available)?\s*[:=-]?)\s*$|\b(?:export|output|save|write)\s+(?:it\s+)?(?:at|as|to)\s*[:=-]?\s*$/i;
+const PROMPT_ARTIFACT_UNSAFE_OUTPUT_PREFIX_PATTERN = /n['’]t\b|\b(?:cannot|disallowed|forbidden|maybe|needed|never|no|not|optional(?:ly)?|perhaps|prohibited|rather|refrain|unable|without)\b|\b(?:he|i|it|she|they|we|you)\s+(?:can|could|may|might)\b/i;
+const PROMPT_ARTIFACT_AFFIRMATIVE_PREFIX_PATTERN = /^(?:(?:and(?:\s+then)?|then)(?:\s+please)?|please|you|(?:be|make)\s+sure\s+to|(?:can|could|will|would)\s+you(?:\s+please)?|(?:i|we)\s+(?:need|want)\s+you\s+to|you\s+(?:must|should))$/i;
+const PROMPT_ARTIFACT_AFFIRMATIVE_LEAD_IN_PATTERN = /^(?:please\s+)?(?:capture|create|export|generate|output|record|render|save|screenshot|start|take|write)\b.*(?:[,\-:–—]|\b(?:and|then))\s*$/i;
+const PROMPT_ARTIFACT_LIST_CONNECTOR_PATTERN = /^[\s"'`()\[\]{},;:.*!?\/&+>-]*(?:(?:and|or)[\s"'`()\[\]{},;:.*!?\/&+>-]*)?$/i;
+const PROMPT_ARTIFACT_LIST_PREFIX_PATTERN = /^\s*(?:(?:[-*+]|\d+[.)])\s*)/;
+const PROMPT_ARTIFACT_OPTIONAL_RECORDING_PATTERN = /\b(?:if|when)\s+(?:recordings?\s+)?(?:(?:are|is)\s+)?available\b/i;
+const PROMPT_ARTIFACT_STANDALONE_OPTIONAL_RECORDING_PATTERN = /^\s*(?:if|when)\s+(?:recordings?\s+)?(?:(?:are|is)\s+)?available[.:;]?\s*$/i;
+const PROMPT_ARTIFACT_EXPLICIT_OPTIONAL_PATTERN = /\b(?:optionally|if\s+(?:convenient|desired|needed|possible|you\s+can|you\s+want\s+to)|when\s+(?:convenient|desired|needed|possible)|only\s+if\s+you\s+(?:can|want\s+to))\b/i;
+const PROMPT_ARTIFACT_REFERENCE_INTENT_PATTERN = /\btake\s+the\s+(?:image|recording|screenshot|video)\s+(?:at|from)\b/i;
+const PROMPT_ARTIFACT_CLAUSE_BOUNDARY_PATTERN = /(?:[;.!?](?:\s|$)|\b(?:but|instead)\b)/i;
+function getPromptArtifactKind(path) {
     const lowerPath = path.toLowerCase();
     if (/\.(?:webm|mp4)$/.test(lowerPath))
         return "recording";
     if (/\.(?:png|jpe?g|webp|gif)$/.test(lowerPath))
         return "screenshot";
-    const lowerLine = line.toLowerCase();
-    if (lowerLine.includes("screenshot"))
-        return "screenshot";
-    if (/\b(?:screen\s+recording|recording|webm|video)\b/.test(lowerLine))
-        return "recording";
     return undefined;
 }
+function getPromptArtifactIntentClause(context) {
+    return context.split(PROMPT_ARTIFACT_CLAUSE_BOUNDARY_PATTERN).at(-1) ?? context;
+}
+function getPromptArtifactTrailingClause(context) {
+    return context.split(PROMPT_ARTIFACT_CLAUSE_BOUNDARY_PATTERN)[0] ?? context;
+}
+function hasPromptArtifactOutputIntent(context) {
+    const clause = getPromptArtifactIntentClause(context)
+        .replace(/\[[^\]\r\n]*\]\(\s*$/, "")
+        .replace(/[([{\"'`]+\s*$/, "");
+    const intentMatch = clause.match(PROMPT_ARTIFACT_OUTPUT_INTENT_PATTERN) ?? clause.match(PROMPT_ARTIFACT_COLON_OUTPUT_INTENT_PATTERN);
+    if (!intentMatch)
+        return false;
+    const prefix = clause.slice(0, intentMatch.index ?? 0);
+    const governingPrefix = prefix.split(/\b(?:before|unless|until)\b/i).at(-1) ?? prefix;
+    if (PROMPT_ARTIFACT_UNSAFE_OUTPUT_PREFIX_PATTERN.test(governingPrefix))
+        return false;
+    const normalizedPrefix = governingPrefix.trim();
+    return normalizedPrefix.length === 0
+        || PROMPT_ARTIFACT_AFFIRMATIVE_PREFIX_PATTERN.test(normalizedPrefix)
+        || PROMPT_ARTIFACT_AFFIRMATIVE_LEAD_IN_PATTERN.test(governingPrefix);
+}
+function stripPromptArtifactListPrefix(context) {
+    return context.replace(PROMPT_ARTIFACT_LIST_PREFIX_PATTERN, "");
+}
+function normalizePromptArtifactPath(path) {
+    return path.replace(/^[([{]+/, "");
+}
+function isLikelyInboundPromptArtifact(path) {
+    return /(?:^|[\\/])pi-(?:attachment|clipboard|paste|upload)-/i.test(path);
+}
 function extractPromptRequestedArtifacts(prompt) {
     const artifacts = [];
-    const seen = new Set();
-    for (const line of prompt.split(/\r?\n/)) {
+    const seen = new Map();
+    const lines = prompt.split(/\r?\n/);
+    let inCodeFence = false;
+    let listArtifactIndexes = [];
+    let listContinuation;
+    let pendingRecordingAvailability = false;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex] ?? "";
+        if (/^\s*(?:`{3,}|~{3,})/.test(line)) {
+            inCodeFence = !inCodeFence;
+            listArtifactIndexes = [];
+            listContinuation = undefined;
+            pendingRecordingAvailability = false;
+            continue;
+        }
+        if (inCodeFence)
+            continue;
         PROMPT_ARTIFACT_PATH_PATTERN.lastIndex = 0;
+        const pathMatches = [];
         for (const match of line.matchAll(PROMPT_ARTIFACT_PATH_PATTERN)) {
-            const path = match[1]?.trim();
-            if (!path)
-                continue;
-            const kind = inferPromptArtifactKind(line, path);
-            if (!kind)
+            const rawPath = match[1]?.trim();
+            const path = rawPath ? normalizePromptArtifactPath(rawPath) : undefined;
+            if (!path || !rawPath)
                 continue;
-            const key = `${kind}:${path}`;
-            if (seen.has(key))
+            const start = (match.index ?? 0) + match[0].indexOf(rawPath) + rawPath.indexOf(path);
+            pathMatches.push({ end: start + path.length, path, start });
+        }
+        if (pathMatches.length === 0 && PROMPT_ARTIFACT_STANDALONE_OPTIONAL_RECORDING_PATTERN.test(line)) {
+            if (listContinuation?.kind === "recording") {
+                for (const artifactIndex of listArtifactIndexes) {
+                    if (artifacts[artifactIndex]?.kind === "recording")
+                        artifacts[artifactIndex].required = false;
+                }
+                listContinuation = { ...listContinuation, required: false };
+            }
+            else {
+                pendingRecordingAvailability = true;
+            }
+            continue;
+        }
+        if (pathMatches.length === 0 && pendingRecordingAvailability && /\brecordings?\b/i.test(line) && hasPromptArtifactOutputIntent(line))
+            continue;
+        const pendingRecordingAvailabilityForLine = pathMatches.length > 0 && pendingRecordingAvailability;
+        pendingRecordingAvailability = false;
+        const pathlessLine = stripPromptArtifactListPrefix(line.replace(PROMPT_ARTIFACT_PATH_PATTERN, ""));
+        const remainder = pathlessLine.replace(/[\s"'`()\[\],;:.*!?>-]+/g, "").toLowerCase();
+        const listSyntax = pathlessLine
+            .replace(PROMPT_ARTIFACT_OPTIONAL_RECORDING_PATTERN, "")
+            .replace(PROMPT_ARTIFACT_EXPLICIT_OPTIONAL_PATTERN, "");
+        const isPathList = pathMatches.length > 0 && PROMPT_ARTIFACT_LIST_CONNECTOR_PATTERN.test(listSyntax);
+        const groupOptional = new Map();
+        const candidates = [];
+        let nextGroup = 0;
+        let previousGroup;
+        let previousKind;
+        let previousPathEnd = 0;
+        for (let matchIndex = 0; matchIndex < pathMatches.length; matchIndex += 1) {
+            const { end, path, start } = pathMatches[matchIndex];
+            const localContext = stripPromptArtifactListPrefix(line.slice(previousPathEnd, start));
+            const intentContext = matchIndex === 0 && (isPathList || !remainder || ["file", "output", "path"].includes(remainder))
+                ? `${lines[lineIndex - 1] ?? ""}\n${localContext}`
+                : localContext;
+            const kind = getPromptArtifactKind(path);
+            const directIntent = hasPromptArtifactOutputIntent(intentContext);
+            const sameLineContinuation = kind === previousKind && previousGroup !== undefined && PROMPT_ARTIFACT_LIST_CONNECTOR_PATTERN.test(localContext);
+            const priorLineContinuation = matchIndex === 0 && isPathList && kind === listContinuation?.kind && PROMPT_ARTIFACT_LIST_CONNECTOR_PATTERN.test(localContext);
+            let group;
+            if (directIntent) {
+                group = nextGroup++;
+                groupOptional.set(group, pendingRecordingAvailabilityForLine || PROMPT_ARTIFACT_OPTIONAL_RECORDING_PATTERN.test(getPromptArtifactIntentClause(intentContext)));
+            }
+            else if (sameLineContinuation) {
+                group = previousGroup;
+            }
+            else if (priorLineContinuation) {
+                group = nextGroup++;
+                groupOptional.set(group, listContinuation?.required === false);
+            }
+            const referenceReading = directIntent && PROMPT_ARTIFACT_REFERENCE_INTENT_PATTERN.test(getPromptArtifactIntentClause(intentContext));
+            const trailingContext = getPromptArtifactTrailingClause(line.slice(end, pathMatches[matchIndex + 1]?.start ?? line.length));
+            const explicitlyOptional = directIntent && (PROMPT_ARTIFACT_EXPLICIT_OPTIONAL_PATTERN.test(getPromptArtifactIntentClause(intentContext))
+                || PROMPT_ARTIFACT_EXPLICIT_OPTIONAL_PATTERN.test(trailingContext));
+            if (!kind || group === undefined || referenceReading || explicitlyOptional || isLikelyInboundPromptArtifact(path)) {
+                previousGroup = undefined;
+                previousKind = undefined;
+                previousPathEnd = end;
                 continue;
-            seen.add(key);
-            artifacts.push({
-                kind,
-                path,
-                required: kind === "screenshot" || !/\b(?:if|when)\s+(?:recording\s+)?(?:is\s+)?available\b/i.test(line),
-            });
+            }
+            candidates.push({ continuedFromPriorLine: priorLineContinuation && !directIntent, group, kind, matchIndex, path });
+            previousGroup = group;
+            previousKind = kind;
+            previousPathEnd = end;
+        }
+        for (const candidate of candidates) {
+            const match = pathMatches[candidate.matchIndex];
+            const nextStart = pathMatches[candidate.matchIndex + 1]?.start ?? line.length;
+            if (PROMPT_ARTIFACT_OPTIONAL_RECORDING_PATTERN.test(getPromptArtifactTrailingClause(line.slice(match.end, nextStart)))) {
+                groupOptional.set(candidate.group, true);
+            }
+        }
+        const lineArtifactIndexes = [];
+        for (const candidate of candidates) {
+            const required = candidate.kind === "screenshot" || groupOptional.get(candidate.group) !== true;
+            const key = `${candidate.kind}:${candidate.path}`;
+            let artifactIndex = seen.get(key);
+            if (artifactIndex === undefined) {
+                artifactIndex = artifacts.length;
+                seen.set(key, artifactIndex);
+                artifacts.push({ kind: candidate.kind, path: candidate.path, required });
+            }
+            else if (required) {
+                artifacts[artifactIndex].required = true;
+            }
+            lineArtifactIndexes.push(artifactIndex);
+        }
+        const lastCandidate = candidates.at(-1);
+        if (isPathList && lastCandidate?.matchIndex === pathMatches.length - 1) {
+            const lastArtifact = artifacts[lineArtifactIndexes.at(-1)];
+            listContinuation = { kind: lastArtifact.kind, required: lastArtifact.required };
+            if (candidates[0]?.continuedFromPriorLine) {
+                for (const artifactIndex of lineArtifactIndexes)
+                    listArtifactIndexes.push(artifactIndex);
+            }
+            else {
+                listArtifactIndexes = lineArtifactIndexes;
+            }
+        }
+        else {
+            listArtifactIndexes = [];
+            listContinuation = undefined;
         }
     }
     return artifacts;