@tangle-network/agent-app 0.1.0

package/dist/eval/index.d.ts

@@ -0,0 +1,50 @@
+import { CompletionRequirement, RuntimeEventLike } from '@tangle-network/agent-eval';
+export { CompletionRequirement, CompletionVerdict, CorrectnessChecker, ProducedState, RuntimeEventLike, SatisfiedBy, TaskGold, createLlmCorrectnessChecker, extractProducedState, verifyCompletion, weightedComposite } from '@tangle-network/agent-eval';
+import { e as AppToolProducedEvent } from '../types-CeWor4bQ.js';
+
+/**
+ * Eval — the app-shell BRIDGE to `@tangle-network/agent-eval`, not a reimpl.
+ *
+ * The completion/scoring ENGINE lives in agent-eval (a peer dependency):
+ * `verifyCompletion`, `extractProducedState`, `weightedComposite`,
+ * `createLlmCorrectnessChecker`, and the `CompletionRequirement` / `TaskGold` /
+ * `ProducedState` types — all re-exported here so a consumer has one import
+ * root. This module adds only what agent-eval doesn't have and what is
+ * app-shell-specific:
+ *
+ *   1. {@link producedFromToolEvents} — the bridge: turn the structured app-tool
+ *      side channel's `AppToolProducedEvent`s (from a tool runtime executor's
+ *      `onProduced`) into the `RuntimeEventLike`s agent-eval's
+ *      `extractProducedState` consumes. This is the one piece that knows about
+ *      the app-tool channel, so it belongs here, not in the engine.
+ *   2. {@link createTokenRecallChecker} — a deterministic, no-LLM
+ *      `CorrectnessChecker` (agent-eval ships only the LLM one). For apps/tests
+ *      that gate completion without a judge call.
+ *
+ * Full campaigns (persona simulation, traces, scorecards, held-out gates) are
+ * agent-eval's `runEvalCampaign` / `AgentDriver` / `BenchmarkRunner` — use them
+ * directly; this module composes with them.
+ */
+
+/**
+ * Bridge the app-tool side channel's produced events into the runtime-event
+ * shape agent-eval's `extractProducedState` reads. Pipe it:
+ *   `verifyCompletion(taskGold, extractProducedState(producedFromToolEvents(events)), checker)`
+ */
+declare function producedFromToolEvents(events: readonly AppToolProducedEvent[]): RuntimeEventLike[];
+/**
+ * A deterministic `CorrectnessChecker` (agent-eval exports only
+ * `createLlmCorrectnessChecker`). A produced item fulfils a requirement when
+ * its content is substantive and recalls ≥ `minRecall` of the requirement
+ * title's significant tokens. No network — the default gate for apps/tests
+ * without an LLM judge. Pass to `verifyCompletion` as the checker.
+ */
+declare function createTokenRecallChecker(opts?: {
+    minRecall?: number;
+    minContentLength?: number;
+}): (requirement: CompletionRequirement, content: string) => Promise<{
+    correct: boolean;
+    reason: string;
+}>;
+
+export { createTokenRecallChecker, producedFromToolEvents };

package/dist/eval/index.js

@@ -0,0 +1,17 @@
+import {
+  createLlmCorrectnessChecker,
+  createTokenRecallChecker,
+  extractProducedState,
+  producedFromToolEvents,
+  verifyCompletion,
+  weightedComposite
+} from "../chunk-4NXVI7PW.js";
+export {
+  createLlmCorrectnessChecker,
+  createTokenRecallChecker,
+  extractProducedState,
+  producedFromToolEvents,
+  verifyCompletion,
+  weightedComposite
+};
+//# sourceMappingURL=index.js.map

package/dist/eval/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { APP_TOOL_NAMES, AppToolMcpServer, AppToolName, AppToolRuntimeExecutor, AuthenticateOptions, BuildHttpMcpServerOptions, BuildMcpServerOptions, CapabilityTokenOptions, DEFAULT_APP_TOOL_PATHS, DEFAULT_HEADER_NAMES, DispatchOptions, HandleToolRequestOptions, OpenAIFunctionTool, RuntimeExecutorOptions, ToolAuthResult, ToolHeaderNames, ToolInputError, authenticateToolRequest, buildAppToolMcpServer, buildAppToolOpenAITools, buildHttpMcpServer, createAppToolRuntimeExecutor, createCapabilityToken, dispatchAppTool, handleAppToolRequest, isAppToolName, outcomeStatus, readToolArgs, verifyCapabilityToken } from './tools/index.js';
+export { A as AddCitationArgs, a as AddCitationResult, b as AppToolContext, c as AppToolHandlers, d as AppToolOutcome, e as AppToolProducedEvent, f as AppToolTaxonomy, R as RenderUiArgs, g as RenderUiResult, S as ScheduleFollowupArgs, h as ScheduleFollowupResult, i as SubmitProposalArgs, j as SubmitProposalResult } from './types-CeWor4bQ.js';
+export { BuildDelegationOptions, DELEGATION_MCP_SERVER_KEY, DELEGATION_TOOLS, DelegationMcpServer, buildDelegationMcpServer } from './delegation/index.js';
+export { BrokerToken, BrokerTokenMinter, BrokerTokenProvider, BrokerTokenProviderOptions, ConsentUrlInput, buildConsentUrl, createBrokerTokenProvider } from './tangle/index.js';
+export { AppToolLoopOptions, DEFAULT_TANGLE_ROUTER_BASE_URL, LoopEvent, LoopToolCall, OpenAICompatStreamTurnOptions, OpenAIStreamChunk, ResolveModelOptions, StreamAppToolLoopOptions, StreamLoopYield, TangleModelConfig, ToolLoopResult, createOpenAICompatStreamTurn, resolveTangleModelConfig, runAppToolLoop, streamAppToolLoop, toLoopEvents } from './runtime/index.js';
+export { createTokenRecallChecker, producedFromToolEvents } from './eval/index.js';
+export { KeyCrypto, KeyProvisioner, WorkspaceKeyManager, WorkspaceKeyManagerOptions, WorkspaceKeyRecord, WorkspaceKeyStore, WorkspaceModelKeyUsage, createWorkspaceKeyManager } from './billing/index.js';
+export { createFieldCrypto, decodeHexKey, decryptAesGcm, encryptAesGcm } from './crypto/index.js';
+export { JsonRecord, PersistedChatMessageForTurn, ResolvedChatTurn, StreamEvent, asRecord, asString, buildUserTextParts, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName } from './stream/index.js';
+export { HubExecClient, HubExecClientOptions, HubExecErrorCode, HubExecResult, HubInvokeDeps, HubInvokeInput, HubInvokeOutcome, ParsedIntegrationAction, invokeIntegrationHub, resolveIntegrationAction } from './integrations/index.js';
+export { JsonObject, KvLike, RateLimitResult, RequestContext, SecurityHeaderOptions, addSecurityHeaders, checkRateLimit, extractRequestContext, parseJsonObjectBody, requireString } from './web/index.js';
+export { redactForIngestion } from './redact/index.js';
+export { CompletionRequirement, CompletionVerdict, CorrectnessChecker, ProducedState, RuntimeEventLike, SatisfiedBy, TaskGold, createLlmCorrectnessChecker, extractProducedState, verifyCompletion, weightedComposite } from '@tangle-network/agent-eval';

package/dist/index.js

@@ -0,0 +1,149 @@
+import {
+  asRecord,
+  asString,
+  buildUserTextParts,
+  encodeEvent,
+  finalizeAssistantParts,
+  getPartKey,
+  mergePersistedPart,
+  messageHasTurnId,
+  normalizeClientTurnId,
+  normalizePersistedPart,
+  normalizeTime,
+  normalizeToolEvent,
+  resolveChatTurn,
+  resolveToolId,
+  resolveToolName
+} from "./chunk-GMFPCCQZ.js";
+import {
+  HubExecClient,
+  invokeIntegrationHub,
+  resolveIntegrationAction
+} from "./chunk-L2TG5DBW.js";
+import {
+  addSecurityHeaders,
+  checkRateLimit,
+  extractRequestContext,
+  parseJsonObjectBody,
+  requireString
+} from "./chunk-CN75FIPT.js";
+import {
+  redactForIngestion
+} from "./chunk-C5CREGT2.js";
+import {
+  APP_TOOL_NAMES,
+  DEFAULT_APP_TOOL_PATHS,
+  DEFAULT_HEADER_NAMES,
+  ToolInputError,
+  authenticateToolRequest,
+  buildAppToolMcpServer,
+  buildAppToolOpenAITools,
+  buildHttpMcpServer,
+  createAppToolRuntimeExecutor,
+  createCapabilityToken,
+  dispatchAppTool,
+  handleAppToolRequest,
+  isAppToolName,
+  outcomeStatus,
+  readToolArgs,
+  verifyCapabilityToken
+} from "./chunk-EDIQ6F55.js";
+import {
+  DELEGATION_MCP_SERVER_KEY,
+  DELEGATION_TOOLS,
+  buildDelegationMcpServer
+} from "./chunk-7P6VIHI4.js";
+import {
+  buildConsentUrl,
+  createBrokerTokenProvider
+} from "./chunk-YGUNTIT5.js";
+import {
+  DEFAULT_TANGLE_ROUTER_BASE_URL,
+  createOpenAICompatStreamTurn,
+  resolveTangleModelConfig,
+  runAppToolLoop,
+  streamAppToolLoop,
+  toLoopEvents
+} from "./chunk-FS5OUVRB.js";
+import {
+  createLlmCorrectnessChecker,
+  createTokenRecallChecker,
+  extractProducedState,
+  producedFromToolEvents,
+  verifyCompletion,
+  weightedComposite
+} from "./chunk-4NXVI7PW.js";
+import {
+  createWorkspaceKeyManager
+} from "./chunk-45MYQ3GD.js";
+import {
+  createFieldCrypto,
+  decodeHexKey,
+  decryptAesGcm,
+  encryptAesGcm
+} from "./chunk-SIDR6BH3.js";
+export {
+  APP_TOOL_NAMES,
+  DEFAULT_APP_TOOL_PATHS,
+  DEFAULT_HEADER_NAMES,
+  DEFAULT_TANGLE_ROUTER_BASE_URL,
+  DELEGATION_MCP_SERVER_KEY,
+  DELEGATION_TOOLS,
+  HubExecClient,
+  ToolInputError,
+  addSecurityHeaders,
+  asRecord,
+  asString,
+  authenticateToolRequest,
+  buildAppToolMcpServer,
+  buildAppToolOpenAITools,
+  buildConsentUrl,
+  buildDelegationMcpServer,
+  buildHttpMcpServer,
+  buildUserTextParts,
+  checkRateLimit,
+  createAppToolRuntimeExecutor,
+  createBrokerTokenProvider,
+  createCapabilityToken,
+  createFieldCrypto,
+  createLlmCorrectnessChecker,
+  createOpenAICompatStreamTurn,
+  createTokenRecallChecker,
+  createWorkspaceKeyManager,
+  decodeHexKey,
+  decryptAesGcm,
+  dispatchAppTool,
+  encodeEvent,
+  encryptAesGcm,
+  extractProducedState,
+  extractRequestContext,
+  finalizeAssistantParts,
+  getPartKey,
+  handleAppToolRequest,
+  invokeIntegrationHub,
+  isAppToolName,
+  mergePersistedPart,
+  messageHasTurnId,
+  normalizeClientTurnId,
+  normalizePersistedPart,
+  normalizeTime,
+  normalizeToolEvent,
+  outcomeStatus,
+  parseJsonObjectBody,
+  producedFromToolEvents,
+  readToolArgs,
+  redactForIngestion,
+  requireString,
+  resolveChatTurn,
+  resolveIntegrationAction,
+  resolveTangleModelConfig,
+  resolveToolId,
+  resolveToolName,
+  runAppToolLoop,
+  streamAppToolLoop,
+  toLoopEvents,
+  verifyCapabilityToken,
+  verifyCompletion,
+  weightedComposite
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/integrations/index.d.ts

@@ -0,0 +1,84 @@
+/** `{ success: false }` codes the hub returns on `/exec`. */
+type HubExecErrorCode = 'HUB_APPROVAL_REQUIRED' | 'HUB_POLICY_DENIED' | 'HUB_CONNECTION_MISSING' | 'HUB_CONNECTION_REVOKED' | 'HUB_CONFIG_MISSING' | 'HUB_NOT_FOUND' | string;
+/** Outcome of a hub `/exec` call. Callers MUST inspect `succeeded` before
+ *  reading `result` — a denied or approval-gated write resolves with
+ *  `succeeded: false` and a populated `code`, never a thrown silent failure. */
+type HubExecResult = {
+    succeeded: true;
+    result: unknown;
+} | {
+    succeeded: false;
+    code: HubExecErrorCode;
+    message: string;
+    approval?: unknown;
+};
+interface HubExecClientOptions {
+    /** Platform base URL (e.g. `TANGLE_PLATFORM_URL`). */
+    baseUrl: string;
+    /** Calling user's Tangle API key — the hub principal bearer. */
+    bearer: string;
+    /** Test seam. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** The provider/connector/action a hub action path addresses, plus the dotted
+ *  `path` the hub `/exec` endpoint expects. */
+interface ParsedIntegrationAction {
+    providerId: string;
+    connectorId: string;
+    actionId: string;
+    /** `provider.connector.action`. */
+    path: string;
+}
+/**
+ * Resolve an MCP tool name (the opaque `int_…` catalog name the agent calls)
+ * into the dotted hub action path. Returns `undefined` when the name is not a
+ * catalog integration tool, so the chat loop routes non-integration calls
+ * elsewhere instead of misrouting them to the hub.
+ */
+declare function resolveIntegrationAction(toolName: string): ParsedIntegrationAction | undefined;
+/** Typed client over the platform hub `/v1/hub/exec`. The hub holds the user's
+ *  credentials, resolves the connection from the bearer principal, evaluates
+ *  per-action policy (read → allow, write/destructive → approval), and runs the
+ *  action server-side. Never throws on a policy block — a gated write is a
+ *  normal `succeeded: false` outcome. */
+declare class HubExecClient {
+    private readonly baseUrl;
+    private readonly bearer;
+    private readonly fetchImpl;
+    constructor(options: HubExecClientOptions);
+    exec(input: {
+        path: string;
+        actionInput?: unknown;
+        connectionId?: string;
+    }): Promise<HubExecResult>;
+    private readEnvelope;
+}
+interface HubInvokeInput {
+    userId: string;
+    /** The MCP tool name the agent called (`int_<provider>_<connector>_<action>`). */
+    toolName: string;
+    args?: Record<string, unknown>;
+}
+interface HubInvokeOutcome {
+    status: number;
+    body: Record<string, unknown>;
+}
+interface HubInvokeDeps {
+    /** Resolve the user's Tangle API key (the hub principal bearer). Required —
+     *  the product binds its own session-key resolver. Null → user not linked. */
+    apiKeyResolver: (userId: string) => Promise<string | null>;
+    /** Platform base URL. Defaults to `env.TANGLE_PLATFORM_URL`. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Resolve + execute one integration tool call through the hub: resolve the
+ * per-user bearer, map the MCP tool name to the hub action path, forward to
+ * `/v1/hub/exec`, and shape the route response (200 ok / 401 not-linked /
+ * 400 unknown-tool / 409 approval-required / 502 hub-error). A write that's
+ * approval-gated surfaces verbatim as 409, never silently executed.
+ */
+declare function invokeIntegrationHub(input: HubInvokeInput, deps: HubInvokeDeps): Promise<HubInvokeOutcome>;
+
+export { HubExecClient, type HubExecClientOptions, type HubExecErrorCode, type HubExecResult, type HubInvokeDeps, type HubInvokeInput, type HubInvokeOutcome, type ParsedIntegrationAction, invokeIntegrationHub, resolveIntegrationAction };

package/dist/integrations/index.js

@@ -0,0 +1,11 @@
+import {
+  HubExecClient,
+  invokeIntegrationHub,
+  resolveIntegrationAction
+} from "../chunk-L2TG5DBW.js";
+export {
+  HubExecClient,
+  invokeIntegrationHub,
+  resolveIntegrationAction
+};
+//# sourceMappingURL=index.js.map

package/dist/integrations/index.js.map

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

package/dist/redact/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PII redaction for production trace payloads.
+ *
+ * The chat-trace emission sites pass tool args + results — and at one
+ * point the LLM span carried the system prompt + user message verbatim
+ * — through the wire. Anything that lands in the ingestion store is
+ * also fair game for the analyst-loop's LLM prompts, so personal
+ * identifiers MUST be stripped before they leave the request path.
+ *
+ * Discipline:
+ *   - Match cheap, deterministic patterns at the string level (SSN, EIN).
+ *   - Match well-known sensitive object keys (case-insensitive) and
+ *     replace the value, never the key, so the shape of the object
+ *     remains debuggable.
+ *   - Recurse arrays + plain objects only; pass through everything else
+ *     unchanged (numbers, booleans, null, undefined, functions, etc).
+ *   - NEVER throw — a redaction failure must not crash the chat handler.
+ *     Unrecognized inputs round-trip as-is.
+ */
+declare function redactForIngestion(value: unknown): unknown;
+
+export { redactForIngestion };

package/dist/redact/index.js

@@ -0,0 +1,7 @@
+import {
+  redactForIngestion
+} from "../chunk-C5CREGT2.js";
+export {
+  redactForIngestion
+};
+//# sourceMappingURL=index.js.map

package/dist/redact/index.js.map

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

package/dist/runtime/index.d.ts

@@ -0,0 +1,219 @@
+import { d as AppToolOutcome } from '../types-CeWor4bQ.js';
+
+/**
+ * Resolve the model config a Tangle agent's sandbox/runtime runs on.
+ *
+ * Every Tangle agent product resolves the SAME thing from env: the Tangle Router
+ * (OpenAI-compatible, metered at the platform markup against a single
+ * `TANGLE_API_KEY`) by default, with a direct-Anthropic BYOK escape hatch. The
+ * shape feeds the sandbox SDK's `backend.model`. Lifted here so no product
+ * hand-rolls the env parsing + the router default.
+ */
+interface TangleModelConfig {
+    /** The Tangle Router is OpenAI-compatible → driven via `openai-compat`.
+     *  `anthropic` is the BYOK escape hatch. */
+    provider: 'openai-compat' | 'anthropic';
+    model: string;
+    apiKey: string;
+    baseUrl: string;
+}
+interface ResolveModelOptions {
+    /** Env to read (defaults to process.env). */
+    env?: Record<string, string | undefined>;
+    /** Router base URL default when `TANGLE_ROUTER_BASE_URL` is unset. */
+    defaultRouterBaseUrl?: string;
+}
+declare const DEFAULT_TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
+/**
+ * Resolve the model config from env. DEFAULT path (`MODEL_PROVIDER` unset or
+ * `openai-compat`/`tangle-router`/`tcloud`): the Tangle Router, authenticated
+ * with `TANGLE_API_KEY`, model from `MODEL_NAME`. BYOK path
+ * (`MODEL_PROVIDER=anthropic`): direct Anthropic with `ANTHROPIC_API_KEY` +
+ * `ANTHROPIC_BASE_URL`. Throws (fail-loud) on a missing required var so a
+ * misconfigured deploy fails at boot, not mid-turn.
+ */
+declare function resolveTangleModelConfig(opts?: ResolveModelOptions): TangleModelConfig;
+
+/**
+ * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.
+ *
+ * `streamAppToolLoop` takes a `streamTurn` seam that yields `LoopEvent`s. A
+ * sandboxed agent produces those from its container; a browser/edge copilot
+ * instead calls a model directly. The Tangle Router, the tcloud SDK, and most
+ * providers all speak the OpenAI Chat Completions streaming shape — so the ONE
+ * reusable piece is assembling that stream (content deltas + FRAGMENTED
+ * tool-call deltas) into `LoopEvent`s. That assembly is the boilerplate every
+ * copilot would re-write (and get wrong — OpenAI streams tool-call arguments in
+ * pieces across chunks).
+ *
+ * This does NOT implement an HTTP client beyond a minimal `fetch` + SSE reader
+ * (browser/edge/Node-safe, zero deps). For richer transport use the tcloud SDK
+ * or the Vercel AI SDK and pipe their stream through {@link toLoopEvents}.
+ */
+
+/** Minimal OpenAI Chat Completions streaming chunk (structural — no `openai` dep). */
+interface OpenAIStreamChunk {
+    choices?: Array<{
+        delta?: {
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason?: string | null;
+    }>;
+}
+/**
+ * Map an OpenAI-compat streaming chunk iterator to `LoopEvent`s: each content
+ * delta → a `text` event; tool-call deltas are accumulated by index across
+ * chunks and emitted as one complete `tool_call` event when the stream finishes
+ * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than
+ * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.
+ */
+declare function toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent>;
+interface OpenAICompatStreamTurnOptions {
+    /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** OpenAI tool definitions — pass `buildAppToolOpenAITools(taxonomy)` so the
+     *  model can call the app tools. Omit for a tool-free copilot. */
+    tools?: unknown[];
+    temperature?: number;
+    fetchImpl?: typeof fetch;
+    /** Extra body fields (e.g. `max_tokens`). */
+    extraBody?: Record<string, unknown>;
+}
+/**
+ * Build a `streamTurn` that calls an OpenAI-compatible `/chat/completions`
+ * endpoint (Tangle Router / tcloud / any compat provider) with `stream: true`
+ * and yields `LoopEvent`s via {@link toLoopEvents}. Browser/edge/Node-safe —
+ * just `fetch` + an SSE reader. Drop straight into `streamAppToolLoop`:
+ *
+ *   const cfg = resolveTangleModelConfig()                 // or { baseUrl, apiKey, model }
+ *   streamAppToolLoop({ streamTurn: createOpenAICompatStreamTurn({ ...cfg, tools }), executeToolCall, ... })
+ */
+declare function createOpenAICompatStreamTurn(opts: OpenAICompatStreamTurnOptions): (messages: Array<{
+    role: string;
+    content: string;
+}>) => AsyncIterable<LoopEvent>;
+
+interface LoopToolCall {
+    toolCallId?: string;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+/** Events a turn stream yields. `text` accumulates into the final answer;
+ *  `tool_call` is collected for dispatch. Extra event types pass through
+ *  untouched (the caller re-emits them to its own UI stream). */
+type LoopEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_call';
+    call: LoopToolCall;
+} | {
+    type: 'other';
+    event: unknown;
+};
+interface ToolLoopResult {
+    /** The model's final text across the loop. */
+    finalText: string;
+    /** Every tool call executed, with its outcome, in order. */
+    toolResults: Array<{
+        call: LoopToolCall;
+        label: string;
+        outcome: AppToolOutcome;
+    }>;
+    /** Number of model turns run (1 + tool-driven re-runs). */
+    turns: number;
+    /** True when the loop stopped because it hit `maxToolTurns` with calls still pending. */
+    cappedOut: boolean;
+}
+interface AppToolLoopOptions {
+    systemPrompt: string;
+    userMessage: string;
+    priorMessages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Stream one model turn over the running message list. The app wraps its
+     *  backend here. */
+    streamTurn: (messages: Array<{
+        role: string;
+        content: string;
+    }>) => AsyncIterable<LoopEvent>;
+    /** Execute one tool call. The app routes to its integration executor / app-tool
+     *  executor and returns the outcome. */
+    executeToolCall: (call: LoopToolCall) => Promise<AppToolOutcome>;
+    /** Which emitted tool names are executable (others are ignored — e.g. a UI-only
+     *  tool the app renders but doesn't run here). */
+    isExecutableTool: (toolName: string) => boolean;
+    /** Max tool-driven re-runs. Default 8. */
+    maxToolTurns?: number;
+    /** Render one tool outcome as a line the next turn's message carries. Default
+     *  is a compact `- <label> → ok/failed: …`. */
+    renderResult?: (label: string, outcome: AppToolOutcome) => string;
+    /** Map a tool call to the label its result is keyed under (default: toolName). */
+    labelFor?: (call: LoopToolCall) => string;
+}
+/**
+ * Run the bounded tool loop and return the final text + every executed tool
+ * outcome. Yields nothing — it's an awaitable driver; callers that need to
+ * re-emit events to a UI stream should do so inside `streamTurn`. (A streaming
+ * variant can wrap this later; keeping the core awaitable makes it trivially
+ * testable.)
+ */
+declare function runAppToolLoop(opts: AppToolLoopOptions): Promise<ToolLoopResult>;
+type StreamLoopYield<Raw> = {
+    kind: 'event';
+    event: Raw;
+} | {
+    kind: 'tool_result';
+    toolName: string;
+    toolCallId?: string;
+    label: string;
+    outcome: AppToolOutcome;
+} | {
+    kind: 'capped';
+    pending: number;
+};
+interface StreamAppToolLoopOptions<Raw> {
+    systemPrompt: string;
+    userMessage: string;
+    priorMessages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Stream one model turn (the app wraps its backend / runAgentTaskStream). */
+    streamTurn: (messages: Array<{
+        role: string;
+        content: string;
+    }>) => AsyncIterable<Raw>;
+    /** Text contribution of a raw event, '' if none — used to record the
+     *  assistant's turn so the next turn has its context. */
+    extractText: (event: Raw) => string;
+    /** The tool call a raw event represents, or null. */
+    extractToolCall: (event: Raw) => LoopToolCall | null;
+    /** Which tool names are executable here (others pass through, unexecuted). */
+    isExecutableTool: (toolName: string) => boolean;
+    /** Execute one call — the app routes to its integration / app-tool executor. */
+    executeToolCall: (call: LoopToolCall) => Promise<AppToolOutcome>;
+    maxToolTurns?: number;
+    renderResult?: (label: string, outcome: AppToolOutcome) => string;
+    labelFor?: (call: LoopToolCall) => string;
+}
+/**
+ * The streaming bounded tool loop. Yields `event` for each raw turn event and
+ * `tool_result` for each executed tool; emits a single `capped` when it stops at
+ * the turn limit with calls still pending. The app drives telemetry + UI
+ * emission off the yielded items.
+ */
+declare function streamAppToolLoop<Raw>(opts: StreamAppToolLoopOptions<Raw>): AsyncGenerator<StreamLoopYield<Raw>, void, unknown>;
+
+export { type AppToolLoopOptions, DEFAULT_TANGLE_ROUTER_BASE_URL, type LoopEvent, type LoopToolCall, type OpenAICompatStreamTurnOptions, type OpenAIStreamChunk, type ResolveModelOptions, type StreamAppToolLoopOptions, type StreamLoopYield, type TangleModelConfig, type ToolLoopResult, createOpenAICompatStreamTurn, resolveTangleModelConfig, runAppToolLoop, streamAppToolLoop, toLoopEvents };

package/dist/runtime/index.js

@@ -0,0 +1,17 @@
+import {
+  DEFAULT_TANGLE_ROUTER_BASE_URL,
+  createOpenAICompatStreamTurn,
+  resolveTangleModelConfig,
+  runAppToolLoop,
+  streamAppToolLoop,
+  toLoopEvents
+} from "../chunk-FS5OUVRB.js";
+export {
+  DEFAULT_TANGLE_ROUTER_BASE_URL,
+  createOpenAICompatStreamTurn,
+  resolveTangleModelConfig,
+  runAppToolLoop,
+  streamAppToolLoop,
+  toLoopEvents
+};
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

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

package/dist/stream/index.d.ts

@@ -0,0 +1,39 @@
+type JsonRecord = Record<string, unknown>;
+interface StreamEvent {
+    type: string;
+    data?: JsonRecord;
+}
+declare function asRecord(value: unknown): JsonRecord | undefined;
+declare function asString(value: unknown): string | undefined;
+declare function resolveToolId(part: JsonRecord): string;
+declare function resolveToolName(part: JsonRecord): string;
+declare function normalizeTime(value: unknown): JsonRecord | undefined;
+declare function normalizeToolEvent(event: StreamEvent): StreamEvent;
+declare function normalizePersistedPart(rawPart: JsonRecord): JsonRecord | null;
+declare function getPartKey(part: JsonRecord): string;
+declare function mergePersistedPart(existing: JsonRecord | undefined, incoming: JsonRecord, delta?: string): JsonRecord;
+declare function finalizeAssistantParts(partOrder: string[], partMap: Map<string, JsonRecord>, finalText: string): JsonRecord[];
+declare function encodeEvent(encoder: TextEncoder, event: StreamEvent): Uint8Array;
+
+interface PersistedChatMessageForTurn {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    parts: Array<Record<string, unknown>> | null;
+}
+interface ResolvedChatTurn {
+    turnIndex: number;
+    shouldInsertUserMessage: boolean;
+    priorMessages: PersistedChatMessageForTurn[];
+    userParts: JsonRecord[];
+}
+declare function normalizeClientTurnId(value: unknown): string | undefined;
+declare function buildUserTextParts(text: string, turnId: string | undefined): JsonRecord[];
+declare function messageHasTurnId(message: PersistedChatMessageForTurn, turnId: string): boolean;
+declare function resolveChatTurn(input: {
+    existingMessages: PersistedChatMessageForTurn[];
+    userContent: string;
+    turnId?: string;
+}): ResolvedChatTurn;
+
+export { type JsonRecord, type PersistedChatMessageForTurn, type ResolvedChatTurn, type StreamEvent, asRecord, asString, buildUserTextParts, encodeEvent, finalizeAssistantParts, getPartKey, mergePersistedPart, messageHasTurnId, normalizeClientTurnId, normalizePersistedPart, normalizeTime, normalizeToolEvent, resolveChatTurn, resolveToolId, resolveToolName };