@eserstack/ai 0.0.0-bootstrap.0 → 5.0.0

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.
Files changed (62) hide show
  1. package/LICENSE +13 -0
  2. package/README.md +498 -0
  3. package/dist/adapters/ajan-bridge.d.ts +69 -0
  4. package/dist/adapters/ajan-bridge.js +661 -0
  5. package/dist/adapters/anthropic.d.ts +25 -0
  6. package/dist/adapters/anthropic.js +567 -0
  7. package/dist/adapters/claude-code.d.ts +28 -0
  8. package/dist/adapters/claude-code.js +462 -0
  9. package/dist/adapters/cli-shared.d.ts +36 -0
  10. package/dist/adapters/cli-shared.js +207 -0
  11. package/dist/adapters/gemini.d.ts +19 -0
  12. package/dist/adapters/gemini.js +91 -0
  13. package/dist/adapters/google-shared.d.ts +58 -0
  14. package/dist/adapters/google-shared.js +424 -0
  15. package/dist/adapters/kiro.d.ts +19 -0
  16. package/dist/adapters/kiro.js +195 -0
  17. package/dist/adapters/mod.d.ts +61 -0
  18. package/dist/adapters/mod.js +129 -0
  19. package/dist/adapters/ollama.d.ts +20 -0
  20. package/dist/adapters/ollama.js +226 -0
  21. package/dist/adapters/openai.d.ts +25 -0
  22. package/dist/adapters/openai.js +553 -0
  23. package/dist/adapters/opencode.d.ts +19 -0
  24. package/dist/adapters/opencode.js +158 -0
  25. package/dist/adapters/vertexai.d.ts +19 -0
  26. package/dist/adapters/vertexai.js +96 -0
  27. package/dist/batch.d.ts +35 -0
  28. package/dist/batch.js +2 -0
  29. package/dist/commands/ask.d.ts +30 -0
  30. package/dist/commands/ask.js +404 -0
  31. package/dist/commands/list.d.ts +2 -0
  32. package/dist/commands/list.js +35 -0
  33. package/dist/config.d.ts +21 -0
  34. package/dist/config.js +16 -0
  35. package/dist/content.d.ts +14 -0
  36. package/dist/content.js +103 -0
  37. package/dist/detect.d.ts +9 -0
  38. package/dist/detect.js +125 -0
  39. package/dist/errors.d.ts +62 -0
  40. package/dist/errors.js +135 -0
  41. package/dist/generation.d.ts +126 -0
  42. package/dist/generation.js +96 -0
  43. package/dist/main.d.ts +22 -0
  44. package/dist/main.js +42 -0
  45. package/dist/mod.d.ts +16 -0
  46. package/dist/mod.js +11 -0
  47. package/dist/model.d.ts +27 -0
  48. package/dist/model.js +12 -0
  49. package/dist/module.d.ts +10 -0
  50. package/dist/module.js +21 -0
  51. package/dist/package.json +74 -0
  52. package/dist/registry.d.ts +22 -0
  53. package/dist/registry.js +97 -0
  54. package/dist/streams/layers.d.ts +4 -0
  55. package/dist/streams/layers.js +33 -0
  56. package/dist/streams/mod.d.ts +2 -0
  57. package/dist/streams/mod.js +5 -0
  58. package/dist/streams/sources.d.ts +6 -0
  59. package/dist/streams/sources.js +76 -0
  60. package/dist/types.d.ts +79 -0
  61. package/dist/types.js +2 -0
  62. package/package.json +63 -1
package/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ Copyright 2023-present Eser Ozvataf and other contributors.
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License.
5
+ You may obtain a copy of the License at
6
+
7
+ http://www.apache.org/licenses/LICENSE-2.0
8
+
9
+ Unless required by applicable law or agreed to in writing, software
10
+ distributed under the License is distributed on an "AS IS" BASIS,
11
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ See the License for the specific language governing permissions and
13
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,498 @@
1
+ # 🤖 [@eserstack/ai](./)
2
+
3
+ > **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/ai` is published on
4
+ > npm under the same name (`pnpm add @eserstack/ai`); the JSR versions stay
5
+ > available but get no updates.
6
+
7
+ > **eserstack Tool** — [eser/stack on GitHub](https://github.com/eser/stack)
8
+ > **Install:** `pnpm add @eserstack/ai`
9
+
10
+ Unified AI provider interface for eser stack. Supports cloud APIs (Anthropic,
11
+ OpenAI, Gemini, Vertex AI) and local agents (Claude Code, Ollama, OpenCode,
12
+ Kiro) through a single `LanguageModel` abstraction.
13
+
14
+ ## CLI
15
+
16
+ ```bash
17
+ # Standalone, from the package directory
18
+ node ./main.ts ask "explain closures in JS" -p cc
19
+ node ./main.ts ask "summarize this" # auto-detect provider
20
+ node ./main.ts list # show available providers
21
+
22
+ # Via eser CLI
23
+ eser ai ask "hello" -p ollama -m llama3
24
+ eser ai ask "summarize this diff in one line" -p ant --effort low
25
+ eser ai list
26
+ ```
27
+
28
+ ### Provider Aliases
29
+
30
+ | Alias | Provider | Type |
31
+ | ----- | ----------- | ---- |
32
+ | `cc` | claude-code | CLI |
33
+ | `ol` | ollama | HTTP |
34
+ | `oc` | opencode | CLI |
35
+ | `oai` | openai | API |
36
+ | `ant` | anthropic | API |
37
+ | `gem` | gemini | API |
38
+ | `vtx` | vertexai | API |
39
+ | `kr` | kiro | CLI |
40
+
41
+ ### Flags
42
+
43
+ | Flag | Description |
44
+ | ---------------- | ------------------------------------------------------------------------------- |
45
+ | `-p, --provider` | Provider name or alias |
46
+ | `-m, --model` | Model ID override |
47
+ | `--max-tokens` | Max output tokens, a positive whole number |
48
+ | `--effort` | Effort level: `low`, `medium`, `high`, `xhigh` or `max` (see [Effort](#effort)) |
49
+ | `--json` | Output full result as JSON |
50
+ | `-v, --verbose` | Show detection and timing info |
51
+
52
+ `ai ask` stops before it chooses a provider when a flag has no value,
53
+ `--max-tokens` is not a positive whole number, or `--effort` is not one of the
54
+ five levels.
55
+
56
+ ## Library API
57
+
58
+ The package root runs the CLI, so the library is imported from `./mod`, and the
59
+ provider factories from `./adapters`:
60
+
61
+ ```typescript
62
+ import * as ai from "@eserstack/ai/mod";
63
+ import * as aiAdapters from "@eserstack/ai/adapters";
64
+ ```
65
+
66
+ ### Registry + Model
67
+
68
+ Register the factories you need, then add a model per configuration target. When
69
+ `apiKey` is not set, the Anthropic SDK reads `ANTHROPIC_API_KEY` from the
70
+ environment.
71
+
72
+ ```typescript
73
+ import * as ai from "@eserstack/ai/mod";
74
+ import * as aiAdapters from "@eserstack/ai/adapters";
75
+
76
+ const registry = new ai.Registry({
77
+ factories: [aiAdapters.anthropicFactory],
78
+ });
79
+
80
+ await registry.addModel("default", {
81
+ provider: "anthropic",
82
+ model: "claude-sonnet-5",
83
+ });
84
+
85
+ const model = registry.getDefault();
86
+ if (model === null) {
87
+ throw new Error("no model registered: call registry.addModel first");
88
+ }
89
+ ```
90
+
91
+ ### Generate Text
92
+
93
+ `generateText` returns a `Result` from `@eserstack/primitives` instead of
94
+ throwing. Check it before you read the value:
95
+
96
+ ```typescript
97
+ import * as primitives from "@eserstack/primitives";
98
+
99
+ const result = await model.generateText({
100
+ messages: [ai.textMessage("user", "What is gaslighting?")],
101
+ maxTokens: 1024,
102
+ });
103
+
104
+ if (primitives.results.isFail(result)) {
105
+ throw result.error;
106
+ }
107
+
108
+ console.log(ai.text(result.value));
109
+ ```
110
+
111
+ ### Streaming
112
+
113
+ `streamText` yields events as the model writes, and reports a failure as an
114
+ `error` event instead of throwing:
115
+
116
+ ```typescript
117
+ const messages = [ai.textMessage("user", "Write a haiku about rivers.")];
118
+ const parts: string[] = [];
119
+
120
+ for await (const event of model.streamText({ messages })) {
121
+ if (event.kind === "content_delta") {
122
+ parts.push(event.textDelta);
123
+ } else if (event.kind === "error") {
124
+ throw event.error;
125
+ }
126
+ }
127
+
128
+ console.log(parts.join(""));
129
+ ```
130
+
131
+ Leaving the loop early with `break` or `return` ends the request. The Go bridge
132
+ cancels it, and the TypeScript `claude-code`, `kiro` and `opencode` adapters
133
+ stop the CLI process they started.
134
+
135
+ To print the text as it arrives, pipe it through `@eserstack/streams` as the
136
+ next section shows.
137
+
138
+ ### Effort
139
+
140
+ `effort` sets how much the model thinks and how many tokens it spends on a
141
+ reply: `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`. Lower effort answers
142
+ faster and costs less. Leave it unset to keep the provider's default:
143
+
144
+ ```typescript
145
+ const result = await model.generateText({
146
+ messages: [ai.textMessage("user", "Summarize this diff in one line.")],
147
+ effort: "low",
148
+ });
149
+ ```
150
+
151
+ Each provider sends it in its own way, or ignores it:
152
+
153
+ | Provider | Sent as |
154
+ | ---------------------------- | ------------------------------------------------------------------------------------- |
155
+ | `anthropic` | `output_config.effort` |
156
+ | `openai` | `reasoning_effort`; a model that lacks the level rejects the request |
157
+ | `claude-code` | the `--effort` flag, which needs a `claude` CLI version that has it |
158
+ | `gemini`, `vertexai` | `thinkingConfig.thinkingLevel`; `xhigh` and `max` send `HIGH`, Gemini's highest level |
159
+ | `ollama`, `opencode`, `kiro` | ignored |
160
+
161
+ On `anthropic` and `openai`, an explicit `effort` wins over the level that
162
+ `thinkingBudget` maps to.
163
+
164
+ On `gemini` and `vertexai`, an explicit `effort` is sent instead of
165
+ `thinkingBudget`, since the API rejects a request that sets both. The levels a
166
+ Gemini model takes differ from one model to the next, and the adapter sends the
167
+ level without checking it against the model.
168
+ [Google's thinking guide](https://ai.google.dev/gemini-api/docs/thinking) lists
169
+ the levels per model.
170
+
171
+ ### Structured Output
172
+
173
+ `responseFormat` asks for a JSON reply. With `type: "json_schema"`, the reply
174
+ follows the JSON Schema in `jsonSchema`. The reply still arrives as text, and
175
+ model output is untrusted input, so parse it and check its shape before you use
176
+ it:
177
+
178
+ ```typescript
179
+ import * as primitives from "@eserstack/primitives";
180
+
181
+ const result = await model.generateText({
182
+ messages: [
183
+ ai.textMessage("user", "Suggest a title for a post about pnpm workspaces."),
184
+ ],
185
+ responseFormat: {
186
+ type: "json_schema",
187
+ name: "post_title",
188
+ jsonSchema: {
189
+ type: "object",
190
+ properties: { title: { type: "string" } },
191
+ required: ["title"],
192
+ additionalProperties: false,
193
+ },
194
+ },
195
+ });
196
+
197
+ if (primitives.results.isFail(result)) {
198
+ throw result.error;
199
+ }
200
+
201
+ const reply: unknown = JSON.parse(ai.text(result.value));
202
+ ```
203
+
204
+ Each provider sends a `json_schema` format in its own way, or ignores it:
205
+
206
+ | Provider | Sent as |
207
+ | -------------------- | ------------------------------------------------------------------------ |
208
+ | `anthropic` | `output_config.format`, in the same object as `effort` |
209
+ | `openai` | `response_format` with `strict: true` |
210
+ | `gemini`, `vertexai` | a response JSON schema with the `application/json` MIME type |
211
+ | `ollama` | `format` |
212
+ | `claude-code` | the `--json-schema` flag, which needs a `claude` CLI version that has it |
213
+ | `opencode`, `kiro` | ignored |
214
+
215
+ Every provider that sends the schema needs it: without `jsonSchema`, or with one
216
+ that is not an object, the call fails with a `BadRequestError` before any
217
+ request is sent.
218
+
219
+ On `anthropic` and `claude-code`:
220
+
221
+ - `name` is not sent, since neither has a field for it.
222
+ - `json_object` and `text` are ignored: Claude has no JSON mode without a
223
+ schema, so the prompt alone decides the shape of the reply.
224
+ - Claude accepts a subset of JSON Schema; on `anthropic` every object needs
225
+ `additionalProperties: false`. See
226
+ [Anthropic's structured outputs guide](https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
227
+
228
+ On `claude-code`, the reply text is the CLI's structured output, and the prose
229
+ the model writes around it is left out. When the model gives no structured
230
+ output, as when it declines, the reply text is the prose instead. `streamText`
231
+ yields the reply as one `content_delta` once the CLI has finished.
232
+
233
+ On every provider, a reply that stops with `refusal` or `max_tokens` may not
234
+ match the schema, so check `stopReason` before you parse it.
235
+
236
+ ### @eserstack/streams Integration
237
+
238
+ ```typescript
239
+ import * as streams from "@eserstack/streams";
240
+ import * as aiStreams from "@eserstack/ai/streams";
241
+
242
+ await streams
243
+ .pipeline()
244
+ .from(aiStreams.aiTextSource(model, { messages }))
245
+ .to(streams.sinks.stdout())
246
+ .run();
247
+ ```
248
+
249
+ `aiTextSource` passes on the text deltas only. When `streamText` reports an
250
+ `error` event, the source fails with that error, so `run()` rejects instead of
251
+ finishing with a partial reply.
252
+
253
+ Layers are also available:
254
+
255
+ ```typescript
256
+ import * as aiStreams from "@eserstack/ai/streams";
257
+
258
+ // Extract text from StreamEvent chunks
259
+ const textLayer = aiStreams.extractText();
260
+
261
+ // Count tokens via callback
262
+ const counter = aiStreams.tokenCounter((usage) => {
263
+ console.log(`Tokens: ${usage.totalTokens}`);
264
+ });
265
+ ```
266
+
267
+ ## Providers
268
+
269
+ ### Cloud APIs
270
+
271
+ | Provider | Package | Features |
272
+ | --------- | ------------------- | --------------------------------------------------------------- |
273
+ | Anthropic | `@anthropic-ai/sdk` | Text, streaming, tools, vision, batch, struct, reasoning |
274
+ | OpenAI | `openai` | Text, streaming, tools, vision, audio, batch, struct, reasoning |
275
+ | Gemini | `@google/genai` | Text, streaming, tools, vision, audio, struct, reasoning |
276
+ | Vertex AI | `@google/genai` | Same as Gemini, project/location auth |
277
+
278
+ A provider declares the same capabilities (`model.capabilities`) whether the
279
+ TypeScript adapter or the Go bridge serves it.
280
+
281
+ ### Local Agents
282
+
283
+ | Provider | Transport | Drives |
284
+ | ----------- | ------------------------ | -------------------------------------------- |
285
+ | Claude Code | ACP, in-process (or CLI) | `claude --print --output-format stream-json` |
286
+ | Ollama | HTTP fetch | `POST localhost:11434/api/chat` with JSONL |
287
+ | OpenCode | ACP, in-process (or CLI) | `opencode` with its JSON output flag |
288
+ | Kiro | ACP, in-process (or CLI) | `kiro` with its JSON output flag |
289
+
290
+ ### Two paths, and which one you get
291
+
292
+ `defaultFactories()` merges the TypeScript adapters with the Go FFI bridge **per
293
+ provider** — the bridge wins wherever it has an entry, and the TypeScript
294
+ adapter remains for every provider it does not. `factoryFor(provider)` does the
295
+ same for a single provider without importing the others.
296
+
297
+ For the three agent providers above, the bridge speaks the Agent Client Protocol
298
+ to a shim that is **linked into the Go library**, not spawned: `acpfx.InProcess`
299
+ connects them over an in-memory pipe. There is no separate binary to install or
300
+ find on PATH. The shim still drives the vendor CLI, so `claude`, `kiro` or
301
+ `opencode` must be installed — a spawn-time requirement, reported when it fails.
302
+
303
+ When the native library cannot load, the pure-TypeScript adapters take over and
304
+ shell out to the same vendor CLI directly. The bridge **refuses to load over
305
+ WASM** deliberately: WASM loads and then fails every request, because Go's
306
+ `wasip1` target has no outbound network — so a WASM-only machine falls back to
307
+ TypeScript rather than registering a provider that is present and broken.
308
+
309
+ `binPath` on one of these providers names the **vendor CLI**, not a shim.
310
+
311
+ ## Content Types
312
+
313
+ Messages use a discriminated union for content blocks:
314
+
315
+ ```typescript
316
+ type ContentBlock =
317
+ | { kind: "text"; text: string }
318
+ | { kind: "image"; image: ImagePart }
319
+ | { kind: "audio"; audio: AudioPart }
320
+ | { kind: "file"; file: FilePart }
321
+ | { kind: "tool_call"; toolCall: ToolCall }
322
+ | { kind: "tool_result"; toolResult: ToolResult }
323
+ | { kind: "thinking"; thinking: ThinkingPart };
324
+ ```
325
+
326
+ A `thinking` block holds the model's reasoning, which `ai.text()` leaves out.
327
+ Anthropic signs it (`signature`, or `redactedData` when redacted) and rejects a
328
+ tool-use turn sent back without it, so keep `result.content` whole when you add
329
+ the assistant turn to the next request. Streams deliver each block as one
330
+ `thinking` event, and `ai.collectStream` puts them first.
331
+
332
+ Helper constructors:
333
+
334
+ ```typescript
335
+ ai.textMessage("user", "Hello");
336
+ ai.imageMessage("user", "https://example.com/photo.jpg", "high");
337
+ ai.toolResultMessage("call_1", "25C");
338
+ ```
339
+
340
+ ## Refusals
341
+
342
+ A model that declines a request, or a provider's content filter that withholds
343
+ the answer, ends with `stopReason: "refusal"`. The generation itself succeeds,
344
+ and its text, if any, explains the refusal or was cut off by the filter. Check
345
+ the stop reason before using the text as an answer:
346
+
347
+ ```typescript
348
+ import * as primitives from "@eserstack/primitives";
349
+
350
+ const result = await model.generateText({ messages });
351
+
352
+ if (primitives.results.isOk(result) && result.value.stopReason === "refusal") {
353
+ throw new Error(`${result.value.modelId} declined the request`);
354
+ }
355
+ ```
356
+
357
+ Each provider reports a refusal in its own way:
358
+
359
+ | Provider | Reported as `"refusal"` |
360
+ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
361
+ | `anthropic` | `stop_reason: "refusal"` |
362
+ | `openai` | `finish_reason: "content_filter"`, or a `message.refusal`, whose text becomes the reply text |
363
+ | `gemini`, `vertexai` | a filter's `finishReason` (`SAFETY`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `RECITATION` and the image variants), or a blocked prompt |
364
+
365
+ A reply that was cut off ends with `stopReason: "max_tokens"`. On `anthropic`
366
+ that also covers `model_context_window_exceeded`, a reply cut off because the
367
+ context window filled up.
368
+
369
+ ## Error Classification
370
+
371
+ Provider-agnostic error hierarchy with `instanceof` checking. `generateText`
372
+ returns these errors in a failed `Result`, `streamText` in an `error` event, and
373
+ the batch methods throw them:
374
+
375
+ ```typescript
376
+ import * as primitives from "@eserstack/primitives";
377
+
378
+ const result = await model.generateText({ messages });
379
+
380
+ if (primitives.results.isFail(result)) {
381
+ if (result.error instanceof ai.RateLimitedError) {
382
+ /* 429 */
383
+ }
384
+ if (result.error instanceof ai.AuthFailedError) {
385
+ /* 401 */
386
+ }
387
+ if (result.error instanceof ai.BadRequestError) {
388
+ /* 400 */
389
+ }
390
+ }
391
+ ```
392
+
393
+ ## Configuration
394
+
395
+ `loadFromConfig` adds one model per target. The registry needs a factory for
396
+ every provider the config names; `defaultFactories()` returns all of them:
397
+
398
+ ```typescript
399
+ import * as ai from "@eserstack/ai/mod";
400
+ import * as aiAdapters from "@eserstack/ai/adapters";
401
+
402
+ const config: ai.Config = {
403
+ targets: {
404
+ default: {
405
+ provider: "claude-code",
406
+ model: "claude-sonnet-5",
407
+ properties: { maxTurns: 1 },
408
+ },
409
+ ollama: {
410
+ provider: "ollama",
411
+ model: "llama3",
412
+ properties: { baseUrl: "http://localhost:11434" },
413
+ },
414
+ },
415
+ };
416
+
417
+ const registry = new ai.Registry({
418
+ factories: await aiAdapters.defaultFactories(),
419
+ });
420
+
421
+ await registry.loadFromConfig(config);
422
+ ```
423
+
424
+ ## Upgrading from 4.x
425
+
426
+ These changes since 4.5.2 need a change in code, commands or files that use this
427
+ package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
428
+ lists the changes in every package.
429
+
430
+ - `ContentBlock` has a `ThinkingBlock` (`kind: "thinking"`), `StreamEvent` a
431
+ `ThinkingEvent`, and `StopReason` the value `"refusal"`. An exhaustive
432
+ `switch` over them without a `default` no longer compiles. Add the cases, and
433
+ treat `"refusal"` as a declined request, not an answer:
434
+
435
+ ```typescript
436
+ // After: check for a refusal before you use the text
437
+ if (result.stopReason === "refusal") {
438
+ return reportRefusal(result);
439
+ }
440
+ ```
441
+
442
+ - Stop reasons: Anthropic `refusal`, OpenAI `content_filter` and
443
+ `message.refusal`, Gemini and Vertex AI safety, blocklist and recitation
444
+ reasons and blocked prompts, the claude-code CLI's `refusal`, and ACP
445
+ `refusal` are now `"refusal"`; they used to be `"end_turn"` or `"stop"`.
446
+ Anthropic `model_context_window_exceeded` is `"max_tokens"`. Gemini and Vertex
447
+ AI turns that call a tool end with `"tool_use"`, and unknown OpenAI and Gemini
448
+ reasons are `"stop"`. Check for `"refusal"` before you use the text, and
449
+ accept `"tool_use"` where you compared with `"end_turn"` after a tool call.
450
+ - A `json_schema` `responseFormat` with a missing or non-object schema fails
451
+ before sending with `BadRequestError`, on every provider; it used to be sent
452
+ without the schema. Anthropic now sends the schema as `output_config.format`,
453
+ so a schema outside the subset Claude accepts (for example an object without
454
+ `additionalProperties: false`) gets a 400 from the API. Pass a JSON Schema
455
+ object that follows the provider's limits, or use `json_object`:
456
+
457
+ ```typescript
458
+ const options = {
459
+ // Before: { type: "json_schema" } was accepted and the schema ignored
460
+ responseFormat: {
461
+ type: "json_schema",
462
+ jsonSchema: {
463
+ type: "object",
464
+ properties: { title: { type: "string" } },
465
+ required: ["title"],
466
+ additionalProperties: false,
467
+ },
468
+ },
469
+ };
470
+ ```
471
+
472
+ - claude-code with a `json_schema` format passes `--json-schema` to the CLI, and
473
+ `generateCommitMessage` on claude-code passes `--effort low`; a claude CLI
474
+ without these flags rejects the call (2.1.289 has them). The reply text is the
475
+ structured output, and `streamText` yields it as one `content_delta` after the
476
+ CLI exits. Update the claude CLI, and parse `ai.text(result)` as JSON.
477
+ - Capabilities: Anthropic models declare `structured_output` and `reasoning`;
478
+ the Gemini bridge model declares `audio`, `structured_output` and `reasoning`,
479
+ the OpenAI bridge model `audio`, and the Vertex AI bridge model no longer
480
+ declares `batch_processing`. `getByCapability("batch_processing")` no longer
481
+ returns a Vertex AI bridge model, which never had batch methods.
482
+ - `aiTextSource` (`@eserstack/ai/streams`) fails its stream with the error of a
483
+ `streamText` error event; it used to end normally with partial text. Handle
484
+ the rejection of `pipeline().run()`, or use `aiSource` to receive error events
485
+ as data.
486
+ - `eser ai ask`: a value flag with no value (`-p`, `-m`, `--max-tokens`) and a
487
+ `--max-tokens` that is not a positive whole number exit 1 with a message.
488
+ Before: `eser ai ask -m` ignored the flag. After: pass a value, as in
489
+ `eser ai ask "your prompt" -m your_model_id`.
490
+
491
+ ## License
492
+
493
+ Apache-2.0
494
+
495
+ ---
496
+
497
+ 🔗 For further details, visit the
498
+ [eserstack repository](https://github.com/eser/stack).
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Ajan FFI bridge adapter for @eserstack/ai.
3
+ *
4
+ * Routes AI calls through the Go `pkg/ajan/aifx` implementation via the
5
+ * `@eserstack/ajan` C-shared library. Falls back gracefully when native
6
+ * FFI is unavailable.
7
+ *
8
+ * @module
9
+ */
10
+ import * as results from "@eserstack/primitives/results";
11
+ import type * as ffiTypes from "@eserstack/ajan/ffi";
12
+ import type * as types from "../types.ts";
13
+ import type * as config from "../config.ts";
14
+ import type * as generation from "../generation.ts";
15
+ import type * as batch from "../batch.ts";
16
+ import type * as model from "../model.ts";
17
+ import * as errors from "../errors.ts";
18
+ export declare class AjanBridgeModel implements model.BatchCapableModel {
19
+ #private;
20
+ readonly capabilities: readonly types.ProviderCapability[];
21
+ readonly provider: string;
22
+ readonly modelId: string;
23
+ constructor(lib: ffiTypes.FFILibrary, modelHandle: string, provider: string, modelId: string, capabilities: readonly types.ProviderCapability[]);
24
+ generateText(options: generation.GenerateTextOptions, signal?: AbortSignal): Promise<results.Result<generation.GenerateTextResult, errors.AiError>>;
25
+ streamText(options: generation.GenerateTextOptions, signal?: AbortSignal): AsyncIterable<generation.StreamEvent>;
26
+ submitBatch(request: batch.BatchRequest, signal?: AbortSignal): Promise<batch.BatchJob>;
27
+ getBatchJob(jobId: string, signal?: AbortSignal): Promise<batch.BatchJob>;
28
+ listBatchJobs(options?: batch.ListBatchOptions, signal?: AbortSignal): Promise<readonly batch.BatchJob[]>;
29
+ downloadBatchResults(job: batch.BatchJob, signal?: AbortSignal): Promise<readonly batch.BatchResult[]>;
30
+ /**
31
+ * Asks the provider to cancel a batch job.
32
+ *
33
+ * Distinct from aborting this call. `signal` aborts the local request that
34
+ * asks for the cancellation; the cancellation itself is a durable change of
35
+ * state at the provider, and aborting the ask does not undo it if it already
36
+ * landed.
37
+ */
38
+ cancelBatchJob(jobId: string, signal?: AbortSignal): Promise<void>;
39
+ close(): Promise<void>;
40
+ [Symbol.asyncDispose](): Promise<void>;
41
+ [Symbol.dispose](): void;
42
+ getRawClient(): unknown;
43
+ }
44
+ export declare class AjanBridgeModelFactory implements model.ProviderFactory {
45
+ #private;
46
+ readonly provider: string;
47
+ constructor(lib: ffiTypes.FFILibrary, provider: string, capabilities: readonly types.ProviderCapability[]);
48
+ createModel(cfg: config.ResolvedConfigTarget): Promise<model.LanguageModel>;
49
+ }
50
+ /**
51
+ * Creates AjanBridgeModelFactory instances for all supported providers.
52
+ *
53
+ * Every provider the bridge knows, unconditionally — there is nothing that can
54
+ * be independently absent, because every backend is Go code inside the very
55
+ * library that just loaded. The vendor CLI that claude-code, kiro and opencode
56
+ * each drive (claude, kiro, opencode) must still be installed, but that is a
57
+ * spawn-time failure with its own message, not something a PATH probe can
58
+ * predict.
59
+ */
60
+ export declare const createBridgeFactories: (lib: ffiTypes.FFILibrary) => readonly model.ProviderFactory[];
61
+ export declare const tryLoadBridgeFactories: () => Promise<readonly model.ProviderFactory[]>;
62
+ /**
63
+ * Why the Go bridge is not in use, or `null` when it loaded or was never tried.
64
+ *
65
+ * The underlying loader's own diagnostic (the checked paths, the native-vs-WASM
66
+ * cause) is preserved as this error's `cause`, so a caller can report the whole
67
+ * chain rather than just the last frame.
68
+ */
69
+ export declare const getBridgeLoadError: () => Error | null;