@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/tools/todo-write.js

@@ -0,0 +1,184 @@
+/**
+ * todo_write tool — Leak L16 (TodoWrite single-in-progress invariant).
+ *
+ * Mirrors Claude Code's `TodoWrite` tool 1:1 so a model trained on the
+ * upstream grammar speaks Pugi's variant verbatim. The tool dispatches
+ * a BATCH replace of the workspace todo board (not an incremental
+ * mutation — the model emits the FULL list every call). At most ONE
+ * todo may carry `status: 'in_progress'` at any time; violations
+ * reject with the `TODO_INVARIANT_VIOLATED` sentinel and the board on
+ * disk is left unchanged.
+ *
+ * Relationship to `task_*` (β1 T1/T6, tools/tasks.ts):
+ *   - `task_*` is GRANULAR (create/get/list/update one task at a
+ *     time) with an append-only JSONL journal scoped to the SESSION.
+ *   - `todo_write` is BATCH (snapshot the whole board) with an atomic
+ *     JSON snapshot scoped to the WORKSPACE.
+ *   They are complementary surfaces: agents that prefer the upstream
+ *   TodoWrite grammar use `todo_write`; agents that want a fine-grained
+ *   audit trail use `task_*`.
+ *
+ * Hard rules (enforced by Zod + dispatcher):
+ *   - `todos.length` ≤ 50 (board overload guard).
+ *   - Every item: id (≥1 char, ≤128), content (≥1 char), status enum.
+ *   - At most ONE item with `status === 'in_progress'`.
+ *   - All ids unique within the batch.
+ *
+ * Dispatch returns the persisted board as JSON; callers can read
+ * `todos: [...]` directly. Errors return the sentinel-prefixed message
+ * so the engine adapter can pattern-match.
+ */
+import { z } from 'zod';
+import { saveTodoBoard } from '../core/todos/state.js';
+/** Cap matches the `task_*` family's title cap for parity. */
+export const TODO_CONTENT_MAX = 2_000;
+/** id is opaque to us but must be slug-safe so file paths could embed it. */
+export const TODO_ID_MIN = 1;
+export const TODO_ID_MAX = 128;
+/** Hard cap on board size. Beyond this the operator should split work. */
+export const TODO_BATCH_MAX = 50;
+export const todoItemSchema = z
+    .strictObject({
+    id: z
+        .string()
+        .min(TODO_ID_MIN)
+        .max(TODO_ID_MAX)
+        .describe('Stable id for this todo. Opaque, ≤128 chars.'),
+    content: z
+        .string()
+        .min(1)
+        .max(TODO_CONTENT_MAX)
+        .describe('Imperative task description. E.g. "Add invariant check".'),
+    status: z
+        .enum(['pending', 'in_progress', 'completed'])
+        .describe('Lifecycle status. At most ONE in_progress per board.'),
+    activeForm: z
+        .string()
+        .min(1)
+        .max(TODO_CONTENT_MAX)
+        .optional()
+        .describe('Present-continuous form. E.g. "Adding invariant check".'),
+});
+export const todoWriteArgsSchema = z.strictObject({
+    todos: z
+        .array(todoItemSchema)
+        .max(TODO_BATCH_MAX)
+        .describe(`Full todo board (batch replace, not incremental). Max ${TODO_BATCH_MAX} items. ` +
+        `At most ONE item may carry status="in_progress".`),
+});
+/**
+ * JSON-Schema fragment surfaced to the model via the tool-bridge
+ * `parameters` field. Mirrors the Zod schema 1:1 — kept hand-written
+ * (same convention as ask_user_question) because the runtime engine
+ * wires OpenAI-compatible JSON Schema and we have not greenlit the
+ * zod-to-json-schema transitive dep. Keep both in lockstep.
+ */
+export const todoWriteJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['todos'],
+    properties: {
+        todos: {
+            type: 'array',
+            maxItems: TODO_BATCH_MAX,
+            description: `Full todo board (batch replace, not incremental). Max ${TODO_BATCH_MAX} items. ` +
+                `At most ONE item may carry status="in_progress".`,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'content', 'status'],
+                properties: {
+                    id: {
+                        type: 'string',
+                        minLength: TODO_ID_MIN,
+                        maxLength: TODO_ID_MAX,
+                        description: 'Stable id for this todo. Opaque, ≤128 chars.',
+                    },
+                    content: {
+                        type: 'string',
+                        minLength: 1,
+                        maxLength: TODO_CONTENT_MAX,
+                        description: 'Imperative task description.',
+                    },
+                    status: {
+                        type: 'string',
+                        enum: ['pending', 'in_progress', 'completed'],
+                        description: 'Lifecycle status. At most ONE in_progress per board.',
+                    },
+                    activeForm: {
+                        type: 'string',
+                        minLength: 1,
+                        maxLength: TODO_CONTENT_MAX,
+                        description: 'Present-continuous form.',
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * Sentinel prefix the dispatcher returns when Zod schema validation
+ * rejects the raw arguments. Distinct from `TODO_INVARIANT_VIOLATED`
+ * (>1 in_progress) and `TODO_DUPLICATE_ID` (collision within batch),
+ * which are emitted from `saveTodoBoard` AFTER schema parsing.
+ *
+ * Surfaced as a return string (not a throw) so the engine adapter sees
+ * a recoverable tool error and the model can self-correct its args,
+ * instead of the engine loop tearing down on an uncaught ZodError.
+ */
+export const TODO_INVALID_ARGS = 'INVALID_ARGS';
+/**
+ * Render a ZodError into a deterministic `INVALID_ARGS: ...` sentinel
+ * the model can pattern-match. Each issue contributes one
+ * `path: message` clause; clauses are joined with `; ` so the model
+ * sees every offence in a single line. Path with the root scope is
+ * rendered as `<root>` to avoid an empty colon.
+ */
+function renderZodIssues(error) {
+    const parts = error.issues.map((issue) => {
+        const path = issue.path.length === 0 ? '<root>' : issue.path.join('.');
+        return `${path}: ${issue.message}`;
+    });
+    return `${TODO_INVALID_ARGS}: ${parts.join('; ')}`;
+}
+/**
+ * Validate via Zod + persist atomically. Surfaces three sentinel
+ * families the dispatcher pattern-matches on:
+ *   - `INVALID_ARGS: <path>: <issue>; ...`        — Zod schema rejected
+ *     the raw arguments (returned as STRING, not thrown).
+ *   - `TODO_INVARIANT_VIOLATED: ...`              — >1 in_progress
+ *     (thrown by `saveTodoBoard`).
+ *   - `TODO_DUPLICATE_ID: ...`                    — collision within batch
+ *     (thrown by `saveTodoBoard`).
+ *
+ * Why the asymmetry: schema rejection means the model emitted malformed
+ * structure (missing field, wrong type) and CAN self-correct given a
+ * clear breakdown of the offending path. The invariant + duplicate-id
+ * paths mean the model emitted structurally-valid but semantically
+ * conflicting state — those still throw so the engine loop's tool-error
+ * hook can surface them through `PostToolUseFailure` for observability,
+ * mirroring how the file-tools layer surfaces `STALE_READ` / `PermissionDenied`.
+ */
+export function dispatchTodoWrite(ctx, rawArgs) {
+    // L16 P1 fix (2026-05-27): `.parse` throws a `ZodError` on validation
+    // failure. The previous implementation let that throw bubble through
+    // the engine adapter's catch arm as a free-form `error.message`,
+    // which (a) loses the issue-by-issue structure the model needs to
+    // self-correct, and (b) tears down the tool-call as a hard failure
+    // rather than a recoverable tool result. Switch to `safeParse` and
+    // emit a structured `INVALID_ARGS: <path>: <issue>; ...` sentinel
+    // string instead — the engine sees a successful tool call, the model
+    // sees the offending paths, and the dispatcher's catch arm reserves
+    // throws for the genuine semantic conflicts emitted by `saveTodoBoard`.
+    const parsed = todoWriteArgsSchema.safeParse(rawArgs);
+    if (!parsed.success) {
+        return renderZodIssues(parsed.error);
+    }
+    const stateCtx = {
+        workspaceRoot: ctx.workspaceRoot,
+        ...(ctx.now ? { now: ctx.now } : {}),
+    };
+    const board = saveTodoBoard(stateCtx, parsed.data.todos);
+    return JSON.stringify(board);
+}
+//# sourceMappingURL=todo-write.js.map

package/dist/tools/web-fetch.js

@@ -34,7 +34,7 @@
  * Brand voice: brief / dispatch / ship / sentinel only. The
  * brandbook §08 forbidden-word list applies — see CLAUDE.md.
  */
-import { request } from 'undici';
+import { request, Agent } from 'undici';
 import { Readability } from '@mozilla/readability';
 import { parseHTML } from 'linkedom';
 import TurndownService from 'turndown';
@@ -45,6 +45,72 @@ let activeLookup = async (hostname) => await dnsLookup(hostname, { all: true, ve
 export function _setLookupForTests(fn) {
     activeLookup = fn ?? (async (hostname) => await dnsLookup(hostname, { all: true, verbatim: true }));
 }
+/**
+ * β1b #62 — DNS rebinding guard via pinned-address Dispatcher.
+ *
+ * Without this, the SSRF guard's `dns.lookup` and undici's `request()`
+ * connect(2) each issue independent DNS queries. A hostile resolver
+ * can answer "8.8.8.8" the first time (passes the SSRF guard) and
+ * "127.0.0.1" the second time (kernel connects to local metadata).
+ *
+ * Fix: resolve once, validate, then pin the resolved address into a
+ * per-call `Agent` via `connect.lookup`. The connect() path no longer
+ * touches DNS — it uses the IP we already approved.
+ *
+ * Test seam: spec suite uses MockAgent as the global dispatcher; the
+ * MockAgent path does not exercise real connect(), so pinning is both
+ * pointless and would break the MockAgent stub. Specs flip
+ * `_disablePinnedDispatcherForTests(true)` in beforeEach to keep the
+ * MockAgent flow intact while production hits the pinned path.
+ */
+let pinnedDispatcherDisabled = false;
+export function _disablePinnedDispatcherForTests(disabled) {
+    pinnedDispatcherDisabled = disabled;
+}
+/**
+ * Build a per-call undici Agent that always returns the pre-resolved
+ * `address` from its connect.lookup hook. Returns `undefined` when the
+ * test flag disabled pinning — caller then falls back to the global
+ * dispatcher (MockAgent or production default).
+ */
+async function buildPinnedDispatcher(hostname) {
+    if (pinnedDispatcherDisabled)
+        return undefined;
+    // Skip pinning when hostname is already a literal IP — there is no
+    // DNS step to race in that case.
+    if (isIPv4(hostname) || isIPv6(hostname))
+        return undefined;
+    let answers;
+    try {
+        answers = await activeLookup(hostname);
+    }
+    catch {
+        // Best-effort — fall through without pinning; the SSRF guard will
+        // emit the canonical DNS-lookup-failed error on the caller's path.
+        return undefined;
+    }
+    const pinned = answers[0];
+    if (!pinned)
+        return undefined;
+    // β1b r1: close the DNS rebinding window the original guard could
+    // not see. `validateHostnameForFetch` already ran one lookup; the
+    // call above is a SECOND lookup whose answer feeds the pin. A
+    // hostile resolver can return a public address to the guard and a
+    // private address here — re-validate the pinned literal before we
+    // hand it to the Agent. Throws so the caller surfaces a security
+    // refusal rather than silently dispatching to the wrong host.
+    const ipCheck = validateIpLiteralForFetch(pinned.address, pinned.family);
+    if (ipCheck !== null) {
+        throw new Error(`ssrf_pinned_address_blocked: ${ipCheck}`);
+    }
+    return new Agent({
+        connect: {
+            lookup: (_h, _opts, cb) => {
+                cb(null, pinned.address, pinned.family);
+            },
+        },
+    });
+}
 const FETCH_TIMEOUT_MS = 10_000;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024; // 5 MiB
 const MAX_REDIRECTS = 5;
@@ -231,6 +297,42 @@ function ipv4IsBlocked(ip) {
     }
     return false;
 }
+/**
+ * Validate a single IP literal (v4 or v6) against the SSRF blocklist.
+ * Pure synchronous check — no DNS. Returns `null` on success (safe to
+ * connect), an error string when the address is blocked or not a
+ * recognized IP literal.
+ *
+ * Used by the pinned-dispatcher path (web-fetch + web-search) to
+ * RE-VALIDATE the address actually pinned into `connect.lookup` AFTER
+ * the second DNS round-trip. Without this check the original SSRF
+ * guard's lookup answers can diverge from the lookup answers that
+ * feed the pin (hostile resolver flips public→private between calls);
+ * re-checking the pinned literal closes that window.
+ *
+ * Exported for spec coverage.
+ */
+export function validateIpLiteralForFetch(address, family) {
+    if (!address)
+        return 'empty address';
+    // Trust family hint when present (LookupAddress.family is 4 or 6),
+    // otherwise infer from the string shape.
+    const isV4 = family === 4 || (family === undefined && isIPv4(address));
+    const isV6 = family === 6 || (family === undefined && isIPv6(address));
+    if (isV4) {
+        if (ipv4IsBlocked(address)) {
+            return `IP ${address} is in a blocked range (SSRF guard)`;
+        }
+        return null;
+    }
+    if (isV6) {
+        if (ipv6IsBlocked(address)) {
+            return `IPv6 ${address} is in a blocked range (SSRF guard)`;
+        }
+        return null;
+    }
+    return `address ${address} is not a recognized IPv4/IPv6 literal`;
+}
 /**
  * Resolve `hostname` via dns.lookup and reject if any answer maps to
  * a private/loopback/link-local/CGNAT range. Returns `null` on success
@@ -395,10 +497,34 @@ export async function webFetchTool(input, ctx) {
     let currentUrl = parsedUrl;
     let hops = 0;
     const controller = new AbortController();
+    // β1b #62: per-hop pinned Agent so the post-lookup connect(2) cannot
+    // be redirected to a private IP by a hostile resolver. Built lazily
+    // per hop because each redirect target may resolve to a different
+    // host. `undefined` falls back to the global dispatcher (spec
+    // MockAgent or production default), preserving the existing test
+    // path. The current Agent is closed at end-of-call so we do not leak
+    // open connections.
+    let activeAgent;
+    const closeActiveAgent = async () => {
+        if (activeAgent) {
+            try {
+                await activeAgent.close();
+            }
+            catch {
+                /* ignore — agent already closed */
+            }
+            activeAgent = undefined;
+        }
+    };
     try {
         while (true) {
+            // β1b #62: refresh the pinned Agent for the current hop.
+            await closeActiveAgent();
+            const hopHost = currentUrl.hostname.replace(/^\[|\]$/g, '');
+            activeAgent = await buildPinnedDispatcher(hopHost);
             response = await request(currentUrl.toString(), {
                 method: 'GET',
+                ...(activeAgent ? { dispatcher: activeAgent } : {}),
                 headers: {
                     'user-agent': USER_AGENT,
                     accept: 'text/html,application/xhtml+xml',
@@ -436,6 +562,7 @@ export async function webFetchTool(input, ctx) {
                             /* socket already closed — nothing to do */
                         }
                     }
+                    await closeActiveAgent();
                     return { ok: false, error: `Exceeded ${MAX_REDIRECTS} redirect hops.` };
                 }
                 // Drain prior body so the socket can be reused.
@@ -445,9 +572,11 @@ export async function webFetchTool(input, ctx) {
                     nextUrl = new URL(locStr, currentUrl);
                 }
                 catch {
+                    await closeActiveAgent();
                     return { ok: false, error: `Invalid redirect target: ${locStr}` };
                 }
                 if (nextUrl.protocol !== 'http:' && nextUrl.protocol !== 'https:') {
+                    await closeActiveAgent();
                     return {
                         ok: false,
                         error: `Refusing redirect to unsupported scheme ${nextUrl.protocol}.`,
@@ -456,6 +585,7 @@ export async function webFetchTool(input, ctx) {
                 const nextHost = nextUrl.hostname.replace(/^\[|\]$/g, '');
                 const guard = await validateHostnameForFetch(nextHost);
                 if (guard) {
+                    await closeActiveAgent();
                     return { ok: false, error: `SSRF refused on redirect: ${guard}` };
                 }
                 currentUrl = nextUrl;
@@ -465,13 +595,23 @@ export async function webFetchTool(input, ctx) {
         }
     }
     catch (error) {
+        await closeActiveAgent();
         const message = error instanceof Error ? error.message : String(error);
+        // β1b r1: the pinned-dispatcher path throws `ssrf_pinned_address_blocked: …`
+        // when the second DNS lookup answered a private IP. Surface that as a
+        // first-class SSRF refusal so callers (and specs) can match on it
+        // without grovelling through `Fetch failed:` prefixes.
+        if (message.startsWith('ssrf_pinned_address_blocked')) {
+            return { ok: false, error: `SSRF refused: ${message}` };
+        }
         return { ok: false, error: `Fetch failed: ${message}` };
     }
     if (!response) {
+        await closeActiveAgent();
         return { ok: false, error: 'No response received.' };
     }
     if (response.statusCode < 200 || response.statusCode >= 300) {
+        await closeActiveAgent();
         return { ok: false, error: `HTTP ${response.statusCode} from ${currentUrl.toString()}` };
     }
     // content-length is advisory — never trust it for the size cap, but
@@ -489,6 +629,7 @@ export async function webFetchTool(input, ctx) {
             catch {
                 /* ignore */
             }
+            await closeActiveAgent();
             return {
                 ok: false,
                 error: `Declared content-length ${n} exceeds ${MAX_RESPONSE_BYTES} byte cap.`,
@@ -499,11 +640,14 @@ export async function webFetchTool(input, ctx) {
     const contentType = Array.isArray(contentTypeRaw) ? contentTypeRaw[0] : contentTypeRaw;
     const mime = typeof contentType === 'string' ? contentType.split(';')[0]?.trim().toLowerCase() ?? '' : '';
     if (!ALLOWED_CONTENT_TYPES.includes(mime)) {
+        await closeActiveAgent();
         return { ok: false, error: `Disallowed content-type ${mime || '(none)'}; only HTML/XHTML/text.` };
     }
     const bodyResult = await readBodyWithCap(response.body, controller);
-    if (!bodyResult.ok)
+    if (!bodyResult.ok) {
+        await closeActiveAgent();
         return bodyResult;
+    }
     const html = bodyResult.buffer.toString('utf8');
     // linkedom is the lightweight DOM Readability needs; jsdom would
     // add ~3 MB to the install footprint for the same surface.
@@ -524,6 +668,7 @@ export async function webFetchTool(input, ctx) {
         `Source: ${safeSource}\n\n` +
         `${scrubbedMarkdown}\n` +
         `</untrusted-content-${nonce}>`;
+    await closeActiveAgent();
     return {
         ok: true,
         url: currentUrl.toString(),