@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

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

@@ -1,330 +0,0 @@
-/**
- * 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

package/dist/core/agents/loader.js

@@ -1,104 +0,0 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { assertValidSlug, parseSkillMarkdown } from '../skills/loader.js';
-export function globalAgentsDir() {
-    const home = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
-    return join(home, 'agents');
-}
-export function workspaceAgentsDir(workspaceRoot) {
-    return join(workspaceRoot, '.pugi', 'agents');
-}
-export function globalAgentPath(slug) {
-    assertValidSlug(slug, 'agent');
-    return join(globalAgentsDir(), `${slug}.md`);
-}
-export function workspaceAgentPath(workspaceRoot, slug) {
-    assertValidSlug(slug, 'agent');
-    return join(workspaceAgentsDir(workspaceRoot), `${slug}.md`);
-}
-export function listAgents(scope, workspaceRoot) {
-    const dir = scope === 'global' ? globalAgentsDir() : workspaceAgentsDir(workspaceRoot);
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir)
-        .filter((name) => name.endsWith('.md'))
-        .sort((a, b) => a.localeCompare(b))
-        .map((name) => loadAgent(join(dir, name), scope))
-        .filter((agent) => agent !== null);
-}
-function loadAgent(filePath, scope) {
-    try {
-        const source = readFileSync(filePath, 'utf8');
-        const parsed = parseSkillMarkdown(source);
-        // Files under `<scope>/.pugi/agents/` are agents by construction;
-        // the loader override here forces metadata.type=agent even when the
-        // upstream frontmatter (e.g. Anthropic flat dialect) omitted the
-        // declaration. We never mis-categorise a `<dir>/.pugi/agents/foo.md`
-        // file as a skill.
-        if (parsed.frontmatter.metadata.type !== 'agent' &&
-            parsed.frontmatter.metadata.type !== 'skill') {
-            return null;
-        }
-        const slug = filePath.split('/').pop()?.replace(/\.md$/, '') ?? parsed.frontmatter.name;
-        // Filenames on disk are produced by installAgent (which validates)
-        // OR placed manually by the operator. Validate before exposing the
-        // slug to the rest of the system so trust keys + log lines never
-        // carry a hostile string.
-        assertValidSlug(slug, 'agent');
-        const frontmatter = {
-            ...parsed.frontmatter,
-            metadata: { ...parsed.frontmatter.metadata, type: 'agent' },
-        };
-        return {
-            slug,
-            scope,
-            filePath,
-            frontmatter,
-            body: parsed.body,
-            source,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-export function installAgent(input) {
-    // Fail-closed before any filesystem mutation. assertValidSlug also
-    // runs inside globalAgentPath/workspaceAgentPath but we surface it
-    // explicitly here so the error fires before mkdirSync.
-    assertValidSlug(input.slug, 'agent');
-    const target = input.scope === 'global'
-        ? globalAgentPath(input.slug)
-        : workspaceAgentPath(input.workspaceRoot, input.slug);
-    mkdirSync(dirname(target), { recursive: true });
-    const srcFile = pickAgentFile(input.payloadDir);
-    writeFileSync(target, readFileSync(srcFile), { mode: 0o600 });
-    return target;
-}
-function pickAgentFile(payloadDir) {
-    const stat = statSync(payloadDir);
-    if (stat.isFile())
-        return payloadDir;
-    const entries = readdirSync(payloadDir).filter((name) => name.toLowerCase().endsWith('.md'));
-    if (entries.length === 0) {
-        throw new Error('AGENT_INSTALL: payload directory contains no .md file');
-    }
-    if (entries.length > 1) {
-        throw new Error(`AGENT_INSTALL: payload directory contains ${entries.length} .md files (expected exactly 1)`);
-    }
-    const first = entries[0];
-    if (!first) {
-        throw new Error('AGENT_INSTALL: payload directory contains no .md file');
-    }
-    return join(payloadDir, first);
-}
-export function removeAgent(slug, scope, workspaceRoot) {
-    assertValidSlug(slug, 'agent');
-    const target = scope === 'global' ? globalAgentPath(slug) : workspaceAgentPath(workspaceRoot, slug);
-    if (!existsSync(target))
-        return false;
-    rmSync(target, { force: true });
-    return true;
-}
-//# sourceMappingURL=loader.js.map