tina4-nodejs 3.13.112 → 3.13.114

package/types/core/src/aiClient.d.ts

@@ -21,10 +21,92 @@ export interface ChatResponse {
     finishReason: string | null;
     raw: Record<string, unknown>;
 }
-export interface AiMessage {
+/**
+ * A multimodal content part. `text` carries plain UTF-8 prose; `image`
+ * carries a `data:<media_type>;base64,<payload>` URI or an https:// URL
+ * (the client translates to each provider's shape, ADR-0060). `tool_result`
+ * carries the Anthropic-style return of a locally-executed tool call
+ * (ADR-0061); the client translates it to OpenAI's `{role: "tool", ...}`
+ * turn on non-Anthropic providers.
+ */
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: string;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+};
+/** The value a caller may pass for `message.content`. ADR-0060. */
+export type AiMessageContent = string | ContentPart[];
+/**
+ * One conversation turn. The three "chat" roles carry a string OR a
+ * content-parts array (ADR-0060). The `tool` role is the OpenAI-style
+ * return of a tool call (ADR-0061); the client translates it to the
+ * Anthropic user-turn form when the current provider is Anthropic.
+ */
+export type AiMessage = {
     role: "system" | "user" | "assistant";
+    content: AiMessageContent;
+} | {
+    role: "tool";
+    tool_call_id: string;
     content: string;
+};
+/**
+ * A tool declaration the model may call (named `AiToolDeclaration` to
+ * stay out of the way of {@link ./ai.ts}'s existing `AiTool` interface
+ * for AI-coding-tool context installation). `parameters` is a JSON
+ * Schema object; it is passed to the provider unchanged (ADR-0061
+ * `parameters-passthrough`).
+ */
+export interface AiToolDeclaration {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
 }
+/**
+ * How the model picks a tool. Four Tina4 values that span the useful cases
+ * across providers (ADR-0061 wire-translation table):
+ *   'auto'       — model may call any tool or answer with text
+ *   'none'       — model must not call a tool (Anthropic omits `tools`)
+ *   'required'   — model must call some tool
+ *   {name: 'x'}  — model must call tool 'x'
+ */
+export type AiToolChoice = "auto" | "none" | "required" | {
+    name: string;
+};
+/**
+ * One event yielded by `Ai.chat(stream: true)`. The four variants
+ * discriminated by `type`. Text deltas arrive per chunk (typewriter UX);
+ * `tool_call` fires once per call, aggregated from provider fragments;
+ * `done` fires exactly once after all deltas; `error` replaces `done` on
+ * mid-stream failure. ADR-0060.
+ */
+export type AiEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "done";
+    finishReason: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+} | {
+    type: "error";
+    message: string;
+    code?: string;
+};
 export interface AiChatOptions {
     model?: string;
     temperature?: number;
@@ -32,6 +114,14 @@ export interface AiChatOptions {
     stream?: boolean;
     timeout?: number;
     provider?: "local" | "openai" | "anthropic";
+    /** Tools the model may call. ADR-0061 — translated per provider. */
+    tools?: AiToolDeclaration[];
+    /**
+     * How the model picks a tool. ADR-0061 — translated per provider. If
+     * `'none'` on Anthropic (which has no "none" mode), `tools` is omitted
+     * from the outbound body entirely.
+     */
+    toolChoice?: AiToolChoice;
 }
 export interface AiEmbedOptions {
     model?: string;
@@ -41,26 +131,89 @@ export interface AiEmbedOptions {
 export declare class Ai {
     static chat(messages: AiMessage[], options: AiChatOptions & {
         stream: true;
-    }): AsyncGenerator<string>;
+    }): AsyncGenerator<AiEvent>;
     static chat(messages: AiMessage[], options?: AiChatOptions & {
         stream?: false;
     }): Promise<ChatResponse>;
     static complete(prompt: string, options?: Omit<AiChatOptions, "stream">): Promise<string>;
     static embed(textOrTexts: string | string[], options?: AiEmbedOptions): Promise<number[] | number[][]>;
+    /**
+     * Validate role + content shape. Content may be a string OR a non-empty
+     * list of {type:'text'|'image'|'tool_result', ...} parts (ADR-0060 +
+     * ADR-0061). The `tool` role is the OpenAI-style tool-result turn
+     * (ADR-0061). Malformed parts fail fast with AiConfigError, never
+     * reaching the wire.
+     */
     private static validateMessages;
+    private static validateContent;
+    /**
+     * Validate the outbound tool declarations (ADR-0061). Each tool needs a
+     * non-empty `name`, a string `description`, and a JSON-Schema-shaped
+     * `parameters` object. Malformed tools fail fast with AiConfigError,
+     * never reaching the wire.
+     */
+    private static validateTools;
+    /**
+     * Validate the outbound tool_choice value (ADR-0061). The four accepted
+     * shapes are 'auto', 'none', 'required', and {name: 'x'}.
+     */
+    private static validateToolChoice;
     private static number;
     private static config;
     private static endpoint;
     private static headers;
+    /**
+     * Build the provider-specific request body from a Tina4-shaped message
+     * list plus optional tool declarations (ADR-0060 + ADR-0061).
+     *
+     * Content parts translate per provider:
+     *   - OpenAI/local: image → {type:'image_url', image_url:{url}}
+     *   - Anthropic:    image → {type:'image', source:{type:'base64'|'url', ...}}
+     * String content is preserved verbatim in the OpenAI/local shape and
+     * likewise for Anthropic (both accept a bare string).
+     *
+     * Tool-result turns are normalised to the current provider's expected
+     * shape (either the OpenAI `{role:"tool", tool_call_id, content}` turn or
+     * the Anthropic `{role:"user", content:[{type:"tool_result", ...}]}`
+     * turn), so an agent-loop written against Tina4 never has to fork on
+     * TINA4_AI_PROVIDER (ADR-0061 wire translation).
+     */
     private static chatBody;
+    /**
+     * Normalise the Tina4-shaped messages into the provider's on-wire shape.
+     * The `tool` role and the `tool_result` content part are translated
+     * between the OpenAI and Anthropic forms so either input works against
+     * either provider (ADR-0061 return-path table).
+     */
+    private static normalizeMessagesForProvider;
+    /**
+     * Attach the outbound `tools` and `tool_choice` (ADR-0061 outbound
+     * translation tables) to the body in place. When toolChoice is 'none'
+     * on Anthropic (Anthropic has no "none" mode) the tools list is omitted
+     * entirely — the model cannot call what it cannot see.
+     */
+    private static applyTools;
+    /**
+     * Translate one message content value into the provider's on-wire shape.
+     * A plain string is passed through (both providers accept a string
+     * content). A parts array becomes provider-native content blocks.
+     */
+    private static translateContent;
+    private static parseDataUri;
+    private static contentToPlainText;
     private static open;
     private static readBody;
     private static retryDelay;
     private static requestJson;
     private static normalizeChat;
     private static chatResponse;
-    private static streamDelta;
-    private static streamData;
-    private static streamError;
+    /**
+     * Stream the response through the shared {@link parseSseStream} framer
+     * (ADR-0060 rule 5). Translates each SSE data payload into 0..N
+     * {@link AiEvent}s: text_delta per chunk, tool_call aggregated per
+     * index / block, exactly one done (or error) at the end.
+     */
     private static streamRequest;
+    private static responseChunks;
+    private static streamError;
 }

package/types/core/src/api.d.ts

@@ -4,6 +4,38 @@ export interface ApiResult {
     headers: Record<string, string>;
     error: string | null;
 }
+/**
+ * Options for the streaming primitives ({@link Api.streamBytes},
+ * {@link Api.streamLines}, {@link Api.streamSse}). All fields optional.
+ * `timeout` bounds the WHOLE stream (headers + body), matching
+ * `TINA4_API_TIMEOUT`; `connectTimeout` bounds only the connection +
+ * headers-arrival phase, matching `TINA4_API_CONNECT_TIMEOUT`.
+ */
+export interface StreamOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    contentType?: string;
+    timeout?: number;
+    connectTimeout?: number;
+}
+/**
+ * One SSE event yielded by {@link Api.streamSse}. `data` is always present
+ * (multi-line `data:` fields are concatenated with `\n`). `event`, `id`,
+ * `retry` are set only when the corresponding SSE field appeared. `retry`
+ * is a number (milliseconds) per the SSE spec.
+ */
+export interface SseEvent {
+    data: string;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+/** Raised by the streaming primitives on a non-2xx status. */
+export declare class ApiStreamError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
 /**
  * Result of {@link Api.download}. There is no `body` field — the response
  * body went to disk. `path` is the destination on success and `null` on any
@@ -90,6 +122,28 @@ export interface ApiOptions {
      */
     cookies?: boolean;
 }
+/**
+ * Split an async byte iterable into UTF-8 lines. Handles LF and CRLF; a
+ * multibyte codepoint that lands across a chunk boundary buffers across the
+ * split (TextDecoder({stream: true})). A trailing line without a terminator
+ * yields on EOF.
+ *
+ * Exported so {@link Api} instance methods AND `Ai.chat` streaming share
+ * one framer — ADR-0060's "no duplicate framing code" rule.
+ */
+export declare function parseLineStream(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<string>;
+/**
+ * Parse SSE (Server-Sent Events) framing from a line iterable. Yields
+ * one {@link SseEvent} per event boundary (blank line) or on EOF for a
+ * final trailing event. `:` comment lines are ignored. Fields are
+ * `data` (multi-line concatenated with `\n`), `event`, `id`, `retry`.
+ *
+ * Follows the WHATWG SSE parsing algorithm closely enough for every LLM
+ * provider (OpenAI, Anthropic, local): one leading space after the colon
+ * is stripped, unknown fields are ignored, malformed `retry:` values are
+ * ignored.
+ */
+export declare function parseSseStream(lines: AsyncIterable<string>): AsyncGenerator<SseEvent>;
 export declare class Api {
     private baseUrl;
     private headers;
@@ -209,6 +263,54 @@ export declare class Api {
      * not written on error.
      */
     download(path: string, destPath: string, params?: Record<string, string>): Promise<DownloadResult>;
+    /**
+     * Stream a response body as raw bytes. Yields the chunks the transport
+     * delivers, in order, never buffered whole. Ends cleanly on EOF and
+     * throws on a transport failure or a non-2xx status (body drained
+     * first). No JSON decoding, no line splitting, no framing —
+     * {@link streamLines} and {@link streamSse} build on this primitive.
+     *
+     * Closing the iterator before EOF (a `break` out of a `for await`)
+     * destroys the underlying socket, so a caller who takes only the
+     * first few chunks never leaks the connection.
+     *
+     * `opts.timeout` bounds the whole stream duration (default
+     * `TINA4_API_TIMEOUT` or the client `timeout`); `opts.connectTimeout`
+     * bounds just the connect + headers phase (default
+     * `TINA4_API_CONNECT_TIMEOUT` or 10s).
+     */
+    streamBytes(path: string, opts?: StreamOptions): AsyncGenerator<Uint8Array>;
+    /**
+     * Stream the response body as UTF-8 lines. Splits on LF or CRLF;
+     * buffers a multibyte codepoint that lands across a chunk boundary;
+     * yields a trailing line without a terminator on EOF. Built on
+     * {@link streamBytes} plus the shared {@link parseLineStream}.
+     */
+    streamLines(path: string, opts?: StreamOptions): AsyncGenerator<string>;
+    /**
+     * Stream the response as SSE (Server-Sent Events). Yields one
+     * {@link SseEvent} per event boundary (blank line) or on EOF for a
+     * trailing event. `data:[DONE]` is delivered as an ordinary event
+     * with `data === "[DONE]"` and the iterator ends on the next EOF.
+     * Built on {@link streamLines} plus the shared {@link parseSseStream}.
+     */
+    streamSse(path: string, opts?: StreamOptions): AsyncGenerator<SseEvent>;
+    /**
+     * Resolve a stream duration from (in order): explicit `opts` field,
+     * the named env var, then the fallback. Zero disables. A non-numeric
+     * or negative env value warns via a fallback rather than throwing —
+     * a bad env var must not brick every streaming call.
+     */
+    private streamSeconds;
+    /**
+     * Open a streaming HTTP request. Returns the raw
+     * {@link http.IncomingMessage} once headers arrive. Redirects are NOT
+     * followed on streams (a caller who needs a redirect should do a
+     * regular GET first). Connect phase is bounded by `connectSec`;
+     * body-phase timeout is applied by the caller (streamBytes) via
+     * `res.destroy()`.
+     */
+    private openStreamRequest;
     private buildUrl;
     /**
      * Build the request headers (default User-Agent + auth + cookie jar +

package/types/core/src/index.d.ts

@@ -39,8 +39,8 @@ export { ServiceRunner, Tina4Service, matchCronField, matchesCron } from "./serv
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
-export { Api } from "./api.js";
-export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions } from "./api.js";
+export { Api, ApiStreamError, parseLineStream, parseSseStream } from "./api.js";
+export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions, StreamOptions, SseEvent } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";
 export { Events } from "./events.js";
@@ -58,7 +58,7 @@ export type { AiTool } from "./ai.js";
 export { Sso, SSO, SsoError } from "./sso.js";
 export type { SsoOptions } from "./sso.js";
 export { Ai, AiError, AiConfigError, AiHTTPError, AiTimeoutError, AiParseError } from "./aiClient.js";
-export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions } from "./aiClient.js";
+export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions, AiEvent, ContentPart, AiMessageContent, AiToolDeclaration, AiToolChoice } from "./aiClient.js";
 export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";