@venturekit-pro/ai 0.0.48 → 0.0.50

package/dist/agent-loop/types.js

@@ -0,0 +1,8 @@
+/**
+ * Agent loop types — a provider-neutral, bounded tool-use loop on top of
+ * the gateway's `generate`: the model calls function tools (and the
+ * vendor's native web search) until it answers, or until a step, tool
+ * call, cost or time limit asks it to wrap up.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent-loop/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent-loop/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/chat/types.d.ts

@@ -14,9 +14,11 @@
  * The vendor whose SDK / HTTP API a chat client is wired to.
  *
  * Adding a value requires a corresponding adapter file under
- * `chat/<provider>.ts` and a branch in `chat/client.ts:createChatClient`.
+ * `generate/<provider>.ts` and a branch in `generate/client.ts:createGenerateClient`
+ * (and, for the legacy single-shot client, `chat/<provider>.ts` plus a branch in
+ * `chat/client.ts:createChatClient`). `perplexity` is served by `generate` only.
  */
-export type ChatProvider = 'anthropic' | 'openai' | 'google';
+export type ChatProvider = 'anthropic' | 'openai' | 'google' | 'perplexity';
 /**
  * One turn in a chat completion request.
  *

package/dist/chat/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/chat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,gBAAgB,GAChB,OAAO,GACP,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,YAAY,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,cAAc,CAAC;IACtB,gGAAgG;IAChG,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/chat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,gBAAgB,GAChB,OAAO,GACP,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,YAAY,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,cAAc,CAAC;IACtB,gGAAgG;IAChG,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC"}

package/dist/cost/types.d.ts

@@ -88,5 +88,20 @@ export interface ModelDescriptor extends Partial<ChatModelPricing> {
     disabledAt?: string;
     /** Free-form tags for filtering (`['fast', 'cheap', 'multilingual']`). */
     tags?: string[];
+    /**
+     * USD per 1K input tokens served from the provider's prompt cache. When
+     * unset, cached tokens are priced at the input rate (conservative).
+     */
+    costPer1kCachedInputUsd?: number;
+    /**
+     * USD per 1K input tokens written to the provider's prompt cache
+     * (Anthropic 5-minute entries, OpenAI GPT-5.6+: 1.25× input). When
+     * unset, cache writes are priced at the input rate.
+     */
+    costPer1kCacheWriteUsd?: number;
+    /** USD per 1K tokens written with a 1-hour lifetime (Anthropic: 2× input). When unset, the 5-minute write rate. */
+    costPer1kCacheWrite1hUsd?: number;
+    /** USD per 1,000 native web searches. When unset, searches are priced at $0. */
+    webSearchPer1kUsd?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/cost/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IAChE,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,QAAQ,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cost/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAgB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IAChE,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,QAAQ,EAAE,YAAY,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mHAAmH;IACnH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/cost-ledger/migrations/vk_ai_cost_0004_llm_gateway.sql

@@ -0,0 +1,69 @@
+-- @venturekit-pro/ai — LLM gateway (SCHEMA ONLY).
+--
+-- 1. Two prices on the catalog the gateway needs (`src/gateway/pricing.ts`):
+--      cost_per_1k_cached_input  USD per 1K input tokens served from the
+--                                provider's prompt cache. NULL = priced at
+--                                the input rate (conservative).
+--      web_search_per_1k         USD per 1,000 native web searches
+--                                (Anthropic web search, OpenAI web_search,
+--                                Gemini grounding). NULL = $0.
+--    Mirrors `ModelDescriptor.costPer1kCachedInputUsd` / `webSearchPer1kUsd`.
+--
+-- 2. `vk_llm_calls` — the gateway's audit trail: one row per call (served,
+--    failed, denied or cancelled) with its context, every candidate tried,
+--    policy decisions, usage, cost and the full request / response content.
+--    File and image inputs are stored as size + SHA-256, never their bytes.
+--    Rows carry `expires_at` (retention at write time) and are deleted by
+--    `purgeExpiredLlmCalls()`.
+--
+-- The cost ledger (`vk_llm_cost_events`) stays the billing record; this
+-- table is the "what exactly was asked and answered" record.
+--
+-- Idempotent: every statement is IF NOT EXISTS.
+
+ALTER TABLE vk_llm_models
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cached_input numeric(12, 8),
+  ADD COLUMN IF NOT EXISTS web_search_per_1k        numeric(12, 6);
+
+CREATE TABLE IF NOT EXISTS vk_llm_calls (
+  id                 uuid          PRIMARY KEY,
+  tenant_id          uuid,
+  feature            text          NOT NULL,
+  actor_type         text,
+  actor_id           text,
+  target_type        text,
+  target_id          text,
+  correlation_id     text,
+  -- succeeded | failed | denied | cancelled
+  status             text          NOT NULL,
+  model_key          text,
+  provider           text,
+  model              text,
+  -- platform | tenant
+  credential_source  text,
+  fell_back          boolean       NOT NULL DEFAULT false,
+  attempts           jsonb         NOT NULL DEFAULT '[]'::jsonb,
+  policy_decisions   jsonb         NOT NULL DEFAULT '[]'::jsonb,
+  usage              jsonb,
+  cost_usd           numeric(12, 8),
+  cost_micro_usd     bigint,
+  latency_ms         integer,
+  labels             jsonb         NOT NULL DEFAULT '{}'::jsonb,
+  request            jsonb         NOT NULL,
+  response           jsonb,
+  error              jsonb,
+  started_at         timestamptz   NOT NULL,
+  finished_at        timestamptz   NOT NULL,
+  created_at         timestamptz   NOT NULL DEFAULT now(),
+  expires_at         timestamptz   NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS llm_calls_correlation_idx
+  ON vk_llm_calls (correlation_id, started_at DESC)
+  WHERE correlation_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS llm_calls_tenant_started_idx
+  ON vk_llm_calls (tenant_id, started_at DESC);
+
+CREATE INDEX IF NOT EXISTS llm_calls_expires_idx
+  ON vk_llm_calls (expires_at);

package/dist/cost-ledger/migrations/vk_ai_cost_0005_harness.sql

@@ -0,0 +1,99 @@
+-- @venturekit-pro/ai — harness (durable graph runs), SCHEMA ONLY.
+--
+-- Store behind `createPostgresHarnessStore` (src/harness/postgres-store.ts):
+--
+--   vk_harness_runs       one row per run: graph key@version pinned at
+--                         start, status, the run context, input, every
+--                         node's output, the node to run, its step and
+--                         attempt, delays, the worker lease, cancel flag,
+--                         error, spend. `version` is the compare-and-set
+--                         token every state change checks; `event_seq`
+--                         numbers the run's events.
+--   vk_harness_node_runs  one row per node attempt (output, error, spend).
+--   vk_harness_map_items  per-item checkpoints of map nodes.
+--   vk_harness_events     append-only event log (timeline, progress,
+--                         tool calls, gates) ordered by (run_id, seq).
+--
+-- Statuses: queued · running · waiting · completed · failed · cancelled.
+-- Idempotent: every statement is IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS vk_harness_runs (
+  id                uuid           PRIMARY KEY,
+  tenant_id         uuid,
+  graph_key         text           NOT NULL,
+  graph_version     integer        NOT NULL,
+  status            text           NOT NULL,
+  context           jsonb          NOT NULL DEFAULT '{}'::jsonb,
+  target_type       text,
+  target_id         text,
+  input             jsonb,
+  outputs           jsonb          NOT NULL DEFAULT '{}'::jsonb,
+  current_node      text,
+  step              integer        NOT NULL DEFAULT 1,
+  attempt           integer        NOT NULL DEFAULT 1,
+  attempt_base      integer        NOT NULL DEFAULT 0,
+  not_before        timestamptz,
+  lease_until       timestamptz,
+  cancel_requested  boolean        NOT NULL DEFAULT false,
+  error             jsonb,
+  cost_usd          numeric(14, 8) NOT NULL DEFAULT 0,
+  event_seq         integer        NOT NULL DEFAULT 0,
+  version           integer        NOT NULL DEFAULT 0,
+  created_at        timestamptz    NOT NULL DEFAULT now(),
+  updated_at        timestamptz    NOT NULL DEFAULT now(),
+  completed_at      timestamptz,
+  CONSTRAINT harness_runs_status_chk CHECK (status IN ('queued', 'running', 'waiting', 'completed', 'failed', 'cancelled'))
+);
+
+CREATE INDEX IF NOT EXISTS harness_runs_tenant_graph_idx
+  ON vk_harness_runs (tenant_id, graph_key, status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS harness_runs_target_idx
+  ON vk_harness_runs (tenant_id, target_type, target_id)
+  WHERE target_type IS NOT NULL;
+
+-- The sweep: queued runs (lost / due tasks) and running runs (expired leases).
+CREATE INDEX IF NOT EXISTS harness_runs_sweep_idx
+  ON vk_harness_runs (status, updated_at)
+  WHERE status IN ('queued', 'running');
+
+CREATE TABLE IF NOT EXISTS vk_harness_node_runs (
+  run_id       uuid           NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step         integer        NOT NULL,
+  node_id      text           NOT NULL,
+  attempt      integer        NOT NULL,
+  -- succeeded | failed | cancelled
+  status       text           NOT NULL,
+  started_at   timestamptz    NOT NULL,
+  finished_at  timestamptz    NOT NULL,
+  output       jsonb,
+  error        jsonb,
+  cost_usd     numeric(14, 8) NOT NULL DEFAULT 0,
+  PRIMARY KEY (run_id, step, attempt)
+);
+
+CREATE TABLE IF NOT EXISTS vk_harness_map_items (
+  run_id      uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step        integer      NOT NULL,
+  item_index  integer      NOT NULL,
+  output      jsonb,
+  created_at  timestamptz  NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, step, item_index)
+);
+
+CREATE TABLE IF NOT EXISTS vk_harness_events (
+  run_id   uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  seq      integer      NOT NULL,
+  at       timestamptz  NOT NULL DEFAULT now(),
+  type     text         NOT NULL,
+  node_id  text,
+  step     integer,
+  attempt  integer,
+  label    text         NOT NULL,
+  detail   text,
+  data     jsonb,
+  PRIMARY KEY (run_id, seq)
+);
+
+CREATE INDEX IF NOT EXISTS harness_events_type_idx
+  ON vk_harness_events (run_id, type, seq DESC);

package/dist/cost-ledger/migrations/vk_ai_cost_0006_cache_write_prices.sql

@@ -0,0 +1,17 @@
+-- @venturekit-pro/ai — prompt-cache write prices (SCHEMA ONLY).
+--
+-- Writing a prompt prefix to the provider's cache costs more than reading
+-- plain input: Anthropic 1.25× input for 5-minute entries and 2× for
+-- 1-hour entries, OpenAI GPT-5.6+ 1.25×. The gateway prices them
+-- (`src/gateway/pricing.ts`) from:
+--      cost_per_1k_cache_write     USD per 1K tokens written to the cache.
+--                                  NULL = priced at the input rate.
+--      cost_per_1k_cache_write_1h  USD per 1K tokens written with a 1-hour
+--                                  lifetime. NULL = the write rate.
+-- Mirrors `ModelDescriptor.costPer1kCacheWriteUsd` / `costPer1kCacheWrite1hUsd`.
+--
+-- Idempotent: ADD COLUMN IF NOT EXISTS.
+
+ALTER TABLE vk_llm_models
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cache_write    numeric(12, 8),
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cache_write_1h numeric(12, 8);

package/dist/cost-ledger/migrations/vk_ai_cost_0007_harness_fan_out.sql

@@ -0,0 +1,47 @@
+-- @venturekit-pro/ai — harness fan-out (SCHEMA ONLY).
+--
+-- A map node with `dispatch: 'tasks'` sends one queue message per item
+-- (src/harness/harness.ts). Each item becomes a small task row of its own
+-- in `vk_harness_map_items`:
+--      status       pending (not sent yet) · queued (its message is out)
+--                   · running (leased) · done · failed. Rows of inline maps
+--                   are `done` (the default keeps the existing rows valid).
+--      input        the item, as the node's `items()` returned it.
+--      attempt      attempts so far — never reset, so a worker left over
+--                   from an earlier node attempt can't commit.
+--      attempt_base `attempt` when the current node attempt fanned out
+--                   (its retry budget counts from there).
+--      lease_until  the worker's lease on a running item.
+--      not_before   when a retried item is due.
+--      error        the last failure.
+--      cost_usd     model spend of the item (added to the run at the join).
+-- and `vk_harness_map_joins` is the join counter: the item whose write
+-- brings `done` to `total` commits the node.
+--
+-- Idempotent: ADD COLUMN / CREATE ... IF NOT EXISTS.
+
+ALTER TABLE vk_harness_map_items
+  ADD COLUMN IF NOT EXISTS status      text           NOT NULL DEFAULT 'done',
+  ADD COLUMN IF NOT EXISTS input       jsonb,
+  ADD COLUMN IF NOT EXISTS attempt     integer        NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS attempt_base integer       NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS lease_until timestamptz,
+  ADD COLUMN IF NOT EXISTS not_before  timestamptz,
+  ADD COLUMN IF NOT EXISTS error       jsonb,
+  ADD COLUMN IF NOT EXISTS cost_usd    numeric(14, 8) NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS updated_at  timestamptz    NOT NULL DEFAULT now();
+
+-- The sweep: items whose message was lost, or whose worker died.
+CREATE INDEX IF NOT EXISTS harness_map_items_sweep_idx
+  ON vk_harness_map_items (status, updated_at)
+  WHERE status IN ('queued', 'running');
+
+CREATE TABLE IF NOT EXISTS vk_harness_map_joins (
+  run_id      uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step        integer      NOT NULL,
+  total       integer      NOT NULL,
+  done        integer      NOT NULL DEFAULT 0,
+  created_at  timestamptz  NOT NULL DEFAULT now(),
+  updated_at  timestamptz  NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, step)
+);

package/dist/gateway/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A policy denied the call (no credits, model not allowed, provider
+ * switched off). When every candidate is denied, the last denial is
+ * thrown to the caller.
+ */
+export declare class GatewayPolicyError extends Error {
+    readonly policy: string;
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(policy: string, code: string, message: string, details?: Record<string, unknown>);
+}
+/** No candidate could serve the call (unknown / disabled models, no API key). */
+export declare class GatewayUnavailableError extends Error {
+    readonly code = "model_unavailable";
+    readonly attempts: Array<{
+        modelKey: string;
+        reason?: string;
+    }>;
+    constructor(message: string, attempts: Array<{
+        modelKey: string;
+        reason?: string;
+    }>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/gateway/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/gateway/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE/B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO7F;AAED,iFAAiF;AACjF,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;gBAEpD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAKpF"}

package/dist/gateway/errors.js

@@ -0,0 +1,29 @@
+/**
+ * A policy denied the call (no credits, model not allowed, provider
+ * switched off). When every candidate is denied, the last denial is
+ * thrown to the caller.
+ */
+export class GatewayPolicyError extends Error {
+    policy;
+    code;
+    details;
+    constructor(policy, code, message, details) {
+        super(message);
+        this.name = 'GatewayPolicyError';
+        this.policy = policy;
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}
+/** No candidate could serve the call (unknown / disabled models, no API key). */
+export class GatewayUnavailableError extends Error {
+    code = 'model_unavailable';
+    attempts;
+    constructor(message, attempts) {
+        super(message);
+        this.name = 'GatewayUnavailableError';
+        this.attempts = attempts;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/gateway/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/gateway/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAS;IACf,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YAAY,MAAc,EAAE,IAAY,EAAE,OAAe,EAAE,OAAiC;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,GAAG,mBAAmB,CAAC;IAC3B,QAAQ,CAA+C;IAEhE,YAAY,OAAe,EAAE,QAAsD;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/gateway/gateway.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `createLlmGateway` — the one call path for text models.
+ *
+ * Per call, in order:
+ *   1. Route    — `[model, ...fallbacks]`, rewritten by `route` when set
+ *                 (`tierRoute` maps a request's `tier` to catalog keys).
+ *   2. Resolve  — catalog lookup; unknown and disabled models are skipped.
+ *   3. Policies — per candidate; a denial skips to the next candidate, a
+ *                 policy that itself throws denies (fail closed).
+ *   4. Credentials — a missing key skips to the next candidate.
+ *   5. Call     — retries 429 / 5xx / network (`fallback/retry`), then
+ *                 falls back; a caller error (other 4xx) fails at once;
+ *                 cancellation stops everything. A fallback never reuses
+ *                 the primary's vendor idempotency key. A stream may retry
+ *                 and fall back only until its first event.
+ *   6. Record   — one audit row per call (served or not) and one ledger
+ *                 row per billed call. Sink failures are reported, never
+ *                 thrown.
+ *
+ * With a `tracer`, every call is one `chat <model>` span (GenAI semantic
+ * conventions, see `../tracing`).
+ */
+import type { GatewayRequest, LlmCallRequestRecord, LlmGateway, LlmGatewayConfig } from './types.js';
+export declare function createLlmGateway(config: LlmGatewayConfig): LlmGateway;
+/** The request as the audit trail keeps it: full text, file and image bytes as size + hash. */
+export declare function requestRecord(request: GatewayRequest): LlmCallRequestRecord;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/gateway/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAwBH,OAAO,KAAK,EAKV,cAAc,EAId,oBAAoB,EAEpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAC;AA4BpB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA6ZrE;AAwDD,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,oBAAoB,CAsB3E"}