@pugi/cli 0.1.0-alpha.10

package/dist/runtime/commands/agents.js

@@ -0,0 +1,385 @@
+import { createInterface } from 'node:readline/promises';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { stdin as input, stdout as output } from 'node:process';
+import { globalAgentPath, installAgent, listAgents, removeAgent, workspaceAgentPath, } from '../../core/agents/loader.js';
+import { assertValidSlug, parseSkillMarkdown } from '../../core/skills/loader.js';
+import { cleanupTmp, fetchSource } from '../../core/skills/sources.js';
+import { hashAgentFile, recordTrust, revokeTrust, verifyTrust, } from '../../core/skills/trust.js';
+const USAGE = [
+    'Usage:',
+    '  pugi agents list [--global|--workspace]            Show installed agents.',
+    '  pugi agents install <source> [--global|--workspace] [--yes] [--as <slug>]',
+    '                                                     Fetch + trust-prompt + activate an agent.',
+    '  pugi agents info <slug>                            Show metadata + body preview.',
+    '  pugi agents remove <slug> [--global|--workspace]   Delete an installed agent.',
+    '',
+    'Source forms accepted by `install` (same as `pugi skills install`):',
+    '  gh:owner/repo/path/to/agent.md[@ref]',
+    '  https://github.com/...',
+    '  anthropic:<slug>',
+    '  npm:<package>',
+    '  ./path/to/agent.md  or  /abs/path/to/agent.md',
+    '  <slug>                         Catalog lookup (catalog.pugi.dev).',
+].join('\n');
+export async function runAgentsCommand(args, ctx) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        ctx.writeOutput({ command: 'agents', usage: USAGE.split('\n') }, USAGE);
+        return;
+    }
+    switch (sub) {
+        case 'list':
+            return runAgentsList(args.slice(1), ctx);
+        case 'install':
+            return runAgentsInstall(args.slice(1), ctx);
+        case 'info':
+            return runAgentsInfo(args.slice(1), ctx);
+        case 'remove':
+            return runAgentsRemove(args.slice(1), ctx);
+        default:
+            throw new Error(`Unknown sub-command "pugi agents ${sub}". Expected list, install, info, or remove.`);
+    }
+}
+function parseFlags(args) {
+    let scope = 'both';
+    let yes = false;
+    let asName;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--global')
+            scope = 'global';
+        else if (arg === '--workspace')
+            scope = 'workspace';
+        else if (arg === '--yes' || arg === '-y')
+            yes = true;
+        else if (arg === '--as') {
+            asName = args[++i];
+        }
+        else if (arg && !arg.startsWith('--')) {
+            positional.push(arg);
+        }
+        else if (arg) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+    }
+    return { scope, yes, asName, positional };
+}
+async function runAgentsList(args, ctx) {
+    const flags = parseFlags(args);
+    const includeGlobal = flags.scope === 'global' || flags.scope === 'both';
+    const includeWorkspace = flags.scope === 'workspace' || flags.scope === 'both';
+    const global = includeGlobal ? listAgents('global', ctx.workspaceRoot) : [];
+    const workspace = includeWorkspace ? listAgents('workspace', ctx.workspaceRoot) : [];
+    const all = [...global, ...workspace];
+    const verdicts = await Promise.all(all.map(async (agent) => {
+        const actual = hashAgentFile(agent.filePath);
+        const verdict = await verifyTrust('agent', agent.scope, agent.slug, actual);
+        return { agent, trust: verdict };
+    }));
+    if (ctx.json) {
+        ctx.writeOutput({
+            command: 'agents.list',
+            agents: verdicts.map(({ agent, trust }) => ({
+                slug: agent.slug,
+                scope: agent.scope,
+                filePath: agent.filePath,
+                description: agent.frontmatter.description,
+                model: agent.frontmatter.metadata.model ?? null,
+                tools: agent.frontmatter.metadata.tools ?? [],
+                trust: trust.status,
+            })),
+        }, '');
+        return;
+    }
+    if (verdicts.length === 0) {
+        ctx.writeOutput({ command: 'agents.list', agents: [] }, 'No agents installed. Try `pugi agents install gh:anthropics/claude-code-agents/code-reviewer.md@main`.');
+        return;
+    }
+    const lines = ['Installed agents:'];
+    for (const { agent, trust } of verdicts) {
+        const model = agent.frontmatter.metadata.model ? ` model=${String(agent.frontmatter.metadata.model)}` : '';
+        const trustMark = trust.status === 'trusted' ? '[trusted]' : trust.status === 'unsigned' ? '[unsigned]' : '[mismatch]';
+        lines.push(`  ${agent.slug.padEnd(28)} ${agent.scope.padEnd(10)} ${trustMark.padEnd(11)}${model}`);
+        lines.push(`    ${truncate(agent.frontmatter.description, 80)}`);
+    }
+    ctx.writeOutput({ command: 'agents.list', agents: verdicts }, lines.join('\n'));
+}
+async function runAgentsInstall(args, ctx) {
+    const flags = parseFlags(args);
+    const source = flags.positional[0];
+    if (!source) {
+        throw new Error('pugi agents install requires a <source> argument. See `pugi agents --help`.');
+    }
+    const scope = flags.scope === 'workspace' ? 'workspace' : 'global';
+    let fetched;
+    try {
+        fetched = await fetchSource(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.writeOutput({ command: 'agents.install', status: 'fetch_failed', source, error: message }, `Agent fetch failed: ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Pick the .md file inside the payload. fetchSource for local single
+    // files already wrote into a tmp dir; for gh: we need to look for the
+    // .md inside the payload root (one-file convention).
+    const stat = statSync(fetched.tmpDir);
+    let agentFile;
+    if (stat.isFile()) {
+        agentFile = fetched.tmpDir;
+    }
+    else {
+        const candidates = readdirSync(fetched.tmpDir).filter((name) => name.toLowerCase().endsWith('.md'));
+        if (candidates.length === 0) {
+            cleanupTmp(fetched.tmpDir);
+            ctx.writeOutput({ command: 'agents.install', status: 'no_markdown', source }, `Agent fetch from ${source} contains no .md file at root.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (candidates.length > 1) {
+            cleanupTmp(fetched.tmpDir);
+            ctx.writeOutput({ command: 'agents.install', status: 'ambiguous', source, candidates }, `Agent fetch from ${source} contains ${candidates.length} .md files. Specify one with a subdir path.`);
+            process.exitCode = 1;
+            return;
+        }
+        const first = candidates[0];
+        if (!first) {
+            cleanupTmp(fetched.tmpDir);
+            process.exitCode = 1;
+            return;
+        }
+        agentFile = join(fetched.tmpDir, first);
+    }
+    let parsed;
+    try {
+        parsed = parseSkillMarkdown(readFileSync(agentFile, 'utf8'));
+    }
+    catch (error) {
+        cleanupTmp(fetched.tmpDir);
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.writeOutput({ command: 'agents.install', status: 'parse_failed', source, error: message }, `Agent parse failed: ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Agents are single-file. If the frontmatter declares "skill" (Pugi
+    // native dialect) the operator picked the wrong command; refuse and
+    // hint. If the frontmatter omits type entirely (Anthropic flat
+    // dialect), the loader defaulted to "skill" — we override to "agent"
+    // since the operator explicitly chose `pugi agents install`. The
+    // single-file storage convention is the disambiguator.
+    if (parsed.frontmatter.metadata.type === 'skill' &&
+        Object.prototype.hasOwnProperty.call(parsed.frontmatter, 'metadata')) {
+        // Did the source explicitly declare type=skill? We detect via the
+        // raw frontmatter — when the type was inferred (no metadata block),
+        // we permit the install.
+        const sourceHasExplicitMetadata = /^metadata:\s*$/m.test(parsed.source);
+        if (sourceHasExplicitMetadata) {
+            cleanupTmp(fetched.tmpDir);
+            ctx.writeOutput({ command: 'agents.install', status: 'wrong_kind', source, declaredType: 'skill' }, `Source ${source} declares metadata.type="skill", not "agent". Use \`pugi skills install\` for skills.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const slug = flags.asName ?? parsed.frontmatter.name;
+    // Fail-fast before trust prompt + FS write: a hostile `--as` flag or
+    // hostile frontmatter `name` must never reach path.join.
+    try {
+        assertValidSlug(slug, 'agent');
+    }
+    catch (error) {
+        cleanupTmp(fetched.tmpDir);
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.writeOutput({ command: 'agents.install', status: 'invalid_slug', source, slug, error: message }, message);
+        process.exitCode = 1;
+        return;
+    }
+    const sha256 = hashAgentFile(agentFile);
+    const targetPath = scope === 'global' ? globalAgentPath(slug) : workspaceAgentPath(ctx.workspaceRoot, slug);
+    const summary = {
+        name: slug,
+        description: parsed.frontmatter.description,
+        version: parsed.frontmatter.metadata.version
+            ? String(parsed.frontmatter.metadata.version)
+            : null,
+        tools: (parsed.frontmatter.metadata.tools ?? []),
+        files: 1,
+        source: fetched.sourceUrl,
+        targetDir: targetPath,
+        sha256,
+    };
+    if (!flags.yes) {
+        const decision = await promptTrust('agent', summary, parsed.body);
+        if (decision === 'no') {
+            cleanupTmp(fetched.tmpDir);
+            ctx.writeOutput({ command: 'agents.install', status: 'declined', source, slug }, 'Install declined. Nothing changed.');
+            return;
+        }
+    }
+    installAgent({
+        payloadDir: agentFile,
+        slug,
+        scope,
+        workspaceRoot: ctx.workspaceRoot,
+    });
+    await recordTrust({
+        kind: 'agent',
+        scope,
+        name: slug,
+        sha256,
+        source: fetched.sourceUrl,
+        signedBy: signerIdentity(),
+    });
+    cleanupTmp(fetched.tmpDir);
+    ctx.writeOutput({
+        command: 'agents.install',
+        status: 'installed',
+        slug,
+        scope,
+        path: targetPath,
+        sha256,
+        source: fetched.sourceUrl,
+    }, [
+        `Installed agent "${slug}" (${scope}).`,
+        `  Path:    ${targetPath}`,
+        `  Source:  ${fetched.sourceUrl}`,
+        `  sha256:  ${sha256}`,
+    ].join('\n'));
+}
+async function runAgentsInfo(args, ctx) {
+    const flags = parseFlags(args);
+    const slug = flags.positional[0];
+    if (!slug) {
+        throw new Error('pugi agents info requires a <slug> argument.');
+    }
+    const matches = findAgent(slug, flags.scope, ctx.workspaceRoot);
+    if (matches.length === 0) {
+        ctx.writeOutput({ command: 'agents.info', status: 'not_found', slug }, `No agent "${slug}" installed. Try \`pugi agents list\`.`);
+        process.exitCode = 1;
+        return;
+    }
+    const agent = matches[0];
+    if (!agent) {
+        process.exitCode = 1;
+        return;
+    }
+    const actualSha = hashAgentFile(agent.filePath);
+    const trust = await verifyTrust('agent', agent.scope, agent.slug, actualSha);
+    const preview = agent.body.slice(0, 800);
+    const lines = [
+        `Agent: ${agent.slug}`,
+        `  Scope:        ${agent.scope}`,
+        `  Path:         ${agent.filePath}`,
+        `  Description:  ${agent.frontmatter.description}`,
+        `  Model:        ${String(agent.frontmatter.metadata.model ?? '(default)')}`,
+        `  Tools:        ${(agent.frontmatter.metadata.tools ?? []).join(', ') || '(none)'}`,
+        `  Trust:        ${trust.status}`,
+        `  sha256:       ${actualSha}`,
+        '',
+        'Body preview:',
+        preview,
+        agent.body.length > 800 ? `... (${agent.body.length - 800} more chars)` : '',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+    ctx.writeOutput({
+        command: 'agents.info',
+        slug: agent.slug,
+        scope: agent.scope,
+        filePath: agent.filePath,
+        frontmatter: agent.frontmatter,
+        sha256: actualSha,
+        trust,
+        bodyPreview: preview,
+        bodyLength: agent.body.length,
+    }, lines);
+}
+async function runAgentsRemove(args, ctx) {
+    const flags = parseFlags(args);
+    const slug = flags.positional[0];
+    if (!slug) {
+        throw new Error('pugi agents remove requires a <slug> argument.');
+    }
+    const matches = findAgent(slug, flags.scope, ctx.workspaceRoot);
+    if (matches.length === 0) {
+        ctx.writeOutput({ command: 'agents.remove', status: 'not_found', slug }, `No agent "${slug}" installed.`);
+        process.exitCode = 1;
+        return;
+    }
+    for (const agent of matches) {
+        removeAgent(agent.slug, agent.scope, ctx.workspaceRoot);
+        await revokeTrust('agent', agent.scope, agent.slug);
+    }
+    ctx.writeOutput({
+        command: 'agents.remove',
+        status: 'removed',
+        slug,
+        removed: matches.map((m) => ({ slug: m.slug, scope: m.scope, filePath: m.filePath })),
+    }, `Removed ${matches.length} agent install(s) named "${slug}".`);
+}
+/* ----------------------------- shared helpers ----------------------------- */
+function findAgent(slug, scope, workspaceRoot) {
+    const scopes = scope === 'both' ? ['global', 'workspace'] : [scope];
+    const out = [];
+    for (const s of scopes) {
+        const all = listAgents(s, workspaceRoot);
+        for (const agent of all) {
+            if (agent.slug === slug)
+                out.push(agent);
+        }
+    }
+    return out;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+function signerIdentity() {
+    return (process.env.PUGI_TRUSTED_BY?.trim() ||
+        process.env.USER?.trim() ||
+        process.env.USERNAME?.trim() ||
+        'cli');
+}
+async function promptTrust(kind, summary, body) {
+    const banner = [
+        '',
+        `About to install ${kind} "${summary.name}"`,
+        `  Description:  ${summary.description}`,
+        `  Version:      ${summary.version ?? '(unset)'}`,
+        `  Tools:        ${summary.tools.join(', ') || '(none)'}`,
+        `  Files:        ${summary.files}`,
+        `  Source:       ${summary.source}`,
+        `  Target:       ${summary.targetDir}`,
+        `  sha256:       ${summary.sha256}`,
+        '',
+        'This payload becomes part of the system prompt and may influence agent decisions.',
+        'Trust this install? [y/N/info] ',
+    ].join('\n');
+    process.stdout.write(banner);
+    if (!input.isTTY) {
+        process.stdout.write('\n(non-interactive stdin; declining install)\n');
+        return 'no';
+    }
+    const rl = createInterface({ input, output });
+    try {
+        while (true) {
+            const answer = (await rl.question('')).trim().toLowerCase();
+            if (answer === 'y' || answer === 'yes')
+                return 'yes';
+            if (answer === 'info') {
+                process.stdout.write('\n');
+                process.stdout.write(body);
+                process.stdout.write('\n\nTrust this install? [y/N] ');
+                continue;
+            }
+            return 'no';
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/runtime/commands/budget.js

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const RATE_INPUT_USD_PER_TOKEN = 0.000003;
+const RATE_OUTPUT_USD_PER_TOKEN = 0.000015;
+export async function runBudgetCommand(args, ctx) {
+    const flags = parseFlags(args);
+    const eventsPath = resolve(ctx.workspaceRoot, '.pugi/events.jsonl');
+    if (!existsSync(eventsPath)) {
+        ctx.writeOutput({
+            command: 'budget',
+            status: 'noop',
+            reason: 'no_session',
+            tokens: 0,
+            dollars: 0,
+        }, 'No session events found. Run a Pugi command first.');
+        return;
+    }
+    const events = readEvents(eventsPath);
+    const cutoff = flags.sinceMs === null ? 0 : Date.now() - flags.sinceMs;
+    const summary = summarise(events, cutoff);
+    const dollars = estimateDollars(summary.tokens);
+    const payload = {
+        command: 'budget',
+        status: 'ok',
+        workspaceRoot: ctx.workspaceRoot,
+        window: flags.sinceMs === null ? 'session' : `last ${args.find((a) => a.startsWith('--since='))?.slice('--since='.length) ?? ''}`,
+        tokens: summary.tokens,
+        dollars,
+        perCommand: summary.perCommand,
+        perPersona: summary.perPersona,
+        rate: {
+            inputUsdPerToken: RATE_INPUT_USD_PER_TOKEN,
+            outputUsdPerToken: RATE_OUTPUT_USD_PER_TOKEN,
+            assumedSplit: 'event log does not break tokens into in/out; rate uses output-token assumption',
+        },
+    };
+    const text = [
+        'Pugi budget',
+        `Window: ${payload.window}`,
+        `Tokens: ${summary.tokens}`,
+        `Estimated cost: $${dollars.toFixed(4)} (output-token rate)`,
+        summary.perCommand.length > 0
+            ? `Per command:\n${summary.perCommand
+                .map((entry) => `  ${entry.command.padEnd(12)} ${entry.tokens} tokens`)
+                .join('\n')}`
+            : 'Per command: (no entries)',
+        summary.perPersona.length > 0
+            ? `Per persona:\n${summary.perPersona
+                .map((entry) => `  ${entry.persona.padEnd(20)} ${entry.tokens} tokens`)
+                .join('\n')}`
+            : 'Per persona: (no entries)',
+    ].join('\n');
+    ctx.writeOutput(payload, text);
+}
+function summarise(events, cutoffMs) {
+    let tokens = 0;
+    const perCommand = new Map();
+    const perPersona = new Map();
+    // Track the active command via command_started / command_completed
+    // bookends so we can attribute tool_result tokens to the surrounding
+    // command. Multiple commands per session are normal.
+    let activeCommand = null;
+    for (const event of events) {
+        if (!matchesWindow(event, cutoffMs))
+            continue;
+        if (event.type === 'session' && event.name === 'command_started' && typeof event.command === 'string') {
+            activeCommand = event.command;
+            continue;
+        }
+        if (event.type === 'session' && event.name === 'command_completed') {
+            activeCommand = null;
+            continue;
+        }
+        const eventTokens = extractTokens(event);
+        if (eventTokens > 0) {
+            tokens += eventTokens;
+            if (activeCommand) {
+                perCommand.set(activeCommand, (perCommand.get(activeCommand) ?? 0) + eventTokens);
+            }
+            const persona = extractPersona(event);
+            if (persona) {
+                perPersona.set(persona, (perPersona.get(persona) ?? 0) + eventTokens);
+            }
+        }
+    }
+    return {
+        tokens,
+        perCommand: Array.from(perCommand.entries())
+            .map(([command, value]) => ({ command, tokens: value }))
+            .sort((a, b) => b.tokens - a.tokens),
+        perPersona: Array.from(perPersona.entries())
+            .map(([persona, value]) => ({ persona, tokens: value }))
+            .sort((a, b) => b.tokens - a.tokens),
+    };
+}
+function matchesWindow(event, cutoffMs) {
+    if (cutoffMs === 0)
+        return true;
+    const ts = typeof event.timestamp === 'string' ? Date.parse(event.timestamp) : NaN;
+    if (!Number.isFinite(ts))
+        return false;
+    return ts >= cutoffMs;
+}
+/**
+ * Extract a token count from any event shape we know about.
+ *
+ *   - `tool_result.tokensUsed`        — engine adapter emits this.
+ *   - `subagent.completed.tokensUsed` — α5.4 subagent runner.
+ *   - `engine.turn.tokensIn/tokensOut` — Anvil F1 metric mirror, future.
+ *
+ * Unknown events return 0 so adding new event types upstream never
+ * breaks `pugi budget`.
+ */
+function extractTokens(event) {
+    const direct = numericField(event, 'tokensUsed');
+    if (direct > 0)
+        return direct;
+    const tIn = numericField(event, 'tokensIn');
+    const tOut = numericField(event, 'tokensOut');
+    if (tIn + tOut > 0)
+        return tIn + tOut;
+    return 0;
+}
+function numericField(event, key) {
+    const raw = event[key];
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0)
+        return 0;
+    return Math.floor(raw);
+}
+function extractPersona(event) {
+    const candidate = event['persona'] ?? event['personaSlug'] ?? event['subagent'];
+    if (typeof candidate === 'string' && candidate.length > 0)
+        return candidate;
+    return null;
+}
+function estimateDollars(totalTokens) {
+    // Use output-token rate as the worst case so a user planning to upgrade
+    // a tier is not surprised by an under-estimate.
+    return Number((totalTokens * RATE_OUTPUT_USD_PER_TOKEN).toFixed(6));
+}
+function parseFlags(args) {
+    const flags = { json: false, sinceMs: null };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--json')
+            flags.json = true;
+        else if (arg.startsWith('--since='))
+            flags.sinceMs = parseDuration(arg.slice('--since='.length));
+        else if (arg === '--since') {
+            const value = args[i + 1];
+            if (!value)
+                throw new Error('--since requires a duration like 24h, 30m, or 7d.');
+            flags.sinceMs = parseDuration(value);
+            i += 1;
+        }
+    }
+    return flags;
+}
+function parseDuration(raw) {
+    const match = /^(\d+)(h|m|d|s)?$/.exec(raw.trim());
+    if (!match) {
+        throw new Error(`Invalid --since duration "${raw}". Expected forms: 24h, 30m, 7d, 90s.`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2] ?? 'h';
+    const multiplier = unit === 'h'
+        ? 60 * 60 * 1000
+        : unit === 'm'
+            ? 60 * 1000
+            : unit === 'd'
+                ? 24 * 60 * 60 * 1000
+                : 1000;
+    return amount * multiplier;
+}
+function readEvents(path) {
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // partial-write lines are ignored
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=budget.js.map