@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/tools/synthetic-output.js

@@ -0,0 +1,133 @@
+/**
+ * synthetic_output tool — operator-readable echo helper (tool gap
+ * pack). EXPERIMENTAL / engine-only.
+ *
+ * Test fixture cousin of `brief`. Whereas `brief` persists a structured
+ * record to `.pugi/briefs/<session>.jsonl`, `synthetic_output` writes
+ * the supplied text VERBATIM к the requested stream (`stdout` or
+ * `stderr`). The use case is the engine-side test harness: a spec wants
+ * to assert that "the loop ran this tool with this payload" without
+ * spinning up the entire dispatch pipeline, AND wants to observe the
+ * write the same way an operator would. Production agent flows should
+ * prefer `brief` because the structured record survives crashes — the
+ * stream write does not.
+ *
+ * The tool is NOT exposed as a slash command. The schema is advertised
+ * to the engine only when the executor is built with an
+ * `allowSyntheticOutput: true` opt-in. Customer CLIs leave it off so
+ * the model cannot use it as a side-channel to bypass the normal tool
+ * result envelope (which is logged, classified, hooked, etc.).
+ *
+ * Wire shape:
+ *  args:  { stream: 'stdout'|'stderr', text: string }
+ *          - text is capped at 16 KiB UTF-8; over-cap rejects with
+ *            the SYNTHETIC_OUTPUT_TOO_LARGE sentinel.
+ *  side:  raw `process.stdout.write(text)` or `process.stderr.write(text)`.
+ *  return: short JSON envelope { ok, stream, bytes } so the engine
+ *          loop can audit the call without re-reading the streamed
+ *          bytes (which it does not buffer).
+ *
+ * Atomicity: writes go to the live process stream; partial writes are
+ * the stream's responsibility, not the tool's. The tool does NOT add a
+ * trailing newline — the model controls the exact bytes. This is the
+ * design point that makes it a useful test fixture (specs assert on
+ * verbatim bytes).
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+/** Per-call byte cap. Mirrors the bash tool's stdout/stderr cap so the
+ * model cannot blow either pane with a single synthetic flush. */
+export const SYNTHETIC_OUTPUT_MAX_BYTES = 16 * 1_024;
+/** Canonical stream values. */
+export const SYNTHETIC_OUTPUT_STREAMS = ['stdout', 'stderr'];
+/** Sentinel returned when input validation rejects the call. */
+export const SYNTHETIC_OUTPUT_INVALID_ARGS = 'SYNTHETIC_OUTPUT_INVALID_ARGS';
+/** Sentinel returned when the encoded text exceeds the per-call cap.
+ * Distinct from the args-schema failure so the model knows to shorten
+ * the payload rather than change the shape. */
+export const SYNTHETIC_OUTPUT_TOO_LARGE = 'SYNTHETIC_OUTPUT_TOO_LARGE';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `SYNTHETIC_OUTPUT_INVALID_ARGS: ...` sentinel string.
+ */
+export function parseSyntheticOutputArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${SYNTHETIC_OUTPUT_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const stream = obj['stream'];
+    if (typeof stream !== 'string') {
+        issues.push('stream: must be a string');
+    }
+    else if (!SYNTHETIC_OUTPUT_STREAMS.includes(stream)) {
+        issues.push(`stream: must be one of ${SYNTHETIC_OUTPUT_STREAMS.join('|')}`);
+    }
+    const text = obj['text'];
+    if (typeof text !== 'string') {
+        issues.push('text: must be a string');
+    }
+    if (issues.length > 0) {
+        return `${SYNTHETIC_OUTPUT_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    return {
+        stream: stream,
+        text: text,
+    };
+}
+/**
+ * Dispatch entry point. Validates input, writes the text verbatim to
+ * the requested stream, and returns the structured envelope as JSON.
+ *
+ * Returns sentinel strings (no throw) on recoverable failures so the
+ * engine adapter surfaces them as tool results.
+ */
+export function dispatchSyntheticOutput(ctx, raw) {
+    const parsed = parseSyntheticOutputArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const bytes = Buffer.byteLength(parsed.text, 'utf8');
+    if (bytes > SYNTHETIC_OUTPUT_MAX_BYTES) {
+        return `${SYNTHETIC_OUTPUT_TOO_LARGE}: encoded text exceeds ${SYNTHETIC_OUTPUT_MAX_BYTES} bytes`;
+    }
+    // Resolve writers once per call so a spec can override stdout while
+    // letting stderr fall through to the real process stream.
+    const writer = parsed.stream === 'stdout'
+        ? (ctx.stdoutWrite ?? defaultStdoutWrite)
+        : (ctx.stderrWrite ?? defaultStderrWrite);
+    writer(parsed.text);
+    const result = {
+        ok: true,
+        stream: parsed.stream,
+        bytes,
+    };
+    return JSON.stringify(result);
+}
+function defaultStdoutWrite(chunk) {
+    process.stdout.write(chunk);
+}
+function defaultStderrWrite(chunk) {
+    process.stderr.write(chunk);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ * Hand-written for parity with the rest of the tool surface.
+ */
+export const syntheticOutputJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['stream', 'text'],
+    properties: {
+        stream: {
+            type: 'string',
+            enum: [...SYNTHETIC_OUTPUT_STREAMS],
+            description: 'Destination stream: stdout or stderr.',
+        },
+        text: {
+            type: 'string',
+            description: `Verbatim bytes to write. Capped at ${SYNTHETIC_OUTPUT_MAX_BYTES} bytes UTF-8.`,
+        },
+    },
+};
+//# sourceMappingURL=synthetic-output.js.map

package/dist/tools/tasks.js

@@ -0,0 +1,208 @@
+/**
+ * task_* tool family — β1 T1/T6 (TodoWrite + agent task ledger).
+ *
+ * Mirrors the standard tool's TodoWrite tool surface so a model trained on
+ * the upstream tool grammar speaks Pugi's variant verbatim. Four ops:
+ *
+ *  - `task_create` — append a new task to the session's todo ledger.
+ *    Returns the assigned id.
+ *  - `task_get`   — fetch a single task by id.
+ *  - `task_list`  — list every task in the current session, ordered
+ *                    by createdAt ascending.
+ *  - `task_update` — mutate status/title/notes of an existing task.
+ *                    Append-only journal — every mutation lands as a
+ *                    fresh JSONL line and the latest line per id wins
+ *                    on `task_list` / `task_get` reads.
+ *
+ * Persistence: append-only JSONL at
+ * `.pugi/sessions/<sessionId>/tasks.jsonl`. Append-only keeps crash
+ * recovery trivial — a partial write at the end of the file is the
+ * worst case and the parser drops the malformed tail line.
+ *
+ * Scope: this is the local-side ledger surface. Anvil-side mirror
+ * (cabinet `/projects/[id]/tasks` page) ships in β5 once the session-
+ * memory hook lands; until then the ledger is purely local.
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+function ledgerPath(ctx) {
+    // Defense-in-depth: the sessionId is supposed to be a UUID minted by
+    // openSession() but the tool surface is operator-facing. Validate the
+    // shape before composing a path — refuse anything that contains
+    // separators or shell wildcards.
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(ctx.sessionId)) {
+        throw new Error(`task_*: invalid sessionId shape: "${ctx.sessionId}"`);
+    }
+    return join(ctx.workspaceRoot, '.pugi', 'sessions', ctx.sessionId, 'tasks.jsonl');
+}
+function nowIso(ctx) {
+    return (ctx.now ? ctx.now() : new Date()).toISOString();
+}
+function ensureDir(path) {
+    // β1a r1 : switched from POSIX-only
+    // `path.slice(0, path.lastIndexOf('/'))` to `path.dirname()` so
+    // Windows path separators (`\`) work. Also chmod the per-session
+    // directory to 0o700 — the tasks ledger carries operator-confidential
+    // brief text, status notes, and timing metadata that should not be
+    // world-readable through an inherited umask.
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Best-effort. POSIX permission setting is a no-op on Windows
+            // NTFS, and the dir-creation race with another concurrent task
+            // tool call is the only realistic failure case. The 0o600 mode
+            // on the JSONL file itself remains the primary guard; the dir
+            // chmod is defense in depth for tools that walk `.pugi/`.
+        }
+    }
+}
+function readJournal(ctx) {
+    const path = ledgerPath(ctx);
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if ((parsed.op === 'create' || parsed.op === 'update') &&
+                typeof parsed.id === 'string' &&
+                typeof parsed.at === 'string') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Drop malformed line (partial-write tail or external corruption).
+            // The append-only design guarantees only the LAST line can be bad
+            // — everything before it is whole.
+        }
+    }
+    return out;
+}
+function fold(journal) {
+    const out = new Map();
+    for (const entry of journal) {
+        if (entry.op === 'create') {
+            if (!entry.title)
+                continue;
+            out.set(entry.id, {
+                id: entry.id,
+                title: entry.title,
+                status: entry.status ?? 'pending',
+                ...(entry.notes !== undefined ? { notes: entry.notes } : {}),
+                createdAt: entry.at,
+                updatedAt: entry.at,
+            });
+        }
+        else {
+            const prev = out.get(entry.id);
+            if (!prev)
+                continue; // update before create — drop silently
+            out.set(entry.id, {
+                ...prev,
+                ...(entry.title !== undefined ? { title: entry.title } : {}),
+                ...(entry.status !== undefined ? { status: entry.status } : {}),
+                ...(entry.notes !== undefined ? { notes: entry.notes } : {}),
+                updatedAt: entry.at,
+            });
+        }
+    }
+    return out;
+}
+function appendEntry(ctx, entry) {
+    const path = ledgerPath(ctx);
+    ensureDir(path);
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export function taskCreate(ctx, input) {
+    const title = input.title?.trim();
+    if (!title) {
+        throw new Error('task_create: title is required');
+    }
+    if (title.length > 2_000) {
+        throw new Error('task_create: title exceeds 2000 char cap');
+    }
+    const status = input.status ?? 'pending';
+    if (!isValidStatus(status)) {
+        throw new Error(`task_create: invalid status "${status}"`);
+    }
+    const id = `task-${randomUUID()}`;
+    const at = nowIso(ctx);
+    const entry = {
+        op: 'create',
+        id,
+        title,
+        status,
+        at,
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+    };
+    appendEntry(ctx, entry);
+    return {
+        id,
+        title,
+        status,
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+        createdAt: at,
+        updatedAt: at,
+    };
+}
+export function taskGet(ctx, id) {
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new Error('task_get: id is required');
+    }
+    const folded = fold(readJournal(ctx));
+    return folded.get(id) ?? null;
+}
+export function taskList(ctx) {
+    const folded = fold(readJournal(ctx));
+    return Array.from(folded.values()).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+export function taskUpdate(ctx, input) {
+    if (!input.id)
+        throw new Error('task_update: id is required');
+    const folded = fold(readJournal(ctx));
+    const existing = folded.get(input.id);
+    if (!existing) {
+        throw new Error(`task_update: unknown id "${input.id}"`);
+    }
+    if (input.status !== undefined && !isValidStatus(input.status)) {
+        throw new Error(`task_update: invalid status "${input.status}"`);
+    }
+    if (input.title !== undefined && input.title.trim().length === 0) {
+        throw new Error('task_update: title cannot be empty');
+    }
+    const at = nowIso(ctx);
+    const entry = {
+        op: 'update',
+        id: input.id,
+        at,
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+    };
+    appendEntry(ctx, entry);
+    return {
+        ...existing,
+        ...(input.title !== undefined ? { title: input.title } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.notes !== undefined ? { notes: input.notes } : {}),
+        updatedAt: at,
+    };
+}
+function isValidStatus(status) {
+    return (status === 'pending' ||
+        status === 'in_progress' ||
+        status === 'completed' ||
+        status === 'cancelled');
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tools/todo-write.js

@@ -0,0 +1,184 @@
+/**
+ * todo_write tool — .
+ *
+ * Mirrors the standard tool'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 : `.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