@rubytech/create-realagent 1.0.853 → 1.0.854

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.853",
+  "version": "1.0.854",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/lib/persistent-components/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The component names that the platform UI treats as long-lived editor
+ * surfaces (not single-shot prompts). They survive multiple `onSubmit`
+ * fires because the operator may auto-save mid-edit, and they are also
+ * the **server-side commitment surface** for Task 942: when the admin
+ * agent emits one of these names via `render-component`, the live
+ * stream-parser materialises the inline content as a sibling
+ * `:KnowledgeDocument` artefact so the row appears in the artefacts
+ * panel and survives session compaction.
+ *
+ * Single source of truth — the platform UI (`app/admin-types.ts`) and
+ * the admin MCP server (`plugins/admin/mcp/src/index.ts`) both import
+ * from this module. Any drift here is an account-isolation /
+ * persistence-doctrine bug; keep the constant in one place.
+ */
+export declare const PERSISTENT_COMPONENTS: Set<string>;
+/**
+ * Cheap, allocation-free guard for hot-path checks.
+ */
+export declare function isPersistentComponent(name: string | undefined | null): boolean;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/persistent-components/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,aAKhC,CAAC;AAEH;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAE9E"}

package/payload/platform/lib/persistent-components/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSISTENT_COMPONENTS = void 0;
+exports.isPersistentComponent = isPersistentComponent;
+/**
+ * The component names that the platform UI treats as long-lived editor
+ * surfaces (not single-shot prompts). They survive multiple `onSubmit`
+ * fires because the operator may auto-save mid-edit, and they are also
+ * the **server-side commitment surface** for Task 942: when the admin
+ * agent emits one of these names via `render-component`, the live
+ * stream-parser materialises the inline content as a sibling
+ * `:KnowledgeDocument` artefact so the row appears in the artefacts
+ * panel and survives session compaction.
+ *
+ * Single source of truth — the platform UI (`app/admin-types.ts`) and
+ * the admin MCP server (`plugins/admin/mcp/src/index.ts`) both import
+ * from this module. Any drift here is an account-isolation /
+ * persistence-doctrine bug; keep the constant in one place.
+ */
+exports.PERSISTENT_COMPONENTS = new Set([
+    'action-list',
+    'document-editor',
+    'rich-content-editor',
+    'grid-editor',
+]);
+/**
+ * Cheap, allocation-free guard for hot-path checks.
+ */
+function isPersistentComponent(name) {
+    return typeof name === 'string' && exports.PERSISTENT_COMPONENTS.has(name);
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/persistent-components/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAyBA,sDAEC;AA3BD;;;;;;;;;;;;;;GAcG;AACU,QAAA,qBAAqB,GAAG,IAAI,GAAG,CAAS;IACnD,aAAa;IACb,iBAAiB;IACjB,qBAAqB;IACrB,aAAa;CACd,CAAC,CAAC;AAEH;;GAEG;AACH,SAAgB,qBAAqB,CAAC,IAA+B;IACnE,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,6BAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrE,CAAC"}

package/payload/platform/lib/persistent-components/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * The component names that the platform UI treats as long-lived editor
+ * surfaces (not single-shot prompts). They survive multiple `onSubmit`
+ * fires because the operator may auto-save mid-edit, and they are also
+ * the **server-side commitment surface** for Task 942: when the admin
+ * agent emits one of these names via `render-component`, the live
+ * stream-parser materialises the inline content as a sibling
+ * `:KnowledgeDocument` artefact so the row appears in the artefacts
+ * panel and survives session compaction.
+ *
+ * Single source of truth — the platform UI (`app/admin-types.ts`) and
+ * the admin MCP server (`plugins/admin/mcp/src/index.ts`) both import
+ * from this module. Any drift here is an account-isolation /
+ * persistence-doctrine bug; keep the constant in one place.
+ */
+export const PERSISTENT_COMPONENTS = new Set<string>([
+  'action-list',
+  'document-editor',
+  'rich-content-editor',
+  'grid-editor',
+]);
+
+/**
+ * Cheap, allocation-free guard for hot-path checks.
+ */
+export function isPersistentComponent(name: string | undefined | null): boolean {
+  return typeof name === 'string' && PERSISTENT_COMPONENTS.has(name);
+}

package/payload/platform/lib/persistent-components/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/admin/PLUGIN.md

@@ -71,5 +71,5 @@ Tools are available via the `admin` MCP server.
 ## Hooks
 
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
-- `hooks/playwright-file-guard.sh` — intercepts file:// URLs with actionable guidance
+- `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.

package/payload/platform/plugins/admin/hooks/__tests__/playwright-file-guard.test.sh

@@ -0,0 +1,278 @@
+#!/usr/bin/env bash
+# Regression test for playwright-file-guard.sh (Task 944).
+#
+# Covers:
+#   1. file:// URL → hook emits hookSpecificOutput.updatedInput.url JSON,
+#      starts a backgrounded python3 -m http.server on a free port rooted
+#      at the file's parent dir, writes /tmp/playwright-file-guard.<port>.pid,
+#      and the rewritten URL responds 200.
+#   2. https:// URL → silent passthrough, exit 0, no stdout JSON.
+#   3. Free-port under contention: hold 8080, run hook on file://, assert
+#      chosen port != 8080.
+#   4. Stale-PID cleanup mode: pre-create stale PID file pointing at a real
+#      http.server we control, run `cleanup`, assert process killed + file
+#      removed.
+#   5. Reused-PID guard: PID file points at non-http.server process,
+#      cleanup leaves the process alone.
+#   6. Fail-open on missing python3 (PATH override).
+#   7. Malformed stdin → exit 0 silent passthrough.
+#   8. Terminal stdin guard preserved.
+#   9. Hook source contains no copy of the old menu phrase.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/playwright-file-guard.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+# Track every PID we spawn so we can reap on EXIT.
+TRACKED_PIDS=()
+TMPFILES=()
+
+cleanup_test_state() {
+  for p in "${TRACKED_PIDS[@]:-}"; do
+    [[ -n "$p" ]] && kill -9 "$p" 2>/dev/null || true
+  done
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+  rm -f /tmp/playwright-file-guard.*.pid 2>/dev/null || true
+}
+trap cleanup_test_state EXIT
+
+PASS=0
+FAIL=0
+
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+# Sweep stale PID files BEFORE running tests so prior runs don't poison the
+# fixture. The hook's opportunistic cleanup also triggers on every call, but
+# a clean slate makes assertions deterministic.
+rm -f /tmp/playwright-file-guard.*.pid 2>/dev/null || true
+
+# ---- Test 1: file:// rewrite happy path -------------------------------------
+
+TEST_HTML=$(mktemp -t playwright-file-guard-XXXXXX).html
+echo "<html><body>hello</body></html>" > "$TEST_HTML"
+TMPFILES+=("$TEST_HTML")
+TEST_BASENAME=$(basename "$TEST_HTML")
+
+INPUT_JSON=$(printf '{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file://%s"}}' "$TEST_HTML")
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+
+printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 1: hook exited $RC on file:// rewrite (expected 0)"
+elif ! grep -q '"hookSpecificOutput"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout missing hookSpecificOutput JSON. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '"updatedInput"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout missing updatedInput field. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -qE '"url":\s*"http://127.0.0.1:[0-9]+/'"$TEST_BASENAME"'"' "$STDOUT_FILE"; then
+  fail "Test 1: stdout url not rewritten as expected. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=rewrite' "$STDERR_FILE"; then
+  fail "Test 1: stderr missing rewrite log line. Got: $(cat "$STDERR_FILE")"
+else
+  PORT=$(grep -oE 'http://127\.0\.0\.1:[0-9]+/' "$STDOUT_FILE" | head -1 | grep -oE ':[0-9]+/' | tr -d ':/')
+  PID_FILE="/tmp/playwright-file-guard.${PORT}.pid"
+  if [[ ! -f "$PID_FILE" ]]; then
+    fail "Test 1: PID file $PID_FILE not created"
+  else
+    SERVER_PID=$(cat "$PID_FILE")
+    TRACKED_PIDS+=("$SERVER_PID")
+    HTTP_BODY=$(curl -s --max-time 2 "http://127.0.0.1:${PORT}/${TEST_BASENAME}" 2>/dev/null || true)
+    if echo "$HTTP_BODY" | grep -q "hello"; then
+      pass "Test 1: file:// → rewrite + spawned server responds 200"
+    else
+      fail "Test 1: spawned server at port $PORT did not return file content. Body: $HTTP_BODY"
+    fi
+  fi
+fi
+
+# ---- Test 2: https:// passthrough -------------------------------------------
+
+INPUT_JSON='{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"https://example.com"}}'
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 2: hook exited $RC on https:// passthrough"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 2: stdout should be empty on passthrough. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=passthrough scheme=https' "$STDERR_FILE"; then
+  fail "Test 2: stderr missing passthrough log line. Got: $(cat "$STDERR_FILE")"
+else
+  pass "Test 2: https:// → silent passthrough"
+fi
+
+# ---- Test 3: free port under :8080 contention -------------------------------
+
+python3 -c "
+import socket, time, sys
+s = socket.socket()
+try:
+  s.bind(('127.0.0.1', 8080))
+  s.listen(1)
+  print('READY', flush=True)
+  time.sleep(15)
+except OSError as e:
+  print('SKIP', e, flush=True)
+  sys.exit(0)
+" >/tmp/playwright-file-guard-test-blocker.stdout 2>&1 &
+BLOCKER_PID=$!
+TRACKED_PIDS+=("$BLOCKER_PID")
+TMPFILES+=("/tmp/playwright-file-guard-test-blocker.stdout")
+
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  if grep -qE 'READY|SKIP' /tmp/playwright-file-guard-test-blocker.stdout 2>/dev/null; then break; fi
+  sleep 0.1
+done
+
+if grep -q SKIP /tmp/playwright-file-guard-test-blocker.stdout 2>/dev/null; then
+  echo "SKIP: Test 3 — port 8080 already held by another process; cannot run contention test"
+else
+  TEST_HTML2=$(mktemp -t playwright-file-guard-XXXXXX).html
+  echo "<html>2</html>" > "$TEST_HTML2"
+  TMPFILES+=("$TEST_HTML2")
+  INPUT_JSON=$(printf '{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file://%s"}}' "$TEST_HTML2")
+  STDOUT_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE")
+  printf '%s' "$INPUT_JSON" | bash "$HOOK" >"$STDOUT_FILE" 2>/dev/null
+  CHOSEN_PORT=$(grep -oE 'http://127\.0\.0\.1:[0-9]+/' "$STDOUT_FILE" | head -1 | grep -oE ':[0-9]+/' | tr -d ':/')
+  if [[ -z "$CHOSEN_PORT" ]]; then
+    fail "Test 3: hook did not produce a rewrite under contention. Stdout: $(cat "$STDOUT_FILE")"
+  elif [[ "$CHOSEN_PORT" == "8080" ]]; then
+    fail "Test 3: hook picked 8080 even though it was bound"
+  else
+    SERVER_PID=$(cat "/tmp/playwright-file-guard.${CHOSEN_PORT}.pid" 2>/dev/null || echo "")
+    [[ -n "$SERVER_PID" ]] && TRACKED_PIDS+=("$SERVER_PID")
+    pass "Test 3: free-port under :8080 contention picked $CHOSEN_PORT"
+  fi
+fi
+
+# ---- Test 4: stale-PID cleanup mode (explicit argv) -------------------------
+
+STALE_DIR=$(mktemp -d); TMPFILES+=("$STALE_DIR")
+( cd "$STALE_DIR" && exec python3 -u -m http.server 0 >/tmp/playwright-file-guard-stale.stdout 2>&1 ) &
+STALE_PID=$!
+TRACKED_PIDS+=("$STALE_PID")
+TMPFILES+=("/tmp/playwright-file-guard-stale.stdout")
+# Wait up to 2s for the http.server banner to flush.
+for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+  if grep -qE 'port [0-9]+' /tmp/playwright-file-guard-stale.stdout 2>/dev/null; then break; fi
+  sleep 0.1
+done
+STALE_PORT=$(grep -oE 'port [0-9]+' /tmp/playwright-file-guard-stale.stdout 2>/dev/null | head -1 | grep -oE '[0-9]+' || echo "")
+if [[ -z "$STALE_PORT" ]]; then
+  fail "Test 4 setup: could not extract port from python3 http.server"
+else
+  STALE_PID_FILE="/tmp/playwright-file-guard.${STALE_PORT}.pid"
+  echo "$STALE_PID" > "$STALE_PID_FILE"
+  TMPFILES+=("$STALE_PID_FILE")
+  touch -t "$(date -u -v-2H +%Y%m%d%H%M.%S 2>/dev/null || date -u -d '2 hours ago' +%Y%m%d%H%M.%S)" "$STALE_PID_FILE"
+
+  bash "$HOOK" cleanup >/dev/null 2>&1
+
+  # SIGTERM is asynchronous — wait up to 1s for the process to actually die.
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    if ! kill -0 "$STALE_PID" 2>/dev/null; then break; fi
+    sleep 0.1
+  done
+
+  if kill -0 "$STALE_PID" 2>/dev/null; then
+    fail "Test 4: stale PID $STALE_PID still alive after cleanup"
+    kill -9 "$STALE_PID" 2>/dev/null || true
+  elif [[ -f "$STALE_PID_FILE" ]]; then
+    fail "Test 4: stale PID file $STALE_PID_FILE not removed after cleanup"
+  else
+    pass "Test 4: stale-PID cleanup killed http.server + removed PID file"
+  fi
+fi
+
+# ---- Test 5: reused-PID guard ----------------------------------------------
+
+REUSED_PID_FILE="/tmp/playwright-file-guard.59999.pid"
+echo "$$" > "$REUSED_PID_FILE"
+TMPFILES+=("$REUSED_PID_FILE")
+touch -t "$(date -u -v-2H +%Y%m%d%H%M.%S 2>/dev/null || date -u -d '2 hours ago' +%Y%m%d%H%M.%S)" "$REUSED_PID_FILE"
+
+bash "$HOOK" cleanup >/dev/null 2>&1
+
+if ! kill -0 "$$" 2>/dev/null; then
+  fail "Test 5: reused-PID guard killed our own bash process — fatal"
+elif [[ -f "$REUSED_PID_FILE" ]]; then
+  fail "Test 5: reused-PID file $REUSED_PID_FILE not removed (hook should drop the stale ref)"
+else
+  pass "Test 5: reused-PID guard left process alive, dropped stale PID file"
+fi
+
+# ---- Test 6: missing python3 fails open ------------------------------------
+
+EMPTY_PATH_DIR=$(mktemp -d); TMPFILES+=("$EMPTY_PATH_DIR")
+ln -s "$(command -v bash)" "$EMPTY_PATH_DIR/bash"
+ln -s "$(command -v grep)" "$EMPTY_PATH_DIR/grep"
+ln -s "$(command -v cat)" "$EMPTY_PATH_DIR/cat"
+ln -s "$(command -v rm)" "$EMPTY_PATH_DIR/rm"
+ln -s "$(command -v mktemp)" "$EMPTY_PATH_DIR/mktemp"
+
+INPUT_JSON='{"hook_event_name":"PreToolUse","tool_name":"mcp__plugin_playwright_playwright__browser_navigate","tool_input":{"url":"file:///tmp/missing-python.html"}}'
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+PATH="$EMPTY_PATH_DIR" printf '%s' "$INPUT_JSON" | PATH="$EMPTY_PATH_DIR" bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 6: missing python3 should fail open (exit 0), got $RC"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 6: stdout should be empty on fail-open. Got: $(cat "$STDOUT_FILE")"
+elif ! grep -q '\[playwright-file-guard\] action=fail reason=python3-missing' "$STDERR_FILE"; then
+  fail "Test 6: stderr missing python3-missing log line. Got: $(cat "$STDERR_FILE")"
+else
+  pass "Test 6: missing python3 → fail open with diagnostic"
+fi
+
+# ---- Test 7: malformed stdin → silent passthrough ---------------------------
+
+STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
+printf '%s' 'not json at all { ' | bash "$HOOK" >"$STDOUT_FILE" 2>"$STDERR_FILE"
+RC=$?
+
+if [[ "$RC" -ne 0 ]]; then
+  fail "Test 7: malformed stdin should fail open (exit 0), got $RC"
+elif [[ -s "$STDOUT_FILE" ]]; then
+  fail "Test 7: stdout should be empty on malformed stdin"
+else
+  pass "Test 7: malformed stdin → silent passthrough"
+fi
+
+# ---- Test 8: terminal stdin guard preserved --------------------------------
+
+if ! grep -q '\[ -t 0 \]' "$HOOK"; then
+  fail "Test 8: terminal stdin guard ([ -t 0 ]) missing from hook"
+else
+  pass "Test 8: terminal stdin guard present"
+fi
+
+# ---- Test 9: zero-grep-hits for old menu copy in this hook ------------------
+
+# The pattern uses [l] to break self-match: this file's bytes contain "[l]ocal"
+# but the hook source contains "local" if the menu copy was reintroduced. The
+# extended-regex bracket class matches "local" without our query containing
+# the literal string we're forbidding.
+OLD_MENU_PATTERN='Start a [l]ocal HTTP server'
+if grep -qE "$OLD_MENU_PATTERN" "$HOOK"; then
+  fail "Test 9: hook still contains the old menu copy"
+else
+  pass "Test 9: hook does not contain the old menu copy"
+fi
+
+echo
+echo "──────── playwright-file-guard test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+[[ "$FAIL" -gt 0 ]] && exit 1
+exit 0

package/payload/platform/plugins/admin/hooks/playwright-file-guard.sh

@@ -1,30 +1,214 @@
 #!/usr/bin/env bash
-# PreToolUse hook — intercepts browser_navigate with file:// URLs.
+# PreToolUse hook — rewrites file:// browser_navigate calls to a backgrounded
+# loopback HTTP server, so Playwright never sees a file:// URL (which it
+# blocks behind a 2-minute MCP timeout).
 #
-# Scoped to mcp__plugin_playwright_playwright__browser_navigate via
-# the settings.json matcher. Blocks file:// attempts with actionable
-# guidance so the agent self-corrects on the first try instead of
-# retrying into Playwright's cryptic error + 2-minute MCP timeout.
+# Scoped to mcp__plugin_playwright_playwright__browser_navigate via the
+# settings.json matcher.
 #
-# Error philosophy: fail open. This is a guidance hook, not a security
-# boundary. If parsing fails, the tool proceeds normally and the agent
-# gets the standard Playwright error.
+# Modes:
+#   default (stdin = PreToolUse JSON):
+#     - Sweeps stale /tmp/playwright-file-guard.*.pid (>1h old) opportunistically.
+#     - If tool_input.url is file://, picks a free port, backgrounds
+#       `python3 -m http.server <port>` rooted at the file's parent dir,
+#       connect-verifies the server within 1s, writes PID to
+#       /tmp/playwright-file-guard.<port>.pid, and emits a JSON object on
+#       stdout setting hookSpecificOutput.updatedInput.url to
+#       http://127.0.0.1:<port>/<basename>.
+#     - Other URLs: passthrough log to stderr, exit 0, no stdout.
+#
+#   `cleanup` argv: only runs the stale-PID sweep; does not read stdin.
+#
+# Error philosophy: fail open. Any internal failure → exit 0 with a stderr
+# diagnostic, letting Playwright handle the original URL (the legacy
+# 2-minute timeout) rather than block on a parser bug.
+#
+# Observability: every action emits one stderr line of the shape
+#   [playwright-file-guard] action=<rewrite|passthrough|cleanup|fail> ...
+
+set -u
 
-if [ -t 0 ]; then
+MODE="${1:-rewrite}"
+
+# Terminal stdin guard. Cleanup mode never reads stdin.
+if [[ "$MODE" != "cleanup" ]] && [ -t 0 ]; then
   exit 0
 fi
-INPUT=$(cat)
-
-if echo "$INPUT" | grep -qiE '"url"\s*:\s*"file://'; then
-  cat >&2 << 'EOF'
-file:// URLs are blocked by Playwright. To view a local HTML file in the browser:
 
-1. Start a local HTTP server: python3 -m http.server 8080
-2. Navigate to http://localhost:8080/filename.html instead
+# Without python3 we cannot do anything useful. Drain stdin (so the upstream
+# tool dispatcher does not get SIGPIPE) and fail open.
+if ! command -v python3 >/dev/null 2>&1; then
+  if [[ "$MODE" != "cleanup" ]]; then
+    cat >/dev/null
+  fi
+  echo "[playwright-file-guard] action=fail reason=python3-missing" >&2
+  exit 0
+fi
 
-Do not retry with file:// — it will always fail.
-EOF
-  exit 2
+if [[ "$MODE" == "cleanup" ]]; then
+  INPUT=""
+else
+  INPUT=$(cat)
 fi
 
-exit 0
+MODE="$MODE" INPUT="$INPUT" python3 <<'PY' || exit 0
+import os, sys, json, glob, time, socket, subprocess
+from urllib.parse import unquote
+
+MODE = os.environ.get('MODE', 'rewrite')
+INPUT = os.environ.get('INPUT', '')
+NOW = time.time()
+STALE_THRESHOLD = 3600  # 1h
+PID_GLOB = '/tmp/playwright-file-guard.*.pid'
+
+def log(line):
+    print(line, file=sys.stderr, flush=True)
+
+def port_from_pidfile(path):
+    parts = os.path.basename(path).split('.')
+    return parts[1] if len(parts) >= 3 else 'unknown'
+
+def sweep_stale():
+    for pid_file in glob.glob(PID_GLOB):
+        try:
+            mtime = os.stat(pid_file).st_mtime
+        except OSError:
+            continue
+        if NOW - mtime < STALE_THRESHOLD:
+            continue
+        port = port_from_pidfile(pid_file)
+        try:
+            with open(pid_file) as f:
+                pid = int(f.read().strip())
+        except Exception:
+            try: os.remove(pid_file)
+            except OSError: pass
+            log(f'[playwright-file-guard] action=cleanup port={port} status=unparseable-pid')
+            continue
+        cmd = subprocess.run(
+            ['ps', '-p', str(pid), '-o', 'command='],
+            capture_output=True, text=True,
+        )
+        cmdline = cmd.stdout if cmd.returncode == 0 else ''
+        # macOS ps resolves /usr/local/bin/python3 → Python.app binary "Python";
+        # Linux/Pi ps shows "python3". Match either via case-insensitive
+        # `python` substring + the unambiguous `http.server` invocation.
+        cmdline_lower = cmdline.lower()
+        if 'python' in cmdline_lower and 'http.server' in cmdline_lower:
+            subprocess.run(['kill', str(pid)], capture_output=True)
+            log(f'[playwright-file-guard] action=cleanup port={port} pid={pid} status=killed')
+        else:
+            log(f'[playwright-file-guard] action=cleanup port={port} pid={pid} status=pid-reused-skip')
+        try: os.remove(pid_file)
+        except OSError: pass
+
+# Opportunistic sweep on every invocation — closes the gap that nothing
+# currently calls cleanup on a periodic schedule.
+sweep_stale()
+
+if MODE == 'cleanup':
+    sys.exit(0)
+
+try:
+    payload = json.loads(INPUT) if INPUT else {}
+except Exception:
+    sys.exit(0)
+
+tool_input = payload.get('tool_input') or {}
+url = tool_input.get('url')
+if not isinstance(url, str) or not url:
+    sys.exit(0)
+
+clean_url = url.split('#', 1)[0].split('?', 1)[0]
+
+if '://' not in clean_url:
+    log('[playwright-file-guard] action=passthrough scheme=none')
+    sys.exit(0)
+
+scheme, rest = clean_url.split('://', 1)
+scheme = scheme.lower()
+if scheme != 'file':
+    log(f'[playwright-file-guard] action=passthrough scheme={scheme}')
+    sys.exit(0)
+
+# file:///abs/path → /abs/path; file://host/path → /path (host ignored).
+if rest.startswith('/'):
+    file_path = rest
+elif '/' in rest:
+    file_path = '/' + rest.split('/', 1)[1]
+else:
+    file_path = '/'
+
+file_path = unquote(file_path)
+abs_path = os.path.abspath(file_path)
+
+if not os.path.isfile(abs_path):
+    log(f'[playwright-file-guard] action=fail reason=file-not-found path={abs_path}')
+    sys.exit(0)
+
+served_dir = os.path.dirname(abs_path)
+basename = os.path.basename(abs_path)
+
+try:
+    s = socket.socket()
+    s.bind(('127.0.0.1', 0))
+    port = s.getsockname()[1]
+    s.close()
+except Exception as e:
+    log(f'[playwright-file-guard] action=fail reason=port-pick-failed err={type(e).__name__}')
+    sys.exit(0)
+
+try:
+    proc = subprocess.Popen(
+        [sys.executable, '-m', 'http.server', str(port), '--bind', '127.0.0.1'],
+        cwd=served_dir,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+except Exception as e:
+    log(f'[playwright-file-guard] action=fail reason=spawn-failed err={type(e).__name__}')
+    sys.exit(0)
+
+pid_file = f'/tmp/playwright-file-guard.{port}.pid'
+try:
+    with open(pid_file, 'w') as f:
+        f.write(str(proc.pid))
+except Exception:
+    pass
+
+# Connect-verify within 1s closes the TOCTOU window between bind(0) and the
+# http.server actually accepting connections.
+deadline = time.time() + 1.0
+ready = False
+while time.time() < deadline:
+    try:
+        sock = socket.create_connection(('127.0.0.1', port), timeout=0.2)
+        sock.close()
+        ready = True
+        break
+    except OSError:
+        time.sleep(0.05)
+
+if not ready:
+    try: proc.kill()
+    except Exception: pass
+    try: os.remove(pid_file)
+    except OSError: pass
+    log(f'[playwright-file-guard] action=fail reason=server-not-ready port={port}')
+    sys.exit(0)
+
+new_url = f'http://127.0.0.1:{port}/{basename}'
+updated_input = dict(tool_input)
+updated_input['url'] = new_url
+
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'allow',
+        'permissionDecisionReason': 'file:// rewritten to local http.server',
+        'updatedInput': updated_input,
+    },
+}))
+log(f'[playwright-file-guard] action=rewrite original=file://{abs_path} served_dir={served_dir} port={port} pid={proc.pid}')
+PY