@nathapp/nax-agent 0.1.0

package/dist/command-safety/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * P5 command-safety shadow: shared types.
+ *
+ * Spec: docs/superpowers/specs/2026-09-23-p5-command-safety-shadow-design.md.
+ * Observational only — except for the optional flag-for-review guard (US-003),
+ * which is also declared here: the shadow's row is a fact on disk, the
+ * guard's decision is a flag the caller routes. Nothing else typed here can
+ * change a verdict, delay a call or fail a call; the types exist so the row
+ * a later decision reads is exact.
+ */
+import type { CallIdentifiers } from "./identifiers.ts";
+/** The six harm categories. Also the ids of the six `noul` questions. */
+export declare const QUESTION_IDS: readonly ["deletes_data", "discards_work", "outside_project", "system_change", "network_send", "privilege"];
+export type QuestionId = (typeof QUESTION_IDS)[number];
+/** Options of the single `harm` choice question: `none` plus every category. */
+export declare const HARM_OPTIONS: readonly ["none", "deletes_data", "discards_work", "outside_project", "system_change", "network_send", "privilege"];
+export type HarmOption = (typeof HARM_OPTIONS)[number];
+/** The mechanical policy verdict, as recorded (never re-decided) by the shadow. */
+export interface MechanicalVerdict {
+    readonly verdict: "allow" | "ask" | "deny";
+    readonly breach: boolean;
+    readonly rule?: string;
+}
+/** The tool-audit ledger outcome of the call. */
+export type LedgerOutcome = "ok" | "error" | "denied" | "denied:ask";
+export interface FinalOutcome {
+    readonly ledger: LedgerOutcome;
+    readonly decidedBy?: string;
+}
+export interface ModelAnswers {
+    /** P(option) for the harm choice. */
+    readonly harm: Readonly<Record<HarmOption, number>>;
+    /** P(yes) per noul question. */
+    readonly noul: Readonly<Record<QuestionId, number>>;
+}
+export type ModelResult = {
+    readonly status: "answered";
+    readonly answers: ModelAnswers;
+    readonly model?: string;
+    readonly decisionId?: string;
+    readonly latencyMs: number;
+} | {
+    readonly status: "blocked";
+    readonly decisionId?: string;
+    readonly latencyMs: number;
+} | {
+    readonly status: "oversize";
+    readonly latencyMs: number;
+} | {
+    readonly status: "unavailable";
+    readonly error: string;
+    readonly latencyMs?: number;
+};
+/** One agent-authored command, as observed right after `policy.check`. */
+export interface Observation extends CallIdentifiers {
+    readonly command: string;
+    readonly identity: "Bash" | "Exec";
+    /** Exec only: the argv verbatim. `command` is it joined with single spaces. */
+    readonly argv?: readonly string[];
+    readonly stage: string;
+    readonly storyId?: string;
+    readonly mechanical: MechanicalVerdict;
+    /**
+     * Bash only: the directory the command starts in (the policy root). An
+     * Exec call's cwd is chosen by the tool, so it arrives with `ExecRun`.
+     */
+    readonly cwd?: string;
+}
+/** Exec only: what the tool actually ran, known once it has run. */
+export interface ExecRun {
+    /** The argv after normalization. */
+    readonly executed: readonly string[];
+    /**
+     * The directory it ran in (the package dir or the repo root). The Exec
+     * branch always sets it; optional because `audit` is shared with tools
+     * (Bash, Git) that report `executed` without a cwd.
+     */
+    readonly cwd?: string;
+}
+/** Per-story shadow. Every method is total: it never throws. */
+export interface CommandShadow {
+    observe(key: string, obs: Observation): void;
+    /**
+     * Attach the ledger outcome and, for an Exec call, what actually ran. `run`
+     * is omitted for every other identity and whenever the call never ran.
+     */
+    settle(key: string, outcome: FinalOutcome, run?: ExecRun): void;
+    /** Resolves within one timeout; afterwards every pending row has been written. */
+    drain(): Promise<void>;
+    /**
+     * Opt-in flag-for-review guard (US-003). When present, `assess` shares the
+     * shadow's rule baseline and classifier cache — the guard never
+     * re-classifies and never rejects, so absence is the safe default.
+     */
+    readonly guard?: CommandGuard;
+}
+/** The guard's total assessment input. Mirrors `Observation` minus the fields the guard does not need. */
+export interface GuardInput {
+    /** The policy identity's command string; Exec passes `argv.join(" ")`. */
+    readonly command: string;
+    /** The policy root, used to score the rules and judge the temp-only exemption. */
+    readonly cwd?: string;
+    /** The session's sandbox confines temp writes (#2285). */
+    readonly tempConfined: boolean;
+}
+/** A flagged command: what the guard wants reviewed, and why. */
+export interface GuardDecision {
+    readonly flagged: boolean;
+    /** 0..1, the composite score behind the flag. */
+    readonly score: number;
+    /** The threshold the guard was configured with. Carried on every decision. */
+    readonly threshold: number;
+    /** Which contributor named the verdict. */
+    readonly basis: "model" | "rules" | "temp-only";
+    /**
+     * The dominant category behind the flag, when one is known.
+     *
+     * Absent for an unflagged decision and for a `blocked` model with no rule
+     * hit. Under the temp-only exemption, `outside_project` is skipped even
+     * when the rules alone would have named it.
+     */
+    readonly category?: QuestionId;
+}
+/**
+ * The guard exposes only the total assessment the shadow shares. It never
+ * rejects: every method resolves; nothing here can stop a command on its
+ * own (master plan D4a).
+ */
+export interface CommandGuard {
+    readonly threshold: number;
+    /** Total: never rejects. */
+    assess(input: GuardInput): Promise<GuardDecision>;
+}
+export interface RuleResult {
+    readonly version: number;
+    readonly hits: Readonly<Record<QuestionId, boolean>>;
+    readonly error?: string;
+}
+/** One line of `<outputDir>/command-safety/<runId>.jsonl` (spec 7.3). */
+export interface CommandSafetyRow extends CallIdentifiers {
+    readonly at: string;
+    readonly runId: string;
+    readonly storyId?: string;
+    readonly stage: string;
+    readonly identity: "Bash" | "Exec";
+    readonly command: string;
+    readonly argv?: readonly string[];
+    /**
+     * Exec only: the argv the Exec tool executed (after normalization); absent
+     * when the call did not run. Distinct from `argv`, which is the model's
+     * requested argv — and the text `command` is classified on.
+     */
+    readonly executed?: readonly string[];
+    /**
+     * The directory the command starts in: the policy root for Bash, the
+     * directory the tool ran it in for Exec (absent when it did not run).
+     * Recorded for labelling only; it is not part of the model's state.
+     */
+    readonly cwd?: string;
+    readonly mechanical: MechanicalVerdict;
+    readonly outcome: {
+        readonly ledger: LedgerOutcome | "unsettled";
+        readonly decidedBy?: string;
+    };
+    readonly rules: RuleResult;
+    /**
+     * Observable, never-decided signals recorded beside the row (US-005).
+     * `tmpWrite` is true when the command writes to a literal `/tmp` or
+     * `/private/tmp` path outside nax's own `/tmp/nax-*` run directories. It is
+     * recorded only: not a `QuestionId`, not in `rules.hits`, and it changes no
+     * verdict.
+     */
+    readonly signals: {
+        readonly tmpWrite: boolean;
+    };
+    readonly model: {
+        readonly status: ModelResult["status"] | "cached";
+        readonly questionSetVersion: number;
+        readonly answers?: ModelAnswers;
+        readonly model?: string;
+        readonly decisionId?: string;
+        readonly latencyMs?: number;
+        readonly error?: string;
+    };
+}

package/dist/command-safety/types.js

@@ -0,0 +1,21 @@
+/**
+ * P5 command-safety shadow: shared types.
+ *
+ * Spec: docs/superpowers/specs/2026-09-23-p5-command-safety-shadow-design.md.
+ * Observational only — except for the optional flag-for-review guard (US-003),
+ * which is also declared here: the shadow's row is a fact on disk, the
+ * guard's decision is a flag the caller routes. Nothing else typed here can
+ * change a verdict, delay a call or fail a call; the types exist so the row
+ * a later decision reads is exact.
+ */
+/** The six harm categories. Also the ids of the six `noul` questions. */
+export const QUESTION_IDS = [
+    "deletes_data",
+    "discards_work",
+    "outside_project",
+    "system_change",
+    "network_send",
+    "privilege",
+];
+/** Options of the single `harm` choice question: `none` plus every category. */
+export const HARM_OPTIONS = ["none", ...QUESTION_IDS];

package/dist/config/bash-approval.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `bashApproval` mode axis (ADR-030).
+ *
+ * Named `raw | gated | escalate` rather than `unrestricted | ...` on purpose:
+ * `unrestricted` already names a permission PROFILE
+ * (`src/config/permissions.ts:17`), and a mode value colliding with a profile
+ * name is a config foot-gun. Profiles answer "which tools is this stage
+ * granted"; the mode answers "how is a bash command string adjudicated".
+ */
+import { z } from "zod";
+export declare const BashApprovalModeSchema: z.ZodEnum<{
+    escalate: "escalate";
+    gated: "gated";
+    raw: "raw";
+}>;
+export type BashApprovalMode = z.infer<typeof BashApprovalModeSchema>;
+/**
+ * BUG-20 — derived from the schema, never hand-written at a second site. The
+ * `execution` default literal in `schemas.ts` must reference THIS constant:
+ * zod does not re-parse a `.default()` value, so a literal there drifts from
+ * the field's own default the moment either changes.
+ */
+export declare const DEFAULT_BASH_APPROVAL_MODE: BashApprovalMode;
+/**
+ * `bashApprovalOps` (ADR-030): the named surface of mode resolution.
+ *
+ * Deliberately a pure function, not an async provider chain. The human
+ * resolver is the existing `AskResolver`, which the `ask` tier already reaches
+ * (`src/tools/runtime.ts:378`); a second chain would duplicate it. A future
+ * model-based classifier attaches at the POST-ALLOW seam in `runtime.ts`
+ * instead, narrowing allow → ask, which is a different insertion point.
+ */
+export declare function resolveBashApproval(global: BashApprovalMode | undefined, perStage: BashApprovalMode | undefined): BashApprovalMode;

package/dist/config/bash-approval.js

@@ -0,0 +1,30 @@
+/**
+ * The `bashApproval` mode axis (ADR-030).
+ *
+ * Named `raw | gated | escalate` rather than `unrestricted | ...` on purpose:
+ * `unrestricted` already names a permission PROFILE
+ * (`src/config/permissions.ts:17`), and a mode value colliding with a profile
+ * name is a config foot-gun. Profiles answer "which tools is this stage
+ * granted"; the mode answers "how is a bash command string adjudicated".
+ */
+import { z } from "zod";
+export const BashApprovalModeSchema = z.enum(["raw", "gated", "escalate"]);
+/**
+ * BUG-20 — derived from the schema, never hand-written at a second site. The
+ * `execution` default literal in `schemas.ts` must reference THIS constant:
+ * zod does not re-parse a `.default()` value, so a literal there drifts from
+ * the field's own default the moment either changes.
+ */
+export const DEFAULT_BASH_APPROVAL_MODE = BashApprovalModeSchema.parse("raw");
+/**
+ * `bashApprovalOps` (ADR-030): the named surface of mode resolution.
+ *
+ * Deliberately a pure function, not an async provider chain. The human
+ * resolver is the existing `AskResolver`, which the `ask` tier already reaches
+ * (`src/tools/runtime.ts:378`); a second chain would duplicate it. A future
+ * model-based classifier attaches at the POST-ALLOW seam in `runtime.ts`
+ * instead, narrowing allow → ask, which is a different insertion point.
+ */
+export function resolveBashApproval(global, perStage) {
+    return perStage ?? global ?? DEFAULT_BASH_APPROVAL_MODE;
+}

package/dist/config/catalog-overrides.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Catalog-override and thinking-level types: the config shapes the native
+ * agent reads (S1 spec section 4.2, port 4). Pure types with no imports, so
+ * they move into nax-agent unchanged; `schema-types.ts` re-exports them for
+ * nax's config schema.
+ */
+/**
+ * Reasoning levels the catalog may declare, mirrored from nax-ai's
+ * `ThinkingLevel` union (nax#1982). nax-ai cannot be imported here
+ * (`packages/repo-tooling/scripts/check-nax-ai-imports.ts`), so the union is hand-mirrored;
+ * `test/unit/agents/native/models.test.ts` pins it against
+ * `THINKING_LEVELS` in `src/agents/native/models.ts`, which is itself a
+ * compile-time-exhaustive `Record<ThinkingLevel, true>` over the nax-ai
+ * union.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Rates for a catalog override, in the CATALOG's vocabulary (`input`,
+ * `output`, `cacheRead`, `cacheWrite`, per 1M tokens) — not `ConfigPricing`'s
+ * `*Per1M` names. This block describes the simulated catalog entry, so it
+ * speaks the catalog's language; `ModelDef.pricing` remains the cost-math
+ * override in nax's own vocabulary.
+ */
+export interface CatalogPricing {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/**
+ * nax#2191: OpenRouter-compatible provider routing, mirrored from nax-ai
+ * 0.1.15's `OpenRouterRouting`. Snake_case on purpose — keys are wire field
+ * names and pass through unmapped. The protocol-side rejection (non-
+ * `openai-completions` protocols, empty declaration) is nax-ai's, owned in
+ * `providers/override-model.ts`'s `assertOverrideModelRouting`.
+ *
+ * `sort: "latency"` / `"throughput"` pair with `quantizations` in the typical
+ * case: OpenRouter's default routing for a slug is overwhelmingly a single
+ * quantization from a single endpoint, and a sort change may otherwise pick
+ * a lower-precision endpoint that the call site never intended (the issue's
+ * own note). The schema does not enforce the pairing — that is UX clutter
+ * for an opt-in override — but `docs/guides/configuration.md` and the config
+ * description should call it out.
+ */
+export interface OpenRouterRouting {
+    allow_fallbacks?: boolean;
+    require_parameters?: boolean;
+    data_collection?: "deny" | "allow";
+    zdr?: boolean;
+    order?: readonly string[];
+    only?: readonly string[];
+    ignore?: readonly string[];
+    quantizations?: readonly string[];
+    sort?: "price" | "throughput" | "latency";
+}
+/**
+ * One complete catalog entry for a model the bundled pi-ai snapshot does not
+ * know. Complete, not a patch: nax-ai's `normaliseCatalog` replaces any
+ * same-id entry wholesale and lazily creates the provider bucket, so nothing
+ * here may be left to the bundled value.
+ */
+export interface CatalogModelOverride {
+    id: string;
+    /** nax-ai protocol id, e.g. "openai-completions" or "anthropic-messages". */
+    protocol: string;
+    contextWindow: number;
+    /**
+     * Output ceiling. Optional: when absent, nax-ai inherits the ceiling of the
+     * bundled sibling it synthesises the override from, which can be smaller
+     * than the newer model's real one (nax-ai 0.1.11, nax#1982).
+     */
+    maxTokens?: number;
+    supportsTools: boolean;
+    thinkingLevels: ThinkingLevel[];
+    pricing: CatalogPricing;
+    /**
+     * nax#2191: OpenRouter-compatible provider routing forwarded verbatim to
+     * nax-ai's `ResolvedModel.openRouterRouting`. Reaches the wire only on
+     * `protocol: "openai-completions"` (nax-ai `assertOverrideModelRouting`).
+     */
+    openRouterRouting?: OpenRouterRouting;
+}
+/** Provider-scoped catalog overrides — maps 1:1 onto nax-ai's `ProviderOverride[]`. */
+export interface ProviderCatalogOverride {
+    provider: string;
+    /**
+     * Provider-wide endpoint redirect (nax#2019). Applies to the whole provider,
+     * not to `models` individually, despite sitting alongside a model list.
+     */
+    baseUrl?: string;
+    /** Provider-wide extra request headers (nax#2019). May carry credentials. */
+    headers?: Record<string, string>;
+    models: CatalogModelOverride[];
+}

package/dist/config/catalog-overrides.js

@@ -0,0 +1,7 @@
+/**
+ * Catalog-override and thinking-level types: the config shapes the native
+ * agent reads (S1 spec section 4.2, port 4). Pure types with no imports, so
+ * they move into nax-agent unchanged; `schema-types.ts` re-exports them for
+ * nax's config schema.
+ */
+export {};

package/dist/config/native-agent/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The agent name that routes to the in-process native adapter.
+ *
+ * Its own nested barrel so the nax-agent move set can import the value
+ * (`@/config/native-agent`) without loading the config barrel (S1 spec
+ * section 4.2, port 4). `agent-defaults.ts` re-exports it for config.
+ */
+export declare const NATIVE_AGENT_NAME = "native";

package/dist/config/native-agent/index.js

@@ -0,0 +1,8 @@
+/**
+ * The agent name that routes to the in-process native adapter.
+ *
+ * Its own nested barrel so the nax-agent move set can import the value
+ * (`@/config/native-agent`) without loading the config barrel (S1 spec
+ * section 4.2, port 4). `agent-defaults.ts` re-exports it for config.
+ */
+export const NATIVE_AGENT_NAME = "native";

package/dist/config/schemas-sandbox.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `execution.sandbox` (P4, ADR-030 amendment): the OS sandbox around
+ * agent-authored Bash and RunCommand Exec commands.
+ *
+ * Nested objects use `.prefault({})`, not `.default({})`: in zod 4 a
+ * `.default()` value short-circuits parsing, so `{ filesystem: {} }` would
+ * yield `filesystem: {}` with no `allowWrite`.
+ */
+import { z } from "zod";
+/**
+ * Glob metacharacters. srt on Linux silently DROPS a policy entry containing
+ * any of them (spec F1), so every sandbox path must be literal.
+ */
+export declare const SANDBOX_GLOB_CHARS: RegExp;
+export declare const SandboxConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    backend: z.ZodDefault<z.ZodEnum<{
+        srt: "srt";
+    }>>;
+    filesystem: z.ZodPrefault<z.ZodObject<{
+        allowWrite: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        denyRead: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowSharedTmp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    network: z.ZodPrefault<z.ZodObject<{
+        allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
+/** BUG-20: derived, never hand-written at a second site. */
+export declare const DEFAULT_SANDBOX_CONFIG: SandboxConfig;

package/dist/config/schemas-sandbox.js

@@ -0,0 +1,45 @@
+/**
+ * `execution.sandbox` (P4, ADR-030 amendment): the OS sandbox around
+ * agent-authored Bash and RunCommand Exec commands.
+ *
+ * Nested objects use `.prefault({})`, not `.default({})`: in zod 4 a
+ * `.default()` value short-circuits parsing, so `{ filesystem: {} }` would
+ * yield `filesystem: {}` with no `allowWrite`.
+ */
+import { z } from "zod";
+/**
+ * Glob metacharacters. srt on Linux silently DROPS a policy entry containing
+ * any of them (spec F1), so every sandbox path must be literal.
+ */
+export const SANDBOX_GLOB_CHARS = /[*?[\]{}]/;
+const literalPath = z
+    .string()
+    .refine((p) => !SANDBOX_GLOB_CHARS.test(p), "sandbox paths must be literal: no * ? [ ] { } (spec F1)");
+export const SandboxConfigSchema = z.object({
+    /** On by default since the P4 exit runs (spec S1); `raw` bash refuses when enabled but unavailable. */
+    enabled: z.boolean().default(true),
+    /** One backend today; the interface admits a container backend later. */
+    backend: z.enum(["srt"]).default("srt"),
+    filesystem: z
+        .object({
+        /** Extra write roots, "~" expanded, relative paths resolved against the story root. */
+        allowWrite: z.array(literalPath).default([]),
+        /** Extra read denies, "~" expanded. */
+        denyRead: z.array(literalPath).default([]),
+        /**
+         * US-002: grant the shared temp roots (`os.tmpdir()`, `/tmp`) as well as
+         * the run's own temp root. Off by default — a sandboxed command writes
+         * temp files under `$TMPDIR` and nowhere else.
+         */
+        allowSharedTmp: z.boolean().default(false),
+    })
+        .prefault({}),
+    network: z
+        .object({
+        /** absent = unrestricted (spec S2); [] = no network; a list = allow-list. */
+        allowedDomains: z.array(z.string()).optional(),
+    })
+        .prefault({}),
+});
+/** BUG-20: derived, never hand-written at a second site. */
+export const DEFAULT_SANDBOX_CONFIG = SandboxConfigSchema.parse({});

package/dist/cost/core/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The cost core that moves into nax-agent (spec R4, section 5.2): pricing math
+ * over nax-ai's usage and pricing types. nax-only cost code (rate-card policy,
+ * catalog lookup, reporting helpers) stays behind `@/agents/cost`.
+ */
+export { estimateCostUsd, priceCall } from "../estimate.ts";
+export type { Pricing, PricingRates, PricingTier, TokenUsage } from "../standard-types.ts";
+export { addTokenUsage, inputClassTokens } from "../usage-math.ts";

package/dist/cost/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * The cost core that moves into nax-agent (spec R4, section 5.2): pricing math
+ * over nax-ai's usage and pricing types. nax-only cost code (rate-card policy,
+ * catalog lookup, reporting helpers) stays behind `@/agents/cost`.
+ */
+export { estimateCostUsd, priceCall } from "../estimate.js";
+export { addTokenUsage, inputClassTokens } from "../usage-math.js";

package/dist/cost/estimate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tier-aware USD cost estimator.
+ *
+ * Relocated from `src/agents/native/models.ts` per US-001 so both the ACP and
+ * native paths share one implementation. Behaviour matches the previous
+ * native version:
+ * - `cacheReadPer1M` / `cacheCreationPer1M` fall back to `inputPer1M` when
+ *   absent.
+ * - Tier selection: the highest `inputTokensAbove` whose threshold is strictly
+ *   less than the total input-class usage wins for the WHOLE request; ties
+ *   resolve to the higher threshold (the array is taken in declaration
+ *   order, so the last tier whose threshold is exceeded is the winner).
+ * - What counts toward the threshold: input + cacheRead + cacheCreation.
+ *
+ * `inputClassTokens` is re-exported from here so callers using
+ * `@/agents/cost` get the helper without reaching into `./calculate`.
+ */
+import type { Pricing, PricingRates, TokenUsage } from "./standard-types.ts";
+import { inputClassTokens } from "./usage-math.ts";
+/**
+ * `inputClassTokens` is re-exported from here so callers using
+ * `estimateCostUsd` can size the prompt with the same definition tier
+ * selection uses.
+ */
+export { inputClassTokens };
+/**
+ * Price one call. `costUsd` and `resolvedRates` come from one tier selection,
+ * so recorded rates always reproduce the recorded cost.
+ */
+export declare function priceCall(usage: TokenUsage, rates: Pricing): {
+    costUsd: number;
+    resolvedRates: PricingRates;
+};
+export declare function estimateCostUsd(usage: TokenUsage, rates: Pricing): number;

package/dist/cost/estimate.js

@@ -0,0 +1,65 @@
+/**
+ * Tier-aware USD cost estimator.
+ *
+ * Relocated from `src/agents/native/models.ts` per US-001 so both the ACP and
+ * native paths share one implementation. Behaviour matches the previous
+ * native version:
+ * - `cacheReadPer1M` / `cacheCreationPer1M` fall back to `inputPer1M` when
+ *   absent.
+ * - Tier selection: the highest `inputTokensAbove` whose threshold is strictly
+ *   less than the total input-class usage wins for the WHOLE request; ties
+ *   resolve to the higher threshold (the array is taken in declaration
+ *   order, so the last tier whose threshold is exceeded is the winner).
+ * - What counts toward the threshold: input + cacheRead + cacheCreation.
+ *
+ * `inputClassTokens` is re-exported from here so callers using
+ * `@/agents/cost` get the helper without reaching into `./calculate`.
+ */
+import { inputClassTokens } from "./usage-math.js";
+/**
+ * `inputClassTokens` is re-exported from here so callers using
+ * `estimateCostUsd` can size the prompt with the same definition tier
+ * selection uses.
+ */
+export { inputClassTokens };
+/** The greatest `inputTokensAbove` the request's input-class total exceeds wins, for the whole request. */
+function selectRates(rates, totalInputClassTokens) {
+    let winner = rates;
+    if (rates.tiers !== undefined) {
+        let bestThreshold = Number.NEGATIVE_INFINITY;
+        for (const tier of rates.tiers) {
+            if (totalInputClassTokens > tier.inputTokensAbove && tier.inputTokensAbove > bestThreshold) {
+                winner = tier;
+                bestThreshold = tier.inputTokensAbove;
+            }
+        }
+    }
+    return winner;
+}
+function resolveRates(rates, totalInputClassTokens) {
+    const effective = selectRates(rates, totalInputClassTokens);
+    return {
+        input: effective.input,
+        output: effective.output,
+        cacheRead: effective.cacheRead ?? effective.input,
+        cacheWrite: effective.cacheWrite ?? effective.input,
+    };
+}
+/**
+ * Price one call. `costUsd` and `resolvedRates` come from one tier selection,
+ * so recorded rates always reproduce the recorded cost.
+ */
+export function priceCall(usage, rates) {
+    const resolvedRates = resolveRates(rates, inputClassTokens(usage));
+    const inputCost = (usage.inputTokens / 1_000_000) * resolvedRates.input;
+    const outputCost = (usage.outputTokens / 1_000_000) * resolvedRates.output;
+    const cacheReadCost = ((usage.cacheReadTokens ?? 0) / 1_000_000) * resolvedRates.cacheRead;
+    const cacheWriteCost = ((usage.cacheWriteTokens ?? 0) / 1_000_000) * resolvedRates.cacheWrite;
+    return {
+        costUsd: inputCost + outputCost + cacheReadCost + cacheWriteCost,
+        resolvedRates,
+    };
+}
+export function estimateCostUsd(usage, rates) {
+    return priceCall(usage, rates).costUsd;
+}

package/dist/cost/model-spec.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model spec parsing.
+ *
+ * nax profiles name models with a trailing reasoning-effort suffix, e.g.
+ * "gpt-5.6-luna[high]". This is a nax-level convention, not an artifact of any
+ * one transport: both agent transports consume it, each decomposing it before
+ * the value reaches its own destination.
+ *
+ * - The ACP path decomposes it before the bare model id reaches acpx. The
+ *   suffix form mirrors codex-acp's legacy session/set_model identifier
+ *   format; acpx 0.13+ selects models through the config-option channel
+ *   instead, where the id is bare and effort is a sibling option
+ *   (reasoning_effort).
+ * - The native path decomposes it before the bare model id reaches
+ *   `client.model()`, and forwards the effort as a `thinking` level on the
+ *   request (see `src/agents/native/models.ts`).
+ *
+ * Only a well-formed trailing [..] is treated as a suffix. Anything else is passed
+ * through as a model id so a profile typo surfaces as the adapter's own
+ * unadvertised-model error rather than a silent rewrite.
+ */
+export interface ModelSpec {
+    /** Model id with any effort suffix removed. Safe to pass to acpx as --model. */
+    readonly model: string;
+    /** Reasoning effort from the suffix, when one was present. */
+    readonly effort?: string;
+}
+export declare function parseModelSpec(raw: string): ModelSpec;

package/dist/cost/model-spec.js

@@ -0,0 +1,29 @@
+/**
+ * Model spec parsing.
+ *
+ * nax profiles name models with a trailing reasoning-effort suffix, e.g.
+ * "gpt-5.6-luna[high]". This is a nax-level convention, not an artifact of any
+ * one transport: both agent transports consume it, each decomposing it before
+ * the value reaches its own destination.
+ *
+ * - The ACP path decomposes it before the bare model id reaches acpx. The
+ *   suffix form mirrors codex-acp's legacy session/set_model identifier
+ *   format; acpx 0.13+ selects models through the config-option channel
+ *   instead, where the id is bare and effort is a sibling option
+ *   (reasoning_effort).
+ * - The native path decomposes it before the bare model id reaches
+ *   `client.model()`, and forwards the effort as a `thinking` level on the
+ *   request (see `src/agents/native/models.ts`).
+ *
+ * Only a well-formed trailing [..] is treated as a suffix. Anything else is passed
+ * through as a model id so a profile typo surfaces as the adapter's own
+ * unadvertised-model error rather than a silent rewrite.
+ */
+/** Matches "<model>[<effort>]" where neither part contains a bracket. */
+const EFFORT_SUFFIX = /^([^[\]]+)\[([^[\]]+)\]$/;
+export function parseModelSpec(raw) {
+    const match = EFFORT_SUFFIX.exec(raw);
+    if (!match)
+        return { model: raw };
+    return { model: match[1], effort: match[2] };
+}

package/dist/cost/standard-types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one usage and rate vocabulary (S1 spec, ruling R3): nax-ai's types.
+ *
+ * Staging re-export for S1-1. Code outside src/agents/native and
+ * src/agents/catalog takes these types from here, so check-nax-ai-imports
+ * keeps a single allow-listed file. In S1-5 this becomes a re-export in
+ * packages/nax-agent and the allow-list entry is removed.
+ */
+export type { Pricing, PricingRates, PricingTier, TokenUsage } from "@nathapp/nax-ai";

package/dist/cost/standard-types.js

@@ -0,0 +1 @@
+export {};