index.ts · Source

index.tspackages/ai/src/providers/index.tsraw ← providers38,043 B← Back to the app
1/**
2 * @factory/ai — provider adapters.
3 *
4 *  - `OpenAIAdapter` / `OssAdapter` / `CustomAdapter` — one OpenAI-compatible
5 *    adapter (baseUrl + optional Bearer key; OSS dimension discovered at
6 *    first use)
7 *  - `AnthropicAdapter` — claude family; **no embed** (gateway routes embed
8 *    to the fallback provider)
9 *  - `GoogleAdapter` — gemini family (`:streamGenerateContent?alt=sse`)
10 *  - `MockProvider` — deterministic, dependency-free, for the CI capability
11 *    suite (TASK-0121: "identical assertion set runs against the mock
12 *    provider always, and against the real provider when AI_REAL_TEST=1")
13 */
14 
15export { AnthropicAdapter, type AnthropicOptions } from "./anthropic.js";
16export { GoogleAdapter, type GoogleOptions } from "./google.js";
17export {
18  CustomAdapter,
19  OpenAIAdapter,
20  OpenAICompatibleAdapter,
21  OssAdapter,
22  type OpenAICompatibleOptions,
23} from "./openai-compatible.js";
24export { abortError };
25import { abortError } from "./http.js";
26import {
27  ProviderHttpError,
28  httpJson,
29  isRetryableStatus,
30  sseData,
31  type HttpOptions,
32} from "./http.js";
33import { mapColumnsToProperties, parseMarkdownTable } from "../schemas/database.js";
34 
35/**
36 * A deterministic in-process provider for unit tests and the CI capability
37 * suite: echoes structured responses, honors the chat chunk protocol
38 * (text deltas → tool calls → final usage), and counts "tokens" as
39 * characters/4 so usage assertions are exact.
40 */
41export class MockProvider {
42  readonly id: "openai" | "anthropic" | "google" | "oss" | "custom";
43  /** When > 0, `chat` throws a retryable HTTP `failStatus` for the next `failTimes` calls. */
44  failTimes = 0;
45  /** HTTP status the failures carry (default 429; use 500 for the 5xx path). */
46  failStatus = 429;
47  calls = 0;
48  /**
49   * TASK-0122: ms to wait BETWEEN deltas (0 = no pacing). Tests that assert
50   * mid-stream cancellation set this so the consumer's abort lands between
51   * deltas; the wait races `req.signal` and aborts throw `AbortError`.
52   */
53  deltaDelayMs = 0;
54  /**
55   * TASK-0122 (E2E): when > 0, `chat` emits exactly this many deltas and
56   * then throws a retryable `failStatus` — a deterministic MID-stream
57   * provider outage. The gateway never re-streams after partial output
58   * (would duplicate content), so the consumer sees the error in-band:
59   * exactly ONE user request fails, the next (the UI's Retry button) is a
60   * fresh call and succeeds. 0 = disabled (the default).
61   */
62  failAfterDeltas = 0;
63  /** Embedding dimension the mock reports. */
64  readonly dimension: number;
65  private callsSeen: { model: string }[] = [];
66 
67  constructor(id: "openai" | "anthropic" | "google" | "oss" | "custom" = "openai", dimension = 8) {
68    this.id = id;
69    this.dimension = dimension;
70  }
71 
72  async models(): Promise<
73    Array<{ id: string; provider: "openai" | "anthropic" | "google" | "oss" | "custom"; kind: "chat" | "embed" | "chat+embed"; contextWindow: number; maxOutput: number; toolCalls: boolean; vision: boolean; pricePer1kIn: number; pricePer1kOut: number; dimension: number }>
74  > {
75    return [
76      {
77        id: "mock-chat",
78        provider: this.id,
79        kind: "chat",
80        contextWindow: 32_000,
81        maxOutput: 4_096,
82        toolCalls: true,
83        vision: false,
84        pricePer1kIn: 0,
85        pricePer1kOut: 0,
86        dimension: 0,
87      },
88    ];
89  }
90 
91  async *chat(req: {
92    model: string;
93    messages: Array<{ role: string; content: unknown }>;
94    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
95    maxTokens?: number;
96    metadata?: Record<string, string>;
97    signal?: AbortSignal;
98  }): AsyncIterable<{
99    delta?: string;
100    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
101    usage?: { in: number; out: number; total: number };
102    finishReason?: "stop" | "tool_calls" | "length" | "error";
103    done: boolean;
104  }> {
105    this.calls += 1;
106    this.callsSeen.push({ model: req.model });
107    if (this.failTimes > 0) {
108      this.failTimes -= 1;
109      const { ProviderHttpError } = await import("./http.js");
110      throw new ProviderHttpError(this.failStatus, "mock provider failure", this.failStatus === 429 || this.failStatus >= 500);
111    }
112    // TASK-0123: deterministic WRITING mode. The app layer opts in via
113    // `metadata.mode = "writing"` (+ `action`). The "model" parses the
114    // `[BLOCK <id>]` markers the prompt builder emits (so the unit/E2E path
115    // exercises the REAL prompt → provider contract, not a side channel) and
116    // answers with ONE `toolCallDelta` carrying the `generateBlocks` result:
117    // a deterministic per-block transform of the block's own text.
118    if (req.metadata?.mode === "writing") {
119      yield* this.writingChat(req);
120      return;
121    }
122    // TASK-0124: deterministic DATABASE-GENERATION mode. The app layer opts in
123    // via `metadata.mode = "database"` (+ `action` ∈ generate|extract|formula,
124    // and, for generate, `prompt`; for extract, `columns`; for formula,
125    // `properties`). The "model" parses the markers the prompt builder emits
126    // and answers with ONE `toolCallDelta` carrying a VALID, deterministic
127    // tool call — so the unit/E2E path exercises the REAL prompt → provider
128    // → server-validation contract. A `metadata.hostile` seam makes it emit a
129    // deliberately INVALID call (to exercise the retry-once → 422 path).
130    if (req.metadata?.mode === "database") {
131      yield* this.databaseChat(req);
132      return;
133    }
134    // TASK-0125: deterministic RAG mode. The app layer opts in via
135    // `metadata.mode = "rag"` and puts the retrieved, numbered context in the
136    // user message as `[n] Source: <label>` blocks (the REAL prompt → provider
137    // contract — a real model would answer from that context with inline
138    // `[n]` citations; the mock deterministically cites the FIRST source so
139    // tests can assert the answer carries the seeded fact + a `[n]` marker
140    // that the server-side citation builder matches to the `sources` frame).
141    if (req.metadata?.mode === "rag") {
142      yield* this.ragChat(req);
143      return;
144    }
145    // TASK-0126: deterministic PAGE-GENERATION mode. The app layer opts in via
146    // `metadata.mode = "generate"`. The "model" answers with ONE `toolCallDelta`
147    // carrying the canonical "product launch plan" PLAN (a ref-based structured
148    // tool list) — so the unit/integration/E2E path exercises the REAL prompt →
149    // provider → server-validation → executor contract. A `metadata.generateFailStep`
150    // seam (armed via the internal test seam) makes it emit a plan whose Nth step
151    // the executor CANNOT run (an unknown ref) → the rollback-on-failure path.
152    if (req.metadata?.mode === "generate") {
153      yield* this.generateChat(req);
154      return;
155    }
156    // T-172…T-175 (A-010): deterministic ASSISTANT mode. The app layer opts in
157    // via `metadata.mode = "assistant"` (+ `action`). The "model" parses the
158    // context the prompt builder emitted (numbered sources / `[id]` candidates
159    // / the notes text) and answers with ONE `toolCallDelta` carrying a VALID,
160    // deterministic tool call — so the unit/integration path exercises the
161    // REAL prompt → provider → server-validation contract. A `metadata.hostile`
162    // seam makes it emit a deliberately INVALID call (retry-once → 422 path).
163    if (req.metadata?.mode === "assistant") {
164      yield* this.assistantChat(req);
165      return;
166    }
167    // deterministic echo: reply with the last user message (first 40 chars).
168    // Streamed as one delta per word (deterministic; ≥3 chunks for a normal
169    // sentence) so streaming consumers (TASK-0122 SSE / the E2E panel)
170    // observe real incremental updates — the concatenation is identical to
171    // the old 2-chunk split.
172    const lastUser = [...req.messages].reverse().find((m) => m.role === "user");
173    const text = typeof lastUser?.content === "string" ? lastUser.content.slice(0, 40) : "ok";
174    // TASK-0122: when the caller sent a system message (the context
175    // assembler), append its tail to the echo so tests can assert what the
176    // model actually SAW (context inclusion / permission-drop verification).
177    const sysMsg = [...req.messages].filter((m) => m.role === "system").pop();
178    const sysTail =
179      sysMsg && typeof sysMsg.content === "string" ? ` [SYS:${sysMsg.content.slice(-200)}]` : "";
180    const words = text.length === 0 ? ["ok"] : text.split(" ");
181    const pace = async (): Promise<void> => {
182      if (this.deltaDelayMs <= 0) return;
183      if (req.signal?.aborted) throw abortError();
184      await new Promise<void>((resolve) => {
185        const timer = setTimeout(resolve, this.deltaDelayMs);
186        const onAbort = (): void => {
187          clearTimeout(timer);
188          resolve();
189        };
190        req.signal?.addEventListener("abort", onAbort, { once: true });
191        // (the timer's cleanup is harmless — it fires at most once after
192        // resolve, on an already-settled promise)
193      });
194      if (req.signal?.aborted) throw abortError();
195    };
196    for (let i = 0; i < words.length; i++) {
197      await pace();
198      yield { delta: (i > 0 ? " " : "") + words[i]!, done: false };
199      // TASK-0122 (E2E): mid-stream provider outage — after exactly
200      // `failAfterDeltas` deltas the stream dies with a retryable status.
201      // The gateway never re-streams partial output, so the consumer sees
202      // the failure in-band (SSE `error` delta) instead of an auto-retry.
203      if (this.failAfterDeltas > 0) {
204        this.failAfterDeltas -= 1;
205        if (this.failAfterDeltas === 0) {
206          throw new ProviderHttpError(
207            this.failStatus,
208            "mock provider mid-stream failure",
209            this.failStatus === 429 || this.failStatus >= 500,
210          );
211        }
212      }
213    }
214    // Arming is single-shot and MUST fire even for short answers: if the
215    // word stream ended before the count was consumed, fail right here
216    // (still mid-stream — the usage/done chunk never goes out).
217    if (this.failAfterDeltas > 0) {
218      this.failAfterDeltas = 0;
219      throw new ProviderHttpError(
220        this.failStatus,
221        "mock provider mid-stream failure",
222        this.failStatus === 429 || this.failStatus >= 500,
223      );
224    }
225    if (sysTail) {
226      await pace();
227      yield { delta: sysTail, done: false };
228    }
229    if (req.tools && req.tools.length > 0) {
230      const first = req.tools[0]!;
231      yield {
232        toolCallDelta: { id: "mock_call_0", name: first.name, arguments: { echoed: text } },
233        done: false,
234      };
235      yield {
236        usage: { in: Math.ceil(text.length / 4), out: Math.ceil(text.length / 4), total: Math.ceil(text.length / 2) },
237        finishReason: "tool_calls",
238        done: true,
239      };
240      return;
241    }
242    yield {
243      usage: { in: Math.ceil(text.length / 4), out: Math.ceil(text.length / 4), total: Math.ceil(text.length / 2) },
244      finishReason: "stop",
245      done: true,
246    };
247  }
248 
249  /**
250   * TASK-0123 — deterministic writing mode (`metadata.mode = "writing"`).
251   *
252   * The app layer (TASK-0123 `ai-writing.service`) sends the selected +
253   * context blocks as delimited `[SELECTED <id>]…[/SELECTED <id>]` /
254   * `[CONTEXT <id>]…[/CONTEXT <id>]` markers in the user message and opts in
255   * with `metadata: { mode: "writing", action, language? }`. The mock plays
256   * the "model" end of that REAL contract (no side channel): it parses the
257   * markers and answers with ONE tool call (`generateBlocks`) whose
258   * `blocks` are deterministic per-action transforms of each block's own
259   * text:
260   *
261   *   summarize → `Summarized: <first 80 chars>`   (per block)
262   *   rewrite   → `Rewritten: <text>`
263   *   improve   → `Improved: <text>`
264   *   translate → `Translated to <language>: <text>`
265   *
266   * `metadata.forceUnknownId` appends a blockId the prompt never contained —
267   * the deterministic seam for the server-side "unknown ID → drop + note"
268   * validation (integration). The TASK-0122 mid-stream-outage arming
269   * (`failAfterDeltas`) is honored: an armed writing call dies before the
270   * tool call goes out (still mid-stream — no usage/done frame leaves).
271   */
272  private async *writingChat(req: {
273    messages: Array<{ role: string; content: unknown }>;
274    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
275    metadata?: Record<string, string>;
276    signal?: AbortSignal;
277  }): AsyncIterable<{
278    delta?: string;
279    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
280    usage?: { in: number; out: number; total: number };
281    finishReason?: "stop" | "tool_calls" | "length" | "error";
282    done: boolean;
283  }> {
284    const action = req.metadata?.action ?? "rewrite";
285    const language = req.metadata?.language;
286    const blocks = parseWritingBlocks(req.messages);
287    const totalChars = blocks.reduce((n, b) => n + b.text.length, 0);
288    const usage = { in: Math.ceil(totalChars / 4), out: Math.ceil(totalChars / 4), total: Math.ceil(totalChars / 2) };
289 
290    if (this.deltaDelayMs > 0) {
291      await new Promise<void>((resolve) => setTimeout(resolve, this.deltaDelayMs));
292    }
293    if (req.signal?.aborted) throw abortError();
294    if (this.failAfterDeltas > 0) {
295      this.failAfterDeltas = 0;
296      throw new ProviderHttpError(
297        this.failStatus,
298        "mock provider mid-stream failure",
299        this.failStatus === 429 || this.failStatus >= 500,
300      );
301    }
302 
303    const toolName = req.tools?.[0]?.name ?? "generateBlocks";
304    const out: Array<{ blockId: string; newText: string }> = blocks.map((b) => ({
305      blockId: b.id,
306      newText: writingTransform(action, b.text, language),
307    }));
308    const forceUnknown = req.metadata?.forceUnknownId;
309    if (forceUnknown) out.push({ blockId: forceUnknown, newText: "Injected unknown block id (mock seam)." });
310 
311    yield {
312      toolCallDelta: { id: "mock_writing_0", name: toolName, arguments: { blocks: out } },
313      done: false,
314    };
315    yield { usage, finishReason: "tool_calls", done: true };
316  }
317 
318  /**
319   * TASK-0125 — deterministic RAG mode (`metadata.mode = "rag"`).
320   *
321   * The app layer (TASK-0125 `rag.service`) sends the retrieved, numbered
322   * context as `[n] Source: <label>\n<chunk text>` blocks followed by a
323   * `Question: <q>` line, and opts in with `metadata: { mode: "rag" }`. The
324   * mock plays the "model" end of that REAL contract: it parses the first
325   * source block and streams a deterministic, CITED answer —
326   * `According to [1] (<label>): <first 200 chars of the chunk text>` — so
327   * tests can assert the answer contains the seeded fact, the `[n]` marker,
328   * and the source label. No context → a deterministic "no results" answer
329   * (the app layer normally short-circuits before the chat call; this keeps
330   * the provider total even if it does not).
331   */
332  private async *ragChat(req: {
333    messages: Array<{ role: string; content: unknown }>;
334    metadata?: Record<string, string>;
335    signal?: AbortSignal;
336  }): AsyncIterable<{
337    delta?: string;
338    usage?: { in: number; out: number; total: number };
339    finishReason?: "stop" | "tool_calls" | "length" | "error";
340    done: boolean;
341  }> {
342    const lastUser = [...req.messages].reverse().find((m) => m.role === "user");
343    const userText = typeof lastUser?.content === "string" ? lastUser.content : "";
344    const first = parseRagSource(userText);
345    const answer = first
346      ? `According to [${first.n}] (${first.label}): ${first.text.slice(0, 200)}`
347      : "I could not find any workspace content that answers this question. Try different wording.";
348    const usage = {
349      in: Math.ceil(userText.length / 4),
350      out: Math.ceil(answer.length / 4),
351      total: Math.ceil((userText.length + answer.length) / 4),
352    };
353    const words = answer.split(" ");
354    for (let i = 0; i < words.length; i++) {
355      if (this.deltaDelayMs > 0) {
356        await new Promise<void>((resolve) => setTimeout(resolve, this.deltaDelayMs));
357      }
358      if (req.signal?.aborted) throw abortError();
359      yield { delta: (i > 0 ? " " : "") + words[i]!, done: false };
360    }
361    yield { usage, finishReason: "stop", done: true };
362  }
363 
364  async embed(req: { model: string; texts: string[]; metadata?: Record<string, string> }): Promise<{
365    model: string;
366    dimension: number;
367    vectors: number[][];
368    usage: { tokens: number };
369    latencyMs: number;
370    provider: "openai" | "anthropic" | "google" | "oss" | "custom";
371  }> {
372    this.calls += 1;
373    if (this.id === "anthropic") {
374      const { ProviderHttpError } = await import("./http.js");
375      throw new ProviderHttpError(501, "Anthropic has no embedding API", false);
376    }
377    const vectors = req.texts.map((t) => {
378      const v = new Array<number>(this.dimension).fill(0);
379      v[0] = Math.min(1, t.length / 100);
380      if (this.dimension > 1) v[1] = 0.5;
381      return v;
382    });
383    return {
384      model: req.model,
385      dimension: this.dimension,
386      vectors,
387      usage: { tokens: Math.ceil(req.texts.join(" ").length / 4) },
388      latencyMs: 0,
389      provider: this.id,
390    };
391  }
392 
393  async health(): Promise<{ ok: boolean; latencyMs: number }> {
394    return { ok: true, latencyMs: 0 };
395  }
396 
397  get callsSeenModels(): string[] {
398    return this.callsSeen.map((c) => c.model);
399  }
400 
401  /**
402   * TASK-0124 — deterministic database-generation mode
403   * (`metadata.mode = "database"`). See the selection point in `chat`. The
404   * "model" parses the markers the prompt builder emits into the USER message
405   * (so the unit/E2E path exercises the REAL prompt → provider → server
406   * validation contract, not a metadata side-channel) and answers with ONE
407   * `toolCallDelta` carrying a deterministic tool call:
408   *   - generate → `createDatabase` (title/properties derived from the prompt)
409   *   - extract  → `insertRecords`  (parses `[PROP <id>]` + the `[ROWS]` table)
410   *   - formula  → `generateFormula` (parses `[PROP <name>] <type>` lines)
411   * `metadata.hostile = "1"` (armed via the internal test seam) makes it emit a
412   * deliberately INVALID call → the retry-once → 422 path.
413   */
414  private async *databaseChat(req: {
415    messages: Array<{ role: string; content: unknown }>;
416    metadata?: Record<string, string>;
417    signal?: AbortSignal;
418  }): AsyncIterable<{
419    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
420    usage?: { in: number; out: number; total: number };
421    finishReason?: "stop" | "tool_calls" | "length" | "error";
422    done: boolean;
423  }> {
424    if (this.deltaDelayMs > 0) await new Promise<void>((r) => setTimeout(r, this.deltaDelayMs));
425    if (req.signal?.aborted) throw abortError();
426 
427    const userMsg = [...req.messages].reverse().find((m) => m.role === "user");
428    const text = typeof userMsg?.content === "string" ? userMsg.content : "";
429    const action = req.metadata?.action ?? "generate";
430    // Hostile is ARMed PER ACTION (the seam sets which feature is hostile).
431    // The arming persists across the two calls of a single retry-once request
432    // (generate/extract/formula each call twice), so BOTH attempts are invalid
433    // → the true 422 path. It is cleared between tests via the seam/reset.
434    const armedAction = req.metadata?.hostile; // "generate" | "extract" | "formula"
435    const hostile = armedAction === action;
436 
437    let toolName = "createDatabase";
438    let args: Record<string, unknown> = {};
439    if (action === "extract") {
440      toolName = "insertRecords";
441      args = mockDatabaseExtract(text, hostile);
442    } else if (action === "formula") {
443      toolName = "generateFormula";
444      args = mockDatabaseFormula(text, hostile);
445    } else {
446      toolName = "createDatabase";
447      args = mockDatabaseGenerate(text, hostile);
448    }
449 
450    yield { toolCallDelta: { id: "mock_db_0", name: toolName, arguments: args }, done: false };
451    const chars = JSON.stringify(args).length;
452    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
453  }
454 
455  /**
456   * TASK-0126 — deterministic page-generation mode (`metadata.mode =
457   * "generate"`). The "model" answers with ONE `toolCallDelta` carrying the
458   * canonical PLAN — a ref-based structured tool list for the "product launch
459   * plan" (a page with section headings, then a Tasks database with a
460   * status select + due date + 2 sample records). The plan is DETERMINISTIC
461   * (same prompt → same plan) so the unit/integration/E2E path exercises the
462   * REAL prompt → provider → server-validation → executor contract.
463   *
464   * `metadata.generateFailStep` (a 1-based step number, armed via the
465   * internal test seam) makes the mock emit a plan whose Nth step references a
466   * ref that does not exist → the executor's step fails → the rollback path.
467   * (The plan is still schema-valid; the FAILURE is a run-time unknown ref,
468   * which is the deterministic way to force a step to fail.)
469   */
470  private async *generateChat(req: {
471    messages: Array<{ role: string; content: unknown }>;
472    metadata?: Record<string, string>;
473    signal?: AbortSignal;
474  }): AsyncIterable<{
475    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
476    usage?: { in: number; out: number; total: number };
477    finishReason?: "stop" | "tool_calls" | "length" | "error";
478    done: boolean;
479  }> {
480    // Signal-aware "plan latency": `generateSlowMs` (armed via the internal
481    // test seam) makes the plan fetch outlast the service's total timeout so
482    // the timeout watchdog fires; the wait RESOLVES (not hangs) on abort and
483    // the post-wait check then throws, so the test is fast (≈ timeoutMs).
484    const slowMs = req.metadata?.generateSlowMs ? Number.parseInt(req.metadata.generateSlowMs, 10) : this.deltaDelayMs;
485    if (slowMs > 0) {
486      const sig = req.signal;
487      if (sig?.aborted) throw abortError();
488      await new Promise<void>((resolve) => {
489        const timer = setTimeout(resolve, slowMs);
490        sig?.addEventListener("abort", () => {
491          clearTimeout(timer);
492          resolve();
493        }, { once: true });
494      });
495      if (sig?.aborted) throw abortError();
496    }
497 
498    const userMsg = [...req.messages].reverse().find((m) => m.role === "user");
499    const text = typeof userMsg?.content === "string" ? userMsg.content : "";
500    const failStep = req.metadata?.generateFailStep ? Number.parseInt(req.metadata.generateFailStep, 10) : 0;
501 
502    const plan = mockGeneratePlan(text, failStep);
503    const args = JSON.parse(JSON.stringify(plan)) as Record<string, unknown>;
504    yield { toolCallDelta: { id: "mock_gen_0", name: "generatePlan", arguments: args }, done: false };
505    const chars = JSON.stringify(args).length;
506    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
507  }
508 
509  /**
510   * T-172…T-175 — deterministic ASSISTANT mode (`metadata.mode = "assistant"`).
511   *
512   * Parses the markers the app layer's prompt builder emits (numbered sources
513   * `[n] label`, candidate pages `[<id>] title`, the raw notes text) and
514   * answers with ONE `toolCallDelta` carrying a VALID, deterministic tool call
515   * — so the integration path exercises the REAL prompt → provider →
516   * server-validation contract (exactly the writing/database/rag/generate
517   * pattern). `metadata.hostile` (armed via the internal seam) makes it emit a
518   * deliberately INVALID call → the "validate → retry once → 422, no write"
519   * path.
520   */
521  private async *assistantChat(req: {
522    messages: Array<{ role: string; content: unknown }>;
523    tools?: Array<{ name: string; description: string; parameters: Record<string, unknown> }>;
524    metadata?: Record<string, string>;
525    signal?: AbortSignal;
526  }): AsyncIterable<{
527    toolCallDelta?: { id: string; name: string; arguments: Record<string, unknown> };
528    usage?: { in: number; out: number; total: number };
529    finishReason?: "stop" | "tool_calls" | "length" | "error";
530    done: boolean;
531  }> {
532    if (req.signal?.aborted) throw abortError();
533    const user = [...req.messages].reverse().find((m) => m.role === "user");
534    const text = typeof user?.content === "string" ? user.content : "";
535    const action = req.metadata?.action ?? "extract-actions";
536    const toolName = req.tools?.[0]?.name ?? "extractActionItems";
537 
538    // The deterministic "model" output per capability.
539    let args: Record<string, unknown>;
540    if (req.metadata?.hostile) {
541      // Deliberately INVALID (fails the app layer's zod validation) → the
542      // retry-once path emits this again → 422, no write.
543      args = { invalid: "hostile mock tool call" };
544    } else if (action === "extract-actions") {
545      // The notes' bullet lines (the prompt puts the raw text under a header):
546      // every "- …" / "* …" / "1. …" line becomes a task.
547      const lines = text
548        .split("\n")
549        .map((l) => l.match(/^\s*(?:[-*]|\d+[.)])\s+(.+)$/)?.[1]?.trim())
550        .filter((l): l is string => Boolean(l && l.length > 1 && l.length <= 200));
551      args = { actions: lines.slice(0, 10).map((l) => ({ title: l.replace(/\.$/, "") })) };
552    } else if (action === "generate-faqs") {
553      // Numbered sources → one FAQ per source, citing it (the RAG-style [n]
554      // marker the app layer validates against the retrieved set).
555      const sources = [...text.matchAll(/^\[(\d+)\]\s+(.+)$/gm)];
556      const faqs = sources.slice(0, 15).map((m) => ({
557        question: `About ${m[2]!.trim()}?`,
558        answer: `Deterministic answer (per [${m[1]}]).`,
559      }));
560      args = {
561        title: `FAQ: ${sources.length || 1} source${sources.length === 1 ? "" : "s"}`,
562        faqs: faqs.length ? faqs : [{ question: "Anything?", answer: "Deterministic answer (per [1])." }],
563      };
564    } else if (action === "find-duplicates") {
565      // Candidate ids `[<id>] title` — the mock groups them 2 at a time
566      // (the app layer filters ids to the permission-filtered set).
567      const ids = [...text.matchAll(/^\[([^\]\s]+)\]\s+(.+)$/gm)].map((m) => m[1]!);
568      const groups: Array<{ pageIds: string[]; similarity: number; reason: string }> = [];
569      for (let i = 0; i + 1 < ids.length; i += 2) {
570        groups.push({ pageIds: [ids[i]!, ids[i + 1]!], similarity: 0.9, reason: "Overlapping content (mock)." });
571      }
572      // Hostile-forgery seam (separate from `hostile`): also emit an id the
573      // prompt never contained → the server's no-fabricated-refs drop path.
574      if (req.metadata?.forgeId) groups.push({ pageIds: [ids[0] ?? "p1", "forged-id"], similarity: 0.8, reason: "Forged id (mock seam)." });
575      args = { groups };
576    } else if (action === "find-stale") {
577      // Flag the FIRST two candidates (deterministic subset).
578      const ids = [...text.matchAll(/^\[([^\]\s]+)\]\s+(.+)$/gm)].map((m) => m[1]!);
579      args = { pages: ids.slice(0, 2).map((id) => ({ pageId: id, reason: "Contains outdated dates (mock)." })) };
580    } else {
581      // suggest-metadata: derive from the page's own title.
582      const titleLine = text.match(/^Page title:\n(.+)$/m)?.[1]?.trim() ?? "Untitled";
583      args = { title: titleLine ? `Revised: ${titleLine}`.slice(0, 200) : "Revised page", description: "Deterministic description grounded in the page (mock)." };
584    }
585 
586    const serialized = JSON.stringify(args);
587    yield { toolCallDelta: { id: "mock_assistant_0", name: toolName, arguments: JSON.parse(serialized) }, done: false };
588    const chars = serialized.length;
589    yield { usage: { in: Math.ceil(chars / 4), out: Math.ceil(chars / 4), total: Math.ceil(chars / 2) }, finishReason: "tool_calls", done: true };
590  }
591}
592 
593// ── TASK-0126 page-generation mode helpers ───────────────────────────────────
594 
595/**
596 * The canonical "product launch plan" PLAN the mock emits. Ref-based (see
597 * `schemas/generate.ts`): the root page is created first (no `ref` → the
598 * executor's root), its section headings are inserted under it, and a Tasks
599 * database is created under the root with a status select + due date + 2
600 * sample records. `failStep` (1-based) injects a step at that position that
601 * references a NON-EXISTENT ref (the executor fails the step → rollback).
602 */
603export function mockGeneratePlan(prompt: string, failStep = 0): { tools: Array<Record<string, unknown>> } {
604  const title = "Product Launch Plan";
605  const sections = ["Objectives", "Requirements", "Timeline", "Risks", "Team", "Meeting Notes"];
606  const tools: Array<Record<string, unknown>> = [
607    { name: "createPage", args: { title, blocks: [] } },
608  ];
609  // Fail seam: inject a broken step at the requested position.
610  const broken: Record<string, unknown> = {
611    name: "insertBlocks",
612    args: { pageRef: "no_such_ref", blocks: [{ type: "PARAGRAPH", content: { text: "boom" } }] },
613  };
614  if (failStep > 0 && failStep <= tools.length + 1) tools.splice(failStep - 1, 0, broken);
615  // Section headings (one insertBlocks step for the whole section list — the
616  // executor appends each block in order under the root page).
617  tools.push({
618    name: "insertBlocks",
619    args: {
620      pageRef: undefined,
621      blocks: sections.map((s) => ({ type: "HEADING_2", content: { text: s } })),
622    },
623  });
624  // The Tasks database (under the root page): a status select + a due date.
625  // The seeded Title/Status already exist on a fresh database — so the plan
626  // declares only its OWN extra columns (Due) + the seeded Status options are
627  // already there. We still add a "Due" date column (the spec's "a date").
628  tools.push({
629    name: "createDatabase",
630    args: {
631      ref: "tasks",
632      pageRef: undefined, // the root page
633      title: "Tasks",
634      properties: [{ name: "Due", type: "date" }],
635      sampleRecords: [
636        { properties: { Title: "Draft launch announcement", Due: "2026-01-15" } },
637        { properties: { Title: "Schedule launch review", Due: "2026-01-20" } },
638      ],
639    },
640  });
641  // (prompt is echoed into the description-less plan for observability; it
642  // does not change the deterministic structure — the E2E asserts structure.)
643  void prompt;
644  return { tools };
645}
646 
647// ── TASK-0124 database-generation mode helpers ────────────────────────────────
648 
649/** The deterministic `createDatabase` tool call the mock emits for a prompt. */
650export function mockDatabaseGenerate(prompt: string, hostile: boolean): Record<string, unknown> {
651  const title = (prompt.trim().slice(0, 60) || "Generated database").replace(/[^\p{L}\p{N}\s:—-]/gu, "").trim() || "Generated database";
652  if (hostile) {
653    // A type NOT in the generated allowlist → the server must reject it with a
654    // per-property reason (and, after the retry-once, a 422).
655    return {
656      title,
657      description: "hostile (mock)",
658      properties: [{ name: "Broken", type: "relation" }],
659      sampleRecords: [],
660    };
661  }
662  return {
663    title,
664    description: `Generated from: ${prompt.trim().slice(0, 80)}`,
665    // NOTE: the generated db already SEEDS a "Title" + a "Status" select —
666    // the model must not re-declare them (the server rejects a 2nd
667    // "status"). So the mock's own select is named "State", not "Status".
668    properties: [
669      { name: "Name", type: "text" },
670      { name: "State", type: "select", options: [{ name: "To Do" }, { name: "Done" }] },
671      { name: "Due", type: "date" },
672      { name: "Done?", type: "checkbox" },
673    ],
674    // Sample records are keyed by property NAME; the record TITLE comes from
675    // the "Title" key (the seeded title property), the rest by their names.
676    sampleRecords: [
677      { properties: { Title: "First item", Name: "First item", State: "To Do", Due: "2026-01-01", "Done?": false } },
678      { properties: { Title: "Second item", Name: "Second item", State: "Done", Due: "2026-01-02", "Done?": true } },
679    ],
680  };
681}
682 
683/**
684 * The deterministic `insertRecords` tool call the mock emits for an extract.
685 * Parses the prompt markers the TASK-0124 prompt builder emits:
686 *   `[PROP <propertyId>] <Name> (<TYPE>)` — the database's real properties,
687 *   `<<<PASTE … PASTE>>>` — the user's pasted text (usually a markdown
688 *   table). The table is parsed with the SAME deterministic parser the server
689 *   uses (`parseMarkdownTable`); columns that match no property BY NAME go in
690 *   `ignoredColumns`.
691 */
692export function mockDatabaseExtract(text: string, hostile: boolean): Record<string, unknown> {
693  const props: Array<{ id: string; name: string; type: string }> = [];
694  {
695    const re = /\[PROP ([A-Za-z0-9_-]+)\]\s+([^\n<]+?)\s*\(([^)\n]+)\)/g;
696    let m: RegExpExecArray | null;
697    while ((m = re.exec(text)) !== null) props.push({ id: m[1]!, name: m[2]!.trim(), type: m[3]!.trim() });
698  }
699  // The pasted region (fall back to the whole prompt when the markers are
700  // absent — the parser is harmless on prose: it just finds the pipe rows).
701  const paste = /<<<PASTE\n([\s\S]*?)\nPASTE>>>/.exec(text);
702  const pasted = paste ? paste[1]! : text;
703  const table = parseMarkdownTable(pasted);
704  if (hostile) {
705    // A record referencing a property id the database does NOT have → the
706    // server's per-record validation must reject it (no partial write).
707    return { records: [{ properties: { does_not_exist: "x" } }], ignoredColumns: [] };
708  }
709  if (!table.isTable || table.rows.length === 0) {
710    return { records: [], ignoredColumns: table.columns };
711  }
712  const mapping = mapColumnsToProperties(table.columns, props.map((p) => ({ id: p.id, name: p.name })));
713  const records = table.rows.map((row) => {
714    const properties: Record<string, unknown> = {};
715    for (const pair of mapping.mapped) {
716      const cell = row[pair.column] ?? "";
717      if (cell !== "") properties[pair.propertyId] = cell;
718    }
719    return { properties };
720  });
721  return { records, ignoredColumns: mapping.ignored };
722}
723 
724/**
725 * The deterministic `generateFormula` tool call the mock emits. `properties`
726 * = `[PROP <name>] <type>` lines. It builds a REAL, engine-valid expression
727 * referencing the first two properties: `if` (a bool) when the first is a
728 * string-ish type, else `sum`/`+`. `hostile` emits an expression that the
729 * engine cannot parse (an unknown function) → the retry-once → 422 path.
730 */
731export function mockDatabaseFormula(text: string, hostile: boolean): Record<string, unknown> {
732  const props: Array<{ name: string; type: string }> = [];
733  const re = /\[PROP ([^\n\]]+?)\]\s+([a-z_]+)/g;
734  let m: RegExpExecArray | null;
735  while ((m = re.exec(text)) !== null) props.push({ name: m[1]!.trim(), type: m[2]! });
736  if (hostile) {
737    // An expression the formula engine CANNOT parse (unknown function) → the
738    // retry-once → 422 `formula_invalid` path.
739    return { expression: "explode(prop(\"x\"))", explanation: "hostile (unknown function)" };
740  }
741  const [a] = props;
742  if (a) {
743    return { expression: `if(prop("${a.name}") == "Done", 100, 0)`, explanation: `Deterministic formula over ${a.name}.` };
744  }
745  return { expression: "now()", explanation: "No properties; a now() expression." };
746}
747 
748// ── TASK-0123 writing-mode helpers ────────────────────────────────────────────
749 
750/** Parse the delimited block markers the TASK-0123 prompt builder emits into
751 *  the user message. `[SELECTED <id>]…[/SELECTED <id>]` are the blocks the
752 *  user asked the model to edit; `[CONTEXT <id>]…[/CONTEXT <id>]` are the
753 *  surrounding ±5 blocks (never edited). Returns selected blocks in prompt
754 *  order. */
755export function parseWritingBlocks(messages: Array<{ role: string; content: unknown }>): Array<{ id: string; text: string }> {
756  const userMsg = [...messages].reverse().find((m) => m.role === "user");
757  if (!userMsg) return [];
758  const text = typeof userMsg.content === "string" ? userMsg.content : "";
759  const out: Array<{ id: string; text: string }> = [];
760  const re = /\[SELECTED ([A-Za-z0-9_-]+)\]\n?([\s\S]*?)\n?\[\/SELECTED \1\]/g;
761  let m: RegExpExecArray | null;
762  while ((m = re.exec(text)) !== null) {
763    out.push({ id: m[1]!, text: (m[2] ?? "").trim() });
764  }
765  return out;
766}
767 
768/**
769 * Parse the FIRST numbered context block the TASK-0125 RAG prompt builder
770 * emits into the user message:
771 *   `[n] Source: <label>\n<chunk text>\n\n` — followed by either another
772 *   `[n] Source:` block, the `Question:` line, or end of message.
773 * Returns `null` when no source block is present (the "no results" answer).
774 */
775export function parseRagSource(
776  userText: string,
777): { n: number; label: string; text: string } | null {
778  // The block always starts at the very beginning of the user message (the
779  // service builds `<contextBlocks>\n\nQuestion: …`), so `^` is anchored to
780  // string start and the `$` alternative is the TRUE end — deliberately NOT
781  // multiline: a `/m` flag would let `$` match every line break and truncate
782  // multi-line chunk text at its first newline (e.g. a whole-page body
783  // `Title\n<fact>` would yield only `Title` — TASK-0125 integration caught
784  // this with the seeded `Launch Runbook\n…Zanzibar-7.` parent body).
785  const m = /^\[(\d+)\] Source: ([^\n]+)\n([\s\S]*?)(?=\n\[\d+\] Source: |\nQuestion: |$)/.exec(userText);
786  if (!m) return null;
787  return { n: Number(m[1]!), label: m[2]!.trim(), text: (m[3] ?? "").trim() };
788}
789 
790/** Deterministic per-action transform (TASK-0123). */
791export function writingTransform(action: string, text: string, language?: string): string {
792  const t = text.trim();
793  switch (action) {
794    case "summarize":
795      return `Summarized: ${t.slice(0, 80)}`;
796    case "improve":
797      return `Improved: ${t}`;
798    case "translate":
799      return `Translated to ${language ?? "the target language"}: ${t}`;
800    case "rewrite":
801    default:
802      return `Rewritten: ${t}`;
803  }
804}
805