@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/core/agent-progress/schema.js

@@ -0,0 +1,144 @@
+/**
+ * Agent progress JSON schema — live-progress sprint .
+ *
+ * Long-running agents (spawned externally OR via `pugi /agent`) emit a
+ * single JSON document per agent to `~/.pugi/agent-progress/<id>.json`.
+ * `pugi jobs --watch` tails the directory via chokidar and re-renders
+ * an Ink TUI that mirrors the the upstream tool `/compact` visual pattern
+ * (header with elapsed + token counter, unicode progress bar, milestone
+ * list with done/active/pending status icons).
+ *
+ * Schema is intentionally optimistic — every numeric field is clamped
+ * by the writer/reader so a malformed document degrades to a partial
+ * card instead of crashing the watcher. The `pendingCount` /
+ * `completedCount` fields are pre-computed by the agent for the
+ * "… +N pending, M completed" footer; the renderer never re-counts
+ * (the agent may have collapsed milestone history to save bytes).
+ */
+/**
+ * Validate an unknown payload as an `AgentProgress` document. Returns
+ * the typed value on success and a string error otherwise. We deliberately
+ * keep this hand-rolled (no zod) — every field is checked exactly once,
+ * the error message is human-readable, and zero runtime deps.
+ */
+export function validateAgentProgress(value) {
+    if (typeof value !== 'object' || value === null) {
+        return { ok: false, error: 'progress payload must be a JSON object' };
+    }
+    const raw = value;
+    const requiredString = (field) => {
+        const v = raw[field];
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    };
+    const agentId = requiredString('agentId');
+    if (!agentId)
+        return { ok: false, error: 'agentId required (non-empty string)' };
+    if (!/^[a-zA-Z0-9_-]+$/.test(agentId)) {
+        return { ok: false, error: 'agentId must match [a-zA-Z0-9_-]+ (filename-safe)' };
+    }
+    const agentType = requiredString('agentType');
+    if (!agentType)
+        return { ok: false, error: 'agentType required (non-empty string)' };
+    const task = requiredString('task');
+    if (!task)
+        return { ok: false, error: 'task required (non-empty string)' };
+    const startedAt = requiredString('startedAt');
+    if (!startedAt)
+        return { ok: false, error: 'startedAt required (ISO string)' };
+    if (Number.isNaN(Date.parse(startedAt))) {
+        return { ok: false, error: 'startedAt must be a parseable ISO timestamp' };
+    }
+    const lastUpdate = requiredString('lastUpdate');
+    if (!lastUpdate)
+        return { ok: false, error: 'lastUpdate required (ISO string)' };
+    if (Number.isNaN(Date.parse(lastUpdate))) {
+        return { ok: false, error: 'lastUpdate must be a parseable ISO timestamp' };
+    }
+    const elapsedMs = raw.elapsedMs;
+    if (typeof elapsedMs !== 'number' || !Number.isFinite(elapsedMs) || elapsedMs < 0) {
+        return { ok: false, error: 'elapsedMs required (non-negative number)' };
+    }
+    const percentComplete = raw.percentComplete;
+    if (typeof percentComplete !== 'number' ||
+        !Number.isFinite(percentComplete)) {
+        return { ok: false, error: 'percentComplete required (number 0..100)' };
+    }
+    const clampedPercent = Math.max(0, Math.min(100, percentComplete));
+    const status = raw.status;
+    if (status !== 'running' && status !== 'completed' && status !== 'failed') {
+        return { ok: false, error: 'status must be running | completed | failed' };
+    }
+    const currentStep = raw.currentStep;
+    if (typeof currentStep !== 'number' || currentStep < 0) {
+        return { ok: false, error: 'currentStep required (non-negative number)' };
+    }
+    const totalSteps = raw.totalSteps;
+    if (typeof totalSteps !== 'number' || totalSteps < 0) {
+        return { ok: false, error: 'totalSteps required (non-negative number)' };
+    }
+    const stepDescription = typeof raw.stepDescription === 'string'
+        ? raw.stepDescription
+        : '';
+    const milestonesRaw = raw.milestones;
+    if (!Array.isArray(milestonesRaw)) {
+        return { ok: false, error: 'milestones required (array, may be empty)' };
+    }
+    const milestones = [];
+    for (let i = 0; i < milestonesRaw.length; i += 1) {
+        const m = milestonesRaw[i];
+        if (typeof m !== 'object' || m === null) {
+            return { ok: false, error: `milestones[${i}] must be an object` };
+        }
+        const mr = m;
+        const label = typeof mr.label === 'string' ? mr.label : '';
+        if (!label) {
+            return { ok: false, error: `milestones[${i}].label required` };
+        }
+        const mStatus = mr.status;
+        if (mStatus !== 'done' && mStatus !== 'active' && mStatus !== 'pending') {
+            return {
+                ok: false,
+                error: `milestones[${i}].status must be done | active | pending`,
+            };
+        }
+        const ts = typeof mr.ts === 'string' ? mr.ts : undefined;
+        milestones.push({ label, status: mStatus, ts });
+    }
+    const tokensUsed = typeof raw.tokensUsed === 'number' && Number.isFinite(raw.tokensUsed)
+        ? Math.max(0, raw.tokensUsed)
+        : undefined;
+    const pendingCount = typeof raw.pendingCount === 'number' && Number.isFinite(raw.pendingCount)
+        ? Math.max(0, Math.floor(raw.pendingCount))
+        : undefined;
+    const completedCount = typeof raw.completedCount === 'number' && Number.isFinite(raw.completedCount)
+        ? Math.max(0, Math.floor(raw.completedCount))
+        : undefined;
+    return {
+        ok: true,
+        value: {
+            agentId,
+            agentType,
+            task,
+            startedAt,
+            lastUpdate,
+            elapsedMs,
+            tokensUsed,
+            percentComplete: clampedPercent,
+            status,
+            currentStep,
+            totalSteps,
+            stepDescription,
+            milestones,
+            pendingCount,
+            completedCount,
+        },
+    };
+}
+/**
+ * Default directory the writer and watcher share. Lives under the
+ * project workspace by convention so worktree-isolated agents can emit
+ * progress without crossing tenant boundaries. Operators can override
+ * via `PUGI_AGENT_PROGRESS_DIR` env var.
+ */
+export const DEFAULT_AGENT_PROGRESS_DIRNAME = '.pugi/agent-progress';
+//# sourceMappingURL=schema.js.map

package/dist/core/agent-progress/writer.js

@@ -0,0 +1,101 @@
+/**
+ * Agent progress writer — atomic file ops so the chokidar watcher
+ * never reads a half-written JSON document.
+ *
+ * Pattern (POSIX-portable):
+ *  1. Build the canonical JSON body.
+ *  2. Write to `<dir>/<agentId>.json.tmp-<pid>-<seq>`.
+ *  3. Rename (atomic on the same filesystem) to `<dir>/<agentId>.json`.
+ *  4. Cleanup is a no-op on success; on failure the caller bubbles the
+ *     error and the .tmp file is removed best-effort.
+ *
+ * The auto-cleanup of completed entries lives in `cleanup.ts` (commit 4);
+ * the writer here is the minimal surface the agent prompt boilerplate
+ * needs to copy + paste.
+ */
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { DEFAULT_AGENT_PROGRESS_DIRNAME, validateAgentProgress, } from './schema.js';
+let writeSequence = 0;
+/**
+ * Resolve the effective progress directory. Public so the watcher can
+ * share the same resolution rules without duplicating env-var logic.
+ */
+export function resolveProgressDir(override) {
+    const candidate = override
+        ?? process.env.PUGI_AGENT_PROGRESS_DIR
+        ?? join(process.cwd(), DEFAULT_AGENT_PROGRESS_DIRNAME);
+    if (candidate.startsWith('~/')) {
+        return join(homedir(), candidate.slice(2));
+    }
+    return resolve(candidate);
+}
+/**
+ * Write a progress document atomically.
+ *
+ * Throws on validation failure so the caller is loud about a schema
+ * regression. File-system errors propagate untouched.
+ */
+export function writeProgress(progress, options = {}) {
+    const validation = validateAgentProgress(progress);
+    if (!validation.ok) {
+        throw new Error(`invalid agent-progress payload: ${validation.error}`);
+    }
+    const dir = resolveProgressDir(options.dir);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const finalPath = join(dir, `${progress.agentId}.json`);
+    writeSequence += 1;
+    const tmpPath = `${finalPath}.tmp-${process.pid}-${writeSequence}`;
+    const body = `${JSON.stringify(progress, null, 2)}\n`;
+    try {
+        // mkdirSync above may have created `dir`, but a parallel agent could
+        // delete it between the existsSync and writeFile — ensure the parent
+        // of the tmp file exists right before the write.
+        const parent = dirname(tmpPath);
+        if (!existsSync(parent)) {
+            mkdirSync(parent, { recursive: true });
+        }
+        writeFileSync(tmpPath, body, 'utf8');
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup; surface the original error
+        }
+        throw err;
+    }
+    return { path: finalPath };
+}
+/**
+ * Build a fresh progress document with sensible defaults. Mostly a
+ * convenience for tests + the agent prompt boilerplate — the writer
+ * does NOT call this implicitly because agents have richer context
+ * about their own milestone state.
+ */
+export function makeInitialProgress(input) {
+    const now = input.now ?? Date.now;
+    const iso = new Date(now()).toISOString();
+    return {
+        agentId: input.agentId,
+        agentType: input.agentType,
+        task: input.task,
+        startedAt: iso,
+        lastUpdate: iso,
+        elapsedMs: 0,
+        percentComplete: 0,
+        status: 'running',
+        currentStep: 0,
+        totalSteps: Math.max(0, Math.floor(input.totalSteps)),
+        stepDescription: '',
+        milestones: input.milestones ?? [],
+        pendingCount: input.milestones?.filter((m) => m.status === 'pending').length,
+        completedCount: input.milestones?.filter((m) => m.status === 'done').length,
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/core/agents/adaptive-router.js

@@ -0,0 +1,330 @@
+/**
+ * Adaptive router — primitive #4 of the 9-layer RAG architecture gap
+ * analysis (docs/research/2026-05-31-9-layer-rag-architecture-.md).
+ *
+ * Picks the best source (RAG workspace / web fetch / code-intel / cache
+ * tier / agent persona / tool) for a given query by asking an LLM to
+ * rank candidates from a caller-supplied catalog. The router is pure
+ * logic — it never opens a network connection itself. The caller
+ * injects a `transport` callback that maps a prompt string to a model
+ * response string, which keeps Anvil-engine wiring (Hiroshi persona,
+ * auth, retry, telemetry) out of the primitive and makes tests
+ * deterministic.
+ *
+ * Failure model is fail-closed to a heuristic pick. Every malformed
+ * response, transport throw, schema violation, empty catalog, or
+ * unknown source id collapses to a deterministic ranking based on
+ * `kind` priority (cache > agent > everything-else, in catalog order).
+ * The caller inspects `usedFallback` plus `reason` and decides whether
+ * the degradation is acceptable for the active route. Routing is never
+ * load-bearing for correctness — the caller can always fall back to a
+ * monolithic default source.
+ *
+ * Composition with sibling primitives:
+ *  - #3 query-decomposer feeds an ordered SubQuery list. The engine
+ *    consumer will call `chooseRoute` once per SubQuery to pick the
+ *    per-step source. That binding lives in the engine wire-up PR, not
+ *    here.
+ *  - #5 pre-flight token estimator may pre-set `tierBudget` to gate
+ *    out 'expensive' sources before the LLM call is made.
+ *
+ * Out of scope (separate PRs):
+ *  - Engine wire-up that binds Hiroshi persona to `transport`.
+ *  - Source-catalog registry — caller supplies the catalog per call.
+ *  - Per-source cost telemetry (separate follow-up).
+ *  - Streaming partial-ranks during LLM emission.
+ */
+import { estimateTokens } from '../compact/token-counter.js';
+/** Whitelisted source kinds. New kinds require a corresponding catalog migration. */
+const SOURCE_KIND_VALUES = ['rag', 'web', 'code', 'cache', 'agent', 'tool'];
+const DEFAULT_MAX_FALLBACKS = 3;
+const DEFAULT_MAX_INPUT_TOKENS = 4000;
+/** Hard upper bound on pickIds we accept from the LLM. 1 primary + 3 fallbacks. */
+const HARD_MAX_PICKS = 4;
+/** Trim the user query before substitution. Keeps router prompt within sane bounds. */
+const PROMPT_QUERY_HARD_CAP_CHARS = 2000;
+/**
+ * Prompt template embedded as a constant so the primitive has zero
+ * filesystem dependencies. The `{contextHint}`, `{query}`, and
+ * `{candidates}` markers are substituted at call time. The instruction
+ * explicitly forbids markdown fences and prose around the JSON, which
+ * trims the most common parse failures observed with mid-tier models.
+ */
+export const ADAPTIVE_ROUTER_PROMPT_TEMPLATE = [
+    'You are an adaptive router for a software-engineering AI assistant.',
+    "Pick the best source(s) from the candidate list to answer the user's query.",
+    '',
+    'Return JSON only matching this schema:',
+    '{ "pickIds": ["source-id-1", "source-id-2", ...], "confidence": 0.85, "reasoning": "..." }',
+    '',
+    'Rules:',
+    '- Order pickIds best to worst (first = primary).',
+    '- Max 4 ids total (1 primary + up to 3 fallbacks).',
+    '- confidence in [0, 1].',
+    '- reasoning is one sentence under 200 chars.',
+    '- No prose around JSON. No markdown fences.',
+    '',
+    'CONTEXT: {contextHint}',
+    'QUERY: {query}',
+    '',
+    'CANDIDATES:',
+    '{candidates}',
+].join('\n');
+/**
+ * Pick the best source(s) for a query. Never throws.
+ *
+ * Every internal failure mode collapses to a heuristic fallback that
+ * still produces a usable `RouteDecision`. Caller inspects
+ * `usedFallback` and `reason` to decide whether to surface a warning or
+ * treat the routing as opaque.
+ */
+export async function chooseRoute(opts) {
+    const filtered = filterCatalog(opts.catalog, opts.tierBudget);
+    const maxFallbacks = clampMaxFallbacks(opts.maxFallbacks);
+    const maxInputTokens = clampMaxInputTokens(opts.maxInputTokens);
+    if (filtered.length === 0) {
+        return emptyCatalogFallback();
+    }
+    if (filtered.length === 1) {
+        // Single available source — no need to round-trip through the LLM.
+        const only = filtered[0];
+        if (!only)
+            return emptyCatalogFallback();
+        return {
+            primary: only,
+            fallbacks: [],
+            confidence: 1,
+            usedFallback: false,
+        };
+    }
+    const safeQuery = truncateToTokenBudget(opts.query.trim(), maxInputTokens);
+    const prompt = buildPrompt(safeQuery, opts.contextHint ?? 'unknown', filtered);
+    let raw;
+    try {
+        raw = await opts.transport(prompt);
+    }
+    catch {
+        return heuristicFallback(filtered, maxFallbacks, 'transport-error');
+    }
+    const parsed = parseAndValidate(raw, filtered);
+    if (!parsed.ok) {
+        return heuristicFallback(filtered, maxFallbacks, parsed.reason);
+    }
+    const ranked = parsed.sources;
+    const first = ranked[0];
+    if (!first) {
+        return heuristicFallback(filtered, maxFallbacks, 'empty-pick-ids');
+    }
+    const fallbacks = ranked.slice(1, 1 + maxFallbacks);
+    return {
+        primary: first,
+        fallbacks,
+        confidence: clampConfidence(parsed.confidence),
+        reasoning: parsed.reasoning,
+        usedFallback: false,
+    };
+}
+// -----------------------------------------------------------------------
+// Internals
+// -----------------------------------------------------------------------
+function filterCatalog(catalog, tierBudget) {
+    const out = [];
+    for (const source of catalog) {
+        if (!source.available)
+            continue;
+        if (tierBudget === 'cheap' && source.costHint === 'expensive')
+            continue;
+        out.push(source);
+    }
+    return out;
+}
+function buildPrompt(query, contextHint, sources) {
+    const trimmedQuery = query.length > PROMPT_QUERY_HARD_CAP_CHARS
+        ? query.slice(0, PROMPT_QUERY_HARD_CAP_CHARS)
+        : query;
+    const candidateLines = sources
+        .map((s) => `- ${s.id} (${s.kind}, ${s.costHint}, ${s.latencyHint}): ${s.description}`)
+        .join('\n');
+    return ADAPTIVE_ROUTER_PROMPT_TEMPLATE
+        .replace('{contextHint}', contextHint)
+        .replace('{query}', trimmedQuery)
+        .replace('{candidates}', candidateLines);
+}
+function parseAndValidate(raw, catalog) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripFences(raw));
+    }
+    catch {
+        return { ok: false, reason: 'parse-failed' };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: false, reason: 'schema-violation' };
+    }
+    const pickIdsRaw = parsed.pickIds;
+    if (!Array.isArray(pickIdsRaw)) {
+        return { ok: false, reason: 'schema-violation' };
+    }
+    if (pickIdsRaw.length === 0) {
+        return { ok: false, reason: 'empty-pick-ids' };
+    }
+    const byId = new Map(catalog.map((s) => [s.id, s]));
+    const seen = new Set();
+    const resolved = [];
+    for (const candidate of pickIdsRaw) {
+        if (typeof candidate !== 'string') {
+            return { ok: false, reason: 'schema-violation' };
+        }
+        if (seen.has(candidate)) {
+            return { ok: false, reason: 'duplicate-pick-id' };
+        }
+        const source = byId.get(candidate);
+        if (!source) {
+            return { ok: false, reason: 'unknown-source-id' };
+        }
+        seen.add(candidate);
+        resolved.push(source);
+        // Cap at the hard ceiling so a malicious / runaway LLM cannot make us allocate unbounded fallbacks.
+        if (resolved.length >= HARD_MAX_PICKS)
+            break;
+    }
+    const confidenceRaw = parsed.confidence;
+    // Confidence is intentionally lenient — we coerce non-numbers to 0.5
+    // and clamp the rest. Out-of-range is NOT a fallback trigger per the
+    // spec: pickIds is the load-bearing field.
+    const confidence = typeof confidenceRaw === 'number' && Number.isFinite(confidenceRaw)
+        ? confidenceRaw
+        : 0.5;
+    const reasoningRaw = parsed.reasoning;
+    const reasoning = typeof reasoningRaw === 'string' && reasoningRaw.trim().length > 0
+        ? reasoningRaw.trim()
+        : undefined;
+    return {
+        ok: true,
+        sources: resolved,
+        confidence,
+        ...(reasoning !== undefined ? { reasoning } : {}),
+    };
+}
+/**
+ * Heuristic ranking applied when the LLM call fails. Priority order:
+ *
+ *  1. `kind === 'cache'` first (always cheapest and safe to try).
+ *  2. `kind === 'agent'` next (persona has its own routing intelligence).
+ *  3. Everything else in the catalog's natural order.
+ *
+ * Within each bucket the catalog's natural order acts as a stable
+ * tiebreaker — the caller controls the priority by ordering the
+ * catalog deliberately.
+ */
+function heuristicFallback(catalog, maxFallbacks, reason) {
+    const ranked = heuristicRank(catalog);
+    const first = ranked[0];
+    // Defensive: caller guarantees catalog.length >= 1 by the time we
+    // get here (the `filtered.length === 0` short-circuit runs upstream),
+    // but the type checker needs the guard.
+    if (!first)
+        return emptyCatalogFallback();
+    const fallbacks = ranked.slice(1, 1 + maxFallbacks);
+    return {
+        primary: first,
+        fallbacks,
+        confidence: 0,
+        usedFallback: true,
+        reason,
+    };
+}
+function heuristicRank(catalog) {
+    const cache = [];
+    const agents = [];
+    const rest = [];
+    for (const source of catalog) {
+        if (source.kind === 'cache')
+            cache.push(source);
+        else if (source.kind === 'agent')
+            agents.push(source);
+        else
+            rest.push(source);
+    }
+    return [...cache, ...agents, ...rest];
+}
+/**
+ * Synthetic fallback used only when the filtered catalog is empty.
+ * The caller MUST treat `usedFallback === true` as a signal to skip
+ * the routed step — the `primary` here is a placeholder so the return
+ * type stays non-nullable.
+ */
+function emptyCatalogFallback() {
+    return {
+        primary: {
+            id: 'unknown',
+            kind: 'tool',
+            description: 'No source available for this query.',
+            costHint: 'cheap',
+            latencyHint: 'sub-second',
+            available: false,
+        },
+        fallbacks: [],
+        confidence: 0,
+        usedFallback: true,
+        reason: 'empty-catalog',
+    };
+}
+function clampMaxFallbacks(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        return DEFAULT_MAX_FALLBACKS;
+    }
+    return Math.floor(value);
+}
+function clampMaxInputTokens(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+        return DEFAULT_MAX_INPUT_TOKENS;
+    }
+    return Math.floor(value);
+}
+function clampConfidence(value) {
+    if (!Number.isFinite(value))
+        return 0.5;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+/**
+ * Truncate input to the token budget using the existing chars/4
+ * heuristic. We slice by characters proportional to the budget rather
+ * than binary-searching `estimateTokens`, because the heuristic is
+ * monotonic in length and an over-shoot is acceptable — the prompt also
+ * carries the static template overhead.
+ */
+function truncateToTokenBudget(text, maxTokens) {
+    const current = estimateTokens(text);
+    if (current <= maxTokens)
+        return text;
+    const ratio = maxTokens / current;
+    const targetLength = Math.max(1, Math.floor(text.length * ratio));
+    return text.slice(0, targetLength);
+}
+/**
+ * Tolerate the most common mid-tier-model deviation: wrapping JSON in
+ * a fenced code block. We strip a single leading and trailing fence
+ * marker when both are present; otherwise the raw text is returned
+ * unchanged and `JSON.parse` will reject it through the normal path.
+ */
+function stripFences(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('```'))
+        return trimmed;
+    const firstNewline = trimmed.indexOf('\n');
+    if (firstNewline < 0)
+        return trimmed;
+    const closing = trimmed.lastIndexOf('```');
+    if (closing <= firstNewline)
+        return trimmed;
+    return trimmed.slice(firstNewline + 1, closing).trim();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=adaptive-router.js.map