@zenera/cli 1.1.0

package/dist/tui/app.js

@@ -0,0 +1,257 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { TextInput } from '@inkjs/ui';
+import { Box, Static, Text, useApp, useInput, useStdout } from 'ink';
+import { pathToFileURL } from 'node:url';
+import React, { useCallback, useContext, useRef, useState } from 'react';
+import { isCheckpoint, turns, zeroUsage } from '@zenera/neo';
+import * as Engine from "../engine.js";
+import { format } from "../narrate.js";
+import { display } from "../session.js";
+import { CliError } from "../term.js";
+import { resolveTheme, THEMES } from "./theme.js";
+import { windowOf } from "./wrap.js";
+const BANNER = { key: 'banner' };
+const isBanner = (item) => item.key === 'banner';
+const MARK = {
+    you: '›',
+    agent: ' ',
+    tool: '·',
+    note: ' ',
+    error: '!',
+};
+// The theme is decided once, before the first frame, and never changes while
+// the app is up — a terminal does not repaint its own scheme underneath us.
+// A context rather than props only because every part of the view wants it.
+const ThemeContext = React.createContext(THEMES.dark);
+const useTheme = () => useContext(ThemeContext);
+function Row({ line }) {
+    const style = useTheme().line[line.kind];
+    return (_jsxs(Box, { flexDirection: "row", marginTop: line.kind === 'you' ? 1 : 0, children: [_jsxs(Text, { color: style.color, dimColor: style.dim, children: [MARK[line.kind], ' '] }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: style.color, dimColor: style.dim, bold: line.kind === 'you', children: line.text }), line.detail ? _jsx(Text, { dimColor: true, children: line.detail }) : null] })] }));
+}
+function App({ engine, options, theme }) {
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const [lines, setLines] = useState([]);
+    const [live, setLive] = useState('');
+    const [thinking, setThinking] = useState('');
+    const [busy, setBusy] = useState(false);
+    const [agent, setAgent] = useState(engine.state?.agentName ?? engine.project.entry);
+    const [stats, setStats] = useState({
+        session: engine.state?.usage ?? zeroUsage(),
+        calls: engine.state ? turns(engine.state) : 0,
+    });
+    const [tool, setTool] = useState(undefined);
+    const stopping = useRef(undefined);
+    const seq = useRef(0);
+    // Read during render so a resize, which re-renders the root, resizes the
+    // windows below with it. The two streaming blocks share one budget: what
+    // is left of the terminal once the chrome has had its rows.
+    const rows = stdout?.rows ?? 24;
+    const columns = stdout?.columns ?? 80;
+    const budget = Math.max(2, rows - CHROME_ROWS);
+    const thinkingRows = thinking ? Math.min(THINKING_ROWS, Math.max(1, budget - 2)) : 0;
+    const liveRows = Math.max(1, budget - thinkingRows);
+    const push = useCallback((kind, text, detail) => {
+        setLines((prev) => [...prev, { key: `${seq.current++}`, kind, text, detail }]);
+    }, []);
+    // Deltas arrive far faster than a terminal can usefully redraw, so text is
+    // accumulated in one string and React coalesces the repaints. The finished
+    // answer replaces it in one piece when the turn lands.
+    //
+    // Reasoning is accumulated the same way but never enters `lines`: it is a
+    // progress indicator, not part of the conversation. The full chain is in
+    // the trajectory (`LlmCallNode.thinking`) and the run's report, so nothing
+    // is lost when it is cleared at the start of the next model call.
+    const onEvent = useCallback((event) => {
+        if (!isCheckpoint(event)) {
+            if (event.type === 'text_delta') {
+                setLive((prev) => prev + event.delta);
+            }
+            else if (event.type === 'thinking_delta') {
+                setThinking((prev) => prev + event.delta);
+            }
+            return;
+        }
+        switch (event.type) {
+            case 'before_llm_call':
+                setThinking('');
+                break;
+            case 'before_tool_call':
+                setTool(event.call.name);
+                break;
+            case 'after_tool_call':
+                setTool(undefined);
+                push('tool', event.node.name, event.node.isError ? 'failed' : durationOf(event.node.durationMs));
+                break;
+            case 'handoff':
+                setAgent(event.to);
+                push('note', `→ ${event.to}`, `handed off from ${event.from}`);
+                break;
+            case 'before_fork':
+                push('note', `⑂ ${event.node.branches.map((b) => b.name).join(', ')}`);
+                break;
+            case 'branch_finished':
+                push('tool', `⑂ ${event.child.name}`, event.status);
+                break;
+            default:
+                break;
+        }
+    }, [push]);
+    const submit = useCallback((value) => {
+        const text = value.trim();
+        if (!text || busy) {
+            return;
+        }
+        if (text === '/exit' || text === '/quit') {
+            exit();
+            return;
+        }
+        if (text === '/clear') {
+            setLines([]);
+            stdout?.write('\u001b[2J\u001b[H');
+            return;
+        }
+        push('you', text);
+        setBusy(true);
+        setLive('');
+        setThinking('');
+        const controller = new AbortController();
+        stopping.current = controller;
+        void (async () => {
+            try {
+                const outcome = await Engine.run(engine, text, onEvent, controller.signal);
+                push('agent', outcome.text);
+                // The previous total is the only thing that can say what
+                // this turn cost, and reading it out of the updater is what
+                // makes that true regardless of when the turn lands.
+                setStats((prev) => ({
+                    session: outcome.result.usage,
+                    turn: since(prev.session, outcome.result.usage),
+                    calls: turns(outcome.result.state),
+                    durationMs: outcome.durationMs,
+                }));
+                setAgent(outcome.result.agent);
+                if (outcome.result.stopReason === 'aborted') {
+                    push('note', 'stopped');
+                }
+                if (outcome.report) {
+                    push('note', `↗ report ${pathToFileURL(outcome.report).href}`);
+                }
+            }
+            catch (err) {
+                const hint = err instanceof CliError ? err.hint : undefined;
+                push('error', err instanceof Error ? err.message : String(err), hint);
+            }
+            finally {
+                setBusy(false);
+                setLive('');
+                setThinking('');
+                setTool(undefined);
+                stopping.current = undefined;
+            }
+        })();
+    }, [busy, engine, exit, onEvent, push, stdout]);
+    // Escape stops the turn; ctrl-c leaves. They are different things, and a
+    // run that is asked to stop still writes its state, so the session survives
+    // either one.
+    useInput((_input, keys) => {
+        if (keys.escape && stopping.current) {
+            stopping.current.abort();
+        }
+        if (keys.ctrl && _input === 'c') {
+            stopping.current?.abort();
+            exit();
+        }
+    });
+    return (_jsx(ThemeContext.Provider, { value: theme, children: _jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: [BANNER, ...lines], children: (item) => isBanner(item) ? (_jsx(Header, { engine: engine, readOnly: options.readOnly }, item.key)) : (_jsx(Row, { line: item }, item.key)) }), thinking ? (_jsx(Thinking, { text: thinking, columns: columns, rows: thinkingRows })) : null, live ? _jsx(Live, { text: live, columns: columns, rows: liveRows }) : null, _jsx(Footer, { agent: agent, busy: busy, tool: tool, stats: stats, thinking: Boolean(thinking) }), busy ? null : (_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, children: "\u203A " }), _jsx(TextInput, { placeholder: "Ask something\u2026 (/exit to leave)", onSubmit: submit })] }))] }) }));
+}
+function Header({ engine, readOnly, }) {
+    const theme = useTheme();
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, children: engine.name }), _jsxs(Text, { dimColor: true, children: [" ", engine.session.id] }), readOnly ? _jsx(Text, { color: theme.warn, children: " read-only" }) : null] }), _jsx(Text, { dimColor: true, children: display(engine.workspace) })] }));
+}
+// ---------------------------------------------------------------------------
+// The repainting frame
+//
+// Everything below `Static` is redrawn on every event, and it has one hard
+// constraint: **it must never be taller than the terminal.** Ink erases the
+// previous frame by moving the cursor up over it, which only works while that
+// frame is still on screen. A frame that outgrows the viewport scrolls its own
+// top away, the erase falls short, and every repaint strands another copy of
+// its first line in the scrollback — the same line, over and over, with the
+// text creeping sideways as the stream advances.
+//
+// The unit that matters here is the **row the terminal draws**, not the line
+// the model wrote. A reasoning stream is one enormous paragraph with almost no
+// newlines in it, so counting `\n` says "six lines" while the terminal draws
+// sixty. So `windowOf` wraps the text itself, to a width it knows, and takes
+// the last N wrapped rows — and then the same number is given again as an
+// explicit `height` with `overflow="hidden"`, so a miscount clips instead of
+// corrupting.
+//
+// Nothing is lost by any of it: the finished answer lands in `Static` whole,
+// and the full reasoning chain is in the trajectory and the run's report.
+// ---------------------------------------------------------------------------
+/** How much of the reasoning stream is worth showing. It is a progress bar. */
+const THINKING_ROWS = 6;
+/** The two footer rows, its margin, the prompt, and a row in hand. */
+const CHROME_ROWS = 6;
+/** The gutter every streaming block is indented behind. */
+const GUTTER = 2;
+function Thinking({ text, columns, rows }) {
+    const theme = useTheme();
+    const shown = windowOf(text, columns - GUTTER, rows);
+    return (_jsxs(Box, { flexDirection: "row", height: shown.length, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", width: GUTTER, children: shown.map((_, i) => (_jsx(Text, { color: theme.rule, dimColor: true, children: i === 0 ? '◇ ' : '  ' }, i))) }), _jsx(Box, { flexDirection: "column", children: shown.map((row, i) => (_jsx(Text, { dimColor: true, italic: true, wrap: "truncate-end", children: row }, i))) })] }));
+}
+function Live({ text, columns, rows }) {
+    const shown = windowOf(text, columns - GUTTER, rows);
+    return (_jsx(Box, { flexDirection: "column", paddingLeft: GUTTER, height: shown.length, overflow: "hidden", children: shown.map((row, i) => (_jsx(Text, { wrap: "truncate-end", children: row }, i))) }));
+}
+function Footer({ agent, busy, tool, stats, thinking, }) {
+    const what = tool ? `running ${tool}` : thinking ? 'reasoning' : 'thinking';
+    const theme = useTheme();
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { children: [busy ? _jsxs(Text, { color: theme.warn, children: [what, "\u2026 "] }) : null, _jsx(Text, { color: theme.accent, dimColor: true, children: agent }), stats.turn ? (_jsxs(Text, { dimColor: true, children: ['  turn ', tokens(stats.turn), stats.durationMs === undefined
+                                ? ''
+                                : ` · ${durationOf(stats.durationMs) ?? ''}`] })) : null, busy ? _jsx(Text, { dimColor: true, children: '  esc to stop' }) : null] }), _jsxs(Text, { dimColor: true, children: ['session ', tokens(stats.session), stats.calls ? ` · ${stats.calls} ${stats.calls === 1 ? 'call' : 'calls'}` : ''] })] }));
+}
+/**
+ * Cache and reasoning are subsets of the numbers beside them, not additions to
+ * them, and they are only worth the width when a provider actually reports one
+ * — most do not, and a row of zeroes teaches nobody anything.
+ */
+function tokens(usage) {
+    const parts = [`${format(usage.inputTokens)} in`];
+    if (usage.cachedInputTokens) {
+        parts.push(`${format(usage.cachedInputTokens)} cached`);
+    }
+    parts.push(`${format(usage.outputTokens)} out`);
+    if (usage.reasoningTokens) {
+        parts.push(`${format(usage.reasoningTokens)} thinking`);
+    }
+    return parts.join(' · ');
+}
+/** What the last turn added. Usage only ever grows, so a subtraction is safe. */
+function since(before, after) {
+    return {
+        inputTokens: after.inputTokens - before.inputTokens,
+        cachedInputTokens: after.cachedInputTokens - before.cachedInputTokens,
+        outputTokens: after.outputTokens - before.outputTokens,
+        reasoningTokens: after.reasoningTokens - before.reasoningTokens,
+    };
+}
+function durationOf(ms) {
+    return ms === undefined ? undefined : ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+// ---------------------------------------------------------------------------
+export async function start(engine, options) {
+    // Asked before Ink takes the terminal: the query talks to stdin directly,
+    // and there is exactly one moment when nothing else is holding it.
+    const theme = await resolveTheme(options.theme);
+    const { render } = await import('ink');
+    // Ctrl-C is handled above so an in-flight turn can be aborted and recorded
+    // rather than the process simply vanishing mid-write.
+    const instance = render(_jsx(App, { engine: engine, options: options, theme: theme }), {
+        exitOnCtrlC: false,
+    });
+    await instance.waitUntilExit();
+}
+//# sourceMappingURL=app.js.map

package/dist/tui/theme.d.ts

@@ -0,0 +1,23 @@
+export type Appearance = 'dark' | 'light';
+/** The roles a line can play in the transcript. */
+export type Kind = 'you' | 'agent' | 'tool' | 'note' | 'error';
+export interface LineStyle {
+    /** `undefined` means the terminal's own foreground. */
+    readonly color?: string;
+    readonly dim?: boolean;
+}
+export interface Theme {
+    readonly appearance: Appearance;
+    readonly line: Record<Kind, LineStyle>;
+    /** Agent name, prompt caret — the one colour the eye is trained to find. */
+    readonly accent: string;
+    /** Read-only badge, busy label. */
+    readonly warn: string;
+    /** Gutters and marks: structure, not content. Always drawn dim. */
+    readonly rule?: string;
+}
+export declare const THEMES: Record<Appearance, Theme>;
+export type ThemeChoice = Appearance | 'auto';
+export declare function parseChoice(value: string | undefined): ThemeChoice | undefined;
+export declare function resolveTheme(choice?: string): Promise<Theme>;
+//# sourceMappingURL=theme.d.ts.map

package/dist/tui/theme.js

@@ -0,0 +1,134 @@
+// ---------------------------------------------------------------------------
+// Light and dark
+//
+// A terminal already has a colour scheme, and it is not ours to replace. The
+// rule here is to name as few colours as possible and to name them by role:
+// the answer is drawn in the terminal's *own* foreground (no colour at all),
+// asides are drawn dim, and only the few things that must stand out —
+// the person's own turn, the agent name, a warning, an error — take a colour.
+//
+// That alone fixes most of it. `white` was the bug: it is legible on exactly
+// one kind of background, and half the world runs the other kind. What is left
+// is the handful of accents that ANSI *does* let a light theme get wrong —
+// `cyan` on paper, `gray` on paper — so those swap.
+//
+// Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
+// A palette that ignores the user's scheme is worse on both schemes than one
+// that mostly defers to it.
+// ---------------------------------------------------------------------------
+const DARK = {
+    appearance: 'dark',
+    line: {
+        you: { color: 'cyan' },
+        agent: {},
+        tool: { color: 'gray', dim: true },
+        note: { color: 'cyan', dim: true },
+        error: { color: 'red' },
+    },
+    accent: 'cyan',
+    warn: 'yellow',
+    rule: 'gray',
+};
+// On a light background `gray` is bright black — pale grey on white — and
+// `cyan` and `yellow` are barely darker than the paper. Dimmed default
+// foreground and `blue`/`magenta` are the same information, still legible.
+const LIGHT = {
+    appearance: 'light',
+    line: {
+        you: { color: 'blue' },
+        agent: {},
+        tool: { dim: true },
+        note: { color: 'blue', dim: true },
+        error: { color: 'red' },
+    },
+    accent: 'blue',
+    warn: 'magenta',
+};
+export const THEMES = { dark: DARK, light: LIGHT };
+export function parseChoice(value) {
+    const v = value?.trim().toLowerCase();
+    return v === 'dark' || v === 'light' || v === 'auto' ? v : undefined;
+}
+export async function resolveTheme(choice) {
+    const asked = parseChoice(choice) ?? parseChoice(process.env['ZENERA_THEME']) ?? 'auto';
+    if (asked !== 'auto') {
+        return THEMES[asked];
+    }
+    return THEMES[(await queryBackground()) ?? fromColorFgBg() ?? 'dark'];
+}
+/**
+ * `COLORFGBG` is `fg;bg` or `fg;<something>;bg`; the background is the last
+ * field. Anything non-numeric (notably `default`) tells us nothing.
+ */
+function fromColorFgBg() {
+    const parts = process.env['COLORFGBG']?.split(';');
+    const bg = parts?.[parts.length - 1];
+    if (bg === undefined || !/^\d+$/.test(bg)) {
+        return undefined;
+    }
+    const n = Number(bg);
+    return n === 7 || n >= 9 ? 'light' : 'dark';
+}
+const QUERY = '\u001b]11;?\u0007';
+const REPLY = /\u001b\]11;rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})/i;
+/**
+ * Ask the terminal for its background colour and read the answer off stdin.
+ *
+ * This is a conversation with a program that may not be listening, so it is
+ * bounded on every axis: raw mode is taken and given back, the listener is
+ * removed either way, and a terminal that does not answer costs one timeout
+ * and nothing else. Anything the user typed in that window is put back, so
+ * the first keystroke of a fast start is not eaten by the handshake.
+ */
+async function queryBackground(timeoutMs = 120) {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== 'function') {
+        return undefined;
+    }
+    const wasRaw = stdin.isRaw;
+    let timer;
+    let settled = false;
+    let seen = '';
+    return await new Promise((resolve) => {
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            stdin.off('data', onData);
+            stdin.setRawMode(wasRaw);
+            if (!wasRaw) {
+                stdin.pause();
+            }
+            const typed = seen.replace(REPLY, '').replace(/\u001b\\|\u0007/g, '');
+            if (typed) {
+                stdin.unshift(Buffer.from(typed, 'latin1'));
+            }
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            seen += chunk.toString('latin1');
+            const m = REPLY.exec(seen);
+            if (m) {
+                finish(appearanceOf(m[1], m[2], m[3]));
+            }
+            else if (seen.length > 256) {
+                finish(undefined);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+        timer = setTimeout(() => finish(undefined), timeoutMs);
+        timer.unref?.();
+        stdout.write(QUERY);
+    });
+}
+/** Components come back as 1–4 hex digits, so each is scaled by its own width. */
+function appearanceOf(r, g, b) {
+    const channel = (hex) => parseInt(hex, 16) / (16 ** hex.length - 1);
+    const luminance = 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+    return luminance > 0.5 ? 'light' : 'dark';
+}
+//# sourceMappingURL=theme.js.map

package/dist/tui/wrap.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The last `rows` rows of `text` once wrapped to `width`, each one short enough
+ * that the terminal will not wrap it again.
+ *
+ * Only the tail is ever wanted, so only the tail is wrapped: `width * rows * 2`
+ * characters is more than enough to fill the window whatever the wrapping does,
+ * and bounds the work per keystroke on a stream that never stops growing.
+ */
+export declare function windowOf(text: string, width: number, rows: number): string[];
+/** Word wrap. Every returned row is at most `width` columns wide. */
+export declare function wrap(text: string, width: number): string[];
+//# sourceMappingURL=wrap.d.ts.map

package/dist/tui/wrap.js

@@ -0,0 +1,62 @@
+// ---------------------------------------------------------------------------
+// Measuring in rows
+//
+// The unit that matters in a repainting terminal frame is the **row the
+// terminal draws**, not the line the model wrote. A reasoning stream is one
+// enormous paragraph with almost no newlines in it, so counting `\n` says
+// "six lines" while the terminal draws sixty — and a frame that outgrows the
+// viewport is the one thing Ink cannot erase (see tui/app.tsx).
+//
+// So the text is wrapped here, to a width we know, and measured in what comes
+// out. Plain text only: nothing that reaches these two functions has style
+// codes in it, so there is no need to carry the machinery for counting around
+// them.
+// ---------------------------------------------------------------------------
+/**
+ * The last `rows` rows of `text` once wrapped to `width`, each one short enough
+ * that the terminal will not wrap it again.
+ *
+ * Only the tail is ever wanted, so only the tail is wrapped: `width * rows * 2`
+ * characters is more than enough to fill the window whatever the wrapping does,
+ * and bounds the work per keystroke on a stream that never stops growing.
+ */
+export function windowOf(text, width, rows) {
+    const w = Math.max(8, width);
+    const n = Math.max(1, rows);
+    const wrapped = wrap(text.slice(-w * n * 2).replace(/\n{2,}/g, '\n'), w);
+    return wrapped.slice(-n);
+}
+/** Word wrap. Every returned row is at most `width` columns wide. */
+export function wrap(text, width) {
+    const w = Math.max(1, width);
+    const out = [];
+    for (const paragraph of text.split('\n')) {
+        let line = '';
+        for (const word of paragraph.split(' ')) {
+            // A word wider than the terminal has to be broken somewhere, and
+            // anywhere is as good as anywhere else.
+            let rest = word;
+            while (rest.length > w) {
+                if (line) {
+                    out.push(line);
+                    line = '';
+                }
+                out.push(rest.slice(0, w));
+                rest = rest.slice(w);
+            }
+            if (!line) {
+                line = rest;
+            }
+            else if (line.length + 1 + rest.length <= w) {
+                line += ` ${rest}`;
+            }
+            else {
+                out.push(line);
+                line = rest;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+//# sourceMappingURL=wrap.js.map

package/dist/validate.d.ts

@@ -0,0 +1,145 @@
+import { type AnyTool, type ProjectConfig } from '@zenera/neo';
+import { type DeclaredRole } from './audit.ts';
+import { type KeyStore } from './keys.ts';
+/**
+ * `error` — the project will not load, or will not run.
+ * `warning` — it loads, and something about it is probably not what was meant.
+ * `note` — worth knowing, wrong in no sense at all.
+ */
+export type Severity = 'error' | 'warning' | 'note';
+export interface Finding {
+    severity: Severity;
+    /** stable identifier, e.g. `prompt.missing` — safe to match on */
+    code: string;
+    /** the config key or path this is about, e.g. `agents.triage.system` */
+    where: string;
+    message: string;
+    /** what to do about it, naming a file or a command */
+    fix?: string;
+}
+export interface FileCheck {
+    /** relative to the project root */
+    path: string;
+    /** what the file is for, in words */
+    role: string;
+    kind: 'file' | 'directory';
+    exists: boolean;
+    /** the project does not load without it */
+    required: boolean;
+    bytes?: number;
+    /** the config key that named it, when a key did rather than a convention */
+    from?: string;
+}
+export interface AgentReport {
+    name: string;
+    /** the agent a bare `zen run` starts on */
+    entry: boolean;
+    description?: string;
+    /** the model as written, before aliases are resolved */
+    model?: string;
+    /** where that value came from */
+    modelSource: 'agent' | 'project' | 'none';
+    /** prompt files, in the order they are concatenated */
+    instructions: string[];
+    /** `tools:` as written */
+    toolSelectors: string[];
+    /** what those selectors resolve to */
+    tools: string[];
+    handoffs: string[];
+    skills?: {
+        provider: string;
+        discovery: string;
+        allow?: string[];
+        preload?: string[];
+    };
+    fork?: {
+        agents?: string[];
+        maxBranches?: number;
+    };
+    /** true when the agent overrides the project's container */
+    ownSandbox: boolean;
+}
+export interface SkillReport {
+    name: string;
+    description: string;
+    /** the SKILL.md, relative to the project root */
+    path: string;
+    tools?: string[];
+    /** other files in the skill folder, which the agent gets as resources */
+    resources?: string[];
+    /** agents whose binding can see it */
+    usedBy: string[];
+}
+export interface ModelReport {
+    /** the alias it is declared under, or the reference itself */
+    name: string;
+    /** what the config declared it for */
+    role: DeclaredRole;
+    /** the provider it resolves to */
+    provider?: string;
+    kind?: string;
+    /** the variable that would carry the credential */
+    env?: string;
+    credential: 'present' | 'missing' | 'rejected' | 'unknown';
+    detail?: string;
+    /** agents that would use it */
+    usedBy: string[];
+}
+export interface Report {
+    /** no errors — the project loads */
+    ok: boolean;
+    project: {
+        name: string | null;
+        root: string;
+        /** whether the registry knows this path, i.e. whether `zen list` shows it */
+        registered: boolean;
+        /** the config file that wins, relative to the root */
+        config: string | null;
+        /** other config files present, which the loader will ignore */
+        shadowed: string[];
+        version: number | null;
+        entry: string | null;
+    };
+    files: FileCheck[];
+    agents: AgentReport[];
+    skills: {
+        /** the directories the catalog is built from */
+        dirs: string[];
+        entries: SkillReport[];
+    };
+    providers: string[];
+    models: ModelReport[];
+    sandbox: {
+        image: string | null;
+        declared: boolean;
+        used: boolean;
+    };
+    findings: Finding[];
+    counts: {
+        errors: number;
+        warnings: number;
+        notes: number;
+    };
+}
+export interface ValidateOptions {
+    /** the project directory */
+    dir: string;
+    /** the registered name, when there is one */
+    name?: string;
+    /**
+     * Whether the registry knows this path. Passed in rather than looked up,
+     * because nothing in this check may depend on `$HOME` being readable: the
+     * machine that is not set up yet is the one that most needs the report.
+     */
+    registered?: boolean;
+    /**
+     * The keyring, materialised. Given, every model the project names is
+     * checked for a credential; omitted, that section says `unknown` and no
+     * finding is raised — a project is not invalid because this laptop cannot
+     * pay for it.
+     */
+    keys?: KeyStore;
+}
+export declare function validateProject(opts: ValidateOptions): Promise<Report>;
+export declare function availableTools(root: string, config: ProjectConfig): AnyTool<unknown>[];
+//# sourceMappingURL=validate.d.ts.map