@tangle-network/agent-app 0.60.229 → 0.60.230
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -0
- package/dist/chat-routes/index.js +1 -1
- package/dist/chat-routes/turn-admission.d.ts +43 -0
- package/dist/chat-routes/turn-event-stream.d.ts +31 -0
- package/dist/chat-routes/turn-execution.d.ts +23 -0
- package/dist/chat-routes/turn-route-contracts.d.ts +724 -0
- package/dist/chat-routes/turn-routes.d.ts +2 -723
- package/dist/{chunk-PTB2B2OO.js → chunk-RMPPWNW7.js} +363 -336
- package/dist/chunk-RMPPWNW7.js.map +1 -0
- package/dist/public-consultation/index.js +1 -1
- package/dist/skills-placement/index.d.ts +16 -3
- package/dist/skills-placement/index.js +11 -7
- package/dist/skills-placement/index.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-PTB2B2OO.js.map +0 -1
|
@@ -50,728 +50,7 @@
|
|
|
50
50
|
* keeps its two-argument `(event, context)` signature rather than being
|
|
51
51
|
* normalized to the single-args shape the other seams take.
|
|
52
52
|
*/
|
|
53
|
-
import { type
|
|
54
|
-
|
|
55
|
-
import { type DraftPersistenceTuning } from './draft-persistence';
|
|
56
|
-
import { type InteractionAnswerRoute, type InteractionAnswerRouteOptions } from '../interactions/route';
|
|
57
|
-
import { type PersistedChatMessageForTurn, type TurnEventStore } from '../stream/index';
|
|
58
|
-
import type { ModelFailoverAttempt } from '../model-resolution/failover';
|
|
59
|
-
import { type ModelPolicy } from '../policy-filters/index';
|
|
60
|
-
import { type TurnSpan, type TurnSpanAttrs, type TurnTrace, type TurnTraceSink, type TurnTraceSummary } from '../turn-trace/recorder';
|
|
61
|
-
import { type TurnRoutePhase } from './turn-progress';
|
|
62
|
-
import { type ChatTurnPartInput, type ChatTurnRequestPayload } from './wire';
|
|
63
|
-
/** Usage receipt persisted onto the assistant message (the flattened
|
|
64
|
-
* `step-finish` shape `/chat-store`'s columns mirror). */
|
|
65
|
-
export interface ChatTurnUsage {
|
|
66
|
-
inputTokens?: number;
|
|
67
|
-
outputTokens?: number;
|
|
68
|
-
reasoningTokens?: number;
|
|
69
|
-
cacheReadTokens?: number;
|
|
70
|
-
cacheWriteTokens?: number;
|
|
71
|
-
costUsd?: number;
|
|
72
|
-
}
|
|
73
|
-
/** What the route persists — a structural subset of `/chat-store`'s
|
|
74
|
-
* `ChatStore`, so `createChatStore(db, tables)` satisfies it directly and a
|
|
75
|
-
* product with its own persistence adapts without importing drizzle. */
|
|
76
|
-
export interface ChatTurnMessageStore {
|
|
77
|
-
listMessages(threadId: string): Promise<Array<{
|
|
78
|
-
id: string;
|
|
79
|
-
role: 'user' | 'assistant' | 'system' | 'tool';
|
|
80
|
-
content: string;
|
|
81
|
-
parts?: ChatMessagePart[] | null;
|
|
82
|
-
}>>;
|
|
83
|
-
appendMessage(input: {
|
|
84
|
-
/** Caller-assigned row id. Honored by `/chat-store`'s `createChatStore`;
|
|
85
|
-
* a product store free to ignore it (the writer then adopts whatever id
|
|
86
|
-
* the insert returns). Set only by incremental persistence. */
|
|
87
|
-
id?: string;
|
|
88
|
-
threadId: string;
|
|
89
|
-
role: 'user' | 'assistant';
|
|
90
|
-
content: string;
|
|
91
|
-
parts?: ChatMessagePart[];
|
|
92
|
-
model?: string | null;
|
|
93
|
-
requestedModel?: string | null;
|
|
94
|
-
servedModel?: string | null;
|
|
95
|
-
servedProvider?: string | null;
|
|
96
|
-
servedSource?: string | null;
|
|
97
|
-
inputTokens?: number | null;
|
|
98
|
-
outputTokens?: number | null;
|
|
99
|
-
reasoningTokens?: number | null;
|
|
100
|
-
cacheReadTokens?: number | null;
|
|
101
|
-
cacheWriteTokens?: number | null;
|
|
102
|
-
costUsd?: number | null;
|
|
103
|
-
}): Promise<unknown>;
|
|
104
|
-
/** Patch an existing row. Its PRESENCE is what enables incremental assistant
|
|
105
|
-
* persistence — a store without it keeps today's exact single-write-on-
|
|
106
|
-
* completion behavior, which is what makes this additive. */
|
|
107
|
-
updateMessage?(id: string, patch: {
|
|
108
|
-
content?: string;
|
|
109
|
-
parts?: ChatMessagePart[];
|
|
110
|
-
model?: string | null;
|
|
111
|
-
requestedModel?: string | null;
|
|
112
|
-
servedModel?: string | null;
|
|
113
|
-
servedProvider?: string | null;
|
|
114
|
-
servedSource?: string | null;
|
|
115
|
-
inputTokens?: number | null;
|
|
116
|
-
outputTokens?: number | null;
|
|
117
|
-
reasoningTokens?: number | null;
|
|
118
|
-
cacheReadTokens?: number | null;
|
|
119
|
-
cacheWriteTokens?: number | null;
|
|
120
|
-
costUsd?: number | null;
|
|
121
|
-
}): Promise<unknown>;
|
|
122
|
-
/** Remove a row. Used to retract a draft assistant row for a turn that ended
|
|
123
|
-
* producing nothing, so the empty-turn case still leaves no row at all. */
|
|
124
|
-
deleteMessage?(id: string): Promise<unknown>;
|
|
125
|
-
}
|
|
126
|
-
/** `ChatTurnProducer` plus the persisted projection the assembly reads after
|
|
127
|
-
* drain. `createSandboxChatProducer` returns this; a router-lane producer
|
|
128
|
-
* may omit the optional members (finalText persists as a single text part). */
|
|
129
|
-
export interface ChatTurnRouteProducer extends ChatTurnProducer {
|
|
130
|
-
/** Actual backend result/done was observed; transport EOF/error alone is not completion. */
|
|
131
|
-
terminalObserved?(): boolean;
|
|
132
|
-
assistantParts?(): Array<Record<string, unknown>>;
|
|
133
|
-
/** MID-STREAM snapshot of the same projection, safe to call while the turn
|
|
134
|
-
* is running: no dangling-tool terminalization, no pending-ask settlement
|
|
135
|
-
* (see `/stream`'s `draftAssistantParts`). Read by incremental persistence.
|
|
136
|
-
* A producer that omits it still drafts — the scalar text — but persists no
|
|
137
|
-
* parts until the turn completes. */
|
|
138
|
-
draftParts?(): Array<Record<string, unknown>>;
|
|
139
|
-
usage?(): ChatTurnUsage;
|
|
140
|
-
/** The model that SERVED the turn. With failover wired this is the model that
|
|
141
|
-
* actually answered, which is not necessarily the one the caller preferred —
|
|
142
|
-
* read it after the stream drains, never before. */
|
|
143
|
-
model?: string;
|
|
144
|
-
/** Model-failover attribution, when the producer supports it. Reported onto
|
|
145
|
-
* the usage/billing receipt so a downgrade is never silent. */
|
|
146
|
-
modelFailover?(): ChatTurnModelFailover;
|
|
147
|
-
/** Requested-versus-served attribution reported by the sandbox sidecar.
|
|
148
|
-
* `echoReceived` distinguishes a missing echo from a partial echo. */
|
|
149
|
-
modelAttribution?(): ChatTurnModelAttribution;
|
|
150
|
-
}
|
|
151
|
-
/** Which model served, and what it took to get there. */
|
|
152
|
-
export interface ChatTurnModelFailover {
|
|
153
|
-
/** The model that served the turn. */
|
|
154
|
-
model?: string;
|
|
155
|
-
/** Every model tried, in order, with the reason each was abandoned. */
|
|
156
|
-
attempts: ModelFailoverAttempt[];
|
|
157
|
-
/** True when the preferred model did not serve. */
|
|
158
|
-
usedFallback: boolean;
|
|
159
|
-
}
|
|
160
|
-
/** Requested and effective model attribution for one sandbox turn. */
|
|
161
|
-
export interface ChatTurnModelAttribution {
|
|
162
|
-
/** The model explicitly requested by the caller, before shell failover. */
|
|
163
|
-
requestedModel?: string;
|
|
164
|
-
/** The model the downstream sandbox reports actually served the turn. */
|
|
165
|
-
servedModel?: string;
|
|
166
|
-
/** The provider that served the turn, when echoed by the sandbox. */
|
|
167
|
-
servedProvider?: string;
|
|
168
|
-
/** How the sandbox selected the served model. */
|
|
169
|
-
servedSource?: 'request' | 'environment' | 'profile';
|
|
170
|
-
/** True when a structurally valid effective-backend echo was observed. */
|
|
171
|
-
echoReceived: boolean;
|
|
172
|
-
}
|
|
173
|
-
/** Resolve authorization status and context for a chat turn including tenant and user identification */
|
|
174
|
-
export type ChatTurnAuthorization<TContext> = {
|
|
175
|
-
ok: true;
|
|
176
|
-
tenantId: string;
|
|
177
|
-
userId: string;
|
|
178
|
-
context: TContext;
|
|
179
|
-
/** When `false`, skip the `role:'user'` message insert for this turn — for
|
|
180
|
-
* a product-dispatched / synthetic turn (e.g. a follow-up the product
|
|
181
|
-
* raised itself) that must not surface a new user row. Composes with —
|
|
182
|
-
* never overrides — the engine's retry-dedup: `authorize` runs before
|
|
183
|
-
* turn identity is resolved, so it cannot tell a retry from a fresh turn;
|
|
184
|
-
* a turn already deduped stays deduped. Omit / `true` → today's behavior.
|
|
185
|
-
*
|
|
186
|
-
* Settled shape (#227). The validated case in both consumers is the same:
|
|
187
|
-
* a durable plan-approval follow-up re-entering an execution the decision
|
|
188
|
-
* route already enqueued — a decision, not a typed message, so it must
|
|
189
|
-
* not surface a user bubble. Suppressing the insert also propagates:
|
|
190
|
-
* `ChatTurnProduceArgs.userMessageId` is `null` for the rest of the turn
|
|
191
|
-
* when there is no row to reuse, so a seam anchoring to the user row must
|
|
192
|
-
* handle that arm rather than assume a string. */
|
|
193
|
-
insertUserMessage?: boolean;
|
|
194
|
-
} | {
|
|
195
|
-
ok: false;
|
|
196
|
-
response: Response;
|
|
197
|
-
};
|
|
198
|
-
/** Define arguments required to authorize a chat turn based on intent and request details */
|
|
199
|
-
export interface ChatTurnAuthorizeArgs {
|
|
200
|
-
request: Request;
|
|
201
|
-
intent: 'turn' | 'replay' | 'running';
|
|
202
|
-
/** Parsed, validated POST body (turn intent only). */
|
|
203
|
-
body?: ChatTurnRequestPayload;
|
|
204
|
-
/** The buffered turn id being replayed (replay intent only). */
|
|
205
|
-
turnId?: string;
|
|
206
|
-
/** The thread whose running turns are being discovered (running intent only). */
|
|
207
|
-
threadId?: string;
|
|
208
|
-
/** The turn's trace (turn intent only). A product records its own child spans (a billing read, a workspace check) so the
|
|
209
|
-
* admission wait is named by step; the route already records `admission.authorize` around the whole call. */
|
|
210
|
-
trace?: TurnTrace;
|
|
211
|
-
/** The `admission.authorize` span (turn intent only): the parent for those child spans, so they nest under it. */
|
|
212
|
-
span?: TurnSpan;
|
|
213
|
-
}
|
|
214
|
-
/** What `prepareTurn` receives: the admitted turn, before the conversation loads. */
|
|
215
|
-
export interface ChatTurnPrepareArgs<TContext> {
|
|
216
|
-
request: Request;
|
|
217
|
-
/** Parsed, validated POST body. */
|
|
218
|
-
body: ChatTurnRequestPayload;
|
|
219
|
-
tenantId: string;
|
|
220
|
-
userId: string;
|
|
221
|
-
threadId: string;
|
|
222
|
-
/** The context `authorize` returned; mutate it in place to finish it. */
|
|
223
|
-
context: TContext;
|
|
224
|
-
/** Name the stage this work is in. On a progress-first stream it reaches the
|
|
225
|
-
* client as a `session.run.phase` event; otherwise it is a no-op. */
|
|
226
|
-
progress(phase: string, message: string): void;
|
|
227
|
-
}
|
|
228
|
-
/** `prepareTurn`'s verdict: proceed, or answer with the product's response. */
|
|
229
|
-
export type ChatTurnPrepareResult = {
|
|
230
|
-
ok: true;
|
|
231
|
-
} | {
|
|
232
|
-
ok: false;
|
|
233
|
-
response: Response;
|
|
234
|
-
};
|
|
235
|
-
/** What `afterAuthorize` receives: the admitted turn, before the conversation loads and before any lock, read or write. */
|
|
236
|
-
export interface ChatTurnAfterAuthorizeArgs<TContext> {
|
|
237
|
-
request: Request;
|
|
238
|
-
/** Parsed, validated POST body. */
|
|
239
|
-
body: ChatTurnRequestPayload;
|
|
240
|
-
tenantId: string;
|
|
241
|
-
userId: string;
|
|
242
|
-
threadId: string;
|
|
243
|
-
/** The context `authorize` returned. Keep what the seam starts on it: `prepareTurn`, every later seam and `produce` receive the same object. */
|
|
244
|
-
context: TContext;
|
|
245
|
-
/** The turn's trace, for the spans of the work the seam starts. */
|
|
246
|
-
trace: TurnTrace;
|
|
247
|
-
}
|
|
248
|
-
/** Frees what `afterAuthorize` started, for a turn that ends before `produce` takes it. */
|
|
249
|
-
export type ChatTurnAfterAuthorizeRelease = () => void | Promise<void>;
|
|
250
|
-
/** Trusted per-turn limits supplied by a server adapter, never by the body. */
|
|
251
|
-
export interface ChatTurnExecutionLimits {
|
|
252
|
-
maxInputTokens?: number;
|
|
253
|
-
maxOutputTokens?: number;
|
|
254
|
-
maxReasoningTokens?: number;
|
|
255
|
-
maxToolTokens?: number;
|
|
256
|
-
maxToolCalls?: number;
|
|
257
|
-
maxProviderCostUsd?: number;
|
|
258
|
-
}
|
|
259
|
-
/** Server-only context for one turn request. */
|
|
260
|
-
export interface ChatTurnRequestContext {
|
|
261
|
-
waitUntil?(p: Promise<unknown>): void;
|
|
262
|
-
/** Abort this turn when its HTTP client disconnects. Browser callers omit it. */
|
|
263
|
-
cancelOnDisconnect?: boolean;
|
|
264
|
-
/** Limits already authenticated by the server adapter. */
|
|
265
|
-
executionLimits?: ChatTurnExecutionLimits;
|
|
266
|
-
}
|
|
267
|
-
/** Define the arguments required to produce a chat turn with context and messaging details */
|
|
268
|
-
export interface ChatTurnProduceArgs<TContext> {
|
|
269
|
-
request: Request;
|
|
270
|
-
body: ChatTurnRequestPayload;
|
|
271
|
-
identity: ChatTurnIdentity;
|
|
272
|
-
context: TContext;
|
|
273
|
-
/** The message to send: plain text, or parts when the client attached
|
|
274
|
-
* files (a text part is prepended from `content` when present). */
|
|
275
|
-
prompt: string | ChatTurnPartInput[];
|
|
276
|
-
/** Stable id for cross-process reconnect (`deriveExecutionId`). */
|
|
277
|
-
executionId: string;
|
|
278
|
-
/** The turn-buffer id announced to the client for replay. */
|
|
279
|
-
turnStreamId: string;
|
|
280
|
-
priorMessages: PersistedChatMessageForTurn[];
|
|
281
|
-
/** The turn's intent line (`intentLine`), or null when it was off, slow or
|
|
282
|
-
* failed. Never rejects. A product puts it in the harness turn's context so
|
|
283
|
-
* the agent knows what the founder was told it would do. */
|
|
284
|
-
intentLine?: Promise<string | null>;
|
|
285
|
-
/** Server-authenticated limits for this turn. Never copied from the body. */
|
|
286
|
-
executionLimits?: ChatTurnExecutionLimits;
|
|
287
|
-
/**
|
|
288
|
-
* The turn's trace (`@tangle-network/agent-app/turn-trace`), bound to this turn's execution id. Pass it to the
|
|
289
|
-
* Router engine (`trace`), `streamSandboxPrompt` and `ensureWorkspaceSandbox` so the turn's model calls, tool
|
|
290
|
-
* calls and box claim are recorded under it; its `traceId` is what those calls send as `x-tangle-trace-id`.
|
|
291
|
-
* The route records admission and persistence itself. Optional for source compatibility with synthetic
|
|
292
|
-
* producers; every `createChatTurnRoutes` invocation supplies it.
|
|
293
|
-
*/
|
|
294
|
-
trace?: TurnTrace;
|
|
295
|
-
/** The durable `role:'user'` row this turn is anchored to — the row the
|
|
296
|
-
* factory just inserted, or the one retry-dedup REUSED. Products anchor
|
|
297
|
-
* optimistic-bubble swaps, retry targeting, and stop-polling to it, and it
|
|
298
|
-
* is the only way to name a REUSED row (which `priorMessages` excludes).
|
|
299
|
-
*
|
|
300
|
-
* Three states, all meaningful:
|
|
301
|
-
* - `undefined` — not resolved yet. `turnLock.acquire` is the one seam that
|
|
302
|
-
* sees this: it runs before any side effect by contract, so the row does
|
|
303
|
-
* not exist when it reads the args.
|
|
304
|
-
* - `null` — resolved, no row: `authorize` returned `insertUserMessage:
|
|
305
|
-
* false` on a turn with nothing to reuse, or the store's `appendMessage`
|
|
306
|
-
* resolved without a usable id.
|
|
307
|
-
* - a string — the row id, for `contextGate`, `beforeTurn`, and `produce`. */
|
|
308
|
-
userMessageId?: string | null;
|
|
309
|
-
/** True when this turn's own insert created `userMessageId`, so no earlier
|
|
310
|
-
* attempt can have answered it; false when retry-dedup reused the row or no
|
|
311
|
-
* row was written. A gate that refuses an already-answered retry can skip
|
|
312
|
-
* its read when this is true. Undefined until `userMessageId` resolves. */
|
|
313
|
-
userMessageInserted?: boolean;
|
|
314
|
-
/**
|
|
315
|
-
* Transfer completion ownership to a product-owned durable runner. The
|
|
316
|
-
* product MUST first register that runner durably, then await this callback
|
|
317
|
-
* before dispatching native execution. Once it resolves, this route remains
|
|
318
|
-
* a live event projector only: it no longer writes or settles the assistant
|
|
319
|
-
* transcript, lifecycle hooks, lock, or replay-buffer status.
|
|
320
|
-
*
|
|
321
|
-
* Optional for source compatibility with synthetic producers. Every
|
|
322
|
-
* `createChatTurnRoutes` invocation supplies it before `produce` runs.
|
|
323
|
-
*/
|
|
324
|
-
handoffCompletion?: () => Promise<void>;
|
|
325
|
-
}
|
|
326
|
-
/** One event as it crosses the route: the producer's own vocabulary, or an
|
|
327
|
-
* injected keepalive. Same shape the engine forwards verbatim.
|
|
328
|
-
*
|
|
329
|
-
* Public because it IS the vocabulary of two seams — `onRawEvent`'s parameter
|
|
330
|
-
* and `heartbeat.event`'s return. Exported so a product can declare a
|
|
331
|
-
* standalone handler (`function onRawEvent(e: ChatRouteEvent, ctx: T)`) rather
|
|
332
|
-
* than depending on contextual typing from an inline object literal. */
|
|
333
|
-
export type ChatRouteEvent = {
|
|
334
|
-
type: string;
|
|
335
|
-
data?: Record<string, unknown>;
|
|
336
|
-
};
|
|
337
|
-
/** Keepalive emitted while the producer is quiet (long tool calls, first-token
|
|
338
|
-
* wait) so client watchdogs stay re-armed. One is emitted each time
|
|
339
|
-
* `intervalMs` elapses with no producer event; the window resets on every real
|
|
340
|
-
* event, so a chatty producer never triggers one. The product owns the event
|
|
341
|
-
* shape (`type` + `data`). Omit → no keepalives (today's behavior). */
|
|
342
|
-
export interface ChatTurnHeartbeat {
|
|
343
|
-
intervalMs: number;
|
|
344
|
-
event(info: {
|
|
345
|
-
elapsedMs: number;
|
|
346
|
-
tick: number;
|
|
347
|
-
}): ChatRouteEvent;
|
|
348
|
-
}
|
|
349
|
-
/** Patch a `beforeTurn` hook returns to augment the producer's input. Omitted
|
|
350
|
-
* fields keep the route-assembled value; the product's `produce` still owns
|
|
351
|
-
* the system prompt. */
|
|
352
|
-
export interface ChatTurnInputPatch {
|
|
353
|
-
prompt?: string | ChatTurnPartInput[];
|
|
354
|
-
priorMessages?: PersistedChatMessageForTurn[];
|
|
355
|
-
}
|
|
356
|
-
/** Pre-turn readiness verdict — proceed, short-circuit, or hand off to a
|
|
357
|
-
* product-owned durable turn. Distinct from `authorize`: this gates domain
|
|
358
|
-
* readiness, not access. */
|
|
359
|
-
export type ChatTurnGateResult = {
|
|
360
|
-
proceed: true;
|
|
361
|
-
} | {
|
|
362
|
-
proceed: false;
|
|
363
|
-
response: Response;
|
|
364
|
-
}
|
|
365
|
-
/** The product has accepted the turn and owns execution and lifecycle after
|
|
366
|
-
* the route releases its lock. */
|
|
367
|
-
| {
|
|
368
|
-
proceed: 'handoff';
|
|
369
|
-
response: Response;
|
|
370
|
-
};
|
|
371
|
-
/** Single-flight lock verdict — acquired (with an opaque handle passed back to
|
|
372
|
-
* `release`), or already held (short-circuit with the product's 409-style
|
|
373
|
-
* `Response`). */
|
|
374
|
-
export type ChatTurnLockResult = {
|
|
375
|
-
acquired: true;
|
|
376
|
-
handle?: unknown;
|
|
377
|
-
} | {
|
|
378
|
-
acquired: false;
|
|
379
|
-
response: Response;
|
|
380
|
-
};
|
|
381
|
-
/** Async acquire/release wrapped around the turn. `acquire` runs before any
|
|
382
|
-
* side effect; `release` runs once when the turn settles — including on a
|
|
383
|
-
* short-circuit or a throw. */
|
|
384
|
-
export interface ChatTurnLock<TContext> {
|
|
385
|
-
acquire(args: ChatTurnProduceArgs<TContext>): ChatTurnLockResult | Promise<ChatTurnLockResult>;
|
|
386
|
-
release(handle: unknown): void | Promise<void>;
|
|
387
|
-
/** Bring up whatever `acquire` will talk to, as soon as the turn is admitted
|
|
388
|
-
* and while `prepareTurn` and the history read run. Never awaited; a failure
|
|
389
|
-
* is logged and the turn goes on to `acquire` as usual. */
|
|
390
|
-
warm?(target: {
|
|
391
|
-
tenantId: string;
|
|
392
|
-
userId: string;
|
|
393
|
-
threadId: string;
|
|
394
|
-
context: TContext;
|
|
395
|
-
}): void | Promise<void>;
|
|
396
|
-
}
|
|
397
|
-
interface ChatTurnLifecycleBase<TContext> {
|
|
398
|
-
identity: ChatTurnIdentity;
|
|
399
|
-
executionId: string;
|
|
400
|
-
turnStreamId: string;
|
|
401
|
-
context: TContext;
|
|
402
|
-
}
|
|
403
|
-
/** When the turn's first visible word streamed, measured from `onTurnStart`. Absent when no word streamed. */
|
|
404
|
-
interface ChatTurnLifecycleTiming {
|
|
405
|
-
/** First reasoning, tool activity or answer output, measured from onTurnStart. */
|
|
406
|
-
firstVisibleMs?: number;
|
|
407
|
-
firstTextMs?: number;
|
|
408
|
-
/** Where the turn's wall time went: its share inside named spans and the time per kind of span. */
|
|
409
|
-
trace?: TurnTraceSummary;
|
|
410
|
-
}
|
|
411
|
-
/** Define lifecycle start event with context and timestamp for a chat turn */
|
|
412
|
-
export interface ChatTurnLifecycleStart<TContext> extends ChatTurnLifecycleBase<TContext> {
|
|
413
|
-
startedAt: number;
|
|
414
|
-
}
|
|
415
|
-
/** Define the structure representing the completion state of a chat turn lifecycle with usage data */
|
|
416
|
-
export interface ChatTurnLifecycleComplete<TContext> extends ChatTurnLifecycleBase<TContext>, ChatTurnLifecycleTiming {
|
|
417
|
-
finalText: string;
|
|
418
|
-
usage: ChatTurnUsage;
|
|
419
|
-
durationMs: number;
|
|
420
|
-
/** The model that SERVED the turn — the fallback's id when failover moved it.
|
|
421
|
-
* `usage` is that model's, so telemetry that splits cost or quality by model
|
|
422
|
-
* must key on this and not on the requested one. */
|
|
423
|
-
model?: string;
|
|
424
|
-
/** Requested-versus-served attribution. A difference is detectable from
|
|
425
|
-
* this receipt and from the persisted assistant row independently. */
|
|
426
|
-
requestedModel?: string;
|
|
427
|
-
servedModel?: string;
|
|
428
|
-
servedProvider?: string;
|
|
429
|
-
servedSource?: 'request' | 'environment' | 'profile';
|
|
430
|
-
/** Attribution for a downgrade: which models were tried and why each failed.
|
|
431
|
-
* `undefined` when the producer reports no failover support. */
|
|
432
|
-
modelFailover?: ChatTurnModelFailover;
|
|
433
|
-
/** The durable `role:'assistant'` row this turn wrote, or `null` when it
|
|
434
|
-
* wrote none (an empty turn leaves no row — a draft started mid-stream is
|
|
435
|
-
* retracted). The detached lane surfaces the same id as
|
|
436
|
-
* `DetachedTurnResult.messageId`; one contract, two lanes. */
|
|
437
|
-
assistantMessageId: string | null;
|
|
438
|
-
/** Set when `contextGate` answered this turn and the producer never ran.
|
|
439
|
-
*
|
|
440
|
-
* Present so telemetry can tell "the model produced nothing" apart from "the
|
|
441
|
-
* model was never asked" — they look identical here (`finalText: ''`,
|
|
442
|
-
* empty `usage`) and mean opposite things. A gated turn writes no assistant
|
|
443
|
-
* row, so `assistantMessageId` is `null`, and the billing/persistence
|
|
444
|
-
* `onTurnComplete` is deliberately NOT fired for it. */
|
|
445
|
-
gated?: true;
|
|
446
|
-
}
|
|
447
|
-
/** Represent an error occurring during a chat turn lifecycle with context and duration information */
|
|
448
|
-
export interface ChatTurnLifecycleError<TContext> extends ChatTurnLifecycleBase<TContext>, ChatTurnLifecycleTiming {
|
|
449
|
-
error: unknown;
|
|
450
|
-
durationMs: number;
|
|
451
|
-
}
|
|
452
|
-
/** Deterministic run telemetry: `onTurnStart` fires before the producer runs;
|
|
453
|
-
* exactly one of `onTurnComplete` / `onTurnError` fires after the turn
|
|
454
|
-
* settles, always after `onTurnStart`. Failure is derived from the turn's own
|
|
455
|
-
* `error` / `session.run.failed` events (or a drain throw), not the engine's
|
|
456
|
-
* lifecycle envelope. Hook errors are swallowed — telemetry never fails a
|
|
457
|
-
* turn. */
|
|
458
|
-
export interface ChatTurnLifecycle<TContext> {
|
|
459
|
-
onTurnStart?(info: ChatTurnLifecycleStart<TContext>): void | Promise<void>;
|
|
460
|
-
onTurnComplete?(info: ChatTurnLifecycleComplete<TContext>): void | Promise<void>;
|
|
461
|
-
onTurnError?(info: ChatTurnLifecycleError<TContext>): void | Promise<void>;
|
|
462
|
-
/** Follow-up work for a turn that ended cleanly: it runs with `onTurnComplete`'s own info once the assistant row is
|
|
463
|
-
* persisted, the lifecycle hooks have fired and the thread's lock is released, under `waitUntil` where the host has
|
|
464
|
-
* one. The member's next send never waits for it, so work that only decorates the answer (a model-written
|
|
465
|
-
* checklist, a title, an index) belongs here and not in the producer's stream, where it holds the lock and the
|
|
466
|
-
* stream open. It does not run for a failed, gated or handed-off turn. The turn's trace has ended; a product that
|
|
467
|
-
* wants this work traced starts its own. A throw is logged and never reaches the member. */
|
|
468
|
-
afterSettle?(info: ChatTurnLifecycleComplete<TContext>): void | Promise<void>;
|
|
469
|
-
}
|
|
470
|
-
/** What a settled turn reports to `onTurnComplete` — the product's
|
|
471
|
-
* post-processing seam (billing, titles, audit). */
|
|
472
|
-
export interface ChatTurnCompleteInput<TContext> {
|
|
473
|
-
identity: ChatTurnIdentity;
|
|
474
|
-
finalText: string;
|
|
475
|
-
context: TContext;
|
|
476
|
-
failed: boolean;
|
|
477
|
-
failureReason?: string;
|
|
478
|
-
/** Typed reason of a failed turn, when its terminal error event names one. */
|
|
479
|
-
failureCode?: string;
|
|
480
|
-
/** The model that SERVED this turn. With failover wired it may differ from
|
|
481
|
-
* the requested one, so a product that bills or scores per model MUST read
|
|
482
|
-
* it here rather than assuming the model it asked for. */
|
|
483
|
-
model?: string;
|
|
484
|
-
/** Requested-versus-served attribution. A difference is detectable from
|
|
485
|
-
* this receipt and from the persisted assistant row independently. */
|
|
486
|
-
requestedModel?: string;
|
|
487
|
-
servedModel?: string;
|
|
488
|
-
servedProvider?: string;
|
|
489
|
-
servedSource?: 'request' | 'environment' | 'profile';
|
|
490
|
-
/** Present when the producer supports failover: the full attempt trail, and
|
|
491
|
-
* `usedFallback` — the flag that makes a silent downgrade impossible. */
|
|
492
|
-
modelFailover?: ChatTurnModelFailover;
|
|
493
|
-
/** The durable `role:'assistant'` row this turn wrote, or `null` when it
|
|
494
|
-
* wrote none (an empty turn leaves no row).
|
|
495
|
-
*
|
|
496
|
-
* Populated even when `failed` is true — a terminal error event still
|
|
497
|
-
* persists whatever partial answer arrived, and that pairing is exactly
|
|
498
|
-
* what lets a product render an error row against a REAL message instead of
|
|
499
|
-
* hunting for the newest row in the thread. The detached lane surfaces the
|
|
500
|
-
* same id as `DetachedTurnResult.messageId`. */
|
|
501
|
-
assistantMessageId: string | null;
|
|
502
|
-
}
|
|
503
|
-
/** Where a finished turn's trace goes, and the host's labels for its root span. Metadata only: never content. */
|
|
504
|
-
export interface ChatTurnTraceOptions<TContext> {
|
|
505
|
-
/** Default: `createIntelligenceTurnTraceSink({ project: projectId })`, which reads the Sandbox product key from the environment. */
|
|
506
|
-
sink?: TurnTraceSink;
|
|
507
|
-
/** Labels for the root span, e.g. the workspace id. Called once per exported turn. */
|
|
508
|
-
labels?(info: {
|
|
509
|
-
identity: ChatTurnIdentity;
|
|
510
|
-
executionId: string;
|
|
511
|
-
context: TContext;
|
|
512
|
-
}): TurnSpanAttrs;
|
|
513
|
-
}
|
|
514
|
-
/** Define options to configure chat turn routes including authorization, storage, and event buffering */
|
|
515
|
-
export interface CreateChatTurnRoutesOptions<TContext = void> {
|
|
516
|
-
/** Names the product in `deriveExecutionId` so retries land on the same
|
|
517
|
-
* substrate execution. */
|
|
518
|
-
projectId: string;
|
|
519
|
-
/** Authenticate + authorize the caller for a turn or a replay. The only
|
|
520
|
-
* product-supplied access step: session auth, thread/workspace access,
|
|
521
|
-
* seat/balance gates, rate limits all live here. */
|
|
522
|
-
authorize(args: ChatTurnAuthorizeArgs): Promise<ChatTurnAuthorization<TContext>>;
|
|
523
|
-
/** Finish the turn's context after `authorize` has admitted the caller and
|
|
524
|
-
* before the conversation loads or the lock is taken: resolve the profile,
|
|
525
|
-
* the model, anything that reads or writes product state. Keep `authorize`
|
|
526
|
-
* to admission (identity, access, rate limits, input checks) so a refusal
|
|
527
|
-
* stays fast and no write ever runs for a caller who is not admitted; on a
|
|
528
|
-
* progress-first stream this work runs inside the stream and can name its
|
|
529
|
-
* stages through `progress`. A refusal here is answered like a held lock:
|
|
530
|
-
* a plain response without the progress header, a `turn.response` event
|
|
531
|
-
* with it. Omit → nothing to prepare. */
|
|
532
|
-
prepareTurn?(args: ChatTurnPrepareArgs<TContext>): ChatTurnPrepareResult | Promise<ChatTurnPrepareResult>;
|
|
533
|
-
/** Start the work this turn will need, the moment `authorize` and `modelPolicy` have admitted it, so that work overlaps
|
|
534
|
-
* `prepareTurn`, the history read, the lock, the history recheck and the user-row insert instead of following them: the
|
|
535
|
-
* workspace box, the keys a producer mints, a session ensure. Keep what it starts on `args.context`; `produce` receives
|
|
536
|
-
* that object and awaits it.
|
|
537
|
-
*
|
|
538
|
-
* Admission has not finished, so the seam must start only work that the turn's refusal leaves harmless: a held lock
|
|
539
|
-
* (409), a changed history, a gate's answer or a throw all end the turn without `produce`, and the work already
|
|
540
|
-
* started runs on. Start nothing a second request for the same thread could not safely repeat, and nothing that
|
|
541
|
-
* writes product state.
|
|
542
|
-
*
|
|
543
|
-
* Not awaited, and it must return synchronously: start the work and return, never wait for it. It may return a release
|
|
544
|
-
* function; the route calls it once, only if the turn ends without `produce` (the chain above, or a throw before the
|
|
545
|
-
* engine took the turn), so a product frees credentials or leases the unused work holds. Once `produce` runs, the
|
|
546
|
-
* work belongs to `produce` and the route never calls the release. A throw is logged and the turn goes on without
|
|
547
|
-
* the early work. Omit → nothing starts early. */
|
|
548
|
-
afterAuthorize?(args: ChatTurnAfterAuthorizeArgs<TContext>): void | ChatTurnAfterAuthorizeRelease;
|
|
549
|
-
/** Product admission policy over the model a turn NAMES. When the request
|
|
550
|
-
* body carries a `model`, it is checked here — after `authorize`, before
|
|
551
|
-
* the conversation loads, the lock is taken, or any row is written — and a
|
|
552
|
-
* refusal answers 403 with the policy's reason. Fail-closed: a named model
|
|
553
|
-
* carrying no policy metadata is refused.
|
|
554
|
-
*
|
|
555
|
-
* This is half the enforcement. A body without `model` resolves to a
|
|
556
|
-
* product default inside `produce`, which this seam never sees — enforce
|
|
557
|
-
* that half at execution with `createSandboxChatProducer`'s `modelPolicy`
|
|
558
|
-
* (or `runWithModelFailover`'s `policy` on a custom producer), which also
|
|
559
|
-
* covers every fallback the turn could fail over to. Wire the SAME policy
|
|
560
|
-
* object to both. Omit → no policy check (today's behavior). */
|
|
561
|
-
modelPolicy?: ModelPolicy;
|
|
562
|
-
/** Thread/message persistence (`/chat-store`'s store or a product adapter). */
|
|
563
|
-
store: ChatTurnMessageStore;
|
|
564
|
-
/** Turn-event buffer (`createD1TurnEventStore(env.DB)` or `/turn-stream`'s
|
|
565
|
-
* `createDurableObjectTurnEventStore(env.TURN_STREAM_DO)` in production,
|
|
566
|
-
* `createMemoryTurnEventStore()` in tests). Wired by default — every turn
|
|
567
|
-
* is buffered and replayable. */
|
|
568
|
-
turnStore: TurnEventStore;
|
|
569
|
-
/** Build the turn's event stream. Sandbox lane: `streamSandboxPrompt(...)`
|
|
570
|
-
* wrapped in `createSandboxChatProducer`. Router/openai-compat lane: the
|
|
571
|
-
* product's own producer. May be async (box resolution). */
|
|
572
|
-
produce(args: ChatTurnProduceArgs<TContext>): ChatTurnRouteProducer | Promise<ChatTurnRouteProducer>;
|
|
573
|
-
/** Single-flight lock acquired before any side effect and released once when
|
|
574
|
-
* the turn settles (including short-circuit/throw). `/turn-stream`'s
|
|
575
|
-
* `createDurableTurnLock` is the shared DO-backed implementation. Omit →
|
|
576
|
-
* no lock. */
|
|
577
|
-
turnLock?: ChatTurnLock<TContext>;
|
|
578
|
-
/** Pre-turn readiness gate that can short-circuit with a product `Response`
|
|
579
|
-
* before the producer runs (the user row is already persisted). Runs after
|
|
580
|
-
* `turnLock.acquire`, before `beforeTurn`. Omit → always proceed.
|
|
581
|
-
*
|
|
582
|
-
* Settled shape (#227). What a consumer may depend on:
|
|
583
|
-
* - `args.userMessageId` is RESOLVED here — a string, or `null` when the
|
|
584
|
-
* insert was suppressed with nothing to reuse. (`turnLock.acquire` is the
|
|
585
|
-
* only seam that sees it `undefined`.)
|
|
586
|
-
* - `{proceed:false}` releases the lock and returns the product's `Response`
|
|
587
|
-
* verbatim: `beforeTurn` and `produce` never run, no assistant row is
|
|
588
|
-
* written, and the user row already inserted is KEPT — a real user turn
|
|
589
|
-
* whose assistant side is the gate's own response.
|
|
590
|
-
* - `{proceed:'handoff'}` releases the route-acquired lock, returns the
|
|
591
|
-
* product's accepted `Response`, and transfers execution and lifecycle
|
|
592
|
-
* ownership to the product's durable owner. The route runs no producer
|
|
593
|
-
* or lifecycle hook.
|
|
594
|
-
* - Always returning `{proceed:true}` is supported, not a misuse: the seam
|
|
595
|
-
* doubles as the one place that runs after the user row exists and before
|
|
596
|
-
* the producer, which is where per-turn analytics and readiness
|
|
597
|
-
* precomputation belong. A gate that never gates is a valid consumer. */
|
|
598
|
-
contextGate?(args: ChatTurnProduceArgs<TContext>): ChatTurnGateResult | Promise<ChatTurnGateResult>;
|
|
599
|
-
/** Observe the assembled producer input and optionally augment it (rewrite
|
|
600
|
-
* the prompt / prior messages) before the producer runs. Omit → no change.
|
|
601
|
-
*
|
|
602
|
-
* Settled shape (#227). BOTH return arms are contract:
|
|
603
|
-
* - a `ChatTurnInputPatch` shallow-merges over the route-assembled args, so
|
|
604
|
-
* an omitted field keeps the route's value;
|
|
605
|
-
* - `void` means "no patch" — and mutating `args.context` in place is the
|
|
606
|
-
* supported way to thread request-scoped state forward to `produce` /
|
|
607
|
-
* `lifecycle` / `onTurnComplete`, which all receive the same object.
|
|
608
|
-
*
|
|
609
|
-
* A throw propagates (the turn fails with the lock released). It runs BEFORE
|
|
610
|
-
* `lifecycle.onTurnStart`, so a throw here fires no terminal lifecycle hook —
|
|
611
|
-
* the span never opened. Telemetry for a failure in this seam belongs in the
|
|
612
|
-
* seam, not in `lifecycle`. */
|
|
613
|
-
beforeTurn?(args: ChatTurnProduceArgs<TContext>,
|
|
614
|
-
/** `span` is the `admission.before_turn` span: the parent for a product's own child spans. */
|
|
615
|
-
seam?: {
|
|
616
|
-
span: TurnSpan;
|
|
617
|
-
}): ChatTurnInputPatch | void | Promise<ChatTurnInputPatch | void>;
|
|
618
|
-
/** Deterministic run telemetry (start / complete / error) with identity and
|
|
619
|
-
* timing. Omit → no telemetry. */
|
|
620
|
-
lifecycle?: ChatTurnLifecycle<TContext>;
|
|
621
|
-
/** Keepalive injected while the producer is quiet. Omit → no keepalives. */
|
|
622
|
-
heartbeat?: ChatTurnHeartbeat;
|
|
623
|
-
/** Observe each event the producer emits, before the engine frames it and
|
|
624
|
-
* before any heartbeat injection (the raw sidecar-producer events, for
|
|
625
|
-
* telemetry). Never alters the stream; errors are swallowed. Distinct from
|
|
626
|
-
* `onEvent`, which sees the engine-framed stream incl. lifecycle envelopes.
|
|
627
|
-
*
|
|
628
|
-
* Settled shape (#227). What a consumer may depend on:
|
|
629
|
-
* - it sees EXACTLY the producer's own events — no engine lifecycle
|
|
630
|
-
* envelopes, and no injected keepalives (`heartbeat` wraps the stream
|
|
631
|
-
* downstream of this tap, so a synthetic event never reaches a trace);
|
|
632
|
-
* - a throw is caught and logged, never surfaced: a broken telemetry sink
|
|
633
|
-
* cannot fail a turn or truncate the client's stream;
|
|
634
|
-
* - it is an OBSERVER — the return value is ignored, and the event object
|
|
635
|
-
* continues downstream. Mutating it mutates the stream; don't.
|
|
636
|
-
*
|
|
637
|
-
* Takes `(event, context)` rather than one args object, matching both
|
|
638
|
-
* shipped consumers; see the module header on why it stays that way. */
|
|
639
|
-
onRawEvent?(event: ChatRouteEvent, context: TContext): void | Promise<void>;
|
|
640
|
-
/** Pre-persist transform of the final text (e.g. `/redact`'s `redactPII`).
|
|
641
|
-
* Live stream is never altered. */
|
|
642
|
-
transformFinalText?(text: string): string | Promise<string>;
|
|
643
|
-
/** Incremental persistence of the assistant row WHILE the turn streams
|
|
644
|
-
* (`./draft-persistence`), so a viewer arriving mid-run is served from
|
|
645
|
-
* durable storage instead of the streaming gateway's hot event buffer.
|
|
646
|
-
*
|
|
647
|
-
* This is what lets the gateway keep that hot buffer SHORT at scale: its
|
|
648
|
-
* Redis footprint is one sorted set per session refreshed on every push, so
|
|
649
|
-
* memory grows LINEARLY with `ttl x concurrent sessions`. Stretching the
|
|
650
|
-
* TTL to cover late viewers buys memory proportional to the increase and
|
|
651
|
-
* still serves nothing past the new horizon. The buffer stays a reconnect
|
|
652
|
-
* window; durable storage — kept at most one cadence interval stale by this
|
|
653
|
-
* option — is the history tier.
|
|
654
|
-
*
|
|
655
|
-
* Enabled by DEFAULT whenever `store.updateMessage` exists (every
|
|
656
|
-
* `/chat-store` consumer); a store without it keeps today's exact
|
|
657
|
-
* single-write behavior. Pass `false` to opt out, or an object to tune the
|
|
658
|
-
* cadence. Wiring it against a store that cannot patch rows throws at route
|
|
659
|
-
* construction rather than silently no-op'ing. */
|
|
660
|
-
incrementalPersistence?: false | DraftPersistenceTuning;
|
|
661
|
-
/** Deterministic durable row id for this turn's assistant message. Default
|
|
662
|
-
* `assistant:<executionId>` — already stable across retries because
|
|
663
|
-
* `deriveExecutionId` is. Override only if the product's message ids have a
|
|
664
|
-
* format constraint; it MUST stay deterministic per turn or a re-entered
|
|
665
|
-
* turn will duplicate its row instead of converging. */
|
|
666
|
-
draftMessageId?(args: {
|
|
667
|
-
identity: ChatTurnIdentity;
|
|
668
|
-
executionId: string;
|
|
669
|
-
threadId: string;
|
|
670
|
-
}): string;
|
|
671
|
-
/** Post-processing after a turn settles (billing, titles, audit). Fires with
|
|
672
|
-
* `failed:true` + `failureReason` when the turn carried a terminal error
|
|
673
|
-
* event (model 402 / rate-limit / server error) instead of a clean
|
|
674
|
-
* completion, so products skip the deduct and render an error row rather
|
|
675
|
-
* than billing an empty turn and marking it done. A turn that THROWS never
|
|
676
|
-
* reaches this hook (the engine skips it on a producer throw). Errors are
|
|
677
|
-
* swallowed by the engine — they never fail a streamed turn. */
|
|
678
|
-
onTurnComplete?(input: ChatTurnCompleteInput<TContext>): Promise<void>;
|
|
679
|
-
/** Per-event side channel (product broadcast). The turn-buffer tap is
|
|
680
|
-
* already wired; this runs in addition. */
|
|
681
|
-
onEvent?(event: {
|
|
682
|
-
type: string;
|
|
683
|
-
data?: Record<string, unknown>;
|
|
684
|
-
}, context: TContext): void | Promise<void>;
|
|
685
|
-
/** Trace flush handed to `waitUntil` (OTLP export). */
|
|
686
|
-
traceFlush?(context: TContext): Promise<void>;
|
|
687
|
-
/**
|
|
688
|
-
* Where each finished turn's trace goes. On by default: omit it and every turn goes to Tangle Intelligence under
|
|
689
|
-
* `projectId` (`createIntelligenceTurnTraceSink`); pass `{ sink, labels }` to send it elsewhere or label it.
|
|
690
|
-
* The route always records the turn's trace (`ChatTurnProduceArgs.trace`), reports its summary to `lifecycle`, and
|
|
691
|
-
* writes one `agent_app_turn_trace` log line per turn (first text, coverage, time per kind); this sends the spans on.
|
|
692
|
-
* The sink runs under `waitUntil` after the lifecycle hooks and after the turn lock is released, and its failure never
|
|
693
|
-
* fails a turn. A turn handed to a durable owner (`handoffCompletion`) is exported when this request's live
|
|
694
|
-
* projection ends, failed only when the projection saw an error. `false` is the only opt-out, and
|
|
695
|
-
* `agent-app-signoff defaults` fails it until the app's `signoff.config.mjs` gives the reason.
|
|
696
|
-
*/
|
|
697
|
-
turnTrace?: ChatTurnTraceOptions<TContext> | false;
|
|
698
|
-
/** Compose the interaction-answer endpoints (`/interactions`). Omit when the
|
|
699
|
-
* product has no sidecar ask channel. */
|
|
700
|
-
interactions?: InteractionAnswerRouteOptions;
|
|
701
|
-
/** Byte budget for inline prompt parts. Default `INLINE_PARTS_MAX_BYTES`. */
|
|
702
|
-
maxInlinePartBytes?: number;
|
|
703
|
-
/** Per-flush coalescer for the turn buffer. Default `coalesceDeltas` (this
|
|
704
|
-
* assembly streams the client vocabulary's `{type:'text'|'reasoning',
|
|
705
|
-
* text}` lines, which it merges). A producer streaming raw
|
|
706
|
-
* `message.part.updated` events passes `coalesceChatStreamEvents`. */
|
|
707
|
-
coalesceTurnEvents?: (events: unknown[]) => unknown[];
|
|
708
|
-
replay?: {
|
|
709
|
-
pollMs?: number;
|
|
710
|
-
timeoutMs?: number;
|
|
711
|
-
};
|
|
712
|
-
/** Text for the route's own stages on a progress-first stream (`./turn-progress`).
|
|
713
|
-
* Omitted stages keep `TURN_ROUTE_PHASE_MESSAGES`. */
|
|
714
|
-
progressMessages?: Partial<Record<TurnRoutePhase, string>>;
|
|
715
|
-
/** Write and stream the turn's intent line ({@link ChatTurnIntentLine}). Omit → no line. */
|
|
716
|
-
intentLine?: ChatTurnIntentLine<TContext>;
|
|
717
|
-
log?: (message: string, meta?: Record<string, unknown>) => void;
|
|
718
|
-
}
|
|
719
|
-
/** What `intentLine.generate` receives: the admitted turn's message and the thread's last few turns. */
|
|
720
|
-
export interface ChatTurnIntentLineArgs<TContext> {
|
|
721
|
-
content: string;
|
|
722
|
-
/** The thread's last turns before this one, oldest first (at most {@link INTENT_LINE_HISTORY_MESSAGES}). */
|
|
723
|
-
history: ReadonlyArray<{
|
|
724
|
-
role: 'user' | 'assistant' | 'system' | 'tool';
|
|
725
|
-
content: string;
|
|
726
|
-
}>;
|
|
727
|
-
tenantId: string;
|
|
728
|
-
userId: string;
|
|
729
|
-
threadId: string;
|
|
730
|
-
context: TContext;
|
|
731
|
-
/** Aborted when the line is no longer wanted (its deadline passed). */
|
|
732
|
-
signal: AbortSignal;
|
|
733
|
-
}
|
|
734
|
-
/**
|
|
735
|
-
* The intent line: one plain sentence, written by a fast model call the moment
|
|
736
|
-
* a turn is admitted, saying what the agent is about to do. It reaches a
|
|
737
|
-
* progress-first client as a {@link TURN_INTENT_EVENT} while the harness boots,
|
|
738
|
-
* and the turn's first answer text replaces it. It narrates intent and must
|
|
739
|
-
* never answer or act. It fails open: a line later than `timeoutMs`, an error,
|
|
740
|
-
* or an empty answer shows nothing.
|
|
741
|
-
*/
|
|
742
|
-
export interface ChatTurnIntentLine<TContext> {
|
|
743
|
-
generate(args: ChatTurnIntentLineArgs<TContext>): Promise<string | null>;
|
|
744
|
-
/** Longest wait for the line. Default {@link INTENT_LINE_TIMEOUT_MS}. */
|
|
745
|
-
timeoutMs?: number;
|
|
746
|
-
}
|
|
747
|
-
/** A line slower than this shows nothing. */
|
|
748
|
-
export declare const INTENT_LINE_TIMEOUT_MS = 1500;
|
|
749
|
-
/** Turns of the thread the line is written from. */
|
|
750
|
-
export declare const INTENT_LINE_HISTORY_MESSAGES = 6;
|
|
751
|
-
/** Longest line kept; anything longer is cut. */
|
|
752
|
-
export declare const INTENT_LINE_MAX_CHARS = 240;
|
|
753
|
-
/** Define routes to run, replay, and list running chat turns with streaming and reconnect support */
|
|
754
|
-
export interface ChatTurnRoutes {
|
|
755
|
-
/** POST — run one turn, streaming NDJSON. First line is
|
|
756
|
-
* `{type:'turn', turnId}` (the replay handle); the rest is the engine's
|
|
757
|
-
* event protocol. Pass the platform's `waitUntil` so the turn keeps
|
|
758
|
-
* running (and buffering) after a client disconnect. A request with
|
|
759
|
-
* `TURN_PROGRESS_HEADER` gets a progress-first stream once it is
|
|
760
|
-
* authorized (`./turn-progress`). */
|
|
761
|
-
turn(request: Request, ctx?: ChatTurnRequestContext): Promise<Response>;
|
|
762
|
-
/** GET — replay a buffered turn from `?fromSeq=` (0 = everything), then
|
|
763
|
-
* follow it live until it completes. */
|
|
764
|
-
replay(request: Request, params: {
|
|
765
|
-
turnId: string;
|
|
766
|
-
}): Promise<Response>;
|
|
767
|
-
/** GET `?threadId=` — the reconnect-discovery endpoint: the turn ids still
|
|
768
|
-
* running on a thread, so a client that reloaded mid-turn can re-attach to
|
|
769
|
-
* the live stream via {@link replay} instead of losing it. Returns `[]` when
|
|
770
|
-
* the turn store cannot enumerate running turns (`listRunning` unimplemented). */
|
|
771
|
-
running(request: Request): Promise<Response>;
|
|
772
|
-
/** list/answer endpoints from `/interactions`; null when not configured. */
|
|
773
|
-
interactions: InteractionAnswerRoute | null;
|
|
774
|
-
}
|
|
53
|
+
import { type ChatTurnRoutes, type CreateChatTurnRoutesOptions } from './turn-route-contracts';
|
|
54
|
+
export * from './turn-route-contracts';
|
|
775
55
|
/** Build chat turn routes to handle and validate incoming chat requests with optional logging */
|
|
776
56
|
export declare function createChatTurnRoutes<TContext = void>(options: CreateChatTurnRoutesOptions<TContext>): ChatTurnRoutes;
|
|
777
|
-
export {};
|