@rcrsr/rill-agent-foundry 0.18.4 → 0.18.6

package/README.md

@@ -5,7 +5,7 @@ Azure-hosted harness factory for the [rill](https://github.com/rcrsr/rill) agent
 ## Install
 
 ```bash
-npm install @rcrsr/rill-agent-foundry @rcrsr/rill-agent @opentelemetry/api
+npm install @rcrsr/rill-agent-foundry @opentelemetry/api
 ```
 
 `@opentelemetry/api` is a required peer dependency.

package/dist/index.d.ts

@@ -1,17 +1,398 @@
-export type { ContentPart, CreateResponse, ErrorResponse, FoundryHarnessOptions, FoundryMetrics, FoundryResponse, FoundryToolDefinition, InputItem, FunctionCallItem, FunctionCallOutputItem, JSONSchemaObject, JSONSchemaProperty, OutputContentPart, OutputItem, StreamErrorEvent, ToolDefinition, UserMessageItem, } from './types.js';
-export { CapacityError, CredentialError, InputError } from './errors.js';
-export type { IdGenerator } from './id.js';
-export { createIdGenerator, generateId } from './id.js';
-export type { ExtractedInput } from './extract.js';
-export { extractInput } from './extract.js';
-export type { SessionManager } from './session.js';
-export { createSessionManager } from './session.js';
-export { buildErrorResponse, buildSyncResponse, generateToolDefinitions, } from './response.js';
-export { streamFoundryResponse } from './stream.js';
-export type { ConversationsClient } from './conversations.js';
-export { createConversationsClient, PersistenceError, } from './conversations.js';
-export type { TelemetryOptions } from './telemetry.js';
-export { initTelemetry, getTracer, shutdownTelemetry } from './telemetry.js';
-export type { FoundryHarness } from './harness.js';
-export { createFoundryHarness } from './harness.js';
-//# sourceMappingURL=index.d.ts.map
+// Generated by dts-bundle-generator v9.5.1
+
+import { TokenCredential } from '@azure/identity';
+import { Tracer } from '@opentelemetry/api';
+import { Hono } from 'hono';
+
+/**
+ * A single text part within a user message content array.
+ */
+export interface ContentPart {
+	readonly type: "input_text";
+	readonly text: string;
+}
+/**
+ * A user message input item.
+ */
+export interface UserMessageItem {
+	readonly type: "message";
+	readonly role: "user";
+	readonly content: string | ContentPart[];
+}
+/**
+ * A function call output input item (tool result).
+ */
+export interface FunctionCallOutputItem {
+	readonly type: "function_call_output";
+	readonly call_id: string;
+	readonly output: string;
+}
+/**
+ * A function call item (paired with function_call_output).
+ */
+export interface FunctionCallItem {
+	readonly type: "function_call";
+	readonly call_id: string;
+	readonly name: string;
+	readonly arguments: string;
+}
+/**
+ * Discriminated union of all input item variants.
+ */
+export type InputItem = UserMessageItem | FunctionCallOutputItem | FunctionCallItem;
+/**
+ * Tool definition included in a CreateResponse request.
+ */
+export interface ToolDefinition {
+	readonly type: "function";
+	readonly name: string;
+	readonly description?: string | undefined;
+}
+/**
+ * Inbound request body for the Foundry Responses endpoint.
+ * Maps to the Azure AI Foundry CreateResponse API.
+ */
+export interface CreateResponse {
+	readonly input: string | InputItem[];
+	readonly stream?: boolean | undefined;
+	readonly conversation?: string | {
+		id: string;
+	} | undefined;
+	readonly store?: boolean | undefined;
+	readonly model?: string | undefined;
+	readonly instructions?: string | undefined;
+	readonly temperature?: number | undefined;
+	readonly user?: string | undefined;
+	readonly metadata?: Record<string, string> | undefined;
+	readonly tools?: ToolDefinition[] | undefined;
+}
+/**
+ * A single text part in an output message content array.
+ */
+export interface OutputContentPart {
+	readonly type: "text";
+	readonly text: string;
+	readonly annotations: [
+	];
+}
+/**
+ * A single output message item in a FoundryResponse.
+ */
+export interface OutputItem {
+	readonly id: string;
+	readonly type: "message";
+	readonly role: "assistant";
+	readonly status: "completed";
+	readonly content: OutputContentPart[];
+}
+/**
+ * Synchronous response body returned by the Foundry Responses endpoint.
+ */
+export interface FoundryResponse {
+	readonly id: string;
+	readonly object: "response";
+	readonly created_at: number;
+	readonly status: "completed" | "failed";
+	readonly output: OutputItem[];
+	readonly error: {
+		readonly code: string;
+		readonly message: string;
+	} | null;
+	readonly metadata: Record<string, string>;
+	readonly temperature: number;
+	readonly top_p: number;
+	readonly user: string;
+}
+/**
+ * Non-streaming error response body.
+ */
+export interface ErrorResponse {
+	readonly error: {
+		readonly code: string;
+		readonly message: string;
+	};
+}
+/**
+ * Streaming error event payload.
+ */
+export interface StreamErrorEvent {
+	readonly type: "error";
+	readonly message: string;
+}
+/**
+ * JSON Schema object used in tool parameter definitions.
+ */
+export interface JSONSchemaObject {
+	readonly type: "object";
+	readonly properties: Record<string, JSONSchemaProperty>;
+	readonly required?: string[] | undefined;
+}
+/**
+ * A single property in a JSON Schema object.
+ */
+export interface JSONSchemaProperty {
+	readonly type: string;
+	readonly description?: string | undefined;
+	readonly default?: unknown;
+}
+/**
+ * A tool definition generated from an agent handler for the Foundry API.
+ */
+export interface FoundryToolDefinition {
+	readonly type: "function";
+	readonly name: string;
+	readonly description: string;
+	readonly parameters: JSONSchemaObject;
+	readonly strict: boolean;
+}
+/**
+ * Runtime metrics for the Foundry harness.
+ */
+export interface FoundryMetrics {
+	readonly activeSessions: number;
+	readonly totalRequests: number;
+	readonly errorCount: number;
+}
+/**
+ * Options accepted by createFoundryHarness.
+ * All values default from environment variables.
+ */
+export interface FoundryHarnessOptions {
+	readonly port?: number | undefined;
+	readonly maxConcurrentSessions?: number | undefined;
+	readonly agentName?: string | undefined;
+	readonly agentVersion?: string | undefined;
+	readonly debugErrors?: boolean | undefined;
+	readonly forceSync?: boolean | undefined;
+}
+/**
+ * Error thrown when the request input is missing, empty, or unparseable.
+ * Maps to HTTP 400. Error code: INVALID_REQUEST.
+ */
+export declare class InputError extends Error {
+	/** HTTP status code for this error. */
+	readonly statusCode: 400;
+	constructor(message: string);
+}
+/**
+ * Error thrown when managed identity credential acquisition fails at startup.
+ * Triggers a non-zero process exit.
+ */
+export declare class CredentialError extends Error {
+	constructor(message: string);
+}
+/**
+ * Error thrown when the session pool is at maximum capacity.
+ * Maps to HTTP 429. Error code: RATE_LIMITED.
+ */
+export declare class CapacityError extends Error {
+	/** HTTP status code for this error. */
+	readonly statusCode: 429;
+	constructor(max: number);
+}
+export interface IdGenerator {
+	readonly responseId: string;
+	generateMessageId(): string;
+	generateFunctionCallId(): string;
+	generateFunctionOutputId(): string;
+}
+/**
+ * Create an IdGenerator scoped to a single request.
+ *
+ * Partition key extraction priority:
+ *   1. conversationId (preferred for conversation-scoped routing)
+ *   2. responseId (fallback for response-scoped routing)
+ *   3. random 18-char key when neither has a valid format
+ *
+ * If responseId is not provided, one is generated with prefix `resp`.
+ */
+export declare function createIdGenerator(responseId?: string | undefined, conversationId?: string | undefined): IdGenerator;
+/**
+ * Generate a prefixed random ID using crypto-secure entropy.
+ * Format: {prefix}{32 alphanumeric chars}
+ *
+ * Kept for backward compatibility with callers that do not need
+ * partition-key correlation.
+ */
+export declare function generateId(prefix: string): string;
+/**
+ * Result of extractInput: the extracted params and an optional target agent.
+ */
+export interface ExtractedInput {
+	readonly params: Record<string, unknown>;
+	readonly targetAgent?: string | undefined;
+}
+/**
+ * Extract normalized params and optional target agent from a polymorphic input.
+ *
+ * Variants:
+ * - string → { params: { input: string } }
+ * - array with user message → { params: { input: lastUserText } }
+ * - array with function_call_output → { params: { tool_results: [...] }, targetAgent }
+ *
+ * Throws InputError for missing, empty, or unactionable input.
+ */
+export declare function extractInput(input: unknown): ExtractedInput;
+export interface SessionManager {
+	/**
+	 * Acquire a session for the given conversation ID.
+	 * When conversationId is provided, it is used directly as the session ID.
+	 * When absent, a new random session ID is generated.
+	 * Throws CapacityError when the pool is at maximum capacity.
+	 */
+	acquire(conversationId: string | undefined): string;
+	/**
+	 * Release a session by ID. No-op if the session ID is not tracked.
+	 */
+	release(sessionId: string): void;
+	/**
+	 * Return the number of currently open sessions.
+	 */
+	activeCount(): number;
+}
+/**
+ * Create a bounded pool manager for concurrent rill sessions.
+ *
+ * Max capacity reads from MAX_CONCURRENT_SESSIONS env var, default 10.
+ */
+export declare function createSessionManager(): SessionManager;
+export interface HandlerDescription {
+	readonly name: string;
+	readonly description?: string | undefined;
+	readonly params: ReadonlyArray<{
+		readonly name: string;
+		readonly type: string;
+		readonly required: boolean;
+		readonly description?: string | undefined;
+		readonly defaultValue?: unknown;
+	}>;
+}
+export interface RunRequest {
+	readonly params?: Record<string, unknown> | undefined;
+	readonly timeout?: number | undefined;
+}
+export interface RunContext {
+	readonly sessionVars?: Record<string, string> | undefined;
+	readonly onLog?: ((message: string) => void) | undefined;
+	readonly onChunk?: ((chunk: unknown) => Promise<void>) | undefined;
+}
+export interface RunResponse {
+	readonly state: "completed" | "error";
+	readonly result: unknown;
+	readonly streamed?: boolean | undefined;
+}
+export interface AgentRouter {
+	run(agentName: string, request: RunRequest, context?: RunContext): Promise<RunResponse>;
+	describe(agentName: string): HandlerDescription | null;
+	agents(): string[];
+	defaultAgent(): string;
+	dispose(): Promise<void>;
+}
+/**
+ * Build a synchronous FoundryResponse from a RunResponse.
+ *
+ * State mapping: 'completed' → 'completed', 'error' → 'failed'.
+ * Result is coerced to string; errors are encoded in the response body.
+ */
+export declare function buildSyncResponse(result: RunResponse, responseId: string): FoundryResponse;
+/**
+ * Build a non-streaming JSON error response body.
+ *
+ * When debug is true, the original message is passed through verbatim.
+ * When debug is false or absent, a generic message is returned based on
+ * the error code per IR-10 (FOUNDRY_AGENT_DEBUG_ERRORS=false behavior).
+ */
+export declare function buildErrorResponse(code: string, message: string, debug?: boolean): ErrorResponse;
+/**
+ * Generate Foundry tool definitions from the default agent's handler descriptions.
+ *
+ * Only the default agent's handlers are exposed (AC-21).
+ * Returns an empty array when describe() returns null.
+ */
+export declare function generateToolDefinitions(router: AgentRouter): FoundryToolDefinition[];
+export interface StreamOptions {
+	readonly onError?: ((err: unknown) => void) | undefined;
+	/** IdGenerator scoped to the request for correlated message IDs. */
+	readonly idGenerator?: IdGenerator | undefined;
+	/** Session ID echoed back in x-agent-session-id response header. */
+	readonly sessionId?: string | undefined;
+	/** Invocation ID echoed back in x-agent-invocation-id response header. */
+	readonly invocationId?: string | undefined;
+	/** Pre-built x-aml-foundry-agents-metadata JSON string. */
+	readonly metadataHeader?: string | undefined;
+	/**
+	 * When true, raw error messages are forwarded to clients. When false
+	 * (default), error events emit a generic message to avoid leaking
+	 * internal details. Mirrors the harness `debugErrors` option used by
+	 * `buildErrorResponse`.
+	 */
+	readonly debugErrors?: boolean | undefined;
+}
+/**
+ * Stream a Foundry Responses lifecycle via SSE.
+ * Delegates to createFoundryStreamResponse for all paths.
+ */
+export declare function streamFoundryResponse(_c: unknown, responseId: string, resultStream: AsyncIterable<{
+	value?: unknown;
+}>, options: StreamOptions & {
+	resultPromise?: Promise<string>;
+}): Response;
+export interface ConversationsClient {
+	saveItems(conversationId: string, items: ReadonlyArray<unknown>): Promise<void>;
+}
+/**
+ * Error thrown when the Conversations API returns a non-success status
+ * or when a network timeout occurs.
+ * Maps to HTTP 502. Error code: SERVER_ERROR.
+ */
+export declare class PersistenceError extends Error {
+	readonly statusCode: 502;
+	constructor(message: string);
+}
+/**
+ * Create a client for the Azure AI Foundry Conversations API.
+ *
+ * Auth: DefaultAzureCredential with scope https://ai.azure.com/.default
+ * API version: 2025-11-15-preview
+ *
+ * saveItems() throws PersistenceError on 4xx/5xx or network timeout.
+ */
+export declare function createConversationsClient(projectEndpoint: string, credential: TokenCredential): ConversationsClient;
+export interface TelemetryOptions {
+	agentName?: string | undefined;
+	agentVersion?: string | undefined;
+}
+/**
+ * Initialize the OpenTelemetry SDK when OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ * No-op when the env var is absent. Safe to call multiple times.
+ */
+export declare function initTelemetry(options?: TelemetryOptions): void;
+/**
+ * Return a tracer for the foundry harness instrumentation scope.
+ * Returns a no-op tracer when the SDK is not initialized.
+ */
+export declare function getTracer(): Tracer;
+/**
+ * Gracefully shut down the OpenTelemetry SDK and flush pending spans.
+ * No-op when the SDK was never initialized.
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+export interface FoundryHarness {
+	listen(): Promise<void>;
+	close(): Promise<void>;
+	readonly app: Hono;
+	metrics(): FoundryMetrics;
+}
+/**
+ * Create a Foundry harness wrapping an AgentRouter.
+ *
+ * Routes:
+ *   POST /responses  — main Foundry Responses endpoint
+ *   POST /runs       — alias for /responses
+ *   GET  /readiness  — 503 before init, 200 after
+ *   GET  /liveness   — always 200
+ *   GET  /metrics    — FoundryMetrics JSON
+ */
+export declare function createFoundryHarness(router: AgentRouter, options?: FoundryHarnessOptions): FoundryHarness;
+
+export {};