@telnyx/agent-harness 0.1.0-beta.0

package/dist/harness.d.ts

@@ -0,0 +1,199 @@
+import { type FinishReason, type GenerateTextOnFinishCallback, type GenerateTextOnStartCallback, type GenerateTextOnStepFinishCallback, type GenerateTextOnStepStartCallback, type GenerateTextOnToolCallFinishCallback, type GenerateTextOnToolCallStartCallback, type LanguageModel, type ToolSet } from "ai";
+import type { AgentHarnessPorts } from "./ports.js";
+import { type HarnessApprovalLedger } from "./approvals.js";
+import { type HarnessCheckpoint, type HarnessRunLedger } from "./durable.js";
+import { type HarnessMiddleware } from "./lifecycle.js";
+import { type HarnessRuntimeConfig } from "./runtime-config.js";
+import type { HarnessStepContext } from "./steps.js";
+/** Structural subset of an AI SDK output definition used for parsed-result inference. */
+interface HarnessOutputDefinition<Parsed = unknown> {
+    parseCompleteOutput(options: {
+        text: string;
+    }, context: unknown): Promise<Parsed>;
+}
+/** Complete parsed value associated with an AI SDK output definition. */
+type HarnessParsedOutput<Definition> = Definition extends HarnessOutputDefinition<infer Parsed> ? Parsed : never;
+/** Raised after the final allowed model step still requests executable tools. */
+export declare class HarnessStepLimitError extends Error {
+    readonly maxSteps: number;
+    readonly completedSteps: number;
+    readonly lastToolCalls: ReadonlyArray<Readonly<{
+        id: string;
+        name: string;
+    }>>;
+    readonly code: "HARNESS_STEP_LIMIT";
+    constructor(maxSteps: number, completedSteps: number, lastToolCalls: ReadonlyArray<Readonly<{
+        id: string;
+        name: string;
+    }>>);
+}
+/** Safe provider failure fields. Raw causes, URLs, headers, and bodies are never retained. */
+export interface HarnessProviderDiagnostics {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly causeName: string;
+    readonly statusCode?: number;
+    readonly retryable?: boolean;
+}
+/** Stable provider-boundary error containing only allowlisted diagnostics. */
+export declare class HarnessProviderError extends Error {
+    readonly diagnostics: HarnessProviderDiagnostics;
+    readonly code: "HARNESS_PROVIDER_ERROR";
+    constructor(diagnostics: HarnessProviderDiagnostics);
+}
+/** Local tool failure used when a successful execution returns an unsafe output. */
+export declare class HarnessToolOutputError extends Error {
+    readonly toolName: string;
+    readonly code: "HARNESS_TOOL_OUTPUT_ERROR";
+    constructor(toolName: string);
+}
+/** Stable cancellation classification for an aborted caller-owned turn signal. */
+export declare class HarnessCancellationError extends Error {
+    readonly code: "HARNESS_CANCELLED";
+    constructor();
+}
+/** Stable aggregate retaining a primary turn failure when its observer also fails. */
+export declare class HarnessObserverError extends Error {
+    readonly primary: unknown;
+    readonly observer: unknown;
+    readonly phase: "cancel" | "error";
+    readonly code: "HARNESS_OBSERVER_ERROR";
+    constructor(primary: unknown, observer: unknown, phase: "cancel" | "error");
+}
+/** Construction input for one portable model/tool turn engine. */
+export interface HarnessSpec<State extends Record<string, unknown>, TOOLS extends ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> {
+    /** Durable host capabilities supplied through the versioned ports seam. */
+    ports: AgentHarnessPorts<State>;
+    /** AI SDK v6 language model. */
+    model: LanguageModel;
+    /** Host-owned models selectable only by a named runtime configuration key. */
+    models?: Readonly<Record<string, LanguageModel>>;
+    /** The one explicit, flat tool set available to the model. */
+    tools: TOOLS;
+    /**
+     * Private, host-owned Service Account action mapping. Every supplied tool is
+     * mapped exactly once when approval-capable tools are present; model/tool
+     * metadata is never treated as an authorization authority.
+     */
+    authorization?: Readonly<{
+        toolActions: Readonly<Record<string, string>>;
+        /** Required host-owned lifetime for durable approval decisions. */
+        approvalTtlMs?: number;
+    }>;
+    /** Optional static subset of the injected tool set. */
+    activeTools?: readonly (keyof TOOLS & string)[];
+    /** Optional static instructions supplied to every model step. */
+    instructions?: string;
+    /** Optional host-owned structured output mode. */
+    output?: OutputDefinition;
+    /** Host-owned output modes selectable only by a named runtime configuration key. */
+    outputs?: Readonly<Record<string, OutputDefinition>>;
+    /** Required bounded turn limits. */
+    limits: Readonly<{
+        steps: number;
+    }>;
+    /** Ordered transport-neutral lifecycle middleware. */
+    middleware?: Readonly<{
+        turn?: readonly HarnessMiddleware<HarnessTurnMiddlewareContext<TOOLS, OutputDefinition>, HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>[];
+        modelStep?: readonly HarnessMiddleware<HarnessModelStepMiddlewareContext<TOOLS>, unknown>[];
+        tool?: readonly HarnessMiddleware<HarnessToolMiddlewareContext<TOOLS>, unknown>[];
+    }>;
+    /** Deterministic durability seams used by recovery tests. */
+    durability?: Readonly<{
+        checkpoints?: HarnessCheckpoint;
+        /** Deterministic test seam for delaying one durable tool call before execution. */
+        onToolCallStart?: GenerateTextOnToolCallStartCallback<TOOLS>;
+        /** Explicit version for the built-in durable tool-effect contract. */
+        toolStepVersion?: string;
+    }>;
+}
+/** Transport-safe aggregate token usage for a completed turn. */
+export interface HarnessUsage {
+    readonly inputTokens: number | undefined;
+    readonly outputTokens: number | undefined;
+    readonly totalTokens: number | undefined;
+}
+/** Transport-neutral result of a completed turn. */
+export interface HarnessTurnResult<Output = unknown> {
+    readonly text: string;
+    readonly stepCount: number;
+    readonly finishReason: FinishReason;
+    readonly journalThrough: number;
+    readonly usage: HarnessUsage;
+    /** Parsed AI SDK output when a structured output mode is configured. */
+    readonly output?: Output;
+}
+/** Immutable turn-local context passed to turn middleware. */
+export interface HarnessTurnMiddlewareContext<TOOLS extends ToolSet = ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> {
+    readonly phase: "turn";
+    readonly input: string;
+    readonly config: HarnessRuntimeConfig<LanguageModel, TOOLS, OutputDefinition>;
+    readonly signal: AbortSignal | undefined;
+}
+/** Immutable context passed around an actual model invocation. */
+export interface HarnessModelStepMiddlewareContext<TOOLS extends ToolSet = ToolSet> {
+    readonly phase: "modelStep";
+    readonly config: HarnessRuntimeConfig<LanguageModel, TOOLS>;
+    readonly stepNumber: number;
+    readonly signal: AbortSignal | undefined;
+}
+/** Immutable context passed around an actual server-tool invocation. */
+export interface HarnessToolMiddlewareContext<TOOLS extends ToolSet = ToolSet> {
+    readonly phase: "tool";
+    readonly config: HarnessRuntimeConfig<LanguageModel, TOOLS>;
+    readonly toolName: string;
+    readonly toolCallId: string | undefined;
+    readonly signal: AbortSignal | undefined;
+}
+/** One completed model step, excluding provider request/response bodies and metadata. */
+export interface HarnessStep {
+    number: number;
+    text: string;
+    finishReason: FinishReason;
+    toolCalls: ReadonlyArray<Readonly<{
+        id: string;
+        name: string;
+        input: unknown;
+    }>>;
+    journalThrough: number;
+    toolResults: ReadonlyArray<Readonly<{
+        id: string;
+        name: string;
+        output: unknown;
+        isError: boolean;
+    }>>;
+}
+/** Per-turn transport-neutral observation callbacks. */
+export interface HarnessTurnOptions<TOOLS extends ToolSet = ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> {
+    /** Caller-owned cancellation signal passed to AI SDK without transport coupling. */
+    signal?: AbortSignal;
+    /** Durable context supplied only by the harness run ledger. */
+    steps?: HarnessStepContext;
+    /** Runs after the completed step has been durably journaled. */
+    onStepCommitted?: (step: HarnessStep) => void | Promise<void>;
+    /** Runs once after the complete successful output has been durably journaled. */
+    onOutput?: (output: HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>) => void | Promise<void>;
+    /** AI SDK lifecycle callbacks, chained after harness durability work. */
+    callbacks?: Readonly<{
+        onStart?: GenerateTextOnStartCallback;
+        onStepStart?: GenerateTextOnStepStartCallback<TOOLS>;
+        onToolCallStart?: GenerateTextOnToolCallStartCallback<TOOLS>;
+        onToolCallFinish?: GenerateTextOnToolCallFinishCallback<TOOLS>;
+        onStepFinish?: GenerateTextOnStepFinishCallback<TOOLS>;
+        onFinish?: GenerateTextOnFinishCallback<TOOLS>;
+    }>;
+    /** Runs once after cleanup when the caller-owned signal cancels a turn. */
+    onCancel?: (error: HarnessCancellationError) => void | Promise<void>;
+    /** Runs once after cleanup for non-cancellation failures. */
+    onError?: (error: unknown) => void | Promise<void>;
+}
+/** Portable harness constructed by {@link createHarness}. */
+export interface Harness<TOOLS extends ToolSet = ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined> extends HarnessRunLedger {
+    turn(input: string, options?: HarnessTurnOptions<TOOLS, OutputDefinition>): Promise<HarnessTurnResult<HarnessParsedOutput<OutputDefinition>>>;
+    /** Durable, authorization-gated approval inspection and decisions. */
+    readonly approvals: HarnessApprovalLedger;
+}
+/** Construct a portable AI SDK v6 turn engine over an explicit ports object. */
+export declare function createHarness<State extends Record<string, unknown>, TOOLS extends ToolSet, OutputDefinition extends HarnessOutputDefinition | undefined = undefined>(spec: HarnessSpec<State, TOOLS, OutputDefinition>): Harness<TOOLS, OutputDefinition>;
+export {};
+//# sourceMappingURL=harness.d.ts.map