@kuralle-agents/core 0.2.1 → 0.3.0

package/dist/runtime/Runtime.js

@@ -19,6 +19,7 @@ export class Runtime {
     sessionStore;
     defaultModel;
     maxHandoffs;
+    terminalHandoffTargets;
     hooks;
     activeTurnAborts = new Map();
     constructor(config) {
@@ -27,6 +28,7 @@ export class Runtime {
         this.sessionStore = config.sessionStore ?? new MemoryStore();
         this.defaultModel = config.defaultModel;
         this.maxHandoffs = config.maxHandoffs ?? 5;
+        this.terminalHandoffTargets = new Set(config.terminalHandoffTargets ?? ['human']);
         this.hooks = config.hooks;
     }
     run(opts) {
@@ -47,6 +49,7 @@ export class Runtime {
                 sessionId,
                 userId: opts.userId,
                 input: opts.input,
+                selection: opts.selection,
                 agentId: opts.agentId,
                 seedMessages: opts.seedMessages,
                 historyDelta: opts.historyDelta,
@@ -110,6 +113,12 @@ export class Runtime {
                         select: this.config.hostSelect,
                     });
                     if (loopResult.kind === 'handoff') {
+                        if (this.terminalHandoffTargets.has(loopResult.to)) {
+                            emit({ type: 'handoff', targetAgent: loopResult.to, reason: loopResult.reason });
+                            runCtx.runState.status = 'paused';
+                            await runCtx.runStore.putRunState(runCtx.runState);
+                            break;
+                        }
                         handoffCount += 1;
                         if (handoffCount > this.maxHandoffs) {
                             throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);

package/dist/runtime/channels/TextDriver.js

@@ -69,16 +69,20 @@ export class TextDriver {
                     toolCallId: call.toolCallId,
                 });
                 const localTool = node.localTools?.[call.toolName];
-                const toolResult = localTool
-                    ? await localTool.execute(call.input, {
-                        session: ctx.session,
-                        runState: ctx.runState,
-                        tool: ctx.tool.bind(ctx),
-                        now: ctx.now.bind(ctx),
-                        uuid: ctx.uuid.bind(ctx),
-                        emit: ctx.emit.bind(ctx),
-                    })
-                    : await ctx.tool(call.toolName, call.input);
+                const toolResult = await ctx.tool(call.toolName, call.input, {
+                    toolCallId: call.toolCallId,
+                    ...(localTool && {
+                        def: localTool,
+                        toolCtx: {
+                            session: ctx.session,
+                            runState: ctx.runState,
+                            tool: ctx.tool.bind(ctx),
+                            now: ctx.now.bind(ctx),
+                            uuid: ctx.uuid.bind(ctx),
+                            emit: ctx.emit.bind(ctx),
+                        },
+                    }),
+                });
                 out.toolResults.push({
                     name: call.toolName,
                     args: call.input,

package/dist/runtime/channels/VoiceDriver.js

@@ -121,16 +121,20 @@ export class VoiceDriver {
                     try {
                         ctx.emit({ type: 'tool-call', toolName: name, args, toolCallId: id });
                         const localTool = localTools?.[name];
-                        const toolResult = localTool
-                            ? await localTool.execute(args, {
-                                session: ctx.session,
-                                runState: ctx.runState,
-                                tool: ctx.tool.bind(ctx),
-                                now: ctx.now.bind(ctx),
-                                uuid: ctx.uuid.bind(ctx),
-                                emit: ctx.emit.bind(ctx),
-                            })
-                            : await ctx.tool(name, args, { toolCallId: id });
+                        const toolResult = await ctx.tool(name, args, {
+                            toolCallId: id,
+                            ...(localTool && {
+                                def: localTool,
+                                toolCtx: {
+                                    session: ctx.session,
+                                    runState: ctx.runState,
+                                    tool: ctx.tool.bind(ctx),
+                                    now: ctx.now.bind(ctx),
+                                    uuid: ctx.uuid.bind(ctx),
+                                    emit: ctx.emit.bind(ctx),
+                                },
+                            }),
+                        });
                         out.toolResults.push({ name, args, result: toolResult, toolCallId: id });
                         toolCallsMade.push({
                             toolCallId: id,

package/dist/runtime/channels/index.d.ts

@@ -1,7 +1,7 @@
 export type { ChannelDriver } from '../../types/channel.js';
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
 export type { TextDriverConfig } from './TextDriver.js';
-export { VoiceDriver, buildNodePrompt as buildVoiceNodePrompt } from './VoiceDriver.js';
+export { VoiceDriver } from './VoiceDriver.js';
 export type { VoiceDriverConfig } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -1,4 +1,4 @@
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
-export { VoiceDriver, buildNodePrompt as buildVoiceNodePrompt } from './VoiceDriver.js';
+export { VoiceDriver } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput } from './inputBuffer.js';

package/dist/runtime/channels/voiceTools.d.ts

@@ -4,5 +4,4 @@ import type { AnyTool } from '../../types/effectTool.js';
 import { buildToolSet } from '../../tools/effect/defineTool.js';
 export declare function v2ToolsToGemini(tools: Record<string, AnyTool>): GeminiFunctionDeclaration[];
 export declare function resolveVoiceGeminiTools(resolved: ResolvedNode, toolDefs: Record<string, AnyTool>): GeminiFunctionDeclaration[];
-export declare function mergeVoiceToolDefs(resolved: ResolvedNode, toolDefs: Record<string, AnyTool>): Record<string, AnyTool>;
 export { buildToolSet };

package/dist/runtime/channels/voiceTools.js

@@ -36,14 +36,4 @@ function toolSetToEffectTools(tools) {
     }
     return out;
 }
-export function mergeVoiceToolDefs(resolved, toolDefs) {
-    const merged = { ...toolDefs, ...(resolved.localTools ?? {}) };
-    const fromNode = toolSetToEffectTools(resolved.tools);
-    for (const [name, tool] of Object.entries(fromNode)) {
-        if (!merged[name]) {
-            merged[name] = tool;
-        }
-    }
-    return merged;
-}
 export { buildToolSet };

package/dist/runtime/citations/index.d.ts

@@ -1,5 +1,4 @@
-import type { AgentKnowledgeOverrides, HarnessStreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, Session, SourceRef } from '../../types/index.js';
-export declare const PENDING_CITATIONS_KEY = "__pendingCitations";
+import type { AgentKnowledgeOverrides, HarnessStreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, SourceRef } from '../../types/index.js';
 export interface CitationRetrievalProvider {
     retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
         results: KnowledgeRetrievalResult[];
@@ -14,13 +13,3 @@ export interface CitationRetrievalResult {
 }
 export declare function retrieveWithCitations(provider: CitationRetrievalProvider, query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<CitationRetrievalResult>;
 export declare function normalizeCitations(results: KnowledgeRetrievalResult[], nativeCitations?: readonly SourceRef[]): SourceRef[];
-export declare function getPendingCitations(session: Session): SourceRef[];
-export declare function popPendingCitations(session: Session): SourceRef[];
-export declare function withCitationMetadata<T extends {
-    role?: unknown;
-    metadata?: unknown;
-}>(message: T, citations: readonly SourceRef[]): T;
-export declare function withCitationsOnLastAssistantMessage<T extends {
-    role?: unknown;
-    metadata?: unknown;
-}>(messages: readonly T[], citations: readonly SourceRef[]): T[];

package/dist/runtime/citations/index.js

@@ -1,5 +1,4 @@
 import { createHash } from 'node:crypto';
-export const PENDING_CITATIONS_KEY = '__pendingCitations';
 export async function retrieveWithCitations(provider, query, cache, agentOverrides, isVoice = false) {
     const raw = await provider.retrieve(query, cache, agentOverrides, isVoice);
     return {
@@ -20,41 +19,6 @@ export function normalizeCitations(results, nativeCitations) {
     }
     return Array.from(byId.values()).sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
 }
-export function getPendingCitations(session) {
-    const pending = session.workingMemory[PENDING_CITATIONS_KEY];
-    return Array.isArray(pending) ? pending : [];
-}
-export function popPendingCitations(session) {
-    const citations = getPendingCitations(session);
-    delete session.workingMemory[PENDING_CITATIONS_KEY];
-    return citations;
-}
-export function withCitationMetadata(message, citations) {
-    if (message.role !== 'assistant' || citations.length === 0)
-        return message;
-    const metadata = typeof message.metadata === 'object' && message.metadata !== null
-        ? { ...message.metadata }
-        : {};
-    return {
-        ...message,
-        metadata: {
-            ...metadata,
-            citations,
-        },
-    };
-}
-export function withCitationsOnLastAssistantMessage(messages, citations) {
-    if (citations.length === 0)
-        return [...messages];
-    const next = [...messages];
-    for (let index = next.length - 1; index >= 0; index--) {
-        if (next[index].role === 'assistant') {
-            next[index] = withCitationMetadata(next[index], citations);
-            break;
-        }
-    }
-    return next;
-}
 function sourceRefFromResult(result) {
     const sourceId = result.sourceId || `synthetic-${hashShort(result.text)}`;
     return {

package/dist/runtime/contextOverflow.d.ts

@@ -30,11 +30,6 @@
  * cost of a false negative is a fatal turn loss. Bias OR.
  */
 import type { Session } from '../types/index.js';
-/** Error subclass surfaced to TurnPipeline when overflow recovery fails twice. */
-export declare class ContextOverflowUnrecoverableError extends Error {
-    readonly cause?: unknown;
-    constructor(cause?: unknown);
-}
 /**
  * Returns true if the error is a provider context-overflow / "prompt too
  * long" condition. Matches on AI SDK APICallError + raw provider errors +
@@ -44,12 +39,6 @@ export declare class ContextOverflowUnrecoverableError extends Error {
  * (fatal turn loss).
  */
 export declare function isContextOverflowError(error: unknown): boolean;
-/**
- * APICallError-aware check that also recognizes the AI SDK v6 type guard.
- * Exported separately so callers can compose with other classifiers without
- * paying the message-regex cost when the type tells them everything.
- */
-export declare function isApiCallContextOverflow(error: unknown): boolean;
 export interface OverflowRecoveryResult {
     /** Whether at least one message was stripped from session.messages. */
     stripped: boolean;

package/dist/runtime/contextOverflow.js

@@ -1,16 +1,3 @@
-// AI SDK v6 ships APICallError both directly via 'ai' and re-exports the
-// '@ai-sdk/provider' definition. We import the type only — runtime check
-// uses `APICallError.isInstance` via the imported class.
-import { APICallError } from 'ai';
-/** Error subclass surfaced to TurnPipeline when overflow recovery fails twice. */
-export class ContextOverflowUnrecoverableError extends Error {
-    cause;
-    constructor(cause) {
-        super('Context overflow could not be recovered after retry');
-        this.name = 'ContextOverflowUnrecoverableError';
-        this.cause = cause;
-    }
-}
 // Pre-compiled message patterns — keep tight and audited; loose patterns
 // inflate false positives across providers.
 const OVERFLOW_MESSAGE_PATTERNS = [
@@ -109,16 +96,6 @@ export function isContextOverflowError(error) {
     }
     return false;
 }
-/**
- * APICallError-aware check that also recognizes the AI SDK v6 type guard.
- * Exported separately so callers can compose with other classifiers without
- * paying the message-regex cost when the type tells them everything.
- */
-export function isApiCallContextOverflow(error) {
-    if (!APICallError.isInstance(error))
-        return false;
-    return isContextOverflowError(error);
-}
 /**
  * Strip partial assistant + tool messages that followed the most recent
  * user message — these are in-flight work from the turn that overflowed.

package/dist/runtime/ctx.d.ts

@@ -8,7 +8,7 @@ import type { InputProcessor, OutputProcessor } from '../types/processors.js';
 import type { Limits } from '../types/guardrails.js';
 import type { RunState, StepRecord } from './durable/types.js';
 import type { RunStore } from './durable/RunStore.js';
-export interface EffectClock {
+interface EffectClock {
     now(): number;
     uuid(): string;
 }
@@ -32,5 +32,5 @@ export interface CtxDeps {
     clock?: EffectClock;
     emit?: (part: HarnessStreamPart) => void;
 }
-export declare function makeCtx(deps: CtxDeps): RunContext;
 export declare function createRunContext(deps: CtxDeps): Promise<RunContext>;
+export {};

package/dist/runtime/ctx.js

@@ -2,8 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { SuspendError } from './durable/RunStore.js';
 import { clockEffectKey, pauseEffectKey, toolEffectKey, } from './durable/idempotency.js';
 import { findStepByKey } from './durable/replay.js';
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
 const APPROVAL_SIGNAL = '__approval';
-export function makeCtx(deps) {
+function makeCtx(deps) {
     let effectOrdinal = 0;
     const steps = deps.steps;
     const clock = deps.clock ?? {
@@ -108,6 +109,22 @@ export function makeCtx(deps) {
         bargeIn: deps.bargeIn,
         abortSignal: deps.abortSignal,
         tool: async (name, args, options) => {
+            // needsApproval gate: a tool flagged `needsApproval` must be approved by a human
+            // before it runs. Approval is a durable pause (the `__approval` signal); on resume
+            // the recorded decision is replayed, then the tool effect runs exactly once. The
+            // approval pause consumes its own callsite ordinal before the tool effect, so the
+            // ordering is deterministic across replays. NOTE: the surrounding agent turn is not
+            // itself a replayable effect — this is fully deterministic for flow `action` tools;
+            // for model-issued tool calls, resume re-enters the agent turn.
+            const def = options?.def ?? deps.toolExecutor.getTool?.(name);
+            if (def?.needsApproval) {
+                const decision = (await pauseEffect(APPROVAL_SIGNAL, {
+                    approval: { title: `Approve tool: ${name}` },
+                }));
+                if (!decision.approved) {
+                    throw new ToolApprovalDeniedError(name, decision.by);
+                }
+            }
             const callsite = consumeCallsite();
             const key = toolEffectKey(deps.runState.runId, callsite, name, args);
             return replayOrExecute(key, 'tool', name, () => deps.toolExecutor.execute({
@@ -116,6 +133,8 @@ export function makeCtx(deps) {
                 session: deps.session,
                 toolCallId: options?.toolCallId,
                 abortSignal: deps.bargeIn ?? deps.abortSignal,
+                def: options?.def,
+                toolCtx: options?.toolCtx,
             }));
         },
         approve: async (req) => {

package/dist/runtime/durable/idempotency.d.ts

@@ -1,4 +1,3 @@
-export declare function stableStringify(value: unknown): string;
 export declare function idempotencyKey(runId: string, callsite: string, payload: unknown): string;
 export declare function toolEffectKey(runId: string, callsite: string, name: string, args: unknown): string;
 export declare function pauseEffectKey(runId: string, callsite: string, name: string): string;

package/dist/runtime/durable/idempotency.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-export function stableStringify(value) {
+function stableStringify(value) {
     return JSON.stringify(value, (_key, val) => {
         if (val && typeof val === 'object' && !Array.isArray(val)) {
             const record = val;

package/dist/runtime/durable/replay.d.ts

@@ -1,6 +1,5 @@
 import type { RunState, SignalDelivery, StepRecord } from './types.js';
 import type { RunStore } from './RunStore.js';
 export declare function findStepByKey(steps: StepRecord[], key: string): StepRecord | undefined;
-export declare function findStepBySignalId(steps: StepRecord[], signalId: string): StepRecord | undefined;
 export declare function recordSignalDelivery(runStore: RunStore, runState: RunState, delivery: SignalDelivery): Promise<boolean>;
 export declare function loadRecordedSteps(runStore: RunStore, runId: string): Promise<StepRecord[]>;

package/dist/runtime/durable/replay.js

@@ -2,7 +2,7 @@ import { pauseEffectKey } from './idempotency.js';
 export function findStepByKey(steps, key) {
     return steps.find((step) => step.key === key);
 }
-export function findStepBySignalId(steps, signalId) {
+function findStepBySignalId(steps, signalId) {
     return steps.find((step) => step.signalId === signalId);
 }
 export async function recordSignalDelivery(runStore, runState, delivery) {

package/dist/runtime/durable/types.d.ts

@@ -14,7 +14,7 @@ export interface StepRecord {
     startedAt: number;
     finishedAt?: number;
 }
-export interface WaitingFor {
+interface WaitingFor {
     signalName: string;
     callsite: string;
     deadline?: number;
@@ -48,3 +48,4 @@ export interface PersistedRun {
 }
 export declare const DURABLE_RUNS_KEY: "durableRuns";
 export type SessionDurableRuns = Record<string, PersistedRun>;
+export {};

package/dist/runtime/openRun.d.ts

@@ -5,10 +5,12 @@ import type { AgentConfig } from '../types/agentConfig.js';
 import type { SignalDelivery } from './durable/types.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
 import type { RunState } from './durable/types.js';
+import type { ResolvedSelection } from '../types/selection.js';
 export interface OpenRunOptions {
     sessionId: string;
     userId?: string;
     input?: string;
+    selection?: ResolvedSelection;
     agentId?: string;
     seedMessages?: ModelMessage[];
     historyDelta?: ModelMessage[];

package/dist/runtime/openRun.js

@@ -40,16 +40,22 @@ export async function openRun(agentsById, options) {
         await recordSignalDelivery(runStore, runState, options.signalDelivery);
         runState = (await runStore.getRunState(runId)) ?? runState;
     }
-    if (options.input) {
+    if (options.selection?.formData) {
+        runState.state = { ...runState.state, ...options.selection.formData };
+        runState.updatedAt = Date.now();
+        await runStore.putRunState(runState);
+    }
+    const effectiveInput = options.selection?.id ?? options.input;
+    if (effectiveInput) {
         runState.updatedAt = Date.now();
         if (runState.activeFlow) {
             await runStore.putRunState(runState);
             const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
-            setPendingUserInput(sessionAfterPersist, options.input);
+            setPendingUserInput(sessionAfterPersist, effectiveInput);
             await options.sessionStore.save(sessionAfterPersist);
         }
         else {
-            const userMessage = { role: 'user', content: options.input };
+            const userMessage = { role: 'user', content: effectiveInput };
             runState.messages = [...runState.messages, userMessage];
             runState.updatedAt = Date.now();
             await runStore.putRunState(runState);

package/dist/runtime/policies/agentTurn.d.ts

@@ -1,8 +1,5 @@
-import type { InputProcessor, OutputProcessor } from '../../types/processors.js';
 import type { ToolCallRecord } from '../../types/session.js';
 import type { RunContext } from '../../types/run-context.js';
-import type { RefinementCapability } from '../../capabilities/RefinementCapability.js';
-import type { ValidationCapability } from '../../capabilities/ValidationCapability.js';
 export interface PreTurnResult {
     proceed: boolean;
     userMessage: string;
@@ -15,5 +12,3 @@ export interface PostTurnResult {
 }
 export declare function applyPreTurnPolicies(ctx: RunContext): Promise<PreTurnResult>;
 export declare function applyPostTurnPolicies(ctx: RunContext, assistantOutput: string, toolCallsMade?: ToolCallRecord[]): Promise<PostTurnResult>;
-export declare function buildValidationPolicies(outputProcessors: OutputProcessor[], moderators: ValidationCapability[]): ValidationCapability[];
-export declare function buildRefinementPolicies(inputProcessors: InputProcessor[], refinements: RefinementCapability[]): RefinementCapability[];

package/dist/runtime/policies/agentTurn.js

@@ -129,9 +129,3 @@ function patchLatestUserMessage(messages, next) {
     }
     messages.push({ role: 'user', content: next });
 }
-export function buildValidationPolicies(outputProcessors, moderators) {
-    return [...moderators];
-}
-export function buildRefinementPolicies(inputProcessors, refinements) {
-    return [...refinements];
-}

package/dist/runtime/policies/limits.d.ts

@@ -3,7 +3,6 @@ import type { RunState } from '../durable/types.js';
 export declare class LimitsExceededError extends Error {
     constructor(message: string);
 }
-export declare function readTurnCount(run: RunState): number;
 export declare function incrementTurnCount(run: RunState): number;
 export declare function assertWithinTurnLimit(run: RunState, limits?: Limits): void;
 export declare function resolveMaxSteps(limits: Limits | undefined, fallback: number): number;

package/dist/runtime/policies/limits.js

@@ -5,7 +5,7 @@ export class LimitsExceededError extends Error {
         this.name = 'LimitsExceededError';
     }
 }
-export function readTurnCount(run) {
+function readTurnCount(run) {
     const value = run.state[TURN_COUNT_KEY];
     return typeof value === 'number' ? value : 0;
 }

package/dist/runtime/policies/resolvePolicies.d.ts

@@ -2,7 +2,6 @@ import type { AgentConfig } from '../../types/agentConfig.js';
 import type { RefinementCapability } from '../../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../../types/processors.js';
-import type { EnforcementRule } from '../../types/tool.js';
 import type { Limits } from '../../types/guardrails.js';
 import { type ToolEnforcer } from '../../guards/ToolEnforcer.js';
 export interface ResolvedAgentPolicies {
@@ -14,5 +13,3 @@ export interface ResolvedAgentPolicies {
     enforcer?: ToolEnforcer;
 }
 export declare function resolveAgentPolicies(agent: AgentConfig): ResolvedAgentPolicies;
-export declare function withValidationPolicies(base: ResolvedAgentPolicies, validationPolicies: ValidationCapability[]): ResolvedAgentPolicies;
-export declare function withEnforcementRules(base: ResolvedAgentPolicies, rules: EnforcementRule[]): ResolvedAgentPolicies;

package/dist/runtime/policies/resolvePolicies.js

@@ -11,16 +11,3 @@ export function resolveAgentPolicies(agent) {
         enforcer: enforcementRules.length > 0 ? createToolEnforcer(enforcementRules) : undefined,
     };
 }
-export function withValidationPolicies(base, validationPolicies) {
-    return {
-        ...base,
-        validationPolicies: [...base.validationPolicies, ...validationPolicies],
-    };
-}
-export function withEnforcementRules(base, rules) {
-    const merged = [...(base.enforcer?.getRules() ?? []), ...rules];
-    return {
-        ...base,
-        enforcer: merged.length > 0 ? createToolEnforcer(merged) : undefined,
-    };
-}

package/dist/runtime/promptCache.d.ts

@@ -25,10 +25,6 @@
  */
 import type { ModelMessage } from 'ai';
 export type AnthropicCacheTtl = '5m' | '1h';
-export interface AnthropicCacheControl {
-    type: 'ephemeral';
-    ttl?: '1h';
-}
 /**
  * Returns a SHALLOW-COPIED message list with cache_control markers
  * applied to the system message (if present) + the last 3 non-system

package/dist/tools/Tool.d.ts

@@ -1,5 +1,4 @@
 import { type Tool as AiTool, type ToolSet as AiToolSet, type ToolExecutionOptions as AiToolExecutionOptions, type ToolExecuteFunction } from 'ai';
-import type { Runtime } from '../runtime/Runtime.js';
 import type { ZodTypeAny, z } from 'zod';
 export type Tool<TInput = unknown, TResult = unknown> = AiTool<TInput, TResult>;
 export type ToolSet = AiToolSet;
@@ -16,11 +15,6 @@ export interface ToolExecutionContext {
     [key: string]: unknown;
 }
 export type ToolExecutionOptions = AiToolExecutionOptions;
-export type ToolExecutionContextWithRuntime = ToolExecutionContext & {
-    runtime: Runtime;
-};
-export declare function isAgentContext(value: unknown): value is ToolExecutionContextWithRuntime;
-export declare function getRuntimeFromContext(context: ToolExecutionContext | undefined): Runtime | undefined;
 export interface ToolDefinition<TInput = unknown, TResult = unknown> {
     description: string;
     inputSchema: ZodTypeAny;

package/dist/tools/Tool.js

@@ -1,12 +1,4 @@
 import { tool as aiTool, zodSchema, } from 'ai';
-export function isAgentContext(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        'runtime' in value);
-}
-export function getRuntimeFromContext(context) {
-    return context?.runtime;
-}
 export function createTool(definition) {
     const { description, inputSchema, execute } = definition;
     // AI SDK tool() overload resolution fails when INPUT/OUTPUT are deferred wrapper generics.

package/dist/tools/effect/ToolExecutor.d.ts

@@ -17,6 +17,8 @@ export interface CoreExecuteArgs {
     abortSignal?: AbortSignal;
     toolCallId?: string;
     toolCtx?: ToolContext;
+    /** Flow-local tool def passed by the driver; wins over the registry when both exist. */
+    def?: AnyTool;
 }
 export declare class CoreToolExecutor implements EffectToolExecutor {
     private readonly tools;

package/dist/tools/effect/ToolExecutor.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { debug } from '../../debug.js';
 import { cancelledPlaceholder, inProgressPlaceholder, PairingTracker, } from './pairing.js';
 import { ToolValidationError, validateAndSanitize, validateOutput } from './schema.js';
 export class CoreToolExecutor {
@@ -45,7 +46,11 @@ export class CoreToolExecutor {
     }
     async executeInner(args) {
         const { name, session, abortSignal, toolCallId, toolCtx } = args;
-        const def = this.tools.get(name);
+        const registryDef = this.tools.get(name);
+        if (args.def && registryDef) {
+            debug(`[ToolExecutor] flow-local tool "${name}" shadows a same-named registry tool`);
+        }
+        const def = args.def ?? registryDef;
         if (!def) {
             throw new Error(`Unknown tool: ${name}`);
         }

package/dist/tools/effect/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thrown by `ctx.tool(...)` when a tool declared `needsApproval: true` is denied
+ * by a human (the `__approval` signal resolves with `approved: false`). Catch it
+ * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
+ */
+export declare class ToolApprovalDeniedError extends Error {
+    readonly toolName: string;
+    readonly by?: string;
+    constructor(toolName: string, by?: string);
+}

package/dist/tools/effect/errors.js

@@ -0,0 +1,15 @@
+/**
+ * Thrown by `ctx.tool(...)` when a tool declared `needsApproval: true` is denied
+ * by a human (the `__approval` signal resolves with `approved: false`). Catch it
+ * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
+ */
+export class ToolApprovalDeniedError extends Error {
+    toolName;
+    by;
+    constructor(toolName, by) {
+        super(`Tool "${toolName}" was denied approval${by ? ` by ${by}` : ''}`);
+        this.name = 'ToolApprovalDeniedError';
+        this.toolName = toolName;
+        this.by = by;
+    }
+}

package/dist/tools/effect/index.d.ts

@@ -4,3 +4,4 @@ export type { CoreToolExecutorConfig, CoreExecuteArgs } from './ToolExecutor.js'
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export type { ToolCallPair, ToolPairStatus, ToolRequestRecord, ToolResponseRecord, CancelledToolResult, InProgressToolResult, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';
+export { ToolApprovalDeniedError } from './errors.js';

package/dist/tools/effect/index.js

@@ -2,3 +2,4 @@ export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';
+export { ToolApprovalDeniedError } from './errors.js';

package/dist/tools/errorHandling.d.ts

@@ -20,7 +20,6 @@ export declare function executeWithRetry<T>(fn: () => Promise<T>, config?: {
     maxDelayMs?: number;
     onRetry?: (error: Error, attempt: number) => void;
 }): Promise<T>;
-export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
 export declare function createCircuitBreaker<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, config?: {
     failureThreshold?: number;
     resetTimeoutMs?: number;

package/dist/types/channel.d.ts

@@ -27,7 +27,7 @@ export type UserSignal = {
     type: 'message';
     input: string;
 };
-export interface ToolResultRecord {
+interface ToolResultRecord {
     name: string;
     args: unknown;
     result: unknown;
@@ -41,3 +41,4 @@ export type TurnControl = {
     type: 'end';
     reason: string;
 };
+export {};