tina4-nodejs 3.13.113 → 3.13.115

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

@@ -24,7 +24,10 @@ export interface ChatResponse {
 /**
  * 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.
+ * (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";
@@ -32,13 +35,50 @@ export type ContentPart = {
 } | {
     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[];
-export interface AiMessage {
+/**
+ * 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);
@@ -74,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;
@@ -91,24 +139,60 @@ export declare class Ai {
     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', ...} parts (ADR-0060). Malformed parts
-     * fail fast with AiConfigError, never reaching the wire.
+     * 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. Multimodal parts are translated per provider (ADR-0060):
-     *   - OpenAI/local: {type:'image_url', image_url:{url}}
-     *   - Anthropic:    {type:'image', source:{type:'base64'|'url', ...}}
+     * 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

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

@@ -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, AiEvent, ContentPart, AiMessageContent } 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";

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

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import type { Tina4Config } from "./types.js";
+import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router } from "./router.js";
 import { MiddlewareChain } from "./middleware.js";
 /** How long a graceful shutdown waits for in-flight requests, in seconds. */
@@ -167,6 +167,28 @@ export declare function stop(): void;
  * Useful for testing and embedding.
  */
 export declare function handle(rawReq: IncomingMessage, rawRes: ServerResponse): Promise<void>;
+/**
+ * Invoke a matched route's handler, binding path params BY NAME.
+ *
+ * A handler declares whatever it needs - `(id, request, response)`, `(req, res)`,
+ * or nothing - and each parameter is resolved by its name: a path param wins,
+ * then `request`/`req`, then the response.
+ */
+/**
+ * Resolve a handler's argument list to `[reqOrParam, resOrParam, ...]` values.
+ *
+ * By-name path preserved (route-param names, `req`/`request`, `res`/`response`)
+ * so existing code keeps its DX. Any remaining unmatched name falls back to
+ * POSITIONAL binding: first unmatched -> request, rest -> response. That makes
+ * dispatch bundler-safe by construction: Bun `--compile` and terser/esbuild
+ * identifier-mangling rename `(req, res)` to `(req2, r$0)` — the by-name path
+ * misses, the positional fallback catches, and the handler still receives the
+ * request as its first argument. Fixes #56.
+ *
+ * Exported so the regression test can pin the behaviour directly, without a
+ * live HTTP server.
+ */
+export declare function resolveHandlerArgs(handler: unknown, req: Tina4Request, res: Tina4Response, routeParams: Record<string, unknown>): unknown[];
 /**
  * Everything one request's dispatch needs beyond req/res: the resolved
  * router, middleware chain, filesystem roots and template engine a boot