@kortyx/agent 0.28.0 → 0.30.0

package/dist/index.d.ts

@@ -1,208 +1,17 @@
-import { KortyxError, FailureDescriptor } from '@kortyx/core/errors';
-import { FinalizedChatMessage, StreamChunk } from '@kortyx/stream';
-import { WorkflowDefinition, ExecutionLimits, TokenUsage, ExecutionLimitReached, ExecutionBudget, GraphState } from '@kortyx/core';
+import { a3 as ChatLifecyclePhase, a4 as ChatLifecycleHookError, a5 as Agent, a6 as ChatResponseFinalized, p as EvalJson, C as CreateEvalsOptions, S as EvalSuite, K as EvalRunOptions, L as EvalRunResult, t as EvalJudgeOptions, q as EvalJudge, r as EvalJudgeIdentity } from './studio-judge-BFF0TsT2.js';
+export { a7 as AgentProcessOptions, a8 as AgentProjectTopologyOptions, a9 as ChatResponseStatus, aa as CreateAgentArgs, E as EvalCase, a as EvalCaseResult, c as EvalCommand, d as EvalConfigurationError, e as EvalContext, f as EvalCriterion, g as EvalCriterionResult, h as EvalDefaults, i as EvalExecution, j as EvalExecutionStatus, k as EvalExpectation, l as EvalGradeInput, m as EvalHandlerRef, n as EvalInterrupt, o as EvalIssue, s as EvalJudgeIdentitySchema, u as EvalJudgeUsage, v as EvalJudgeUsageSchema, w as EvalManifest, x as EvalManifestSchema, y as EvalObservation, A as EvalOutputExpectation, B as EvalPhase, D as EvalProgress, F as EvalProgressSchema, G as EvalRemoteRunRequest, H as EvalRemoteRunRequestSchema, I as EvalResponder, M as EvalRunResultSchema, N as EvalSetupContext, O as EvalStatus, P as EvalStep, Q as EvalStepResult, T as EvalSuiteSchema, U as EvalVerdict, W as EvalWireEvent, X as EvalWireEventSchema, ab as ExecutableWorkflow, ac as ExecuteOptions, ad as ExecutionInfo, ae as ExecutionInterrupt, af as ExecutionRequestError, ag as ExecutionResult, ah as InterruptScope, ai as ListInterruptsOptions, aj as PendingInterrupt, ak as ResumableInterrupt, al as ResumeHandle, am as ResumeOptions, an as ResumeResponse, Y as StudioEvalJudgeOptions, Z as StudioEvalJudgeRequestSchema, _ as StudioEvalJudgeResponseSchema, $ as StudioEvalStartRequestSchema, ao as createAgent, a0 as createStudioEvalJudge, a1 as defineSuite, a2 as parseEvalSuite, ap as projectWorkflowTopology } from './studio-judge-BFF0TsT2.js';
+import { C as ChatMessage } from './chat-message-D4EsFcr1.js';
+export { StreamChatFromRouteArgs, streamChatFromRoute } from './browser.js';
 import { GetProviderFn } from '@kortyx/providers';
-import { PendingRequestRecord, PendingRequestStore, CheckpointSummary, CheckpointId, SessionCheckpointRecord, RollbackSessionCheckpointResult, ForkSessionCheckpointResult, WorkflowRegistry, FrameworkAdapter, ExecutionRuntimeConfig } from '@kortyx/runtime';
-import { z } from 'zod';
+import { PendingRequestRecord, FrameworkAdapter, WorkflowRegistry } from '@kortyx/runtime';
+import { StreamChunk } from '@kortyx/stream';
+import { ExecutionBudget, GraphState, WorkflowDefinition, ExecutionLimits } from '@kortyx/core';
 import * as _kortyx_hooks from '@kortyx/hooks';
-import { KortyxTelemetryConfig, EnsureWorkflowTopologyRequest } from '@kortyx/hooks';
-import { C as ChatMessage } from './browser-EVWVR9BO.js';
-export { S as StreamChatFromRouteArgs, s as streamChatFromRoute } from './browser-EVWVR9BO.js';
+import { z } from 'zod';
 import { StreamEvent } from '@langchain/core/tracers/log_stream';
+import '@kortyx/core/errors';
 import '@kortyx/stream/browser';
 
-type ChatResponseStatus = "completed" | "failed" | "cancelled" | "interrupted";
-type ChatResponseFinalized = {
-    sessionId: string;
-    runId: string;
-    clientTurnId: string;
-    status: ChatResponseStatus;
-    message: FinalizedChatMessage;
-    checkpointId?: string;
-};
-type ChatLifecyclePhase = "turn-accepted" | "response-finalized" | "forked" | "rolled-back";
-declare class ChatLifecycleHookError extends KortyxError {
-    readonly phase: ChatLifecyclePhase;
-    constructor(phase: ChatLifecyclePhase, cause: unknown);
-}
-
-type ExecutableWorkflow = WorkflowDefinition & {
-    inputSchema: z.ZodType;
-    outputSchema: z.ZodType<Record<string, unknown>>;
-};
-/** Serializable identity of a waiting request. Treat tokens as private credentials. */
-type ResumeHandle = {
-    token: string;
-    requestId: string;
-    sessionId: string;
-    runId: string;
-};
-type ResumeResponse = {
-    type: "text";
-    text: string;
-} | {
-    type: "select";
-    ids: string[];
-} | {
-    type: "value";
-    value: unknown;
-} | {
-    type: "cancel";
-};
-type ExecutionInterrupt = {
-    workflow: string;
-    node: string;
-    input: PendingRequestRecord["schema"] & {
-        options: Array<{
-            id: string;
-            label: string;
-            description?: string | undefined;
-        }>;
-    };
-};
-type ExecutionInfo = {
-    runId: string;
-    sessionId: string;
-    checkpointId?: string;
-    usage?: TokenUsage;
-};
-type ExecutionResult<T = Record<string, unknown>> = ExecutionInfo & ({
-    status: "completed";
-    data: T;
-} | {
-    status: "suspended";
-    reason?: "limit_reached";
-    limit?: ExecutionLimitReached;
-    interrupt: ExecutionInterrupt;
-    resume: ResumeHandle;
-} | {
-    status: "cancelled";
-    reason: string;
-} | {
-    status: "failed";
-    error: Pick<FailureDescriptor, "code" | "message"> & Partial<FailureDescriptor>;
-});
-type ExecuteOptions<W extends ExecutableWorkflow> = {
-    limits?: ExecutionLimits;
-    abortSignal?: AbortSignal;
-    workflow: W;
-    input: z.input<W["inputSchema"]>;
-    sessionId?: string;
-    context?: Record<string, unknown>;
-};
-type ResumeOptions<W extends ExecutableWorkflow> = {
-    limits?: ExecutionLimits;
-    abortSignal?: AbortSignal;
-    workflow: W;
-    resume: ResumeHandle;
-    response: ResumeResponse;
-};
-/** The command was rejected before starting work or claiming an interrupt. */
-declare class ExecutionRequestError extends KortyxError {
-    name: string;
-    constructor(code: string, message: string, cause?: unknown);
-}
-
-declare const scopeSchema: z.ZodObject<{
-    sessionId: z.ZodOptional<z.ZodString>;
-    runId: z.ZodOptional<z.ZodString>;
-    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
-}, z.core.$strict>;
-type InterruptScope = z.input<typeof scopeSchema>;
-type ListInterruptsOptions = InterruptScope & {
-    status?: "pending";
-    afterResponseCompleted?: boolean;
-};
-type PendingInterrupt = {
-    id: string;
-    status: "pending";
-    runId: string;
-    sessionId: string;
-    workflow: string;
-    node: string;
-    createdAt: string;
-    expiresAt: string;
-    afterResponseCompleted: boolean;
-    input: Omit<PendingRequestRecord["schema"], "meta"> & {
-        options: Array<{
-            id: string;
-            label: string;
-            description?: string;
-        }>;
-    };
-};
-type ResumableInterrupt = PendingInterrupt & {
-    resume: ResumeHandle;
-};
-declare function createInterruptDiscovery(store: PendingRequestStore): {
-    listInterrupts(options: ListInterruptsOptions): Promise<PendingInterrupt[]>;
-    getInterrupt(id: string, scope: InterruptScope): Promise<ResumableInterrupt | null>;
-};
-
-/** Produces the topology-only, deterministic Contract A snapshot. */
-declare const projectWorkflowTopology: (args: {
-    workflow: WorkflowDefinition;
-    environment: string;
-    service: NonNullable<KortyxTelemetryConfig["service"]>;
-    knownWorkflowIds?: readonly string[] | undefined;
-}) => EnsureWorkflowTopologyRequest;
-
-interface AgentProcessOptions {
-    executionSignal?: AbortSignal | undefined;
-    onExecution?: ((completion: Promise<void>) => void) | undefined;
-    clientTurnId?: string | undefined;
-    continueOnDisconnect?: boolean | undefined;
-    onResponseFinalized?: ((event: ChatResponseFinalized) => void | Promise<void>) | undefined;
-    limits?: ExecutionLimits | undefined;
-    abortSignal?: AbortSignal | undefined;
-    sessionId?: string | undefined;
-    workflowId?: string | undefined;
-    context?: Record<string, unknown> | undefined;
-}
-type AgentTopologySnapshot = ReturnType<typeof projectWorkflowTopology>;
-interface AgentProjectTopologyOptions {
-    environment: string;
-    service: AgentTopologySnapshot["service"];
-}
-interface CreateAgentArgs {
-    limits?: ExecutionLimits | undefined;
-    getProvider?: GetProviderFn | undefined;
-    workflows?: WorkflowDefinition[];
-    workflowsDir?: string;
-    workflowRegistry?: WorkflowRegistry;
-    defaultWorkflowId?: string;
-    frameworkAdapter?: FrameworkAdapter;
-    telemetry?: ExecutionRuntimeConfig["telemetry"];
-}
-interface Agent extends ReturnType<typeof createInterruptDiscovery> {
-    execute<W extends ExecutableWorkflow>(args: ExecuteOptions<W>): Promise<ExecutionResult<z.output<W["outputSchema"]>>>;
-    execute(args: {
-        limits?: ExecutionLimits;
-        abortSignal?: AbortSignal;
-        workflow: string;
-        input: unknown;
-        sessionId?: string;
-        context?: Record<string, unknown>;
-    }): Promise<ExecutionResult>;
-    resume<W extends ExecutableWorkflow>(args: ResumeOptions<W>): Promise<ExecutionResult<z.output<W["outputSchema"]>>>;
-    resume(args: {
-        limits?: ExecutionLimits;
-        abortSignal?: AbortSignal;
-        workflow: string;
-        resume: ResumeHandle;
-        response: ResumeResponse;
-    }): Promise<ExecutionResult>;
-    projectTopology?: (options: AgentProjectTopologyOptions) => Promise<AgentTopologySnapshot[]>;
-    streamChat: (messages: ChatMessage[], options?: AgentProcessOptions) => Promise<AsyncIterable<StreamChunk>>;
-    listCheckpoints: (sessionId: string) => Promise<CheckpointSummary[]>;
-    getCheckpoint: (id: CheckpointId) => Promise<SessionCheckpointRecord | null>;
-    rollbackTo: (id: CheckpointId) => Promise<RollbackSessionCheckpointResult>;
-    fork: (id: CheckpointId, options?: {
-        newSessionId?: string;
-    }) => Promise<ForkSessionCheckpointResult>;
-}
-declare function createAgent(args: CreateAgentArgs): Agent;
-
 type ChatRequestBody = {
     sessionId?: string | undefined;
     workflowId?: string | undefined;
@@ -406,6 +215,51 @@ interface StreamChatArgs<Options> {
 }
 declare function streamChat<Options = unknown>({ messages, abortSignal, executionSignal, onExecution, clientTurnId, continueOnDisconnect, onResponseFinalized, options, sessionId, defaultWorkflowId, loadRuntimeConfig, selectWorkflow, workflowRegistry, knownWorkflowIds, frameworkAdapter, getProvider, applyResumeSelection, }: StreamChatArgs<Options>): Promise<AsyncIterable<StreamChunk>>;
 
+/** Run serializable conversations against the same agent used by the application. */
+declare function createEvals<Params = EvalJson | undefined, Prepared = undefined>(options: CreateEvalsOptions<Params, Prepared>): {
+    listSuites(): EvalSuite[];
+    describe(): {
+        judge?: {
+            location?: "app" | "studio";
+            id: string;
+            version: string;
+        };
+        paramsSchema?: z.core.ZodStandardJSONSchemaPayload<z.ZodType<Params, unknown, z.core.$ZodTypeInternals<Params, unknown>>>;
+        schemaVersion: 1;
+        studioJudging: true;
+        suites: EvalSuite[];
+        responders: {
+            schemaVersion?: string;
+            schemaId?: string;
+            name: string;
+        }[];
+        references: string[];
+    };
+    run(args: EvalRunOptions): Promise<EvalRunResult>;
+};
+
+/** A separate model call: the evaluated agent never grades itself inside its workflow. */
+declare function createEvalJudge({ model, id, version, }: EvalJudgeOptions): EvalJudge;
+
+declare const getEvalSuiteRevision: (suite: EvalSuite) => string;
+
+type EvalRunner = {
+    describe: () => {
+        schemaVersion: 1;
+        suites: readonly EvalSuite[];
+        studioJudging?: true;
+        judge?: EvalJudgeIdentity;
+    };
+    run: (args: EvalRunOptions) => Promise<EvalRunResult>;
+};
+/** Mount this Web Request handler in the consumer app. Keys never enter cases. */
+declare function createEvalRouteHandler({ evals, serviceKey, maxCases, maxActiveRuns, }: {
+    evals: EvalRunner;
+    serviceKey: string;
+    maxCases?: number;
+    maxActiveRuns?: number;
+}): (request: Request) => Promise<Response>;
+
 interface TransformOptions {
     debug?: boolean;
     emitStatus?: boolean;
@@ -420,4 +274,4 @@ declare function transformGraphStreamForUI(stream: AsyncIterable<StreamEvent>, o
 
 declare function extractLatestUserMessage(messages: ChatMessage[]): string;
 
-export { type Agent, type AgentProcessOptions, type AgentProjectTopologyOptions, type ApplyResumeSelection, type ChatLifecycleErrorEvent, ChatLifecycleHookError, type ChatLifecyclePhase, ChatMessage, type ChatRequestBody, type ChatResponseFinalized, type ChatResponseStatus, type ChatRouteHandlerOptions, type CheckpointRequestBody, type CheckpointRouteHandlerOptions, type CompiledGraphLike, type CreateAgentArgs, type ExecutableWorkflow, type ExecuteOptions, type ExecutionInfo, type ExecutionInterrupt, ExecutionRequestError, type ExecutionResult, type InterruptScope, type ListInterruptsOptions, type OrchestrateArgs, type PendingInterrupt, type ResumableInterrupt, type ResumeHandle, type ResumeMeta, type ResumeOptions, type ResumeResponse, type SaveMemoryFn, type SelectWorkflowFn, type StreamChatArgs, createAgent, createChatRouteHandler, createCheckpointRouteHandler, createFailureResponse, extractLatestUserMessage, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, projectWorkflowTopology, readRequestJson, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };
+export { Agent, type ApplyResumeSelection, type ChatLifecycleErrorEvent, ChatLifecycleHookError, ChatLifecyclePhase, ChatMessage, type ChatRequestBody, ChatResponseFinalized, type ChatRouteHandlerOptions, type CheckpointRequestBody, type CheckpointRouteHandlerOptions, type CompiledGraphLike, CreateEvalsOptions, EvalJson, EvalJudge, EvalJudgeIdentity, EvalJudgeOptions, EvalRunOptions, EvalRunResult, type EvalRunner, EvalSuite, type OrchestrateArgs, type ResumeMeta, type SaveMemoryFn, type SelectWorkflowFn, type StreamChatArgs, createChatRouteHandler, createCheckpointRouteHandler, createEvalJudge, createEvalRouteHandler, createEvals, createFailureResponse, extractLatestUserMessage, getEvalSuiteRevision, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, readRequestJson, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };