@zhivex-ai/core 1.5.0 → 1.7.0

package/dist/agent.js

@@ -1,15 +1,15 @@
 import { createHash } from "node:crypto";
 import { createAgentApprovalMessage, getAgentApprovalRequests } from "./agent-approval.js";
-import { createAgentHandoffMessage } from "./agent-handoff.js";
+import { createAgentHandoffMessage } from "./agent-handoff-contracts.js";
 import { createAgentExecutionEnvironmentBinding, fingerprintAgentHarness } from "./agent-harness.js";
 import { AGENT_RUN_STATE_SCHEMA_VERSION, normalizeAgentRunState } from "./agent-state.js";
 import { BoundedReplayBroadcast } from "./bounded-broadcast.js";
 import { ConflictError, GuardrailTriggeredError, UnsupportedFeatureError, ValidationError } from "./errors.js";
 import { aggregateTokenUsage, generateText, getGenerateTextStepTiming, normalizeMessages, streamText } from "./generate-text.js";
 import { createTextMessage, isCallableToolDefinition, serializeJsonValue } from "./messages.js";
-import { mergeAbortSignals } from "./runtime.js";
+import { createMergedAbortSignal } from "./runtime.js";
 import { evaluateAgentBudgetPreflight, getAgentBudgetStatus } from "./safety-policy.js";
-import { createSecureId } from "./secure-id.js";
+import { createSecureId } from "#secure-id";
 import { createStructuredOutputPrompt } from "./structured-output-prompt.js";
 import { ToolExecutionSuspendedError } from "./tool-execution-suspension.js";
 import { toToolSet } from "./tool-registry.js";
@@ -416,6 +416,71 @@ const finalizeState = (agent, state, result, newSteps, newToolResults) => {
 const emitTelemetryEvent = async (agent, event) => {
     await invokeOperationalHook(agent, "telemetry", event.type, event.runId, agent.onTelemetryEvent ? () => agent.onTelemetryEvent(event) : undefined, undefined);
 };
+const emitInvocationStartTelemetry = async (agent, runId, startedAt, maxSteps) => {
+    try {
+        await agent.onTelemetryEvent?.startInvocation?.({
+            runId,
+            agentId: agent.id,
+            agentName: agent.name,
+            provider: agent.model.provider,
+            modelId: agent.model.modelId,
+            maxSteps,
+            startedAt
+        });
+    }
+    catch {
+        // Invocation telemetry is best-effort and cannot replace setup/business errors.
+    }
+};
+const emitInvocationFinishTelemetry = async (agent, runId, status, error) => {
+    try {
+        await agent.onTelemetryEvent?.finishInvocation?.({
+            runId,
+            agentId: agent.id,
+            agentName: agent.name,
+            status,
+            error,
+            finishedAt: Date.now()
+        });
+    }
+    catch {
+        // Invocation telemetry is best-effort and cannot replace setup/business errors.
+    }
+};
+const withAgentTelemetryRunContext = (agent, runId, callback) => {
+    const telemetryObserver = agent.onTelemetryEvent;
+    const wrapper = telemetryObserver?.withRunContext;
+    if (!wrapper)
+        return Promise.resolve().then(callback);
+    let execution;
+    let callbackError;
+    let callbackFailed = false;
+    const executeOnce = () => {
+        execution ??= Promise.resolve()
+            .then(callback)
+            .catch((error) => {
+            callbackFailed = true;
+            callbackError = error;
+            throw error;
+        });
+        return execution;
+    };
+    return Promise.resolve()
+        .then(async () => {
+        await wrapper.call(telemetryObserver, runId, executeOnce);
+        return executeOnce();
+    })
+        .catch(async (wrapperError) => {
+        if (callbackFailed)
+            throw callbackError;
+        try {
+            return await executeOnce();
+        }
+        catch (executionError) {
+            throw callbackFailed ? callbackError : executionError ?? wrapperError;
+        }
+    });
+};
 const subAgentToolInputSchema = z.object({
     prompt: z.string().min(1),
     system: z.string().optional()
@@ -1171,6 +1236,7 @@ const createGenerateOptions = (agent, state, input, messages, maxSteps, context,
             context,
             runId: state.runId,
             agentId: state.agentId,
+            agentName: agent.name,
             scope: state.scope,
             metadata: state.metadata,
             executionEnvironment: executionEnvironmentSession
@@ -1206,19 +1272,27 @@ const createGenerateOptions = (agent, state, input, messages, maxSteps, context,
                 return compacted.messages;
             }
             : undefined,
-        onBeforeModelStep: ({ step }) => {
-            if (!budget)
-                return;
-            const trigger = evaluateAgentBudgetPreflight(state, budget, {
-                operation: "model",
-                requiredSteps: Math.max(1, step - state.currentStep),
-                requestedOutputTokens: maxTokens
-            });
-            if (trigger) {
-                throw new GuardrailTriggeredError("input", trigger.reason ?? "Agent model budget preflight failed.", {
-                    metadata: trigger.metadata
+        onBeforeModelStep: async ({ step }) => {
+            if (budget) {
+                const trigger = evaluateAgentBudgetPreflight(state, budget, {
+                    operation: "model",
+                    requiredSteps: Math.max(1, step - state.currentStep),
+                    requestedOutputTokens: maxTokens
                 });
+                if (trigger) {
+                    throw new GuardrailTriggeredError("input", trigger.reason ?? "Agent model budget preflight failed.", {
+                        metadata: trigger.metadata
+                    });
+                }
             }
+            await emitTelemetryEvent(agent, {
+                type: "step-start",
+                runId: state.runId,
+                agentId: state.agentId,
+                agentName: agent.name,
+                stepIndex: step,
+                startedAt: Date.now()
+            });
         },
         onModelStep: async ({ request, response, step, toolCalls, approvalRequests }) => {
             if (!agent.store)
@@ -1285,17 +1359,28 @@ const createGenerateOptions = (agent, state, input, messages, maxSteps, context,
             state.revision = checkpointState.revision;
         },
         stepOffset: state.currentStep,
-        onBeforeToolExecution: ({ toolCalls }) => {
-            if (!budget)
-                return;
-            reservedToolCalls += toolCalls.length;
-            const trigger = evaluateAgentBudgetPreflight(state, budget, {
-                operation: "tool",
-                requiredToolCalls: reservedToolCalls
-            });
-            if (trigger) {
-                throw new GuardrailTriggeredError("input", trigger.reason ?? "Agent tool budget preflight failed.", {
-                    metadata: trigger.metadata
+        onBeforeToolExecution: async ({ step, toolCalls }) => {
+            if (budget) {
+                reservedToolCalls += toolCalls.length;
+                const trigger = evaluateAgentBudgetPreflight(state, budget, {
+                    operation: "tool",
+                    requiredToolCalls: reservedToolCalls
+                });
+                if (trigger) {
+                    throw new GuardrailTriggeredError("input", trigger.reason ?? "Agent tool budget preflight failed.", {
+                        metadata: trigger.metadata
+                    });
+                }
+            }
+            for (const toolCall of toolCalls) {
+                await emitTelemetryEvent(agent, {
+                    type: "tool-start",
+                    runId: state.runId,
+                    agentId: state.agentId,
+                    agentName: agent.name,
+                    stepIndex: step,
+                    toolCall,
+                    startedAt: Date.now()
                 });
             }
         },
@@ -1347,22 +1432,22 @@ const resolveRunPolicy = (agent, input) => {
     return Object.keys(policy).length ? policy : undefined;
 };
 const withAgentPolicyTimeout = async (operation, timeout) => {
-    if (!timeout.timeoutPromise) {
-        return operation;
-    }
     try {
-        return await Promise.race([operation, timeout.timeoutPromise]);
+        return timeout.timeoutPromise
+            ? await Promise.race([operation, timeout.timeoutPromise])
+            : await operation;
     }
     finally {
         timeout.cleanup();
     }
 };
-const createAgentAbortContext = (inputAbortSignal, policy) => {
+const createAgentAbortContext = (inputAbortSignal, policy, ...additionalSignals) => {
     if (!policy?.timeoutMs) {
+        const merged = createMergedAbortSignal(inputAbortSignal, ...additionalSignals);
         return {
-            signal: inputAbortSignal,
+            signal: merged.signal,
             timeoutPromise: undefined,
-            cleanup: () => undefined,
+            cleanup: merged.cleanup,
             isTimedOut: () => false
         };
     }
@@ -1376,10 +1461,12 @@ const createAgentAbortContext = (inputAbortSignal, policy) => {
             reject(new AgentPolicyTimeoutError(policy.timeoutMs));
         }, policy.timeoutMs);
     });
+    const merged = createMergedAbortSignal(inputAbortSignal, ...additionalSignals, controller.signal);
     return {
-        signal: mergeAbortSignals(inputAbortSignal, controller.signal),
+        signal: merged.signal,
         timeoutPromise,
         cleanup: () => {
+            merged.cleanup();
             if (timeout) {
                 clearTimeout(timeout);
             }
@@ -1500,14 +1587,16 @@ const acquireAgentExecutionLease = async (agent, state, policy) => {
         }
     };
 };
-const emitRunStartTelemetry = async (agent, state, memoryMessages, approvals) => {
+const emitRunStartTelemetry = async (agent, state, memoryMessages, approvals, invocationStartedAt) => {
     await emitTelemetryEvent(agent, {
         type: "run-start",
         runId: state.runId,
         agentId: state.agentId,
+        agentName: agent.name,
         provider: state.provider,
         modelId: state.modelId,
-        maxSteps: state.maxSteps
+        maxSteps: state.maxSteps,
+        startedAt: invocationStartedAt
     });
     if (state.handoff) {
         await emitTelemetryEvent(agent, {
@@ -1539,8 +1628,10 @@ const emitRunFinishTelemetry = async (agent, state) => {
         type: "run-finish",
         runId: state.runId,
         agentId: state.agentId,
+        agentName: agent.name,
         status: state.status,
-        state: cloneState(state)
+        state: cloneState(state),
+        finishedAt: Date.now()
     });
 };
 export const createAgent = (definition) => ({
@@ -1549,6 +1640,7 @@ export const createAgent = (definition) => ({
 });
 export class Agent {
     id;
+    name;
     model;
     instructions;
     contextSchema;
@@ -1584,6 +1676,7 @@ export class Agent {
     toDefinition() {
         return createAgent({
             id: this.id,
+            name: this.name,
             model: this.model,
             instructions: this.instructions,
             contextSchema: this.contextSchema,
@@ -1671,16 +1764,17 @@ export const runAgentGroup = async (agents, input = {}) => {
         });
     };
     const runs = agents.map(async (member, index) => {
-        const runInput = {
-            ...sharedInput,
-            ...(member.input ?? {}),
-            parentRunId: member.input?.parentRunId ?? parentRunId,
-            abortSignal: mergeAbortSignals(input.abortSignal, member.input?.abortSignal, controllers[index].signal),
-            metadata: cloneMetadata(input.metadata, member.input?.metadata, {
-                ...(member.name ? { agentGroupMember: member.name } : {})
-            })
-        };
+        const merged = createMergedAbortSignal(input.abortSignal, member.input?.abortSignal, controllers[index].signal);
         try {
+            const runInput = {
+                ...sharedInput,
+                ...(member.input ?? {}),
+                parentRunId: member.input?.parentRunId ?? parentRunId,
+                abortSignal: merged.signal,
+                metadata: cloneMetadata(input.metadata, member.input?.metadata, {
+                    ...(member.name ? { agentGroupMember: member.name } : {})
+                })
+            };
             const output = await runAgent(member.agent, runInput);
             if (isFailingOutput(output)) {
                 abortPending(index);
@@ -1691,6 +1785,9 @@ export const runAgentGroup = async (agents, input = {}) => {
             abortPending(index);
             throw error;
         }
+        finally {
+            merged.cleanup();
+        }
     });
     const settled = await Promise.allSettled(runs);
     const outputs = settled.map((result, index) => {
@@ -1788,175 +1885,204 @@ export const cancelAgentRunTree = async (store, runId, options = {}) => {
     };
 };
 export const runAgent = async (agent, input = {}) => {
-    const context = await resolveContext(agent, input);
-    const currentStatus = normalizeApprovalStatus(context.state.status);
-    const policy = resolveRunPolicy(agent, input);
-    if (currentStatus === "completed" ||
-        currentStatus === "cancelled" ||
-        currentStatus === "cancel_requested" ||
-        currentStatus === "timed_out") {
-        context.state.status = currentStatus;
-        return toOutput(context.state);
-    }
-    if (currentStatus === "waiting_approval" && context.state.pendingApprovals.length > 0) {
-        context.state.status = currentStatus;
-        return toOutput(context.state);
-    }
-    const supportsLeases = Boolean(agent.store?.acquireLease && agent.store.renewLease && agent.store.releaseLease);
-    if (!context.fresh && currentStatus === "running" && !supportsLeases) {
-        return toOutput(context.state);
-    }
-    const freshRequiresExistingClaim = context.fresh && Boolean(context.state.idempotencyKey);
-    if (context.fresh && !freshRequiresExistingClaim) {
-        await claimAgentExecution(agent, context.state);
-    }
-    const executionLease = await acquireAgentExecutionLease(agent, context.state, policy);
-    if (!executionLease) {
-        if (input.state) {
-            throw new ConflictError(`Agent run "${context.state.runId}" is already owned by another worker.`);
+    const invocationStartedAt = Date.now();
+    const telemetryRunId = input.runId ?? input.state?.runId ?? randomId("run");
+    const invocationInput = input.runId || input.state
+        ? input
+        : { ...input, runId: telemetryRunId };
+    let invocationStatus = "completed";
+    let invocationError;
+    const returnInvocationOutput = (output) => {
+        invocationStatus = output.status;
+        if (output.status === "failed" || output.status === "timed_out") {
+            invocationError = new Error(output.error?.message ?? `Agent invocation ${output.status}.`);
+            if (output.status === "timed_out")
+                invocationError.name = "TimeoutError";
         }
-        const activeState = await agent.store?.load(context.state.runId, context.state.scope);
-        return toOutput(activeState ? normalizeAgentRunState(activeState) : context.state);
-    }
+        else {
+            invocationError = undefined;
+        }
+        return output;
+    };
+    await emitInvocationStartTelemetry(agent, telemetryRunId, invocationStartedAt, Math.max(1, input.maxSteps ?? input.state?.maxSteps ?? agent.maxSteps ?? 1));
     try {
-        if (!context.fresh || freshRequiresExistingClaim) {
+        const context = await resolveContext(agent, invocationInput);
+        const currentStatus = normalizeApprovalStatus(context.state.status);
+        const policy = resolveRunPolicy(agent, input);
+        if (currentStatus === "completed" ||
+            currentStatus === "cancelled" ||
+            currentStatus === "cancel_requested" ||
+            currentStatus === "timed_out") {
+            context.state.status = currentStatus;
+            invocationStatus = currentStatus;
+            return returnInvocationOutput(toOutput(context.state));
+        }
+        if (currentStatus === "waiting_approval" && context.state.pendingApprovals.length > 0) {
+            context.state.status = currentStatus;
+            invocationStatus = currentStatus;
+            return returnInvocationOutput(toOutput(context.state));
+        }
+        const supportsLeases = Boolean(agent.store?.acquireLease && agent.store.renewLease && agent.store.releaseLease);
+        if (!context.fresh && currentStatus === "running" && !supportsLeases) {
+            invocationStatus = currentStatus;
+            return returnInvocationOutput(toOutput(context.state));
+        }
+        const freshRequiresExistingClaim = context.fresh && Boolean(context.state.idempotencyKey);
+        if (context.fresh && !freshRequiresExistingClaim) {
             await claimAgentExecution(agent, context.state);
         }
-        await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals);
-    }
-    catch (error) {
-        await executionLease.release();
-        throw error;
-    }
-    if (context.remainingSteps === 0) {
-        const state = createFailedState(context.state, "Agent exhausted maxSteps before reaching a terminal response.");
-        await persistState(agent, state, policy);
-        await emitRunFinishTelemetry(agent, state);
-        await executionLease.release();
-        return toOutput(state);
-    }
-    let inputGuardrail;
-    try {
-        inputGuardrail = await runGuardrails(agent, context.state, "input", agent.inputGuardrails, () => ({
-            runId: context.state.runId,
-            agentId: context.state.agentId,
-            context: context.context,
-            state: cloneState(context.state),
-            messages: context.messages,
-            metadata: context.state.metadata
-        }));
-    }
-    catch (error) {
-        await executionLease.release();
-        throw error;
-    }
-    if (inputGuardrail) {
-        const failedState = applyGuardrailFailure(context.state, "input", inputGuardrail);
-        await persistState(agent, failedState, policy);
-        await emitRunFinishTelemetry(agent, failedState);
-        await executionLease.release();
-        return toOutput(failedState);
-    }
-    try {
-        await emitTelemetryEvent(agent, {
-            type: "step-start",
-            runId: context.state.runId,
-            agentId: context.state.agentId,
-            stepIndex: context.state.currentStep + 1
-        });
-    }
-    catch (error) {
-        await executionLease.release();
-        throw error;
-    }
-    const abortContext = createAgentAbortContext(mergeAbortSignals(input.abortSignal, executionLease.signal), policy);
-    let executionEnvironmentSession;
-    let executionEnvironmentStatus = "failed";
-    let executionEnvironmentError;
-    try {
-        executionEnvironmentSession = await acquireExecutionEnvironment(context.executionEnvironment, context.state, context.context, abortContext.signal);
-    }
-    catch (error) {
-        await executionLease.release();
-        throw error;
-    }
-    try {
-        const result = await withAgentPolicyTimeout(generateText(createGenerateOptions(agent, context.state, input, context.messages, context.remainingSteps, context.context, executionEnvironmentSession, abortContext.signal)), abortContext);
-        const cancelled = executionLease.cancelledState();
-        if (cancelled) {
-            executionEnvironmentStatus = cancelled.status;
-            await emitRunFinishTelemetry(agent, cancelled);
-            return toOutput(cancelled);
-        }
-        if (executionLease.leaseLost()) {
-            throw new ConflictError(`Agent run "${context.state.runId}" lost its worker lease.`);
-        }
-        const newSteps = mapSteps(result.steps, context.state.currentStep, result.toolResults);
-        let output = finalizeState(agent, context.state, result, newSteps, result.toolResults);
-        const outputGuardrail = await runGuardrails(agent, output.state, "output", agent.outputGuardrails, () => ({
-            runId: output.state.runId,
-            agentId: output.state.agentId,
-            context: context.context,
-            state: cloneState(output.state),
-            output,
-            metadata: output.state.metadata
-        }));
-        if (outputGuardrail) {
-            output = toOutput(applyGuardrailFailure(output.state, "output", outputGuardrail));
-        }
-        await emitFinalizedStepTelemetry(agent, output.state, newSteps);
-        await emitApprovalTelemetry(agent, output.state, [
-            ...(result.approvalRequests ?? []),
-            ...approvalsFromEvents(newSteps.flatMap((step) => step.response?.messages ?? []))
-        ]);
-        await persistState(agent, output.state, policy);
-        await emitRunFinishTelemetry(agent, output.state);
-        executionEnvironmentStatus = output.status;
-        return output;
-    }
-    catch (error) {
-        executionEnvironmentError = {
-            message: error instanceof Error ? error.message : String(error)
-        };
-        const cancelled = executionLease.cancelledState();
-        if (cancelled) {
-            executionEnvironmentStatus = cancelled.status;
-            await emitRunFinishTelemetry(agent, cancelled);
-            return toOutput(cancelled);
-        }
-        if (executionLease.leaseLost()) {
-            throw new ConflictError(`Agent run "${context.state.runId}" lost its worker lease.`);
-        }
-        if (error instanceof AgentPolicyTimeoutError || abortContext.isTimedOut()) {
-            const status = policy?.onTimeout === "cancel-requested" ? "cancel_requested" : "timed_out";
-            const message = error instanceof Error ? error.message : `Agent run timed out after ${policy?.timeoutMs}ms.`;
+        const executionLease = await acquireAgentExecutionLease(agent, context.state, policy);
+        if (!executionLease) {
+            if (input.state) {
+                throw new ConflictError(`Agent run "${context.state.runId}" is already owned by another worker.`);
+            }
+            const activeState = await agent.store?.load(context.state.runId, context.state.scope);
+            const outputState = activeState ? normalizeAgentRunState(activeState) : context.state;
+            invocationStatus = outputState.status;
+            return returnInvocationOutput(toOutput(outputState));
+        }
+        try {
+            if (!context.fresh || freshRequiresExistingClaim) {
+                await claimAgentExecution(agent, context.state);
+            }
+            await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals, invocationStartedAt);
+        }
+        catch (error) {
+            await executionLease.release();
+            throw error;
+        }
+        if (context.remainingSteps === 0) {
+            const state = createFailedState(context.state, "Agent exhausted maxSteps before reaching a terminal response.");
+            await persistState(agent, state, policy);
+            await emitRunFinishTelemetry(agent, state);
+            await executionLease.release();
+            return returnInvocationOutput(toOutput(state));
+        }
+        let inputGuardrail;
+        try {
+            inputGuardrail = await runGuardrails(agent, context.state, "input", agent.inputGuardrails, () => ({
+                runId: context.state.runId,
+                agentId: context.state.agentId,
+                context: context.context,
+                state: cloneState(context.state),
+                messages: context.messages,
+                metadata: context.state.metadata
+            }));
+        }
+        catch (error) {
+            await executionLease.release();
+            throw error;
+        }
+        if (inputGuardrail) {
+            const failedState = applyGuardrailFailure(context.state, "input", inputGuardrail);
+            await persistState(agent, failedState, policy);
+            await emitRunFinishTelemetry(agent, failedState);
+            await executionLease.release();
+            return returnInvocationOutput(toOutput(failedState));
+        }
+        const abortContext = createAgentAbortContext(input.abortSignal, policy, executionLease.signal);
+        let executionEnvironmentSession;
+        let executionEnvironmentStatus = "failed";
+        let executionEnvironmentError;
+        try {
+            executionEnvironmentSession = await acquireExecutionEnvironment(context.executionEnvironment, context.state, context.context, abortContext.signal);
+        }
+        catch (error) {
+            abortContext.cleanup();
+            await executionLease.release();
+            throw error;
+        }
+        try {
+            const result = await withAgentTelemetryRunContext(agent, context.state.runId, () => withAgentPolicyTimeout(generateText(createGenerateOptions(agent, context.state, input, context.messages, context.remainingSteps, context.context, executionEnvironmentSession, abortContext.signal)), abortContext));
+            const cancelled = executionLease.cancelledState();
+            if (cancelled) {
+                executionEnvironmentStatus = cancelled.status;
+                await emitRunFinishTelemetry(agent, cancelled);
+                return returnInvocationOutput(toOutput(cancelled));
+            }
+            if (executionLease.leaseLost()) {
+                throw new ConflictError(`Agent run "${context.state.runId}" lost its worker lease.`);
+            }
+            const newSteps = mapSteps(result.steps, context.state.currentStep, result.toolResults);
+            let output = finalizeState(agent, context.state, result, newSteps, result.toolResults);
+            const outputGuardrail = await runGuardrails(agent, output.state, "output", agent.outputGuardrails, () => ({
+                runId: output.state.runId,
+                agentId: output.state.agentId,
+                context: context.context,
+                state: cloneState(output.state),
+                output,
+                metadata: output.state.metadata
+            }));
+            if (outputGuardrail) {
+                output = toOutput(applyGuardrailFailure(output.state, "output", outputGuardrail));
+            }
+            await emitFinalizedStepTelemetry(agent, output.state, newSteps);
+            await emitApprovalTelemetry(agent, output.state, [
+                ...(result.approvalRequests ?? []),
+                ...approvalsFromEvents(newSteps.flatMap((step) => step.response?.messages ?? []))
+            ]);
+            await persistState(agent, output.state, policy);
+            await emitRunFinishTelemetry(agent, output.state);
+            executionEnvironmentStatus = output.status;
+            return returnInvocationOutput(output);
+        }
+        catch (error) {
+            executionEnvironmentError = {
+                message: error instanceof Error ? error.message : String(error)
+            };
+            const cancelled = executionLease.cancelledState();
+            if (cancelled) {
+                executionEnvironmentStatus = cancelled.status;
+                await emitRunFinishTelemetry(agent, cancelled);
+                return returnInvocationOutput(toOutput(cancelled));
+            }
+            if (executionLease.leaseLost()) {
+                throw new ConflictError(`Agent run "${context.state.runId}" lost its worker lease.`);
+            }
+            if (error instanceof AgentPolicyTimeoutError || abortContext.isTimedOut()) {
+                const status = policy?.onTimeout === "cancel-requested" ? "cancel_requested" : "timed_out";
+                const message = error instanceof Error ? error.message : `Agent run timed out after ${policy?.timeoutMs}ms.`;
+                const durableState = agent.store
+                    ? normalizeAgentRunState((await agent.store.load(context.state.runId, context.state.scope)) ?? context.state)
+                    : context.state;
+                const timedOutState = createTerminalState(durableState, status, message);
+                await persistState(agent, timedOutState, policy);
+                await emitRunFinishTelemetry(agent, timedOutState);
+                executionEnvironmentStatus = timedOutState.status;
+                return returnInvocationOutput(toOutput(timedOutState));
+            }
             const durableState = agent.store
                 ? normalizeAgentRunState((await agent.store.load(context.state.runId, context.state.scope)) ?? context.state)
                 : context.state;
-            const timedOutState = createTerminalState(durableState, status, message);
-            await persistState(agent, timedOutState, policy);
-            await emitRunFinishTelemetry(agent, timedOutState);
-            executionEnvironmentStatus = timedOutState.status;
-            return toOutput(timedOutState);
-        }
-        const durableState = agent.store
-            ? normalizeAgentRunState((await agent.store.load(context.state.runId, context.state.scope)) ?? context.state)
-            : context.state;
-        const failedState = createFailedState(durableState, error instanceof Error ? error.message : String(error));
-        await persistState(agent, failedState, policy);
-        await emitRunFinishTelemetry(agent, failedState);
-        executionEnvironmentStatus = failedState.status;
+            const failedState = createFailedState(durableState, error instanceof Error ? error.message : String(error));
+            await persistState(agent, failedState, policy);
+            await emitRunFinishTelemetry(agent, failedState);
+            executionEnvironmentStatus = failedState.status;
+            throw error;
+        }
+        finally {
+            await executionEnvironmentSession?.release?.({
+                status: executionEnvironmentStatus,
+                error: executionEnvironmentError
+            });
+            await executionLease.release();
+        }
+    }
+    catch (error) {
+        invocationStatus = "failed";
+        invocationError = error instanceof Error ? error : new Error(String(error));
         throw error;
     }
     finally {
-        await executionEnvironmentSession?.release?.({
-            status: executionEnvironmentStatus,
-            error: executionEnvironmentError
-        });
-        await executionLease.release();
+        await emitInvocationFinishTelemetry(agent, telemetryRunId, invocationStatus, invocationError);
     }
 };
 export const streamAgent = (agent, input = {}) => {
+    const invocationStartedAt = Date.now();
+    const telemetryRunId = input.runId ?? input.state?.runId ?? randomId("run");
+    const invocationInput = input.runId || input.state
+        ? input
+        : { ...input, runId: telemetryRunId };
     const policy = resolveRunPolicy(agent, input);
     const broadcast = new BoundedReplayBroadcast({
         maxHistory: policy?.maxStreamEvents ?? 4096
@@ -1964,12 +2090,19 @@ export const streamAgent = (agent, input = {}) => {
     const publish = (event, terminal = false) => broadcast.publish(event, { terminal });
     let activeLease;
     let activeExecutionEnvironment;
+    let invocationFinishPromise;
+    const finishInvocation = (status, error) => {
+        invocationFinishPromise ??= emitInvocationFinishTelemetry(agent, telemetryRunId, status, error);
+        return invocationFinishPromise;
+    };
     const runner = (async () => {
-        const context = await resolveContext(agent, input);
+        await emitInvocationStartTelemetry(agent, telemetryRunId, invocationStartedAt, Math.max(1, input.maxSteps ?? input.state?.maxSteps ?? agent.maxSteps ?? 1));
+        const context = await resolveContext(agent, invocationInput);
         const currentStatus = normalizeApprovalStatus(context.state.status);
         const supportsLeases = Boolean(agent.store?.acquireLease && agent.store.renewLease && agent.store.releaseLease);
         if (!context.fresh && currentStatus === "running" && !supportsLeases) {
             broadcast.close();
+            await finishInvocation(currentStatus);
             return {
                 output: toOutput(context.state),
                 textStream: emptyAsyncIterable()
@@ -1981,6 +2114,7 @@ export const streamAgent = (agent, input = {}) => {
             currentStatus === "timed_out") {
             context.state.status = currentStatus;
             broadcast.close();
+            await finishInvocation(currentStatus);
             return {
                 output: toOutput(context.state),
                 textStream: emptyAsyncIterable()
@@ -1989,6 +2123,7 @@ export const streamAgent = (agent, input = {}) => {
         if (currentStatus === "waiting_approval" && context.state.pendingApprovals.length > 0) {
             context.state.status = currentStatus;
             broadcast.close();
+            await finishInvocation(currentStatus);
             return {
                 output: toOutput(context.state),
                 textStream: emptyAsyncIterable()
@@ -2005,8 +2140,10 @@ export const streamAgent = (agent, input = {}) => {
             }
             const activeState = await agent.store?.load(context.state.runId, context.state.scope);
             broadcast.close();
+            const outputState = activeState ? normalizeAgentRunState(activeState) : context.state;
+            await finishInvocation(outputState.status);
             return {
-                output: toOutput(activeState ? normalizeAgentRunState(activeState) : context.state),
+                output: toOutput(outputState),
                 textStream: emptyAsyncIterable()
             };
         }
@@ -2015,7 +2152,7 @@ export const streamAgent = (agent, input = {}) => {
             if (!context.fresh || freshRequiresExistingClaim) {
                 await claimAgentExecution(agent, context.state);
             }
-            await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals);
+            await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals, invocationStartedAt);
         }
         catch (error) {
             await executionLease.release();
@@ -2027,6 +2164,7 @@ export const streamAgent = (agent, input = {}) => {
             await emitRunFinishTelemetry(agent, state);
             await executionLease.release();
             broadcast.close();
+            await finishInvocation(state.status);
             return {
                 output: toOutput(state),
                 textStream: emptyAsyncIterable()
@@ -2064,6 +2202,7 @@ export const streamAgent = (agent, input = {}) => {
             }, true);
             broadcast.close();
             await executionLease.release();
+            await finishInvocation(failedState.status);
             return {
                 output: toOutput(failedState),
                 textStream: emptyAsyncIterable()
@@ -2084,14 +2223,16 @@ export const streamAgent = (agent, input = {}) => {
             type: "agent-step-start",
             stepIndex: context.state.currentStep + 1
         });
-        await emitTelemetryEvent(agent, {
-            type: "step-start",
-            runId: context.state.runId,
-            agentId: context.state.agentId,
-            stepIndex: context.state.currentStep + 1
-        });
-        const abortContext = createAgentAbortContext(mergeAbortSignals(input.abortSignal, executionLease.signal), policy);
-        const executionEnvironmentSession = await acquireExecutionEnvironment(context.executionEnvironment, context.state, context.context, abortContext.signal);
+        const abortContext = createAgentAbortContext(input.abortSignal, policy, executionLease.signal);
+        let executionEnvironmentSession;
+        try {
+            executionEnvironmentSession = await acquireExecutionEnvironment(context.executionEnvironment, context.state, context.context, abortContext.signal);
+        }
+        catch (error) {
+            abortContext.cleanup();
+            await executionLease.release();
+            throw error;
+        }
         activeExecutionEnvironment = executionEnvironmentSession;
         let executionEnvironmentStatus = "failed";
         let executionEnvironmentError;
@@ -2105,6 +2246,7 @@ export const streamAgent = (agent, input = {}) => {
             }));
         }
         catch (error) {
+            abortContext.cleanup();
             executionEnvironmentError = {
                 message: error instanceof Error ? error.message : String(error)
             };
@@ -2117,7 +2259,7 @@ export const streamAgent = (agent, input = {}) => {
             throw error;
         }
         const approvalRequests = [];
-        const eventRelay = (async () => {
+        const eventRelay = withAgentTelemetryRunContext(agent, context.state.runId, async () => {
             for await (const event of streamResult.eventStream) {
                 await publish(event);
                 if (event.type === "tool-approval-request") {
@@ -2162,7 +2304,7 @@ export const streamAgent = (agent, input = {}) => {
                     });
                 }
             }
-        })();
+        });
         const output = (async () => {
             try {
                 const final = await withAgentPolicyTimeout(eventRelay.then(() => streamResult.collect()), abortContext);
@@ -2291,12 +2433,13 @@ export const streamAgent = (agent, input = {}) => {
                 activeExecutionEnvironment = undefined;
                 await executionLease.release();
             }
-        })();
+        })().finally(() => finishInvocation(executionEnvironmentStatus, executionEnvironmentError ? new Error(executionEnvironmentError.message) : undefined));
         return {
             output,
             textStream: streamResult.textStream
         };
     })().catch(async (error) => {
+        await finishInvocation("failed", error instanceof Error ? error : new Error(String(error)));
         await activeExecutionEnvironment?.release?.({
             status: "failed",
             error: { message: error instanceof Error ? error.message : String(error) }