@intentface/latch-core 0.9.1

package/dist/models/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/models/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAsC,CAAC;AAErF,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAKtE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GACxD,UAAU,GAAG,SAAS,CAIxB"}

package/dist/models/provider.js

@@ -0,0 +1,22 @@
+export const PROVIDER_IDS = ["anthropic", "openai", "google"];
+/** Provider by id prefix alone: claude → anthropic; gpt/o-series → openai; gemini/gemma → google. */
+export function providerFromId(modelId) {
+    if (/^claude/i.test(modelId))
+        return "anthropic";
+    if (/^(gpt|o\d|chatgpt)/i.test(modelId))
+        return "openai";
+    if (/^(gemini|gemma)/i.test(modelId))
+        return "google";
+    return undefined;
+}
+/**
+ * Provider for a model id: the catalog's answer when the id is listed, else the
+ * id-prefix heuristic. `catalog` is any list of `{ id, provider }`.
+ */
+export function providerOf(modelId, catalog) {
+    const listed = catalog?.find((m) => m.id === modelId)?.provider;
+    if (listed && PROVIDER_IDS.includes(listed))
+        return listed;
+    return providerFromId(modelId);
+}
+//# sourceMappingURL=provider.js.map

package/dist/models/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/models/provider.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErF,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,WAAW,CAAC;IACjD,IAAI,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzD,IAAI,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,OAAyD;IAEzD,MAAM,MAAM,GAAG,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,QAAQ,CAAC;IAChE,IAAI,MAAM,IAAK,YAAkC,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,MAAoB,CAAC;IAChG,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/models/reasoning.d.ts

@@ -0,0 +1,21 @@
+import type { ModelInfo } from "./catalog.js";
+/**
+ * Per-agent reasoning effort. Providers don't share one knob — OpenAI takes an
+ * effort enum, Anthropic/Google take a thinking-token budget — so a single
+ * `effort` level is mapped to each provider's shape here. Gated to
+ * reasoning-capable models so a non-thinking model is a no-op rather than an
+ * API error.
+ */
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+export interface ReasoningResolution {
+    providerOptions?: Record<string, unknown>;
+    maxOutputTokens?: number;
+}
+/**
+ * Build the `RuntimeConfig.resolveReasoningOptions` hook over the model catalog.
+ * Returns `providerOptions` (keyed by provider id) plus a safe `maxOutputTokens`
+ * for the token-budget providers (the budget must stay under the model's max
+ * output, and the answer needs room after thinking).
+ */
+export declare function makeResolveReasoningOptions(models: readonly ModelInfo[]): (modelId: string, effort: string) => ReasoningResolution | undefined;
+//# sourceMappingURL=reasoning.d.ts.map

package/dist/models/reasoning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.d.ts","sourceRoot":"","sources":["../../src/models/reasoning.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAYpE,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,IAE9D,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,mBAAmB,GAAG,SAAS,CA6C1E"}

package/dist/models/reasoning.js

@@ -0,0 +1,59 @@
+const EFFORTS = ["minimal", "low", "medium", "high"];
+/** Thinking-token budgets per effort (Anthropic/Google). OpenAI uses the enum directly. */
+const BUDGET = {
+    minimal: 0,
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+};
+/**
+ * Build the `RuntimeConfig.resolveReasoningOptions` hook over the model catalog.
+ * Returns `providerOptions` (keyed by provider id) plus a safe `maxOutputTokens`
+ * for the token-budget providers (the budget must stay under the model's max
+ * output, and the answer needs room after thinking).
+ */
+export function makeResolveReasoningOptions(models) {
+    const byId = new Map(models.map((m) => [m.id, m]));
+    return (modelId, effort) => {
+        const info = byId.get(modelId);
+        const eff = EFFORTS.includes(effort) ? effort : undefined;
+        // No (valid) effort, or a model not known to support reasoning: don't
+        // touch thinking config — but still lift the SDK's tiny Anthropic/Google
+        // default max_tokens (4096). Models that think by DEFAULT (e.g.
+        // claude-sonnet-5) can burn all 4096 inside the thinking block on a heavy
+        // turn and end the run with an empty message.
+        if (!eff || !info?.reasoning) {
+            // Same fallback as the effort path: a catalog entry without maxOutput
+            // must still lift the 4096 default.
+            return info?.provider === "anthropic" || info?.provider === "google"
+                ? { maxOutputTokens: Math.min(info.maxOutput ?? 32_000, 32_000) }
+                : undefined;
+        }
+        const provider = info.provider;
+        if (provider === "openai") {
+            return { providerOptions: { openai: { reasoningEffort: eff } } };
+        }
+        // Token-budget providers (Anthropic, Google): cap the budget under the
+        // model's max output, and set maxOutputTokens so the answer has room.
+        const max = info.maxOutput ?? 32_000;
+        const budget = Math.min(BUDGET[eff], Math.max(1024, Math.floor(max / 2)));
+        const maxOutputTokens = Math.min(max, budget + 8192);
+        if (provider === "google") {
+            return {
+                providerOptions: {
+                    google: { thinkingConfig: { thinkingBudget: eff === "minimal" ? 0 : budget, includeThoughts: true } },
+                },
+                maxOutputTokens,
+            };
+        }
+        // Anthropic: minimal turns thinking off; otherwise an explicit budget.
+        if (eff === "minimal") {
+            return { providerOptions: { anthropic: { thinking: { type: "disabled" } } } };
+        }
+        return {
+            providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: budget }, sendReasoning: true } },
+            maxOutputTokens,
+        };
+    };
+}
+//# sourceMappingURL=reasoning.js.map

package/dist/models/reasoning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.js","sourceRoot":"","sources":["../../src/models/reasoning.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,GAA+B,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEjF,2FAA2F;AAC3F,MAAM,MAAM,GAAoC;IAC9C,OAAO,EAAE,CAAC;IACV,GAAG,EAAE,IAAI;IACT,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,KAAK;CACZ,CAAC;AAOF;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAA4B;IACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,OAAO,CAAC,OAAe,EAAE,MAAc,EAAmC,EAAE;QAC1E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAyB,CAAC,CAAC,CAAC,CAAE,MAA0B,CAAC,CAAC,CAAC,SAAS,CAAC;QAClG,sEAAsE;QACtE,yEAAyE;QACzE,gEAAgE;QAChE,0EAA0E;QAC1E,8CAA8C;QAC9C,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7B,sEAAsE;YACtE,oCAAoC;YACpC,OAAO,IAAI,EAAE,QAAQ,KAAK,WAAW,IAAI,IAAI,EAAE,QAAQ,KAAK,QAAQ;gBAClE,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,MAAM,EAAE,MAAM,CAAC,EAAE;gBACjE,CAAC,CAAC,SAAS,CAAC;QAChB,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAE/B,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;QACnE,CAAC;QAED,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;QAErD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO;gBACL,eAAe,EAAE;oBACf,MAAM,EAAE,EAAE,cAAc,EAAE,EAAE,cAAc,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,EAAE;iBACtG;gBACD,eAAe;aAChB,CAAC;QACJ,CAAC;QAED,uEAAuE;QACvE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,EAAE,eAAe,EAAE,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC;QAChF,CAAC;QACD,OAAO;YACL,eAAe,EAAE,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE;YAC5G,eAAe;SAChB,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/pricing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cost calculation — a small seam over token usage.
+ *
+ * `Pricing` maps a model id to its per-million-token rates; the runtime applies
+ * it to each turn's usage and records the cost on the message, the run, and the
+ * usage ledger. Inject a static table now (`staticPricing`); a models.dev-backed
+ * catalog (live rates, cached in the DB) can replace it behind the same seam.
+ */
+/** Rate card for one model, in the account's currency unit per 1M tokens. */
+export interface ModelPrice {
+    inputPer1M: number;
+    outputPer1M: number;
+    /** Cached-prompt READ rate (much cheaper). Falls back to the input rate. */
+    cacheReadPer1M?: number;
+    /** Cache WRITE/creation rate (Anthropic charges a premium). Falls back to input. */
+    cacheWritePer1M?: number;
+    /**
+     * Higher rates that apply to the WHOLE turn once its input exceeds
+     * `thresholdTokens` (long-context pricing, e.g. OpenAI's >200k tier). Cache
+     * rates fall back to the tier's input rate when absent.
+     */
+    tier?: {
+        thresholdTokens: number;
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadPer1M?: number;
+        cacheWritePer1M?: number;
+    };
+}
+/** A turn's token usage, split so cached input can be priced separately. */
+export interface UsageBreakdown {
+    /** Total prompt tokens (cached + non-cached). */
+    inputTokens: number;
+    outputTokens: number;
+    /** Cached prompt tokens READ (billed at `cacheReadPer1M`). */
+    cacheReadTokens?: number;
+    /** Cache-creation tokens WRITTEN (billed at `cacheWritePer1M`). */
+    cacheWriteTokens?: number;
+}
+/** Resolve a model id to its price, or undefined if unknown (→ cost 0). */
+export type Pricing = (model: string) => ModelPrice | undefined;
+/**
+ * Cost for a turn's token usage under a price (0 if no price). Cached prompt
+ * tokens are billed at the cache read/write rates (providers auto-cache repeated
+ * prefixes — e.g. a tool loop re-sending context — so cache reads are far
+ * cheaper than fresh input). `inputTokens` is the TOTAL; the non-cached
+ * remainder bills at the full input rate.
+ */
+export declare function computeCost(price: ModelPrice | undefined, usage: UsageBreakdown): number;
+/** A `Pricing` from a static `{ modelId: ModelPrice }` table. */
+export declare function staticPricing(table: Record<string, ModelPrice>): Pricing;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,IAAI,CAAC,EAAE;QACL,eAAe,EAAE,MAAM,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAiBxF;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,OAAO,CAExE"}

package/dist/pricing.js

@@ -0,0 +1,37 @@
+/**
+ * Cost calculation — a small seam over token usage.
+ *
+ * `Pricing` maps a model id to its per-million-token rates; the runtime applies
+ * it to each turn's usage and records the cost on the message, the run, and the
+ * usage ledger. Inject a static table now (`staticPricing`); a models.dev-backed
+ * catalog (live rates, cached in the DB) can replace it behind the same seam.
+ */
+/**
+ * Cost for a turn's token usage under a price (0 if no price). Cached prompt
+ * tokens are billed at the cache read/write rates (providers auto-cache repeated
+ * prefixes — e.g. a tool loop re-sending context — so cache reads are far
+ * cheaper than fresh input). `inputTokens` is the TOTAL; the non-cached
+ * remainder bills at the full input rate.
+ */
+export function computeCost(price, usage) {
+    if (!price)
+        return 0;
+    // Long-context tier: once input crosses the threshold, the whole turn bills
+    // at the higher rates (cache rates fall back to that tier's input rate).
+    const useTier = !!price.tier && usage.inputTokens > price.tier.thresholdTokens;
+    const r = useTier && price.tier ? price.tier : price;
+    const inputRate = r.inputPer1M;
+    const cacheRead = usage.cacheReadTokens ?? 0;
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+    const nonCached = Math.max(0, usage.inputTokens - cacheRead - cacheWrite);
+    const per = (n, rate) => (n / 1_000_000) * rate;
+    return (per(nonCached, inputRate) +
+        per(cacheRead, r.cacheReadPer1M ?? inputRate) +
+        per(cacheWrite, r.cacheWritePer1M ?? inputRate) +
+        per(usage.outputTokens, r.outputPer1M));
+}
+/** A `Pricing` from a static `{ modelId: ModelPrice }` table. */
+export function staticPricing(table) {
+    return (model) => table[model];
+}
+//# sourceMappingURL=pricing.js.map

package/dist/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../src/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAsCH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAA6B,EAAE,KAAqB;IAC9E,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC;IAC/E,MAAM,CAAC,GAAG,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IACrD,MAAM,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC;IAC/B,MAAM,SAAS,GAAG,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;IAC1E,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;IAChE,OAAO,CACL,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC;QACzB,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,cAAc,IAAI,SAAS,CAAC;QAC7C,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,eAAe,IAAI,SAAS,CAAC;QAC/C,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,WAAW,CAAC,CACvC,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,KAAiC;IAC7D,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC"}

package/dist/principal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Identity & tenancy primitives.
+ *
+ * Latch carries NO tenancy vocabulary of its own. The customer defines their
+ * own `Principal` type (`P`) — whatever their auth produces (tenant/team/user,
+ * a workspace id, a single user id, anything). It must be JSON-serializable, so
+ * the runtime can persist it per run and rebuild it for resume/cron.
+ *
+ * The framework treats `P` as opaque: it threads it to the storage adapter,
+ * secret store, context builder, tools, and agents — but never reads a field of
+ * it. Isolation is enforced in the adapter/store (via an `owner` key derived
+ * from the principal), and authorization lives in the customer's app. There is
+ * no `Scope`, no `orgId`/`userId` — those, if they exist, live in the
+ * customer's `P` and the `owner` function they give their adapter.
+ *
+ * CONTRACT — principals persist in CLEARTEXT. The runtime serializes `P`
+ * verbatim onto durable rows (`runs.identity`, `schedules.identity`, memory
+ * episodes) and into OAuth flow state, and replays it on resume/cron — days
+ * or months later. Therefore a principal must carry DURABLE IDENTIFIERS ONLY:
+ *   - never secrets or tokens (they'd be stored unencrypted and replayed
+ *     stale — credentials belong in the Vault);
+ *   - no PII beyond ids (emails, names — they'd spread across tables and
+ *     complicate erasure);
+ *   - nothing volatile (roles, flags, session state — a replayed copy would
+ *     silently disagree with reality; derive those per turn in
+ *     `context.build`, and re-validate stale identity in
+ *     `reconstructPrincipal`).
+ */
+/** Maps an incoming web request to a `Principal`. Customer-provided. Null = unauthenticated. */
+export type ContextResolver<P> = (request: Request) => P | null | Promise<P | null>;
+/**
+ * Rebuilds a `Principal` from the opaque identity blob persisted on a run, for
+ * non-interactive triggers (resume, cron) where there is no request. The mirror
+ * of `ContextResolver`. Default in the runtime is a passthrough.
+ */
+export type ReconstructPrincipal<P> = (identity: unknown) => P | Promise<P>;
+//# sourceMappingURL=principal.d.ts.map

package/dist/principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.d.ts","sourceRoot":"","sources":["../src/principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gGAAgG;AAChG,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAC/B,OAAO,EAAE,OAAO,KACb,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/principal.js

@@ -0,0 +1,30 @@
+/**
+ * Identity & tenancy primitives.
+ *
+ * Latch carries NO tenancy vocabulary of its own. The customer defines their
+ * own `Principal` type (`P`) — whatever their auth produces (tenant/team/user,
+ * a workspace id, a single user id, anything). It must be JSON-serializable, so
+ * the runtime can persist it per run and rebuild it for resume/cron.
+ *
+ * The framework treats `P` as opaque: it threads it to the storage adapter,
+ * secret store, context builder, tools, and agents — but never reads a field of
+ * it. Isolation is enforced in the adapter/store (via an `owner` key derived
+ * from the principal), and authorization lives in the customer's app. There is
+ * no `Scope`, no `orgId`/`userId` — those, if they exist, live in the
+ * customer's `P` and the `owner` function they give their adapter.
+ *
+ * CONTRACT — principals persist in CLEARTEXT. The runtime serializes `P`
+ * verbatim onto durable rows (`runs.identity`, `schedules.identity`, memory
+ * episodes) and into OAuth flow state, and replays it on resume/cron — days
+ * or months later. Therefore a principal must carry DURABLE IDENTIFIERS ONLY:
+ *   - never secrets or tokens (they'd be stored unencrypted and replayed
+ *     stale — credentials belong in the Vault);
+ *   - no PII beyond ids (emails, names — they'd spread across tables and
+ *     complicate erasure);
+ *   - nothing volatile (roles, flags, session state — a replayed copy would
+ *     silently disagree with reality; derive those per turn in
+ *     `context.build`, and re-validate stale identity in
+ *     `reconstructPrincipal`).
+ */
+export {};
+//# sourceMappingURL=principal.js.map

package/dist/principal.js.map

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

package/dist/projections.d.ts

@@ -0,0 +1,37 @@
+import { type ModelMessage } from "ai";
+import type { AppMessage } from "./message.js";
+/**
+ * The two message projections (see `message.ts`). `AppMessage` is the stored
+ * source of truth; these derive what each *audience* sees, reading the two
+ * metadata axes. Both default permissively: absent `visibility` → shown to the
+ * user; absent `sendToModel` → fed to the model. Exceptions are explicit.
+ */
+/** Client projection: keep user-visible messages, drop `internal`/`redacted`. */
+export declare function toClientMessages(messages: AppMessage[]): AppMessage[];
+/** The part type that marks a compaction boundary (see `sliceAtCompaction`). */
+export declare const COMPACTION_PART_TYPE = "data-compaction";
+/**
+ * The live context window: everything from the LAST compaction marker onward.
+ *
+ * `compactChat` summarizes a conversation and appends the summary as one message
+ * carrying a `data-compaction` part; from then on the model sees that summary
+ * instead of the turns it replaces, while stored history — and the client
+ * projection — keep everything. No marker → the messages unchanged, so chats
+ * that were never compacted are untouched.
+ *
+ * Slicing at a marker can orphan a `tool_result` from its `tool_use` only if the
+ * two straddled the boundary, which can't happen: the marker is appended at the
+ * tail of a settled conversation, so a call and its result are always on the
+ * same side of it.
+ */
+export declare function sliceAtCompaction(messages: AppMessage[]): AppMessage[];
+/**
+ * Model projection: cut to the live context window, drop `sendToModel === false`,
+ * neutralize audio file parts, close any dangling tool calls, then convert to
+ * model messages. (`data-*` parts — e.g. the compaction marker — are dropped by
+ * the SDK during conversion, so they never reach the model.)
+ */
+export declare function toModelMessages(messages: AppMessage[], opts?: {
+    tools?: Record<string, unknown>;
+}): Promise<ModelMessage[]>;
+//# sourceMappingURL=projections.d.ts.map

package/dist/projections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projections.d.ts","sourceRoot":"","sources":["../src/projections.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,IAAI,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;GAKG;AAEH,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAErE;AAmFD,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAQtE;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,EAAE,EACtB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACzC,OAAO,CAAC,YAAY,EAAE,CAAC,CAOzB"}

package/dist/projections.js

@@ -0,0 +1,128 @@
+import { convertToModelMessages } from "ai";
+/**
+ * The two message projections (see `message.ts`). `AppMessage` is the stored
+ * source of truth; these derive what each *audience* sees, reading the two
+ * metadata axes. Both default permissively: absent `visibility` → shown to the
+ * user; absent `sendToModel` → fed to the model. Exceptions are explicit.
+ */
+/** Client projection: keep user-visible messages, drop `internal`/`redacted`. */
+export function toClientMessages(messages) {
+    return messages.filter((m) => (m.metadata?.visibility ?? "user") === "user");
+}
+/**
+ * Close any tool call left without a result — an undecided `approval-requested`
+ * part, or a tool that was still running when the turn was interrupted (e.g. the
+ * user sent a new message before it finished). `convertToModelMessages` throws
+ * (and Anthropic rejects) on a `tool_use` with no following `tool_result`, so we
+ * give such parts a synthetic terminal output. Projection-only — the stored
+ * history is untouched; the synthetic result just keeps the model view valid.
+ */
+function closeDanglingToolCalls(messages) {
+    const lastIndex = messages.length - 1;
+    return messages.map((m, i) => {
+        const parts = m.parts;
+        if (m.role !== "assistant" || !Array.isArray(parts))
+            return m;
+        // Tail = the final message of the history: the continuation the tool loop
+        // re-runs. Only there will an approved-but-unexecuted call actually execute.
+        const isTail = i === lastIndex;
+        let changed = false;
+        const next = parts.map((p) => {
+            const type = typeof p.type === "string" ? p.type : "";
+            const isToolCall = type === "dynamic-tool" || type.startsWith("tool-");
+            if (!isToolCall)
+                return p;
+            const state = p.state;
+            const approval = p.approval;
+            // Close ONLY calls that nothing will resolve:
+            //  - an interrupted execution (a call with no result, no approval flow),
+            //  - an UN-decided approval (abandoned by a new message instead of a decision), or
+            //  - an APPROVED call with no result that is no longer the tail — its
+            //    continuation was interrupted (crash/restart mid-execution) and a later
+            //    message buried it, so no re-run will ever execute it.
+            // Leave tail-position approved calls and denied approvals alone — the
+            // re-run executes the former; the SDK synthesizes a denial result for the latter.
+            const interrupted = state === "input-available" || state === "input-streaming";
+            const undecidedApproval = state === "approval-requested" && (!approval || approval.approved === undefined);
+            const buriedApproved = !isTail &&
+                state === "approval-responded" &&
+                approval?.approved === true &&
+                p.output == null;
+            if (!interrupted && !undecidedApproval && !buriedApproved)
+                return p;
+            changed = true;
+            return {
+                ...p,
+                state: "output-available",
+                output: p.output ?? {
+                    interrupted: true,
+                    reason: "Not completed — superseded by a new message before this tool finished.",
+                },
+            };
+        });
+        return changed ? { ...m, parts: next } : m;
+    });
+}
+/**
+ * Replace audio file parts with a text placeholder. Voice messages ingested
+ * before channel-side transcription existed were stored as `audio/*` file
+ * parts, and a chat model without audio input (Anthropic) rejects the whole
+ * prompt — bricking every later turn of that chat. Projection-only — the
+ * stored history keeps the original part.
+ */
+function replaceAudioFileParts(messages) {
+    return messages.map((m) => {
+        const parts = m.parts;
+        if (!Array.isArray(parts))
+            return m;
+        let changed = false;
+        const next = parts.map((p) => {
+            const isAudio = p.type === "file" && typeof p.mediaType === "string" && p.mediaType.startsWith("audio/");
+            if (!isAudio)
+                return p;
+            changed = true;
+            const name = typeof p.filename === "string" ? p.filename : "audio";
+            return {
+                type: "text",
+                text: `[A voice message ("${name}") was attached here but could not be included — audio input is not supported.]`,
+            };
+        });
+        return changed ? { ...m, parts: next } : m;
+    });
+}
+/** The part type that marks a compaction boundary (see `sliceAtCompaction`). */
+export const COMPACTION_PART_TYPE = "data-compaction";
+/**
+ * The live context window: everything from the LAST compaction marker onward.
+ *
+ * `compactChat` summarizes a conversation and appends the summary as one message
+ * carrying a `data-compaction` part; from then on the model sees that summary
+ * instead of the turns it replaces, while stored history — and the client
+ * projection — keep everything. No marker → the messages unchanged, so chats
+ * that were never compacted are untouched.
+ *
+ * Slicing at a marker can orphan a `tool_result` from its `tool_use` only if the
+ * two straddled the boundary, which can't happen: the marker is appended at the
+ * tail of a settled conversation, so a call and its result are always on the
+ * same side of it.
+ */
+export function sliceAtCompaction(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const parts = messages[i].parts;
+        if (Array.isArray(parts) && parts.some((p) => p.type === COMPACTION_PART_TYPE)) {
+            return messages.slice(i);
+        }
+    }
+    return messages;
+}
+/**
+ * Model projection: cut to the live context window, drop `sendToModel === false`,
+ * neutralize audio file parts, close any dangling tool calls, then convert to
+ * model messages. (`data-*` parts — e.g. the compaction marker — are dropped by
+ * the SDK during conversion, so they never reach the model.)
+ */
+export async function toModelMessages(messages, opts) {
+    const forModel = closeDanglingToolCalls(replaceAudioFileParts(sliceAtCompaction(messages).filter((m) => m.metadata?.sendToModel !== false)));
+    return convertToModelMessages(forModel, (opts ?? {}));
+}
+//# sourceMappingURL=projections.js.map

package/dist/projections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projections.js","sourceRoot":"","sources":["../src/projections.ts"],"names":[],"mappings":"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"}

package/dist/prompt-caching.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Prompt-caching plans: which provider options a turn should set so the model
+ * provider caches the stable prompt prefix (tool definitions, system prompt,
+ * conversation history) instead of re-billing it every step.
+ *
+ * Kept provider-generic in core: the PLATFORM decides which provider a model id
+ * belongs to (it owns the catalog) and calls `promptCachingPlanFor` from its
+ * `RuntimeConfig.resolvePromptCaching` hook; core only applies the plan in
+ * `buildTurn`. Providers not named here (e.g. Google: implicit caching only)
+ * get no plan and are untouched.
+ *
+ * Anthropic layout — three of the four allowed `cache_control` breakpoints:
+ *  1. The LAST function tool definition. Tools render before the system prompt
+ *     in the request, so this keeps the (often large, MCP-heavy) tool prefix
+ *     cached even when the system block changes mid-conversation (e.g. a
+ *     memory-index write).
+ *  2. The system message that holds the agent instructions + memory block. The
+ *     day-granular date line is a SEPARATE, unmarked system message after it,
+ *     so the daily date flip never invalidates this breakpoint.
+ *  3. A request-level (top-level) `cache_control` — Anthropic's automatic
+ *     caching: the API places a breakpoint on the last cacheable block of the
+ *     request. The AI SDK re-sends call-level providerOptions on every step of
+ *     the tool loop, so this breakpoint ROLLS to the newest tool result with no
+ *     per-step code. Note: top-level cache_control is a first-party Claude API
+ *     feature (not Bedrock/Vertex); block-level markers work everywhere. Also
+ *     note the SDK's client-side breakpoint validator counts only block-level
+ *     markers, so the request-level one is invisible to it — harmless.
+ *
+ * TTL is left at the provider default (5m). Agents whose turns arrive slower
+ * than that won't benefit — that's surfaced by the platform's caching lint,
+ * not worked around here.
+ */
+export interface PromptCachingPlan {
+    /**
+     * Call-level providerOptions (merged with e.g. reasoning options). Anthropic:
+     * the rolling request-level breakpoint. OpenAI: `promptCacheKey` for cache
+     * routing (OpenAI caches automatically; the key only improves shard routing).
+     */
+    requestProviderOptions?: Record<string, Record<string, unknown>>;
+    /**
+     * providerOptions for the system message carrying the agent instructions.
+     * Presence also signals `buildTurn` to split the system prompt into two
+     * messages so volatile trailing content (the date line) lands AFTER the
+     * breakpoint.
+     */
+    systemProviderOptions?: Record<string, Record<string, unknown>>;
+    /**
+     * providerOptions to place on the LAST active function tool definition
+     * (a breakpoint covering the whole tools prefix). Applied via
+     * `markLastFunctionTool`.
+     */
+    toolProviderOptions?: Record<string, Record<string, unknown>>;
+}
+/**
+ * The caching plan for a provider family (`"anthropic"`, `"openai"`, …).
+ * `cacheKeySuffix` scopes OpenAI's cache routing key beyond the agent name —
+ * pass a per-principal key for agents whose system prompt is per-principal
+ * (e.g. memory-enabled agents), so structurally different prefixes don't
+ * co-route to one shard.
+ */
+export declare function promptCachingPlanFor(provider: string | undefined, opts: {
+    agent: string;
+    cacheKeySuffix?: string;
+}): PromptCachingPlan | undefined;
+/**
+ * The DEFAULT caching plan, used when the runtime has no `resolvePromptCaching`
+ * hook: derive the provider family from the model object itself — every AI SDK
+ * `LanguageModel` carries a `provider` string (`"anthropic.messages"`,
+ * `"openai.responses"`, …) — and apply {@link promptCachingPlanFor}. Measured
+ * on a real MCP-heavy agent, this is a ~6x difference in unit cost (a ~32k-token
+ * tool catalogue re-billed every step vs read from cache), which is not a
+ * default a customer should have to discover by reading source.
+ *
+ * Deliberately conservative: only FIRST-PARTY Anthropic/OpenAI provider ids
+ * match (Bedrock/Vertex ids don't contain these substrings), because the
+ * Anthropic plan's request-level `cache_control` is a first-party feature.
+ * Unknown providers get no plan and are untouched. Opt out entirely with
+ * `resolvePromptCaching: () => undefined`, or per turn with
+ * `promptCaching: false`.
+ */
+export declare function defaultPromptCachingPlan(model: unknown, agent: string): PromptCachingPlan | undefined;
+/**
+ * One-level-deep merge of providerOptions objects (per provider key), so e.g.
+ * `{ anthropic: { thinking } }` from reasoning and `{ anthropic: { cacheControl } }`
+ * from caching coexist — a plain spread would clobber one with the other. Later
+ * sources win on conflicting inner keys. Returns undefined when nothing to merge.
+ */
+export declare function mergeProviderOptions(...sources: Array<Record<string, unknown> | undefined>): Record<string, unknown> | undefined;
+/**
+ * Stable fingerprint of a toolset (FNV-1a 64-bit over the sorted names) —
+ * equality is all that matters (same hash ⇔ same tool names), so a
+ * dependency-free non-cryptographic hash beats pulling in node:crypto (core
+ * stays runtime-agnostic). Stored on the run row to detect toolset churn
+ * across a chat's turns, one of the main prompt-cache invalidators.
+ */
+export declare function toolsetHash(names: Iterable<string>): string;
+/**
+ * Mark the LAST active function tool with the given providerOptions (in place).
+ * Skips provider-executed tools (`type: "provider"`, e.g. Anthropic's native
+ * web_search/web_fetch) — the provider silently drops `cache_control` on those —
+ * and, when `activeNames` is given, tools the turn filtered out via
+ * `activeTools` (a marker on an unsent tool would vanish). Returns the marked
+ * tool name, or undefined when no eligible tool exists.
+ */
+export declare function markLastFunctionTool(tools: Record<string, unknown>, providerOptions: Record<string, Record<string, unknown>>, activeNames?: readonly string[]): string | undefined;
+//# sourceMappingURL=prompt-caching.d.ts.map

package/dist/prompt-caching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-caching.d.ts","sourceRoot":"","sources":["../src/prompt-caching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChE;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,iBAAiB,GAAG,SAAS,CAoB/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,iBAAiB,GAAG,SAAS,CAW/B;AAaD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GACrD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAerC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,GAAG,SAAS,CAmBpB"}