@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/tools/brief.js

@@ -0,0 +1,224 @@
+/**
+ * brief tool — operator-facing progress brief (tool gap pack).
+ *
+ * Emits a short, structured status note from the engine to the operator
+ * without consuming an assistant turn for narrative. The model calls
+ * this tool when it wants to surface "what I am doing right now" — a
+ * planning sketch, a blocker reason, a final wrap — in a form the
+ * operator can scan at-a-glance.
+ *
+ * Wire shape:
+ *  args: { headline: string, status: 'planning'|'working'|'blocked'|'done',
+ *          detail?: string }
+ *  side-effect: append one JSON line to `.pugi/briefs/<sessionId>.jsonl`,
+ *               via the atomic tmp+rename pattern (see writeBriefLine).
+ *  return:     one-line text envelope the engine echoes back to the
+ *               operator's stdout (the engine adapter renders it as a
+ *               neutral system line above the next model output).
+ *
+ * Why JSONL (one record per line) instead of a single rewritten JSON
+ * document: briefs accumulate across a session and the operator may
+ * want to scroll back through them; a JSONL tail is the natural shape
+ * for "give me the last N briefs" — same convention `.pugi/sessions/`
+ * already uses for tool-call events.
+ *
+ * Why atomic tmp+rename for append: a concurrent reader (`pugi briefs
+ * --tail`, future TUI surface) must never see a half-written line. The
+ * pattern: read existing body -> append the new line -> write the
+ * combined body to a sibling tmp file -> rename. Atomic on the same
+ * filesystem and POSIX-portable. The overhead (re-write the whole file
+ * on each append) is acceptable because briefs are short and capped to
+ * a small per-session budget by upstream rate limits.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** Maximum header length. Mirrors the agent-progress card cap so the
+ * TUI can render briefs and progress cards in the same visual lane. */
+export const BRIEF_HEADLINE_MAX = 120;
+/** Maximum detail length. Keeps a single brief well below the 4 KiB
+ * line limit some tooling assumes for JSONL files. */
+export const BRIEF_DETAIL_MAX = 2_000;
+/** Hard cap on total bytes per brief line. Defense-in-depth gate so a
+ * pathological detail-with-headline-with-status combo cannot blow the
+ * tail consumer's per-line buffer. */
+export const BRIEF_LINE_MAX_BYTES = 4_096;
+/** Canonical brief statuses. The set is intentionally tiny — the goal
+ * is "what is the agent doing" at a glance, not a free-form taxonomy. */
+export const BRIEF_STATUSES = ['planning', 'working', 'blocked', 'done'];
+/** Sentinel returned when the input fails schema validation. The
+ * dispatcher pattern-matches on the prefix for retry-budget bookkeeping
+ * and the model self-corrects from the issue list that follows. */
+export const BRIEF_INVALID_ARGS = 'BRIEF_INVALID_ARGS';
+/** Sentinel returned when the encoded line would exceed the per-line
+ * byte cap. Distinct from the args-schema failure so the model knows it
+ * needs to shorten the detail / headline, not change the shape. */
+export const BRIEF_LINE_TOO_LARGE = 'BRIEF_LINE_TOO_LARGE';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `BRIEF_INVALID_ARGS: ...` sentinel string the dispatcher surfaces back
+ * to the model.
+ */
+export function parseBriefArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${BRIEF_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const headline = obj['headline'];
+    if (typeof headline !== 'string') {
+        issues.push('headline: must be a string');
+    }
+    else if (headline.trim().length === 0) {
+        issues.push('headline: must be non-empty');
+    }
+    else if (headline.length > BRIEF_HEADLINE_MAX) {
+        issues.push(`headline: must be <= ${BRIEF_HEADLINE_MAX} chars`);
+    }
+    const status = obj['status'];
+    if (typeof status !== 'string') {
+        issues.push('status: must be a string');
+    }
+    else if (!BRIEF_STATUSES.includes(status)) {
+        issues.push(`status: must be one of ${BRIEF_STATUSES.join('|')}`);
+    }
+    let detail;
+    if (obj['detail'] !== undefined && obj['detail'] !== null) {
+        if (typeof obj['detail'] !== 'string') {
+            issues.push('detail: must be a string when present');
+        }
+        else if (obj['detail'].length > BRIEF_DETAIL_MAX) {
+            issues.push(`detail: must be <= ${BRIEF_DETAIL_MAX} chars`);
+        }
+        else {
+            detail = obj['detail'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${BRIEF_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const result = detail !== undefined
+        ? { headline: headline, status: status, detail }
+        : { headline: headline, status: status };
+    return result;
+}
+/**
+ * Compute the on-disk path for a session's brief log. Public so a
+ * future tail consumer (`pugi briefs --tail <session>`) can share the
+ * exact resolution rules without duplicating layout knowledge.
+ */
+export function briefLogPath(ctx) {
+    const safe = sanitizeSessionId(ctx.sessionId);
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'briefs', `${safe}.jsonl`);
+}
+/**
+ * Sanitise a session id for use as a filename. Restricts to the same
+ * character set agent-progress uses (`[A-Za-z0-9_-]+`) so the basename
+ * cannot escape the briefs directory via a `..` segment. Collapses any
+ * disallowed character to `_`; an empty result falls back to `session`.
+ *
+ * NOT exported as a generic helper because the only caller is this
+ * module — keep the surface area minimal.
+ */
+function sanitizeSessionId(id) {
+    if (typeof id !== 'string' || id.length === 0)
+        return 'session';
+    const collapsed = id.replace(/[^A-Za-z0-9_-]/g, '_');
+    const trimmed = collapsed.slice(0, 64);
+    return trimmed.length > 0 ? trimmed : 'session';
+}
+/**
+ * Dispatch entry point. Validates input, persists the brief line, and
+ * returns the operator-visible echo envelope. Returns sentinels on
+ * recoverable failures so the engine loop can surface them as tool
+ * results without tearing down on a throw.
+ */
+export function dispatchBrief(ctx, raw) {
+    const parsed = parseBriefArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const ts = (ctx.now ? ctx.now() : new Date()).toISOString();
+    const record = parsed.detail !== undefined
+        ? { ts, status: parsed.status, headline: parsed.headline, detail: parsed.detail }
+        : { ts, status: parsed.status, headline: parsed.headline };
+    const line = JSON.stringify(record);
+    // Defense-in-depth byte cap. The earlier char-length checks bound the
+    // best case, but multi-byte UTF-8 input can still push the encoded
+    // line over the limit. Surface a distinct sentinel so the model knows
+    // to shorten the payload rather than change the shape.
+    if (Buffer.byteLength(line, 'utf8') > BRIEF_LINE_MAX_BYTES) {
+        return `${BRIEF_LINE_TOO_LARGE}: encoded line exceeds ${BRIEF_LINE_MAX_BYTES} bytes`;
+    }
+    const path = briefLogPath(ctx);
+    appendBriefLine(path, line);
+    return formatEcho(record, path);
+}
+/**
+ * Atomic append. Read existing body -> append the new line -> write to
+ * sibling tmp -> rename. The rename is atomic on the same filesystem
+ * so a concurrent tail consumer never reads a half-written line.
+ *
+ * Append-only via full rewrite is acceptable because brief logs are
+ * tiny (one short JSON object per call, sub-kilobyte each, capped by
+ * upstream rate limits to a few-hundred per session at most).
+ */
+function appendBriefLine(finalPath, line) {
+    const dir = dirname(finalPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const prior = existsSync(finalPath) ? readFileSync(finalPath, 'utf8') : '';
+    const tail = prior.length > 0 && !prior.endsWith('\n') ? '\n' : '';
+    const next = `${prior}${tail}${line}\n`;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${briefSequence++}`;
+    writeFileSync(tmpPath, next, { encoding: 'utf8', mode: 0o644 });
+    renameSync(tmpPath, finalPath);
+}
+let briefSequence = 0;
+/**
+ * Render the one-line operator echo. The format is stable so a future
+ * REPL renderer can pattern-match the prefix for colouring.
+ */
+function formatEcho(record, path) {
+    const detail = record.detail ? ` -- ${truncate(record.detail, 240)}` : '';
+    return `[brief ${record.status}] ${record.headline}${detail} (logged to ${path})`;
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ * Hand-written to mirror the `parseBriefArgs` checks 1:1 — same
+ * convention `todo_write` and `ask_user_question` use because the
+ * runtime engine wires OpenAI-shape JSON Schema and we have not
+ * greenlit a zod-to-json-schema dependency.
+ */
+export const briefJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['headline', 'status'],
+    properties: {
+        headline: {
+            type: 'string',
+            minLength: 1,
+            maxLength: BRIEF_HEADLINE_MAX,
+            description: `Short one-line summary, <= ${BRIEF_HEADLINE_MAX} chars.`,
+        },
+        status: {
+            type: 'string',
+            enum: [...BRIEF_STATUSES],
+            description: 'Lifecycle state: planning (deciding what to do), working (in progress), ' +
+                'blocked (waiting on operator), done (final wrap).',
+        },
+        detail: {
+            type: 'string',
+            maxLength: BRIEF_DETAIL_MAX,
+            description: `Optional context, <= ${BRIEF_DETAIL_MAX} chars.`,
+        },
+    },
+};
+//# sourceMappingURL=brief.js.map

package/dist/tools/cron.js

@@ -0,0 +1,433 @@
+/**
+ * cron_* tool family — ScheduleCronTool / CronList / CronDelete (PUGI-7).
+ *
+ * Three tools that expose the local cron-routine surface to the persona:
+ *
+ *  - `cron_create` — register a recurring routine. Writes one JSON
+ *    document per routine to `.pugi/cron/<name>.json` via the atomic
+ *    tmp+rename pattern.
+ *  - `cron_delete` — remove a routine by name. Idempotent: deleting an
+ *    unknown name returns `{ ok: true, removed: false }` instead of
+ *    throwing, so the model never wedges on a stale routine list.
+ *  - `cron_list` — return every registered routine, sorted by name.
+ *    An empty registry returns `{ routines: [] }`, NOT an error.
+ *
+ * Why one JSON document per routine instead of a single `routines.json`
+ * board: routines are independent — there is no cross-routine invariant
+ * (unlike the `todo_write` single-in-progress rule). Per-file storage
+ * means a corrupt or partially-written routine cannot poison the
+ * others, and the atomic tmp+rename pattern is a one-file-at-a-time
+ * primitive that maps cleanly to per-file persistence.
+ *
+ * Why hand-rolled JSON-Schema instead of zod-to-json-schema: matches
+ * the project-wide convention (see brief.ts §note) — we have not
+ * greenlit the runtime dependency, and the schemas here are small
+ * enough to author by hand without drift risk.
+ *
+ * Cron expression validation: delegates to node-cron's `validate()` via
+ * `isValidCronExpression()` in core/cron/scheduler.ts. node-cron handles
+ * 5-field standard expressions plus the common shortcuts. We do NOT
+ * roll our own regex because cron has too many edge cases (step values,
+ * ranges with step, named months/days) and a partial regex silently
+ * accepts garbage the scheduler later rejects.
+ *
+ * On duplicate name during cron_create: the second call REPLACES the
+ * first, mirroring `CronScheduler.schedule()` which also replaces. The
+ * dispatcher returns `{ ok: true, replaced: true }` so the model and
+ * the operator can see the swap happened. Rationale: a routine name is
+ * an idempotency key; if the model re-registers the same logical
+ * routine with a tweaked expression we want the new shape to win
+ * rather than failing the call and leaving stale state.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isValidCronExpression } from '../core/cron/scheduler.js';
+/** Maximum routine name length. Kept small so it renders cleanly in
+ * the operator-facing `pugi routines list` table. */
+export const CRON_NAME_MAX = 64;
+/** Maximum command length. The routine executes a shell command, so
+ * the cap mirrors the operator-facing brief detail cap — long enough
+ * for a realistic invocation, short enough to log without truncation. */
+export const CRON_COMMAND_MAX = 2_000;
+/** Maximum description length. Free-form prose, capped to fit one
+ * paragraph in the routines table. */
+export const CRON_DESCRIPTION_MAX = 500;
+/** Maximum number of positional args. A large arg list is a smell —
+ * the model should wrap into a single script invocation instead. */
+export const CRON_ARGS_MAX = 32;
+/** Maximum per-arg length. Same rationale as CRON_COMMAND_MAX. */
+export const CRON_ARG_LEN_MAX = 500;
+/** Sentinel returned when input fails schema validation. Mirrors
+ * `BRIEF_INVALID_ARGS` / `VERIFY_PLAN_INVALID_ARGS` so the dispatcher
+ * pattern-matches the prefix for retry-budget bookkeeping. */
+export const CRON_INVALID_ARGS = 'CRON_INVALID_ARGS';
+/** Sentinel returned when a registry write fails for an
+ * environment-level reason (filesystem full, permission denied). */
+export const CRON_PERSIST_FAILED = 'CRON_PERSIST_FAILED';
+/** Allowed routine name pattern. Slug-shaped so the name maps 1:1 to
+ * a safe filesystem basename — no separators, no shell metacharacters,
+ * no leading dot. */
+const CRON_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+/* -------------------------------------------------------------------------- */
+/* parse helpers                                                              */
+/* -------------------------------------------------------------------------- */
+export function parseCronCreateArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${CRON_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const name = obj['name'];
+    if (typeof name !== 'string') {
+        issues.push('name: must be a string');
+    }
+    else if (name.length === 0) {
+        issues.push('name: must be non-empty');
+    }
+    else if (name.length > CRON_NAME_MAX) {
+        issues.push(`name: must be <= ${CRON_NAME_MAX} chars`);
+    }
+    else if (!CRON_NAME_RE.test(name)) {
+        issues.push('name: must match /^[a-z][a-z0-9_-]{0,63}$/ (lowercase, no separators, no leading digit)');
+    }
+    const cronExpression = obj['cronExpression'];
+    if (typeof cronExpression !== 'string') {
+        issues.push('cronExpression: must be a string');
+    }
+    else if (cronExpression.trim().length === 0) {
+        issues.push('cronExpression: must be non-empty');
+    }
+    else if (!isValidCronExpression(cronExpression)) {
+        issues.push('cronExpression: must be a valid 5-field cron expression (see https://crontab.guru)');
+    }
+    const command = obj['command'];
+    if (typeof command !== 'string') {
+        issues.push('command: must be a string');
+    }
+    else if (command.trim().length === 0) {
+        issues.push('command: must be non-empty');
+    }
+    else if (command.length > CRON_COMMAND_MAX) {
+        issues.push(`command: must be <= ${CRON_COMMAND_MAX} chars`);
+    }
+    let args;
+    if (obj['args'] !== undefined && obj['args'] !== null) {
+        if (!Array.isArray(obj['args'])) {
+            issues.push('args: must be an array of strings when present');
+        }
+        else if (obj['args'].length > CRON_ARGS_MAX) {
+            issues.push(`args: must have <= ${CRON_ARGS_MAX} entries`);
+        }
+        else {
+            args = [];
+            for (let i = 0; i < obj['args'].length; i++) {
+                const a = obj['args'][i];
+                if (typeof a !== 'string') {
+                    issues.push(`args[${i}]: must be a string`);
+                }
+                else if (a.length > CRON_ARG_LEN_MAX) {
+                    issues.push(`args[${i}]: must be <= ${CRON_ARG_LEN_MAX} chars`);
+                }
+                else {
+                    args.push(a);
+                }
+            }
+        }
+    }
+    let description;
+    if (obj['description'] !== undefined && obj['description'] !== null) {
+        if (typeof obj['description'] !== 'string') {
+            issues.push('description: must be a string when present');
+        }
+        else if (obj['description'].length > CRON_DESCRIPTION_MAX) {
+            issues.push(`description: must be <= ${CRON_DESCRIPTION_MAX} chars`);
+        }
+        else {
+            description = obj['description'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${CRON_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const result = {
+        name: name,
+        cronExpression: cronExpression,
+        command: command,
+        ...(args !== undefined ? { args } : {}),
+        ...(description !== undefined ? { description } : {}),
+    };
+    return result;
+}
+export function parseCronDeleteArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${CRON_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const name = obj['name'];
+    if (typeof name !== 'string') {
+        return `${CRON_INVALID_ARGS}: name: must be a string`;
+    }
+    if (name.length === 0) {
+        return `${CRON_INVALID_ARGS}: name: must be non-empty`;
+    }
+    if (name.length > CRON_NAME_MAX) {
+        return `${CRON_INVALID_ARGS}: name: must be <= ${CRON_NAME_MAX} chars`;
+    }
+    if (!CRON_NAME_RE.test(name)) {
+        return `${CRON_INVALID_ARGS}: name: must match /^[a-z][a-z0-9_-]{0,63}$/`;
+    }
+    return { name };
+}
+/* -------------------------------------------------------------------------- */
+/* path resolution                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Compute the on-disk path for a routine's JSON document. Public so
+ * future surfaces (`pugi routines show <name>`) can share the layout
+ * rules without duplicating string composition.
+ */
+export function cronRoutinePath(ctx, name) {
+    // Defense in depth: the name is already validated by the parse layer,
+    // but a direct programmatic caller (tests, future internal hooks)
+    // might skip parsing. Re-check the slug shape here so we never compose
+    // a path that escapes the cron directory.
+    if (!CRON_NAME_RE.test(name)) {
+        throw new Error(`cron: invalid routine name shape: "${name}"`);
+    }
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'cron', `${name}.json`);
+}
+function cronDir(ctx) {
+    return join(resolve(ctx.workspaceRoot), '.pugi', 'cron');
+}
+/* -------------------------------------------------------------------------- */
+/* persistence                                                                */
+/* -------------------------------------------------------------------------- */
+let cronSequence = 0;
+/**
+ * Atomic write: serialise -> sibling tmp file -> rename. POSIX-portable
+ * and atomic on the same filesystem so a concurrent `cron_list` reader
+ * never observes a half-written routine document.
+ */
+function persistRoutine(ctx, routine) {
+    const dir = cronDir(ctx);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const finalPath = cronRoutinePath(ctx, routine.name);
+    const body = `${JSON.stringify(routine, null, 2)}\n`;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${cronSequence++}`;
+    writeFileSync(tmpPath, body, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmpPath, finalPath);
+}
+function loadRoutine(ctx, name) {
+    const path = cronRoutinePath(ctx, name);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isValidLoadedRoutine(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        // A corrupt or partially-written file is treated as "no routine
+        // here" — the next cron_create call replaces it cleanly. We do not
+        // surface the parse error because the model cannot act on it.
+        return null;
+    }
+}
+function isValidLoadedRoutine(value) {
+    return (typeof value.name === 'string' &&
+        typeof value.cronExpression === 'string' &&
+        typeof value.command === 'string' &&
+        Array.isArray(value.args) &&
+        typeof value.createdAt === 'string' &&
+        typeof value.updatedAt === 'string');
+}
+/* -------------------------------------------------------------------------- */
+/* dispatchers                                                                */
+/* -------------------------------------------------------------------------- */
+function nowIso(ctx) {
+    return (ctx.now ? ctx.now() : new Date()).toISOString();
+}
+/**
+ * Dispatch entry for `cron_create`. Returns a JSON-string envelope so
+ * the engine adapter can surface structured data to the persona model
+ * without bespoke parsing. Mirrors the brief/todo_write dispatcher
+ * shape (string return for sentinel routing, JSON-string for success).
+ */
+export function dispatchCronCreate(ctx, raw) {
+    const parsed = parseCronCreateArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const at = nowIso(ctx);
+    const existing = loadRoutine(ctx, parsed.name);
+    const routine = {
+        name: parsed.name,
+        cronExpression: parsed.cronExpression,
+        command: parsed.command,
+        args: parsed.args ?? [],
+        ...(parsed.description !== undefined ? { description: parsed.description } : {}),
+        createdAt: existing ? existing.createdAt : at,
+        updatedAt: at,
+    };
+    try {
+        persistRoutine(ctx, routine);
+    }
+    catch (error) {
+        return `${CRON_PERSIST_FAILED}: ${error.message}`;
+    }
+    const result = {
+        ok: true,
+        routine,
+        replaced: existing !== null,
+    };
+    return JSON.stringify(result);
+}
+/**
+ * Dispatch entry for `cron_delete`. Idempotent: a delete of an unknown
+ * routine returns `{ ok: true, removed: false }` rather than a 404-
+ * shaped sentinel. Rationale: the persona's mental model of "the
+ * routine is gone" is satisfied either way, and treating delete as
+ * idempotent avoids the model spinning on a stale routine that was
+ * already cleaned up by a parallel operator action.
+ */
+export function dispatchCronDelete(ctx, raw) {
+    const parsed = parseCronDeleteArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const path = cronRoutinePath(ctx, parsed.name);
+    let removed = false;
+    if (existsSync(path)) {
+        try {
+            unlinkSync(path);
+            removed = true;
+        }
+        catch (error) {
+            return `${CRON_PERSIST_FAILED}: ${error.message}`;
+        }
+    }
+    const result = {
+        ok: true,
+        removed,
+        name: parsed.name,
+    };
+    return JSON.stringify(result);
+}
+/**
+ * Dispatch entry for `cron_list`. Returns every registered routine,
+ * sorted by name. Zero routines returns an empty array (`{ routines:
+ * [] }`), never an error — an empty registry is the steady state on a
+ * fresh workspace and the model should not have to special-case it.
+ *
+ * `cron_list` accepts no arguments. We still parse the input so that a
+ * model that sends a stray object (because its tool grammar emits
+ * `{}` by default) does not crash; only an explicit non-object value
+ * is rejected with `CRON_INVALID_ARGS`.
+ */
+export function dispatchCronList(ctx, raw) {
+    if (raw !== undefined && raw !== null) {
+        if (typeof raw !== 'object' || Array.isArray(raw)) {
+            return `${CRON_INVALID_ARGS}: arguments must be a JSON object or omitted`;
+        }
+    }
+    const dir = cronDir(ctx);
+    const routines = [];
+    if (existsSync(dir)) {
+        const entries = readdirSync(dir).filter((e) => e.endsWith('.json'));
+        for (const entry of entries) {
+            const name = entry.slice(0, -'.json'.length);
+            // The persistence layer only writes files with slug-safe names,
+            // but a manual edit (operator hand-rolled a file) might violate
+            // the shape. Skip such entries instead of crashing the list call.
+            if (!CRON_NAME_RE.test(name))
+                continue;
+            const routine = loadRoutine(ctx, name);
+            if (routine)
+                routines.push(routine);
+        }
+        routines.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const result = { routines };
+    return JSON.stringify(result);
+}
+/* -------------------------------------------------------------------------- */
+/* JSON-Schema fragments (engine-side tool definitions)                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * JSON-Schema for cron_create. Mirrors `parseCronCreateArgs` checks
+ * 1:1. Hand-rolled per the project convention (see brief.ts §note on
+ * zod-to-json-schema).
+ */
+export const cronCreateJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name', 'cronExpression', 'command'],
+    properties: {
+        name: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_NAME_MAX,
+            pattern: '^[a-z][a-z0-9_-]{0,63}$',
+            description: 'Routine name (slug-shaped, lowercase). Doubles as the on-disk basename and the idempotency key — re-registering with the same name REPLACES the prior routine.',
+        },
+        cronExpression: {
+            type: 'string',
+            minLength: 1,
+            description: 'Standard 5-field cron expression (minute hour day-of-month month day-of-week). Example: "0 9 * * 1-5" runs at 09:00 on weekdays. Validated by node-cron.',
+        },
+        command: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_COMMAND_MAX,
+            description: 'Shell command to execute on each tick. Example: "pugi review --triple --remote". The command is stored verbatim; the runner spawns it without word-splitting.',
+        },
+        args: {
+            type: 'array',
+            maxItems: CRON_ARGS_MAX,
+            items: {
+                type: 'string',
+                maxLength: CRON_ARG_LEN_MAX,
+            },
+            description: 'Optional positional arguments passed to <command> as a separate argv array. Prefer this over embedding shell metacharacters in <command>.',
+        },
+        description: {
+            type: 'string',
+            maxLength: CRON_DESCRIPTION_MAX,
+            description: 'Optional one-paragraph description. Surfaces in `pugi routines list` so an operator can audit unfamiliar routines.',
+        },
+    },
+};
+/**
+ * JSON-Schema for cron_delete. Single-field shape — name only.
+ */
+export const cronDeleteJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['name'],
+    properties: {
+        name: {
+            type: 'string',
+            minLength: 1,
+            maxLength: CRON_NAME_MAX,
+            pattern: '^[a-z][a-z0-9_-]{0,63}$',
+            description: 'Routine name to delete. Idempotent: an unknown name returns ok:true with removed:false instead of erroring.',
+        },
+    },
+};
+/**
+ * JSON-Schema for cron_list. Zero-field shape — every list returns the
+ * full registry. We expose an empty `additionalProperties: false`
+ * object so the schema-aware engine knows the tool takes no input.
+ */
+export const cronListJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {},
+};
+//# sourceMappingURL=cron.js.map