@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/spend/budget.d.ts

@@ -0,0 +1,123 @@
+import type { SpendLedger } from './store';
+/** Why provisioning was refused, with every number the decision used. */
+export interface ComputeBudgetRefusal {
+    readonly workspaceId: string;
+    /** The cap, unsigned nanodollars. */
+    readonly limitNanoUsd: number;
+    /** Cumulative settled compute spend for this workspace, unsigned nanodollars. */
+    readonly settledNanoUsd: number;
+    /** How far past the cap it already is. */
+    readonly overageNanoUsd: number;
+    readonly at: number;
+}
+/**
+ * Provisioning refused because the workspace is already past its compute cap.
+ *
+ * Correctable by design: every number the decision used is on the error, so a
+ * product can render "this workspace has spent $X of its $Y compute budget" and
+ * an operator can raise the cap or investigate without reading logs.
+ *
+ * This is the failure mode the module exists to produce. A platform billing
+ * defect that used to end in a silent negative balance now ends in provisioning
+ * stopping and something loud happening instead.
+ */
+export declare class ComputeBudgetExceededError extends Error {
+    readonly workspaceId: string;
+    readonly limitNanoUsd: number;
+    readonly settledNanoUsd: number;
+    readonly overageNanoUsd: number;
+    constructor(refusal: ComputeBudgetRefusal);
+}
+/**
+ * A per-workspace cap on sandbox compute.
+ *
+ * `/billing`'s budget primitive caps MODEL keys, and it works because the
+ * platform enforces the cap at the key it minted. Sandbox compute has no such
+ * key: a box bills the shared company wallet, so nothing upstream refuses. This
+ * carries the same shape to the one place a consumer can still act — the moment
+ * before it asks for another box.
+ *
+ * `settledNanoUsd` is a callback rather than a number because the authority is
+ * the platform ledger, not this package: the product reads the same rows it
+ * hands the reconciler. Cache it if the read is expensive; a cap is a
+ * coarse-grained control and a slightly stale total still refuses.
+ */
+export interface ComputeBudget {
+    /** The cap, unsigned nanodollars. */
+    readonly limitNanoUsd: number;
+    /** Cumulative settled compute spend for the workspace, unsigned nanodollars. */
+    readonly settledNanoUsd: (workspaceId: string) => Promise<number> | number;
+    /**
+     * Called on every refusal, before the error is thrown. This is the alert
+     * seam: a refusal nobody hears is a product that silently stopped working.
+     */
+    readonly onRefusal?: (refusal: ComputeBudgetRefusal) => void;
+    /** Injectable clock (epoch ms). Default `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Throw {@link ComputeBudgetExceededError} when the workspace is already past
+ * its cap. Returns normally — and reads nothing — when no budget is configured.
+ *
+ * Deliberately a pre-check against spend ALREADY SETTLED, not a reservation
+ * against spend about to happen: settlement lags provisioning by design (the
+ * platform's durable settlement queue), so there is no instant at which a
+ * consumer could hold an accurate running total. The cap therefore overshoots by
+ * at most the unsettled tail, which is bounded by the box's own idle timeout.
+ * A cap that refuses one box late is worth far more than one that cannot be
+ * implemented honestly.
+ */
+export declare function assertComputeBudget(budget: ComputeBudget | undefined, workspaceId: string): Promise<void>;
+/**
+ * What `/sandbox` reports once a box is provisioned, reused or resumed.
+ *
+ * Structurally identical to `SandboxProvisionedObservation` in `/sandbox`, and
+ * deliberately re-declared rather than imported: `/spend` composes `/sandbox`,
+ * so a type import in the other direction would invert the dependency. The two
+ * are pinned together by a compile-time assignment in this module's tests.
+ */
+export interface SpendProvisionObservation {
+    readonly workspaceId: string;
+    readonly userId?: string;
+    readonly sandboxId: string;
+    readonly boxKey?: string | undefined;
+    readonly idleTimeoutSeconds: number;
+    readonly maxLifetimeSeconds?: number | undefined;
+    readonly at: number;
+}
+/**
+ * The optional seam `EnsureWorkspaceSandboxOptions.spend` and the turn
+ * primitives' `spend` option both accept. One object, wired in both places.
+ */
+export interface SandboxSpendSeam {
+    beforeProvision?(input: {
+        workspaceId: string;
+        userId?: string;
+    }): Promise<void> | void;
+    onProvisioned?(observation: SpendProvisionObservation): Promise<void> | void;
+    /** Synchronous by contract — it sits on the turn path. See `createSandboxSpendHooks`. */
+    onActivity?(input: {
+        sandboxId: string;
+        at: number;
+    }): void;
+}
+export interface SandboxSpendHooksOptions {
+    /** Records box lifecycle. Omit to run the budget guard alone. */
+    readonly ledger?: SpendLedger;
+    /** Refuses provisioning past a cap. Omit to record alone. */
+    readonly budget?: ComputeBudget;
+    /**
+     * Called when RECORDING fails. Recording is best-effort — a bookkeeping
+     * failure must never take down the provisioning it is bookkeeping — so this
+     * is the only place such a failure is visible. A refusal is NOT routed here;
+     * refusals throw, by design.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Build the object to hand `ensureWorkspaceSandbox`'s `spend` option.
+ *
+ * Wiring it is the entire adoption cost: one field, and the product's boxes are
+ * both budget-capped and recorded.
+ */
+export declare function createSandboxSpendHooks(options: SandboxSpendHooksOptions): SandboxSpendSeam;

package/dist/spend/ceiling.d.ts

@@ -0,0 +1,51 @@
+import type { ExpectedCeiling, SpendBoxRecord } from './types';
+/**
+ * Slack allowed between the product's bound and what the platform settled,
+ * before an overage is called a discrepancy. 15 minutes.
+ *
+ * Not a guess: it is the platform's OWN staleness threshold for compute
+ * settlement. Its runbook clears an incident when
+ * `/health computeSettlement.oldestAgeSeconds` is "back under 900" — so 900 s is
+ * the age the platform itself treats as normal settlement lag, and anything
+ * inside it is drift the platform has already declared acceptable. Below that a
+ * product would alert on the platform's ordinary queue behaviour; far above it
+ * the tolerance starts eating the signal, because the idle window it must stay
+ * well under is 3600 s in every shipped product.
+ *
+ * It is a caller parameter because a product that asks for a shorter idle
+ * timeout must shrink this with it.
+ */
+export declare const DEFAULT_CEILING_TOLERANCE_MS = 900000;
+export interface ComputeExpectedCeilingOptions {
+    /** The instant the reconciliation treats as "now", epoch ms. */
+    readonly asOf: number;
+    /** Slack before an overage counts. Default {@link DEFAULT_CEILING_TOLERANCE_MS}. */
+    readonly toleranceMs?: number;
+}
+/**
+ * The upper bound on how long one box could honestly have been billable.
+ *
+ * The whole design constraint is that this must stay an UPPER bound under
+ * everything the product cannot see. Three such blind spots exist, and they
+ * pull in different directions:
+ *
+ * - **Platform-side suspends.** The platform can park a box the product never
+ *   hears about. That only ever REDUCES real billable time, so an upper bound
+ *   is unaffected and nothing here widens for it.
+ * - **Detached runs.** The product dispatches work and disconnects. The box
+ *   keeps working — and billing — after the last activity the product saw, so
+ *   `lastActivityAt` understates the truth. An unfinished detached run
+ *   therefore abandons the activity-based bound entirely rather than reporting
+ *   a bound it cannot support.
+ * - **Reconnects.** A browser or worker re-attaches and work resumes. This
+ *   needs no special case: a reconnect is recorded as activity, the fold takes
+ *   the max, and the horizon moves out on its own.
+ *
+ * The bound that rescues the detached case is `maxLifetimeSeconds`. The platform
+ * destroys the box at `createdAt + maxLifetimeSeconds` no matter what anyone
+ * observed, so a product that asks for one holds a hard bound that survives
+ * every blind spot above. Both shipped products ask for 86 400 s, which is why
+ * the incident — 124 to 268 hours settled against boxes with a 24-hour
+ * lifetime — is detectable with no lifecycle bookkeeping at all.
+ */
+export declare function computeExpectedCeiling(record: SpendBoxRecord, options: ComputeExpectedCeilingOptions): ExpectedCeiling;

package/dist/spend/cli-args.d.ts

@@ -0,0 +1,20 @@
+import type { ReconcileSpendOptions } from './reconcile';
+/** A usage or config problem — exit code 2, never a finding. */
+export declare class SpendUsageError extends Error {
+}
+export declare const USAGE: string;
+export interface SpendCliArgs {
+    readonly configFile: string;
+    readonly json: boolean;
+    readonly asOf: number | undefined;
+    readonly skip: readonly string[];
+}
+/** Parse argv. Split out of `cli.ts` so it is testable without a `process.exit`. */
+export declare function parseSpendArgs(argv: readonly string[]): SpendCliArgs;
+/**
+ * Load the product's reconcile options.
+ *
+ * A function export is awaited, so a config can open its database connection and
+ * mint its platform credential at load time rather than at module scope.
+ */
+export declare function loadSpendConfig(configFile: string): Promise<ReconcileSpendOptions>;

package/dist/spend/cli.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+export {};

package/dist/spend/fixtures/incident-parked-time.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The 2026-08-05 parked-time settlement incident, as a fixture.
+ *
+ * A gate calibrated only against invented data proves nothing about the failure
+ * it was built for, so this reconstructs the real one. What comes from the
+ * receipts on agent-dev-container#4422 and its runbook, and what is
+ * reconstructed, is marked per field below — because a fixture that quietly
+ * blends the two is how a calibration stops meaning anything.
+ *
+ * MEASURED (from the incident receipts):
+ *   - The reporter's refund totalled $514.161090533, one of eight wallets
+ *     refunded for a combined $614.31.
+ *   - 23 settlements, interval starts in July, durations 124–268 h, all settled
+ *     inside one burst in the 02:40–04:00 UTC window on 2026-08-05.
+ *   - Two sub-cent rows in the same window were GENUINE short intervals and
+ *     were deliberately not refunded.
+ *   - The ledger reference id is `sandbox:stop:<sandboxId>:<intervalStart>`
+ *     with the interval start in epoch ms; amounts are signed nanodollars,
+ *     negative for a charge; the group key is `sandbox:<sandboxId>`.
+ *   - Both shipped products run `idleTimeoutSeconds: 3600` and
+ *     `maxLifetimeSeconds: 86400`.
+ *
+ * RECONSTRUCTED (the per-row split is not published in the issue):
+ *   - How the 23 durations distribute inside 124–268 h — spread linearly.
+ *   - The implied price, derived so the 23 amounts sum to the refunded total to
+ *     the nanodollar ($0.114055/h for the 2 vCPU / 4 GB box both products run).
+ *   - The fourteen ordinary days of prior spend, which the receipts do not
+ *     enumerate but which the velocity rule needs in order to have a trailing
+ *     median at all.
+ *
+ * One published figure is NOT reproduced here: the brief's aggregate of ~10 718
+ * billed hours cannot be reconciled with 23 rows of 124–268 h, whose arithmetic
+ * maximum is 6 164 h. The per-row bounds are the more specific claim and are
+ * what this uses; the aggregate may span more rows or more wallets than the
+ * reporter's 23. Nothing in the calibration depends on it.
+ */
+import type { SettlementRow, SpendBoxRecord } from '../types';
+/** The reporter's refund, to the nanodollar. */
+export declare const REPORTER_REFUND_NANO_USD = 514161090533;
+export interface IncidentFixture {
+    /** Every settled row an operator's fetch would return, oldest first. */
+    readonly rows: readonly SettlementRow[];
+    /** The expectation ledger a product that had adopted `/spend` would hold. */
+    readonly records: readonly SpendBoxRecord[];
+    /** The 23 over-billed boxes. */
+    readonly incidentSandboxIds: readonly string[];
+    /** The two boxes whose short intervals in the same window were genuine. */
+    readonly genuineSandboxIds: readonly string[];
+    readonly asOf: number;
+}
+/**
+ * Build the incident. Deterministic — no clock, no randomness — so the
+ * calibration test asserts exact numbers rather than ranges.
+ */
+export declare function incidentFixture(): IncidentFixture;