@zhivex-ai/core 1.18.0 → 1.19.1

package/dist/agent/lifecycle.js

@@ -0,0 +1,184 @@
+import { normalizeAgentRunState } from "../agent-state.js";
+import { ConflictError, ValidationError } from "../errors.js";
+import { createMergedAbortSignal } from "../runtime.js";
+import { randomId } from "./common.js";
+const DEFAULT_AGENT_LEASE_TTL_MS = 30_000;
+const DEFAULT_AGENT_CANCELLATION_POLL_MS = 1_000;
+const DEFAULT_AGENT_MONITOR_SHUTDOWN_TIMEOUT_MS = 1_000;
+export class AgentPolicyTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Agent run timed out after ${timeoutMs}ms.`);
+        this.name = "AgentPolicyTimeoutError";
+    }
+}
+export const resolveRunPolicy = (agent, input) => {
+    const policy = {
+        ...(agent.policy ?? {}),
+        ...(input.policy ?? {})
+    };
+    return Object.keys(policy).length ? policy : undefined;
+};
+export const withAgentPolicyTimeout = async (operation, timeout) => {
+    try {
+        return timeout.timeoutPromise
+            ? await Promise.race([operation, timeout.timeoutPromise])
+            : await operation;
+    }
+    finally {
+        timeout.cleanup();
+    }
+};
+export const createAgentAbortContext = (inputAbortSignal, policy, ...additionalSignals) => {
+    if (!policy?.timeoutMs) {
+        const merged = createMergedAbortSignal(inputAbortSignal, ...additionalSignals);
+        return {
+            signal: merged.signal,
+            timeoutPromise: undefined,
+            cleanup: merged.cleanup,
+            isTimedOut: () => false
+        };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+            reject(new AgentPolicyTimeoutError(policy.timeoutMs));
+        }, policy.timeoutMs);
+    });
+    const merged = createMergedAbortSignal(inputAbortSignal, ...additionalSignals, controller.signal);
+    return {
+        signal: merged.signal,
+        timeoutPromise,
+        cleanup: () => {
+            merged.cleanup();
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+        },
+        isTimedOut: () => timedOut
+    };
+};
+const waitForAgentMonitorShutdown = async (monitor, timeoutMs) => {
+    let timeout;
+    const deadline = new Promise((resolve) => {
+        timeout = setTimeout(resolve, timeoutMs);
+    });
+    try {
+        await Promise.race([monitor, deadline]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+};
+export const acquireAgentExecutionLease = async (agent, state, policy) => {
+    const store = agent.store;
+    if (policy?.leaseMode === "disabled" || !store?.acquireLease || !store.renewLease || !store.releaseLease) {
+        return {
+            supported: false,
+            cancelledState: () => undefined,
+            leaseLost: () => false,
+            release: async () => undefined
+        };
+    }
+    const ttlMs = policy?.leaseTtlMs ?? DEFAULT_AGENT_LEASE_TTL_MS;
+    const heartbeatMs = policy?.heartbeatMs ?? Math.max(250, Math.floor(ttlMs / 3));
+    const cancellationPollMs = policy?.cancellationPollMs ?? DEFAULT_AGENT_CANCELLATION_POLL_MS;
+    for (const [name, value] of [
+        ["leaseTtlMs", ttlMs],
+        ["heartbeatMs", heartbeatMs],
+        ["cancellationPollMs", cancellationPollMs]
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1) {
+            throw new ValidationError(`Agent policy "${name}" must be a positive integer.`);
+        }
+    }
+    if (heartbeatMs >= ttlMs) {
+        throw new ValidationError('Agent policy "heartbeatMs" must be less than "leaseTtlMs".');
+    }
+    const ownerId = randomId("worker");
+    const lease = await store.acquireLease(state.runId, { ownerId, ttlMs }, state.scope);
+    if (!lease) {
+        return undefined;
+    }
+    const controller = new AbortController();
+    let cancelled;
+    let lost = false;
+    let stopped = false;
+    let activeMonitor;
+    let lastHeartbeat = Date.now();
+    let lastCancellationPoll = 0;
+    const intervalMs = Math.max(25, Math.min(heartbeatMs, cancellationPollMs));
+    const monitorShutdownTimeoutMs = Math.min(ttlMs, DEFAULT_AGENT_MONITOR_SHUTDOWN_TIMEOUT_MS);
+    const cleanupStoppedMonitorLease = async () => {
+        try {
+            await store.releaseLease?.(state.runId, ownerId, state.scope);
+        }
+        catch {
+            // The foreground release remains authoritative; late monitor cleanup is best effort.
+        }
+    };
+    const monitorLease = async () => {
+        const now = Date.now();
+        try {
+            if (now - lastHeartbeat >= heartbeatMs) {
+                const renewed = await store.renewLease?.(state.runId, { ownerId, ttlMs }, state.scope);
+                if (stopped) {
+                    await cleanupStoppedMonitorLease();
+                    return;
+                }
+                if (!renewed) {
+                    lost = true;
+                    controller.abort(new ConflictError(`Agent run "${state.runId}" lost its worker lease.`));
+                    return;
+                }
+                lastHeartbeat = now;
+            }
+            if (now - lastCancellationPoll >= cancellationPollMs) {
+                const latest = await store.load(state.runId, state.scope);
+                if (stopped)
+                    return;
+                lastCancellationPoll = now;
+                if (latest?.status === "cancel_requested" || latest?.status === "cancelled") {
+                    cancelled = normalizeAgentRunState(latest);
+                    controller.abort(new Error(latest.cancellationReason ?? "Agent run was cancelled."));
+                }
+            }
+        }
+        catch (error) {
+            if (stopped) {
+                await cleanupStoppedMonitorLease();
+                return;
+            }
+            lost = true;
+            controller.abort(error);
+        }
+    };
+    const timer = setInterval(() => {
+        if (stopped || activeMonitor)
+            return;
+        activeMonitor = monitorLease().finally(() => {
+            activeMonitor = undefined;
+        });
+    }, intervalMs);
+    timer.unref?.();
+    return {
+        supported: true,
+        signal: controller.signal,
+        cancelledState: () => cancelled,
+        leaseLost: () => lost,
+        release: async () => {
+            stopped = true;
+            clearInterval(timer);
+            const monitor = activeMonitor;
+            if (monitor) {
+                await waitForAgentMonitorShutdown(monitor, monitorShutdownTimeoutMs);
+            }
+            await store.releaseLease?.(state.runId, ownerId, state.scope);
+        }
+    };
+};
+//# sourceMappingURL=lifecycle.js.map

package/dist/agent/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/agent/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/agent/state.d.ts

@@ -0,0 +1,6 @@
+import type { AgentDefinition, AgentRunOutput, AgentRunState, AgentRunPolicy, AgentRunStore, AgentStep, GenerateTextOutput, LanguageModel, ToolExecutionResult } from "../types.js";
+export declare const finalizeState: <TOutput>(agent: AgentDefinition<LanguageModel, any, TOutput>, state: AgentRunState, result: GenerateTextOutput, newSteps: AgentStep[], newToolResults: ToolExecutionResult[]) => AgentRunOutput<TOutput>;
+export declare const saveStateWithRevision: (store: AgentRunStore, state: AgentRunState, serializedNextState?: string) => Promise<void>;
+export declare const claimAgentExecution: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState) => Promise<void>;
+export declare const persistState: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, policy?: AgentRunPolicy) => Promise<void>;
+//# sourceMappingURL=state.d.ts.map

package/dist/agent/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/agent/state.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAarB,eAAO,MAAM,aAAa,GAAI,OAAO,SAC5B,eAAe,CAAC,aAAa,EAAE,GAAG,EAAE,OAAO,CAAC,SAC5C,aAAa,UACZ,kBAAkB,YAChB,SAAS,EAAE,kBACL,mBAAmB,EAAE,KACpC,cAAc,CAAC,OAAO,CA0DxB,CAAC;AAEF,eAAO,MAAM,qBAAqB,UAAiB,aAAa,SAAS,aAAa,wBAAwB,MAAM,kBAMnH,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,aAAa,SAC7D,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,kBAQrB,CAAC;AAqBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,aAAa,SACtD,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,WACX,cAAc,kBA8BxB,CAAC"}

package/dist/agent/state.js

@@ -0,0 +1,119 @@
+import { refreshAgentTaskOutcome } from "../agent-reconciliation.js";
+import { getAgentApprovalRequests } from "../agent-approval.js";
+import { normalizeAgentRunState } from "../agent-state.js";
+import { ValidationError } from "../errors.js";
+import { aggregateTokenUsage } from "../generate-text.js";
+import { serializeJsonValue } from "../messages.js";
+import { cloneState, hasToolCalls, toOutput } from "./common.js";
+import { emitTelemetryEvent, invokeOperationalHook } from "./telemetry.js";
+const DEFAULT_AGENT_MAX_STATE_BYTES = 4 * 1024 * 1024;
+export const finalizeState = (agent, state, result, newSteps, newToolResults) => {
+    const nextCurrentStep = state.currentStep + newSteps.length;
+    const exhausted = nextCurrentStep >= state.maxSteps;
+    const lastStep = newSteps.at(-1);
+    const unresolvedToolCalls = lastStep?.response ? hasToolCalls(lastStep.response.messages) : false;
+    const pendingApprovals = [
+        ...(result.approvalRequests ?? []),
+        ...getAgentApprovalRequests(newSteps.flatMap((step) => step.response?.messages ?? []))
+    ];
+    if (pendingApprovals.length) {
+        state.status = "waiting_approval";
+        state.error = undefined;
+        if (lastStep) {
+            lastStep.status = "waiting_approval";
+        }
+    }
+    else if (exhausted && unresolvedToolCalls) {
+        state.status = "failed";
+        state.error = {
+            message: "Agent exhausted maxSteps before reaching a terminal response."
+        };
+        if (lastStep) {
+            lastStep.status = "failed";
+            lastStep.error = state.error;
+        }
+    }
+    else {
+        state.status = "completed";
+        state.error = undefined;
+    }
+    state.messages = result.messages;
+    state.steps = [...state.steps, ...newSteps];
+    state.toolResults = [...state.toolResults, ...newToolResults];
+    state.currentStep = nextCurrentStep;
+    state.outputText = result.text;
+    if (state.status === "completed") {
+        const terminalText = result.steps.at(-1)?.response.text ?? result.text;
+        if (agent.outputSchema) {
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(terminalText);
+            }
+            catch (error) {
+                throw new ValidationError("Agent final output is not valid JSON.", { cause: error });
+            }
+            const parsedOutput = agent.outputSchema.safeParse(parsedJson);
+            if (!parsedOutput.success) {
+                throw new ValidationError(`Agent final output validation failed: ${parsedOutput.error.message}`);
+            }
+            state.finalOutput = serializeJsonValue(parsedOutput.data);
+        }
+    }
+    state.finishReason = result.finishReason;
+    state.providerFinishReason = result.providerFinishReason;
+    state.usage = aggregateTokenUsage([state.usage, result.usage]);
+    state.pendingApprovals = pendingApprovals;
+    state.updatedAt = Date.now();
+    return toOutput(state);
+};
+export const saveStateWithRevision = async (store, state, serializedNextState) => {
+    const expectedRevision = state.revision ?? 0;
+    const nextRevision = expectedRevision + 1;
+    const nextState = { ...state, revision: nextRevision };
+    await store.save(serializedNextState === undefined ? cloneState(nextState) : JSON.parse(serializedNextState), { expectedRevision });
+    state.revision = nextRevision;
+};
+export const claimAgentExecution = async (agent, state) => {
+    state.status = "running";
+    state.updatedAt = Date.now();
+    const serialized = assertStateSize(agent, agent.store ? normalizeAgentRunState({ ...state, revision: (state.revision ?? 0) + 1 }) : state);
+    if (agent.store) {
+        await saveStateWithRevision(agent.store, state, serialized);
+    }
+};
+const assertStateSize = (agent, state, policy) => {
+    const limit = policy?.maxStateBytes ?? agent.policy?.maxStateBytes ?? DEFAULT_AGENT_MAX_STATE_BYTES;
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new ValidationError('Agent policy "maxStateBytes" must be a positive integer.');
+    }
+    const serialized = JSON.stringify(state);
+    const bytes = new TextEncoder().encode(serialized).byteLength;
+    if (bytes > limit) {
+        throw new ValidationError(`Agent run state is ${bytes} bytes and exceeds maxStateBytes=${limit}. Offload large tool outputs to artifacts or raise the explicit limit.`);
+    }
+    return serialized;
+};
+export const persistState = async (agent, state, policy) => {
+    state.updatedAt = Date.now();
+    await refreshAgentTaskOutcome(state, agent.store);
+    const serialized = assertStateSize(agent, agent.store ? normalizeAgentRunState({ ...state, revision: (state.revision ?? 0) + 1 }) : state, policy);
+    if (agent.store) {
+        await saveStateWithRevision(agent.store, state, serialized);
+    }
+    await emitTelemetryEvent(agent, {
+        type: "state-saved",
+        runId: state.runId,
+        agentId: state.agentId,
+        status: state.status
+    });
+    await invokeOperationalHook(agent, "memory", "save", state.runId, agent.memory?.save
+        ? () => agent.memory.save({
+            runId: state.runId,
+            agentId: state.agentId,
+            scope: state.scope,
+            state: cloneState(state),
+            metadata: state.metadata
+        })
+        : undefined, undefined);
+};
+//# sourceMappingURL=state.js.map

package/dist/agent/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/agent/state.ts"],"names":[],"mappings":"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"}

package/dist/agent/telemetry.d.ts

@@ -0,0 +1,12 @@
+import type { AgentApprovalRequest, AgentApprovalResponse, AgentDefinition, AgentRunState, AgentStep, AgentStatus, AgentTelemetryEvent, LanguageModel, ModelMessage, ToolApprovalEvent } from "../types.js";
+export declare const invokeOperationalHook: <TModel extends LanguageModel, TResult>(agent: AgentDefinition<TModel>, source: "telemetry" | "memory", operation: string, runId: string | undefined, callback: (() => TResult | Promise<TResult>) | undefined, fallback: TResult) => Promise<TResult>;
+export declare const emitTelemetryEvent: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, event: AgentTelemetryEvent) => Promise<void>;
+export declare const emitInvocationStartTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, runId: string, startedAt: number, maxSteps: number) => Promise<void>;
+export declare const emitInvocationFinishTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, runId: string, status: AgentStatus, error: Error | undefined) => Promise<void>;
+export declare const withAgentTelemetryRunContext: <TModel extends LanguageModel, TResult>(agent: AgentDefinition<TModel>, runId: string, callback: () => TResult | Promise<TResult>) => Promise<TResult>;
+export declare const emitFinalizedStepTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, steps: AgentStep[]) => Promise<void>;
+export declare const emitApprovalTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, approvals: AgentApprovalRequest[]) => Promise<void>;
+export declare const emitToolApprovalTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, event: ToolApprovalEvent) => Promise<void>;
+export declare const emitRunStartTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, memoryMessages: ModelMessage[], approvals: AgentApprovalResponse[] | undefined, invocationStartedAt: number) => Promise<void>;
+export declare const emitRunFinishTelemetry: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState) => Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/agent/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/agent/telemetry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,SAAS,EACT,WAAW,EACX,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAKrB,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,aAAa,EAAE,OAAO,SACxE,eAAe,CAAC,MAAM,CAAC,UACtB,WAAW,GAAG,QAAQ,aACnB,MAAM,SACV,MAAM,GAAG,SAAS,YACf,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,YAC9C,OAAO,KAChB,OAAO,CAAC,OAAO,CAwBjB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,MAAM,SAAS,aAAa,SAC5D,eAAe,CAAC,MAAM,CAAC,SACvB,mBAAmB,kBAW3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,GAAU,MAAM,SAAS,aAAa,SACtE,eAAe,CAAC,MAAM,CAAC,SACvB,MAAM,aACF,MAAM,YACP,MAAM,kBAejB,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,aAAa,SACvE,eAAe,CAAC,MAAM,CAAC,SACvB,MAAM,UACL,WAAW,SACZ,KAAK,GAAG,SAAS,kBAczB,CAAC;AAEF,eAAO,MAAM,4BAA4B,GAAI,MAAM,SAAS,aAAa,EAAE,OAAO,SACzE,eAAe,CAAC,MAAM,CAAC,SACvB,MAAM,YACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KACzC,OAAO,CAAC,OAAO,CAgCjB,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAU,MAAM,SAAS,aAAa,SACpE,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,SACb,SAAS,EAAE,kBAUnB,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,aAAa,SAC/D,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,aACT,oBAAoB,EAAE,kBAUlC,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAU,MAAM,SAAS,aAAa,SACnE,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,SACb,iBAAiB,kBAWzB,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,aAAa,SAC/D,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,kBACJ,YAAY,EAAE,aACnB,qBAAqB,EAAE,GAAG,SAAS,uBACzB,MAAM,kBAuC5B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,MAAM,SAAS,aAAa,SAChE,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,kBAWrB,CAAC"}

package/dist/agent/telemetry.js

@@ -0,0 +1,176 @@
+import { runViewSink } from "../agent-run-view.js";
+import { cloneState } from "./common.js";
+export const invokeOperationalHook = async (agent, source, operation, runId, callback, fallback) => {
+    if (!callback) {
+        return fallback;
+    }
+    try {
+        return await callback();
+    }
+    catch (error) {
+        const normalizedError = error instanceof Error ? error : new Error(String(error));
+        try {
+            await agent.hookFailurePolicy?.onError?.({
+                source,
+                operation,
+                runId,
+                error: normalizedError
+            });
+        }
+        catch {
+            // Reporting an observer failure must never recursively fail the run.
+        }
+        if (agent.hookFailurePolicy?.[source] === "fail") {
+            throw normalizedError;
+        }
+        return fallback;
+    }
+};
+export const emitTelemetryEvent = async (agent, event) => {
+    await agent[runViewSink]?.(event, agent);
+    await invokeOperationalHook(agent, "telemetry", event.type, event.runId, agent.onTelemetryEvent ? () => agent.onTelemetryEvent(event) : undefined, undefined);
+};
+export 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.
+    }
+};
+export 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.
+    }
+};
+export 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;
+        }
+    });
+};
+export const emitFinalizedStepTelemetry = async (agent, state, steps) => {
+    for (const step of steps) {
+        await emitTelemetryEvent(agent, {
+            type: "step-finish",
+            runId: state.runId,
+            agentId: state.agentId,
+            step
+        });
+    }
+};
+export const emitApprovalTelemetry = async (agent, state, approvals) => {
+    for (const approval of approvals) {
+        await emitTelemetryEvent(agent, {
+            type: "approval-request",
+            runId: state.runId,
+            agentId: state.agentId,
+            approval
+        });
+    }
+};
+export const emitToolApprovalTelemetry = async (agent, state, event) => {
+    await emitTelemetryEvent(agent, {
+        type: "tool-approval",
+        runId: state.runId,
+        agentId: state.agentId,
+        toolCall: event.request.toolCall,
+        approved: event.decision.approved,
+        reason: event.decision.reason,
+        metadata: event.decision.metadata
+    });
+};
+export 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,
+        startedAt: invocationStartedAt
+    });
+    if (state.handoff) {
+        await emitTelemetryEvent(agent, {
+            type: "handoff",
+            runId: state.runId,
+            agentId: state.agentId,
+            handoff: state.handoff
+        });
+    }
+    if (memoryMessages.length) {
+        await emitTelemetryEvent(agent, {
+            type: "memory-loaded",
+            runId: state.runId,
+            agentId: state.agentId,
+            messageCount: memoryMessages.length
+        });
+    }
+    for (const approval of approvals ?? []) {
+        await emitTelemetryEvent(agent, {
+            type: "approval-resolved",
+            runId: state.runId,
+            agentId: state.agentId,
+            approval
+        });
+    }
+};
+export const emitRunFinishTelemetry = async (agent, state) => {
+    await emitTelemetryEvent(agent, {
+        type: "run-finish",
+        runId: state.runId,
+        agentId: state.agentId,
+        agentName: agent.name,
+        status: state.status,
+        state: cloneState(state),
+        finishedAt: Date.now()
+    });
+};
+//# sourceMappingURL=telemetry.js.map

package/dist/agent/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/agent/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/agent/tool-execution.d.ts

@@ -0,0 +1,6 @@
+import type { AgentDefinition, AgentExecutionEnvironment, AgentExecutionEnvironmentSession, AgentRunState, JsonValue, LanguageModel, ToolDefinition } from "../types.js";
+export declare const durableToolCallId: (runId: string, step: number, providerToolCallId: string, toolName: string, input: JsonValue) => string;
+export declare const wrapToolWithExecutionEnvironment: (tool: ToolDefinition, session: AgentExecutionEnvironmentSession) => ToolDefinition;
+export declare const wrapToolWithJournal: <TModel extends LanguageModel>(agent: AgentDefinition<TModel>, state: AgentRunState, tool: ToolDefinition) => ToolDefinition;
+export declare const acquireExecutionEnvironment: <TContext>(environment: AgentExecutionEnvironment<TContext> | undefined, state: AgentRunState, context: TContext | undefined, abortSignal: AbortSignal | undefined) => Promise<AgentExecutionEnvironmentSession<TContext> | undefined>;
+//# sourceMappingURL=tool-execution.d.ts.map

package/dist/agent/tool-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution.d.ts","sourceRoot":"","sources":["../../src/agent/tool-execution.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,eAAe,EACf,yBAAyB,EACzB,gCAAgC,EAChC,aAAa,EAEb,SAAS,EACT,aAAa,EACb,cAAc,EAGf,MAAM,aAAa,CAAC;AAerB,eAAO,MAAM,iBAAiB,UACrB,MAAM,QACP,MAAM,sBACQ,MAAM,YAChB,MAAM,SACT,SAAS,KACf,MAGiB,CAAC;AAErB,eAAO,MAAM,gCAAgC,SACrC,cAAc,WACX,gCAAgC,KACxC,cA2DF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM,SAAS,aAAa,SACvD,eAAe,CAAC,MAAM,CAAC,SACvB,aAAa,QACd,cAAc,KACnB,cAoFF,CAAC;AAEF,eAAO,MAAM,2BAA2B,GAAU,QAAQ,eAC3C,yBAAyB,CAAC,QAAQ,CAAC,GAAG,SAAS,SACrD,aAAa,WACX,QAAQ,GAAG,SAAS,eAChB,WAAW,GAAG,SAAS,KACnC,OAAO,CAAC,gCAAgC,CAAC,QAAQ,CAAC,GAAG,SAAS,CA+BhE,CAAC"}