@tangle-network/agent-app 0.43.53 → 0.43.55

package/README.md

@@ -8,6 +8,8 @@ The application-shell layer for building agent products on the Tangle stack.
 
 The substrate packages — `@tangle-network/agent-runtime`, `agent-eval`, `agent-integrations`, `tcloud`, `sandbox` — are the **engine**. This package is the **shell**: the chat tool-loop, the structured agent→app side channel, the integration-hub client, per-workspace billing, field crypto, and the web boundary utilities that every agent app otherwise rewrites by hand. You supply your domain through typed seams; the package supplies the mechanism and imports none of your code.
 
+**Who it's for:** engineers building an agent product on the Tangle sandbox — a chat app, a copilot, an autonomous worker — who want the shell (chat routes, streaming, durability, approvals, billing, the tool side channel) as composable pieces instead of a per-app rewrite. It is **not** an agent framework or a model SDK: the reasoning lives in the sandbox agent; agent-app is everything around it — the turn plumbing, durability, and money.
+
 ## Highlights
 
 - **Structured tool side channel** — `submit_proposal` (approval-gated), `schedule_followup`, `render_ui`, `add_citation`, exposed as validated tool calls over three surfaces (HTTP route, per-turn MCP server, agent-runtime executor). No fenced-text parsing.
@@ -109,43 +111,47 @@ One rule decides where anything lives:
 
 Everything here is reached through a typed seam — `AppToolHandlers`, `AppToolTaxonomy`, `streamTurn`, `executeToolCall`, `verifyToken`, `KeyProvisioner` / `WorkspaceKeyStore` / `KeyCrypto`. The package never imports product code and never hard-codes a domain value (a proposal type, a premium, a disclaimer); each is a parameter. New capability arrives as a new subpath, never a breaking change to an existing one.
 
+## Choosing a path
+
+Three decisions cover most of the surface.
+
+**1. How does the turn run?** Pick the transport by who's watching, not by feature.
+
+| Your turn | Use | Why |
+|---|---|---|
+| **Interactive** — a user is watching a chat or copilot | `streamPrompt` held open for the turn; the sandbox gateway lets the browser attach directly | Worker lifetime ≈ turn length; a dropped tab replays the buffered tail on reconnect. |
+| **Autonomous** — a mission step, queue job, cron, or inbound email, with nobody watching | `dispatchPrompt({ detach: true })` + poll from a durable driver. `runDetachedTurn` (`/chat-routes`) bridges that detached run into the live buffer, so a browser opening the session mid-run still tails it token-by-token | No consumer exists and Workers die in minutes; the platform runs the turn server-side and a crash re-dispatch is a lookup, not a second run. |
+| **Eval / CI** — a long-lived harness process | `runAppToolLoop` / `streamPrompt` in-process | The process outlives the run; durability adds nothing — a failed run is re-run, not resumed. |
+
+**2. Assembled or à la carte?** `createChatTurnRoutes` (`/chat-routes`) wires the whole server chat turn — auth, store, streaming, replay, uploads, interactions — over typed seams. Reach for the individual modules (`/stream`, `/chat-store`, `/interactions`) only to compose something the assembled route doesn't cover.
+
+**3. Sandbox or sandbox-free?** The tools, billing, eval, and loop all work without a container: `createOpenAICompatStreamTurn` maps any OpenAI-compatible endpoint into the loop for a browser or edge copilot. Reach for `/sandbox` only when the turn needs a real container — bash, files, sub-agents, MCP.
+
 ## Modules
 
-Each is an independent entry point — import only what you use.
-
-| Subpath | What it gives you |
-|---|---|
-| [`/tools`](src/tools) | The structured agent→app side channel: `buildAppToolOpenAITools`, `createAppToolRuntimeExecutor`, `handleAppToolRequest` (HTTP), `buildAppToolMcpServer` / `buildHttpMcpServer` (MCP), `createCapabilityToken` + `authenticateToolRequest` (capability auth), `ToolInputError`. |
-| [`/runtime`](src/runtime) | `runAppToolLoop` / `streamAppToolLoop` (bounded tool loop), `resolveTangleModelConfig` (Tangle Router / Anthropic BYOK), and `toLoopEvents` / `createOpenAICompatStreamTurn` (OpenAI-compat stream → loop events, with fragmented tool-call args reassembled). |
-| [`/integrations`](src/integrations) | Integration-hub client: `HubExecClient`, `resolveIntegrationAction`, `invokeIntegrationHub`. Composes `@tangle-network/agent-integrations`. |
-| [`/eval`](src/eval) | `producedFromToolEvents` (bridge tool events into the eval verifier) and `createTokenRecallChecker` (deterministic content check). Re-exports `@tangle-network/agent-eval`'s `verifyCompletion`, `extractProducedState`, `weightedComposite`, `createLlmCorrectnessChecker`. |
-| [`/tangle`](src/tangle) | App-registration consent URL (`buildConsentUrl`) and a cached, auto-refreshing broker-token provider (`createBrokerTokenProvider`). Structural over the tcloud client. |
-| [`/billing`](src/billing) | `createWorkspaceKeyManager` — mint / rotate / roll over / report usage on per-workspace, budget-capped model keys. Seams for provisioner, store, and crypto. |
-| [`/crypto`](src/crypto) | AES-GCM field encryption: `encryptAesGcm`, `decryptAesGcm`, `createFieldCrypto`. Key supplied by the caller. |
-| [`/missions`](src/missions) | Durable multi-step mission orchestration over a `MissionStorePort` seam: guarded status/step machine, idempotent plan engine with budget/approval gates, `:::mission` parser, the client-safe live-event reducer, and the canonical `StepAgentActivity` per-step delegated-run lane. |
-| [`/trace`](src/trace) | Flow observability: `buildFlowTrace` + ASCII `renderWaterfall`/`renderHistogram`; the mission trace bridge (`createMissionTraceContext`, `childSpanContext`, `traceEnv`) whose ids/env a delegated run inherits; and delegation→FlowSpan converters (`delegationActivityToFlowSpans`, `loopTraceEventsToFlowSpans`, `composeMissionFlowTrace`). |
-| [`/web-react`](src/web-react) | Router-safe React chat components: `ChatComposer`, `ModelPicker`, `EffortPicker`, `ChatMessages`, `RunDrillIn`, plus observability surfaces — `MissionActivityLane`, `AgentActivityPanel`, `FlowWaterfall`. This path must not import sandbox-only UI. |
-| [`/composer`](src/composer) | Sandbox-first `AgentComposer` and profile/model/sandbox-runner controls re-exported from `@tangle-network/sandbox-ui/chat`. Use when the chat owns a sandbox profile or needs the full sandbox composer. |
-| `/web-react/terminal` | Sandbox terminal React components, including `WorkspaceTerminalPanel`. Import this explicit path only for container/terminal views. |
-| [`/web`](src/web) | Request-boundary utilities: `parseJsonObjectBody`, `requireString`, `extractRequestContext`, `checkRateLimit`, `addSecurityHeaders`. |
-| [`/stream`](src/stream) | SSE normalization and turn identity: `normalizeToolEvent`, `resolveChatTurn`, `encodeEvent`, message-part merging. |
-| [`/redact`](src/redact) | `redactForIngestion` — PII redaction before content leaves the boundary. |
-
-**The chat vertical** — the assembled server chat stack. Wire it with [`examples/chat-app.md`](./examples/chat-app.md).
-
-| Subpath | What it gives you |
-|---|---|
-| [`/chat-routes`](src/chat-routes) | `createChatTurnRoutes` — the assembled turn vertical: NDJSON `turn` + buffered `replay` + `running` reconnect-discovery + composed `interactions` answer endpoints, over `authorize` / `produce` / `store` seams. Plus `createSandboxChatProducer`, `createUploadRoute`, `createSandboxFileIndexRoute`, `withDurableChatProjection`, and the import-free `./wire` contract (`chatTurnRequestInit`, `ChatTurnRequestPayload`). Composes agent-runtime's `handleChatTurn`; subpath-only (not re-exported from the root). |
-| [`/chat-store`](src/chat-store) | `createChatTables` + `createChatStore` — drizzle thread/message persistence behind the `ChatStore` port, and the canonical `ChatMessagePart` parts vocabulary (`toChatMessageParts`, part guards). The drizzle store/schema is subpath-only. |
-| [`/interactions`](src/interactions) | Human-in-the-loop ask channel: `createInteractionAnswerRoute` (list/answer endpoint factory — validation, 410 mapping, duplicate-answer safety), the server sidecar client, and the shared `ChatInteraction` wire/persisted-part contract + codecs. Composes `@tangle-network/agent-interface` types. |
-| [`/durable-chat`](src/durable-chat) | Durable plan/question workflow around the authoritative channels: `createDurablePlanRoutes`, `createDurableChatScope`, `createDurableChatEventProjection`, `createDurableInteractionRoutePersistence`, the `DurablePlanStore` port, and `InMemoryDurableChatStateStore` (tests/demos only — production supplies the store). |
-| [`/plans`](src/plans) | Browser-safe durable-plan chat projection: `parsePlanSubmittedEvent`, `planToPersistedPart` / `persistedPartToPlan`, `canTransitionPlanStatus`, and the `ChatPlan` union. Byte-matches the SDK's `SandboxSession.plan()`. |
-| [`/object-store`](src/object-store) | Content-addressed durable attachment store: the `ObjectStore` port + `createR2ObjectStore`, `signObjectUrl` / `verifyObjectUrl`, `createProxiedArtifactRoute`, `objectKey`. |
-| [`/app-auth`](src/app-auth) | `createAppAuth` — better-auth config factory + request guards (`requireApiUser`) over the standard users/sessions/accounts/verifications tables; composes `/platform`'s SSO cookie minter. Optional `better-auth` peer; subpath-only. |
-| [`/sandbox`](src/sandbox) | Workspace sandbox provisioning + turn streaming: `ensureWorkspaceSandbox` / `peekWorkspaceSandbox`, `streamSandboxPrompt` / `runSandboxPrompt`, `createWorkspaceSandboxManager`, and terminal / runtime-proxy handlers. Peer `@tangle-network/sandbox`; subpath-only. |
-| [`/platform`](src/platform) | Tangle platform glue: cross-site SSO (`createTangleSsoHandlers`), request guards (`createAuthGuard`, `guardResolution`), the hub proxy, and seat billing. |
-
-The root entry (`@tangle-network/agent-app`) re-exports every module, but importing the subpath keeps your bundle to what you use.
+Each subpath is an independent entry point — import only what you use; the root re-exports everything, but a subpath import keeps your bundle to what you touch.
+
+The **complete, always-current reference** — every published subpath, its exported symbols, and its internal dependencies — is generated into **[`docs/CODEMAP.md`](./docs/CODEMAP.md)** and kept honest by a CI check (regenerate with `pnpm docs:gen`). Start with the core entry points:
+
+**Run a turn**
+- [`/tools`](src/tools) — the structured agent→app side channel (proposals, follow-ups, citations, UI) as validated tool calls, over HTTP / MCP / runtime-executor surfaces.
+- [`/runtime`](src/runtime) — the bounded tool loop; the same loop drives a sandbox agent, a Worker, or an in-browser copilot behind one `streamTurn` seam.
+
+**The server chat vertical** ([`examples/chat-app.md`](./examples/chat-app.md))
+- [`/chat-routes`](src/chat-routes) — `createChatTurnRoutes`: auth → store → streaming turn with buffered replay → uploads → sidecar question answering, assembled. Plus `runDetachedTurn` for autonomous turns a browser can still watch live.
+- [`/chat-store`](src/chat-store) · [`/interactions`](src/interactions) · [`/durable-chat`](src/durable-chat) · [`/plans`](src/plans) — persistence, human-in-the-loop asks, and the durable plan/question workflow around them.
+
+**On the sandbox**
+- [`/sandbox`](src/sandbox) — workspace provisioning + turn streaming.
+- [`/missions`](src/missions) — durable multi-step orchestration: sequencing, budgets, approval gates, schedules.
+
+**React surfaces**
+- [`/web-react`](src/web-react) — router-safe chat + observability components (never imports sandbox-only UI); [`/composer`](src/composer) when the chat owns a full sandbox profile.
+
+**Utilities (zero-dependency)**
+- [`/web`](src/web) · [`/stream`](src/stream) · [`/crypto`](src/crypto) · [`/redact`](src/redact) — request boundary, SSE normalization, field crypto, PII redaction.
+
+See **[`docs/CODEMAP.md`](./docs/CODEMAP.md)** for the rest — `/billing`, `/tangle`, `/object-store`, `/trace`, `/theme`, `/eval`, `/app-auth`, `/platform`, and more.
 
 ### Missions: id shape and product columns
 

package/dist/assistant/index.d.ts

@@ -4,13 +4,13 @@ import { ToolDetailRenderers, ChatUiMessage } from '../web-react/index.js';
 import '../contract-KfqJh_au.js';
 import '@tangle-network/agent-interface';
 import '../plans/index.js';
-import '../parts-IB-Kbb7z.js';
+import '../parts-1sRYSPjF.js';
 import '../agent-activity-C8ZG0F0M.js';
 import '../flow-types-Cb_AblZs.js';
 import '../sandbox-terminal-BIIC__CP.js';
 import '../catalog/index.js';
 import '../harness/index.js';
-import '../attachment-validation-DX2KIzMC.js';
+import '../attachment-validation-D0csjCvz.js';
 import '../stream-normalizer-DWvtmY6F.js';
 
 /**

package/dist/assistant/index.js

@@ -3,11 +3,11 @@ import {
   ChatMessages,
   ModelPicker,
   ProviderLogo
-} from "../chunk-EIG7ZQW2.js";
+} from "../chunk-RVUISYUE.js";
 import "../chunk-65P3HJY3.js";
-import "../chunk-3EKOSBYL.js";
+import "../chunk-K63OWUDJ.js";
 import "../chunk-2QI7XV2T.js";
-import "../chunk-JGYOYY5D.js";
+import "../chunk-XKBIYSSM.js";
 import "../chunk-5MG74GVQ.js";
 import "../chunk-XAWFPMAR.js";
 import "../chunk-SIXYZ2FB.js";

package/dist/{attachment-validation-DX2KIzMC.d.ts → attachment-validation-D0csjCvz.d.ts}

@@ -1,4 +1,4 @@
-import { K as FileMention } from './parts-IB-Kbb7z.js';
+import { K as FileMention } from './parts-1sRYSPjF.js';
 
 /**
  * `createSandboxFileIndexRoute` — server side of `@`-file-mentions

package/dist/chat-routes/index.d.ts

@@ -1,6 +1,6 @@
-import { L as ChatTurnRequestPayload, M as ChatTurnPartInput, g as ChatMessagePart, N as ChatTurnFilePartInput, a as ChatAttachmentPart, C as ChatAttachmentKind, f as ChatMentionPart } from '../parts-IB-Kbb7z.js';
-export { O as ChatAttachmentInput, e as ChatMentionKind, P as ChatTurnInputError, Q as ChatTurnTextPartInput, R as DISPATCH_MAX_MEDIA_PARTS, T as DISPATCH_MAX_PARTS, U as DISPATCH_REQUEST_MAX_BYTES, V as DISPATCH_STRUCTURAL_RESERVE_BYTES, K as FileMention, W as FileMentionsToPartsOptions, X as INLINE_PARTS_MAX_BYTES, Y as MENTION_MAX_COUNT, Z as SandboxMentionPathCheck, _ as assertPromptPartsWithinCap, $ as base64WireLen, a0 as buildMentionPromptBlock, a1 as chatTurnRequestInit, a2 as fileMentionsToParts, a3 as formatBytes, a4 as mediaTypeForMentionPath, a5 as mentionKindForPath, a6 as parseChatTurnParts, a7 as parseFileMentions, a8 as promptPartsByteSize, a9 as validateSandboxMentionPath } from '../parts-IB-Kbb7z.js';
-export { A as ALLOWED_ATTACHMENT_SNIFFED_MIMES, a as ATTACHMENT_ACCEPT, b as ATTACHMENT_MAX_COUNT, c as AttachmentTypeCheckResult, C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, d as FileIndexCache, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse, M as MAX_ATTACHMENT_TOTAL_BYTES, h as MAX_BINARY_ATTACHMENT_BYTES, i as MAX_TEXT_ATTACHMENT_BYTES, S as SandboxFileTreeSource, j as SandboxTreeFile, k as SandboxTreeResult, l as SniffResult, m as attachmentSizeErrorMessage, n as attachmentTotalSizeErrorMessage, o as checkAttachmentType, p as createSandboxFileIndexRoute, s as sanitizeAttachmentFileName, q as sniffBinary } from '../attachment-validation-DX2KIzMC.js';
+import { L as ChatTurnRequestPayload, M as ChatTurnPartInput, g as ChatMessagePart, N as ChatTurnFilePartInput, a as ChatAttachmentPart, C as ChatAttachmentKind, f as ChatMentionPart } from '../parts-1sRYSPjF.js';
+export { O as ChatAttachmentInput, e as ChatMentionKind, P as ChatTurnInputError, Q as ChatTurnTextPartInput, R as DISPATCH_MAX_MEDIA_PARTS, T as DISPATCH_MAX_PARTS, U as DISPATCH_REQUEST_MAX_BYTES, V as DISPATCH_STRUCTURAL_RESERVE_BYTES, K as FileMention, W as FileMentionsToPartsOptions, X as INLINE_PARTS_MAX_BYTES, Y as MENTION_MAX_COUNT, Z as ProducerErrorEvent, _ as ProducerNoticeEvent, $ as ProducerPassthroughEvent, a0 as ProducerPassthroughEventType, a1 as ProducerReasoningEvent, a2 as ProducerTextEvent, a3 as ProducerToolCallEvent, a4 as ProducerToolResultEvent, a5 as ProducerUsageEvent, a6 as ProducerWireEvent, a7 as SandboxMentionPathCheck, a8 as assertPromptPartsWithinCap, a9 as base64WireLen, aa as buildMentionPromptBlock, ab as chatTurnRequestInit, ac as fileMentionsToParts, ad as formatBytes, ae as mediaTypeForMentionPath, af as mentionKindForPath, ag as parseChatTurnParts, ah as parseFileMentions, ai as promptPartsByteSize, aj as validateSandboxMentionPath } from '../parts-1sRYSPjF.js';
+export { A as ALLOWED_ATTACHMENT_SNIFFED_MIMES, a as ATTACHMENT_ACCEPT, b as ATTACHMENT_MAX_COUNT, c as AttachmentTypeCheckResult, C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, d as FileIndexCache, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse, M as MAX_ATTACHMENT_TOTAL_BYTES, h as MAX_BINARY_ATTACHMENT_BYTES, i as MAX_TEXT_ATTACHMENT_BYTES, S as SandboxFileTreeSource, j as SandboxTreeFile, k as SandboxTreeResult, l as SniffResult, m as attachmentSizeErrorMessage, n as attachmentTotalSizeErrorMessage, o as checkAttachmentType, p as createSandboxFileIndexRoute, s as sanitizeAttachmentFileName, q as sniffBinary } from '../attachment-validation-D0csjCvz.js';
 import { ChatTurnIdentity, ChatTurnProducer } from '@tangle-network/agent-runtime';
 import { InteractionAnswerRoute, InteractionAnswerRouteOptions } from '../interactions/index.js';
 import { PersistedChatMessageForTurn } from '../stream/index.js';
@@ -335,7 +335,8 @@ declare function createChatTurnRoutes<TContext = void>(options: CreateChatTurnRo
  * the `ChatTurnProducer` shape agent-runtime's `handleChatTurn` consumes AND
  * the client vocabulary `/web-react`'s `dispatchChatStreamLine` already parses
  * (`text` / `reasoning` / `tool_call` / `tool_result` / `usage` /
- * `interaction`). Legal and tax each hand-rolled this mapping differently;
+ * `notice` / structured `error` / `interaction`). Legal and tax each hand-rolled
+ * this mapping differently;
  * this is that middle, composed from `/stream`'s normalizers — no new loop
  * logic, no SDK import (the event source is an injected `AsyncIterable`).
  *
@@ -376,11 +377,13 @@ interface SandboxChatProducerOptions {
     model?: string;
     /** Which ask kinds the product renders a card for. Anything else is
      *  auto-declined (see `declineInteraction`) so the run never hangs in the
-     *  broker waiting on a card no client will show. Default: question/plan. */
+     *  broker waiting on a card no client will show. Default: question/plan.
+     *  Products with per-turn plan mode can close over it without another option:
+     *  `(kind) => kind === 'question' || (kind === 'plan' && planEnabled)`. */
     isRenderableInteraction?: (kind: string) => boolean;
     /** Resolve a non-renderable ask (wire `respondToSessionInteraction` with the
-     *  session's sidecar connection). Without it, non-renderable asks are only
-     *  logged — the run stays blocked until the broker times out. */
+     *  session's sidecar connection). Without it, a failure notice is emitted and
+     *  the run stays blocked until the broker times out. */
     declineInteraction?: (id: string) => Promise<void>;
     /** Opt-in eager promotion of harness-emitted `file` parts. Unset, a `file`
      *  part persists exactly as the harness sent it — a transient `url` (a
@@ -497,8 +500,8 @@ interface DetachedTurnOptions {
 }
 interface DetachedTurnResult {
     /** `completed` — clean drain: persist + bill. `failed` — a terminal error
-     *  EVENT in the stream: skip billing, render an error row. (A stream that
-     *  THROWS re-throws out of `runDetachedTurn` instead of returning here.) */
+     *  event, including the producer's structured `sandbox.stream_failed` event
+     *  when the raw sandbox stream throws: skip billing, render an error row. */
     state: 'completed' | 'failed';
     text: string;
     /** The structured assistant body to persist (tool calls, file/plan/interaction