@byte-42/fantastico-sdk 0.0.0-stage → 0.21.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byte42 S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,470 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @byte-42/fantastico-sdk
+
+> The FANTASTICO client: opaque tool orchestration, inference sent straight to the LLM provider,
+> per-tenant budgets. It runs **inside your perimeter** (in your application's own process), not as a
+> separate service — Byte42 never sees the prompt.
+
+## Installation
+
+```bash
+npm install @byte-42/fantastico-sdk
+```
+
+Published on the public npm registry: no `.npmrc`, no token. The package was previously
+`@byte42/fantastico-sdk` on Byte42's private registry (up to 0.20.0); the API is unchanged, only
+the import name differs — the `@byte42` scope on npmjs.org belongs to someone else.
+
+Pure ESM package (`"type":"module"`). From a **CommonJS** consumer (e.g. TypeScript compiled with
+`"module":"CommonJS"`) use a dynamic `import()` — never a top-level `require()`. `require()` does
+work thanks to the `"default"` condition in the `exports` map (Node ≥22.12 loads it transparently
+via require(esm)); on Node <22.12, or inside a bundler, you need dynamic `import()` or a CJS/ESM
+dual build.
+
+## Quick start
+
+```typescript
+import { Fantastico } from "@byte-42/fantastico-sdk";
+
+const ai = new Fantastico({
+  apiKey: "sk-fant-prod-…",                        // project key: the only credential
+  baseUrl: "https://fantastico.cc/api",
+});
+
+const response = await ai.chat.completions.create({
+  messages: [{ role: "user", content: "What is the deadline for a short-form appeal?" }],
+  user: "studio-rossi",                            // end tenant → spend attributed and capped
+});
+
+console.log(response.choices[0].message.content);
+// → Full answer, with statutory citations (MCP resolved internally)
+```
+
+## How it works
+
+The SDK exposes **a single virtual LLM**. You know nothing about MCP, tools or services: you send
+messages and you get answers. The orchestration is opaque:
+
+```
+You → SDK ──► LLM provider (project runtime key, DIRECT call)
+               ↓ tool_use?
+             SDK runs the tool internally, against the tool's own endpoint
+               ↓ result
+             SDK calls the LLM provider again
+               ↓ stop
+          SDK → You (final text only + aggregated usage, with real USD cost)
+```
+
+The FANTASTICO Cloud is involved only to mint the project runtime key (`POST /api/runtime/key`), which
+also hands back one grant per enabled tool, and to reserve and settle tenant budgets
+(`POST /api/runtime/budget`). Neither sits on the prompt's path — and neither does tool execution:
+each grant carries the tool's own endpoint and a token issued for it, so the SDK calls the tool
+directly.
+
+## Per-tenant budgets
+
+Pass `user` (the standard OpenAI field) to attribute spend to a tenant. The SDK reserves budget
+from the Cloud **before** the call — stopping with a 402 if the tenant or the project is out of
+funds — and settles the real USD spend on the next round. At the end of a session,
+`ai.flushBudget("studio-rossi")` clears the last outstanding amount.
+
+Without `user`, only the project ceiling on the runtime key applies, and the LLM provider itself
+enforces it.
+
+## Accounts
+
+An account is the end tenant that spend is attributed to. Project and environment are **never
+passed**: they are the ones belonging to the project key you built the client with.
+
+```typescript
+await ai.accounts.create({ userKey: "studio-rossi", label: "Studio Rossi", spendLimit: 20 });
+await ai.accounts.list();
+await ai.accounts.get("studio-rossi");
+await ai.accounts.update("studio-rossi", { spendLimit: 50 });
+```
+
+### Account keys — delegating to a perimeter you do not control
+
+So far **you** operate the account, from this client, with the project key. That is the usual model, and
+it is fine as long as the calling code runs in your own backend.
+
+If the client runs somewhere you cannot reach — a plugin on a customer's server, a device, a
+third-party installation — that project key cannot go there: it is worth the project's entire
+reserve, and anyone tampering with it would burn every other account's credit. For that case there
+is the **account key**: it is worth one account only, and the runtime key it mints is capped to
+*that* account's credit.
+
+```typescript
+const { key } = await ai.accounts.keys.issue("sito-1");
+// ↑ the only time the value exists: at rest the Cloud keeps only its hash.
+//   Hand it over and forget it — a lost key is not recovered, it is rotated.
+
+await ai.accounts.keys.list();           // which accounts have a credential out there
+await ai.accounts.keys.rotate("sito-1"); // issues a new one; the old one dies immediately
+await ai.accounts.keys.revoke("sito-1"); // the account stays, and becomes operable from here again
+```
+
+**One live key per account**: if one already exists, `issue` answers `409 CONTO_KEY_EXISTS` — use
+`rotate` to replace it. Two live credentials would make "revoke that site's key" ambiguous, and the
+case that would motivate them (a site cloned to staging) is better served by rotating.
+
+Issuing a key is **optional**: an account without one is not incomplete, it is an account you
+operate yourself.
+
+## Options
+
+```typescript
+new Fantastico({
+  // Required
+  apiKey: "sk-fant-prod-…",                   // project key, or account key `ck-fant-…`
+
+  // Optional
+  baseUrl: "https://fantastico.cc/api",       // control plane, including /api
+  defaultModel: "anthropic/claude-sonnet-5",
+  activitySessionId: "…",                     // continue an activity session (rare)
+  reserveUsd: 0.1,                            // USD reserved per tenant each round
+  maxTurns: 8,                                // max internal orchestrator turns
+  budgetMs: 90_000,                           // orchestration timeout
+  mcpTimeoutMs: 30_000,                       // per-MCP-call timeout
+  retry: { attempts: 2 },                     // transient provider errors; `false` disables
+  reasoning: { enabled: false },              // default for requests that don't carry their own
+});
+```
+
+## The credential picks the surface
+
+There is no option for this: **the key's prefix says it**, and saying it twice would mean being
+able to say it two different ways.
+
+| | `sk-fant-…` project key | `ck-fant-…` account key |
+|---|---|---|
+| Routes | `/api/runtime/*` | `/api/edge/*` |
+| Reach | every account in the project | **one** account, the credential's own |
+| Naming an account | yes (`user`, `userKey`) | **no**: there is no field for it |
+| `ai.accounts.*` | yes | `SURFACE_UNSUPPORTED` |
+| `ai.balance()` | `SURFACE_UNSUPPORTED` (use `accounts.get`) | yes |
+
+`ai.surface` tells you which of the two you got. A string that is neither is an error **at
+construction time**, not a 401 on every call.
+
+## The runtime key, when you need to see it
+
+The client mints it by itself on the first call and keeps it in memory for its TTL — there is no
+mode in which it does not. When you need to **hand it back** before it expires (every open key
+holds a `maxOpenKeys` slot until it settles):
+
+```typescript
+const key = await ai.runtimeKeys.ensure();   // mint now, if there isn't one already
+console.log(key.recordId, key.limitUsd, key.expiresAt, key.activitySessionId);
+// … use the client normally …
+const live = ai.runtimeKeys.current();       // the one in hand RIGHT NOW: may not be the same one
+if (live) await ai.runtimeKeys.revoke(live.recordId);
+```
+
+Neither returns the secret: it lives inside the `AuthClient` and never crosses the public surface.
+`ai.runtimeKeys.list()` lists the ones still open on the account — the answer to "what did I leave
+behind" after a restart, when memory holds nothing any more.
+
+Revoking the key currently in use also clears the client's in-memory copy, so the next call mints a
+fresh one instead of presenting a credential the provider no longer knows.
+
+## Activity session
+
+`ai.activitySessionId` is the id that groups this stretch of work's spend across the many runtime
+keys that pass through it. **It is not a credential**: it authorises nothing, and it belongs in
+logs and tickets, because the support query downstream is `WHERE activity_session_id = '…'`. It is
+`null` before the first mint, and it can **change on its own**: the control plane silently replaces
+one it no longer recognises, so re-read it rather than storing it once and for all.
+
+## Model
+
+The provider is always OpenRouter: any model available there can be used, not just Claude. Two
+levels:
+
+- **Default**, at client construction — `defaultModel` (above). Omitted, it is
+  `anthropic/claude-sonnet-5`.
+- **Per-call override** — the `model` field of `create()`/`createRaw()`:
+
+```typescript
+await ai.chat.completions.create({
+  messages: [{ role: "user", content: "..." }],
+  model: "openai/gpt-4o", // applies to this call only
+});
+```
+
+Omitted, the client's `defaultModel` stands.
+
+## Usage in the response
+
+```typescript
+response.usage = {
+  prompt_tokens: 1200,        // aggregated across ALL internal turns
+  completion_tokens: 450,
+  total_tokens: 1650,
+  internal_turns: 3,          // how many LLM turns it took
+  cache_creation_tokens: 0,
+  cache_read_tokens: 800,
+  reasoning_tokens: 0,        // already INSIDE completion_tokens, do not add it (see Reasoning)
+  mcp_calls: 2,               // how many MCP invocations
+  cost_usd: 0.0042,           // real cost reported by the LLM provider (not estimated)
+};
+```
+
+## Reasoning (thinking tokens)
+
+Thinking-capable models can reason before answering. On OpenRouter those tokens are **billed as
+output** and **count against the request's `max_tokens`** — so a model can spend the entire output
+budget reasoning and return **empty or truncated content**, with HTTP 200 and usage metered as
+usual.
+
+> **Why this is a trap rather than an error.** Structured extraction reads empty content as a valid
+> JSON `[]` — "nothing found": a plausible, metered, apparently successful, and wrong answer. A
+> document anonymizer ships a document with the real names still in it.
+
+The field goes to `create()` and `createRaw()`, in OpenRouter's own shape:
+
+```typescript
+await ai.chat.completions.createRaw({
+  messages: [...],
+  reasoning: { enabled: false },     // or { effort: "low" } | { max_tokens: 2000 }
+});
+```
+
+| Field | What it does |
+|---|---|
+| `enabled` | turns reasoning on (without `effort`, OpenRouter uses "medium") |
+| `effort` | `"none"`/`"minimal"`/`"low"`/`"medium"`/`"high"`/`"xhigh"`/`"max"` — **excludes** `max_tokens` |
+| `max_tokens` | explicit reasoning budget (Anthropic/Gemini style) — **excludes** `effort` |
+| `exclude` | reason, but do not return the reasoning |
+
+**The SDK has no global default**: omitted everywhere, the field is not sent at all and the model's
+and OpenRouter's own behaviour applies. On `create()` it applies to **every** turn of the
+orchestration.
+
+You can set it once per client, for requests that do not carry their own:
+
+```typescript
+const ai = new Fantastico({ apiKey: "sk-fant-prod-…", reasoning: { enabled: false } });
+```
+
+A per-request `reasoning` **replaces** the client default outright — no deep merge, so no field of
+the default survives inside the request's object.
+
+> ⚠️ Some models reason unconditionally. OpenRouter marks those `mandatory` and **rejects** an
+> explicit disable rather than ignoring it, so a client-wide `{ enabled: false }` would make them
+> unreachable through that client. Set it per request, or use a second client, if you mix them.
+
+To tell whether it happened, two numbers in the response: `usage.reasoning_tokens` (what the
+thinking cost — it is **inside** `completion_tokens`, so visible output is the difference) and
+`choices[0].finish_reason`, which is `"length"` when the ceiling was hit. Both are available on
+`create()` and on `createRaw()`.
+
+And when the budget went entirely to thinking, you do not have to notice it yourself — see
+[Empty completions](#empty-completions-are-errors-not-answers).
+
+## Empty completions are errors, not answers
+
+When `finish_reason` is `"length"`, there are no tool calls, and the content is empty or
+whitespace, both `create()` and `createRaw()` throw `EmptyCompletionError` instead of handing back
+an empty string.
+
+That combination is a failure wearing a 200: usage is billed, the response looks fine, and an empty
+string parses as a valid `[]` — "nothing found". The error carries what tells you what to do:
+
+```typescript
+import { EmptyCompletionError } from "@byte-42/fantastico-sdk";
+
+try {
+  const res = await ai.chat.completions.createRaw({ messages });
+} catch (err) {
+  if (err instanceof EmptyCompletionError) {
+    console.log(err.reasoningTokens, "of", err.completionTokens, "went to thinking");
+    console.log(err.maxTokens, err.model, err.message);
+  }
+}
+```
+
+`reasoningTokens > 0` means reasoning ate the answer: disable it or raise `max_tokens`.
+`reasoningTokens === 0` means the answer simply did not fit: raise `max_tokens`. On `create()` the
+numbers belong to the **failing turn**, not the whole orchestration.
+
+It is never retried and never triggers a re-mint: a new key changes nothing, and retrying would
+spend your money again on the same outcome.
+
+**Not flagged**, because a false positive would fail a response you would have used: `"length"`
+with non-empty content (truncated, but there — `finish_reason` already tells you), `"stop"` with
+empty content (a model choosing to say nothing), and empty content with `tool_calls` (the normal
+shape of a tool turn).
+
+## Your own tools: `createRaw()`
+
+`create()` is opaque: it resolves only the MCPs enabled on the project, and does not accept tools
+of yours. If you have your own tool-use loop (say an agent with application tools FANTASTICO knows
+nothing about), use `createRaw()` — **a single call**, no orchestration, with `tool_calls` handed
+back to you exactly as the model emits them:
+
+```typescript
+const res = await ai.chat.completions.createRaw({
+  messages: [
+    { role: "system", content: "You are an assistant working on a case file." },
+    { role: "user", content: "Close the matter" },
+  ],
+  tools: [{ type: "function", function: { name: "closeMatter", description: "…", parameters: {} } }],
+  user: "studio-rossi",   // same per-tenant budget as create()
+});
+
+if (res.choices[0].finish_reason === "tool_calls") {
+  // run the tool yourself, then call createRaw() again with the result as a
+  // { role: "tool", tool_call_id, content } message
+}
+```
+
+Runtime key and budget reservation are **the same** as `create()` — the only difference is that you
+drive the turn, calling `createRaw()` at each step of your own loop.
+
+To use FANTASTICO marketplace tools **as well** in the same loop (statutory search, for instance),
+add them explicitly and route execution through `ai.tools`:
+
+```typescript
+const fantasticoTools = await ai.tools.list();       // the project's tool definitions
+const res = await ai.chat.completions.createRaw({
+  messages, user,
+  tools: [...myTools, ...fantasticoTools],
+});
+// in the loop: your tool_call → you run it; a FANTASTICO tool_call → ai.tools.execute(name, args)
+```
+
+### Prompt caching (`cache_control`)
+
+`createRaw()` supports multi-part content with `cache_control: { type: "ephemeral" }` (Anthropic's
+format — see [`ChatContentPart`](src/types.ts)). **Verified empirically**: without pinning routing
+to Anthropic directly, the LLM provider may route to a sub-provider (e.g. Amazon Bedrock) that
+ignores `cache_control` without error — you silently pay full price. That is why `createRaw()`
+**pins** `provider: {order:["Anthropic"]}` automatically when it detects `cache_control` in the
+messages (override with `pinProvider: false`/`true` if you need something else).
+
+```typescript
+const res = await ai.chat.completions.createRaw({
+  messages: [
+    { role: "system", content: [{ type: "text", text: largeContext, cache_control: { type: "ephemeral" } }] },
+    { role: "user", content: "Summarise" },
+  ],
+});
+// The next turn with the SAME system block reads from cache (~90% cheaper on cached tokens —
+// measured: $0.0229 → $0.0019 on a ~9k-token block).
+```
+
+## Speech (text-to-speech)
+
+`ai.audio.speech.create()` is a drop-in for the OpenAI SDK's `audio.speech.create()`. It runs on
+the **same account and the same runtime key** as every other call: per-tenant budget reservation
+(`user`), re-mint on a rejected key, retries on transient errors. The spend lands on the key's
+usage at the provider exactly like a chat turn does, so it is metered and settled on the account
+without the client declaring anything.
+
+```typescript
+const res = await ai.audio.speech.create({
+  model: "mistralai/voxtral-mini-tts-2603",
+  input: "Good morning, this is a generated voice.",
+  voice: "en_paul_neutral",
+  response_format: "mp3",   // see below before setting it
+  user: "studio-rossi",     // same per-tenant budget as create()
+});
+fs.writeFileSync("voice.mp3", res.audio);   // Uint8Array
+res.contentType;    // "audio/mpeg" — or "audio/pcm;rate=24000;channels=1"
+res.generationId;   // the provider's generation id, for your logs
+```
+
+**Pick the voice (and the price) from the catalogue.** TTS models are **not** in
+`ai.models.list()`; they have their own list, with the voices each model accepts:
+
+```typescript
+const models = await ai.audio.speech.models();
+// [{ id, name, pricing: { prompt, completion }, supported_voices: ["Kore", "Puck", …], … }]
+```
+
+How to read `pricing`: when `completion` is `"0"`, `prompt` is USD **per character** of input text
+(nearly every model — verified: a 70-character sentence cost exactly 70 × `prompt`). When both are
+non-zero the model bills per token, text in and audio out (Gemini TTS). When `prompt` is `"0"` it
+bills per second of generated audio (Seed Audio). Some models declare no voices: they take the
+voice from `input_references` instead.
+
+**`response_format` is model-dependent and the catalogue does not say which one a model serves.**
+HeyGen and Gemini TTS return only `pcm` (asking for `mp3` is a 400 that says so); Mistral and
+ElevenLabs serve `mp3`. Left out, the field is **not sent** and the provider default (`pcm`)
+applies. Always read `contentType` on the result rather than assuming.
+
+There is no `usage.cost_usd` on the result, on purpose: the provider does not return it with the
+audio, and the figure that matters is the one the ledger measures from the key — it shows up in the
+account statement, grouped under the same activity session as the rest of the work.
+
+## OpenAI SDK compatibility
+
+The interface is a drop-in for the OpenAI SDK:
+
+```typescript
+// Before (OpenAI)
+import OpenAI from "openai";
+const ai = new OpenAI({ apiKey: "..." });
+
+// After (FANTASTICO) — same interface
+import { Fantastico } from "@byte-42/fantastico-sdk";
+const ai = new Fantastico({ apiKey: "sk-fant-prod-..." });
+
+// Your code does not change
+const res = await ai.chat.completions.create({ messages: [...] });
+```
+
+## Errors
+
+```typescript
+import { FantasticoError } from "@byte-42/fantastico-sdk";
+
+try {
+  await ai.chat.completions.create({ messages: [...] });
+} catch (err) {
+  if (err instanceof FantasticoError) {
+    console.log(err.code);   // "ALLOWANCE_EXHAUSTED" | "PROVIDER_CONTEXT_LENGTH_EXCEEDED" | …
+    console.log(err.status); // 402, 400, 500, …
+  }
+}
+```
+
+On the account routes the code arrives **untouched from the control plane** instead of being
+flattened into a generic one — it is the only thing that tells you what to do:
+
+| `code` | | What to do |
+|---|---|---|
+| `CONTO_KEY_EXISTS` | 409 | the account already has a key → `rotate` instead of `issue` |
+| `ALLOWANCE_EXHAUSTED` | 402 | the account is out of credit → top that account up |
+| `PROJECT_FUNDS_EXHAUSTED` | 402 | the project reserve is empty → everything has stopped |
+| `SCOPE_FORBIDDEN` | 403 | this project key lacks the powers for the operation |
+| `ILLEGAL_MOVEMENT` | 422 | no such live account in this project → create it before issuing a key |
+
+```typescript
+if (err.code === "CONTO_KEY_EXISTS") {
+  await ai.accounts.keys.rotate(userKey);
+}
+```
+
+Errors coming from the **LLM provider** carry a `PROVIDER_` prefix and the provider's own status,
+so you can tell who spoke — 403, for one, is used both by the control plane (unverified account,
+disabled account) and by the provider (moderation), and the remedies are opposite:
+
+| `code` | | What to do |
+|---|---|---|
+| `PROVIDER_CONTEXT_LENGTH_EXCEEDED` | 400 | the conversation no longer fits → trim history |
+| `PROVIDER_CONTENT_POLICY_VIOLATION` | 403 | the prompt was flagged → have the user rephrase |
+| `PROVIDER_PERMISSION_DENIED` | 403 | no access to that model or a guardrail blocked it |
+| `LLM_PROVIDER_ERROR` | 502 | two attempts failed — this is **not** a verdict about your funds |
+| `EMPTY_COMPLETION` | 502 | ceiling hit with no content → see [Empty completions](#empty-completions-are-errors-not-answers) |
+| `INTERNAL_ERROR` | 500 | an error the provider did not classify |
+
+429 and 503 are retried automatically (twice, exponential with jitter, honouring `Retry-After`); a
+502 or 504 is not, because the generation may have happened and the response been lost.
+
+If you inject your own `LlmClient`, throw the exported `ProviderError` to take part in the automatic
+remint on `401`/`402`; a plain `Error` is treated as an error and nothing more.
+
+## Licence
+
+MIT — Byte42 S.r.l. See [LICENSE](LICENSE).

package/dist/activity.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cosa sta facendo un turno mentre lo fa. `create()`/`resume()` risolvono l'intero turno in una
+ * chiamata: senza questi eventi chi aspetta vede solo "sto ragionando" per tutta la durata, anche
+ * quando il modello sta leggendo dieci documenti. Con `onEvent` il chiamante li riceve man mano
+ * che accadono, e `writeActivityStream` li porta fino al browser, dove il widget
+ * (`@byte42/genioai-chat-widget`, `readActivityStream`) li mostra sopra al composer.
+ *
+ * Il formato di trasporto è NDJSON, una riga per oggetto: `{"event":…}` per ogni evento, poi
+ * esattamente una `{"result":…}` (l'esito di create/resume) oppure una `{"error":…}`. Il widget
+ * ne tiene una copia propria (non importa questo pacchetto, si builda isolato): le due forme
+ * vanno cambiate insieme.
+ */
+export type ChatActivityEvent = 
+/** Il modello sta per essere chiamato (un turno del loop). */
+{
+    type: "thinking";
+    turn: number;
+}
+/** Un tool comincia a girare. `label` viene da `LocalToolDefinition.activityLabel`, se c'è. */
+ | {
+    type: "tool_start";
+    id: string;
+    name: string;
+    label?: string;
+}
+/** Il tool è finito; `ok: false` quando il suo esito è un `{ error }`. */
+ | {
+    type: "tool_end";
+    id: string;
+    name: string;
+    ok: boolean;
+    durationMs: number;
+};
+export type ChatActivityListener = (event: ChatActivityEvent) => void;
+/** Opzioni per turno di `create()`/`resume()` che non sono parte della richiesta al modello. */
+export interface ChatActivityOptions {
+    /**
+     * Chiamato per ogni evento del turno, in ordine. Un'eccezione qui dentro è ignorata: chi
+     * guarda il turno non deve poterlo far fallire.
+     */
+    onEvent?: ChatActivityListener;
+    /**
+     * Tool locali **per questa chiamata**, in aggiunta a quelli del client (con lo stesso nome vince
+     * questo). Dalla 0.19.0.
+     *
+     * Servono quando un client è condiviso fra parti diverse di un'applicazione — in Fantastico
+     * Studio, fra agenti diversi dello stesso conto — e ognuna deve offrire al modello solo le
+     * proprie funzioni: registrarle sul client (`addTool`) le darebbe a tutti. Per `resume()` vanno
+     * ripassati gli stessi: lo stato di una pausa non porta funzioni, solo nomi.
+     */
+    localTools?: import("./local-tools.js").RegisteredTool[];
+}
+/** Il `Content-Type` della risposta scritta da `writeActivityStream`. */
+export declare const ACTIVITY_STREAM_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+/**
+ * Esegue un turno inoltrando i suoi eventi come righe NDJSON a `write`, poi l'esito. Per un
+ * endpoint HTTP dell'host: si imposta `ACTIVITY_STREAM_CONTENT_TYPE`, si passa la `write` della
+ * risposta e si chiude la risposta quando la promessa si risolve.
+ *
+ * ```ts
+ * res.setHeader("Content-Type", ACTIVITY_STREAM_CONTENT_TYPE);
+ * await writeActivityStream((line) => res.write(line), (onEvent) =>
+ *   ai.chat.completions.create({ messages }, { onEvent }));
+ * res.end();
+ * ```
+ *
+ * Un errore del turno diventa una riga `{"error":{message,code}}` (lo stato HTTP è già partito
+ * con la prima riga, non lo si può più cambiare) e la promessa si risolve con `undefined`.
+ */
+export declare function writeActivityStream<T>(write: (line: string) => void, run: (onEvent: ChatActivityListener) => Promise<T>): Promise<T | undefined>;
+/** Un tool è andato male se il suo esito (la stringa che torna al modello) è un `{ error }`. */
+export declare function toolResultOk(result: string): boolean;

package/dist/activity.js

@@ -0,0 +1,22 @@
+export const ACTIVITY_STREAM_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
+export async function writeActivityStream(write, run) {
+    try {
+        const result = await run((event) => write(`${JSON.stringify({ event })}\n`));
+        write(`${JSON.stringify({ result })}\n`);
+        return result;
+    }
+    catch (err) {
+        const e = err;
+        write(`${JSON.stringify({ error: { message: e?.message ?? "Errore", code: e?.code } })}\n`);
+        return undefined;
+    }
+}
+export function toolResultOk(result) {
+    try {
+        const parsed = JSON.parse(result);
+        return !(parsed && typeof parsed === "object" && !Array.isArray(parsed) && "error" in parsed);
+    }
+    catch {
+        return true;
+    }
+}