kritya 0.8.2-beta

package/dist/headless.js

@@ -0,0 +1,274 @@
+import path from "node:path";
+import { Agent } from "./agent/loop.js";
+import { CONFIG_DIR, legacyGlobalModel, listProviders, loadConfig, loadDotEnv, resolveProvider, } from "./config/config.js";
+import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
+import { PermissionManager } from "./permissions/permissions.js";
+import { loadRules } from "./permissions/rules.js";
+import { ProviderClient, RetryExhaustedError } from "./provider/client.js";
+import { createSwitchyardClient } from "./provider/switchyardClient.js";
+import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel, staleSwitchyardModelWarning, stopSwitchyardSidecar, } from "./provider/switchyardSidecar.js";
+import { SessionStore } from "./session/store.js";
+import { AuditLog } from "./audit/audit.js";
+import { createTracer, telemetryFileFor, cleanupOldTelemetry } from "./telemetry/tracer.js";
+import { createMeter } from "./telemetry/metrics.js";
+import { retentionDaysFor } from "./config/retention.js";
+import { backgroundManager } from "./shell/background.js";
+import { lspManager } from "./lsp/manager.js";
+import { ALL_TOOLS } from "./tools/index.js";
+import { loadMcpTools, shutdownMcp } from "./mcp/client.js";
+import { loadProjectMcpServers, mergeMcpServers } from "./mcp/servers.js";
+import { pluginsDir, scanPlugins, userPluginsDir } from "./plugins/discover.js";
+import { loadPluginMcpServers } from "./plugins/mcp.js";
+import { loadHooks, HookRunner } from "./hooks/hooks.js";
+import { gatedContentHash, isTrusted } from "./trust/trust.js";
+import { partitionByTrust, serverFingerprint, trustServer } from "./trust/mcpTrust.js";
+import { installCrashHandlers } from "./crash.js";
+import { defaultSandboxMode } from "./shell/sandbox.js";
+function emit(args, r) {
+    if (args.output === "json") {
+        console.log(JSON.stringify(r));
+        return;
+    }
+    if (r.result)
+        console.log(r.result);
+    if (r.error)
+        console.error(`Error: ${r.error}`);
+}
+/**
+ * Headless has no terminal to prompt for new MCP server approvals, so a
+ * server only loads if it was already approved in a past interactive
+ * session, unless --trust opts in (same escape hatch as workspace trust).
+ * `source` names where these servers came from, for the skip message.
+ */
+function approveHeadlessMcp(servers, trust, source) {
+    if (!servers)
+        return undefined;
+    const { trusted, pending } = partitionByTrust(servers);
+    if (Object.keys(pending).length === 0)
+        return trusted;
+    if (trust) {
+        for (const [name, cfg] of Object.entries(pending))
+            trustServer(name, serverFingerprint(cfg));
+        return { ...trusted, ...pending };
+    }
+    process.stderr.write(`kritya: skipping unapproved MCP server(s) from ${source}: ${Object.keys(pending).join(", ")} ` +
+        `(approve them once interactively, or pass --trust)\n`);
+    return trusted;
+}
+/**
+ * Runs a single prompt to completion with no terminal UI at all — for
+ * scripting, CI pipelines, and GitHub Actions (`kritya --prompt "..." --output json`).
+ * Returns the process exit code (0 success, 1 failure) rather than exiting
+ * itself, so the caller can flush stdio first.
+ */
+export async function runHeadless(args) {
+    const startedAt = Date.now();
+    const workspace = path.resolve(args.dir);
+    // Only the user's own global .env is unconditionally trusted; see below.
+    loadDotEnv([path.join(CONFIG_DIR, ".env")]);
+    // There's no terminal to show the interactive trust prompt, so headless
+    // mode never blocks on it. The workspace's gated content (its own allow
+    // rules, hooks, .env, and custom commands) only takes effect if it was
+    // already trusted in a prior interactive session, or --trust opts in
+    // explicitly — never silently, since CI checking out arbitrary PR branches
+    // is exactly the scenario that trust gate exists to protect against.
+    const hash = gatedContentHash(workspace);
+    const trustWorkspace = args.trust || !hash || isTrusted(workspace, hash);
+    if (trustWorkspace)
+        loadDotEnv([path.join(workspace, ".env")]);
+    const config = loadConfig();
+    const provider = resolveProvider(config, args.provider || undefined);
+    if (!provider.apiKey) {
+        return finish(args, startedAt, {
+            success: false,
+            result: "",
+            error: `No API key found for provider "${provider.name}". Set it via env var, a .env file, or ~/.kritya/config.json.`,
+            toolCalls: [],
+            usage: { promptTokens: 0, completionTokens: 0, cachedPromptTokens: 0, estimated: false },
+            durationMs: 0,
+        });
+    }
+    const providerDefaultModel = config.providers?.[provider.name]?.model;
+    const model = resolveEffectiveModel(provider.name, [args.model, providerDefaultModel, legacyGlobalModel(config, provider.name)], provider.name === "switchyard" ? SWITCHYARD_ROUTE_ID : DEFAULT_MODEL);
+    const staleModelWarning = staleSwitchyardModelWarning(provider.name, model, args.model);
+    if (staleModelWarning)
+        process.stderr.write(`${staleModelWarning}\n`);
+    const sampling = {
+        temperature: provider.temperature,
+        topP: provider.topP,
+        maxTokens: provider.maxTokens,
+    };
+    const client = provider.name === "switchyard"
+        ? await createSwitchyardClient(provider.apiKey, sampling)
+        : new ProviderClient(provider.apiKey, provider.baseUrl, sampling);
+    const session = new SessionStore(workspace);
+    const initialHistory = args.continue ? (SessionStore.loadLatest(workspace) ?? []) : [];
+    session.start(initialHistory);
+    const sessionAudit = AuditLog.forSession(session.id, config.audit);
+    const sessionTracer = createTracer(session.id, config.otel);
+    const sessionMeter = createMeter(session.id, config.otel);
+    // A crash here orphans MCP children and background processes onto a CI
+    // runner, where nothing will ever reap them. No terminal to restore. The
+    // crash path is fire-and-forget best-effort by Node's own constraints (a
+    // crash handler can't reliably await async work), so this uses the
+    // synchronous flush() rather than flushAndWait().
+    installCrashHandlers({
+        cleanup: () => {
+            backgroundManager.killAll();
+            lspManager.disposeAll();
+            shutdownMcp();
+            sessionMeter.flush();
+            sessionMeter.stop();
+        },
+        details: () => (session.path ? ["", `Transcript: ${session.path}`] : []),
+    });
+    // Same best-effort retention as the interactive path — headless/CI runs are
+    // often the only way kritya ever runs for a given user, so this can't skip
+    // pruning old transcripts/audit logs/telemetry just because there's no TTY.
+    const retentionDays = retentionDaysFor(config);
+    SessionStore.cleanupOldSessions(retentionDays);
+    AuditLog.cleanupOld(retentionDays);
+    cleanupOldTelemetry(retentionDays);
+    // Subagents (spawn_agent/spawn_write_agent) aren't wired up here — they
+    // need per-call worktree/concurrency plumbing that isn't worth duplicating
+    // for a single headless prompt. If the model tries to use one, the tool
+    // itself reports "not available in this session", same as any context
+    // that doesn't wire spawnAgents.
+    // .mcp.json is trust-gated for the same reason hooks and .env are: it runs
+    // processes / contacts endpoints on the user's behalf the moment we load it.
+    const projectMcp = trustWorkspace ? loadProjectMcpServers(workspace) : undefined;
+    // On top of that, each individual server needs its own prior approval (see
+    // trust/mcpTrust.ts) — approveHeadlessMcp below.
+    const approvedProjectMcp = approveHeadlessMcp(projectMcp, args.trust, ".mcp.json");
+    // Agent Plugins: the workspace's own plugins/ folder is part of the same
+    // trust gate as .mcp.json above; user-global plugins are always
+    // discovered, same as ~/.kritya/config.json. Each plugin-declared server
+    // still needs its own prior approval, same as a project server.
+    const plugins = scanPlugins(trustWorkspace ? [pluginsDir(workspace), userPluginsDir()] : [userPluginsDir()]);
+    const { servers: pluginMcp } = loadPluginMcpServers(plugins);
+    const approvedPluginMcp = approveHeadlessMcp(Object.keys(pluginMcp).length ? pluginMcp : undefined, args.trust, "a plugin's mcp.json");
+    // Headless has no UI to ask the user anything, so sampling always fails
+    // closed rather than silently granting a server free use of the model.
+    const onSampling = async () => ({
+        ok: false,
+        reason: "sampling requires interactive mode (kritya without --headless)",
+    });
+    const onElicitation = async () => ({ action: "cancel" });
+    const mcpTools = await loadMcpTools(mergeMcpServers(config.mcpServers, approvedProjectMcp, approvedPluginMcp), { tracer: sessionTracer, audit: sessionAudit, workspace, onSampling, onElicitation });
+    const tools = [...ALL_TOOLS, ...mcpTools];
+    const permissions = new PermissionManager(loadRules(workspace, trustWorkspace));
+    const agent = new Agent(client, () => model, tools, 
+    // No requestElicitation here — no UI to ask through. Leaving it undefined
+    // (rather than an always-cancel stub) lets ask_user report itself as
+    // unavailable, same message a subagent gets, instead of "the user
+    // declined" for a question no one was actually asked.
+    { workspace, sandboxMode: config.sandboxExec ?? defaultSandboxMode(), trustWorkspace }, permissions, session, initialHistory);
+    agent.contextWindow = contextWindowFor(model, config);
+    if (config.maxSteps && config.maxSteps > 0)
+        agent.maxSteps = config.maxSteps;
+    if (config.toolTimeoutSeconds !== undefined) {
+        agent.toolTimeoutMs = config.toolTimeoutSeconds * 1000;
+    }
+    agent.hooks = new HookRunner(loadHooks(workspace, trustWorkspace), workspace);
+    agent.audit = sessionAudit;
+    agent.tracer = sessionTracer;
+    agent.meter = sessionMeter;
+    agent.hooks.tracer = sessionTracer;
+    const toolCalls = [];
+    let usage = { promptTokens: 0, completionTokens: 0, cachedPromptTokens: 0, estimated: false };
+    let finalText = "";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(1, args.timeoutSeconds) * 1000);
+    timer.unref();
+    const handlers = {
+        onTextDelta: () => { },
+        onReasoningDelta: () => { },
+        onAssistantText: (text) => {
+            finalText = text;
+        },
+        onToolStart: () => { },
+        onToolEnd: (_id, name, summary, _preview, isError) => {
+            toolCalls.push({ name, summary, error: isError });
+        },
+        // No terminal to ask. A destructive command (classifyDanger sets
+        // `warning`) is always denied, no matter what — there's no one to
+        // confirm it and letting it run unattended would be unsafe. Anything
+        // else follows --allow-all, or falls through to settings.json allow
+        // rules (which PermissionManager already applied before this is called).
+        requestPermission: async (_name, _summary, _diff, warning) => {
+            if (warning)
+                return "no";
+            return args.allowAll ? "yes" : "no";
+        },
+        onUsage: (u) => {
+            usage = {
+                promptTokens: usage.promptTokens + u.promptTokens,
+                completionTokens: usage.completionTokens + u.completionTokens,
+                cachedPromptTokens: usage.cachedPromptTokens + (u.cachedPromptTokens ?? 0),
+                estimated: usage.estimated || Boolean(u.estimated),
+            };
+        },
+    };
+    let success = true;
+    let errorMessage;
+    try {
+        await agent.runTurn(args.prompt, handlers, controller.signal);
+    }
+    catch (err) {
+        success = false;
+        const isTimeout = controller.signal.aborted;
+        if (isTimeout) {
+            errorMessage = `Timed out after ${args.timeoutSeconds}s (--timeout to raise it)`;
+        }
+        else if (err instanceof RetryExhaustedError) {
+            const alternatives = listProviders(config)
+                .filter((p) => p.hasKey && p.name !== provider.name)
+                .map((p) => p.name);
+            const hint = alternatives.length
+                ? ` Retry with --provider ${alternatives[0]}` +
+                    (alternatives.length > 1
+                        ? ` (also configured: ${alternatives.slice(1).join(", ")})`
+                        : "") +
+                    `.`
+                : " No other provider has an API key configured to fall back to.";
+            errorMessage = `${err.message}.${hint}`;
+        }
+        else {
+            errorMessage = err instanceof Error ? err.message : String(err);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        backgroundManager.killAll();
+        lspManager.disposeAll();
+        shutdownMcp();
+        if (provider.name === "switchyard")
+            stopSwitchyardSidecar();
+    }
+    // Normal (non-crash) shutdown: give the final metrics export a real chance
+    // to land, capped so a hung collector can't stall the exit code the caller
+    // is waiting on.
+    await Promise.race([
+        sessionMeter.flushAndWait(),
+        new Promise((resolve) => setTimeout(resolve, 2000).unref()),
+    ]);
+    sessionMeter.stop();
+    return finish(args, startedAt, {
+        success,
+        result: finalText,
+        error: errorMessage,
+        toolCalls,
+        usage,
+        durationMs: Date.now() - startedAt,
+        model,
+        sessionId: session.id,
+        traceId: agent.lastTraceId,
+        auditFile: agent.audit?.path,
+        telemetryFile: telemetryFileFor(session.id),
+    });
+}
+function finish(args, startedAt, r) {
+    const result = { ...r, durationMs: r.durationMs ?? Date.now() - startedAt };
+    emit(args, result);
+    return result.success ? 0 : 1;
+}

package/dist/hooks/hooks.js

@@ -0,0 +1,122 @@
+import { exec } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR, scrubbedShellEnv } from "../config/config.js";
+import { safeCompileRegex } from "../tools/common.js";
+import { NOOP_TRACER } from "../telemetry/tracer.js";
+import { debugLog } from "../config/debug.js";
+const HOOK_TIMEOUT_MS = 30_000;
+export function loadHooks(workspace, trustWorkspace = true) {
+    const merged = {};
+    const files = [path.join(CONFIG_DIR, "settings.json")];
+    if (trustWorkspace)
+        files.push(path.join(workspace, ".kritya", "settings.json"));
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!parsed.hooks)
+                continue;
+            for (const event of ["preToolUse", "postToolUse", "stop"]) {
+                const defs = parsed.hooks[event];
+                if (Array.isArray(defs))
+                    merged[event] = [...(merged[event] ?? []), ...defs];
+            }
+        }
+        catch (err) {
+            // A missing settings.json is normal; a malformed one silently means
+            // "no hooks run", worth being able to see.
+            debugLog(`loadHooks(${file})`, err);
+        }
+    }
+    return merged;
+}
+/** Run one hook command without blocking the event loop (the Ink UI stays live). */
+function execHook(command, cwd, env) {
+    return new Promise((resolve) => {
+        exec(command, { cwd, env, timeout: HOOK_TIMEOUT_MS, windowsHide: true, encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error) {
+                const output = (stderr || stdout || error.message || "hook failed").toString().trim();
+                resolve({ ok: false, output });
+            }
+            else {
+                resolve({ ok: true, output: (stdout ?? "").trim() });
+            }
+        });
+    });
+}
+export class HookRunner {
+    hooks;
+    workspace;
+    /** OpenTelemetry-shaped tracer, one span per hook execution. No-op unless set by the caller. */
+    tracer = NOOP_TRACER;
+    constructor(hooks, workspace) {
+        this.hooks = hooks;
+        this.workspace = workspace;
+    }
+    has(event) {
+        return (this.hooks[event]?.length ?? 0) > 0;
+    }
+    /** Run tool-related hooks. For preToolUse, `blocked` is true if a blocking hook failed. */
+    async runToolHooks(event, toolName, args, parent) {
+        const defs = this.hooks[event] ?? [];
+        // scrubbedShellEnv: hooks are arbitrary commands and must not silently
+        // inherit provider API keys from kritya's own environment.
+        const env = {
+            ...scrubbedShellEnv(),
+            KRITYA_TOOL_NAME: toolName,
+            KRITYA_TOOL_PATH: String(args.path ?? ""),
+            KRITYA_TOOL_COMMAND: String(args.command ?? ""),
+            KRITYA_TOOL_ARGS: safeJson(args),
+        };
+        const outputs = [];
+        for (const def of defs) {
+            if (def.match) {
+                let matches;
+                try {
+                    matches = safeCompileRegex(def.match).test(toolName);
+                }
+                catch {
+                    continue; // malformed or unsafe pattern in settings.json — skip this hook
+                }
+                if (!matches)
+                    continue;
+            }
+            const span = this.tracer.startSpan(`hook.${event}`, {
+                parent,
+                attributes: { "kritya.hook_command": def.command, "kritya.hook_tool": toolName },
+            });
+            const { ok, output } = await execHook(def.command, this.workspace, env);
+            if (output)
+                outputs.push(output);
+            if (!ok && event === "preToolUse" && def.blocking) {
+                span.setStatus("ERROR", "blocked").end();
+                return {
+                    blocked: true,
+                    blockedBy: def.command,
+                    output: `A preToolUse hook (\`${def.command}\`) blocked this ${toolName} call:\n${output}`,
+                };
+            }
+            span.setStatus(ok ? "OK" : "ERROR", ok ? undefined : output.slice(0, 500)).end();
+        }
+        return { blocked: false, output: outputs.join("\n") };
+    }
+    async runStop(parent) {
+        for (const def of this.hooks.stop ?? []) {
+            const span = this.tracer.startSpan("hook.stop", {
+                parent,
+                attributes: { "kritya.hook_command": def.command },
+            });
+            // stop hooks are best-effort; failures are ignored beyond the span.
+            const { ok, output } = await execHook(def.command, this.workspace, scrubbedShellEnv());
+            span.setStatus(ok ? "OK" : "ERROR", ok ? undefined : output.slice(0, 500)).end();
+        }
+    }
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return "{}";
+    }
+}