@dudousxd/nestjs-agent-core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -275,6 +275,38 @@ interface ThreadDetail extends ThreadSummary {
     activeStreamId?: string;
 }
 type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+/**
+ * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
+ * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
+ */
+interface LlmStepEnvelope {
+    /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
+    agentName?: string;
+    system: string;
+    messages: ModelMessage[];
+    /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
+    actor: Actor;
+}
+/**
+ * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
+ * from DI).
+ */
+interface ToolStepCtx {
+    actor: Actor;
+    threadId: string;
+    runId: string;
+    requestId: string;
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/** Serializable input for a dispatched tool-execution step. */
+interface ToolStepEnvelope {
+    toolName: string;
+    input: unknown;
+    ctx: ToolStepCtx;
+    /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
+    timeoutMs?: number;
+}
 
 /**
  * Public, cross-lib-discoverable DI tokens.
@@ -541,6 +573,19 @@ interface RecordUsageInput {
     /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
     costUsd?: number;
 }
+interface RecordRunStartInput {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName?: string;
+}
+interface RecordRunEndInput {
+    runId: string;
+    status: 'completed' | 'failed';
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
 /** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
 interface AgentStore {
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
@@ -570,6 +615,15 @@ interface AgentStore {
      * Absent on a store that predates this — thread read/list payloads report `activeRunId: null`.
      */
     activeRunForThread?(threadId: string): Promise<string | null>;
+    /**
+     * OPTIONAL: persist the start of a run (turn). Replay-safe: called under a durable localStep.
+     * Absent on a store that predates run recording — reliability metrics degrade to zeros/empty.
+     */
+    recordRunStart?(run: RecordRunStartInput): Promise<void>;
+    /** OPTIONAL: settle a run's outcome. `errorCode`/`errorMessage` only when status is 'failed'. */
+    recordRunEnd?(end: RecordRunEndInput): Promise<void>;
+    /** OPTIONAL: bump the run's llm-step retry counter (dispatched-step attempt > 1). */
+    bumpRunRetries?(runId: string): Promise<void>;
     /**
      * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
      * for thread-scoped endpoints (detail / delete / fork): the service compares this against the
@@ -822,6 +876,52 @@ interface ThreadActivityRow {
     totalTokens: number;
     lastActivityAt: string;
 }
+/** Aggregated run reliability over a range. */
+interface RunMetrics {
+    runs: number;
+    completed: number;
+    failed: number;
+    /** completed / runs, 0 when runs = 0. */
+    successRate: number;
+    /** Total llm-step retries across the range's runs. */
+    retries: number;
+    durationP50Ms: number | null;
+    durationP95Ms: number | null;
+}
+/** Run/failure/retry rollup for one agent over a range. */
+interface RunAgentBreakdownRow {
+    /** '(default)' when the run had none. */
+    agentName: string;
+    runs: number;
+    failed: number;
+    retries: number;
+}
+/** Failed-run count for one error code over a range. */
+interface RunErrorBreakdownRow {
+    errorCode: string;
+    count: number;
+}
+/** One point on the daily run/failure trend. */
+interface RunTrendPoint {
+    day: string;
+    runs: number;
+    failed: number;
+}
+/** A recent run for the reliability feed. */
+interface RecentRunRow {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName: string | null;
+    /** 'running' | 'completed' | 'failed'. */
+    status: string;
+    durationMs: number | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    retries: number;
+    /** ISO timestamp. */
+    startedAt: string;
+}
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -835,6 +935,11 @@ interface AgentGovernanceQueries {
     usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
+    runMetrics(range: GovernanceRange): Promise<RunMetrics>;
+    runsByAgent(range: GovernanceRange): Promise<RunAgentBreakdownRow[]>;
+    runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
+    runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
+    recentRuns(limit: number): Promise<RecentRunRow[]>;
 }
 
 /**
@@ -1066,15 +1171,36 @@ interface AgentLoopHooks {
         text: string;
     }>;
     /**
-     * Checkpoint wrapper. Inline = call fn directly; durable = ctx.step(name, fn).
+     * Checkpoint wrapper. Inline = call fn directly; durable = ctx.localStep(name, fn) — the
+     * in-process checkpointed primitive (`name` is a checkpoint identity, not a worker group).
      * EVERY side-effect and control-flow read goes through this so durable replay returns
      * cached results (stable ids, no double-write, no re-streaming).
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Dispatch the model turn as a routed remote step. When present the loop uses it INSTEAD of
+     * running the model inline under hooks.step. Must resolve to exactly what deps.model.runTurn
+     * resolves. The durable runner enriches the envelope with sink routing (sinkRunId/childSink)
+     * on its side — core stays sink-topology-agnostic.
+     */
+    dispatchLlm?(index: number, envelope: LlmStepEnvelope): Promise<ModelTurnResult>;
+    /**
+     * Dispatch one tool execution as a routed remote step. Replaces ONLY the registry.invoke call
+     * (+ its timeout, applied handler-side); all persist steps around it stay local.
+     */
+    dispatchTool?(call: ToolCallRequest, envelope: ToolStepEnvelope): Promise<unknown>;
+    /**
+     * Recognizes the runner's control-flow signals (durable suspend / continue-as-new) so the loop
+     * rethrows them untouched instead of recording a failure. Inline runners omit it — they have no
+     * control-flow exceptions.
+     */
+    isControlFlowError?(error: unknown): boolean;
 }
 declare class QuotaExceededError extends Error {
     constructor();
 }
+/** Reject if `work` doesn't settle within `ms`. The underlying work is left to finish on its own. */
+declare function withToolTimeout<T>(work: Promise<T>, ms: number, toolName: string): Promise<T>;
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
@@ -1158,4 +1284,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, withToolTimeout };

package/dist/index.d.ts

@@ -275,6 +275,38 @@ interface ThreadDetail extends ThreadSummary {
     activeStreamId?: string;
 }
 type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+/**
+ * Serializable input for a dispatched model-turn step. Carries only data — the serving worker
+ * re-resolves the model/sink/registry from its own DI via AGENT_DEPS_FACTORY.forAgent(agentName).
+ */
+interface LlmStepEnvelope {
+    /** Undefined = default agent (same semantics as {@link AgentRunInput.agentName}). */
+    agentName?: string;
+    system: string;
+    messages: ModelMessage[];
+    /** The turn's actor — the handler re-derives tool definitions from it (definitionsFor). */
+    actor: Actor;
+}
+/**
+ * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
+ * from DI).
+ */
+interface ToolStepCtx {
+    actor: Actor;
+    threadId: string;
+    runId: string;
+    requestId: string;
+    agentName?: string;
+    pageContext?: PageContext;
+}
+/** Serializable input for a dispatched tool-execution step. */
+interface ToolStepEnvelope {
+    toolName: string;
+    input: unknown;
+    ctx: ToolStepCtx;
+    /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
+    timeoutMs?: number;
+}
 
 /**
  * Public, cross-lib-discoverable DI tokens.
@@ -541,6 +573,19 @@ interface RecordUsageInput {
     /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
     costUsd?: number;
 }
+interface RecordRunStartInput {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName?: string;
+}
+interface RecordRunEndInput {
+    runId: string;
+    status: 'completed' | 'failed';
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
 /** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
 interface AgentStore {
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
@@ -570,6 +615,15 @@ interface AgentStore {
      * Absent on a store that predates this — thread read/list payloads report `activeRunId: null`.
      */
     activeRunForThread?(threadId: string): Promise<string | null>;
+    /**
+     * OPTIONAL: persist the start of a run (turn). Replay-safe: called under a durable localStep.
+     * Absent on a store that predates run recording — reliability metrics degrade to zeros/empty.
+     */
+    recordRunStart?(run: RecordRunStartInput): Promise<void>;
+    /** OPTIONAL: settle a run's outcome. `errorCode`/`errorMessage` only when status is 'failed'. */
+    recordRunEnd?(end: RecordRunEndInput): Promise<void>;
+    /** OPTIONAL: bump the run's llm-step retry counter (dispatched-step attempt > 1). */
+    bumpRunRetries?(runId: string): Promise<void>;
     /**
      * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
      * for thread-scoped endpoints (detail / delete / fork): the service compares this against the
@@ -822,6 +876,52 @@ interface ThreadActivityRow {
     totalTokens: number;
     lastActivityAt: string;
 }
+/** Aggregated run reliability over a range. */
+interface RunMetrics {
+    runs: number;
+    completed: number;
+    failed: number;
+    /** completed / runs, 0 when runs = 0. */
+    successRate: number;
+    /** Total llm-step retries across the range's runs. */
+    retries: number;
+    durationP50Ms: number | null;
+    durationP95Ms: number | null;
+}
+/** Run/failure/retry rollup for one agent over a range. */
+interface RunAgentBreakdownRow {
+    /** '(default)' when the run had none. */
+    agentName: string;
+    runs: number;
+    failed: number;
+    retries: number;
+}
+/** Failed-run count for one error code over a range. */
+interface RunErrorBreakdownRow {
+    errorCode: string;
+    count: number;
+}
+/** One point on the daily run/failure trend. */
+interface RunTrendPoint {
+    day: string;
+    runs: number;
+    failed: number;
+}
+/** A recent run for the reliability feed. */
+interface RecentRunRow {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName: string | null;
+    /** 'running' | 'completed' | 'failed'. */
+    status: string;
+    durationMs: number | null;
+    errorCode: string | null;
+    errorMessage: string | null;
+    retries: number;
+    /** ISO timestamp. */
+    startedAt: string;
+}
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -835,6 +935,11 @@ interface AgentGovernanceQueries {
     usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
+    runMetrics(range: GovernanceRange): Promise<RunMetrics>;
+    runsByAgent(range: GovernanceRange): Promise<RunAgentBreakdownRow[]>;
+    runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
+    runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
+    recentRuns(limit: number): Promise<RecentRunRow[]>;
 }
 
 /**
@@ -1066,15 +1171,36 @@ interface AgentLoopHooks {
         text: string;
     }>;
     /**
-     * Checkpoint wrapper. Inline = call fn directly; durable = ctx.step(name, fn).
+     * Checkpoint wrapper. Inline = call fn directly; durable = ctx.localStep(name, fn) — the
+     * in-process checkpointed primitive (`name` is a checkpoint identity, not a worker group).
      * EVERY side-effect and control-flow read goes through this so durable replay returns
      * cached results (stable ids, no double-write, no re-streaming).
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Dispatch the model turn as a routed remote step. When present the loop uses it INSTEAD of
+     * running the model inline under hooks.step. Must resolve to exactly what deps.model.runTurn
+     * resolves. The durable runner enriches the envelope with sink routing (sinkRunId/childSink)
+     * on its side — core stays sink-topology-agnostic.
+     */
+    dispatchLlm?(index: number, envelope: LlmStepEnvelope): Promise<ModelTurnResult>;
+    /**
+     * Dispatch one tool execution as a routed remote step. Replaces ONLY the registry.invoke call
+     * (+ its timeout, applied handler-side); all persist steps around it stay local.
+     */
+    dispatchTool?(call: ToolCallRequest, envelope: ToolStepEnvelope): Promise<unknown>;
+    /**
+     * Recognizes the runner's control-flow signals (durable suspend / continue-as-new) so the loop
+     * rethrows them untouched instead of recording a failure. Inline runners omit it — they have no
+     * control-flow exceptions.
+     */
+    isControlFlowError?(error: unknown): boolean;
 }
 declare class QuotaExceededError extends Error {
     constructor();
 }
+/** Reject if `work` doesn't settle within `ms`. The underlying work is left to finish on its own. */
+declare function withToolTimeout<T>(work: Promise<T>, ms: number, toolName: string): Promise<T>;
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
@@ -1158,4 +1284,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, withToolTimeout };

package/dist/index.js

@@ -436,7 +436,7 @@ var ToolTimeoutError = class ToolTimeoutError2 extends Error {
     this.name = "ToolTimeoutError";
   }
 };
-function withTimeout(work, ms, toolName) {
+function withToolTimeout(work, ms, toolName) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new ToolTimeoutError(toolName, ms)), ms);
     work.then((value) => {
@@ -448,7 +448,7 @@ function withTimeout(work, ms, toolName) {
     });
   });
 }
-__name(withTimeout, "withTimeout");
+__name(withToolTimeout, "withToolTimeout");
 function parseFollowUps(text, count) {
   const source = text.match(/\[[\s\S]*\]/)?.[0] ?? text;
   try {
@@ -553,6 +553,17 @@ async function runAgentLoop(deps, input, hooks) {
       agentName: input.agentName
     } : {}
   });
+  const startedAt = await hooks.step("run:started-at", () => Promise.resolve(Date.now()));
+  await hooks.step("persist:run:start", async () => {
+    await deps.store.recordRunStart?.({
+      runId: hooks.runId,
+      threadId: input.threadId,
+      actorRef: input.actor.id,
+      ...input.agentName !== void 0 ? {
+        agentName: input.agentName
+      } : {}
+    });
+  });
   let injectedPassages;
   if (deps.retriever !== void 0) {
     const retriever = deps.retriever;
@@ -586,13 +597,25 @@ ${buildContextBlock(passages)}`;
         kind: "step-start"
       }));
     });
-    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
-    const turn = await hooks.step(`llm:${i}`, () => deps.model.runTurn({
-      system,
-      messages: modelMessages,
-      tools,
-      sink: writer
-    }));
+    let turn;
+    if (hooks.dispatchLlm) {
+      turn = await hooks.dispatchLlm(i, {
+        ...input.agentName !== void 0 ? {
+          agentName: input.agentName
+        } : {},
+        system,
+        messages: modelMessages,
+        actor: input.actor
+      });
+    } else {
+      const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
+      turn = await hooks.step(`llm:${i}`, () => deps.model.runTurn({
+        system,
+        messages: modelMessages,
+        tools,
+        sink: writer
+      }));
+    }
     const resolvedModelId = turn.modelId ?? deps.modelId ?? "unknown";
     const costUsd = resolveCostUsd(turn.usage, turn.costUsd, priceByModel.get(resolvedModelId));
     const toolCallsWithKind = turn.toolCalls.map((call) => ({
@@ -812,11 +835,36 @@ ${buildContextBlock(passages)}`;
           status: "auto_executed"
         }));
       }
-      const startedAt = Date.now();
+      const startedAt2 = Date.now();
       try {
-        const invocation = hooks.step(`tool:${call.id}`, () => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy));
-        const output = deps.toolTimeoutMs !== void 0 ? await withTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
-        const executionMs = Date.now() - startedAt;
+        let output;
+        if (hooks.dispatchTool) {
+          const stepCtx = {
+            actor: input.actor,
+            threadId: input.threadId,
+            runId: hooks.runId,
+            requestId: hooks.runId,
+            ...input.agentName !== void 0 ? {
+              agentName: input.agentName
+            } : {},
+            ...input.pageContext !== void 0 ? {
+              pageContext: input.pageContext
+            } : {}
+          };
+          const envelope = {
+            toolName: call.name,
+            input: call.input,
+            ctx: stepCtx,
+            ...deps.toolTimeoutMs !== void 0 ? {
+              timeoutMs: deps.toolTimeoutMs
+            } : {}
+          };
+          output = await hooks.dispatchTool(call, envelope);
+        } else {
+          const invocation = hooks.step(`tool:${call.id}`, () => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy));
+          output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+        }
+        const executionMs = Date.now() - startedAt2;
         await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({
           toolCallId: call.id,
           status: "executed",
@@ -839,7 +887,10 @@ ${buildContextBlock(passages)}`;
           durationMs: executionMs
         });
       } catch (error) {
-        const executionMs = Date.now() - startedAt;
+        if (hooks.isControlFlowError?.(error) === true) {
+          throw error;
+        }
+        const executionMs = Date.now() - startedAt2;
         const message = error instanceof Error ? error.message : String(error);
         await hooks.step(`persist:toolfail:${call.id}`, () => deps.store.updateToolCall({
           toolCallId: call.id,
@@ -887,6 +938,13 @@ ${buildContextBlock(passages)}`;
   if (thread !== null && (thread.title === "" || thread.title === "New chat")) {
     await hooks.step("persist:title", () => deps.store.setTitle(input.threadId, deriveTitle(input.userText)));
   }
+  await hooks.step("persist:run:end", async () => {
+    await deps.store.recordRunEnd?.({
+      runId: hooks.runId,
+      status: "completed",
+      durationMs: Date.now() - startedAt
+    });
+  });
   await writer.end();
   publishAgentRunFinished({
     runId: hooks.runId,
@@ -946,6 +1004,7 @@ export {
   publishAgentRunStarted,
   publishAgentToolCall,
   runAgentLoop,
-  seedModelPrices
+  seedModelPrices,
+  withToolTimeout
 };
 //# sourceMappingURL=index.js.map