@tangle-network/agent-app 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tangle Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,59 +1,144 @@
 # @tangle-network/agent-app
 
-Shared **application-shell framework** for Tangle agent products (insurance, tax, legal, creative, gtm, agent-builder). The substrate packages (`@tangle-network/{sandbox, agent-runtime, agent-eval, agent-integrations, agent-knowledge, tcloud}`) are the *engine*; this package is the *shell* — the opinionated, reusable application layer those products currently fork-duplicate.
+[![npm](https://img.shields.io/npm/v/@tangle-network/agent-app.svg)](https://www.npmjs.com/package/@tangle-network/agent-app)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-blue.svg)](https://www.npmjs.com/package/@tangle-network/agent-app#provenance)
+[![license](https://img.shields.io/npm/l/@tangle-network/agent-app.svg)](./LICENSE)
 
-The goal: a product should `pnpm add @tangle-network/agent-app`, supply its domain seams (schema, prompt, taxonomy, persistence), and get the whole shell — instead of copy-forking another agent app and inheriting its bugs (the way insurance forked legal and inherited legal's IRS/FinCEN filing scripts).
+The application-shell layer for building agent products on the Tangle stack.
 
-Everything here is **domain-seamed**: the generic mechanism lives in the package; each product supplies callbacks/config for the domain-specific bits. The package imports no product code.
+The substrate packages — `@tangle-network/agent-runtime`, `agent-eval`, `agent-integrations`, `tcloud`, `sandbox` — are the **engine**. This package is the **shell**: the chat tool-loop, the structured agent→app side channel, the integration-hub client, per-workspace billing, field crypto, and the web boundary utilities that every agent app otherwise rewrites by hand. You supply your domain through typed seams; the package supplies the mechanism and imports none of your code.
 
-## Modules
+## Highlights
+
+- **Structured tool side channel** — `submit_proposal` (approval-gated), `schedule_followup`, `render_ui`, `add_citation`, exposed as validated tool calls over three surfaces (HTTP route, per-turn MCP server, agent-runtime executor). No fenced-text parsing.
+- **Bounded tool loop** — `runAppToolLoop` / `streamAppToolLoop`: stream a turn → collect tool calls → dispatch → fold results back → re-run, capped. Substrate-free behind a `streamTurn` seam, so it drives a sandboxed agent, a Worker, or an in-browser copilot unchanged.
+- **Sandbox-optional** — the same tools, billing, eval, and loop work without a container. A `fetch`-only adapter maps any OpenAI-compatible stream (Tangle Router, tcloud) into the loop. See [`examples/browser-copilot.md`](./examples/browser-copilot.md).
+- **Composes the engine, never forks it** — `/eval` re-exports `@tangle-network/agent-eval`'s verifier; `/integrations` wraps the hub; `/tangle` and `/billing` take the tcloud client as a structural contract. Engines are **peer dependencies** — you pin the version, nothing is bundled.
+- **ESM, typed, zero runtime deps** in the substrate-free modules (`/runtime`, `/web`, `/crypto`, `/redact`, `/stream`). Ships with `.d.ts` and npm [provenance](https://www.npmjs.com/package/@tangle-network/agent-app#provenance).
+
+## Install
+
+```bash
+pnpm add @tangle-network/agent-app
+```
 
-| Subpath | Status | What it is |
+The engine packages you actually use are **peer dependencies** — install the ones your modules touch:
+
+```bash
+# /eval composes the eval engine; /integrations composes the hub client
+pnpm add @tangle-network/agent-eval @tangle-network/agent-integrations
+```
+
+| Peer | Required by | Range |
 |---|---|---|
-| `@tangle-network/agent-app/tools` | ✅ **shipped + tested** | The structured agent→app tool side channel — `submit_proposal` (approval-gated), `schedule_followup`, `render_ui`, `add_citation`. OpenAI tool defs, MCP-server builder, HTTP route handler, agent-runtime executor, capability auth. Replaces brittle fenced `:::` blocks with validated tool calls. Seam: `AppToolHandlers` + `AppToolTaxonomy`. |
-| `@tangle-network/agent-app/delegation` | ✅ **shipped + tested** | The agent-runtime "driven loop" MCP (`delegate_research` / `delegate_code` / `delegation_status` …) for multi-step work that runs to completion in its own agent-driver sandbox. Optional; opt in by spreading into the profile `mcp` map. |
-| `@tangle-network/agent-app/tangle` | ✅ **shipped + tested** | Tangle login (SSO) + the developer self-service **app-registration → broker-token** flow: `buildConsentUrl` (one-time user consent) + `createBrokerTokenProvider` (caches/auto-refreshes the `sk-tan-broker-` token per durable grant, shares in-flight mints). Structural (depends on the minter contract; pass the concrete `TangleAppsClient` from `@tangle-network/agent-integrations`). |
-| `@tangle-network/agent-app/runtime` | ✅ **shipped + tested** | `runAppToolLoop` — the bounded multi-turn tool loop every app's chat runtime hand-rolls: stream a turn → collect tool calls → dispatch → fold results back → re-run, capped. Substrate-free via a `streamTurn` seam (wrap any backend / `runAgentTaskStream`) + an `executeToolCall` seam (route to integration + app-tool executors). |
-| `@tangle-network/agent-app/eval` | ✅ **shipped + tested** | The inline completion gate: `producedFromToolEvents` (bridge `/tools` produced events), `verifyCompletion` (per-requirement `satisfiedBy` gate), `tokenRecallChecker` (deterministic content check), `weightedScore`. For full campaigns/traces/LLM-judge use `@tangle-network/agent-eval`; this composes with it. |
+| `@tangle-network/agent-eval` | `/eval` | `>=0.50.0` |
+| `@tangle-network/agent-integrations` | `/integrations`, `/tangle` | `>=0.32.0` |
 
-✅ = built, typechecked, unit-tested, builds. All five modules done — 39 tests.
+The substrate-free modules (`/runtime`, `/tools`, `/web`, `/crypto`, `/redact`, `/stream`, `/billing`) need no peers.
 
-## `/tools` usage (the shipped module)
+## Quick start
 
-A product supplies its taxonomy + handlers (its real DB/vault ops), then wires the three surfaces:
+A product supplies its **taxonomy** (which proposal types exist, which are approval-gated) and its **handlers** (the real DB/vault writes), then wires the tool side channel to whichever surface it runs on.
 
 ```ts
 import {
-  buildAppToolOpenAITools, createAppToolRuntimeExecutor, handleAppToolRequest,
-  buildAppToolMcpServer, type AppToolHandlers, type AppToolTaxonomy,
+  buildAppToolOpenAITools,
+  createAppToolRuntimeExecutor,
+  type AppToolHandlers,
+  type AppToolTaxonomy,
 } from '@tangle-network/agent-app/tools'
+import { runAppToolLoop } from '@tangle-network/agent-app/runtime'
+
+// 1. Declare the domain (the package bakes in no proposal types or rules).
+const taxonomy: AppToolTaxonomy = {
+  proposalTypes: ['recommend', 'contact', 'other'],
+  regulatedTypes: ['recommend', 'contact'], // these require a certified approver
+}
+
+// 2. Provide the side effects — your store, your validation.
+const handlers: AppToolHandlers = {
+  submitProposal,
+  scheduleFollowup,
+  renderUi,
+  addCitation,
+}
+
+// 3. Advertise the tools to the model and route their execution.
+const tools = buildAppToolOpenAITools(taxonomy)
+const executeToolCall = createAppToolRuntimeExecutor({
+  handlers,
+  taxonomy,
+  ctx: { userId, workspaceId, threadId },
+})
+
+// 4. Run a bounded, tool-driven turn loop over any backend.
+const result = await runAppToolLoop({
+  systemPrompt,
+  userMessage,
+  streamTurn,                                       // wrap your model / runAgentTaskStream
+  executeToolCall,
+  isExecutableTool: (name) => tools.some((t) => t.function.name === name),
+})
+
+console.log(result.finalText, result.toolResults)
+```
 
-const taxonomy: AppToolTaxonomy = { proposalTypes: [...], regulatedTypes: [...] }
-const handlers: AppToolHandlers = { submitProposal, scheduleFollowup, renderUi, addCitation } // your DB ops
-
-// 1. Sandbox MCP path — one route file per tool:
-export const action = ({ request }) =>
-  handleAppToolRequest(request, { tool: 'submit_proposal', handlers, taxonomy, verifyToken })
+`streamTurn` is the one seam that varies by backend. For an in-browser or edge copilot talking to an OpenAI-compatible endpoint, you don't write it by hand:
 
-// 2. Per-turn MCP servers (spread into the agent profile's mcp map):
-const mcp = { submit_proposal: buildAppToolMcpServer({ tool: 'submit_proposal', baseUrl, token, ctx, description }) /* … */ }
+```ts
+import { createOpenAICompatStreamTurn, resolveTangleModelConfig } from '@tangle-network/agent-app/runtime'
 
-// 3. agent-runtime chat path (eval / non-sandbox) — advertise tools + execute:
-runChatThroughRuntime({ /* … */ backend: makeBackend({ tools: buildAppToolOpenAITools(taxonomy) }),
-  appToolExecutor: createAppToolRuntimeExecutor({ handlers, taxonomy, ctx, onProduced }) })
+const cfg = resolveTangleModelConfig() // reads provider/model/key/baseUrl from env, or pass literals
+const streamTurn = createOpenAICompatStreamTurn({ ...cfg, tools })
 ```
 
-`insurance-agent` is the reference consumer; its `src/lib/.server/tools/*` is being refactored to delegate here.
+The full three-transport walkthrough (Tangle Router, tcloud, Vercel AI SDK) is in [`examples/browser-copilot.md`](./examples/browser-copilot.md).
+
+## How it's organised
+
+One rule decides where anything lives:
+
+> Does the capability make sense **without** a specific app's tool side channel, approval queue, or chat route?
+> **Yes** → it belongs in an engine package (contribute it down).
+> **No** → it's app-shell, and it belongs here.
+
+Everything here is reached through a typed seam — `AppToolHandlers`, `AppToolTaxonomy`, `streamTurn`, `executeToolCall`, `verifyToken`, `KeyProvisioner` / `WorkspaceKeyStore` / `KeyCrypto`. The package never imports product code and never hard-codes a domain value (a proposal type, a premium, a disclaimer); each is a parameter. New capability arrives as a new subpath, never a breaking change to an existing one.
+
+## Modules
+
+Each is an independent entry point — import only what you use.
+
+| Subpath | What it gives you |
+|---|---|
+| [`/tools`](src/tools) | The structured agent→app side channel: `buildAppToolOpenAITools`, `createAppToolRuntimeExecutor`, `handleAppToolRequest` (HTTP), `buildAppToolMcpServer` / `buildHttpMcpServer` (MCP), `createCapabilityToken` + `authenticateToolRequest` (capability auth), `ToolInputError`. |
+| [`/runtime`](src/runtime) | `runAppToolLoop` / `streamAppToolLoop` (bounded tool loop), `resolveTangleModelConfig` (Tangle Router / Anthropic BYOK), and `toLoopEvents` / `createOpenAICompatStreamTurn` (OpenAI-compat stream → loop events, with fragmented tool-call args reassembled). |
+| [`/integrations`](src/integrations) | Integration-hub client: `HubExecClient`, `resolveIntegrationAction`, `invokeIntegrationHub`. Composes `@tangle-network/agent-integrations`. |
+| [`/eval`](src/eval) | `producedFromToolEvents` (bridge tool events into the eval verifier) and `createTokenRecallChecker` (deterministic content check). Re-exports `@tangle-network/agent-eval`'s `verifyCompletion`, `extractProducedState`, `weightedComposite`, `createLlmCorrectnessChecker`. |
+| [`/tangle`](src/tangle) | App-registration consent URL (`buildConsentUrl`) and a cached, auto-refreshing broker-token provider (`createBrokerTokenProvider`). Structural over the tcloud client. |
+| [`/billing`](src/billing) | `createWorkspaceKeyManager` — mint / rotate / roll over / report usage on per-workspace, budget-capped model keys. Seams for provisioner, store, and crypto. |
+| [`/delegation`](src/delegation) | `buildDelegationMcpServer` — the agent-runtime driven-loop MCP (`delegate_research`, `delegate_code`, `delegation_status`) for multi-step work that runs to completion in its own sandbox. Opt-in. |
+| [`/crypto`](src/crypto) | AES-GCM field encryption: `encryptAesGcm`, `decryptAesGcm`, `createFieldCrypto`. Key supplied by the caller. |
+| [`/web`](src/web) | Request-boundary utilities: `parseJsonObjectBody`, `requireString`, `extractRequestContext`, `checkRateLimit`, `addSecurityHeaders`. |
+| [`/stream`](src/stream) | SSE normalization and turn identity: `normalizeToolEvent`, `resolveChatTurn`, `encodeEvent`, message-part merging. |
+| [`/redact`](src/redact) | `redactForIngestion` — PII redaction before content leaves the boundary. |
 
-## Why this exists
+The root entry (`@tangle-network/agent-app`) re-exports every module, but importing the subpath keeps your bundle to what you use.
 
-Each agent app re-implements the same plumbing (chat pipeline, approval queue, the structured side channel, vault, auth/RBAC, eval scaffold). That fork-duplication is why a single change — e.g. migrating the human-in-the-loop gate from fenced `:::proposal` blocks to validated tool calls — has to be redone in five apps. Lifting the shell here makes it a one-place change, propagated by a version bump.
+## Compatibility
 
-## Develop
+- **ESM only.** Ships `import` + `types` conditions per subpath.
+- **Runtimes:** Node ≥ 20, Cloudflare Workers / edge, and the browser (the substrate-free modules use only Web-standard APIs — `fetch`, Web Crypto, `TextEncoder`).
+- **TypeScript:** strict; full `.d.ts` for every entry point.
+
+## Contributing
 
 ```bash
 pnpm install
 pnpm typecheck && pnpm test && pnpm build
 ```
 
-Build: tsup (ESM + d.ts). Tests: vitest. No upward deps on any product.
+Build is [tsup](https://tsup.egoist.dev) (ESM + `.d.ts`), tests are [vitest](https://vitest.dev). A change keeps the suite green and follows the layering rule above — anything engine-general is contributed down to the substrate, not duplicated here. See [AGENTS.md](./AGENTS.md) for the full contributor contract.
+
+## License
+
+[MIT](./LICENSE)

package/dist/billing/index.d.ts

@@ -103,6 +103,99 @@ interface WorkspaceKeyManager {
     /** Live budget usage for the active key (drives the "$X of $Y used" panel). */
     getUsage(workspaceId: string): Promise<WorkspaceModelKeyUsage | null>;
 }
+/** A user's resolved platform identity (from the app's SSO account store). */
+interface PlatformIdentity {
+    platformUserId: string;
+    /** The user's per-user platform API key (reads), or null when unlinked. */
+    apiKey: string | null;
+}
+/** Spendable balance for a platform user. */
+interface PlatformBalanceInfo {
+    balance: number;
+    lifetimeSpent: number;
+}
+/** Per-product spend aggregate. */
+interface PlatformProductUsage {
+    product: string | null;
+    totalSpent: number;
+    count: number;
+}
+/** Plan limits — a PARAMETER per product (dollar allowance, concurrency,
+ *  overage policy). Never baked into the framework. */
+interface PlanLimit {
+    monthlyBalanceUsd: number;
+    concurrency: number;
+    overageAllowed: boolean;
+}
+/**
+ * The platform billing transport — the product wires these to id.tangle.tools
+ * (or any balance backend). Reads authenticate as the user (their `apiKey`);
+ * the deduct write is a service-token call naming the target user. This module
+ * never touches HTTP — it only sequences these calls.
+ */
+interface PlatformBillingClient<Plan extends string> {
+    /** Resolve the user's platform identity, or null when there is no SSO account. */
+    resolveIdentity(userId: string): Promise<PlatformIdentity | null>;
+    /** Subscription plan for the user (via their platform key). */
+    getPlan(apiKey: string): Promise<Plan>;
+    /** Spendable balance for the user (via their platform key). */
+    getBalance(apiKey: string): Promise<PlatformBalanceInfo>;
+    /** Per-product usage rows for the user (via their platform key). */
+    getUsageByProduct(apiKey: string): Promise<PlatformProductUsage[]>;
+    /** Deduct spend against the user's balance (service-token write). */
+    deduct(input: {
+        platformUserId: string;
+        amountUsd: number;
+        type: string;
+        description: string;
+        referenceId: string;
+    }): Promise<void>;
+}
+interface SharedBillingState<Plan extends string> {
+    /** Platform user id, or null when the user has no Tangle SSO account. */
+    platformUserId: string | null;
+    plan: Plan;
+    monthlyBalanceUsd: number;
+    remainingBalanceUsd: number;
+    lifetimeSpentUsd: number;
+    concurrency: number;
+    overageAllowed: boolean;
+}
+interface PlatformBalanceManagerOptions<Plan extends string> {
+    client: PlatformBillingClient<Plan>;
+    /** Plan → limits map (the product's pricing). */
+    planLimits: Record<Plan, PlanLimit>;
+    /** The plan an unlinked / outage user falls to (fails CLOSED). */
+    freePlan: Plan;
+    /** The product slug to attribute usage to (for `getProductUsage`). */
+    productSlug: string;
+}
+interface PlatformBalanceManager<Plan extends string> {
+    /** Resolve the user's plan + balance. Unlinked or platform-outage users fail
+     *  CLOSED: free plan, zero remaining balance — a billable run is never started
+     *  against an unknown balance. */
+    getState(userId: string): Promise<SharedBillingState<Plan>>;
+    /** Gate a billable turn: allowed when the plan permits overage or remaining
+     *  balance is positive. Returns the state so the caller deducts against it. */
+    canStartBillableTurn(userId: string): Promise<{
+        allowed: boolean;
+        state: SharedBillingState<Plan>;
+    }>;
+    /** Deduct `amountUsd` against the user's platform balance. Throws when the
+     *  user is not platform-linked. */
+    deduct(userId: string, params: {
+        amountUsd: number;
+        type: string;
+        description: string;
+        referenceId: string;
+    }): Promise<void>;
+    /** This product's spend for the user (drives a usage panel). */
+    getProductUsage(userId: string): Promise<{
+        spentUsd: number;
+        transactionCount: number;
+    }>;
+}
+declare function createPlatformBalanceManager<Plan extends string>(opts: PlatformBalanceManagerOptions<Plan>): PlatformBalanceManager<Plan>;
 declare function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager;
 
-export { type KeyCrypto, type KeyProvisioner, type WorkspaceKeyManager, type WorkspaceKeyManagerOptions, type WorkspaceKeyRecord, type WorkspaceKeyStore, type WorkspaceModelKeyUsage, createWorkspaceKeyManager };
+export { type KeyCrypto, type KeyProvisioner, type PlanLimit, type PlatformBalanceInfo, type PlatformBalanceManager, type PlatformBalanceManagerOptions, type PlatformBillingClient, type PlatformIdentity, type PlatformProductUsage, type SharedBillingState, type WorkspaceKeyManager, type WorkspaceKeyManagerOptions, type WorkspaceKeyRecord, type WorkspaceKeyStore, type WorkspaceModelKeyUsage, createPlatformBalanceManager, createWorkspaceKeyManager };

package/dist/billing/index.js

@@ -1,7 +1,9 @@
 import {
+  createPlatformBalanceManager,
   createWorkspaceKeyManager
-} from "../chunk-45MYQ3GD.js";
+} from "../chunk-EAJSWUU5.js";
 export {
+  createPlatformBalanceManager,
   createWorkspaceKeyManager
 };
 //# sourceMappingURL=index.js.map

package/dist/{chunk-45MYQ3GD.js → chunk-EAJSWUU5.js}

@@ -2,6 +2,60 @@
 function nextPeriodEnd(now) {
   return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0));
 }
+function createPlatformBalanceManager(opts) {
+  const { client, planLimits, freePlan, productSlug } = opts;
+  const getState = async (userId) => {
+    const identity = await client.resolveIdentity(userId);
+    if (!identity || !identity.apiKey) {
+      const limits2 = planLimits[freePlan];
+      return {
+        platformUserId: identity?.platformUserId ?? null,
+        plan: freePlan,
+        monthlyBalanceUsd: limits2.monthlyBalanceUsd,
+        remainingBalanceUsd: 0,
+        lifetimeSpentUsd: 0,
+        concurrency: limits2.concurrency,
+        overageAllowed: limits2.overageAllowed
+      };
+    }
+    const [plan, balance] = await Promise.all([client.getPlan(identity.apiKey), client.getBalance(identity.apiKey)]);
+    const limits = planLimits[plan];
+    return {
+      platformUserId: identity.platformUserId,
+      plan,
+      monthlyBalanceUsd: limits.monthlyBalanceUsd,
+      remainingBalanceUsd: balance.balance,
+      lifetimeSpentUsd: balance.lifetimeSpent,
+      concurrency: limits.concurrency,
+      overageAllowed: limits.overageAllowed
+    };
+  };
+  const canStartBillableTurn = async (userId) => {
+    const state = await getState(userId);
+    if (!state.platformUserId) return { allowed: false, state };
+    const allowed = state.overageAllowed || state.remainingBalanceUsd > 0;
+    return { allowed, state };
+  };
+  const deduct = async (userId, params) => {
+    const identity = await client.resolveIdentity(userId);
+    if (!identity) throw new Error("Shared billing requires a platform-linked user");
+    await client.deduct({
+      platformUserId: identity.platformUserId,
+      amountUsd: params.amountUsd,
+      type: params.type,
+      description: params.description,
+      referenceId: params.referenceId
+    });
+  };
+  const getProductUsage = async (userId) => {
+    const identity = await client.resolveIdentity(userId);
+    if (!identity?.apiKey) return { spentUsd: 0, transactionCount: 0 };
+    const rows = await client.getUsageByProduct(identity.apiKey);
+    const product = rows.find((row) => row.product === productSlug);
+    return { spentUsd: product?.totalSpent ?? 0, transactionCount: product?.count ?? 0 };
+  };
+  return { getState, canStartBillableTurn, deduct, getProductUsage };
+}
 function createWorkspaceKeyManager(opts) {
   const clock = opts.now ?? (() => /* @__PURE__ */ new Date());
   const product = opts.product ?? "router";
@@ -57,6 +111,7 @@ function createWorkspaceKeyManager(opts) {
 }
 
 export {
+  createPlatformBalanceManager,
   createWorkspaceKeyManager
 };
-//# sourceMappingURL=chunk-45MYQ3GD.js.map
+//# sourceMappingURL=chunk-EAJSWUU5.js.map

package/dist/chunk-EAJSWUU5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/billing/index.ts"],"sourcesContent":["/**\n * Per-workspace budget-capped model keys — app-owned billing, metered on Tangle.\n *\n * Each workspace (the paying entity) runs the agent on its OWN child API key\n * minted from the platform parent key. The child carries a hard USD budget the\n * Tangle Router enforces AT THE KEY — model spend can't exceed the allowance,\n * zero app-side accounting. The app charges its own subscription (e.g. 5× the\n * allowance) and re-provisions each period. Child budgets are IMMUTABLE on the\n * platform, so a new budget = a fresh key + revoke the prior (rotate).\n *\n * The mint / rotate / rollover / usage LOGIC is generic and lives here.\n * Persistence (which D1 table), secret encryption, and key provisioning are\n * SEAMS each product supplies — so this module imports no DB and no key-mgmt\n * SDK (structural contracts only, like `../tangle`). The `@tangle-network/tcloud`\n * SDK is the provisioner a product passes in; it is not a dependency here.\n */\n\n/** The key-provisioning operations this needs — the `@tangle-network/tcloud`\n *  SDK's `TCloudClient` satisfies it structurally; pass it in. */\nexport interface KeyProvisioner {\n  createKey(input: { name: string; product: string; budgetUsd: number; expiresAt: string }): Promise<{ id?: string; key?: string }>\n  revokeKey(keyId: string): Promise<unknown>\n  getKey(keyId: string): Promise<{ budgetUsd?: number; budgetSpent?: number; expiresAt?: string | null }>\n}\n\n/** A stored child-key record (the app's row, shape-normalized). */\nexport interface WorkspaceKeyRecord {\n  /** App row id (opaque). */\n  id: string\n  keyId: string\n  /** The encrypted secret — decrypted via {@link KeyCrypto.decrypt}. */\n  keyEncrypted: string\n  budgetUsd: number\n  expiresAt: Date | null\n}\n\n/** Persistence seam — the product implements this against its own D1 table. */\nexport interface WorkspaceKeyStore {\n  /** Most-recent active key for the workspace, or null. */\n  getActive(workspaceId: string): Promise<WorkspaceKeyRecord | null>\n  /** All active keys (to revoke priors on rotate). */\n  listActive(workspaceId: string): Promise<Array<{ id: string; keyId: string }>>\n  /** Persist a freshly minted active key. */\n  insert(record: { workspaceId: string; keyId: string; keyEncrypted: string; budgetUsd: number; expiresAt: Date }): Promise<void>\n  /** Mark a prior row revoked. */\n  markRevoked(id: string, now: Date): Promise<void>\n}\n\n/** Secret encryption seam (the app's at-rest crypto). */\nexport interface KeyCrypto {\n  encrypt(secret: string): Promise<string>\n  decrypt(encrypted: string): Promise<string>\n}\n\nexport interface WorkspaceKeyManagerOptions {\n  provisioner: KeyProvisioner\n  store: WorkspaceKeyStore\n  crypto: KeyCrypto\n  /** Default monthly allowance (USD) when a call doesn't specify one. */\n  defaultBudgetUsd: number\n  /** Injectable clock. Default `() => new Date()`. */\n  now?: () => Date\n  /** tcloud product the key is scoped to. Default `'router'`. */\n  product?: string\n}\n\nexport interface WorkspaceModelKeyUsage {\n  keyId: string\n  budgetUsd: number\n  budgetSpent: number\n  budgetRemaining: number\n  expiresAt: string | null\n  exhausted: boolean\n}\n\nexport interface WorkspaceKeyManager {\n  /** The workspace's active child-key secret, provisioning one if absent/expired. */\n  ensureKey(workspaceId: string, opts?: { budgetUsd?: number }): Promise<string>\n  /** Mint a fresh key + revoke priors (period renewal / top-up). `rollover`\n   *  carries the prior key's unused budget into the new one, bounded by\n   *  `rolloverCapUsd`. Returns the new secret. */\n  rotateKey(workspaceId: string, opts?: { budgetUsd?: number; rollover?: boolean; rolloverCapUsd?: number }): Promise<string>\n  /** Live budget usage for the active key (drives the \"$X of $Y used\" panel). */\n  getUsage(workspaceId: string): Promise<WorkspaceModelKeyUsage | null>\n}\n\n/** Period end = first day of next month, midnight UTC. Keys expire at the period\n *  boundary so a forgotten rotation fails closed rather than running free. */\nfunction nextPeriodEnd(now: Date): Date {\n  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0))\n}\n\n// ---------------------------------------------------------------------------\n// Shared-platform-balance billing\n//\n// A DIFFERENT model from the per-workspace child-key manager above: here every\n// user runs against a SHARED platform balance (id.tangle.tools), keyed by the\n// user's platform identity. The app owns no key minting — it reads the balance,\n// gates a billable turn, and deducts spend through the platform billing API.\n// Plan limits, the platform transport, and identity resolution are SEAMS the\n// product supplies; this module imports no DB and no HTTP client.\n// ---------------------------------------------------------------------------\n\n/** A user's resolved platform identity (from the app's SSO account store). */\nexport interface PlatformIdentity {\n  platformUserId: string\n  /** The user's per-user platform API key (reads), or null when unlinked. */\n  apiKey: string | null\n}\n\n/** Spendable balance for a platform user. */\nexport interface PlatformBalanceInfo {\n  balance: number\n  lifetimeSpent: number\n}\n\n/** Per-product spend aggregate. */\nexport interface PlatformProductUsage {\n  product: string | null\n  totalSpent: number\n  count: number\n}\n\n/** Plan limits — a PARAMETER per product (dollar allowance, concurrency,\n *  overage policy). Never baked into the framework. */\nexport interface PlanLimit {\n  monthlyBalanceUsd: number\n  concurrency: number\n  overageAllowed: boolean\n}\n\n/**\n * The platform billing transport — the product wires these to id.tangle.tools\n * (or any balance backend). Reads authenticate as the user (their `apiKey`);\n * the deduct write is a service-token call naming the target user. This module\n * never touches HTTP — it only sequences these calls.\n */\nexport interface PlatformBillingClient<Plan extends string> {\n  /** Resolve the user's platform identity, or null when there is no SSO account. */\n  resolveIdentity(userId: string): Promise<PlatformIdentity | null>\n  /** Subscription plan for the user (via their platform key). */\n  getPlan(apiKey: string): Promise<Plan>\n  /** Spendable balance for the user (via their platform key). */\n  getBalance(apiKey: string): Promise<PlatformBalanceInfo>\n  /** Per-product usage rows for the user (via their platform key). */\n  getUsageByProduct(apiKey: string): Promise<PlatformProductUsage[]>\n  /** Deduct spend against the user's balance (service-token write). */\n  deduct(input: { platformUserId: string; amountUsd: number; type: string; description: string; referenceId: string }): Promise<void>\n}\n\nexport interface SharedBillingState<Plan extends string> {\n  /** Platform user id, or null when the user has no Tangle SSO account. */\n  platformUserId: string | null\n  plan: Plan\n  monthlyBalanceUsd: number\n  remainingBalanceUsd: number\n  lifetimeSpentUsd: number\n  concurrency: number\n  overageAllowed: boolean\n}\n\nexport interface PlatformBalanceManagerOptions<Plan extends string> {\n  client: PlatformBillingClient<Plan>\n  /** Plan → limits map (the product's pricing). */\n  planLimits: Record<Plan, PlanLimit>\n  /** The plan an unlinked / outage user falls to (fails CLOSED). */\n  freePlan: Plan\n  /** The product slug to attribute usage to (for `getProductUsage`). */\n  productSlug: string\n}\n\nexport interface PlatformBalanceManager<Plan extends string> {\n  /** Resolve the user's plan + balance. Unlinked or platform-outage users fail\n   *  CLOSED: free plan, zero remaining balance — a billable run is never started\n   *  against an unknown balance. */\n  getState(userId: string): Promise<SharedBillingState<Plan>>\n  /** Gate a billable turn: allowed when the plan permits overage or remaining\n   *  balance is positive. Returns the state so the caller deducts against it. */\n  canStartBillableTurn(userId: string): Promise<{ allowed: boolean; state: SharedBillingState<Plan> }>\n  /** Deduct `amountUsd` against the user's platform balance. Throws when the\n   *  user is not platform-linked. */\n  deduct(userId: string, params: { amountUsd: number; type: string; description: string; referenceId: string }): Promise<void>\n  /** This product's spend for the user (drives a usage panel). */\n  getProductUsage(userId: string): Promise<{ spentUsd: number; transactionCount: number }>\n}\n\nexport function createPlatformBalanceManager<Plan extends string>(\n  opts: PlatformBalanceManagerOptions<Plan>,\n): PlatformBalanceManager<Plan> {\n  const { client, planLimits, freePlan, productSlug } = opts\n\n  const getState: PlatformBalanceManager<Plan>['getState'] = async (userId) => {\n    const identity = await client.resolveIdentity(userId)\n    // No SSO account, or linked without a platform key: unlinked free tier with\n    // zero balance. Reads require the user's key — never call them empty.\n    if (!identity || !identity.apiKey) {\n      const limits = planLimits[freePlan]\n      return {\n        platformUserId: identity?.platformUserId ?? null,\n        plan: freePlan,\n        monthlyBalanceUsd: limits.monthlyBalanceUsd,\n        remainingBalanceUsd: 0,\n        lifetimeSpentUsd: 0,\n        concurrency: limits.concurrency,\n        overageAllowed: limits.overageAllowed,\n      }\n    }\n    const [plan, balance] = await Promise.all([client.getPlan(identity.apiKey), client.getBalance(identity.apiKey)])\n    const limits = planLimits[plan]\n    return {\n      platformUserId: identity.platformUserId,\n      plan,\n      monthlyBalanceUsd: limits.monthlyBalanceUsd,\n      remainingBalanceUsd: balance.balance,\n      lifetimeSpentUsd: balance.lifetimeSpent,\n      concurrency: limits.concurrency,\n      overageAllowed: limits.overageAllowed,\n    }\n  }\n\n  const canStartBillableTurn: PlatformBalanceManager<Plan>['canStartBillableTurn'] = async (userId) => {\n    const state = await getState(userId)\n    if (!state.platformUserId) return { allowed: false, state }\n    const allowed = state.overageAllowed || state.remainingBalanceUsd > 0\n    return { allowed, state }\n  }\n\n  const deduct: PlatformBalanceManager<Plan>['deduct'] = async (userId, params) => {\n    const identity = await client.resolveIdentity(userId)\n    if (!identity) throw new Error('Shared billing requires a platform-linked user')\n    await client.deduct({\n      platformUserId: identity.platformUserId,\n      amountUsd: params.amountUsd,\n      type: params.type,\n      description: params.description,\n      referenceId: params.referenceId,\n    })\n  }\n\n  const getProductUsage: PlatformBalanceManager<Plan>['getProductUsage'] = async (userId) => {\n    const identity = await client.resolveIdentity(userId)\n    if (!identity?.apiKey) return { spentUsd: 0, transactionCount: 0 }\n    const rows = await client.getUsageByProduct(identity.apiKey)\n    const product = rows.find((row) => row.product === productSlug)\n    return { spentUsd: product?.totalSpent ?? 0, transactionCount: product?.count ?? 0 }\n  }\n\n  return { getState, canStartBillableTurn, deduct, getProductUsage }\n}\n\nexport function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager {\n  const clock = opts.now ?? (() => new Date())\n  const product = opts.product ?? 'router'\n\n  const getUsage: WorkspaceKeyManager['getUsage'] = async (workspaceId) => {\n    const active = await opts.store.getActive(workspaceId)\n    if (!active) return null\n    const info = await opts.provisioner.getKey(active.keyId)\n    const budgetUsd = info.budgetUsd ?? active.budgetUsd\n    const budgetSpent = info.budgetSpent ?? 0\n    const budgetRemaining = Math.max(0, budgetUsd - budgetSpent)\n    return {\n      keyId: active.keyId,\n      budgetUsd,\n      budgetSpent,\n      budgetRemaining,\n      expiresAt: info.expiresAt ?? (active.expiresAt ? active.expiresAt.toISOString() : null),\n      exhausted: budgetRemaining <= 0,\n    }\n  }\n\n  const rotateKey: WorkspaceKeyManager['rotateKey'] = async (workspaceId, ropts) => {\n    const now = clock()\n    const allowance = ropts?.budgetUsd ?? opts.defaultBudgetUsd\n\n    let budgetUsd = allowance\n    if (ropts?.rollover) {\n      const prior = await getUsage(workspaceId).catch(() => null)\n      budgetUsd = allowance + (prior?.budgetRemaining ?? 0)\n      if (ropts.rolloverCapUsd != null) budgetUsd = Math.min(budgetUsd, ropts.rolloverCapUsd)\n    }\n\n    const expiresAt = nextPeriodEnd(now)\n    const created = await opts.provisioner.createKey({ name: `ws:${workspaceId}`, product, budgetUsd, expiresAt: expiresAt.toISOString() })\n    if (!created.key || !created.id) throw new Error('tcloud createKey returned no key')\n    const keyEncrypted = await opts.crypto.encrypt(created.key)\n\n    const priors = await opts.store.listActive(workspaceId)\n    await opts.store.insert({ workspaceId, keyId: created.id, keyEncrypted, budgetUsd, expiresAt })\n    for (const p of priors) {\n      await opts.store.markRevoked(p.id, now)\n      // Best-effort upstream revoke — the row is already revoked and an expired\n      // key fails closed regardless, so a transient error is non-fatal.\n      try {\n        await opts.provisioner.revokeKey(p.keyId)\n      } catch {\n        /* non-fatal */\n      }\n    }\n    return created.key\n  }\n\n  const ensureKey: WorkspaceKeyManager['ensureKey'] = async (workspaceId, eopts) => {\n    const now = clock()\n    const active = await opts.store.getActive(workspaceId)\n    if (active && (!active.expiresAt || active.expiresAt.getTime() > now.getTime())) {\n      return opts.crypto.decrypt(active.keyEncrypted)\n    }\n    return rotateKey(workspaceId, { budgetUsd: eopts?.budgetUsd })\n  }\n\n  return { ensureKey, rotateKey, getUsage }\n}\n"],"mappings":"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","names":["limits"]}

package/dist/{chunk-SIDR6BH3.js → chunk-ZJGY7OMZ.js}

@@ -47,11 +47,56 @@ function createFieldCrypto(key) {
     decrypt: (s) => decryptAesGcm(s, resolve())
   };
 }
+async function deriveKey(secret, opts) {
+  const salt = typeof opts.salt === "string" ? new TextEncoder().encode(opts.salt) : opts.salt;
+  const keyMaterial = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), "PBKDF2", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: opts.iterations, hash: opts.hash ?? "SHA-256" },
+    keyMaterial,
+    { name: ALGORITHM, length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptWithKey(plaintext, key) {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, new TextEncoder().encode(plaintext));
+  const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
+  out.set(iv, 0);
+  out.set(new Uint8Array(ciphertext), IV_LENGTH);
+  return toBase64(out);
+}
+async function decryptWithKey(encoded, key) {
+  const raw = fromBase64(encoded);
+  const iv = raw.slice(0, IV_LENGTH);
+  const ciphertext = raw.slice(IV_LENGTH);
+  const plain = await crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext);
+  return new TextDecoder().decode(plain);
+}
+async function encryptBytes(data, key) {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, data);
+  const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
+  out.set(iv, 0);
+  out.set(new Uint8Array(ciphertext), IV_LENGTH);
+  return out.buffer;
+}
+async function decryptBytes(data, key) {
+  const raw = new Uint8Array(data);
+  const iv = raw.slice(0, IV_LENGTH);
+  const ciphertext = raw.slice(IV_LENGTH);
+  return crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext);
+}
 
 export {
   decodeHexKey,
   encryptAesGcm,
   decryptAesGcm,
-  createFieldCrypto
+  createFieldCrypto,
+  deriveKey,
+  encryptWithKey,
+  decryptWithKey,
+  encryptBytes,
+  decryptBytes
 };
-//# sourceMappingURL=chunk-SIDR6BH3.js.map
+//# sourceMappingURL=chunk-ZJGY7OMZ.js.map

package/dist/chunk-ZJGY7OMZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/crypto/index.ts"],"sourcesContent":["/**\n * AES-256-GCM field encryption (for PII at rest — SSN/EIN/ID numbers, secrets).\n * WebCrypto only — runs on Cloudflare Workers, Node, and the browser with no\n * Node `crypto` dependency. The 32-byte key is a PARAMETER (64-char hex); the\n * framework never reads env — the product binds its own `ENCRYPTION_KEY` (this\n * is the concrete impl behind the `KeyCrypto` seam in `../billing`).\n *\n * Wire format: base64(iv ‖ ciphertext ‖ tag) — the 12-byte IV is prepended; the\n * GCM auth tag is appended by WebCrypto inside the ciphertext.\n */\n\nconst IV_LENGTH = 12\nconst TAG_LENGTH = 16\nconst ALGORITHM = 'AES-GCM'\n\n/** Validate + decode a 64-char hex key to 32 bytes. Throws on the wrong shape so\n *  a misconfigured key fails loud, never silently weakens encryption. */\nexport function decodeHexKey(keyHex: string): Uint8Array {\n  if (keyHex.length !== 64) throw new Error('encryption key must be a 64-char hex string (32 bytes)')\n  const bytes = new Uint8Array(32)\n  for (let i = 0; i < 64; i += 2) bytes[i / 2] = parseInt(keyHex.substring(i, i + 2), 16)\n  return bytes\n}\n\nasync function importKey(keyHex: string): Promise<CryptoKey> {\n  const raw = decodeHexKey(keyHex)\n  return crypto.subtle.importKey('raw', raw.buffer as ArrayBuffer, { name: ALGORITHM } as Algorithm, false, ['encrypt', 'decrypt'])\n}\n\nfunction toBase64(data: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < data.length; i++) binary += String.fromCharCode(data[i]!)\n  return btoa(binary)\n}\n\nfunction fromBase64(b64: string): Uint8Array {\n  const binary = atob(b64)\n  const bytes = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)\n  return bytes\n}\n\n/** Encrypt `plaintext` with AES-256-GCM under `keyHex`. Returns\n *  base64(iv ‖ ciphertext ‖ tag). A fresh random IV per call. */\nexport async function encryptAesGcm(plaintext: string, keyHex: string): Promise<string> {\n  const key = await importKey(keyHex)\n  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))\n  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv, tagLength: TAG_LENGTH * 8 }, key, new TextEncoder().encode(plaintext))\n  const result = new Uint8Array(IV_LENGTH + ciphertext.byteLength)\n  result.set(iv, 0)\n  result.set(new Uint8Array(ciphertext), IV_LENGTH)\n  return toBase64(result)\n}\n\n/** Decrypt a base64(iv ‖ ciphertext ‖ tag) string under `keyHex`. Throws if the\n *  tag fails (tamper/wrong key). */\nexport async function decryptAesGcm(encrypted: string, keyHex: string): Promise<string> {\n  const key = await importKey(keyHex)\n  const data = fromBase64(encrypted)\n  const iv = data.slice(0, IV_LENGTH)\n  const ciphertext = data.slice(IV_LENGTH)\n  const plain = await crypto.subtle.decrypt({ name: ALGORITHM, iv, tagLength: TAG_LENGTH * 8 }, key, ciphertext)\n  return new TextDecoder().decode(plain)\n}\n\n/** Build a {@link import('../billing').KeyCrypto}-compatible pair bound to a key\n *  (or a key-resolver, for env-backed keys resolved per call). */\nexport function createFieldCrypto(key: string | (() => string)): { encrypt(s: string): Promise<string>; decrypt(s: string): Promise<string> } {\n  const resolve = typeof key === 'function' ? key : () => key\n  return {\n    encrypt: (s) => encryptAesGcm(s, resolve()),\n    decrypt: (s) => decryptAesGcm(s, resolve()),\n  }\n}\n\n/**\n * --- Passphrase-derived key path (PBKDF2 → AES-256-GCM CryptoKey) ---\n *\n * The `encryptAesGcm`/`decryptAesGcm` path takes a raw 64-char-hex key. Some\n * products instead bind a SECRET STRING (not a hex key) and derive the AES key\n * with PBKDF2 — and need a BINARY path (encrypting document bytes, not just\n * strings). Both are exposed here so a product never hand-rolls WebCrypto.\n *\n * The derivation parameters (salt, iterations) are PARAMETERS — a product pins\n * its own so the derived key bytes stay stable for data already at rest. The\n * default salt/iterations match the historical tax-agent contract, but any\n * product supplies its own via {@link DeriveKeyOptions}.\n */\n\nexport interface DeriveKeyOptions {\n  /** PBKDF2 salt. A product MUST pin this — changing it changes the derived key\n   *  bytes and orphans every value already encrypted at rest. */\n  salt: Uint8Array | string\n  /** PBKDF2 iteration count. Pin it for the same reason as `salt`. */\n  iterations: number\n  /** PBKDF2 hash. Default `'SHA-256'`. */\n  hash?: 'SHA-256' | 'SHA-384' | 'SHA-512'\n}\n\n/** Derive an AES-256-GCM `CryptoKey` from a secret string via PBKDF2. The key is\n *  non-extractable and usable only for encrypt/decrypt. */\nexport async function deriveKey(secret: string, opts: DeriveKeyOptions): Promise<CryptoKey> {\n  const salt = typeof opts.salt === 'string' ? new TextEncoder().encode(opts.salt) : opts.salt\n  const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), 'PBKDF2', false, ['deriveKey'])\n  return crypto.subtle.deriveKey(\n    { name: 'PBKDF2', salt: salt as BufferSource, iterations: opts.iterations, hash: opts.hash ?? 'SHA-256' },\n    keyMaterial,\n    { name: ALGORITHM, length: 256 },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\n/** Encrypt `plaintext` under a derived `CryptoKey`. Returns base64(iv ‖ ct ‖ tag). */\nexport async function encryptWithKey(plaintext: string, key: CryptoKey): Promise<string> {\n  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))\n  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, new TextEncoder().encode(plaintext))\n  const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength)\n  out.set(iv, 0)\n  out.set(new Uint8Array(ciphertext), IV_LENGTH)\n  return toBase64(out)\n}\n\n/** Decrypt a base64(iv ‖ ct ‖ tag) string under a derived `CryptoKey`. */\nexport async function decryptWithKey(encoded: string, key: CryptoKey): Promise<string> {\n  const raw = fromBase64(encoded)\n  const iv = raw.slice(0, IV_LENGTH)\n  const ciphertext = raw.slice(IV_LENGTH)\n  const plain = await crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext)\n  return new TextDecoder().decode(plain)\n}\n\n/** Encrypt binary data under a derived `CryptoKey`. Returns an ArrayBuffer:\n *  12-byte IV ‖ ciphertext ‖ 16-byte GCM tag (same wire layout as the string\n *  path, raw bytes instead of base64). */\nexport async function encryptBytes(data: ArrayBuffer, key: CryptoKey): Promise<ArrayBuffer> {\n  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))\n  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv }, key, data)\n  const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength)\n  out.set(iv, 0)\n  out.set(new Uint8Array(ciphertext), IV_LENGTH)\n  return out.buffer\n}\n\n/** Decrypt binary data (IV ‖ ciphertext ‖ tag) under a derived `CryptoKey`. */\nexport async function decryptBytes(data: ArrayBuffer, key: CryptoKey): Promise<ArrayBuffer> {\n  const raw = new Uint8Array(data)\n  const iv = raw.slice(0, IV_LENGTH)\n  const ciphertext = raw.slice(IV_LENGTH)\n  return crypto.subtle.decrypt({ name: ALGORITHM, iv }, key, ciphertext)\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-ZXNXAQAH.js

@@ -0,0 +1,69 @@
+// src/knowledge/index.ts
+function clamp(value) {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function buildKnowledgeRequirements(specs, signals = {}) {
+  return specs.map((spec) => {
+    const signal = signals[spec.id];
+    return {
+      id: spec.id,
+      description: spec.description,
+      requiredFor: spec.requiredFor ?? [],
+      category: spec.category,
+      acquisitionMode: spec.acquisitionMode,
+      importance: spec.importance ?? "blocking",
+      freshness: spec.freshness ?? "static",
+      sensitivity: spec.sensitivity ?? "private",
+      confidenceNeeded: spec.confidenceNeeded ?? 1,
+      currentConfidence: clamp(signal?.confidence ?? 0),
+      evidenceIds: signal?.evidence ? [signal.evidence] : [],
+      fallbackPolicy: spec.acquisitionMode === "ask_user" ? "ask" : "block"
+    };
+  });
+}
+async function deriveSignals(specs, ctx) {
+  const out = {};
+  for (const spec of specs) {
+    if (spec.derive) {
+      out[spec.id] = { confidence: clamp(await spec.derive(ctx)), evidence: spec.evidence };
+    } else if (spec.satisfiedBy) {
+      const ok = await evalRule(spec.satisfiedBy, ctx);
+      out[spec.id] = ok ? { confidence: 1, evidence: spec.evidence ?? describeRule(spec.satisfiedBy) } : { confidence: 0 };
+    } else {
+      out[spec.id] = { confidence: 0 };
+    }
+  }
+  return out;
+}
+async function evalRule(rule, ctx) {
+  if ("anyOf" in rule) {
+    for (const sub of rule.anyOf) if (await evalRule(sub, ctx)) return true;
+    return false;
+  }
+  if ("allOf" in rule) {
+    for (const sub of rule.allOf) if (!await evalRule(sub, ctx)) return false;
+    return true;
+  }
+  if ("config" in rule) {
+    const value = ctx.config(rule.config);
+    if (rule.nonEmpty) return Array.isArray(value) ? value.length > 0 : value != null && value !== "";
+    return value != null && value !== "" && value !== false;
+  }
+  const rows = await ctx.count({ table: rule.table, where: rule.where, statusIn: rule.statusIn });
+  return rows >= (rule.minRows ?? 1);
+}
+function describeRule(rule) {
+  if ("anyOf" in rule) return `anyOf(${rule.anyOf.map(describeRule).join(",")})`;
+  if ("allOf" in rule) return `allOf(${rule.allOf.map(describeRule).join(",")})`;
+  if ("config" in rule) return `config:${rule.config}`;
+  return `${rule.table}${rule.statusIn ? `[${rule.statusIn.join("|")}]` : ""}>=${rule.minRows ?? 1}`;
+}
+
+export {
+  buildKnowledgeRequirements,
+  deriveSignals
+};
+//# sourceMappingURL=chunk-ZXNXAQAH.js.map

package/dist/chunk-ZXNXAQAH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/knowledge/index.ts"],"sourcesContent":["/**\n * Declarative knowledge-requirement gate.\n *\n * Every agent product hand-rolls the same pair: a `buildXKnowledgeRequirements`\n * declaring the requirements that gate its control loop, and a\n * `deriveXRuntimeKnowledge` that scores each one from workspace state. Across\n * the fleet those derives are uniformly \"is a config field set\" / \"are there\n * >= N rows in table T (optionally with a status filter)\" / \"any/all of the\n * above\" — data, not logic. This module makes both DATA: a spec list with\n * declarative `satisfiedBy` rules, plus a per-spec `derive` escape hatch for\n * the rare rule a declarative form can't express (e.g. an aggregate over a\n * JSON column).\n *\n * Substrate-free: the only seam is `KnowledgeStateAccessor` (a config lookup +\n * a row count), which the consumer's backend — or `agent-app/preset-cloudflare`\n * — implements. Emits `@tangle-network/agent-eval`'s `KnowledgeRequirement[]`,\n * exactly what the agent-runtime control loop consumes.\n */\n\nimport type {\n  KnowledgeAcquisitionMode,\n  KnowledgeFreshness,\n  KnowledgeImportance,\n  KnowledgeRequirement,\n  KnowledgeRequirementCategory,\n  KnowledgeSensitivity,\n} from '@tangle-network/agent-eval'\n\n/** A declarative rule for satisfying a requirement from workspace state. */\nexport type SatisfiedByRule =\n  /** A workspace-config field (dot-path) is set. `nonEmpty` requires a\n   *  non-empty array/string rather than mere presence. */\n  | { config: string; nonEmpty?: boolean }\n  /** At least `minRows` (default 1) rows exist in `table` for the workspace,\n   *  optionally filtered to `statusIn`. `where` names the workspace fk column\n   *  the accessor scopes on (default: the accessor's convention). */\n  | { table: string; where?: string; statusIn?: string[]; minRows?: number }\n  | { anyOf: SatisfiedByRule[] }\n  | { allOf: SatisfiedByRule[] }\n\nexport interface KnowledgeRequirementSpec {\n  id: string\n  description: string\n  category: KnowledgeRequirementCategory\n  acquisitionMode: KnowledgeAcquisitionMode\n  importance?: KnowledgeImportance\n  freshness?: KnowledgeFreshness\n  sensitivity?: KnowledgeSensitivity\n  confidenceNeeded?: number\n  requiredFor?: string[]\n  /** The data path — evaluated against the `KnowledgeStateAccessor`. */\n  satisfiedBy?: SatisfiedByRule\n  /** The escape hatch — a code derive for what a rule can't express. Wins\n   *  over `satisfiedBy` when both are present. Returns confidence in [0, 1]. */\n  derive?: (ctx: KnowledgeStateAccessor) => number | Promise<number>\n  /** Evidence id attached when satisfied (default: a description of the rule). */\n  evidence?: string\n}\n\n/** The single seam a backend implements. `preset-cloudflare` provides a D1\n *  implementation; a custom stack supplies its own. */\nexport interface KnowledgeStateAccessor {\n  /** Resolve a workspace-config field value (dot-path), or undefined. */\n  config: (path: string) => unknown\n  /** Count rows in `table` for the active workspace, optionally status-filtered. */\n  count: (query: { table: string; where?: string; statusIn?: string[] }) => number | Promise<number>\n}\n\nexport interface KnowledgeSignal {\n  confidence: number\n  evidence?: string\n}\n\nfunction clamp(value: number): number {\n  if (!Number.isFinite(value)) return 0\n  if (value < 0) return 0\n  if (value > 1) return 1\n  return value\n}\n\n/**\n * Map specs -> the runtime's `KnowledgeRequirement[]`, folding in per-spec\n * confidence from `signals` (default 0). Pure + sync: an eval harness can pass\n * hand-authored signals; production passes the output of {@link deriveSignals}.\n */\nexport function buildKnowledgeRequirements(\n  specs: KnowledgeRequirementSpec[],\n  signals: Record<string, KnowledgeSignal> = {},\n): KnowledgeRequirement[] {\n  return specs.map((spec) => {\n    const signal = signals[spec.id]\n    return {\n      id: spec.id,\n      description: spec.description,\n      requiredFor: spec.requiredFor ?? [],\n      category: spec.category,\n      acquisitionMode: spec.acquisitionMode,\n      importance: spec.importance ?? 'blocking',\n      freshness: spec.freshness ?? 'static',\n      sensitivity: spec.sensitivity ?? 'private',\n      confidenceNeeded: spec.confidenceNeeded ?? 1,\n      currentConfidence: clamp(signal?.confidence ?? 0),\n      evidenceIds: signal?.evidence ? [signal.evidence] : [],\n      fallbackPolicy: spec.acquisitionMode === 'ask_user' ? 'ask' : 'block',\n    }\n  })\n}\n\n/**\n * Score every spec from workspace state. `derive` (code) wins; otherwise the\n * declarative `satisfiedBy` rule is evaluated through the accessor; a spec with\n * neither scores 0 (an acquisition gate, e.g. `search_web`).\n */\nexport async function deriveSignals(\n  specs: KnowledgeRequirementSpec[],\n  ctx: KnowledgeStateAccessor,\n): Promise<Record<string, KnowledgeSignal>> {\n  const out: Record<string, KnowledgeSignal> = {}\n  for (const spec of specs) {\n    if (spec.derive) {\n      out[spec.id] = { confidence: clamp(await spec.derive(ctx)), evidence: spec.evidence }\n    } else if (spec.satisfiedBy) {\n      const ok = await evalRule(spec.satisfiedBy, ctx)\n      out[spec.id] = ok\n        ? { confidence: 1, evidence: spec.evidence ?? describeRule(spec.satisfiedBy) }\n        : { confidence: 0 }\n    } else {\n      out[spec.id] = { confidence: 0 }\n    }\n  }\n  return out\n}\n\nasync function evalRule(rule: SatisfiedByRule, ctx: KnowledgeStateAccessor): Promise<boolean> {\n  if ('anyOf' in rule) {\n    for (const sub of rule.anyOf) if (await evalRule(sub, ctx)) return true\n    return false\n  }\n  if ('allOf' in rule) {\n    for (const sub of rule.allOf) if (!(await evalRule(sub, ctx))) return false\n    return true\n  }\n  if ('config' in rule) {\n    const value = ctx.config(rule.config)\n    if (rule.nonEmpty) return Array.isArray(value) ? value.length > 0 : value != null && value !== ''\n    return value != null && value !== '' && value !== false\n  }\n  const rows = await ctx.count({ table: rule.table, where: rule.where, statusIn: rule.statusIn })\n  return rows >= (rule.minRows ?? 1)\n}\n\nfunction describeRule(rule: SatisfiedByRule): string {\n  if ('anyOf' in rule) return `anyOf(${rule.anyOf.map(describeRule).join(',')})`\n  if ('allOf' in rule) return `allOf(${rule.allOf.map(describeRule).join(',')})`\n  if ('config' in rule) return `config:${rule.config}`\n  return `${rule.table}${rule.statusIn ? `[${rule.statusIn.join('|')}]` : ''}>=${rule.minRows ?? 1}`\n}\n"],"mappings":";AAyEA,SAAS,MAAM,OAAuB;AACpC,MAAI,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO;AACpC,MAAI,QAAQ,EAAG,QAAO;AACtB,MAAI,QAAQ,EAAG,QAAO;AACtB,SAAO;AACT;AAOO,SAAS,2BACd,OACA,UAA2C,CAAC,GACpB;AACxB,SAAO,MAAM,IAAI,CAAC,SAAS;AACzB,UAAM,SAAS,QAAQ,KAAK,EAAE;AAC9B,WAAO;AAAA,MACL,IAAI,KAAK;AAAA,MACT,aAAa,KAAK;AAAA,MAClB,aAAa,KAAK,eAAe,CAAC;AAAA,MAClC,UAAU,KAAK;AAAA,MACf,iBAAiB,KAAK;AAAA,MACtB,YAAY,KAAK,cAAc;AAAA,MAC/B,WAAW,KAAK,aAAa;AAAA,MAC7B,aAAa,KAAK,eAAe;AAAA,MACjC,kBAAkB,KAAK,oBAAoB;AAAA,MAC3C,mBAAmB,MAAM,QAAQ,cAAc,CAAC;AAAA,MAChD,aAAa,QAAQ,WAAW,CAAC,OAAO,QAAQ,IAAI,CAAC;AAAA,MACrD,gBAAgB,KAAK,oBAAoB,aAAa,QAAQ;AAAA,IAChE;AAAA,EACF,CAAC;AACH;AAOA,eAAsB,cACpB,OACA,KAC0C;AAC1C,QAAM,MAAuC,CAAC;AAC9C,aAAW,QAAQ,OAAO;AACxB,QAAI,KAAK,QAAQ;AACf,UAAI,KAAK,EAAE,IAAI,EAAE,YAAY,MAAM,MAAM,KAAK,OAAO,GAAG,CAAC,GAAG,UAAU,KAAK,SAAS;AAAA,IACtF,WAAW,KAAK,aAAa;AAC3B,YAAM,KAAK,MAAM,SAAS,KAAK,aAAa,GAAG;AAC/C,UAAI,KAAK,EAAE,IAAI,KACX,EAAE,YAAY,GAAG,UAAU,KAAK,YAAY,aAAa,KAAK,WAAW,EAAE,IAC3E,EAAE,YAAY,EAAE;AAAA,IACtB,OAAO;AACL,UAAI,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE;AAAA,IACjC;AAAA,EACF;AACA,SAAO;AACT;AAEA,eAAe,SAAS,MAAuB,KAA+C;AAC5F,MAAI,WAAW,MAAM;AACnB,eAAW,OAAO,KAAK,MAAO,KAAI,MAAM,SAAS,KAAK,GAAG,EAAG,QAAO;AACnE,WAAO;AAAA,EACT;AACA,MAAI,WAAW,MAAM;AACnB,eAAW,OAAO,KAAK,MAAO,KAAI,CAAE,MAAM,SAAS,KAAK,GAAG,EAAI,QAAO;AACtE,WAAO;AAAA,EACT;AACA,MAAI,YAAY,MAAM;AACpB,UAAM,QAAQ,IAAI,OAAO,KAAK,MAAM;AACpC,QAAI,KAAK,SAAU,QAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,SAAS,IAAI,SAAS,QAAQ,UAAU;AAC/F,WAAO,SAAS,QAAQ,UAAU,MAAM,UAAU;AAAA,EACpD;AACA,QAAM,OAAO,MAAM,IAAI,MAAM,EAAE,OAAO,KAAK,OAAO,OAAO,KAAK,OAAO,UAAU,KAAK,SAAS,CAAC;AAC9F,SAAO,SAAS,KAAK,WAAW;AAClC;AAEA,SAAS,aAAa,MAA+B;AACnD,MAAI,WAAW,KAAM,QAAO,SAAS,KAAK,MAAM,IAAI,YAAY,EAAE,KAAK,GAAG,CAAC;AAC3E,MAAI,WAAW,KAAM,QAAO,SAAS,KAAK,MAAM,IAAI,YAAY,EAAE,KAAK,GAAG,CAAC;AAC3E,MAAI,YAAY,KAAM,QAAO,UAAU,KAAK,MAAM;AAClD,SAAO,GAAG,KAAK,KAAK,GAAG,KAAK,WAAW,IAAI,KAAK,SAAS,KAAK,GAAG,CAAC,MAAM,EAAE,KAAK,KAAK,WAAW,CAAC;AAClG;","names":[]}

package/dist/crypto/index.d.ts

@@ -23,5 +23,40 @@ declare function createFieldCrypto(key: string | (() => string)): {
     encrypt(s: string): Promise<string>;
     decrypt(s: string): Promise<string>;
 };
+/**
+ * --- Passphrase-derived key path (PBKDF2 → AES-256-GCM CryptoKey) ---
+ *
+ * The `encryptAesGcm`/`decryptAesGcm` path takes a raw 64-char-hex key. Some
+ * products instead bind a SECRET STRING (not a hex key) and derive the AES key
+ * with PBKDF2 — and need a BINARY path (encrypting document bytes, not just
+ * strings). Both are exposed here so a product never hand-rolls WebCrypto.
+ *
+ * The derivation parameters (salt, iterations) are PARAMETERS — a product pins
+ * its own so the derived key bytes stay stable for data already at rest. The
+ * default salt/iterations match the historical tax-agent contract, but any
+ * product supplies its own via {@link DeriveKeyOptions}.
+ */
+interface DeriveKeyOptions {
+    /** PBKDF2 salt. A product MUST pin this — changing it changes the derived key
+     *  bytes and orphans every value already encrypted at rest. */
+    salt: Uint8Array | string;
+    /** PBKDF2 iteration count. Pin it for the same reason as `salt`. */
+    iterations: number;
+    /** PBKDF2 hash. Default `'SHA-256'`. */
+    hash?: 'SHA-256' | 'SHA-384' | 'SHA-512';
+}
+/** Derive an AES-256-GCM `CryptoKey` from a secret string via PBKDF2. The key is
+ *  non-extractable and usable only for encrypt/decrypt. */
+declare function deriveKey(secret: string, opts: DeriveKeyOptions): Promise<CryptoKey>;
+/** Encrypt `plaintext` under a derived `CryptoKey`. Returns base64(iv ‖ ct ‖ tag). */
+declare function encryptWithKey(plaintext: string, key: CryptoKey): Promise<string>;
+/** Decrypt a base64(iv ‖ ct ‖ tag) string under a derived `CryptoKey`. */
+declare function decryptWithKey(encoded: string, key: CryptoKey): Promise<string>;
+/** Encrypt binary data under a derived `CryptoKey`. Returns an ArrayBuffer:
+ *  12-byte IV ‖ ciphertext ‖ 16-byte GCM tag (same wire layout as the string
+ *  path, raw bytes instead of base64). */
+declare function encryptBytes(data: ArrayBuffer, key: CryptoKey): Promise<ArrayBuffer>;
+/** Decrypt binary data (IV ‖ ciphertext ‖ tag) under a derived `CryptoKey`. */
+declare function decryptBytes(data: ArrayBuffer, key: CryptoKey): Promise<ArrayBuffer>;
 
-export { createFieldCrypto, decodeHexKey, decryptAesGcm, encryptAesGcm };
+export { type DeriveKeyOptions, createFieldCrypto, decodeHexKey, decryptAesGcm, decryptBytes, decryptWithKey, deriveKey, encryptAesGcm, encryptBytes, encryptWithKey };

package/dist/crypto/index.js

@@ -2,12 +2,22 @@ import {
   createFieldCrypto,
   decodeHexKey,
   decryptAesGcm,
-  encryptAesGcm
-} from "../chunk-SIDR6BH3.js";
+  decryptBytes,
+  decryptWithKey,
+  deriveKey,
+  encryptAesGcm,
+  encryptBytes,
+  encryptWithKey
+} from "../chunk-ZJGY7OMZ.js";
 export {
   createFieldCrypto,
   decodeHexKey,
   decryptAesGcm,
-  encryptAesGcm
+  decryptBytes,
+  decryptWithKey,
+  deriveKey,
+  encryptAesGcm,
+  encryptBytes,
+  encryptWithKey
 };
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -4,8 +4,9 @@ export { BuildDelegationOptions, DELEGATION_MCP_SERVER_KEY, DELEGATION_TOOLS, De
 export { BrokerToken, BrokerTokenMinter, BrokerTokenProvider, BrokerTokenProviderOptions, ConsentUrlInput, buildConsentUrl, createBrokerTokenProvider } from './tangle/index.js';
 export { AppToolLoopOptions, DEFAULT_TANGLE_ROUTER_BASE_URL, LoopEvent, LoopToolCall, OpenAICompatStreamTurnOptions, OpenAIStreamChunk, ResolveModelOptions, StreamAppToolLoopOptions, StreamLoopYield, TangleModelConfig, ToolLoopResult, createOpenAICompatStreamTurn, resolveTangleModelConfig, runAppToolLoop, streamAppToolLoop, toLoopEvents } from './runtime/index.js';
 export { createTokenRecallChecker, producedFromToolEvents } from './eval/index.js';
-export { KeyCrypto, KeyProvisioner, WorkspaceKeyManager, WorkspaceKeyManagerOptions, WorkspaceKeyRecord, WorkspaceKeyStore, WorkspaceModelKeyUsage, createWorkspaceKeyManager } from './billing/index.js';
-export { createFieldCrypto, decodeHexKey, decryptAesGcm, encryptAesGcm } from './crypto/index.js';
+export { KnowledgeRequirementSpec, KnowledgeSignal, KnowledgeStateAccessor, SatisfiedByRule, buildKnowledgeRequirements, deriveSignals } from './knowledge/index.js';
+export { KeyCrypto, KeyProvisioner, PlanLimit, PlatformBalanceInfo, PlatformBalanceManager, PlatformBalanceManagerOptions, PlatformBillingClient, PlatformIdentity, PlatformProductUsage, SharedBillingState, WorkspaceKeyManager, WorkspaceKeyManagerOptions, WorkspaceKeyRecord, WorkspaceKeyStore, WorkspaceModelKeyUsage, createPlatformBalanceManager, createWorkspaceKeyManager } from './billing/index.js';
+export { DeriveKeyOptions, createFieldCrypto, decodeHexKey, decryptAesGcm, decryptBytes, decryptWithKey, deriveKey, encryptAesGcm, encryptBytes, encryptWithKey } from './crypto/index.js';
 export { JsonRecord, PersistedChatMessageForTurn, ResolvedChatTurn, StreamEvent, asRecord, asString, buildUserTextParts, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName } from './stream/index.js';
 export { HubExecClient, HubExecClientOptions, HubExecErrorCode, HubExecResult, HubInvokeDeps, HubInvokeInput, HubInvokeOutcome, ParsedIntegrationAction, invokeIntegrationHub, resolveIntegrationAction } from './integrations/index.js';
 export { JsonObject, KvLike, RateLimitResult, RequestContext, SecurityHeaderOptions, addSecurityHeaders, checkRateLimit, extractRequestContext, parseJsonObjectBody, requireString } from './web/index.js';

package/dist/index.js

@@ -1,3 +1,14 @@
+import {
+  createFieldCrypto,
+  decodeHexKey,
+  decryptAesGcm,
+  decryptBytes,
+  decryptWithKey,
+  deriveKey,
+  encryptAesGcm,
+  encryptBytes,
+  encryptWithKey
+} from "./chunk-ZJGY7OMZ.js";
 import {
   asRecord,
   asString,
@@ -74,14 +85,13 @@ import {
   weightedComposite
 } from "./chunk-4NXVI7PW.js";
 import {
-  createWorkspaceKeyManager
-} from "./chunk-45MYQ3GD.js";
+  buildKnowledgeRequirements,
+  deriveSignals
+} from "./chunk-ZXNXAQAH.js";
 import {
-  createFieldCrypto,
-  decodeHexKey,
-  decryptAesGcm,
-  encryptAesGcm
-} from "./chunk-SIDR6BH3.js";
+  createPlatformBalanceManager,
+  createWorkspaceKeyManager
+} from "./chunk-EAJSWUU5.js";
 export {
   APP_TOOL_NAMES,
   DEFAULT_APP_TOOL_PATHS,
@@ -100,6 +110,7 @@ export {
   buildConsentUrl,
   buildDelegationMcpServer,
   buildHttpMcpServer,
+  buildKnowledgeRequirements,
   buildUserTextParts,
   checkRateLimit,
   createAppToolRuntimeExecutor,
@@ -108,13 +119,20 @@ export {
   createFieldCrypto,
   createLlmCorrectnessChecker,
   createOpenAICompatStreamTurn,
+  createPlatformBalanceManager,
   createTokenRecallChecker,
   createWorkspaceKeyManager,
   decodeHexKey,
   decryptAesGcm,
+  decryptBytes,
+  decryptWithKey,
+  deriveKey,
+  deriveSignals,
   dispatchAppTool,
   encodeEvent,
   encryptAesGcm,
+  encryptBytes,
+  encryptWithKey,
   extractProducedState,
   extractRequestContext,
   finalizeAssistantParts,

package/dist/knowledge/index.d.ts

@@ -0,0 +1,90 @@
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement } from '@tangle-network/agent-eval';
+
+/**
+ * Declarative knowledge-requirement gate.
+ *
+ * Every agent product hand-rolls the same pair: a `buildXKnowledgeRequirements`
+ * declaring the requirements that gate its control loop, and a
+ * `deriveXRuntimeKnowledge` that scores each one from workspace state. Across
+ * the fleet those derives are uniformly "is a config field set" / "are there
+ * >= N rows in table T (optionally with a status filter)" / "any/all of the
+ * above" — data, not logic. This module makes both DATA: a spec list with
+ * declarative `satisfiedBy` rules, plus a per-spec `derive` escape hatch for
+ * the rare rule a declarative form can't express (e.g. an aggregate over a
+ * JSON column).
+ *
+ * Substrate-free: the only seam is `KnowledgeStateAccessor` (a config lookup +
+ * a row count), which the consumer's backend — or `agent-app/preset-cloudflare`
+ * — implements. Emits `@tangle-network/agent-eval`'s `KnowledgeRequirement[]`,
+ * exactly what the agent-runtime control loop consumes.
+ */
+
+/** A declarative rule for satisfying a requirement from workspace state. */
+type SatisfiedByRule = 
+/** A workspace-config field (dot-path) is set. `nonEmpty` requires a
+ *  non-empty array/string rather than mere presence. */
+{
+    config: string;
+    nonEmpty?: boolean;
+}
+/** At least `minRows` (default 1) rows exist in `table` for the workspace,
+ *  optionally filtered to `statusIn`. `where` names the workspace fk column
+ *  the accessor scopes on (default: the accessor's convention). */
+ | {
+    table: string;
+    where?: string;
+    statusIn?: string[];
+    minRows?: number;
+} | {
+    anyOf: SatisfiedByRule[];
+} | {
+    allOf: SatisfiedByRule[];
+};
+interface KnowledgeRequirementSpec {
+    id: string;
+    description: string;
+    category: KnowledgeRequirementCategory;
+    acquisitionMode: KnowledgeAcquisitionMode;
+    importance?: KnowledgeImportance;
+    freshness?: KnowledgeFreshness;
+    sensitivity?: KnowledgeSensitivity;
+    confidenceNeeded?: number;
+    requiredFor?: string[];
+    /** The data path — evaluated against the `KnowledgeStateAccessor`. */
+    satisfiedBy?: SatisfiedByRule;
+    /** The escape hatch — a code derive for what a rule can't express. Wins
+     *  over `satisfiedBy` when both are present. Returns confidence in [0, 1]. */
+    derive?: (ctx: KnowledgeStateAccessor) => number | Promise<number>;
+    /** Evidence id attached when satisfied (default: a description of the rule). */
+    evidence?: string;
+}
+/** The single seam a backend implements. `preset-cloudflare` provides a D1
+ *  implementation; a custom stack supplies its own. */
+interface KnowledgeStateAccessor {
+    /** Resolve a workspace-config field value (dot-path), or undefined. */
+    config: (path: string) => unknown;
+    /** Count rows in `table` for the active workspace, optionally status-filtered. */
+    count: (query: {
+        table: string;
+        where?: string;
+        statusIn?: string[];
+    }) => number | Promise<number>;
+}
+interface KnowledgeSignal {
+    confidence: number;
+    evidence?: string;
+}
+/**
+ * Map specs -> the runtime's `KnowledgeRequirement[]`, folding in per-spec
+ * confidence from `signals` (default 0). Pure + sync: an eval harness can pass
+ * hand-authored signals; production passes the output of {@link deriveSignals}.
+ */
+declare function buildKnowledgeRequirements(specs: KnowledgeRequirementSpec[], signals?: Record<string, KnowledgeSignal>): KnowledgeRequirement[];
+/**
+ * Score every spec from workspace state. `derive` (code) wins; otherwise the
+ * declarative `satisfiedBy` rule is evaluated through the accessor; a spec with
+ * neither scores 0 (an acquisition gate, e.g. `search_web`).
+ */
+declare function deriveSignals(specs: KnowledgeRequirementSpec[], ctx: KnowledgeStateAccessor): Promise<Record<string, KnowledgeSignal>>;
+
+export { type KnowledgeRequirementSpec, type KnowledgeSignal, type KnowledgeStateAccessor, type SatisfiedByRule, buildKnowledgeRequirements, deriveSignals };

package/dist/knowledge/index.js

@@ -0,0 +1,9 @@
+import {
+  buildKnowledgeRequirements,
+  deriveSignals
+} from "../chunk-ZXNXAQAH.js";
+export {
+  buildKnowledgeRequirements,
+  deriveSignals
+};
+//# sourceMappingURL=index.js.map

package/dist/knowledge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "packageManager": "pnpm@10.33.4",
-  "description": "Shared application-shell framework for Tangle agent products: the structured agent\u2192app tool side channel (proposals, follow-ups, generated UI, citations), domain-seamed so each product supplies its own persistence and types.",
+  "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
+  "keywords": [
+    "tangle",
+    "ai-agent",
+    "agent-framework",
+    "llm",
+    "tool-calling",
+    "mcp",
+    "openai",
+    "approval-workflow",
+    "cloudflare-workers",
+    "eval"
+  ],
   "homepage": "https://github.com/tangle-network/agent-app#readme",
   "repository": {
     "type": "git",
@@ -49,6 +61,11 @@
       "import": "./dist/eval/index.js",
       "default": "./dist/eval/index.js"
     },
+    "./knowledge": {
+      "types": "./dist/knowledge/index.d.ts",
+      "import": "./dist/knowledge/index.js",
+      "default": "./dist/knowledge/index.js"
+    },
     "./billing": {
       "types": "./dist/billing/index.d.ts",
       "import": "./dist/billing/index.js",

package/dist/chunk-45MYQ3GD.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/billing/index.ts"],"sourcesContent":["/**\n * Per-workspace budget-capped model keys — app-owned billing, metered on Tangle.\n *\n * Each workspace (the paying entity) runs the agent on its OWN child API key\n * minted from the platform parent key. The child carries a hard USD budget the\n * Tangle Router enforces AT THE KEY — model spend can't exceed the allowance,\n * zero app-side accounting. The app charges its own subscription (e.g. 5× the\n * allowance) and re-provisions each period. Child budgets are IMMUTABLE on the\n * platform, so a new budget = a fresh key + revoke the prior (rotate).\n *\n * The mint / rotate / rollover / usage LOGIC is generic and lives here.\n * Persistence (which D1 table), secret encryption, and key provisioning are\n * SEAMS each product supplies — so this module imports no DB and no key-mgmt\n * SDK (structural contracts only, like `../tangle`). The `@tangle-network/tcloud`\n * SDK is the provisioner a product passes in; it is not a dependency here.\n */\n\n/** The key-provisioning operations this needs — the `@tangle-network/tcloud`\n *  SDK's `TCloudClient` satisfies it structurally; pass it in. */\nexport interface KeyProvisioner {\n  createKey(input: { name: string; product: string; budgetUsd: number; expiresAt: string }): Promise<{ id?: string; key?: string }>\n  revokeKey(keyId: string): Promise<unknown>\n  getKey(keyId: string): Promise<{ budgetUsd?: number; budgetSpent?: number; expiresAt?: string | null }>\n}\n\n/** A stored child-key record (the app's row, shape-normalized). */\nexport interface WorkspaceKeyRecord {\n  /** App row id (opaque). */\n  id: string\n  keyId: string\n  /** The encrypted secret — decrypted via {@link KeyCrypto.decrypt}. */\n  keyEncrypted: string\n  budgetUsd: number\n  expiresAt: Date | null\n}\n\n/** Persistence seam — the product implements this against its own D1 table. */\nexport interface WorkspaceKeyStore {\n  /** Most-recent active key for the workspace, or null. */\n  getActive(workspaceId: string): Promise<WorkspaceKeyRecord | null>\n  /** All active keys (to revoke priors on rotate). */\n  listActive(workspaceId: string): Promise<Array<{ id: string; keyId: string }>>\n  /** Persist a freshly minted active key. */\n  insert(record: { workspaceId: string; keyId: string; keyEncrypted: string; budgetUsd: number; expiresAt: Date }): Promise<void>\n  /** Mark a prior row revoked. */\n  markRevoked(id: string, now: Date): Promise<void>\n}\n\n/** Secret encryption seam (the app's at-rest crypto). */\nexport interface KeyCrypto {\n  encrypt(secret: string): Promise<string>\n  decrypt(encrypted: string): Promise<string>\n}\n\nexport interface WorkspaceKeyManagerOptions {\n  provisioner: KeyProvisioner\n  store: WorkspaceKeyStore\n  crypto: KeyCrypto\n  /** Default monthly allowance (USD) when a call doesn't specify one. */\n  defaultBudgetUsd: number\n  /** Injectable clock. Default `() => new Date()`. */\n  now?: () => Date\n  /** tcloud product the key is scoped to. Default `'router'`. */\n  product?: string\n}\n\nexport interface WorkspaceModelKeyUsage {\n  keyId: string\n  budgetUsd: number\n  budgetSpent: number\n  budgetRemaining: number\n  expiresAt: string | null\n  exhausted: boolean\n}\n\nexport interface WorkspaceKeyManager {\n  /** The workspace's active child-key secret, provisioning one if absent/expired. */\n  ensureKey(workspaceId: string, opts?: { budgetUsd?: number }): Promise<string>\n  /** Mint a fresh key + revoke priors (period renewal / top-up). `rollover`\n   *  carries the prior key's unused budget into the new one, bounded by\n   *  `rolloverCapUsd`. Returns the new secret. */\n  rotateKey(workspaceId: string, opts?: { budgetUsd?: number; rollover?: boolean; rolloverCapUsd?: number }): Promise<string>\n  /** Live budget usage for the active key (drives the \"$X of $Y used\" panel). */\n  getUsage(workspaceId: string): Promise<WorkspaceModelKeyUsage | null>\n}\n\n/** Period end = first day of next month, midnight UTC. Keys expire at the period\n *  boundary so a forgotten rotation fails closed rather than running free. */\nfunction nextPeriodEnd(now: Date): Date {\n  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0))\n}\n\nexport function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager {\n  const clock = opts.now ?? (() => new Date())\n  const product = opts.product ?? 'router'\n\n  const getUsage: WorkspaceKeyManager['getUsage'] = async (workspaceId) => {\n    const active = await opts.store.getActive(workspaceId)\n    if (!active) return null\n    const info = await opts.provisioner.getKey(active.keyId)\n    const budgetUsd = info.budgetUsd ?? active.budgetUsd\n    const budgetSpent = info.budgetSpent ?? 0\n    const budgetRemaining = Math.max(0, budgetUsd - budgetSpent)\n    return {\n      keyId: active.keyId,\n      budgetUsd,\n      budgetSpent,\n      budgetRemaining,\n      expiresAt: info.expiresAt ?? (active.expiresAt ? active.expiresAt.toISOString() : null),\n      exhausted: budgetRemaining <= 0,\n    }\n  }\n\n  const rotateKey: WorkspaceKeyManager['rotateKey'] = async (workspaceId, ropts) => {\n    const now = clock()\n    const allowance = ropts?.budgetUsd ?? opts.defaultBudgetUsd\n\n    let budgetUsd = allowance\n    if (ropts?.rollover) {\n      const prior = await getUsage(workspaceId).catch(() => null)\n      budgetUsd = allowance + (prior?.budgetRemaining ?? 0)\n      if (ropts.rolloverCapUsd != null) budgetUsd = Math.min(budgetUsd, ropts.rolloverCapUsd)\n    }\n\n    const expiresAt = nextPeriodEnd(now)\n    const created = await opts.provisioner.createKey({ name: `ws:${workspaceId}`, product, budgetUsd, expiresAt: expiresAt.toISOString() })\n    if (!created.key || !created.id) throw new Error('tcloud createKey returned no key')\n    const keyEncrypted = await opts.crypto.encrypt(created.key)\n\n    const priors = await opts.store.listActive(workspaceId)\n    await opts.store.insert({ workspaceId, keyId: created.id, keyEncrypted, budgetUsd, expiresAt })\n    for (const p of priors) {\n      await opts.store.markRevoked(p.id, now)\n      // Best-effort upstream revoke — the row is already revoked and an expired\n      // key fails closed regardless, so a transient error is non-fatal.\n      try {\n        await opts.provisioner.revokeKey(p.keyId)\n      } catch {\n        /* non-fatal */\n      }\n    }\n    return created.key\n  }\n\n  const ensureKey: WorkspaceKeyManager['ensureKey'] = async (workspaceId, eopts) => {\n    const now = clock()\n    const active = await opts.store.getActive(workspaceId)\n    if (active && (!active.expiresAt || active.expiresAt.getTime() > now.getTime())) {\n      return opts.crypto.decrypt(active.keyEncrypted)\n    }\n    return rotateKey(workspaceId, { budgetUsd: eopts?.budgetUsd })\n  }\n\n  return { ensureKey, rotateKey, getUsage }\n}\n"],"mappings":";AAwFA,SAAS,cAAc,KAAiB;AACtC,SAAO,IAAI,KAAK,KAAK,IAAI,IAAI,eAAe,GAAG,IAAI,YAAY,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;AACtF;AAEO,SAAS,0BAA0B,MAAuD;AAC/F,QAAM,QAAQ,KAAK,QAAQ,MAAM,oBAAI,KAAK;AAC1C,QAAM,UAAU,KAAK,WAAW;AAEhC,QAAM,WAA4C,OAAO,gBAAgB;AACvE,UAAM,SAAS,MAAM,KAAK,MAAM,UAAU,WAAW;AACrD,QAAI,CAAC,OAAQ,QAAO;AACpB,UAAM,OAAO,MAAM,KAAK,YAAY,OAAO,OAAO,KAAK;AACvD,UAAM,YAAY,KAAK,aAAa,OAAO;AAC3C,UAAM,cAAc,KAAK,eAAe;AACxC,UAAM,kBAAkB,KAAK,IAAI,GAAG,YAAY,WAAW;AAC3D,WAAO;AAAA,MACL,OAAO,OAAO;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,KAAK,cAAc,OAAO,YAAY,OAAO,UAAU,YAAY,IAAI;AAAA,MAClF,WAAW,mBAAmB;AAAA,IAChC;AAAA,EACF;AAEA,QAAM,YAA8C,OAAO,aAAa,UAAU;AAChF,UAAM,MAAM,MAAM;AAClB,UAAM,YAAY,OAAO,aAAa,KAAK;AAE3C,QAAI,YAAY;AAChB,QAAI,OAAO,UAAU;AACnB,YAAM,QAAQ,MAAM,SAAS,WAAW,EAAE,MAAM,MAAM,IAAI;AAC1D,kBAAY,aAAa,OAAO,mBAAmB;AACnD,UAAI,MAAM,kBAAkB,KAAM,aAAY,KAAK,IAAI,WAAW,MAAM,cAAc;AAAA,IACxF;AAEA,UAAM,YAAY,cAAc,GAAG;AACnC,UAAM,UAAU,MAAM,KAAK,YAAY,UAAU,EAAE,MAAM,MAAM,WAAW,IAAI,SAAS,WAAW,WAAW,UAAU,YAAY,EAAE,CAAC;AACtI,QAAI,CAAC,QAAQ,OAAO,CAAC,QAAQ,GAAI,OAAM,IAAI,MAAM,kCAAkC;AACnF,UAAM,eAAe,MAAM,KAAK,OAAO,QAAQ,QAAQ,GAAG;AAE1D,UAAM,SAAS,MAAM,KAAK,MAAM,WAAW,WAAW;AACtD,UAAM,KAAK,MAAM,OAAO,EAAE,aAAa,OAAO,QAAQ,IAAI,cAAc,WAAW,UAAU,CAAC;AAC9F,eAAW,KAAK,QAAQ;AACtB,YAAM,KAAK,MAAM,YAAY,EAAE,IAAI,GAAG;AAGtC,UAAI;AACF,cAAM,KAAK,YAAY,UAAU,EAAE,KAAK;AAAA,MAC1C,QAAQ;AAAA,MAER;AAAA,IACF;AACA,WAAO,QAAQ;AAAA,EACjB;AAEA,QAAM,YAA8C,OAAO,aAAa,UAAU;AAChF,UAAM,MAAM,MAAM;AAClB,UAAM,SAAS,MAAM,KAAK,MAAM,UAAU,WAAW;AACrD,QAAI,WAAW,CAAC,OAAO,aAAa,OAAO,UAAU,QAAQ,IAAI,IAAI,QAAQ,IAAI;AAC/E,aAAO,KAAK,OAAO,QAAQ,OAAO,YAAY;AAAA,IAChD;AACA,WAAO,UAAU,aAAa,EAAE,WAAW,OAAO,UAAU,CAAC;AAAA,EAC/D;AAEA,SAAO,EAAE,WAAW,WAAW,SAAS;AAC1C;","names":[]}

package/dist/chunk-SIDR6BH3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/crypto/index.ts"],"sourcesContent":["/**\n * AES-256-GCM field encryption (for PII at rest — SSN/EIN/ID numbers, secrets).\n * WebCrypto only — runs on Cloudflare Workers, Node, and the browser with no\n * Node `crypto` dependency. The 32-byte key is a PARAMETER (64-char hex); the\n * framework never reads env — the product binds its own `ENCRYPTION_KEY` (this\n * is the concrete impl behind the `KeyCrypto` seam in `../billing`).\n *\n * Wire format: base64(iv ‖ ciphertext ‖ tag) — the 12-byte IV is prepended; the\n * GCM auth tag is appended by WebCrypto inside the ciphertext.\n */\n\nconst IV_LENGTH = 12\nconst TAG_LENGTH = 16\nconst ALGORITHM = 'AES-GCM'\n\n/** Validate + decode a 64-char hex key to 32 bytes. Throws on the wrong shape so\n *  a misconfigured key fails loud, never silently weakens encryption. */\nexport function decodeHexKey(keyHex: string): Uint8Array {\n  if (keyHex.length !== 64) throw new Error('encryption key must be a 64-char hex string (32 bytes)')\n  const bytes = new Uint8Array(32)\n  for (let i = 0; i < 64; i += 2) bytes[i / 2] = parseInt(keyHex.substring(i, i + 2), 16)\n  return bytes\n}\n\nasync function importKey(keyHex: string): Promise<CryptoKey> {\n  const raw = decodeHexKey(keyHex)\n  return crypto.subtle.importKey('raw', raw.buffer as ArrayBuffer, { name: ALGORITHM } as Algorithm, false, ['encrypt', 'decrypt'])\n}\n\nfunction toBase64(data: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < data.length; i++) binary += String.fromCharCode(data[i]!)\n  return btoa(binary)\n}\n\nfunction fromBase64(b64: string): Uint8Array {\n  const binary = atob(b64)\n  const bytes = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)\n  return bytes\n}\n\n/** Encrypt `plaintext` with AES-256-GCM under `keyHex`. Returns\n *  base64(iv ‖ ciphertext ‖ tag). A fresh random IV per call. */\nexport async function encryptAesGcm(plaintext: string, keyHex: string): Promise<string> {\n  const key = await importKey(keyHex)\n  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH))\n  const ciphertext = await crypto.subtle.encrypt({ name: ALGORITHM, iv, tagLength: TAG_LENGTH * 8 }, key, new TextEncoder().encode(plaintext))\n  const result = new Uint8Array(IV_LENGTH + ciphertext.byteLength)\n  result.set(iv, 0)\n  result.set(new Uint8Array(ciphertext), IV_LENGTH)\n  return toBase64(result)\n}\n\n/** Decrypt a base64(iv ‖ ciphertext ‖ tag) string under `keyHex`. Throws if the\n *  tag fails (tamper/wrong key). */\nexport async function decryptAesGcm(encrypted: string, keyHex: string): Promise<string> {\n  const key = await importKey(keyHex)\n  const data = fromBase64(encrypted)\n  const iv = data.slice(0, IV_LENGTH)\n  const ciphertext = data.slice(IV_LENGTH)\n  const plain = await crypto.subtle.decrypt({ name: ALGORITHM, iv, tagLength: TAG_LENGTH * 8 }, key, ciphertext)\n  return new TextDecoder().decode(plain)\n}\n\n/** Build a {@link import('../billing').KeyCrypto}-compatible pair bound to a key\n *  (or a key-resolver, for env-backed keys resolved per call). */\nexport function createFieldCrypto(key: string | (() => string)): { encrypt(s: string): Promise<string>; decrypt(s: string): Promise<string> } {\n  const resolve = typeof key === 'function' ? key : () => key\n  return {\n    encrypt: (s) => encryptAesGcm(s, resolve()),\n    decrypt: (s) => decryptAesGcm(s, resolve()),\n  }\n}\n"],"mappings":";AAWA,IAAM,YAAY;AAClB,IAAM,aAAa;AACnB,IAAM,YAAY;AAIX,SAAS,aAAa,QAA4B;AACvD,MAAI,OAAO,WAAW,GAAI,OAAM,IAAI,MAAM,wDAAwD;AAClG,QAAM,QAAQ,IAAI,WAAW,EAAE;AAC/B,WAAS,IAAI,GAAG,IAAI,IAAI,KAAK,EAAG,OAAM,IAAI,CAAC,IAAI,SAAS,OAAO,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE;AACtF,SAAO;AACT;AAEA,eAAe,UAAU,QAAoC;AAC3D,QAAM,MAAM,aAAa,MAAM;AAC/B,SAAO,OAAO,OAAO,UAAU,OAAO,IAAI,QAAuB,EAAE,MAAM,UAAU,GAAgB,OAAO,CAAC,WAAW,SAAS,CAAC;AAClI;AAEA,SAAS,SAAS,MAA0B;AAC1C,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,IAAK,WAAU,OAAO,aAAa,KAAK,CAAC,CAAE;AAC5E,SAAO,KAAK,MAAM;AACpB;AAEA,SAAS,WAAW,KAAyB;AAC3C,QAAM,SAAS,KAAK,GAAG;AACvB,QAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;AAC1C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,OAAM,CAAC,IAAI,OAAO,WAAW,CAAC;AACtE,SAAO;AACT;AAIA,eAAsB,cAAc,WAAmB,QAAiC;AACtF,QAAM,MAAM,MAAM,UAAU,MAAM;AAClC,QAAM,KAAK,OAAO,gBAAgB,IAAI,WAAW,SAAS,CAAC;AAC3D,QAAM,aAAa,MAAM,OAAO,OAAO,QAAQ,EAAE,MAAM,WAAW,IAAI,WAAW,aAAa,EAAE,GAAG,KAAK,IAAI,YAAY,EAAE,OAAO,SAAS,CAAC;AAC3I,QAAM,SAAS,IAAI,WAAW,YAAY,WAAW,UAAU;AAC/D,SAAO,IAAI,IAAI,CAAC;AAChB,SAAO,IAAI,IAAI,WAAW,UAAU,GAAG,SAAS;AAChD,SAAO,SAAS,MAAM;AACxB;AAIA,eAAsB,cAAc,WAAmB,QAAiC;AACtF,QAAM,MAAM,MAAM,UAAU,MAAM;AAClC,QAAM,OAAO,WAAW,SAAS;AACjC,QAAM,KAAK,KAAK,MAAM,GAAG,SAAS;AAClC,QAAM,aAAa,KAAK,MAAM,SAAS;AACvC,QAAM,QAAQ,MAAM,OAAO,OAAO,QAAQ,EAAE,MAAM,WAAW,IAAI,WAAW,aAAa,EAAE,GAAG,KAAK,UAAU;AAC7G,SAAO,IAAI,YAAY,EAAE,OAAO,KAAK;AACvC;AAIO,SAAS,kBAAkB,KAA4G;AAC5I,QAAM,UAAU,OAAO,QAAQ,aAAa,MAAM,MAAM;AACxD,SAAO;AAAA,IACL,SAAS,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAAA,IAC1C,SAAS,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAAA,EAC5C;AACF;","names":[]}