nuabase 2.3.3 → 2.3.5

package/dist/types/__tests__/helpers/client-factory.d.ts

@@ -1,17 +1,39 @@
 import { Nua } from '../../nua';
-export type TestMode = 'gateway' | 'direct';
+import type { LocalAgentId } from '../../nua-llm-core/index';
 /**
- * Creates a Nua client for the specified test mode.
- *
- * Gateway mode: Requires api-server running on localhost:3030
- * Direct mode: Requires one of GROQ_API_KEY, OPENROUTER_API_KEY, CEREBRAS_API_KEY, or GEMINI_API_KEY
- *
- * @param mode - 'gateway' or 'direct'
- * @returns Configured Nua instance
+ * One way of running casts that the shared tests exercise:
+ * - gateway: the Nuabase API at NUABASE_API_URL
+ * - direct: LLM providers' APIs, with API keys
+ * - local-agent: a coding-agent CLI on this machine, with its own login
  */
-export declare function createTestClient(mode: TestMode): Nua;
+export type TestMode = {
+    name: string;
+} & ({
+    kind: 'gateway';
+} | {
+    kind: 'direct';
+} | {
+    kind: 'local-agent';
+    agent: LocalAgentId | 'auto';
+});
 /**
- * Returns the list of test modes to run based on environment.
- * Respects SKIP_DIRECT_TESTS and SKIP_GATEWAY_TESTS env vars.
+ * Returns the modes to run the shared tests in.
+ * - gateway, unless SKIP_GATEWAY_TESTS is set.
+ * - direct, when a provider API key is set, unless SKIP_DIRECT_TESTS is set.
+ * - one local-agent mode per agent in NUA_LOCAL_AGENTS (e.g. "claude-code,codex", or "auto").
  */
 export declare function getTestModes(): TestMode[];
+/**
+ * Creates a Nua client for the specified test mode.
+ *
+ * Gateway mode: Requires NUABASE_API_URL and NUABASE_API_KEY for a running Nuabase API
+ * Direct mode: Requires one of GROQ_API_KEY, OPENROUTER_API_KEY, CEREBRAS_API_KEY, or GEMINI_API_KEY
+ * Local-agent mode: Requires that agent installed and logged in on this machine
+ */
+export declare function createTestClient(mode: TestMode): Promise<Nua>;
+/** The result `source` a mode produces: local agents run through the direct backend. */
+export declare function expectedSource(mode: TestMode): 'gateway' | 'direct';
+/** The part of a direct result's `meta` that says which engine answered. */
+export declare function expectedDirectMeta(mode: TestMode): Record<string, unknown>;
+/** Per-test time limit. A coding-agent CLI starts a process and may reason before answering. */
+export declare function testTimeoutMs(mode: TestMode): number;

package/dist/types/__tests__/helpers/index.d.ts

@@ -1 +1,2 @@
-export { createTestClient, getTestModes, TestMode } from './client-factory';
+export { createTestClient, expectedDirectMeta, expectedSource, getTestModes, testTimeoutMs, } from './client-factory';
+export type { TestMode } from './client-factory';

package/dist/types/backend/direct.d.ts

@@ -1,16 +1,28 @@
 import { CastArrayParams, CastResult, CastValueParams, LlmBackend } from './types';
-import { LlmProviderId } from 'nua-llm-core';
-export type DirectConfig = {
-    model: string;
-    providers: {
-        [key in LlmProviderId]?: {
-            apiKey: string;
-        };
+import type { LlmProviderId, ModelInput } from '../nua-llm-core/index';
+import type { LocalAgent } from '../nua-llm-core/local-agent';
+/** API keys for the LLM providers direct mode may call. */
+export type ProviderApiKeys = {
+    [key in LlmProviderId]?: {
+        apiKey: string;
     };
 };
+/**
+ * Either `providers`: API keys for LLM providers, with an optional default `model`.
+ * Or `localAgent`: a coding-agent CLI on this machine, from `localAgent()` or
+ * `findLocalAgent()` in "nuabase/local-agent".
+ */
+export type DirectConfig = {
+    providers: ProviderApiKeys;
+    model?: ModelInput;
+    localAgent?: never;
+} | {
+    localAgent: LocalAgent;
+    providers?: never;
+    model?: never;
+};
 export declare class DirectBackend implements LlmBackend {
     private readonly client;
-    private readonly model;
     constructor(config: DirectConfig);
     castValue<T>(params: CastValueParams): Promise<CastResult<T>>;
     castArray<T>(params: CastArrayParams): Promise<CastResult<T[]>>;

package/dist/types/backend/types.d.ts

@@ -1,9 +1,10 @@
+import type { AnswerOrigin, ModelInput, SchemaEnforcementKind } from '../nua-llm-core/index';
 export type CastValueParams = {
     prompt: string;
     data: unknown;
     outputName: string;
     outputSchema: object;
-    model?: string;
+    model?: ModelInput;
 };
 export type CastArrayParams = {
     prompt: string;
@@ -11,7 +12,7 @@ export type CastArrayParams = {
     primaryKey: string;
     outputName: string;
     outputSchema: object;
-    model?: string;
+    model?: ModelInput;
 };
 export type NormalizedUsage = {
     promptTokens: number;
@@ -24,7 +25,11 @@ export type GatewayMeta = {
     llmUsage: NormalizedUsage;
     cacheUsage: NormalizedUsage;
 };
-export type DirectMeta = unknown;
+export type DirectMeta = AnswerOrigin & {
+    /** How the output schema was enforced. The result is validated against the schema either way. */
+    schemaEnforcement: SchemaEnforcementKind;
+};
+export type CastResultSource = 'gateway' | 'direct';
 type CastResultSuccess<T> = {
     success: true;
     data: T;
@@ -41,7 +46,7 @@ type CastResultSuccess<T> = {
 type CastResultFailure = {
     success: false;
     error: string;
-    source: 'gateway' | 'direct';
+    source: CastResultSource;
     latencyMs: number;
 };
 export type CastResult<T> = CastResultSuccess<T> | CastResultFailure;

package/dist/types/index.d.cts

@@ -1,6 +1,7 @@
 export { Nua } from './nua';
 export type { OutputDef, GetOptions, ListOptions, ListResultRow } from './nua';
-export type { LlmBackend, CastResult, CastValueParams, CastArrayParams, NormalizedUsage, GatewayMeta, DirectMeta, QueueResult, } from './backend/types';
+export type { LlmBackend, CastResult, CastValueParams, CastArrayParams, NormalizedUsage, GatewayMeta, DirectMeta, CastResultSource, QueueResult, } from './backend/types';
 export type { GatewayConfig } from './backend/gateway';
-export type { DirectConfig } from './backend/direct';
+export type { DirectConfig, ProviderApiKeys } from './backend/direct';
+export type { AnswerOrigin, LocalAgentId, ModelInput, SchemaEnforcementKind } from './nua-llm-core/index';
 export { z } from 'zod';

package/dist/types/index.d.mts

@@ -1,6 +1,7 @@
 export { Nua } from './nua';
 export type { OutputDef, GetOptions, ListOptions, ListResultRow } from './nua';
-export type { LlmBackend, CastResult, CastValueParams, CastArrayParams, NormalizedUsage, GatewayMeta, DirectMeta, QueueResult, } from './backend/types';
+export type { LlmBackend, CastResult, CastValueParams, CastArrayParams, NormalizedUsage, GatewayMeta, DirectMeta, CastResultSource, QueueResult, } from './backend/types';
 export type { GatewayConfig } from './backend/gateway';
-export type { DirectConfig } from './backend/direct';
+export type { DirectConfig, ProviderApiKeys } from './backend/direct';
+export type { AnswerOrigin, LocalAgentId, ModelInput, SchemaEnforcementKind } from './nua-llm-core/index';
 export { z } from 'zod';

package/dist/types/local-agent.d.cts

@@ -0,0 +1,2 @@
+export { detectLocalAgents, findLocalAgent, isLocalAgentId, LOCAL_AGENT_IDS, localAgent, } from './nua-llm-core/local-agent';
+export type { LocalAgent, LocalAgentAuthMode, LocalAgentConfig, LocalAgentId, LocalAgentOptions, LocalAgentStatus, } from './nua-llm-core/local-agent';

package/dist/types/local-agent.d.mts

@@ -0,0 +1,2 @@
+export { detectLocalAgents, findLocalAgent, isLocalAgentId, LOCAL_AGENT_IDS, localAgent, } from './nua-llm-core/local-agent';
+export type { LocalAgent, LocalAgentAuthMode, LocalAgentConfig, LocalAgentId, LocalAgentOptions, LocalAgentStatus, } from './nua-llm-core/local-agent';

package/dist/types/nua-llm-core/index.d.ts

@@ -0,0 +1,23 @@
+export * from "./nua-llm-client";
+export * from "./lib/logger";
+export * from "./lib/types";
+export * from "./lib/nua-errors";
+export { LLM_PROVIDER_IDS, normalizedUsageZero, providerConfigs, } from "./modules/engine/http/provider-config";
+export type { LlmProviderId } from "./modules/engine/http/provider-config";
+export { providerEngines } from "./modules/engine/http/provider-engines";
+export type { ProviderEngines, ProviderEnginesConfig } from "./modules/engine/http/provider-engines";
+export type { EngineRouter, Route } from "./modules/engine/engine-router";
+export type { AnswerOrigin, LlmEngine, SchemaEnforcementKind, } from "./modules/engine/llm-engine";
+export type { LocalAgentId } from "./modules/engine/local-agent/agent-id";
+export { validateJsonSchema } from "./modules/json-schema-validation/validate-json-schema";
+export { stableStringify } from "./lib/stable-stringify";
+export * from "./modules/model-info";
+export * from "./lib/schema-utils";
+export { listSchema, parseListSchema } from "./modules/cast/list-schema";
+export type { ListRowKeys, ListSchema } from "./modules/cast/list-schema";
+export type { CastResult, CastSuccess, CastFailure } from "./modules/cast/run-cast";
+export type { RenderedPrompt } from "./modules/cast/cast-request";
+export type { ToolDefinition, ToolExecutionResult, AgentTool, TextContent, ToolCallContent, AssistantContentBlock, UserMessage, AssistantMessage, ToolResultMessage, ConversationMessage, AgenticParsedResponse, AgentRunParams, AgentCompletionReason, AgentResult, AgentEvent, AgentEventHandler, } from "./modules/agent/types";
+export { runAgent } from "./modules/agent/run-agent";
+export { runAgentLoop } from "./modules/agent/agent-loop";
+export type { SendAgenticRequestFn } from "./modules/agent/agent-loop";

package/dist/types/nua-llm-core/lib/error-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Safely extracts an error message from an unknown value.
+ * @param error The unknown value caught in a catch block.
+ * @returns A string representing the error message.
+ */
+export declare function getErrorMessageFromException(error: unknown): string;

package/dist/types/nua-llm-core/lib/logger.d.ts

@@ -0,0 +1,44 @@
+export interface Logger {
+    debug(message: string, context?: object): void;
+    info(message: string, context?: object): void;
+    warn(message: string, context?: object): void;
+    error(message: string, context?: object): void;
+}
+export declare class ConsoleLogger implements Logger {
+    debug(message: string, context?: object): void;
+    info(message: string, context?: object): void;
+    warn(message: string, context?: object): void;
+    error(message: string, context?: object): void;
+}
+export declare const generateSpanId: () => string;
+/**
+ * Generic header filtering with allowlist and optional redaction
+ */
+export declare function pickHeaders(headers: Record<string, string | string[] | undefined>, allowlist: Set<string>, redactSet?: Set<string>): Record<string, string>;
+/**
+ * Error normalization for logging
+ */
+export declare function normalizeError(error: unknown): {
+    message: string;
+    stack?: string;
+} | string;
+interface LlmRequestLog {
+    url: string;
+    httpMethod: string;
+    model: string;
+    maxTokens: number;
+}
+interface LlmResponseLog {
+    status: number;
+    responseLength: number;
+    headers: Record<string, string>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+export declare const logLlmCallStart: (logger: Logger, spanId: string, service: string, method: string, request: LlmRequestLog) => void;
+export declare const logLlmCallComplete: (logger: Logger, spanId: string, service: string, method: string, response: LlmResponseLog, duration: number) => void;
+export declare const logLlmCallError: (logger: Logger, spanId: string, service: string, method: string, error: unknown, duration: number) => void;
+export {};

package/dist/types/nua-llm-core/lib/nua-errors.d.ts

@@ -0,0 +1,12 @@
+export type NuaError = NuaInternalError | NuaValidationError;
+export type NuaValidationError = {
+    kind: "validation-error";
+    message: string;
+};
+export declare const isNuaValidationError: (a: unknown) => a is NuaValidationError;
+export type NuaInternalError = {
+    kind: "internal-error";
+    message: string;
+};
+export declare const isNuaInternalError: (a: unknown) => a is NuaInternalError;
+export declare const isNuaError: (a: unknown) => a is NuaError;

package/dist/types/nua-llm-core/lib/prompt-template-utils.d.ts

@@ -0,0 +1,2 @@
+export declare const templateVarName: (varName: string) => string;
+export declare const replaceTemplateVarName: (str: string, varName: string, value: string) => string;

package/dist/types/nua-llm-core/lib/schema-utils.d.ts

@@ -0,0 +1 @@
+export type JsonSchema = Record<string, unknown>;

package/dist/types/nua-llm-core/lib/stable-stringify.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(value: unknown): string;

package/dist/types/nua-llm-core/lib/strict-json-schema.d.ts

@@ -0,0 +1,7 @@
+import { JsonSchema } from "./schema-utils";
+/**
+ * Converts a schema to OpenAI strict mode, or returns null when that would
+ * change which values are valid (optional properties, open-ended objects,
+ * unsupported keywords).
+ */
+export declare function toStrictSchema(schema: JsonSchema): JsonSchema | null;

package/dist/types/nua-llm-core/lib/types.d.ts

@@ -0,0 +1,8 @@
+export type UserDataPKValue = string | number;
+export type MappableInputDataRow = Record<string, unknown>;
+export type MappableInputData = MappableInputDataRow[];
+export type NormalizedUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};

package/dist/types/nua-llm-core/lib/validate-mappable-input-data.d.ts

@@ -0,0 +1,4 @@
+import { NuaValidationError } from "./nua-errors";
+export type MappableInputDataRow = Record<string, unknown>;
+export type MappableInputData = MappableInputDataRow[];
+export declare function validateMappableInputData(data: unknown, primaryKey: string | null): NuaValidationError | MappableInputData;

package/dist/types/nua-llm-core/local-agent.d.ts

@@ -0,0 +1,7 @@
+export { findLocalAgent, localAgent } from "./modules/engine/local-agent/create-local-agent";
+export type { LocalAgentAuthMode, LocalAgentConfig, LocalAgentOptions, } from "./modules/engine/local-agent/create-local-agent";
+export type { LocalAgent } from "./modules/engine/local-agent/local-agent";
+export { detectLocalAgents } from "./modules/engine/local-agent/detect";
+export type { LocalAgentStatus } from "./modules/engine/local-agent/detect";
+export { LOCAL_AGENT_IDS, isLocalAgentId } from "./modules/engine/local-agent/agent-id";
+export type { LocalAgentId } from "./modules/engine/local-agent/agent-id";

package/dist/types/nua-llm-core/modules/agent/agent-loop.d.ts

@@ -0,0 +1,10 @@
+import { AgentEventHandler, AgentResult, AgentTool, AgenticParsedResponse, ConversationMessage } from "./types";
+export type SendAgenticRequestFn = (messages: ConversationMessage[], tools: AgentTool[], systemPrompt?: string) => Promise<AgenticParsedResponse>;
+export declare function runAgentLoop(params: {
+    messages: ConversationMessage[];
+    tools: AgentTool[];
+    systemPrompt?: string;
+    maxTurns: number;
+    sendRequest: SendAgenticRequestFn;
+    onEvent?: AgentEventHandler;
+}): Promise<AgentResult>;

package/dist/types/nua-llm-core/modules/agent/agent-turn.d.ts

@@ -0,0 +1,17 @@
+import { Logger } from "../../lib/logger";
+import { ProviderTarget } from "../engine/http/provider-call";
+import { AgentEventHandler, AgenticParsedResponse, ConversationMessage, ToolDefinition } from "./types";
+export type AgentTurn = {
+    target: ProviderTarget;
+    maxTokens: number;
+    messages: ConversationMessage[];
+    tools: ToolDefinition[];
+    systemPrompt?: string;
+    /** When set, the reply is streamed and reported through it as it arrives. */
+    onEvent?: AgentEventHandler;
+};
+/**
+ * Sends one turn of a tool-calling conversation to an LLM provider's HTTP API.
+ * Throws when the call fails; the agent loop reports that as the end of the conversation.
+ */
+export declare function sendAgentTurn(turn: AgentTurn, logger: Logger): Promise<AgenticParsedResponse>;

package/dist/types/nua-llm-core/modules/agent/provider-formatters.d.ts

@@ -0,0 +1,22 @@
+import { ProviderRequestBase } from "../engine/http/provider-config";
+import { AgentEventHandler, AgenticParsedResponse, ConversationMessage, ToolDefinition } from "./types";
+export declare function buildOpenAiAgenticRequest(options: {
+    messages: ConversationMessage[];
+    tools: ToolDefinition[];
+    model: string;
+    maxTokens: number;
+    systemPrompt?: string;
+    stream?: boolean;
+}, baseUrl: string, apiKey: string): ProviderRequestBase;
+export declare function parseOpenAiAgenticResponse(response: Response, errorLabel: string): Promise<AgenticParsedResponse>;
+export declare function buildGeminiAgenticRequest(options: {
+    messages: ConversationMessage[];
+    tools: ToolDefinition[];
+    model: string;
+    maxTokens: number;
+    systemPrompt?: string;
+    stream?: boolean;
+}, apiKey: string): ProviderRequestBase;
+export declare function parseGeminiAgenticResponse(response: Response): Promise<AgenticParsedResponse>;
+export declare function streamOpenAiAgenticResponse(response: Response, errorLabel: string, onEvent?: AgentEventHandler): Promise<AgenticParsedResponse>;
+export declare function streamGeminiAgenticResponse(response: Response, onEvent?: AgentEventHandler): Promise<AgenticParsedResponse>;

package/dist/types/nua-llm-core/modules/agent/run-agent.d.ts

@@ -0,0 +1,7 @@
+import { ProviderEngines } from "../engine/http/provider-engines";
+import { AgentResult, AgentRunParams } from "./types";
+/**
+ * Runs a multi-turn, tool-calling conversation on an LLM provider's API. It needs
+ * the providers' API directly, so it takes provider engines rather than any engine router.
+ */
+export declare function runAgent(providers: ProviderEngines, params: AgentRunParams): Promise<AgentResult>;

package/dist/types/nua-llm-core/modules/agent/types.d.ts

@@ -0,0 +1,90 @@
+import { NormalizedUsage } from "../engine/http/provider-config";
+import { ModelInput } from "../model-info";
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+export type ToolExecutionResult = {
+    content: string;
+    isError?: boolean;
+};
+export type AgentTool = ToolDefinition & {
+    execute: (args: Record<string, unknown>) => Promise<ToolExecutionResult>;
+};
+export type TextContent = {
+    type: "text";
+    text: string;
+};
+export type ToolCallContent = {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+};
+export type AssistantContentBlock = TextContent | ToolCallContent;
+export type UserMessage = {
+    role: "user";
+    content: string;
+};
+export type AssistantMessage = {
+    role: "assistant";
+    content: AssistantContentBlock[];
+};
+export type ToolResultMessage = {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: string;
+    isError: boolean;
+};
+export type ConversationMessage = UserMessage | AssistantMessage | ToolResultMessage;
+export type AgenticParsedResponse = {
+    message: AssistantMessage;
+    usage: NormalizedUsage;
+    stopReason: "stop" | "tool_use";
+};
+export type AgentEvent = {
+    type: "turn_start";
+    turn: number;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "response_complete";
+    message: AssistantMessage;
+    usage: NormalizedUsage;
+    stopReason: "stop" | "tool_use";
+} | {
+    type: "tool_start";
+    toolCallId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: "tool_complete";
+    toolCallId: string;
+    toolName: string;
+    result: ToolExecutionResult;
+} | {
+    type: "error";
+    error: string;
+};
+export type AgentEventHandler = (event: AgentEvent) => void;
+export type AgentRunParams = {
+    model?: ModelInput;
+    systemPrompt?: string;
+    messages: ConversationMessage[];
+    tools: AgentTool[];
+    maxTokens?: number;
+    maxTurns?: number;
+    onEvent?: AgentEventHandler;
+};
+export type AgentCompletionReason = "stop" | "max_turns" | "error";
+export type AgentResult = {
+    success: boolean;
+    completionReason: AgentCompletionReason;
+    messages: ConversationMessage[];
+    textResponse?: string;
+    usage: NormalizedUsage;
+    error?: string;
+};

package/dist/types/nua-llm-core/modules/cast/cast-request.d.ts

@@ -0,0 +1,32 @@
+import { JsonSchema } from "../../lib/schema-utils";
+import { MappableInputData } from "../../lib/types";
+/** A cast ready to run, as plain data. Its prompt is rendered per attempt (see prompts/render-prompt). */
+export type CastRequest = ValueCastRequest | ListCastRequest;
+/** Asks for one value. */
+export type ValueCastRequest = {
+    kind: "value";
+    /** The caller's instructions. */
+    prompt: string;
+    data: unknown;
+    outputName: string;
+    /** The schema the result must satisfy. */
+    schema: JsonSchema;
+    maxTokens: number;
+};
+/** Asks for one result row per input row, each keyed by the input row's primary key. */
+export type ListCastRequest = {
+    kind: "list";
+    /** The caller's instructions. */
+    prompt: string;
+    rows: MappableInputData;
+    primaryKey: string;
+    outputName: string;
+    /** The schema the whole list must satisfy (see list-schema). */
+    schema: JsonSchema;
+    maxTokens: number;
+};
+/** The prompt one attempt sends. `system` is the part that tells the model how to shape its answer. */
+export type RenderedPrompt = {
+    system: string;
+    full: string;
+};

package/dist/types/nua-llm-core/modules/cast/envelope.d.ts

@@ -0,0 +1,9 @@
+import { JsonSchema } from "../../lib/schema-utils";
+export declare const ENVELOPE_KEY = "value";
+export declare function wrapInEnvelope(schema: JsonSchema): JsonSchema;
+export declare function unwrapEnvelope(envelope: unknown): {
+    found: true;
+    value: unknown;
+} | {
+    found: false;
+};

package/dist/types/nua-llm-core/modules/cast/list-schema.d.ts

@@ -0,0 +1,32 @@
+import { NuaValidationError } from "../../lib/nua-errors";
+import { JsonSchema } from "../../lib/schema-utils";
+declare const listSchemaBrand: unique symbol;
+/** Names the two fields of every row in a list result. */
+export type ListRowKeys = {
+    /** Holds the primary key of the input row the result row answers. */
+    primaryKey: string;
+    /** Holds the output value. */
+    outputName: string;
+};
+/**
+ * The schema of a list cast's result, with the row keys it was built for. Only
+ * listSchema() and parseListSchema() make one, so a castArray call cannot be
+ * given an item schema by mistake.
+ */
+export type ListSchema = ListRowKeys & {
+    readonly [listSchemaBrand]: true;
+    /** The JSON schema of the whole list, as sent to the model and validated against. */
+    jsonSchema: JsonSchema;
+};
+/**
+ * Builds the list schema whose rows each hold one `itemSchema` value:
+ *
+ *   array<{ <primaryKey>: string | number, <outputName>: <itemSchema> }>
+ */
+export declare function listSchema(itemSchema: JsonSchema, keys: ListRowKeys): ListSchema;
+/**
+ * Reads back a list schema that was built by listSchema() and stored as JSON. It is
+ * used exactly as stored, so a change to listSchema() does not alter stored ones.
+ */
+export declare function parseListSchema(jsonSchema: unknown, keys: ListRowKeys): ListSchema | NuaValidationError;
+export {};

package/dist/types/nua-llm-core/modules/cast/prompts/list-prompt.d.ts

@@ -0,0 +1,3 @@
+import { SchemaEnforcementKind } from "../../engine/llm-engine";
+import { ListCastRequest, RenderedPrompt } from "../cast-request";
+export declare function renderListPrompt(cast: ListCastRequest, enforcement: SchemaEnforcementKind): RenderedPrompt;

package/dist/types/nua-llm-core/modules/cast/prompts/render-prompt.d.ts

@@ -0,0 +1,7 @@
+import { SchemaEnforcementKind } from "../../engine/llm-engine";
+import { CastRequest, RenderedPrompt } from "../cast-request";
+/**
+ * The prompt for one attempt at a cast. It differs by enforcement: with native
+ * enforcement the model is told its answer goes in an envelope field.
+ */
+export declare function renderPrompt(cast: CastRequest, enforcement: SchemaEnforcementKind): RenderedPrompt;

package/dist/types/nua-llm-core/modules/cast/prompts/value-prompt.d.ts

@@ -0,0 +1,3 @@
+import { SchemaEnforcementKind } from "../../engine/llm-engine";
+import { RenderedPrompt, ValueCastRequest } from "../cast-request";
+export declare function renderValuePrompt(cast: ValueCastRequest, enforcement: SchemaEnforcementKind): RenderedPrompt;

package/dist/types/nua-llm-core/modules/cast/run-cast.d.ts

@@ -0,0 +1,44 @@
+import { Logger } from "../../lib/logger";
+import { NormalizedUsage } from "../engine/http/provider-config";
+import { AnswerOrigin, AttemptOutcome, LlmEngine, SchemaEnforcementKind } from "../engine/llm-engine";
+import { ValidationResult } from "../json-schema-validation/nua-json-schema-value-validation";
+import { CastRequest, RenderedPrompt } from "./cast-request";
+export type CastSuccess<T> = {
+    success: true;
+    data: T;
+    /** Usage of the attempt that succeeded. */
+    usage: NormalizedUsage;
+    /** The prompt of the attempt that succeeded. */
+    prompt: RenderedPrompt;
+    origin: AnswerOrigin;
+    schemaEnforcement: SchemaEnforcementKind;
+};
+export type CastFailure = {
+    success: false;
+    error: string;
+    /** The prompt of the last attempt, when one was made. */
+    prompt?: RenderedPrompt;
+};
+export type CastResult<T> = CastSuccess<T> | CastFailure;
+/**
+ * Runs a cast on an engine: asks for an answer, checks it against the schema,
+ * and tries again when another attempt could help.
+ */
+export declare function runCast<T>(engine: LlmEngine, request: CastRequest, logger: Logger): Promise<CastResult<T>>;
+export type Verdict = {
+    kind: "accept";
+    data: unknown;
+    usage: NormalizedUsage;
+    origin: AnswerOrigin;
+} | {
+    kind: "retry";
+    error: string;
+} | {
+    kind: "retry-in-prompt";
+    error: string;
+} | {
+    kind: "give-up";
+    error: string;
+};
+/** Decides what one attempt means for the cast. */
+export declare function judgeOutcome(outcome: AttemptOutcome, validate: (data: object) => ValidationResult): Verdict;

package/dist/types/nua-llm-core/modules/engine/engine-router.d.ts

@@ -0,0 +1,23 @@
+import { Logger } from "../../lib/logger";
+import { ModelInput } from "../model-info";
+import { LlmEngine } from "./llm-engine";
+/** The engine that runs a model choice, or why none can. */
+export type Route = {
+    kind: "routed";
+    engine: LlmEngine;
+} | {
+    kind: "unroutable";
+    message: string;
+};
+/**
+ * Where a client's calls run. Every setup answers the same question: for this
+ * model choice, which engine runs it? Created by providerEngines() for LLM
+ * providers' APIs, or by localAgent() / findLocalAgent() in the Node-only
+ * "nua-llm-core/local-agent" entry point for a coding-agent CLI.
+ */
+export interface EngineRouter {
+    /** Where the engines log their calls. Casts log their retries here too. */
+    readonly logger: Logger;
+    /** `model` undefined means this router's default model. */
+    route(model: ModelInput | undefined): Route;
+}

package/dist/types/nua-llm-core/modules/engine/http/http-engine.d.ts

@@ -0,0 +1,12 @@
+import { Logger } from "../../../lib/logger";
+import { AttemptOutcome, AttemptRequest, LlmEngine } from "../llm-engine";
+import { ProviderTarget } from "./provider-call";
+/** Answers cast attempts on one model of an LLM provider's HTTP API. */
+export declare class HttpEngine implements LlmEngine {
+    private readonly target;
+    private readonly logger;
+    constructor(target: ProviderTarget, logger: Logger);
+    /** Provider APIs are given the schema in the prompt; none is enforced natively yet. */
+    nativeSchema(): null;
+    attempt(request: AttemptRequest): Promise<AttemptOutcome>;
+}