@vinhnt-sdk/core 0.6.1 → 0.8.0

package/dist/kernel/run-context.js

@@ -1,13 +1,184 @@
-/** Create a fresh per-run context. */
-export function createRunContext(runId, agent, saga) {
-    return {
-        runId,
-        agent,
-        depth: 0,
-        agentChain: new Set(),
-        saga,
-        cachedTools: null,
-        cachedToolsAgentId: undefined,
-    };
+/**
+ * AgentRunContext — dependency injection container for a single agent run.
+ *
+ * Follows the OpenAI Agents SDK pattern: a typed context object that is
+ * created once per run and shared across all tools, hooks, and guardrails.
+ *
+ * @example
+ * ```ts
+ * // User creates a plain context object
+ * interface AppContext {
+ *   userId: string;
+ *   apiKey: string;
+ *   db: Database;
+ * }
+ *
+ * // Tools receive AgentRunContext<AppContext> as 2nd parameter
+ * const fetchUser = tool({
+ *   name: 'fetch_user',
+ *   description: 'Fetch user by ID',
+ *   parameters: z.object({ userId: z.string() }),
+ *   execute: async (args, runContext) => {
+ *     const user = await runContext.context.db.getUser(args.userId);
+ *     return user;
+ *   },
+ * });
+ *
+ * // Kernel creates AgentRunContext internally
+ * const kernel = new AgentKernel({ ... });
+ * const result = await kernel.run('Get user 123', {
+ *   context: { userId: 'u-1', apiKey: 'sk-...', db: myDb },
+ * });
+ * ```
+ */
+/**
+ * AgentRunContext carries all state for a single agent run.
+ *
+ * - `context`: user's application state (generic, typed)
+ * - `usage`: cumulative token usage
+ * - `signal`: abort signal for cancellation
+ * - `approvals`: tool approval decisions
+ *
+ * The context is **mutable** — tools can read/write `context` and all
+ * tools in the same run see the mutations (shared reference).
+ */
+export class AgentRunContext {
+    /** User's application state. */
+    context;
+    /** Cumulative usage for this run. */
+    usage;
+    /** Abort signal — tools should check `signal.aborted` before long operations. */
+    signal;
+    /** Session ID for this run. */
+    sessionId;
+    /** Run ID. */
+    runId;
+    /** Agent ID. */
+    agentId;
+    /** Agent name. */
+    agentName;
+    /** Environment variables (for subprocess execution). */
+    env;
+    /**
+     * The active workspace root for this run.
+     * Tools should resolve file paths relative to this directory.
+     */
+    workspaceRoot;
+    /** Tool approval decisions (toolName+callId → decision). */
+    approvals;
+    /** Compensation actions for saga rollback. */
+    compensations;
+    /** Extension data for plugins. */
+    extensionData;
+    /** Current tool input (set before tool execute, cleared after). */
+    toolInput;
+    constructor(context, options) {
+        this.context = context;
+        this.signal = options.signal;
+        this.sessionId = options.sessionId;
+        this.runId = options.runId;
+        this.agentId = options.agentId;
+        this.agentName = options.agentName;
+        this.env = options.env ?? {};
+        if (options.workspaceRoot !== undefined) {
+            this.workspaceRoot = options.workspaceRoot;
+        }
+        this.approvals = new Map();
+        this.compensations = [];
+        this.extensionData = {};
+        this.usage = {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            modelCalls: 0,
+            toolCalls: 0,
+        };
+    }
+    /**
+     * Check if a tool call has been approved.
+     * Returns the approval record if found, undefined otherwise.
+     */
+    getApproval(toolName, callId) {
+        return this.approvals.get(`${toolName}:${callId}`);
+    }
+    /**
+     * Record an approval decision for a tool call.
+     */
+    setApproval(toolName, callId, decision) {
+        this.approvals.set(`${toolName}:${callId}`, {
+            toolName,
+            callId,
+            decision,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Register a compensation action for saga rollback.
+     * If the run fails, compensations are executed in reverse order.
+     */
+    setCompensation(action) {
+        this.compensations.push(action);
+    }
+    /**
+     * Execute all compensation actions in reverse order.
+     * Called automatically on run failure if `saga: true` is set.
+     */
+    async runCompensations() {
+        const errors = [];
+        for (const comp of this.compensations.reverse()) {
+            try {
+                await comp();
+            }
+            catch (err) {
+                errors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Compensation errors:\n${errors.map((e) => e.message).join("\n")}`);
+        }
+    }
+    /**
+     * Fork context for a sub-agent run (scoped toolInput, shared approvals).
+     */
+    forkForSubagent(options) {
+        const childOptions = {
+            signal: this.signal,
+            sessionId: this.sessionId,
+            runId: this.runId,
+            agentId: options.agentId,
+            agentName: options.agentName,
+            env: this.env,
+        };
+        if (this.workspaceRoot !== undefined) {
+            childOptions.workspaceRoot = this.workspaceRoot;
+        }
+        const child = new AgentRunContext(this.context, childOptions);
+        // Share approvals and extension data by reference
+        child.approvals.clear();
+        this.approvals.forEach((v, k) => child.approvals.set(k, v));
+        Object.assign(child.extensionData, this.extensionData);
+        return child;
+    }
+    /**
+     * Create a ToolContext from this RunContext (adapter for existing tool code).
+     */
+    toToolContext() {
+        return {
+            sessionId: this.sessionId,
+            runId: this.runId,
+            agentId: this.agentId,
+            agentName: this.agentName,
+            signal: this.signal,
+            env: this.env,
+            ...(this.workspaceRoot !== undefined ? { workspaceRoot: this.workspaceRoot } : {}),
+            extensionData: this.extensionData,
+            ask: async (input) => {
+                // Delegate to approval handler (will be set by kernel)
+                return "reject";
+            },
+            metadata: () => { },
+            setCompensation: (action) => this.setCompensation(action),
+        };
+    }
 }
 //# sourceMappingURL=run-context.js.map

package/dist/kernel/run-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../../src/kernel/run-context.ts"],"names":[],"mappings":"AAyBA,sCAAsC;AACtC,MAAM,UAAU,gBAAgB,CAC9B,KAAY,EACZ,KAA8B,EAC9B,IAAc;IAEd,OAAO;QACL,KAAK;QACL,KAAK;QACL,KAAK,EAAE,CAAC;QACR,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,IAAI;QACJ,WAAW,EAAE,IAAI;QACjB,kBAAkB,EAAE,SAAS;KAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../../src/kernel/run-context.ts"],"names":[],"mappings":"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"}

package/dist/kernel/run-loop.d.ts

@@ -1,5 +1,5 @@
 import type { RequestContext, RunId, AgentConfig } from "@vinhnt-sdk/schema";
-import type { ModelProvider } from "../model.js";
+import type { ChatMessage, ModelProvider } from "../model.js";
 import type { ContextRegistry } from "../system-context/types.js";
 import type { ConversationCompactor } from "@vinhnt-sdk/session";
 import type { RunEventStore, SessionStore } from "@vinhnt-sdk/session";
@@ -12,6 +12,8 @@ import type { ToolSaga } from "@vinhnt-sdk/tools";
 import type { CircuitBreaker } from "@vinhnt-sdk/step-executor";
 import type { RunStateMachine } from "@vinhnt-sdk/step-executor";
 import type { TerminationPolicy } from "@vinhnt-sdk/step-executor";
+import type { Guardrail } from "@vinhnt-sdk/guardrails";
+import type { z } from "zod";
 export interface RunLoopDeps {
     readonly modelCaller: ModelCaller;
     readonly permissionGate: PermissionGate;
@@ -33,6 +35,14 @@ export interface RunLoopDeps {
     readonly compactionThreshold?: number;
     readonly currentAgent?: AgentConfig;
     readonly termination?: TerminationPolicy;
+    /** Input guardrails — run before model calls. */
+    readonly inputGuardrails?: readonly Guardrail[];
+    /** Output guardrails — run after model responses. */
+    readonly outputGuardrails?: readonly Guardrail[];
+    /** Structured output type — 'text' or Zod schema. */
+    readonly outputType?: 'text' | z.ZodTypeAny;
+    /** Per-run workspace root override. Tools operate within this directory. */
+    readonly workspaceRoot?: string;
     /** Optional judge model for `llm-judge` stop conditions (defaults to the active run model). */
     readonly judgeModel?: ModelProvider;
     /** Await once before the loop starts, e.g. re-queuing persisted pending inputs (RV-21). */
@@ -80,6 +90,27 @@ export interface RunLoopInput {
     emitFail: (runId: RunId, ctx: RequestContext, reason: string, steps: number, sessionId?: string, totalInputTokens?: number, totalOutputTokens?: number, durationMs?: number, cancelled?: boolean) => Promise<void>;
     /** If true, resuming from durable storage — skip run.started event and user prompt injection. */
     resume?: boolean;
+    /**
+     * Optional callback invoked before each step. Allows dynamic model/tool selection.
+     *
+     * Inspired by Vercel AI SDK's `prepareStep` pattern.
+     *
+     * @example
+     * ```typescript
+     * prepareStep: async ({ step, model, messages }) => {
+     *   // Use a cheaper model for early steps
+     *   if (step < 3) return { model: fastModel };
+     *   return {}; // use defaults
+     * }
+     * ```
+     */
+    prepareStep?: (params: {
+        step: number;
+        model: ModelProvider;
+        messages: readonly ChatMessage[];
+    }) => Promise<{
+        model?: ModelProvider;
+    } | void>;
 }
 export type RunLoopStatus = "succeeded" | "failed" | "cancelled";
 export interface RunLoopResult {
@@ -88,6 +119,15 @@ export interface RunLoopResult {
     readonly totalInputTokens?: number;
     readonly totalOutputTokens?: number;
     readonly durationMs?: number;
+    /** Validated structured output (when outputType is Zod schema). */
+    readonly structuredOutput?: unknown;
+    /** If set, a handoff was detected — kernel should transfer control. */
+    readonly handoff?: {
+        readonly targetAgentId: string;
+        readonly reason: string;
+        readonly summary?: string | undefined;
+        readonly context?: Record<string, unknown> | undefined;
+    };
 }
 export declare function runLoop(deps: RunLoopDeps, input: RunLoopInput): Promise<RunLoopResult>;
 //# sourceMappingURL=run-loop.d.ts.map

package/dist/kernel/run-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-loop.d.ts","sourceRoot":"","sources":["../../src/kernel/run-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-loop.d.ts","sourceRoot":"","sources":["../../src/kernel/run-loop.ts"],"names":[],"mappings":"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"}

package/dist/kernel/run-loop.js

@@ -1,6 +1,31 @@
 import { getTextContent, COMPACTION_SUMMARY_PREFIX } from "@vinhnt-sdk/schema";
 import { KernelError } from "@vinhnt-sdk/step-executor";
 import { evaluateStopConditions, buildJudgeMessages, parseJudgeVerdict } from "@vinhnt-sdk/step-executor";
+import { runGuardrails } from "@vinhnt-sdk/guardrails";
+import { zodSchemaToNestedJsonSchema } from "@vinhnt-sdk/tools";
+/**
+ * Convert a Zod schema to ResponseFormat for structured output.
+ * Uses the existing zodSchemaToNestedJsonSchema utility from @vinhnt-sdk/tools.
+ */
+function zodToResponseFormat(schema, name) {
+    const jsonSchema = zodSchemaToNestedJsonSchema(schema);
+    if (jsonSchema) {
+        return {
+            type: "json_schema",
+            jsonSchema: { name, schema: jsonSchema, strict: true },
+        };
+    }
+    // Fallback: basic json_object format
+    return { type: "json_object" };
+}
+/**
+ * Validate structured output against a Zod schema.
+ * Returns parsed output or throws on validation failure.
+ */
+function validateStructuredOutput(schema, output) {
+    const parsed = JSON.parse(output);
+    return schema.parse(parsed);
+}
 /** Index of the head `system` message — the first one. All system instructions
  * (identity, agent systemPrompt, context baseline/reconciled updates) must live
  * in that single message so providers never see mid-conversation `system`
@@ -140,6 +165,27 @@ async function processStep(deps, input) {
             throw new KernelError("max_tokens_exceeded", `Agent max tokens exceeded (${input.totalInputTokens + input.totalOutputTokens})`);
         }
         let messages = input.messages;
+        // Run input guardrails before model call
+        if (deps.inputGuardrails && deps.inputGuardrails.length > 0) {
+            const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+            const inputContent = lastUserMsg?.content ?? "";
+            const guardrailResult = await runGuardrails([...deps.inputGuardrails], {
+                direction: "input",
+                content: inputContent,
+                metadata: { runId, step: input.step, agentId: deps.currentAgent?.id },
+            });
+            if (!guardrailResult.passed) {
+                // Input guardrail denied — halt the run
+                throw new KernelError("guardrail_denied", `Input guardrail denied: ${guardrailResult.reason ?? "unknown reason"}`);
+            }
+            // If guardrail modified content, update the message
+            if (guardrailResult.modifiedContent !== undefined && lastUserMsg) {
+                const modifiedText = typeof guardrailResult.modifiedContent === "string"
+                    ? guardrailResult.modifiedContent
+                    : JSON.stringify(guardrailResult.modifiedContent);
+                messages = messages.map((m) => m === lastUserMsg ? { ...m, content: modifiedText } : m);
+            }
+        }
         if (deps.thinkingBudget > 0) {
             await deps.modelCaller.doThinkingStep(messages, input.step, runId, ctx, stepTimeoutController.signal);
         }
@@ -194,10 +240,42 @@ async function processStep(deps, input) {
         else if (runModel.countTokens) {
             input.totalOutputTokens += runModel.countTokens(response.content);
         }
+        // Run output guardrails after model response
+        let finalContent = response.content;
+        if (deps.outputGuardrails && deps.outputGuardrails.length > 0) {
+            const guardrailResult = await runGuardrails([...deps.outputGuardrails], {
+                direction: "output",
+                content: response.content,
+                metadata: { runId, step: input.step, agentId: deps.currentAgent?.id, toolCalls: response.toolCalls?.map((tc) => tc.name) },
+            });
+            if (!guardrailResult.passed) {
+                // Output guardrail denied — halt the run
+                throw new KernelError("guardrail_denied", `Output guardrail denied: ${guardrailResult.reason ?? "unknown reason"}`);
+            }
+            // If guardrail modified content, use the modified version
+            if (guardrailResult.modifiedContent !== undefined) {
+                finalContent = typeof guardrailResult.modifiedContent === "string"
+                    ? guardrailResult.modifiedContent
+                    : JSON.stringify(guardrailResult.modifiedContent);
+            }
+        }
+        // Validate structured output if outputType is Zod schema
+        let validatedOutput = undefined;
+        if (deps.outputType && deps.outputType !== 'text') {
+            try {
+                validatedOutput = validateStructuredOutput(deps.outputType, finalContent);
+                // Use the validated (parsed) output as the final content
+                finalContent = JSON.stringify(validatedOutput);
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                throw new KernelError("validation_error", `Structured output validation failed: ${errMsg}`);
+            }
+        }
         const toolCalls = response.toolCalls ?? [];
         messages.push({
             role: "assistant",
-            content: response.content,
+            content: finalContent,
             ...(toolCalls.length > 0 ? {
                 toolCalls: toolCalls.map((tc) => ({
                     id: tc.id,
@@ -209,7 +287,7 @@ async function processStep(deps, input) {
         const asstTokens = { input: input.totalInputTokens, output: input.totalOutputTokens };
         const asstModel = runModel.model;
         const msgCost = deps.modelCaller.calculateCost(asstTokens.input, asstTokens.output, runModel);
-        await deps.addSessionMessage(sessionId, "assistant", response.content, {
+        await deps.addSessionMessage(sessionId, "assistant", finalContent, {
             tokens: asstTokens,
             ...(asstModel ? { model: asstModel } : {}),
             ...(msgCost !== undefined ? { cost: msgCost } : {}),
@@ -225,9 +303,33 @@ async function processStep(deps, input) {
                 completed: true,
                 toolCallCount: 0,
                 lastStepToolOutcomes: [],
+                ...(validatedOutput !== undefined ? { structuredOutput: validatedOutput } : {}),
+            };
+        }
+        const { toolCallCount, selfCorrectTokens, toolResults, handoff } = await deps.stepExecutor.executeToolCalls(toolCalls.map((tc) => ({ toolId: tc.id, toolName: tc.name, args: tc.args })), messages, input.step, runId, ctx, stepTimeoutController, sessionId, runModel);
+        // Handle handoff — transfer control to target agent
+        if (handoff) {
+            const currentAgentId = deps.currentAgent?.id ?? "unknown";
+            // Note: handoff event is emitted in the main runLoop after processStep returns
+            // Signal to kernel to swap active agent (kernel handles the swap)
+            return {
+                messages,
+                step: input.step,
+                runId,
+                totalInputTokens: input.totalInputTokens,
+                totalOutputTokens: input.totalOutputTokens,
+                finalOutput: input.finalOutput,
+                completed: false,
+                toolCallCount,
+                lastStepToolOutcomes: toolResults,
+                handoff: {
+                    targetAgentId: handoff.targetAgentId,
+                    reason: handoff.reason,
+                    summary: handoff.summary,
+                    context: handoff.context,
+                },
             };
         }
-        const { toolCallCount, selfCorrectTokens, toolResults } = await deps.stepExecutor.executeToolCalls(toolCalls.map((tc) => ({ toolId: tc.id, toolName: tc.name, args: tc.args })), messages, input.step, runId, ctx, stepTimeoutController, sessionId, runModel);
         if (stepTimeoutController.signal.aborted && !runAbort.signal.aborted) {
             // Step timed out during tool execution — surface an error for any tool call
             // that never got a response so the conversation stays coherent for the model.
@@ -283,6 +385,7 @@ async function processStep(deps, input) {
             completed: false,
             toolCallCount,
             lastStepToolOutcomes: toolResults,
+            ...(validatedOutput !== undefined ? { structuredOutput: validatedOutput } : {}),
         };
     }
     finally {
@@ -301,6 +404,8 @@ export async function runLoop(deps, input) {
     let messages = [];
     let step = 0;
     let finalOutput = "";
+    let structuredOutput = undefined;
+    let handoffResult;
     let contextEpochActive = false;
     // Real system head (identity + agent systemPrompt) sent as a proper `system`
     // message at the head of the conversation instead of being flattened into the
@@ -434,6 +539,21 @@ export async function runLoop(deps, input) {
             }
             await emitEvt("step.started", { step });
             await deps.pluginManager?.fireHook("onStepStarted", { step });
+            // Invoke prepareStep callback if provided (Vercel AI SDK pattern)
+            let stepModel = runModel;
+            if (input.prepareStep) {
+                try {
+                    const prepareResult = await input.prepareStep({ step, model: runModel, messages });
+                    if (prepareResult?.model) {
+                        stepModel = prepareResult.model;
+                    }
+                }
+                catch (err) {
+                    if (typeof console !== "undefined") {
+                        console.warn("[run-loop] prepareStep failed, using default model:", err instanceof Error ? err.message : String(err));
+                    }
+                }
+            }
             const compactResult = await maybeCompact(messages, {
                 ...(runModel.countTokens ? { countTokens: runModel.countTokens } : {}),
                 ...(runModel.contextLimit !== undefined ? { contextLimit: runModel.contextLimit } : {}),
@@ -455,7 +575,7 @@ export async function runLoop(deps, input) {
             const stepResult = await processStep(deps, {
                 messages, step, runId, ctx, runAbort,
                 ...(sessionId !== undefined ? { sessionId } : {}),
-                runModel,
+                runModel: stepModel,
                 ...(runSessionState !== undefined ? { runSessionState } : {}),
                 totalInputTokens, totalOutputTokens, finalOutput,
                 ...(onLastStep ? { disableTools: true } : {}),
@@ -464,6 +584,9 @@ export async function runLoop(deps, input) {
             totalInputTokens = stepResult.totalInputTokens;
             totalOutputTokens = stepResult.totalOutputTokens;
             finalOutput = stepResult.finalOutput;
+            if (stepResult.structuredOutput !== undefined) {
+                structuredOutput = stepResult.structuredOutput;
+            }
             if (stepResult.stepFailed) {
                 await emitEvt("step.failed", { step, reason: stepResult.stepFailed.reason, ...(stepResult.stepFailed.error ? { error: stepResult.stepFailed.error } : {}) });
                 await deps.pluginManager?.fireHook("onStepFailed", { step, reason: stepResult.stepFailed.reason, ...(stepResult.stepFailed.error ? { error: stepResult.stepFailed.error } : {}) });
@@ -472,6 +595,21 @@ export async function runLoop(deps, input) {
                 await emitEvt("step.completed", { step, toolCallCount: stepResult.toolCallCount });
                 await deps.pluginManager?.fireHook("onStepCompleted", { step, toolCallCount: stepResult.toolCallCount });
             }
+            // Handle handoff — transfer control to target agent
+            if (stepResult.handoff) {
+                // Emit handoff event
+                const currentAgentId = deps.currentAgent?.id ?? "unknown";
+                await emitEvt("agent.handoff", {
+                    fromAgentId: currentAgentId,
+                    toAgentId: stepResult.handoff.targetAgentId,
+                    reason: stepResult.handoff.reason,
+                    summary: stepResult.handoff.summary,
+                });
+                // Break out of the loop — kernel will handle agent swap
+                finalOutput = `Handoff to agent "${stepResult.handoff.targetAgentId}": ${stepResult.handoff.reason}`;
+                handoffResult = stepResult.handoff;
+                break;
+            }
             if (stepResult.completed) {
                 finalOutput = stepResult.finalOutput;
                 await emitEvt("turn.end", { turn: step, reason: "completed" });
@@ -556,7 +694,14 @@ export async function runLoop(deps, input) {
                         runSessionState.isRunning = false;
                     }
                     await saveFinalSnapshot("succeeded");
-                    return { totalSteps: step + 1, status: "succeeded", totalInputTokens, totalOutputTokens, durationMs: Date.now() - startTime };
+                    return {
+                        totalSteps: step + 1,
+                        status: "succeeded",
+                        totalInputTokens,
+                        totalOutputTokens,
+                        durationMs: Date.now() - startTime,
+                        ...(structuredOutput !== undefined ? { structuredOutput } : {}),
+                    };
                 }
             }
         }
@@ -592,7 +737,7 @@ export async function runLoop(deps, input) {
                 }
                 setState(runId, "completed");
                 await saveFinalSnapshot("succeeded");
-                return { totalSteps: step + 1, status: "succeeded", totalInputTokens, totalOutputTokens, durationMs };
+                return { totalSteps: step + 1, status: "succeeded", totalInputTokens, totalOutputTokens, durationMs, ...(handoffResult ? { handoff: handoffResult } : {}) };
             }
             if (runAbort.signal.aborted)
                 return cancelRun(step + 1);