@tangle-network/agent-app 0.43.25 → 0.43.26

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

@@ -0,0 +1,276 @@
+import { C as ChatTurnRequestPayload, a as ChatTurnPartInput, b as ChatTurnFilePartInput } from '../wire-BaUF66AS.js';
+export { c as ChatTurnInputError, d as ChatTurnTextPartInput, I as INLINE_PARTS_MAX_BYTES, e as assertPromptPartsWithinCap, f as chatTurnRequestInit, p as parseChatTurnParts, g as promptPartsByteSize } from '../wire-BaUF66AS.js';
+import { ChatTurnIdentity, ChatTurnProducer } from '@tangle-network/agent-runtime';
+import { c as ChatMessagePart } from '../parts-BcbitSNp.js';
+import { InteractionAnswerRoute, InteractionAnswerRouteOptions } from '../interactions/index.js';
+import { PersistedChatMessageForTurn, TurnEventStore } from '../stream/index.js';
+import '@tangle-network/agent-interface';
+import '../contract-DYbTzEDf.js';
+
+/**
+ * `createChatTurnRoutes` — the assembled server chat vertical (issue #188
+ * Phase 1). One factory composing the pieces every product re-wired by hand:
+ *
+ *   body parse/validate      → `/web` `parseJsonObjectBody` + `./wire`
+ *   turn identity            → `/stream` `resolveChatTurn` + agent-runtime
+ *                              `deriveExecutionId`
+ *   producer                 → injected seam (sandbox lane via
+ *                              `createSandboxChatProducer`; router lane is the
+ *                              product's own `ChatTurnProducer`)
+ *   turn engine              → agent-runtime `handleChatTurn` (verbatim)
+ *   durability               → `/stream` turn-buffer tap, wired BY DEFAULT
+ *                              (tee + drain keeps the turn running after a
+ *                              client drop; replay serves the buffered tail)
+ *   persistence              → injected `/chat-store`-shaped store
+ *                              (user row on send, assistant row on completion)
+ *   interactions answer      → `/interactions` `createInteractionAnswerRoute`
+ *
+ * Handlers are web-standard `Request → Response` (Workers, Node 18+, Deno) —
+ * no router import. Auth/access is one injected `authorize` seam, composable
+ * with `/app-auth` guards but not coupled to them.
+ */
+
+/** Usage receipt persisted onto the assistant message (the flattened
+ *  `step-finish` shape `/chat-store`'s columns mirror). */
+interface ChatTurnUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costUsd?: number;
+}
+/** What the route persists — a structural subset of `/chat-store`'s
+ *  `ChatStore`, so `createChatStore(db, tables)` satisfies it directly and a
+ *  product with its own persistence adapts without importing drizzle. */
+interface ChatTurnMessageStore {
+    listMessages(threadId: string): Promise<Array<{
+        id: string;
+        role: 'user' | 'assistant' | 'system' | 'tool';
+        content: string;
+        parts?: ChatMessagePart[] | null;
+    }>>;
+    appendMessage(input: {
+        threadId: string;
+        role: 'user' | 'assistant';
+        content: string;
+        parts?: ChatMessagePart[];
+        model?: string | null;
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        reasoningTokens?: number | null;
+        cacheReadTokens?: number | null;
+        cacheWriteTokens?: number | null;
+        costUsd?: number | null;
+    }): Promise<unknown>;
+}
+/** `ChatTurnProducer` plus the persisted projection the assembly reads after
+ *  drain. `createSandboxChatProducer` returns this; a router-lane producer
+ *  may omit the optional members (finalText persists as a single text part). */
+interface ChatTurnRouteProducer extends ChatTurnProducer {
+    assistantParts?(): Array<Record<string, unknown>>;
+    usage?(): ChatTurnUsage;
+    model?: string;
+}
+type ChatTurnAuthorization<TContext> = {
+    ok: true;
+    tenantId: string;
+    userId: string;
+    context: TContext;
+} | {
+    ok: false;
+    response: Response;
+};
+interface ChatTurnAuthorizeArgs {
+    request: Request;
+    intent: 'turn' | 'replay';
+    /** Parsed, validated POST body (turn intent only). */
+    body?: ChatTurnRequestPayload;
+    /** The buffered turn id being replayed (replay intent only). */
+    turnId?: string;
+}
+interface ChatTurnProduceArgs<TContext> {
+    request: Request;
+    body: ChatTurnRequestPayload;
+    identity: ChatTurnIdentity;
+    context: TContext;
+    /** The message to send: plain text, or parts when the client attached
+     *  files (a text part is prepended from `content` when present). */
+    prompt: string | ChatTurnPartInput[];
+    /** Stable id for cross-process reconnect (`deriveExecutionId`). */
+    executionId: string;
+    /** The turn-buffer id announced to the client for replay. */
+    turnStreamId: string;
+    priorMessages: PersistedChatMessageForTurn[];
+}
+interface CreateChatTurnRoutesOptions<TContext = void> {
+    /** Names the product in `deriveExecutionId` so retries land on the same
+     *  substrate execution. */
+    projectId: string;
+    /** Authenticate + authorize the caller for a turn or a replay. The only
+     *  product-supplied access step: session auth, thread/workspace access,
+     *  seat/balance gates, rate limits all live here. */
+    authorize(args: ChatTurnAuthorizeArgs): Promise<ChatTurnAuthorization<TContext>>;
+    /** Thread/message persistence (`/chat-store`'s store or a product adapter). */
+    store: ChatTurnMessageStore;
+    /** Turn-event buffer (`createD1TurnEventStore(env.DB)` in production,
+     *  `createMemoryTurnEventStore()` in tests). Wired by default — every turn
+     *  is buffered and replayable. */
+    turnStore: TurnEventStore;
+    /** Build the turn's event stream. Sandbox lane: `streamSandboxPrompt(...)`
+     *  wrapped in `createSandboxChatProducer`. Router/openai-compat lane: the
+     *  product's own producer. May be async (box resolution). */
+    produce(args: ChatTurnProduceArgs<TContext>): ChatTurnRouteProducer | Promise<ChatTurnRouteProducer>;
+    /** Pre-persist transform of the final text (e.g. `/redact`'s `redactPII`).
+     *  Live stream is never altered. */
+    transformFinalText?(text: string): string | Promise<string>;
+    /** Post-processing after a successful turn (billing, titles, audit). Errors
+     *  are swallowed by the engine — they never fail a streamed turn. */
+    onTurnComplete?(input: {
+        identity: ChatTurnIdentity;
+        finalText: string;
+        context: TContext;
+    }): Promise<void>;
+    /** Per-event side channel (product broadcast). The turn-buffer tap is
+     *  already wired; this runs in addition. */
+    onEvent?(event: {
+        type: string;
+        data?: Record<string, unknown>;
+    }, context: TContext): void | Promise<void>;
+    /** Trace flush handed to `waitUntil` (OTLP export). */
+    traceFlush?(context: TContext): Promise<void>;
+    /** Compose the interaction-answer endpoints (`/interactions`). Omit when the
+     *  product has no sidecar ask channel. */
+    interactions?: InteractionAnswerRouteOptions;
+    /** Byte budget for inline prompt parts. Default `INLINE_PARTS_MAX_BYTES`. */
+    maxInlinePartBytes?: number;
+    /** Per-flush coalescer for the turn buffer. Default `coalesceDeltas` (this
+     *  assembly streams the client vocabulary's `{type:'text'|'reasoning',
+     *  text}` lines, which it merges). A producer streaming raw
+     *  `message.part.updated` events passes `coalesceChatStreamEvents`. */
+    coalesceTurnEvents?: (events: unknown[]) => unknown[];
+    replay?: {
+        pollMs?: number;
+        timeoutMs?: number;
+    };
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface ChatTurnRoutes {
+    /** POST — run one turn, streaming NDJSON. First line is
+     *  `{type:'turn', turnId}` (the replay handle); the rest is the engine's
+     *  event protocol. Pass the platform's `waitUntil` so the turn keeps
+     *  running (and buffering) after a client disconnect. */
+    turn(request: Request, ctx?: {
+        waitUntil?(p: Promise<unknown>): void;
+    }): Promise<Response>;
+    /** GET — replay a buffered turn from `?fromSeq=` (0 = everything), then
+     *  follow it live until it completes. */
+    replay(request: Request, params: {
+        turnId: string;
+    }): Promise<Response>;
+    /** list/answer endpoints from `/interactions`; null when not configured. */
+    interactions: InteractionAnswerRoute | null;
+}
+declare function createChatTurnRoutes<TContext = void>(options: CreateChatTurnRoutesOptions<TContext>): ChatTurnRoutes;
+
+/**
+ * Sandbox lane: bridge a raw sandbox event stream (`streamSandboxPrompt`) into
+ * 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;
+ * this is that middle, composed from `/stream`'s normalizers — no new loop
+ * logic, no SDK import (the event source is an injected `AsyncIterable`).
+ *
+ * Alongside the live mapping it accumulates the PERSISTED projection — the
+ * `message.parts` rows `/chat-store` stores — via `normalizePersistedPart` /
+ * `mergePersistedPart` / `finalizeAssistantParts`, plus the usage receipt from
+ * `step-finish` parts. `createChatTurnRoutes` reads both after drain.
+ */
+
+interface SandboxChatProducerOptions {
+    /** The raw sandbox event stream (e.g. `streamSandboxPrompt(...)`). */
+    events: AsyncIterable<unknown>;
+    /** Recorded on the persisted assistant message. */
+    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. */
+    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. */
+    declineInteraction?: (id: string) => Promise<void>;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+declare function createSandboxChatProducer(options: SandboxChatProducerOptions): ChatTurnRouteProducer;
+
+/**
+ * `createUploadRoute` — the multimodal middle. Accepts multipart file uploads
+ * and returns `PromptInputPart`-shaped descriptors the client echoes back on
+ * send (`ChatTurnRequestPayload.parts`):
+ *
+ *   ≤ inlineMaxBytes (700 KiB default) → inline `data:` URI part — rides the
+ *     turn body directly, no sandbox round trip.
+ *   > inlineMaxBytes → written into the sandbox workspace (base64 through the
+ *     structural `write` seam — `box.fs` satisfies it) and referenced by
+ *     `path`. Mandatory two-step: the gateway caps request bodies at ~1 MiB,
+ *     so a large file can never ride the prompt POST.
+ *
+ * The sink is structural (no sandbox-SDK import); products pass `box.fs`.
+ */
+
+/** 700 KiB: base64 inflates ~4/3, so an inline part stays comfortably under
+ *  the ~1 MiB gateway body cap alongside the JSON envelope. */
+declare const UPLOAD_INLINE_MAX_BYTES: number;
+/** 8 MiB default ceiling per file — one base64 `write` call handles it. Raise
+ *  it only with a sink that can take the bigger single write. */
+declare const UPLOAD_MAX_FILE_BYTES: number;
+/** Structural match of the sandbox SDK's `box.fs` write surface (v0.10.5+:
+ *  `encoding: 'base64'` is the worker-safe binary path). */
+interface SandboxUploadSink {
+    write(path: string, content: string, options?: {
+        encoding?: 'utf8' | 'base64';
+    }): Promise<unknown>;
+}
+type UploadAuthorization = {
+    ok: true;
+    /** Where large files land. Absent/null: only inline uploads are
+     *  accepted and an over-inline-cap file is rejected with 413. */
+    sink?: SandboxUploadSink | null;
+    /** Per-request override of the workspace directory large files go to. */
+    uploadDir?: string;
+} | {
+    ok: false;
+    response: Response;
+};
+interface CreateUploadRouteOptions {
+    /** Authenticate the caller and resolve the sandbox file sink (usually
+     *  `ensureWorkspaceSandbox(...)` → `box.fs`). */
+    authorize(args: {
+        request: Request;
+    }): Promise<UploadAuthorization>;
+    /** Inline-vs-sandbox threshold. Default {@link UPLOAD_INLINE_MAX_BYTES}. */
+    inlineMaxBytes?: number;
+    /** Hard per-file cap. Default {@link UPLOAD_MAX_FILE_BYTES}. */
+    maxFileBytes?: number;
+    /** Workspace directory for path-ref files. Default `'uploads'`. */
+    uploadDir?: string;
+}
+/** One uploaded file, ready for the composer chip and the turn body. */
+interface UploadedChatFile {
+    id: string;
+    name: string;
+    size: number;
+    mediaType: string;
+    /** True when the part carries the bytes inline (`data:` URI). */
+    inline: boolean;
+    /** Echo this back verbatim in `ChatTurnRequestPayload.parts`. */
+    part: ChatTurnFilePartInput;
+}
+/** Path-safe file name: basename only, conservative charset, length-capped. */
+declare function sanitizeUploadFilename(name: string): string;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function createUploadRoute(options: CreateUploadRouteOptions): (request: Request) => Promise<Response>;
+
+export { type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnMessageStore, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, bytesToBase64, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, sanitizeUploadFilename };