@intentface/latch-core 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+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

@@ -0,0 +1,45 @@
+# @intentface/latch-core
+
+The framework core for building agents on the **AI SDK v7** — the runtime, the message/identity model, and the pluggable seams everything else plugs into. Dependency-light and host-agnostic (no HTTP framework, no DB, no provider SDKs).
+
+📖 **Full documentation:** [docs source](https://github.com/Intentface/intentface-latch/tree/main/apps/docs) — to read it locally, run `pnpm --filter @intentface/latch-docs dev` and open http://localhost:3100/docs.
+
+## In one screen
+
+```ts
+import { createRuntime, defineAgent, defineContext } from "@intentface/latch-core";
+
+const runtime = createRuntime<Principal, Ctx>({
+  storage, // chats, messages, runs, usage, schedules
+  context, // per-turn RuntimeContext built from the principal
+  agents, // name → agent factory
+  // …optional seams: pricing, connections, memory, cron, sandbox, telemetry
+});
+
+const response = await runtime.handleChat({ agent: "assistant", principal, message });
+```
+
+## What it does
+
+- **Runtime** (`createRuntime`) — composition root + operations facade. Runs one agent turn with a `ToolLoopAgent`, streams `UIMessage` parts, persists messages/runs/usage, and handles approvals (HITL), durability (leases + reaper), subagents, and schedules.
+- **Message model** — `AppMessage` = a typed AI SDK `UIMessage`. The source of truth; two axes (`visibility`, `sendToModel`) drive the client and model projections.
+- **Seams** — `StorageAdapter`, `ConnectionRegistry`, `Vault`, `Pricing`, `MemoryProvider`, plus the `cron` / `sandbox` / `harnessTools` / `telemetry` hooks. `Principal` stays opaque: authz is the integrator's job.
+- **Helpers** — `defineAgent`, `defineContext`, `mergeConnections`, `computeCost` / `staticPricing`, `toModelMessages` / `toClientMessages`.
+
+## Docs map
+
+| Page | Covers |
+| --- | --- |
+| Introduction | what it is, the adoption tiers, a minimal runtime |
+| Runtime | every config field, every operation, what a turn does in order |
+| Agents | `defineAgent`, capability flags, subagents, dynamic agents |
+| Turn inputs | principal, context, messages, projections, compaction |
+| Storage | the `StorageAdapter` contract and the guarantees it must make |
+| Operations | durability, schedules, human-in-the-loop |
+| Seams | connections, vault, memory, pricing, telemetry, sandbox |
+
+Runnable examples live in [`apps/example`](https://github.com/Intentface/intentface-latch/tree/main/apps/example) (source) — 23 smoke scripts covering persistence, durability, resume, approvals, MCP, vault, cost and observability.
+
+## Where it fits
+
+The base of the `@intentface/latch-*` stack. Mount it over HTTP with `latch-server`; persist with `latch-drizzle`; add tools via `latch-mcp` / `latch-openapi`; reach chat platforms with `latch-channels`. Chat UI primitives live in a separate repo, [`@intentface/chat`](https://github.com/Intentface/intentface-chat).

package/dist/agent.d.ts

@@ -0,0 +1,200 @@
+import type { LanguageModel } from "ai";
+import type { MemoryConfig } from "./memory.js";
+/**
+ * Agent definitions.
+ *
+ * An agent definition is *config*, never an instantiated engine — that's the
+ * "engine portability" invariant: the executor builds a `ToolLoopAgent` (T1) or
+ * a `WorkflowAgent` (later) from the same config. It's a lazy factory resolved
+ * per request with the typed runtime context (static config is wrapped into one).
+ */
+/**
+ * Minimal, engine-agnostic agent config (a subset of the SDK's agent settings).
+ * `tools` is kept loose for now: the SDK does export `ToolSet`, but every tool
+ * source (connections, MCP, OpenAPI, the platform's dynamic connections) builds
+ * a `Record<string, unknown>` and adopting the SDK type is one typing pass
+ * across them all. Until then the concrete engine constrains it at the call
+ * site when the run executes.
+ */
+/** A set of tools opened for a turn, plus the teardown to run when it ends. */
+export interface OpenToolSet {
+    tools: Record<string, unknown>;
+    close(): Promise<void>;
+    /**
+     * Optional per-tool approval policy contributed by this source (merged into
+     * the agent's `toolApproval`, object form). Lets a source gate its own tools —
+     * e.g. an MCP host gating a synthetic `connect_<name>` tool so an unauthorized
+     * connection pauses the turn for OAuth instead of failing.
+     */
+    toolApproval?: Record<string, unknown>;
+    /**
+     * Tools that stay callable even when an agent restricts `enabledTools` — e.g.
+     * the synthetic `connect_<name>` auth tools, which must work so the connect
+     * flow isn't blocked by a tool allow-list.
+     */
+    alwaysActive?: string[];
+}
+/**
+ * A dynamic, per-turn tool provider (e.g. an MCP host). The runtime calls
+ * `open(principal)` before the turn, merges the tools, and calls `close()` after —
+ * so connections are scoped to the caller and torn down when the turn ends.
+ * `@intentface/latch-mcp`'s `McpHost` satisfies this structurally.
+ */
+export interface ToolSource<P> {
+    open(principal: P): Promise<OpenToolSet>;
+}
+export interface AgentConfig<P> {
+    model: LanguageModel;
+    instructions?: string;
+    /** Static tools, available every turn. */
+    tools?: Record<string, unknown>;
+    /** Dynamic tool sources opened per turn and closed after (e.g. MCP). */
+    toolSources?: ToolSource<P>[];
+    /**
+     * Names of the connections (from the runtime's connection registry) this
+     * agent may use — its MCP servers / integrations. The runtime resolves these
+     * to a per-turn tool source: each authorized connection's tools, plus a gated
+     * `connect_<name>` tool for any that still need OAuth. Different agents can
+     * carry different connections. Names with no registry entry are ignored.
+     */
+    connections?: string[];
+    /**
+     * HITL approval policy (the SDK's `toolApproval`): per-tool `'user-approval'`,
+     * an object with a reason, or a function. A gated call ends the turn with an
+     * `approval-requested` part instead of executing; the decision round-trips as
+     * message state via `runtime.applyApproval`. Kept loose (the SDK type is
+     * complex); cast at the agent boundary.
+     */
+    toolApproval?: unknown;
+    /**
+     * Smooth the visible token cadence (AI SDK `smoothStream`): even out bursty
+     * deltas before they stream to the client. `true` uses the SDK defaults
+     * (~10ms, word chunking); or tune `delayInMs`/`chunking`. Presentation only —
+     * it does not change what gets persisted.
+     */
+    smoothStream?: boolean | {
+        delayInMs?: number;
+        chunking?: "word" | "line";
+    };
+    /**
+     * Max tool-loop steps before the turn stops (the SDK `stopWhen` ceiling).
+     * Omitted → SDK default (20). A number caps the loop; `"unlimited"` lets it
+     * run until the model stops on its own (no more tool calls) — use with care,
+     * it removes the runaway-loop backstop.
+     */
+    maxSteps?: number | "unlimited";
+    /**
+     * Restrict which tools the model may call (the SDK's `activeTools`) — the
+     * namespaced names (e.g. `clockify_getTimeEntries`). Omitted → all available
+     * tools are active. Tools a source marks `alwaysActive` (e.g. `connect_<name>`)
+     * stay callable regardless.
+     */
+    enabledTools?: string[];
+    /**
+     * Per-tool description overrides (by namespaced tool name). The runtime
+     * replaces the resolved tool's `description` with this text before the model
+     * sees it — e.g. to tailor a connection tool's guidance for this agent.
+     */
+    toolDescriptions?: Record<string, string>;
+    /**
+     * Agents this one may delegate to. The runtime adds a `spawn_agent` tool that
+     * runs one of these as a subagent (a normal agent, run autonomously — its
+     * tools are auto-approved) and returns its final answer. Each subagent run is
+     * its own persisted thread; pass the returned `threadId` back to continue the
+     * same subagent with full context.
+     */
+    subagents?: string[];
+    /**
+     * Give the agent a per-session sandbox (a workspace) and the filesystem/shell
+     * tools that operate on it (`bash`, `read_file`, `write_file`, `glob`,
+     * `grep`). The runtime resolves the actual `Experimental_SandboxSession` via
+     * `RuntimeConfig.sandbox` and passes it to the model; the tools come from
+     * `RuntimeConfig.harnessTools.sandbox`. Optional `provider` picks the backend
+     * (e.g. `"just-bash"` | `"daytona"`); the resolver decides the default.
+     */
+    sandbox?: boolean;
+    /** Sandbox backend hint, passed through to `RuntimeConfig.sandbox`. */
+    sandboxProvider?: string;
+    /**
+     * Add the app-runtime default harness tools (`web_fetch`, `todo`,
+     * `ask_question`) from `RuntimeConfig.harnessTools.app`. `true` adds all;
+     * an array restricts to those names. These run in the app process, not the
+     * sandbox.
+     */
+    defaultTools?: boolean | string[];
+    /**
+     * Give the agent the platform's render tool(s) from
+     * `RuntimeConfig.harnessTools.render` — a headless-browser fetch for
+     * JS-rendered pages. A separate capability flag (like `sandbox`) rather than
+     * a `defaultTools` member: the platform supplies it (needs a deployed render
+     * service) and it must be opted into explicitly, never swept in by
+     * `defaultTools: true`.
+     */
+    renderTools?: boolean;
+    /** Names of harness/default tools to drop for this agent (eve-style opt-out). */
+    disableTools?: string[];
+    /**
+     * Use the model provider's NATIVE web tools (server-side web search/fetch)
+     * when available, supplied by `RuntimeConfig.resolveProviderTools(modelId)`.
+     * Provider-specific: e.g. Anthropic exposes web_search + web_fetch, OpenAI
+     * web_search only. No-op on providers without native web tools.
+     */
+    providerWebTools?: boolean;
+    /**
+     * Reasoning/thinking effort for this agent. Mapped to provider-specific
+     * options by `RuntimeConfig.resolveReasoningOptions` (OpenAI effort enum vs
+     * Anthropic/Google thinking-token budget) and gated to reasoning-capable
+     * models. Omitted → the provider default.
+     */
+    effort?: "minimal" | "low" | "medium" | "high";
+    /**
+     * Persistent cross-session memory for this agent. Requires the runtime to be
+     * composed with a `MemoryProvider` (`RuntimeConfig.memory`) — without one the
+     * declaration is ignored. When both are set, each turn gets the provider's
+     * compiled memory index appended to `instructions` and its memory tools
+     * (`memory_search`/`memory_save`) merged as capability tools; the provider's
+     * background jobs handle extraction and consolidation out of band.
+     */
+    memory?: MemoryConfig;
+}
+/** Static, display-only metadata for an agent — surfaced by `runtime.listAgents()`. */
+export interface AgentMeta {
+    /** Human-friendly name for a picker (defaults to the registry key). */
+    title?: string;
+    /** Short description of what the agent does. */
+    description?: string;
+    /**
+     * Internal agent: still resolvable/runnable by name, but flagged so
+     * user-facing pickers can drop it. `runtime.listAgents()` returns hidden
+     * agents WITH the flag (internal callers — e.g. a builder validating
+     * subagent names — need the full set); the HTTP `GET agents` route filters
+     * them out.
+     */
+    hidden?: boolean;
+}
+/** An agent's identity for selection UIs: its registry key + display metadata. */
+export interface AgentInfo extends AgentMeta {
+    name: string;
+}
+/**
+ * A factory that produces the agent's config for a given request/context.
+ * Carries optional static `meta` (read without invoking the factory) so the
+ * runtime can list agents for a picker.
+ */
+export type AgentFactory<P, RuntimeContext = unknown> = ((ctx: {
+    /**
+     * The runtime CONTEXT built by `context.build` for this turn (org name, plan,
+     * feature flags — see `ContextDefinition`).
+     */
+    context: RuntimeContext;
+    principal: P;
+    /**
+     * The per-turn request payload (see `ContextDefinition.build`). Ephemeral —
+     * absent on resume/cron turns, so factories must not require it.
+     */
+    turnContext?: unknown;
+}) => AgentConfig<P> | Promise<AgentConfig<P>>) & {
+    meta?: AgentMeta;
+};
+export declare function defineAgent<P, RuntimeContext = unknown>(def: AgentConfig<P> | AgentFactory<P, RuntimeContext>, meta?: AgentMeta): AgentFactory<P, RuntimeContext>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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

package/dist/agent.js

@@ -0,0 +1,9 @@
+export function defineAgent(def, meta) {
+    const factory = typeof def === "function"
+        ? def
+        : () => def;
+    if (meta)
+        factory.meta = meta;
+    return factory;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAyMA,MAAM,UAAU,WAAW,CACzB,GAAqD,EACrD,IAAgB;IAEhB,MAAM,OAAO,GACX,OAAO,GAAG,KAAK,UAAU;QACvB,CAAC,CAAE,GAAuC;QAC1C,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC;IAChB,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/compaction.d.ts

@@ -0,0 +1,33 @@
+import { type LanguageModel, type ModelMessage } from "ai";
+/**
+ * Summarize a conversation for compaction with a single tool-free model call.
+ *
+ * Deliberately NOT a normal agent turn: with the agent's own tools and
+ * instructions in play the tool loop would go do work instead of summarizing.
+ */
+export declare function summarizeForCompaction(input: {
+    model: LanguageModel;
+    messages: ModelMessage[];
+    /** Extra steer from the caller, e.g. `/compact keep the training plan`. */
+    focus?: string;
+    /**
+     * Provider options for the call. Callers should pass their "don't think"
+     * mapping (see `resolveReasoningOptions`): summarizing needs no reasoning
+     * block, and on a thinking-by-default model that block competes with the
+     * summary for the same output budget.
+     */
+    providerOptions?: Record<string, unknown>;
+    /** Abort a stalled provider (a request signal, or a caller-owned timeout). */
+    signal?: AbortSignal;
+}): Promise<{
+    text: string;
+    /** True when even the shortened retry hit `MAX_SUMMARY_TOKENS`. */
+    truncated: boolean;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+}>;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,IAAI,CAAC;AA6CzE;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAClD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,8EAA8E;IAC9E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,CAAC,CA+DD"}

package/dist/compaction.js

@@ -0,0 +1,104 @@
+import { generateText } from "ai";
+/**
+ * Conversation compaction: replace a long history with a summary the model reads
+ * instead, so a chat that never ends (a Telegram DM, a months-old thread) stops
+ * growing its prompt without losing what matters.
+ *
+ * The boundary itself is a projection concern (`sliceAtCompaction` in
+ * `projections.ts`); this module only produces the summary text. Kept separate
+ * from `runtime.ts` so the prompt is easy to find and tune.
+ */
+const COMPACTION_SYSTEM = `You compact conversations so they can continue in a smaller context window.
+
+Write a summary that lets the assistant carry on as if it had read the whole
+conversation. Preserve, in this order of priority:
+1. What the user is trying to achieve, and any decisions already made.
+2. Facts about the user and their situation that came up (names, numbers, dates,
+   preferences, constraints) — these are usually irrecoverable once dropped.
+3. What has been done so far, including tool results that still matter.
+4. Anything explicitly left open, pending, or promised.
+
+Rules:
+- Write in the third person about "the user" and "the assistant".
+- Be specific: keep concrete values, drop pleasantries and dead ends.
+- Never invent anything. If something is unclear, say so plainly.
+- No preamble, no headings-for-their-own-sake, no closing remarks — just the
+  summary itself.`;
+const instructionFor = (words) => `Summarize the conversation above as described in your system prompt, so it can be continued in a fresh context window. Keep it under ${words} words. Output only the summary.`;
+/**
+ * Hard ceiling on the call. Generous on purpose: it is a backstop against a
+ * runaway summary, NOT the mechanism that keeps summaries small — that's the word
+ * target in the instruction. A tight ceiling here is actively harmful, because on
+ * a model that thinks by default the thinking block spends this budget before any
+ * summary text is produced, and the call ends truncated with nothing usable.
+ */
+const MAX_SUMMARY_TOKENS = 8000;
+/** Asked-for length. Big enough to carry a long conversation's specifics. */
+const SUMMARY_WORD_TARGET = 600;
+/** Retry target after a truncated first attempt — decisively shorter. */
+const RETRY_WORD_TARGET = 250;
+/**
+ * Summarize a conversation for compaction with a single tool-free model call.
+ *
+ * Deliberately NOT a normal agent turn: with the agent's own tools and
+ * instructions in play the tool loop would go do work instead of summarizing.
+ */
+export async function summarizeForCompaction(input) {
+    const focus = input.focus?.trim();
+    const attempt = async (words) => {
+        const instruction = instructionFor(words);
+        const res = await generateText({
+            model: input.model,
+            system: COMPACTION_SYSTEM,
+            maxOutputTokens: MAX_SUMMARY_TOKENS,
+            // Cast for the same reason `buildTurn` casts its ToolLoopAgent options: the
+            // hook's shape is `Record<string, unknown>` (it's host-supplied and
+            // provider-specific), while the SDK wants `Record<string, JSONObject>`.
+            ...(input.providerOptions
+                ? { providerOptions: input.providerOptions }
+                : {}),
+            ...(input.signal ? { abortSignal: input.signal } : {}),
+            messages: [
+                ...input.messages,
+                {
+                    role: "user",
+                    content: focus
+                        ? `${instruction}\n\nPay particular attention to: ${focus}`
+                        : instruction,
+                },
+            ],
+        });
+        // Same shape the tool loop reads per step (`onStepEnd` in runtime.ts), so the
+        // cached-prompt split reaches `computeCost` the same way.
+        const u = res.usage;
+        return {
+            text: res.text.trim(),
+            truncated: res.finishReason === "length",
+            usage: {
+                inputTokens: u?.inputTokens ?? 0,
+                outputTokens: u?.outputTokens ?? 0,
+                cacheReadTokens: u?.inputTokenDetails?.cacheReadTokens ?? 0,
+                cacheWriteTokens: u?.inputTokenDetails?.cacheWriteTokens ?? 0,
+            },
+        };
+    };
+    const first = await attempt(SUMMARY_WORD_TARGET);
+    if (!first.truncated)
+        return first;
+    // Truncated: ask again for a decisively shorter summary rather than giving up.
+    // A truncated summary must never be stored (it becomes the permanent head of
+    // every later prompt), but failing outright would mean the longest
+    // conversations — the ones that most need compacting — could never be.
+    const retry = await attempt(RETRY_WORD_TARGET);
+    return {
+        ...retry,
+        // Both calls were paid for; report the total so cost isn't understated.
+        usage: {
+            inputTokens: first.usage.inputTokens + retry.usage.inputTokens,
+            outputTokens: first.usage.outputTokens + retry.usage.outputTokens,
+            cacheReadTokens: first.usage.cacheReadTokens + retry.usage.cacheReadTokens,
+            cacheWriteTokens: first.usage.cacheWriteTokens + retry.usage.cacheWriteTokens,
+        },
+    };
+}
+//# sourceMappingURL=compaction.js.map

package/dist/compaction.js.map

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

package/dist/connections.d.ts

@@ -0,0 +1,16 @@
+import type { ToolSource } from "./agent.js";
+import type { ConnectionRegistry } from "./runtime.js";
+/**
+ * Combine tool sources into one: `open` opens all of them and merges their
+ * tools + approval policies; `close` tears them all down. Later sources win on
+ * key collisions (namespacing avoids that in practice).
+ */
+export declare function mergeToolSources<P>(...sources: ToolSource<P>[]): ToolSource<P>;
+/**
+ * Combine connection registries of different kinds (e.g. MCP + OpenAPI) into one
+ * the runtime can use. An agent's `connections: [...]` then resolves across all
+ * of them — each registry's `hostFor` ignores names it doesn't own, so the
+ * merged source is the union of whatever each kind contributes for those names.
+ */
+export declare function mergeConnections<P>(...registries: ConnectionRegistry<P>[]): ConnectionRegistry<P>;
+//# sourceMappingURL=connections.d.ts.map

package/dist/connections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAuB9E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,GACrC,kBAAkB,CAAC,CAAC,CAAC,CAKvB"}

package/dist/connections.js

@@ -0,0 +1,41 @@
+/**
+ * Combine tool sources into one: `open` opens all of them and merges their
+ * tools + approval policies; `close` tears them all down. Later sources win on
+ * key collisions (namespacing avoids that in practice).
+ */
+export function mergeToolSources(...sources) {
+    return {
+        async open(principal) {
+            const opened = await Promise.all(sources.map((s) => s.open(principal)));
+            const tools = {};
+            const toolApproval = {};
+            const alwaysActive = [];
+            for (const o of opened) {
+                Object.assign(tools, o.tools);
+                Object.assign(toolApproval, o.toolApproval ?? {});
+                if (o.alwaysActive)
+                    alwaysActive.push(...o.alwaysActive);
+            }
+            return {
+                tools,
+                toolApproval,
+                // Preserve each source's always-callable tools (e.g. the synthetic
+                // connect_<name> auth tools) so a tool-restricted agent keeps them.
+                alwaysActive,
+                close: () => Promise.all(opened.map((o) => o.close().catch(() => { }))).then(() => undefined),
+            };
+        },
+    };
+}
+/**
+ * Combine connection registries of different kinds (e.g. MCP + OpenAPI) into one
+ * the runtime can use. An agent's `connections: [...]` then resolves across all
+ * of them — each registry's `hostFor` ignores names it doesn't own, so the
+ * merged source is the union of whatever each kind contributes for those names.
+ */
+export function mergeConnections(...registries) {
+    return {
+        hostFor: (names) => mergeToolSources(...registries.map((r) => r.hostFor(names))),
+    };
+}
+//# sourceMappingURL=connections.js.map

package/dist/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../src/connections.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAI,GAAG,OAAwB;IAC7D,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,SAAS;YAClB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YACxE,MAAM,KAAK,GAA4B,EAAE,CAAC;YAC1C,MAAM,YAAY,GAA4B,EAAE,CAAC;YACjD,MAAM,YAAY,GAAa,EAAE,CAAC;YAClC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;gBACvB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC9B,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;gBAClD,IAAI,CAAC,CAAC,YAAY;oBAAE,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;YAC3D,CAAC;YACD,OAAO;gBACL,KAAK;gBACL,YAAY;gBACZ,mEAAmE;gBACnE,oEAAoE;gBACpE,YAAY;gBACZ,KAAK,EAAE,GAAG,EAAE,CACV,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;aAClF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAG,UAAmC;IAEtC,OAAO;QACL,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,gBAAgB,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;KAC/D,CAAC;AACJ,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-project context definition.
+ *
+ * The AI SDK only has raw per-call `runtimeContext` / `toolsContext`. `defineContext`
+ * is thin sugar (OURS, not an SDK API): a project declares its `RuntimeContext`
+ * shape once and builds it per request from the (opaque, customer-typed)
+ * `Principal`. The type then flows through `defineAgent`, prepareStep, hooks,
+ * and tools.
+ *
+ * Tools receive the built context automatically: the runtime hands every tool
+ * `{ ...runtimeContext, principal, run, writer, runtime }` as its
+ * `options.context` (the runtime itself included, so a harness tool can
+ * schedule or spawn without a host-global), so a tool that needs a credential
+ * resolves it itself, scoped by the principal
+ * (e.g. `vault.resolver(ctx.principal, "crm_api_key")`) — the model never sees
+ * the value.
+ *
+ * Derive runtime context from DURABLE identity (look things up by ids on the
+ * principal), so a resumed run or a scheduled trigger — which has no request —
+ * rebuilds the same context.
+ */
+/** Reads a secret for a principal (the Vault read-side; isolation lives in the store). */
+export type SecretResolver<P> = (principal: P, key: string) => Promise<string | undefined>;
+export interface ContextDefinition<P, RuntimeContext> {
+    /**
+     * Build the shared runtime context for a request from its principal.
+     *
+     * `turnContext` is the per-turn request payload (e.g. the parsed POST body or
+     * a caller-supplied object) — EPHEMERAL by design. Unlike the principal it is
+     * never persisted with a run, so a resumed/cron-fired turn rebuilds context
+     * without it: derive anything durable from the principal, and treat
+     * `turnContext` as optional per-turn enrichment only.
+     */
+    build: (args: {
+        principal: P;
+        request?: Request;
+        turnContext?: unknown;
+    }) => RuntimeContext | Promise<RuntimeContext>;
+}
+export declare function defineContext<P, RuntimeContext>(def: ContextDefinition<P, RuntimeContext>): ContextDefinition<P, RuntimeContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,0FAA0F;AAC1F,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAC9B,SAAS,EAAE,CAAC,EACZ,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjC,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,cAAc;IAClD;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE;QACZ,SAAS,EAAE,CAAC,CAAC;QACb,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAChD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,EAC7C,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,cAAc,CAAC,GACxC,iBAAiB,CAAC,CAAC,EAAE,cAAc,CAAC,CAEtC"}

package/dist/context.js

@@ -0,0 +1,25 @@
+/**
+ * Per-project context definition.
+ *
+ * The AI SDK only has raw per-call `runtimeContext` / `toolsContext`. `defineContext`
+ * is thin sugar (OURS, not an SDK API): a project declares its `RuntimeContext`
+ * shape once and builds it per request from the (opaque, customer-typed)
+ * `Principal`. The type then flows through `defineAgent`, prepareStep, hooks,
+ * and tools.
+ *
+ * Tools receive the built context automatically: the runtime hands every tool
+ * `{ ...runtimeContext, principal, run, writer, runtime }` as its
+ * `options.context` (the runtime itself included, so a harness tool can
+ * schedule or spawn without a host-global), so a tool that needs a credential
+ * resolves it itself, scoped by the principal
+ * (e.g. `vault.resolver(ctx.principal, "crm_api_key")`) — the model never sees
+ * the value.
+ *
+ * Derive runtime context from DURABLE identity (look things up by ids on the
+ * principal), so a resumed run or a scheduled trigger — which has no request —
+ * rebuilds the same context.
+ */
+export function defineContext(def) {
+    return def;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAyBH,MAAM,UAAU,aAAa,CAC3B,GAAyC;IAEzC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/current-date.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The "what day is it" line appended to every agent's instructions.
+ *
+ * Day granularity ONLY — the string may change at most once per calendar day.
+ * Anthropic prompt caches live minutes, not days, so a day-stable line never
+ * invalidates a live cache; anything finer (clock time) would change the
+ * system prompt every turn and bust the cache each time. The weekday is
+ * spelled out because models are unreliable at deriving it from a date, and
+ * the timezone is stated so the model never guesses whose midnight applies.
+ */
+export declare function currentDateLine(now?: Date): string;
+//# sourceMappingURL=current-date.d.ts.map

package/dist/current-date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-date.d.ts","sourceRoot":"","sources":["../src/current-date.ts"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAI9D"}

package/dist/current-date.js

@@ -0,0 +1,25 @@
+const WEEKDAYS_UTC = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+];
+/**
+ * The "what day is it" line appended to every agent's instructions.
+ *
+ * Day granularity ONLY — the string may change at most once per calendar day.
+ * Anthropic prompt caches live minutes, not days, so a day-stable line never
+ * invalidates a live cache; anything finer (clock time) would change the
+ * system prompt every turn and bust the cache each time. The weekday is
+ * spelled out because models are unreliable at deriving it from a date, and
+ * the timezone is stated so the model never guesses whose midnight applies.
+ */
+export function currentDateLine(now = new Date()) {
+    const weekday = WEEKDAYS_UTC[now.getUTCDay()];
+    const iso = now.toISOString().slice(0, 10);
+    return `Today's date is ${weekday}, ${iso} (UTC).`;
+}
+//# sourceMappingURL=current-date.js.map

package/dist/current-date.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-date.js","sourceRoot":"","sources":["../src/current-date.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG;IACnB,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAY,IAAI,IAAI,EAAE;IACpD,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,mBAAmB,OAAO,KAAK,GAAG,SAAS,CAAC;AACrD,CAAC"}