@nanoagent/kernel 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+import { openai } from '@ai-sdk/openai';
+import { Effect } from 'effect';
+import { type LanguageModelResponseMetadata, type LanguageModelUsage, type ModelMessage, streamText, type TextStreamPart, type ToolSet } from 'ai';
+import type { AssistantModelMessage, MaybePromiseLike, ToolCall, ToolModelMessage } from '@ai-sdk/provider-utils';
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonLike = JsonPrimitive | {
+    readonly [key: string]: JsonLike;
+} | readonly JsonLike[];
+export type ReadonlyDeep<T> = T extends (...args: unknown[]) => unknown ? T : T extends readonly (infer ITEM)[] ? readonly ReadonlyDeep<ITEM>[] : T extends object ? {
+    readonly [KEY in keyof T]: ReadonlyDeep<T[KEY]>;
+} : T;
+export type AgentToolCall = ToolCall<string, unknown>;
+export type ReadonlyAgentToolCall = ReadonlyDeep<AgentToolCall>;
+export type AgentToolCallResponse = {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    output: unknown;
+    error?: never;
+} | {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    error: unknown;
+    output?: never;
+};
+export type AgentResponse = LanguageModelResponseMetadata & {
+    messages: Array<AssistantModelMessage | ToolModelMessage>;
+};
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type AgentStreamTextOptions = DistributiveOmit<Parameters<typeof streamText<ToolSet>>[0], 'model' | 'tools' | 'abortSignal'>;
+export type AgentModelArgs = AgentStreamTextOptions & {
+    model: string;
+    toolNames: string[];
+};
+export type AgentRawModelResult = ReturnType<typeof streamText>;
+export type AgentModelResult = {
+    finishReason?: string;
+    response: AgentResponse;
+    totalUsage: LanguageModelUsage;
+    text?: string;
+    reasoning?: Awaited<AgentRawModelResult['reasoning']>;
+    reasoningText?: string;
+    sources?: Awaited<AgentRawModelResult['sources']>;
+    warnings?: Awaited<AgentRawModelResult['warnings']>;
+    providerMetadata?: Awaited<AgentRawModelResult['providerMetadata']>;
+};
+export type SerializedError = {
+    message: string;
+    name?: string;
+    stack?: string;
+};
+export type AgentCompletionSource = 'caller' | 'model_done' | 'max_turns';
+export type AgentPhase = 'run_started' | 'turn_started' | 'turn_prepared' | 'model_started' | 'model_completed' | 'tool_calls_started' | 'tool_call_started' | 'tool_call_completed' | 'tool_calls_completed' | 'turn_completed';
+export type AgentRunStatus = {
+    type: 'running';
+    phase: AgentPhase;
+} | {
+    type: 'paused';
+    phase: AgentPhase;
+    reason?: string;
+    metadata?: JsonLike;
+    createdAt: string;
+} | {
+    type: 'completed';
+    source: AgentCompletionSource;
+    reason?: string;
+    metadata?: JsonLike;
+    createdAt: string;
+} | {
+    type: 'failed';
+    phase: AgentPhase;
+    error: SerializedError;
+    createdAt: string;
+};
+export type ToolCallsSnapshot = {
+    pending: AgentToolCall[];
+    inFlight: AgentToolCall[];
+    completed: AgentToolCallResponse[];
+};
+export type Turn = {
+    turnId: string;
+    turn: number;
+    modelArgs?: AgentModelArgs;
+    modelResult?: AgentModelResult;
+    toolCalls: ToolCallsSnapshot;
+};
+export type AgentPause = {
+    type: 'pause';
+    reason?: string;
+    metadata?: JsonLike;
+};
+export type AgentFinish = {
+    type: 'finish';
+    reason?: string;
+    metadata?: JsonLike;
+};
+export type AgentContinue = {
+    type: 'continue';
+};
+export type AgentControl = AgentPause | AgentFinish | AgentContinue;
+export type AgentRunState<CONTEXT extends JsonLike> = {
+    runId: string;
+    revision: number;
+    status: AgentRunStatus;
+    context: CONTEXT;
+    turns: Turn[];
+    currentTurn?: Turn;
+    updatedAt: string;
+};
+export type AgentPhaseEvent = {
+    type: 'run_started';
+    runId: string;
+    revision: number;
+    createdAt: string;
+} | {
+    type: 'turn_started' | 'turn_prepared' | 'model_started' | 'tool_calls_started' | 'tool_call_started' | 'tool_calls_completed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    turn: Turn;
+} | {
+    type: 'pause';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    phase: AgentPhase;
+    turn?: Turn;
+    reason?: string;
+    metadata?: JsonLike;
+} | {
+    type: 'model_restarted';
+    runId: string;
+    createdAt: string;
+    turn: Turn;
+} | {
+    type: 'model_completed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    duration: number;
+    args: AgentModelArgs;
+    result: AgentModelResult;
+    turn: Turn;
+} | {
+    type: 'tool_call_completed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    duration: number;
+    turn: Turn;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+} | {
+    type: 'turn_completed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    duration: number;
+    turn: Turn;
+} | {
+    type: 'run_completed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    duration: number;
+    turns: Turn[];
+    source: AgentCompletionSource;
+    reason?: string;
+    metadata?: JsonLike;
+} | {
+    type: 'run_failed';
+    runId: string;
+    revision: number;
+    createdAt: string;
+    phase: AgentPhase;
+    error: SerializedError;
+};
+export type AgentStreamEvent = AgentPhaseEvent | {
+    type: 'stream_part';
+    runId: string;
+    turnId: string;
+    turn: number;
+    createdAt: string;
+    part: TextStreamPart<ToolSet>;
+};
+export type AgentSaveState<CONTEXT extends JsonLike> = (args: {
+    state: AgentRunState<CONTEXT>;
+    events: AgentPhaseEvent[];
+}) => AgentEffectResult<void>;
+export type AgentMiddlewareNext<INPUT, OUTPUT> = (input: INPUT) => Promise<OUTPUT>;
+export type AgentMiddleware<INPUT, OUTPUT> = (args: {
+    input: INPUT;
+    next: AgentMiddlewareNext<INPUT, OUTPUT>;
+}) => AgentEffectResult<OUTPUT>;
+export type AgentEffectResult<A, E extends Error = Error> = MaybePromiseLike<A> | Effect.Effect<A, E, never>;
+export type AgentHookResult<VALUE, CONTEXT extends JsonLike> = void | {
+    context?: CONTEXT;
+    value?: VALUE;
+    control?: AgentControl;
+};
+export type AgentVoidHookResult<CONTEXT extends JsonLike> = void | {
+    context?: CONTEXT;
+    control?: AgentControl;
+};
+export type AgentToolCallsStartedValue = readonly AgentToolCall[];
+export type AgentToolCallStartedValue = AgentToolCall | {
+    type: 'skip';
+    result: AgentToolCallResponse;
+};
+export type AgentModelProviders = Record<string, (modelName: string) => ReturnType<typeof openai>>;
+export type AgentTurnPreparedValue = AgentStreamTextOptions & {
+    model: string;
+};
+export type BaseHookArgs<CONTEXT extends JsonLike> = {
+    context: ReadonlyDeep<CONTEXT>;
+    state: ReadonlyDeep<AgentRunState<CONTEXT>>;
+    runId: string;
+};
+export type AgentRunStartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+};
+export type AgentTurnStartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    turn: Turn;
+};
+export type AgentTurnPreparedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    turn: Turn;
+};
+export type AgentModelStartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    args: AgentModelArgs;
+    createdAt: string;
+    turn: Turn;
+};
+export type AgentModelCompletedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    args: AgentModelArgs;
+    createdAt: string;
+    duration: number;
+    result: AgentModelResult;
+    /**
+     * Un-normalized Vercel AI SDK streamText return. Use to extract
+     * SDK-shaped fields (reasoning, sources, steps, files, warnings) that
+     * are not part of the canonical AgentModelResult, then stash extracted
+     * values in context. Not cloned, not deep-frozen — do not mutate.
+     */
+    rawResult: AgentRawModelResult;
+    turn: Turn;
+};
+export type AgentCallModelArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    args: AgentModelArgs;
+    createdAt: string;
+    turn: Turn;
+};
+export type AgentCallModelResult = {
+    args: AgentModelArgs;
+    duration: number;
+    pendingToolCalls: AgentToolCall[];
+    rawResult: AgentRawModelResult;
+    result: AgentModelResult;
+};
+export type AgentStreamUpdateArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    part: TextStreamPart<ToolSet>;
+    turn: Turn;
+};
+export type AgentToolCallsStartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    result: AgentModelResult;
+    toolCalls: readonly ReadonlyAgentToolCall[];
+    turn: Turn;
+};
+export type AgentToolCallStartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    toolCall: ReadonlyAgentToolCall;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    turn: Turn;
+};
+export type AgentToolCallCompletedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    duration: number;
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    turn: Turn;
+} & ({
+    output: unknown;
+    error?: never;
+} | {
+    error: unknown;
+    output?: never;
+});
+export type AgentCallToolArgs<CONTEXT extends JsonLike> = {
+    context: CONTEXT;
+    messages: ModelMessage[];
+    signal?: AbortSignal;
+    toolCall: AgentToolCall;
+    tools: ToolSet;
+};
+export type AgentToolCallsCompletedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    result: AgentModelResult;
+    toolCalls: AgentToolCallResponse[];
+    turn: Turn;
+};
+export type AgentTurnCompletedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    duration: number;
+    turn: Turn;
+};
+export type AgentRunCompletedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    duration: number;
+    turns: Turn[];
+};
+export type AgentStreamPartEvent = Extract<AgentStreamEvent, {
+    type: 'stream_part';
+}>;
+export type AgentMiddlewareMap<CONTEXT extends JsonLike> = {
+    callModel?: Array<AgentMiddleware<AgentCallModelArgs<CONTEXT>, AgentCallModelResult>>;
+    callTool?: Array<AgentMiddleware<AgentCallToolArgs<CONTEXT>, AgentToolCallResponse>>;
+};
+export type AgentRunFailedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    error: unknown;
+};
+export type AgentPauseArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    phase: AgentPhase;
+    turn?: Turn;
+    reason?: string;
+    metadata?: JsonLike;
+};
+export type AgentModelRestartedArgs<CONTEXT extends JsonLike> = BaseHookArgs<CONTEXT> & {
+    createdAt: string;
+    turn: Turn;
+};
+export type AgentRuntime<CONTEXT extends JsonLike> = {
+    state: AgentRunState<CONTEXT> | {
+        context: CONTEXT;
+        runId?: string;
+    };
+    tools?: ToolSet;
+    modelProviders?: AgentModelProviders;
+};
+export type AgentHooks<CONTEXT extends JsonLike> = {
+    onRunStarted?: (args: AgentRunStartedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    onTurnStarted?: (args: AgentTurnStartedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    /**
+     * Return exact model input for this turn.
+     *
+     * This is the client's message assembly boundary: load transcript, summaries,
+     * memories, retrieved context, or hidden system notes, then choose the exact
+     * messages sent to the model for this turn.
+     *
+     * Core does not append assistant/tool messages to future turns. Completed
+     * output is stored in state.turns, and caller code must include any prior
+     * turn's response.messages or tool results in the next messages array.
+     */
+    onTurnPrepared: (args: AgentTurnPreparedArgs<CONTEXT>) => AgentEffectResult<AgentHookResult<AgentTurnPreparedValue, CONTEXT>>;
+    onModelStarted?: (args: AgentModelStartedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    /**
+     * Observation hook for resumed model phase. Fires after the run has
+     * committed back to the model_started phase on resume, before the
+     * model_restarted event yields. Void — cannot change run state.
+     */
+    onModelRestarted?: (args: AgentModelRestartedArgs<CONTEXT>) => AgentEffectResult<void>;
+    /**
+     * Receives the built AgentModelResult plus rawResult (the un-normalized
+     * Vercel AI SDK streamText return). Extract SDK-shaped fields from rawResult
+     * here and stash them in context for later hooks.
+     */
+    onModelCompleted?: (args: AgentModelCompletedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    /**
+     * Observation hook for pause. Fires after the paused snapshot is committed,
+     * before the pause event yields. Void — cannot change run state.
+     */
+    onPause?: (args: AgentPauseArgs<CONTEXT>) => AgentEffectResult<void>;
+    onStreamUpdate?: (args: AgentStreamUpdateArgs<CONTEXT>) => AgentEffectResult<void>;
+    onToolCallsStarted?: (args: AgentToolCallsStartedArgs<CONTEXT>) => AgentEffectResult<AgentHookResult<AgentToolCallsStartedValue, CONTEXT>>;
+    onToolCallStarted?: (args: AgentToolCallStartedArgs<CONTEXT>) => AgentEffectResult<AgentHookResult<AgentToolCallStartedValue, CONTEXT>>;
+    onToolCallCompleted?: (args: AgentToolCallCompletedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    onToolCallsCompleted?: (args: AgentToolCallsCompletedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    /**
+     * Good place to update caller-owned conversation memory from the completed
+     * turn's modelResult.response and toolCalls.completed before next
+     * onTurnPrepared call.
+     */
+    onTurnCompleted?: (args: AgentTurnCompletedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    onRunCompleted?: (args: AgentRunCompletedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+    onRunFailed?: (args: AgentRunFailedArgs<CONTEXT>) => AgentEffectResult<AgentVoidHookResult<CONTEXT>>;
+};
+export type RunAgentOptions<CONTEXT extends JsonLike> = AgentRuntime<CONTEXT> & {
+    maxTurns: number;
+    hooks: AgentHooks<CONTEXT>;
+    saveState?: AgentSaveState<CONTEXT>;
+    middleware?: AgentMiddlewareMap<CONTEXT>;
+    signal?: AbortSignal;
+};
+type AgentEventGenerator = AsyncGenerator<AgentStreamEvent, void, void>;
+export declare function runAgent<CONTEXT extends JsonLike>(options: RunAgentOptions<CONTEXT>): AgentEventGenerator;
+export {};