@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/spend/types.d.ts

@@ -0,0 +1,466 @@
+/**
+ * The vocabulary of consumer-side spend verification.
+ *
+ * Kept in its own module with ZERO imports so a product can type its storage
+ * rows and its reconciliation config without pulling in `node:fs` through the
+ * CLI half.
+ *
+ * The model in one paragraph: the platform's ledger is authoritative about what
+ * was CHARGED. A product knows something the ledger does not — what it ASKED
+ * for. Recording that second view, and diffing it against the first, is what
+ * turns a platform billing defect from silent money into an alert. Nothing here
+ * lets a product self-certify a charge away; the output is a discrepancy a human
+ * disputes.
+ */
+/**
+ * One box, as the PRODUCT understands it. Folded, not an append-only log: a
+ * product runs one row per sandbox, and every field below is derived by a
+ * monotonic fold (see `foldSpendBoxRecord`) so two concurrent writers cannot
+ * produce a wrong answer, only a stale one.
+ *
+ * Timestamps are epoch ms throughout, matching the platform's own
+ * `sandbox_meta.last_started_at`.
+ */
+export interface SpendBoxRecord {
+    /** The platform's sandbox id — the join key to every settlement row. */
+    readonly sandboxId: string;
+    /** The product's own tenancy unit, which the platform does not model. */
+    readonly workspaceId: string;
+    /** First moment the product knew this box existed. */
+    readonly createdAt: number;
+    /**
+     * The idle timeout the product ASKED the platform for, seconds. This is the
+     * width of the grace window between the last thing the product saw and the
+     * moment the platform should have stopped billing.
+     */
+    readonly idleTimeoutSeconds: number;
+    /**
+     * The maximum lifetime the product asked for, seconds, when it asked for one.
+     * This is the strongest bound a product holds: the platform destroys the box
+     * at `createdAt + maxLifetimeSeconds` regardless of what the product observed,
+     * so it caps the ceiling even when nothing else can (see `computeExpectedCeiling`).
+     */
+    readonly maxLifetimeSeconds: number | null;
+    /** Latest moment the product OBSERVED the box doing work. */
+    readonly lastActivityAt: number;
+    /**
+     * Detached runs dispatched but never observed to finish, by run id.
+     *
+     * Non-empty means the product genuinely cannot bound this box from its own
+     * observations: it handed the platform work and disconnected. The ceiling
+     * degrades accordingly rather than pretending to a tightness it did not earn.
+     */
+    readonly openDetachedRunIds: readonly string[];
+    /** When the product knows the box stopped. Cleared by later activity. */
+    readonly stoppedAt: number | null;
+    /** When the product knows the box was deleted. Set once — a deleted id never returns. */
+    readonly deletedAt: number | null;
+    /** Opaque product-column values, written verbatim and never read here. */
+    readonly extras?: Record<string, unknown>;
+}
+/**
+ * A fold step. Every field states its own merge rule, so a SQL implementation
+ * can apply it in one statement and reach the same record an in-memory
+ * read-modify-write reaches.
+ */
+export interface SpendBoxPatch {
+    /** Advance `lastActivityAt` to the max of stored and this. Never moves backward. */
+    readonly observedActivityAt?: number;
+    /** Add a run id to `openDetachedRunIds` (set semantics — re-adding is a no-op). */
+    readonly openDetachedRunAdd?: string;
+    /** Remove a run id from `openDetachedRunIds`. Removing an absent id is a no-op. */
+    readonly openDetachedRunRemove?: string;
+    /**
+     * Latest-wins. Activity observed AFTER a recorded stop clears it: a box that
+     * worked after we thought it stopped is running again, and a stale stop would
+     * make the ceiling too tight.
+     */
+    readonly stoppedAt?: number;
+    /** Set-once. A later delete observation does not move the first one. */
+    readonly deletedAt?: number;
+}
+/** Which fact bounds a box's billable time, weakest last. */
+export type CeilingBasis = 
+/** The product observed deletion. Billing cannot run past a box that is gone. */
+'deleted'
+/** The product observed a stop. Billing should have closed there. */
+ | 'stopped'
+/** No stop seen, but the platform destroys the box at its max lifetime. */
+ | 'max-lifetime'
+/** No stop seen; the platform's idle timer is what should have closed billing. */
+ | 'idle-timeout'
+/**
+ * An unfinished detached run and no max lifetime — the product cannot bound
+ * this box at all, so the ceiling degrades to the reconciliation instant.
+ * A finding on this basis is weak evidence and says so.
+ */
+ | 'open-detached-run';
+/** The upper bound on one box's billable duration, and what earned it. */
+export interface ExpectedCeiling {
+    readonly sandboxId: string;
+    readonly basis: CeilingBasis;
+    /** The latest instant this box could still have been billable, epoch ms. */
+    readonly horizonAt: number;
+    /** `horizonAt - createdAt + toleranceMs`. The upper bound on billable ms. */
+    readonly ceilingMs: number;
+    readonly toleranceMs: number;
+    /**
+     * False when the basis is `open-detached-run` — the ceiling then rests on the
+     * reconciliation instant rather than on anything the product observed, so an
+     * overage means the platform billed outside the box's own lifetime, not merely
+     * longer than expected.
+     */
+    readonly bounded: boolean;
+}
+/**
+ * One settled ledger row, in the shape the platform's `credit_transactions`
+ * table stores it. The product supplies these through its own fetch (the
+ * platform's credit-history API, an export, a mirror) — this package never
+ * reaches for them, because the ledger is the counterparty's record and reading
+ * it is the product's authenticated business.
+ *
+ * The rows a product can fetch are scoped to the BILLING OWNER, not to the
+ * product: `product: 'sandbox'` is the platform's service taxonomy and every
+ * consumer app's compute wears it. So a wallet running two of our products
+ * returns both products' settlements, and telling them apart is
+ * {@link SpendOwnershipRule}'s job.
+ */
+export interface SettlementRow {
+    /** The ledger row id, for the dispute. */
+    readonly id: string;
+    /**
+     * `sandbox:<kind>:<sandboxId>:<intervalStartMs>` — the platform's idempotency
+     * key, and the only place the billed interval's START is recorded.
+     */
+    readonly referenceId: string | null;
+    /**
+     * Signed nanodollars, exactly as the ledger stores it: negative is a charge,
+     * positive is a credit or refund.
+     */
+    readonly amountNanoUsd: number;
+    /** `compute` | `refund` | `inference` | … */
+    readonly type: string;
+    /** `sandbox` | `router` | … */
+    readonly product: string | null;
+    /** `sandbox:<sandboxId>` — the platform's aggregation unit. */
+    readonly groupKey: string | null;
+    /** Settlement instant, epoch ms. The product normalizes the stored text. */
+    readonly createdAt: number;
+    readonly description: string | null;
+    /** Provider at-cost basis, unsigned nanodollars. Null when unattributed. */
+    readonly costBasisNanoUsd: number | null;
+    /**
+     * The billed duration, when the product's ledger view exposes it directly.
+     * Null is the common case: the platform does not store duration on the row.
+     */
+    readonly billedMs: number | null;
+    /**
+     * The platform API key the charge was triggered by — `credit_transactions.key_id`,
+     * stamped from the box's own creation metadata at settlement time and exposed
+     * by `/v1/billing/transactions` (which also filters on it).
+     *
+     * This is the ONLY field on a settlement row that can be attributed back to a
+     * PRODUCT rather than to a wallet or to the platform's service taxonomy, which
+     * is why {@link SpendOwnershipRule}'s shipped constructor is built on it. The
+     * sandbox id cannot do the job: the platform mints it as `sandbox-<12 hex>`
+     * from a hash of (owner, idempotency key), so a product's own box naming never
+     * reaches the ledger row.
+     *
+     * Optional, and `null` is a real answer: the platform leaves it null on legacy
+     * rows and an export may not carry the column at all. A missing key is
+     * `undecidable`, never `foreign` — see {@link SpendOwnershipVerdict}.
+     */
+    readonly keyId?: string | null;
+}
+/**
+ * What one settlement is attributable to, from inside ONE product.
+ *
+ * The distinction this type exists for: a sibling product's box and a charge
+ * that is not ours at all look identical from inside a single product, because
+ * both arrive as a settlement naming a sandbox this product's expectation ledger
+ * has never heard of. Dropping both loses the check's whole purpose; reporting
+ * both makes it noise. Only a platform-stamped attribution field separates them.
+ */
+export type SpendOwnershipVerdict = 
+/** Attributable to THIS product. An unrecorded one is a phantom-charge candidate. */
+'mine'
+/** Attributable to a DIFFERENT product on the same wallet. Reported, never a finding. */
+ | 'foreign'
+/**
+ * The row carries nothing that decides it. Counted as `mine` — FAIL CLOSED.
+ * An unattributable charge on a shared wallet is precisely the shape of the
+ * thing this module exists to catch, so the ambiguous case costs a human five
+ * minutes rather than costing the product the detection.
+ */
+ | 'undecidable';
+/** One settlement, presented to an ownership rule. */
+export interface SpendOwnershipCandidate {
+    readonly row: SettlementRow;
+    /** The sandbox the row is attributable to, or null for a row naming none. */
+    readonly sandboxId: string | null;
+}
+/**
+ * The product's declaration of which settlements are its own.
+ *
+ * The one hard constraint on `decide`: it must answer from PROPERTIES OF THE
+ * ROW. A rule that answers by looking the sandbox up in the product's own
+ * expectation ledger deletes `unknown-box` entirely — every unrecorded box would
+ * be `foreign` by construction, and "we were billed for a box we never asked
+ * for" would become unrepresentable. The ledger already decides recorded-ness;
+ * this decides ATTRIBUTION, and the two must stay independent.
+ *
+ * `decide` must not throw. If it does, the throw propagates and the whole pass
+ * fails — a reconciliation whose ownership rule is broken has no verdict worth
+ * printing, and swallowing it would turn a broken rule into a clean bill.
+ */
+export interface SpendOwnershipRule {
+    /** Named in the report and on every finding, so a reader knows what was excluded. */
+    readonly label: string;
+    decide(candidate: SpendOwnershipCandidate): SpendOwnershipVerdict;
+}
+/**
+ * What this pass scoped itself to — present on every report, including a clean
+ * one, because "nothing fired" and "nothing was looked at" are different
+ * answers and a report that cannot tell them apart is the failure this closes.
+ */
+export interface SpendOwnershipSummary {
+    /**
+     * False when the caller declared no rule. The pass then treats every box as
+     * its own — today's behaviour, which over-reports rather than under-reports —
+     * and every `unknown-box` finding says on its face that a sibling product's
+     * box is indistinguishable from a charge that is not ours.
+     */
+    readonly declared: boolean;
+    /** The rule's label, or null when none was declared. */
+    readonly label: string | null;
+    /** Boxes this pass treated as this product's, and what they were charged. */
+    readonly ownedBoxes: number;
+    readonly ownedNanoUsd: number;
+    /**
+     * Of those, the boxes no rule could decide. Counted as owned (fail-closed) and
+     * reported separately so a product can see how much of its own verdict rests
+     * on rows that carried no attribution.
+     */
+    readonly undecidableBoxes: number;
+    /** Boxes attributed to another product on the same wallet. Never findings. */
+    readonly foreignBoxes: number;
+    readonly foreignNanoUsd: number;
+    /**
+     * Their ids, in full — an exclusion a reader cannot audit is an exclusion
+     * they have to trust, and this module's whole posture is that nothing about
+     * money is taken on trust.
+     */
+    readonly foreignSandboxIds: readonly string[];
+}
+/**
+ * The stretch of time a reconciliation pass covers — the same window the
+ * product's own ledger fetch was scoped to.
+ *
+ * Declared by the caller rather than derived from the rows, because deriving it
+ * from the rows is circular: a feed that returns nothing would produce a
+ * zero-width window that expects nothing and certifies itself.
+ */
+export interface SpendWindow {
+    /** Inclusive start, epoch ms. */
+    readonly startAt: number;
+    /** Inclusive end, epoch ms. */
+    readonly endAt: number;
+}
+/**
+ * One box's life, measured against a reconciliation window.
+ *
+ * The live interval is `[createdAt, horizon]`, where the horizon is the SAME one
+ * `computeExpectedCeiling` derives — so a box cannot count as live for the
+ * expectation check and dead for the ceiling check.
+ */
+export interface SpendBoxLiveness {
+    readonly sandboxId: string;
+    readonly workspaceId: string;
+    /** First instant the box could have been billable. */
+    readonly liveFrom: number;
+    /** Last instant it could have been, evaluated at the window's end. */
+    readonly liveUntil: number;
+    /** Which fact closed the interval — the ceiling's own vocabulary. */
+    readonly basis: CeilingBasis;
+    /** True when any of that life fell inside the window. */
+    readonly overlaps: boolean;
+    /** How much of it did, in ms. Zero for a box that did not overlap. */
+    readonly liveMsInWindow: number;
+    /**
+     * True when the overlap is long enough that a settlement should have landed.
+     * A box that came up moments before the window closed is live but not yet
+     * expected — settlement lags provisioning, and demanding a row inside that lag
+     * would report the platform's ordinary queue as a defect.
+     */
+    readonly expectSettlement: boolean;
+}
+/**
+ * What this pass EXPECTED to be billed for — present on every report, including
+ * a clean one, for the same reason {@link SpendOwnershipSummary} is: "nothing
+ * fired" and "nothing was expected" and "nothing could be expected" are three
+ * different answers and a report that cannot tell them apart is the failure this
+ * closes.
+ */
+export interface SpendExpectationSummary {
+    /**
+     * False when the caller declared no window, or the store cannot list its
+     * boxes. The pass then cannot say what it expected — which is reported, never
+     * rounded down to a clean bill.
+     */
+    readonly declared: boolean;
+    readonly window: SpendWindow | null;
+    /** Live ms inside the window before a settlement is expected of a box. */
+    readonly graceMs: number;
+    /** Boxes whose life overlapped the window at all. */
+    readonly liveBoxes: number;
+    /** Of those, the ones live long enough that a settlement should have landed. */
+    readonly expectedBoxes: number;
+    /** Of those, the ones at least one settlement this pass claimed did land against. */
+    readonly settledBoxes: number;
+    /**
+     * The expected boxes nothing settled against, in full — the exhibit list for
+     * "the check stopped checking", and an expectation a reader cannot audit is
+     * one they have to take on trust.
+     */
+    readonly unsettledSandboxIds: readonly string[];
+}
+/**
+ * How much this pass is entitled to claim about the bill.
+ *
+ * `ok` is gated on this, which is what makes an examined-nobody pass
+ * structurally incapable of rendering as a clean bill.
+ */
+export type SpendCoverage = 
+/** The pass examined this product's settlements, or knows what it expected. */
+'verified'
+/**
+ * Expectation was declared and no box was live long enough to expect a bill.
+ * Zero settlements is the RIGHT answer — an idle product, not a defect, and
+ * the one case in which a pass that examined nobody is still clean.
+ */
+ | 'nothing-expected'
+/**
+ * The pass examined none of this product's settlements and cannot say what it
+ * expected. The CHECK is suspect, not the bill.
+ */
+ | 'unverified';
+/** The parts of a settlement reference id, once parsed. */
+export interface SettlementReference {
+    /** `stop` | `compute` | `egress` | `gpu-lease` | anything the platform adds. */
+    readonly kind: string;
+    /** For compute kinds, the sandbox id. For `gpu-lease`, the lease id. */
+    readonly resourceId: string;
+    /** The interval's start, epoch ms. Null for kinds that carry no interval. */
+    readonly intervalStartMs: number | null;
+}
+/** How a settled duration was arrived at — every duration finding carries one. */
+export type BilledDurationBasis = 
+/** The ledger row carried the duration. Exact. */
+'reported'
+/** `amount ÷ the product's stated hourly rate`. Exact when the rate is right. */
+ | 'rate'
+/**
+ * `settledAt - intervalStart`. An UPPER bound, not the billed duration: a
+ * correct settlement posted late by the platform's durable settlement queue
+ * reads longer here than it billed. Findings on this basis say so.
+ */
+ | 'reference-span'
+/** No basis available — duration rules are skipped for this row. */
+ | 'unknown';
+/** The checks this reconciler runs. Each is individually skippable, by name. */
+export type SpendCheckId = 
+/** A settlement against a box the product has no record of ever asking for. */
+'unknown-box'
+/** A settled duration longer than the product's own upper bound allows. */
+ | 'over-ceiling'
+/** A spend window far above the trailing median — the burst shape of a defect. */
+ | 'velocity'
+/** The balance the product observes has gone below its floor. */
+ | 'negative-balance'
+/**
+ * The product expected settlements and saw none — the only check whose
+ * subject is the CHECK rather than the bill.
+ *
+ * Every other rule is driven by a settlement row, so all of them go quiet
+ * together when the rows stop arriving: an empty ledger fetch, a stale
+ * ownership rule that excludes every box, an expectation ledger naming
+ * nobody. This is the rule that fires when the others cannot, and it reads as
+ * "do not trust this report" rather than "dispute this charge".
+ */
+ | 'silent-ledger';
+export declare const SPEND_CHECKS: readonly SpendCheckId[];
+/**
+ * One discrepancy, with every number the rule compared.
+ *
+ * Nullable fields are per-check and deliberately present-but-null rather than
+ * absent: a reader scanning a JSON dump can tell "this rule does not measure
+ * that" from "that measurement is missing".
+ */
+export interface SpendFinding {
+    readonly check: SpendCheckId;
+    /** What is wrong, in one sentence, with the numbers in it. */
+    readonly message: string;
+    /** What to do about it. A finding without a remedy is a complaint. */
+    readonly remedy: string;
+    readonly sandboxId: string | null;
+    readonly workspaceId: string | null;
+    /** The ledger rows that evidence this finding — the dispute's exhibit list. */
+    readonly referenceIds: readonly string[];
+    /** Nanodollars this finding puts in question, unsigned. */
+    readonly settledNanoUsd: number;
+    /** `over-ceiling` — the duration actually settled, and how that was derived. */
+    readonly settledMs: number | null;
+    readonly durationBasis: BilledDurationBasis | null;
+    /** `over-ceiling` — the bound it broke, and what earned that bound. */
+    readonly ceilingMs: number | null;
+    readonly overageMs: number | null;
+    readonly ceilingBasis: CeilingBasis | null;
+    /** `velocity` — the window, its trailing median, and the ratio between them. */
+    readonly windowNanoUsd: number | null;
+    readonly trailingMedianNanoUsd: number | null;
+    readonly velocityRatio: number | null;
+    /** `velocity` and `silent-ledger` — the window the finding is about. */
+    readonly windowStartAt: number | null;
+    readonly windowEndAt: number | null;
+    /** `negative-balance` — the observed balance and the floor it broke. */
+    readonly balanceNanoUsd: number | null;
+    readonly balanceFloorNanoUsd: number | null;
+    /** `silent-ledger` — how many boxes were expected to settle, and how many did. */
+    readonly expectedBoxes: number | null;
+    readonly settledBoxes: number | null;
+    /** `silent-ledger`, per-box form — how long that box was live inside the window. */
+    readonly liveMsInWindow: number | null;
+}
+/** What one reconciliation pass concluded. */
+export interface SpendReport {
+    /**
+     * True when nothing fired AND the pass earned the right to say so:
+     * `findings.length === 0 && coverage !== 'unverified'`.
+     *
+     * The second half is not decoration. Every rule but `silent-ledger` is driven
+     * by a settlement row, so a pass that read no rows — an empty ledger fetch, a
+     * stale ownership rule excluding every box, an expectation ledger naming
+     * nobody — fires nothing and used to report a clean bill. `coverage` is what
+     * makes that shape unrepresentable, and it holds even when a caller skips the
+     * `silent-ledger` check: the skip removes the finding, never the verdict.
+     */
+    readonly ok: boolean;
+    /** How much this pass is entitled to claim. See {@link SpendCoverage}. */
+    readonly coverage: SpendCoverage;
+    readonly findings: readonly SpendFinding[];
+    readonly checksRun: readonly SpendCheckId[];
+    /** Rows the pass read, including the ones no rule looked at. */
+    readonly rowsExamined: number;
+    /** Distinct boxes those rows settled against. */
+    readonly boxesExamined: number;
+    /** Total charged across every examined row, unsigned nanodollars. */
+    readonly settledNanoUsd: number;
+    /** Total credited back across every examined row, unsigned nanodollars. */
+    readonly creditedNanoUsd: number;
+    /** What this pass claimed as its own, and what it excluded as another product's. */
+    readonly ownership: SpendOwnershipSummary;
+    /** What this pass expected to be billed for, and what did not arrive. */
+    readonly expectation: SpendExpectationSummary;
+    /** The instant the pass treated as "now". */
+    readonly asOf: number;
+}

package/dist/store/index.d.ts

@@ -15,7 +15,7 @@
  * free and driver-agnostic: this module knows nothing about D1, drizzle, or any
  * schema — it only forwards property access to the injected instance.
  */
-interface DatabaseProvider<DB> {
+export interface DatabaseProvider<DB> {
     /** The injected database, as a lazy proxy. Throws (with `notReadyMessage`)
      *  on any access before {@link setDatabase} is called. */
     readonly db: DB;
@@ -27,27 +27,27 @@ interface DatabaseProvider<DB> {
     reset(): void;
 }
 /** Define options for configuring database provider behavior including error messaging */
-interface DatabaseProviderOptions {
+export interface DatabaseProviderOptions {
     /** Error thrown when `db` is accessed before injection. Keep the product's
      *  existing wording so callers see a familiar message. */
     notReadyMessage?: string;
 }
 /** A database driver that can execute related SQLite statements as one batch.
  * Cloudflare D1 and libsql expose this method; portable local drivers may not. */
-interface SqliteBatchDatabase {
+export interface SqliteBatchDatabase {
     batch?: (statements: [unknown, ...unknown[]]) => Promise<unknown[]>;
 }
 /** Execute related SQLite statements in one transactional driver batch when
  * supported, or sequentially in the same order for portable local drivers. */
-declare function runSqliteStatements(db: SqliteBatchDatabase, statements: [unknown, ...unknown[]]): Promise<unknown[]>;
+export declare function runSqliteStatements(db: SqliteBatchDatabase, statements: [unknown, ...unknown[]]): Promise<unknown[]>;
 /**
  * Create a swappable database provider. `DB` is the injected instance's type
  * (e.g. a drizzle `Database`); the proxy is typed as `DB` so callers keep full
  * typing and their existing query syntax.
  */
-declare function createDatabaseProvider<DB extends object>(options?: DatabaseProviderOptions): DatabaseProvider<DB>;
+export declare function createDatabaseProvider<DB extends object>(options?: DatabaseProviderOptions): DatabaseProvider<DB>;
 /** Describe the result of listing keys with completion status and optional pagination cursor */
-interface KVListResult {
+export interface KVListResult {
     keys: {
         name: string;
     }[];
@@ -55,18 +55,18 @@ interface KVListResult {
     cursor?: string;
 }
 /** Define options for storing a key-value pair with expiration and metadata settings */
-interface KVPutOptions {
+export interface KVPutOptions {
     expiration?: number;
     expirationTtl?: number;
     metadata?: unknown;
 }
 /** Resolve a key-value pair retrieval including its associated metadata and value */
-interface KVGetWithMetadataResult {
+export interface KVGetWithMetadataResult {
     value: string | null;
     metadata: unknown | null;
 }
 /** Define a key-value store interface for asynchronous data retrieval, storage, deletion, and listing */
-interface KVStore {
+export interface KVStore {
     get(key: string): Promise<string | null>;
     /** Read a value with its stored metadata (e.g. the vault's encrypted/hasPII flags). */
     getWithMetadata(key: string): Promise<KVGetWithMetadataResult>;
@@ -83,6 +83,4 @@ interface KVStore {
  * Backed by a Map; `list` returns all prefix-matched keys in one complete page
  * (no real pagination needed in-process). Seed with `initial` entries if useful.
  */
-declare function createInMemoryKV(initial?: Record<string, string>): KVStore;
-
-export { type DatabaseProvider, type DatabaseProviderOptions, type KVGetWithMetadataResult, type KVListResult, type KVPutOptions, type KVStore, type SqliteBatchDatabase, createDatabaseProvider, createInMemoryKV, runSqliteStatements };
+export declare function createInMemoryKV(initial?: Record<string, string>): KVStore;

package/dist/stories/app-shell/fixtures.d.ts

@@ -0,0 +1,43 @@
+/**
+ * App-shell story fixtures. The chat content below mirrors the shared
+ * `../fixtures/chat.ts` thread (launch-poster scenario, same message ids); it
+ * is duplicated here so the app-shell area stays self-contained — the composed
+ * shell is the design-evaluation centerpiece and must keep rendering even when
+ * other areas' fixtures move. The sidebar session list and model catalog are
+ * shell-specific and live only here.
+ *
+ * Types come from the package source (`../../web-react`) — the same types the
+ * chat components consume — so a drift in `ChatUiMessage` fails typecheck here.
+ */
+import type { CatalogModel, ChatUiMessage } from '../../web-react';
+import type { SessionStatus, ShellSessionSection } from './shell';
+/** Assistant turn whose proposal is still awaiting human approval. */
+export declare const proposalAwaitingApprovalMessage: ChatUiMessage;
+/**
+ * A turn still streaming: partial answer text, a tool call in flight, and no
+ * completion metrics yet (no `completionTokens`/`durationMs` — producers only
+ * stamp those when the turn settles).
+ */
+export declare const streamingAssistantMessage: ChatUiMessage;
+/**
+ * ~16 messages covering every rendered state: plain exchanges, reasoning,
+ * per-message metrics, interleaved `segments`, a proposal awaiting approval,
+ * an errored tool call, and a trailing in-flight turn. Long enough that the
+ * thread scrolls, so spacing/typography stories evaluate real rhythm.
+ */
+export declare const chatThread: ChatUiMessage[];
+/**
+ * Minimal catalog. `anthropic/claude-opus-4` matches every `modelUsed` in the
+ * thread, so `formatModelCost` renders the per-message cost line; the second
+ * entry gives the composer's model chip somewhere to go.
+ */
+export declare const shellModels: CatalogModel[];
+/**
+ * The session list a production agent shell shows: recency-grouped sections,
+ * one live turn elsewhere (`running`), and titles that read like real work.
+ * The active session (`launch-poster`) is the thread in `chatThread`.
+ */
+export declare const shellSections: ShellSessionSection[];
+/** Return a copy of `sections` with one session's status changed (story args
+ *  are frozen, so derive rather than mutate). */
+export declare function withSessionStatus(sections: ShellSessionSection[], sessionId: string, status: SessionStatus): ShellSessionSection[];

package/dist/stories/app-shell/shell.d.ts

@@ -0,0 +1,81 @@
+/**
+ * App-shell composition pieces for the app-shell stories. The package ships NO
+ * generic app-shell component on purpose — a product composes its own shell
+ * from package primitives (`ChatMessages`, `ChatComposer`, `../../brand`) plus
+ * its own sidebar. These are the story-local building blocks for that
+ * composition: a session sidebar (recency sections, active item, status
+ * affordances, new-chat button), a thread header, and the `AppShell` layout
+ * that wires them together with a mobile drawer below `md`.
+ *
+ * Everything is Tailwind over the shared tokens (`bg-card`, `border-border`,
+ * `text-muted-foreground`, `bg-primary`, …) so the global theme toolbar
+ * restyles it, exactly like the `web-react` styling contract.
+ */
+import { type ReactNode } from 'react';
+export type SessionStatus = 'idle' | 'running' | 'approval';
+interface ShellSession {
+    id: string;
+    title: string;
+    /** `running` shows a spinner, `approval` an amber dot — the two states a
+     *  background agent session can be in while you're looking at another one. */
+    status?: SessionStatus;
+}
+export interface ShellSessionSection {
+    id: string;
+    label: string;
+    sessions: ShellSession[];
+}
+interface ShellUser {
+    name: string;
+    email: string;
+}
+export interface AppSidebarProps {
+    sections: ShellSessionSection[];
+    activeId?: string | null;
+    /** Rail mode: icons only, 52px. */
+    collapsed?: boolean;
+    /** Row rhythm: `comfortable` is the default reading density, `compact` the
+     *  power-user density for long histories. */
+    density?: 'comfortable' | 'compact';
+    pendingApprovals?: number;
+    user?: ShellUser | null;
+    onNewChat?: () => void;
+    onSelectSession?: (id: string) => void;
+    onToggleCollapse?: () => void;
+    onOpenApprovals?: () => void;
+    onOpenSettings?: () => void;
+    onOpenAccount?: () => void;
+    className?: string;
+}
+export declare function AppSidebar(props: AppSidebarProps): import("react").JSX.Element;
+export interface AppShellProps {
+    sections: ShellSessionSection[];
+    activeSessionId?: string | null;
+    sidebarCollapsed?: boolean;
+    sidebarDensity?: 'comfortable' | 'compact';
+    pendingApprovals?: number;
+    user?: ShellUser | null;
+    headerTitle: string;
+    headerSubtitle?: string;
+    onNewChat?: () => void;
+    onSelectSession?: (id: string) => void;
+    onToggleCollapse?: () => void;
+    onOpenApprovals?: () => void;
+    onOpenSettings?: () => void;
+    onOpenAccount?: () => void;
+    onShare?: () => void;
+    onOpenThreadMenu?: () => void;
+    /** The thread — typically `<ChatMessages/>`. Rendered in the scroll area. */
+    children?: ReactNode;
+    /** Typically `<ChatComposer/>`; pinned to the bottom of the main column and
+     *  aligned to the same `max-w-3xl` reading column `ChatMessages` uses. */
+    composer?: ReactNode;
+}
+/**
+ * The production agent-app layout: sidebar (fixed on desktop, drawer below
+ * `md`), header row, scrolling thread, pinned composer. Presentational only —
+ * all behavior arrives via props, so stories drive it with fixtures and
+ * console.log callbacks.
+ */
+export declare function AppShell({ sections, activeSessionId, sidebarCollapsed, sidebarDensity, pendingApprovals, user, headerTitle, headerSubtitle, onNewChat, onSelectSession, onToggleCollapse, onOpenApprovals, onOpenSettings, onOpenAccount, onShare, onOpenThreadMenu, children, composer, }: AppShellProps): import("react").JSX.Element;
+export {};