@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.100

package/dist/tools/file-tools.js

@@ -1,13 +1,42 @@
+/**
+ * file-tools - Pugi CLI file/bash/glob/grep tool surface.
+ *
+ * Workspace-binding contract (CEO red-alert follow-up):
+ *
+ *  Every tool dispatch path threads `ctx.root` from the operator's
+ *  `process.cwd()` through `EngineTask.workspaceRoot` ->
+ *  `native-pugi.run()` -> `toolCtx.root` -> here. Tools call
+ *  `resolveWorkspacePath(ctx.root, path)` for every on-disk operation
+ *  so a dispatched specialist (e.g. Hiroshi writing tic-tac-toe HTML)
+ *  produces files in the OPERATOR'S cwd, never in a server-side temp
+ *  space. The path-security gate refuses traversal (`../etc/passwd`,
+ *  URL-encoded variants, symlink escapes at the target).
+ *
+ *  Wiring chain:
+ *    1. runtime/cli.ts:   workspaceRoot = process.cwd()
+ *    2. EngineTask.workspaceRoot threads through to native-pugi.run().
+ *    3. native-pugi:      const root = task.workspaceRoot
+ *    4. tool-bridge:      passes ctx.root to file-tools / bash.
+ *    5. file-tools:       resolveWorkspacePath(ctx.root, path).
+ *
+ *  The contract is locked by `test/tools-write-to-workspace.spec.ts`
+ *  (6 cases covering relative + nested + absolute paths + traversal
+ *  refusal). If any layer of the chain regressed silently, dispatched
+ *  files would land in `/tmp` instead of the operator's repo, which
+ *  is the same failure surface as the menu-mode anti-pattern the
+ *  sibling commits close.
+ */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, relative } from 'node:path';
 import { globSync } from 'node:fs';
 import { decidePermission } from '../core/permission.js';
-import { createReadRecord, hashContent } from '../core/file-cache.js';
+import { StaleReadError, createReadRecord, hashContent, } from '../core/file-cache.js';
 import { resolveWorkspacePath } from '../core/path-security.js';
+import { scanForInjection, summarizeFindings } from '../core/security/injection-scanner.js';
 import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
 /**
- * α6.9 WriteGate marker — thrown by `gateOnCancellation` when the
+ * WriteGate marker — thrown by `gateOnCancellation` when the
  * caller supplied a cancellation token that has already aborted. The
  * tool dispatch loop in `tool-bridge.ts` recognises the name and folds
  * the throw into a `status: 'aborted'` tool result rather than a hard
@@ -19,8 +48,13 @@ export class OperatorAbortedError extends Error {
         this.name = 'OperatorAbortedError';
     }
 }
+// Re-export StaleReadError so tool-bridge / test consumers can import
+// the typed error from a single file-tools surface alongside
+// OperatorAbortedError. Same shape as the existing OperatorAbortedError
+// re-surface pattern.
+export { StaleReadError } from '../core/file-cache.js';
 /**
- * α6.9 WriteGate: refuse the tool dispatch when the active
+ * WriteGate: refuse the tool dispatch when the active
  * cancellation token has aborted. Idempotent (the token's `isAborted`
  * is a getter, no side effects). Returns void on the happy path so the
  * tool can proceed; throws `OperatorAbortedError` when cancelled.
@@ -71,7 +105,7 @@ function permissionGatedResolve(ctx, inputPath, action, toolName) {
 }
 export function readTool(ctx, path) {
     const toolCallId = recordToolCall(ctx.session, 'read', path);
-    // α6.9 WriteGate: fail fast on operator cancel BEFORE permission
+    // WriteGate: fail fast on operator cancel BEFORE permission
     // decision so a half-second post-cancel race never lands the read.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
         const reason = 'operator_aborted: read refused';
@@ -100,7 +134,7 @@ export function readTool(ctx, path) {
 }
 export function writeTool(ctx, path, content) {
     const toolCallId = recordToolCall(ctx.session, 'write', path);
-    // α6.9 WriteGate: refuse the write when the operator has cancelled
+    // WriteGate: refuse the write when the operator has cancelled
     // the dispatch. The audit log captures the cancellation reason so a
     // post-mortem can distinguish operator_aborted from settings-deny.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -124,10 +158,45 @@ export function writeTool(ctx, path, content) {
         throw error;
     }
     const existed = existsSync(resolved);
-    const before = existed ? readFileSync(resolved, 'utf8') : undefined;
+    // stale-read gate for writeTool's update-existing path. The
+    // model uses writeTool for two distinct intents:
+    //
+    //  - create-new: path does not exist on disk. There is no prior
+    //    read to validate against; skip the gate. This is the
+    //    intentional escape hatch the leak spec also calls out.
+    //  - overwrite-existing: path exists. Without the gate the model
+    //    could blind-clobber an externally-modified file, losing the
+    //    concurrent change silently. Force the model to re-read first.
+    //
+    // We deliberately apply the SAME stale-validation primitive editTool
+    // uses so the two write surfaces stay symmetric and a future fix to
+    // either one cannot accidentally weaken the other.
+    let before;
+    if (existed) {
+        before = readFileSync(resolved, 'utf8');
+        const currentStat = statSync(resolved);
+        const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+        if (validation.stale) {
+            const reason = `stale_read: write ${path} refused — ${validation.detail}`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            throw new StaleReadError(path, validation.reason, validation.detail);
+        }
+    }
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmp, resolved);
+    // Injection scan (ported an external utility,
+    // Apache-2.0). Scan the BODY (never the path — path security is
+    // owned by `path-security.ts`). Findings are SURFACED as an extra
+    // line on the session tool-result, never block the write. Hard-
+    // block requires a separate CEO-signed PR. Failure here must NOT
+    // throw: a buggy scanner cannot rugpull the write that already
+    // landed on disk above.
+    surfaceInjectionWarning(ctx, toolCallId, 'write', path, content);
+    // Refresh the cache with the post-write content so the model can
+    // chain a follow-up read+edit on the same file without an extra
+    // round-trip. Same pattern editTool uses below.
+    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
     recordFileMutation(ctx.session, {
         toolCallId,
         path,
@@ -137,9 +206,39 @@ export function writeTool(ctx, path, content) {
     });
     recordToolResult(ctx.session, toolCallId, 'success', `${existed ? 'Updated' : 'Created'} ${path}`);
 }
+/**
+ * Surface an injection-scan warning on a file write/edit BODY. The
+ * scan never blocks — it folds findings into the session as a
+ * `tool_result` with status `warn` so an operator (or SOC pipeline
+ * tailing `<workspace>/.pugi/events.jsonl`) sees the signal without a
+ * mid-dispatch rollback.
+ *
+ * Wrapped in try/catch so a malformed scanner never crashes the tool
+ * loop — the write itself has already landed on disk by the time we
+ * call this.
+ */
+function surfaceInjectionWarning(ctx, triggeringToolCallId, tool, path, body) {
+    try {
+        const findings = scanForInjection(body);
+        if (findings.length === 0)
+            return;
+        const summary = summarizeFindings(findings);
+        const warnCallId = recordToolCall(ctx.session, 'injection_warning', path);
+        const message = `injection_warning: ${tool} ${path} — ${summary.total} pattern(s) ` +
+            `(score=${summary.score}, kinds=${summary.kinds.join('|')}). ` +
+            `Triggering call: ${triggeringToolCallId}. ` +
+            `Detector: external-injection-patterns. Write was NOT blocked.`;
+        recordToolResult(ctx.session, warnCallId, 'success', message);
+    }
+    catch {
+        // Scanner failure must NEVER throw — the write has already
+        // landed and the tool loop has to continue. Silent no-op
+        // mirrors the audit-trail contract.
+    }
+}
 export function editTool(ctx, path, oldString, newString) {
     const toolCallId = recordToolCall(ctx.session, 'edit', path);
-    // α6.9 WriteGate: refuse the edit when the operator has cancelled
+    // WriteGate: refuse the edit when the operator has cancelled
     // the dispatch. Edits are higher-risk than reads — surface the abort
     // BEFORE we even consult permissions so a cancel-during-tool-loop
     // never partially mutates the workspace.
@@ -154,10 +253,6 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw new Error(reason);
     }
-    const readRecord = ctx.readCache.get(ctx.root, path);
-    if (!readRecord) {
-        throw new Error(`Cannot edit ${path}: file must be read first`);
-    }
     let resolved;
     try {
         resolved = permissionGatedResolve(ctx, path, 'edit', 'edit');
@@ -167,20 +262,42 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw error;
     }
+    // stale-read gate. Validate the model's read-time view of
+    // the file against the on-disk state BEFORE applying the mutation.
+    // We read disk content once and feed it to the validator so a single
+    // syscall covers both the gate decision AND the oldString/newString
+    // replacement below.
     const before = readFileSync(resolved, 'utf8');
-    const currentHash = hashContent(before);
-    if (currentHash !== readRecord.sha256) {
-        throw new Error(`Cannot edit ${path}: file changed since last read`);
+    const currentStat = statSync(resolved);
+    const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+    if (validation.stale) {
+        const reason = `stale_read: edit ${path} refused — ${validation.detail}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new StaleReadError(path, validation.reason, validation.detail);
     }
+    const currentHash = hashContent(before);
     const matches = before.split(oldString).length - 1;
-    if (matches === 0)
-        throw new Error(`Cannot edit ${path}: oldString not found`);
-    if (matches > 1)
-        throw new Error(`Cannot edit ${path}: oldString is not unique`);
+    if (matches === 0) {
+        const reason = `Cannot edit ${path}: oldString not found`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    if (matches > 1) {
+        const reason = `Cannot edit ${path}: oldString is not unique`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
     const after = before.replace(oldString, newString);
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, after, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmp, resolved);
+    // Injection scan (ported an external utility,
+    // Apache-2.0). We scan the NEW SUBSTRING the model is inserting,
+    // not the full post-edit file — the rest of the file is operator-
+    // owned content that pre-dates this dispatch. False-positive on
+    // legitimate prose that mentions banned phrases is the worst
+    // outcome and the warn-only contract bounds the cost.
+    surfaceInjectionWarning(ctx, toolCallId, 'edit', path, newString);
     ctx.readCache.set(createReadRecord(ctx.root, path, after, 'read_tool'));
     recordFileMutation(ctx.session, {
         toolCallId,
@@ -193,7 +310,7 @@ export function editTool(ctx, path, oldString, newString) {
 }
 export function globTool(ctx, pattern) {
     const toolCallId = recordToolCall(ctx.session, 'glob', pattern);
-    // α6.9 WriteGate: cancel-aware short-circuit. Glob is read-only but
+    // WriteGate: cancel-aware short-circuit. Glob is read-only but
     // can be expensive on large trees; respecting the abort here keeps
     // the tool loop responsive when the operator hits Ctrl+C mid-scan.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -203,11 +320,11 @@ export function globTool(ctx, pattern) {
     }
     // Pugi globs are workspace-scoped. Reject any pattern that could enumerate
     // outside the workspace:
-    //   1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
-    //      regardless of `cwd`, so they fan out outside the repo.
-    //   2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
-    //      A substring check would over-reject legitimate names like
-    //      `src/v1..v2/*` so we split on `/` instead.
+    //  1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
+    //     regardless of `cwd`, so they fan out outside the repo.
+    //  2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
+    //     A substring check would over-reject legitimate names like
+    //     `src/v1..v2/*` so we split on `/` instead.
     if (isAbsolute(pattern)) {
         const reason = `Absolute glob patterns are not allowed: ${pattern}`;
         recordToolResult(ctx.session, toolCallId, 'error', reason);
@@ -230,7 +347,7 @@ export function globTool(ctx, pattern) {
 }
 export function grepTool(ctx, query) {
     const toolCallId = recordToolCall(ctx.session, 'grep', query);
-    // α6.9 WriteGate: refuse before scanning. Grep walks the whole
+    // WriteGate: refuse before scanning. Grep walks the whole
     // workspace and can take seconds on a large repo; check abort first
     // so a cancel mid-scan returns immediately rather than after the
     // full walk completes.
@@ -244,7 +361,7 @@ export function grepTool(ctx, query) {
     for (const path of files) {
         if (matches.length >= 200)
             break;
-        // α6.9 WriteGate: poll abort inside the file loop so a cancel
+        // WriteGate: poll abort inside the file loop so a cancel
         // arriving mid-scan terminates early. The per-file branch keeps
         // the responsiveness bounded by the slowest single-file read.
         if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -289,18 +406,18 @@ export function grepTool(ctx, query) {
 }
 /**
  * Workspace-scoped bash tool. Sized for the M1 engine adapter:
- *   - Runs through `/bin/sh -c <command>` so the model can use pipes,
- *     redirection, and shell builtins (`ls | wc -l`, `git status`).
- *   - `cwd` is pinned to the workspace root so a stray `cd /` cannot
- *     leak commands outside the repo (the child process inherits root
- *     filesystem visibility — destructive patterns are blocked by
- *     `decidePermission`, not by chroot).
- *   - Output capped at 64KB combined stdout/stderr to keep the
- *     transcript bounded; the model gets the head + a `(...truncated)`
- *     marker if the cap fires.
- *   - 30s wall-clock timeout. The engine loop's per-tool error path
- *     surfaces the timeout to the model so it can retry with a narrower
- *     command or give up.
+ *  - Runs through `/bin/sh -c <command>` so the model can use pipes,
+ *    redirection, and shell builtins (`ls | wc -l`, `git status`).
+ *  - `cwd` is pinned to the workspace root so a stray `cd /` cannot
+ *    leak commands outside the repo (the child process inherits root
+ *    filesystem visibility — destructive patterns are blocked by
+ *    `decidePermission`, not by chroot).
+ *  - Output capped at 64KB combined stdout/stderr to keep the
+ *    transcript bounded; the model gets the head + a `(...truncated)`
+ *    marker if the cap fires.
+ *  - 30s wall-clock timeout. The engine loop's per-tool error path
+ *    surfaces the timeout to the model so it can retry with a narrower
+ *    command or give up.
  *
  * Permission gating: `kind: 'bash'`. The CLI's permission module already
  * hard-denies the destructive-patterns list (rm -rf /, DROP DATABASE,
@@ -311,7 +428,7 @@ export const BASH_OUTPUT_CAP = 64 * 1024;
 export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 // Child-process stdio buffer — large enough that the model-facing
 // truncation cap (`BASH_OUTPUT_CAP`) is always the gate, never the
-// child's internal buffer. Code Reviewer P2 retro 2026-05-23 flagged
+// child's internal buffer. Code Reviewer P2 retro flagged
 // `BASH_OUTPUT_CAP * 2` as too tight: real builds (`pnpm build`,
 // `tsc --noEmit`) routinely exceed 128 KB combined and the model
 // then saw a fatal `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` instead of a
@@ -319,7 +436,7 @@ export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 export const BASH_CHILD_MAXBUFFER = 10 * 1024 * 1024;
 export function bashTool(ctx, command, options = {}) {
     const toolCallId = recordToolCall(ctx.session, 'bash', command);
-    // α6.9 WriteGate: bash is the highest-risk tool surface. Refuse
+    // WriteGate: bash is the highest-risk tool surface. Refuse
     // before the destructive-pattern classifier even runs so a
     // cancelled dispatch never spawns a child process. Note: this is
     // pre-spawn cancellation only; once the /bin/sh -c process is
@@ -343,7 +460,7 @@ export function bashTool(ctx, command, options = {}) {
     //
     // Env sanitisation strategy: build the child env from an explicit
     // allow-list rather than inheriting `process.env` and trying to
-    // strip secrets after the fact. Code Reviewer P1 2026-05-23 flagged
+    // strip secrets after the fact. Code Reviewer P1 flagged
     // that the deny-list approach missed ANTHROPIC_API_KEY / GH_TOKEN
     // / AWS_SECRET_ACCESS_KEY / DATABASE_URL / arbitrary *_TOKEN /
     // *_SECRET / *_KEY variables — every CI agent rotation would risk
@@ -372,7 +489,7 @@ export function bashTool(ctx, command, options = {}) {
     }
     const timeoutMs = options.timeoutMs ?? BASH_DEFAULT_TIMEOUT_MS;
     // `spawnSync` (vs `execFileSync`) captures stdout AND stderr on
-    // BOTH success and failure paths. Code Reviewer P1 2026-05-23:
+    // BOTH success and failure paths. Code Reviewer P1:
     // `execFileSync` returns only stdout on exit 0, silently dropping
     // stderr output from `tsc`, `eslint`, `pytest`, etc. — the model
     // would see `(no output)` for successful runs that emitted real
@@ -381,7 +498,7 @@ export function bashTool(ctx, command, options = {}) {
     // maxBuffer is generous (10 MB) so the child process is never the
     // truncation gate — the post-hoc `.slice(0, BASH_OUTPUT_CAP)` below
     // is the single source of truth for what the model sees. Code
-    // Reviewer P2 retro 2026-05-23: the previous `BASH_OUTPUT_CAP * 2`
+    // Reviewer P2 retro: the previous `BASH_OUTPUT_CAP * 2`
     // (128 KB) would hard-throw `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`
     // on noisy commands (`pnpm build`, `tsc --noEmit` on the whole
     // monorepo) instead of returning the truncated head.

package/dist/tools/http-request.js

@@ -0,0 +1,336 @@
+/**
+ * http_request - Phase 1 CRUD-smoke primitive (PUGI Phase 1).
+ *
+ * Generic HTTP request tool the model uses to verify a freshly-spun
+ * service end-to-end. Distinct from `web_fetch`:
+ *   - `web_fetch` is an opt-in marketing-grade content fetch (always
+ *     GET, response folded to Markdown, sentinel wrap, SSRF guard
+ *     blocks loopback / RFC1918).
+ *   - `http_request` is a *development-evidence* primitive: any verb,
+ *     any localhost URL, JSON-aware body+response. The default
+ *     allow-list permits localhost / 127.0.0.1 / ::1 so the model can
+ *     drive a CRUD smoke against a server it just started via
+ *     `server_start`; non-loopback hosts require an explicit
+ *     `allowExternal` opt-in.
+ *
+ * Body is serialised to JSON when a plain object is supplied. Headers
+ * are merged on top of a small default set (Accept: application/json,
+ * Content-Type when body is JSON). Response body is capped at 64 KB to
+ * keep the envelope sized; when the response content-type matches
+ * `application/json` the dispatcher attempts a parse and surfaces
+ * `json` alongside `body`.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { isIP } from 'node:net';
+export const HTTP_REQUEST_INVALID_ARGS = 'HTTP_REQUEST_INVALID_ARGS';
+export const HTTP_REQUEST_BODY_CAP_BYTES = 64 * 1024;
+export const HTTP_REQUEST_DEFAULT_TIMEOUT_MS = 10_000;
+export const HTTP_REQUEST_MAX_TIMEOUT_MS = 60_000;
+const ALLOWED_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+/**
+ * Validate raw arguments. Returns the typed payload on success or a
+ * sentinel string on failure (sleep/brief convention).
+ */
+export function parseHttpRequestArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${HTTP_REQUEST_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const method = obj['method'];
+    const url = obj['url'];
+    if (typeof method !== 'string' || !ALLOWED_METHODS.has(method.toUpperCase())) {
+        return `${HTTP_REQUEST_INVALID_ARGS}: method must be one of ${Array.from(ALLOWED_METHODS).join(', ')}`;
+    }
+    if (typeof url !== 'string' || url.trim() === '') {
+        return `${HTTP_REQUEST_INVALID_ARGS}: url must be a non-empty string`;
+    }
+    const body = obj['body'];
+    if (body !== undefined && body !== null) {
+        if (typeof body !== 'string' &&
+            !(typeof body === 'object')) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: body must be a string or a JSON object/array`;
+        }
+    }
+    const headers = obj['headers'];
+    if (headers !== undefined) {
+        if (typeof headers !== 'object' || headers === null || Array.isArray(headers)) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: headers must be a JSON object of string values`;
+        }
+        for (const [k, v] of Object.entries(headers)) {
+            if (typeof v !== 'string') {
+                return `${HTTP_REQUEST_INVALID_ARGS}: headers["${k}"] must be a string`;
+            }
+        }
+    }
+    const timeoutMs = obj['timeoutMs'];
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return `${HTTP_REQUEST_INVALID_ARGS}: timeoutMs must be a positive number when provided`;
+        }
+    }
+    const allowExternal = obj['allowExternal'];
+    if (allowExternal !== undefined && typeof allowExternal !== 'boolean') {
+        return `${HTTP_REQUEST_INVALID_ARGS}: allowExternal must be a boolean when provided`;
+    }
+    const result = {
+        method: method.toUpperCase(),
+        url,
+        ...(body !== undefined && body !== null
+            ? { body: body }
+            : {}),
+        ...(headers !== undefined ? { headers: headers } : {}),
+        ...(typeof timeoutMs === 'number' ? { timeoutMs } : {}),
+        ...(typeof allowExternal === 'boolean' ? { allowExternal } : {}),
+    };
+    return result;
+}
+function clampTimeout(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return HTTP_REQUEST_DEFAULT_TIMEOUT_MS;
+    }
+    return Math.min(value, HTTP_REQUEST_MAX_TIMEOUT_MS);
+}
+/**
+ * Decide whether the target host counts as loopback. Accept the
+ * familiar shorthand (`localhost`, `127.0.0.1`, `::1`) plus the
+ * full 127.0.0.0/8 IPv4 range so a server bound to e.g. `127.0.0.5`
+ * still passes the gate.
+ */
+function isLoopbackHost(host) {
+    const lower = host.toLowerCase();
+    if (lower === 'localhost' ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower === '[::1]' ||
+        // /triple-review P1 (Claude reviewer): IPv4-mapped
+        // IPv6 (`::ffff:127.0.0.1`) reaches loopback at the OS level.
+        // Recognize so a model that emits the IPv6 form is gated as
+        // loopback (rather than blocked as external — safer to allow
+        // explicitly recognised loopback and reject everything else).
+        lower === '::ffff:127.0.0.1' ||
+        lower.startsWith('::ffff:127.')) {
+        return true;
+    }
+    if (isIP(lower) === 4 && lower.startsWith('127.')) {
+        return true;
+    }
+    // /triple-review P1: `0.0.0.0` resolves к localhost for outbound on
+    // Linux and is reachable from inside the host. Treat as loopback so
+    // a server bound к `0.0.0.0` is callable from the dispatcher без
+    // requiring `allowExternal`. The risk surface is identical к
+    // `127.0.0.0/8` — anything reachable via `0.0.0.0` is also reachable
+    // via `127.0.0.1` on the same host.
+    if (lower === '0.0.0.0') {
+        return true;
+    }
+    return false;
+}
+function headersToObject(h) {
+    const out = {};
+    h.forEach((value, key) => {
+        out[key.toLowerCase()] = value;
+    });
+    return out;
+}
+/**
+ * Dispatch entry. Pure async - no shell, no filesystem. Loopback URLs
+ * always pass; external URLs require `allowExternal: true` so the
+ * default posture stays private.
+ */
+export async function dispatchHttpRequest(ctx, raw) {
+    const parsed = parseHttpRequestArgs(raw);
+    if (typeof parsed === 'string')
+        return parsed;
+    const args = parsed;
+    const now = ctx.now ?? (() => Date.now());
+    const fetchImpl = ctx.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: 'no_fetch_available',
+        };
+        return JSON.stringify(result);
+    }
+    // URL parse + loopback gate.
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(args.url);
+    }
+    catch (error) {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `invalid_url: ${error.message}`,
+        };
+        return JSON.stringify(result);
+    }
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `unsupported_protocol: ${parsedUrl.protocol}`,
+        };
+        return JSON.stringify(result);
+    }
+    const host = parsedUrl.hostname;
+    const loopback = isLoopbackHost(host);
+    if (!loopback && args.allowExternal !== true) {
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: 0,
+            error: `external_host_blocked: ${host} (set allowExternal: true to permit)`,
+        };
+        return JSON.stringify(result);
+    }
+    // Header + body normalisation. The default Accept header pushes
+    // servers that content-negotiate toward JSON so the response parse
+    // hits more often.
+    const defaultHeaders = {
+        accept: 'application/json,text/plain;q=0.9,*/*;q=0.5',
+    };
+    const merged = { ...defaultHeaders };
+    if (args.headers) {
+        for (const [k, v] of Object.entries(args.headers)) {
+            merged[k.toLowerCase()] = v;
+        }
+    }
+    let serialisedBody;
+    if (args.body !== undefined && args.body !== null) {
+        if (typeof args.body === 'string') {
+            serialisedBody = args.body;
+        }
+        else {
+            try {
+                serialisedBody = JSON.stringify(args.body);
+            }
+            catch (error) {
+                const result = {
+                    ok: false,
+                    status: 0,
+                    headers: {},
+                    body: '',
+                    durationMs: 0,
+                    error: `body_serialise_failed: ${error.message}`,
+                };
+                return JSON.stringify(result);
+            }
+            if (!('content-type' in merged)) {
+                merged['content-type'] = 'application/json';
+            }
+        }
+    }
+    const timeoutMs = clampTimeout(args.timeoutMs);
+    const start = now();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const init = {
+            method: args.method,
+            headers: merged,
+            signal: ac.signal,
+            // /triple-review P1 (Claude reviewer): default `fetch`
+            // follows redirects to ANY target. A loopback service can return
+            // 30x with Location pointing к cloud metadata IPs (169.254.169.254,
+            // 100.64/10 ranges) or arbitrary external hosts, and `fetch` would
+            // chase the redirect and surface the body. SSRF bypass class.
+            // `redirect: 'manual'` stops the chase; the dispatcher returns the
+            // 30x status + Location header to the model so it can decide
+            // whether the redirect target is acceptable.
+            redirect: 'manual',
+            ...(serialisedBody !== undefined ? { body: serialisedBody } : {}),
+        };
+        const res = await fetchImpl(args.url, init);
+        const text = await res.text();
+        const truncated = text.length > HTTP_REQUEST_BODY_CAP_BYTES;
+        const body = truncated ? text.slice(0, HTTP_REQUEST_BODY_CAP_BYTES) : text;
+        const respHeaders = headersToObject(res.headers);
+        const contentType = respHeaders['content-type'] ?? '';
+        let json;
+        if (contentType.includes('application/json') && body.length > 0 && !truncated) {
+            try {
+                json = JSON.parse(body);
+            }
+            catch {
+                // Body claimed JSON but failed to parse - preserve raw text only.
+            }
+        }
+        const result = {
+            ok: res.status >= 200 && res.status < 300,
+            status: res.status,
+            headers: respHeaders,
+            body,
+            ...(json !== undefined ? { json } : {}),
+            durationMs: now() - start,
+            ...(truncated ? { truncated: true } : {}),
+        };
+        return JSON.stringify(result);
+    }
+    catch (error) {
+        const message = error.message;
+        const aborted = error.name === 'AbortError';
+        const result = {
+            ok: false,
+            status: 0,
+            headers: {},
+            body: '',
+            durationMs: now() - start,
+            error: aborted ? `timeout_after_${timeoutMs}ms` : `request_failed: ${message}`,
+        };
+        return JSON.stringify(result);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const httpRequestJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['method', 'url'],
+    properties: {
+        method: {
+            type: 'string',
+            enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+            description: 'HTTP verb. Uppercase preferred but the dispatcher accepts any case.',
+        },
+        url: {
+            type: 'string',
+            description: 'Fully-qualified http(s) URL. Loopback hosts always pass; external hosts require allowExternal: true.',
+        },
+        body: {
+            description: 'Request body. A string is sent verbatim; an object/array is JSON-serialised and Content-Type defaults to application/json.',
+            oneOf: [
+                { type: 'string' },
+                { type: 'object', additionalProperties: true },
+                { type: 'array' },
+            ],
+        },
+        headers: {
+            type: 'object',
+            description: 'Custom request headers. Lower-cased keys overwrite the dispatcher defaults.',
+            additionalProperties: { type: 'string' },
+        },
+        timeoutMs: {
+            type: 'number',
+            description: `Per-request timeout in ms. Default ${HTTP_REQUEST_DEFAULT_TIMEOUT_MS}, max ${HTTP_REQUEST_MAX_TIMEOUT_MS}.`,
+        },
+        allowExternal: {
+            type: 'boolean',
+            description: 'Opt-in flag for non-loopback hosts. Defaults to false so the dispatcher refuses external URLs without explicit consent.',
+        },
+    },
+};
+//# sourceMappingURL=http-request.js.map