@cruxy/cli 1.0.3 → 1.0.4

package/dist/tools/types.d.ts

@@ -1,257 +0,0 @@
-import type { z, ZodTypeAny } from "zod";
-import type { CruxyConfig } from "../config/index.js";
-import type { ApprovalDecision } from "../approval/types.js";
-import type { SandboxService } from "../sandbox/index.js";
-import type { Workspace } from "../workspace/index.js";
-import type { logger } from "../utils/logger.js";
-/** The leveled logger instance shared across the CLI. */
-type Logger = typeof logger;
-/**
- * The outcome of a tool run. Tools never throw across this boundary — failures
- * are reported as `{ ok: false }` so the agent loop can feed the error back to
- * the model instead of crashing.
- */
-export type ToolResult = {
-    ok: true;
-    output: string;
-} | {
-    ok: false;
-    error: string;
-};
-/**
- * One file's worth of change inside an `apply_patch` preview. Paths are
- * project-relative (the tool relativizes them for display).
- */
-export type PatchFilePreview = {
-    op: "update";
-    path: string;
-    hunks: {
-        oldStr: string;
-        newStr: string;
-    }[];
-} | {
-    op: "create";
-    path: string;
-    lines: string[];
-    omittedLines: number;
-} | {
-    op: "delete";
-    path: string;
-};
-/**
- * An optional preview of exactly what a mutating action will change, threaded
- * from the tool into `ctx.approve` so the prompt can show it before the user
- * decides. The tool fills this in from data it has already computed.
- */
-export type ActionPreview = 
-/** The exact strings `edit_file` is about to swap. */
-{
-    type: "edit";
-    oldStr: string;
-    newStr: string;
-}
-/**
- * What `write_file` will write: whether the path already exists (overwrite vs
- * create) and the first lines of the new content, pre-capped by the tool.
- */
- | {
-    type: "write";
-    exists: boolean;
-    lines: string[];
-    omittedLines: number;
-}
-/** The full set of file changes `apply_patch` will make, for a combined diff. */
- | {
-    type: "patch";
-    files: PatchFilePreview[];
-}
-/**
- * The whole publish plan for a `vcs` action (C.15): the feature branch, the
- * conventional commit, and the PR title/body — shown as one block so the user
- * approves the entire branch → commit → push → open-PR sequence at once. C.26
- * Step 4 adds `target` (the resolved `host/owner/repo` the PR will open against)
- * so the human sees the real API destination — not just the root name — before
- * approving (⚖︎JC-4); it is re-resolved and re-checked immediately before the API
- * call, so what is shown here is what the guard holds them to.
- */
- | {
-    type: "pr";
-    branch: string;
-    base: string;
-    commitSubject: string;
-    commitBody: string;
-    prTitle: string;
-    prBody: string;
-    /** The resolved forge target parsed from `origin` at approval time. */
-    target: {
-        host: string;
-        owner: string;
-        repo: string;
-    };
-}
-/**
- * The full blast radius of a checkpoint restore (C.32): every file rollback
- * will recreate/revert/delete (as patch-style entries), plus the paths that
- * changed since the checkpoint by something *other* than the tracked run —
- * shown before the diff so the collapse cap can never hide them. Rollback
- * covers working-tree files only; commits/pushes/PRs made during the run are
- * out of scope (stated in the rendered note).
- */
- | {
-    type: "rollback";
-    checkpointId: string;
-    createdAt: string;
-    runSummary: string;
-    files: PatchFilePreview[];
-    externalPaths: string[];
-    /** The run executed shell commands, so per-file attribution is impossible. */
-    attributionUnknown: boolean;
-}
-/**
- * A multi-root rollback set (C.26 step 3): one combined preview grouped by root,
- * each root carrying its own file diffs and external-change warnings, so a single
- * U.3 approval covers restoring every touched root of a run at once (⚖︎JC-ι). One
- * `roots` entry per member of the run's `CheckpointSet`.
- */
- | {
-    type: "rollback-set";
-    runId: string;
-    createdAt: string;
-    runSummary: string;
-    roots: {
-        rootName: string;
-        checkpointId: string;
-        files: PatchFilePreview[];
-        externalPaths: string[];
-        attributionUnknown: boolean;
-    }[];
-};
-/**
- * A side-effecting action a tool wants to take, passed to `ctx.approve`. The
- * `kind` set grows as more mutating tools land; it drives the permission prompt.
- */
-export interface ApproveAction {
-    /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test" | "mcp";
-    /** Absolute resolved path the action targets (write/edit). */
-    path?: string;
-    /** The command to run (shell / test). */
-    command?: string;
-    /** MCP tool call (C.27): the server id and the tool name being invoked. The
-     * gate keys a session grant on this exact pair, so approving one MCP tool never
-     * covers another — and a server can never mark its own tool low-risk. */
-    server?: string;
-    tool?: string;
-    /**
-     * The declared workspace root this action acts in (C.26). `vcs` sets it to the
-     * root a pull request was selected for (C.26 Step 4): it may be non-primary, and
-     * the checkpoint gate attributes the vcs checkpoint to exactly this root. `shell`/
-     * `test` still set it to the primary as an attribution seam — their non-primary
-     * support is Step 5 (JC-β residual), so the gate hard-attributes them to the
-     * primary regardless of this value. File actions carry their root in the resolved
-     * absolute `path`/preview instead, so they leave this unset.
-     */
-    root?: string;
-    /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
-    preview?: ActionPreview;
-}
-/**
- * Ambient capabilities handed to every tool at execution time. Tools run on the
- * user's machine, so this is the only sanctioned door to the filesystem root
- * (`cwd`), configuration, logging, and the permission gate.
- */
-export interface ToolContext {
-    /** Absolute path the tool should treat as its working root. */
-    cwd: string;
-    /**
-     * The declared workspace root set for this session (C.26). Path-taking tools
-     * resolve *through* this rather than through `cwd`, so a multi-root session
-     * confines each call to the one root it selects. **Required** (C.26 Step 6): a
-     * construction site that fails to thread it is a *compile error*, not a runtime
-     * primary-default — closing the omission hole the old optional field left. The
-     * runtime always sets it; a single-root caller builds one with `sessionWorkspace`.
-     * (The type catches *omission*; it cannot catch a *fabricated* workspace threaded
-     * through — the `no-split-brain` grep guard covers that. See its header.) `cwd`
-     * remains equal to `workspace.primary().absPath`.
-     */
-    workspace: Workspace;
-    /** Fully-resolved CLI configuration. */
-    config: CruxyConfig;
-    /** Shared leveled logger (diagnostics to stderr, `print` to stdout). */
-    logger: Logger;
-    /**
-     * The approval gate every side-effecting tool funnels through, **before** any
-     * mutation. Returns a decision: `{allow:true}` to proceed, or `{allow:false,
-     * feedback?}` (a clean rejection whose feedback is surfaced to the agent).
-     * Backed by the risk-tiered `ApprovalService` (see src/approval); it may
-     * *throw* `CRUXY_E_APPROVAL_REQUIRED` when it can't ask (non-interactive),
-     * which propagates to the boundary rather than being swallowed. Read-only
-     * tools never call this.
-     */
-    requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
-    /**
-     * Whether per-root checkpointing is active for this session (C.26 step 3). It is
-     * the single fact that lifts the JC-1 non-primary-write refusal: a write to a
-     * non-primary root is permitted **iff** this is true, because a true value means
-     * a per-root checkpoint gate is wired that captures the write (get-or-creates the
-     * root's service and snapshots it) before it reaches disk. False/absent → a
-     * non-primary write is still refused with `CRUXY_E_MULTIROOT_WRITE_DEFERRED`, so
-     * a checkpoints-disabled session never widens un-restorable writes to siblings.
-     * Set together with `requestApproval` (the gate), so permit and capture are one
-     * decision — never lift-then-verify.
-     */
-    checkpointsActive?: boolean;
-    /**
-     * Isolation substrate for the shell + test tools (C.16). Present ONLY when
-     * the sandbox is enabled; when set, `run_command`/`run_tests` execute the
-     * approved command inside the container and NEVER on the host. Its mere
-     * presence is the switch — there is no host fallback once it is set (an
-     * unavailable runtime fails loud at construction, before this is ever
-     * populated). Absent → host execution, unchanged.
-     */
-    sandbox?: SandboxService;
-    /**
-     * Cooperative cancellation for in-flight tool work (C.33). Set on a subagent's
-     * ctx when it runs inside a parallel fan-out: when a fatal sibling failure or
-     * Ctrl-C aborts the batch, this signal fires, and a long-running `run_command`
-     * kills its whole process tree instead of leaving it orphaned — the C.12/C.16
-     * kill-tree discipline extended to N concurrent children. Absent → no external
-     * cancellation (the tool's own timeout still applies), unchanged behaviour.
-     */
-    signal?: AbortSignal;
-}
-/**
- * The one interface every tool implements. `parameters` is a zod schema; it both
- * validates the model's arguments and (via the registry) becomes the wire-format
- * JSON Schema advertised to the provider.
- */
-export interface Tool<Schema extends ZodTypeAny = ZodTypeAny> {
-    /** Unique, snake_case identifier the model uses to call the tool. */
-    name: string;
-    /** One-line description shown to the model. */
-    description: string;
-    /** Zod schema for the tool's input arguments. */
-    parameters: Schema;
-    /**
-     * An optional pre-rendered JSON Schema to advertise to the provider *verbatim*
-     * instead of deriving one from {@link parameters}. Used only by proxied tools
-     * whose schema originates elsewhere and cannot be reconstructed from zod — the
-     * MCP adapter (C.27) sets this to a server's own (bounds-capped) input schema
-     * while keeping a permissive `parameters` for local validation. Built-in tools
-     * leave it unset and are advertised from their zod schema as before.
-     */
-    rawInputSchema?: Record<string, unknown>;
-    /**
-     * Optional per-turn lifecycle hook (C.13). {@link Session.send} calls it on
-     * every tool in the session registry at the start of each user turn, before the
-     * model runs. A tool that carries per-episode state — e.g. `run_tests`' consecutive-
-     * failure breaker — resets it here so a fresh instruction starts clean, while that
-     * state still latches across the many model iterations *within* one turn. Tools
-     * with no per-turn state omit it (a subagent/one-shot run is a single episode, so
-     * a missing hook simply means the state lives for that whole run).
-     */
-    onTurnStart?(): void;
-    /** Run the tool against validated `input` and the ambient `ctx`. */
-    execute(input: z.infer<Schema>, ctx: ToolContext): Promise<ToolResult>;
-}
-export {};

package/dist/usage/collect.d.ts

@@ -1,53 +0,0 @@
-import type { Usage } from "@cruxy/sdk";
-import type { UsageRecord } from "./types.js";
-/**
- * Usage collection (C.22). Accumulates per-request usage exactly as the agent
- * loop reports it — one {@link UsageEntry} per completed model request — and
- * emits a {@link UsageRecord} for the run.
- *
- * The one honesty invariant: `usage: undefined` (the loop's signal that the
- * provider returned NO usage event for a request) is recorded as `undefined`
- * token counts — the honest "unknown". A provider-reported `0` arrives as a real
- * `Usage` and is stored as `0`. Nothing is estimated, re-tokenized, or
- * zero-filled, and this module makes ZERO network calls.
- */
-/**
- * Fold a streamed {@link Usage} event's cache counters into an accumulator.
- *
- * Phase-A prompt caching (Anthropic dev path only) reports `cache_read_*` /
- * `cache_creation_*` ONCE per request but echoes the same value on both the
- * `message_start` and terminal `message_delta` usage events — so we ASSIGN
- * (never `+=`) to avoid double-counting within a request. `undefined` is left
- * untouched: a provider that doesn't cache (the cruxy gateway, OpenAI-compat)
- * never sets these, so the accumulator's fields stay `undefined` — the honest
- * "unknown", never a fabricated `0`. A real reported `0` (cache in play, no read
- * this request) is captured as `0`.
- */
-export declare function accumulateCacheTokens(acc: Usage, ev: Usage): void;
-/** What the loop hands over for one completed request. */
-export interface RequestUsage {
-    /** The routing tier (C.30) the request ran on, if routing was active. */
-    tier?: string;
-    /**
-     * The provider's usage for THIS request, or `undefined` when the provider
-     * emitted no usage event (⇒ tokens are unknown, not zero).
-     */
-    usage?: Usage;
-}
-/** Wall clock as an injectable seam so tests are deterministic. */
-export type Clock = () => string;
-export declare class UsageCollector {
-    private readonly now;
-    private readonly entries;
-    constructor(now?: Clock);
-    /**
-     * Record one completed request. When `req.usage` is absent the entry's token
-     * counts stay `undefined` — the provider reported nothing, so we assert
-     * nothing. A real reported `0` is preserved as `0`.
-     */
-    record(req: RequestUsage): void;
-    /** How many requests have been recorded so far. */
-    get count(): number;
-    /** Snapshot the collected entries into a persistable {@link UsageRecord}. */
-    toRecord(runId: string, sessionId: string | undefined, startedAt: string): UsageRecord;
-}

package/dist/usage/cost.d.ts

@@ -1,19 +0,0 @@
-import type { PriceTable, TierPrice } from "./types.js";
-/**
- * Token → cost mapping (C.22). The whole discipline lives in one rule: a cost is
- * produced ONLY when the tier has a configured price AND at least one token side
- * is known. Otherwise the result is `undefined` — cost is omitted, tokens are
- * still shown, and NO dollar figure is ever fabricated. Prices are per MILLION
- * tokens (see {@link TierPrice}). Keyed by tier only (U.8 gag). No network.
- */
-/** The configured price for a tier, or `undefined` when the tier is unpriced. */
-export declare function priceForTier(tier: string, prices: PriceTable): TierPrice | undefined;
-/**
- * Compute the cost of a tier's usage, or `undefined` when it cannot be stated
- * honestly:
- *  - no configured price for the tier → `undefined` (cost omitted).
- *  - both token counts unknown → `undefined` (nothing real to price).
- * A known side is priced; an unknown side contributes nothing (never a
- * fabricated 0-token charge). tokens/1e6 × price, summed.
- */
-export declare function costFor(tier: string, inputTokens: number | undefined, outputTokens: number | undefined, prices: PriceTable): number | undefined;

package/dist/usage/index.d.ts

@@ -1,15 +0,0 @@
-/**
- * Usage telemetry + cost tracking (C.22) — LOCAL usage accounting only.
- *
- * NO-PHONE-HOME GUARANTEE: nothing here transmits anything. This module reads
- * and writes ONE local file under `~/.cruxy/usage` and renders to the terminal;
- * it imports no provider, no transport, and makes no `fetch`/HTTP call. The
- * `@cruxy/sdk` import below is a TYPE-only import (`Usage`), erased at build. A
- * future opt-in remote report would be a new, clearly-named seam — this build
- * ships nothing that sends. Asserted by the runtime + static no-phone-home tests.
- */
-export * from "./types.js";
-export { UsageCollector, accumulateCacheTokens, type RequestUsage, type Clock, } from "./collect.js";
-export { costFor, priceForTier } from "./cost.js";
-export { loadUsage, appendRun, usageStorePath } from "./store.js";
-export { summarizeRuns, renderSummary, formatCost, type SummarizeOptions, } from "./summary.js";

package/dist/usage/store.d.ts

@@ -1,37 +0,0 @@
-import { CruxyError } from "../errors/index.js";
-import { type UsageFile, type UsageRecord } from "./types.js";
-/**
- * The usage store (C.22): a single JSON file under `~/.cruxy/usage`, holding a
- * bounded, newest-last list of run records. Pure DATA — parsed with the strict
- * schema, NEVER eval'd — and written `0600` (personal accounting). This module
- * touches only the local filesystem; it makes ZERO network calls.
- *
- * Reads are non-fatal by contract: a missing file is empty (not an error); a
- * corrupt/unreadable one yields an empty result plus a coded
- * {@link usageRead} error the caller can surface and SKIP — a broken usage file
- * never crashes a run.
- */
-/** `~/.cruxy/usage/runs.json` — the single usage store file. */
-export declare function usageStorePath(): string;
-/**
- * Load and validate the store. Never throws. A missing file → empty, no error.
- * Invalid JSON or a schema mismatch → empty + a `CRUXY_E_USAGE_READ` error
- * (skip, don't crash). The raw text is parsed with `JSON.parse` only — a store
- * file is never executed, so a hand-edited file cannot run code.
- */
-export declare function loadUsage(file?: string): {
-    data: UsageFile;
-    error?: CruxyError;
-};
-/**
- * Append one run's usage, pruning oldest-first to the last `retention` runs.
- * Never throws — any failure (a corrupt existing file that cannot be safely
- * appended to, or a write error) is returned as a coded error for the caller to
- * downgrade to a warning, so persistence never takes a run down with it.
- */
-export declare function appendRun(record: UsageRecord, opts?: {
-    retention: number;
-    file?: string;
-}): {
-    error?: CruxyError;
-};

package/dist/usage/summary.d.ts

@@ -1,32 +0,0 @@
-import type { Theme } from "../theme/index.js";
-import type { PriceTable, UsageRecord, UsageSummary } from "./types.js";
-/**
- * Usage aggregation + rendering (C.22). Aggregation sums only KNOWN token
- * counts and counts the requests that reported none separately, so a total is
- * never inflated by a fabricated zero — and the renderer ALWAYS surfaces that
- * count, so a total can never be misread as complete while requests are silently
- * excluded. Costs appear only for priced tiers. Only tier names ever reach the
- * output (U.8 gag). Pure — no I/O, no network.
- */
-export interface SummarizeOptions {
-    prices: PriceTable;
-    /** Currency label to prefix costs; "" when the user configured none. */
-    currency: string;
-}
-/** Aggregate one or more run records into a {@link UsageSummary}. */
-export declare function summarizeRuns(runs: readonly UsageRecord[], opts: SummarizeOptions): UsageSummary;
-/**
- * Format a cost figure honestly: enough precision for small per-run costs,
- * trailing zeros trimmed. Prefixed by the currency label only when one is set
- * (never an assumed symbol). Callers pass a cost only when it was actually
- * computed (priced + known tokens).
- */
-export declare function formatCost(n: number, currency: string): string;
-/**
- * Render a {@link UsageSummary} to a single themed line. Honors the theme
- * end-to-end: NO_COLOR yields zero ANSI (identity stylers), and screen-reader
- * mode swaps the arrow glyphs for words. The count of requests that reported no
- * usage is ALWAYS shown when non-zero, so the total is never mistaken for a
- * complete accounting.
- */
-export declare function renderSummary(summary: UsageSummary, t: Theme): string;