@zhivex-ai/core 0.4.0 → 0.5.0

package/dist/agent.js

@@ -0,0 +1,701 @@
+import { createAgentApprovalMessage, getAgentApprovalRequests } from "./agent-approval.js";
+import { createAgentHandoffMessage } from "./agent-handoff.js";
+import { GuardrailTriggeredError, ValidationError } from "./errors.js";
+import { generateText, normalizeMessages, streamText } from "./generate-text.js";
+import { toToolSet } from "./tool-registry.js";
+const randomId = (prefix) => `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
+const joinInstructions = (...parts) => {
+    const content = parts.map((part) => part?.trim()).filter((part) => Boolean(part));
+    return content.length ? content.join("\n\n") : undefined;
+};
+const hasToolCalls = (messages) => messages.some((message) => message.parts.some((part) => part.type === "tool-call"));
+const snapshotRequest = (request) => ({
+    messages: request.messages,
+    toolChoice: request.toolChoice,
+    toolExecution: request.toolExecution,
+    temperature: request.temperature,
+    maxTokens: request.maxTokens,
+    reasoning: request.reasoning,
+    providerOptions: request.providerOptions,
+    timeoutMs: request.timeoutMs,
+    maxRetries: request.maxRetries,
+    retryBackoffMs: request.retryBackoffMs
+});
+const snapshotResponse = (response) => ({
+    messages: response.messages ?? (response.message ? [response.message] : []),
+    text: response.text,
+    finishReason: response.finishReason,
+    providerFinishReason: response.providerFinishReason,
+    usage: response.usage
+});
+const countToolCalls = (messages) => messages.reduce((total, message) => total + message.parts.filter((part) => part.type === "tool-call").length, 0);
+const mapSteps = (steps, offset, toolResults) => {
+    let toolResultCursor = 0;
+    return steps.map((step, index) => {
+        const response = snapshotResponse(step.response);
+        const toolCallCount = countToolCalls(response.messages);
+        const stepToolResults = toolResults.slice(toolResultCursor, toolResultCursor + toolCallCount);
+        toolResultCursor += toolCallCount;
+        const finishedAt = Date.now();
+        return {
+            index: offset + index + 1,
+            status: "completed",
+            startedAt: finishedAt,
+            finishedAt,
+            request: snapshotRequest(step.request),
+            response,
+            toolResults: stepToolResults
+        };
+    });
+};
+const cloneMetadata = (...values) => {
+    const merged = Object.assign({}, ...values.filter(Boolean));
+    return Object.keys(merged).length ? merged : undefined;
+};
+const toOutput = (state) => ({
+    status: state.status,
+    outputText: state.outputText,
+    finishReason: state.finishReason,
+    providerFinishReason: state.providerFinishReason,
+    usage: state.usage,
+    messages: state.messages,
+    steps: state.steps,
+    toolResults: state.toolResults,
+    state,
+    error: state.error
+});
+const cloneState = (state) => JSON.parse(JSON.stringify(state));
+const createBaseState = (provider, modelId, initialMessages, maxSteps, metadata, agentId, runId, handoff) => {
+    const startedAt = Date.now();
+    return {
+        runId,
+        agentId,
+        parentRunId: handoff?.fromRunId,
+        provider,
+        modelId,
+        status: "running",
+        messages: initialMessages,
+        steps: [],
+        toolResults: [],
+        currentStep: 0,
+        maxSteps,
+        outputText: "",
+        pendingApprovals: [],
+        metadata,
+        handoff,
+        startedAt,
+        updatedAt: startedAt
+    };
+};
+const ensureValidStateInput = (input) => {
+    if (input.approvals?.length && !input.state) {
+        throw new ValidationError('The "approvals" option requires an existing agent "state".');
+    }
+    if (!input.state) {
+        return;
+    }
+    if (input.prompt !== undefined || input.messages !== undefined || input.system !== undefined || input.handoff !== undefined) {
+        throw new ValidationError('Pass either "state" or a fresh "prompt"/"messages" input, but not both.');
+    }
+};
+const injectContextMessages = (messages, extraMessages) => {
+    if (!extraMessages.length) {
+        return messages;
+    }
+    if (messages[0]?.role === "system") {
+        return [messages[0], ...extraMessages, ...messages.slice(1)];
+    }
+    return [...extraMessages, ...messages];
+};
+const prepareFreshMessages = async (agent, input, runId) => {
+    let messages = normalizeMessages({
+        prompt: input.prompt,
+        messages: input.messages,
+        system: joinInstructions(agent.instructions, input.system)
+    });
+    const handoffMessages = input.handoff
+        ? [createAgentHandoffMessage(input.handoff), ...input.handoff.contextMessages.filter((message) => message.role !== "system")]
+        : [];
+    messages = injectContextMessages(messages, handoffMessages);
+    const memoryMessages = agent.memory
+        ? await agent.memory.load({
+            runId,
+            agentId: agent.id,
+            metadata: cloneMetadata(agent.metadata, input.metadata)
+        })
+        : [];
+    messages = injectContextMessages(messages, memoryMessages);
+    return {
+        messages,
+        memoryMessages
+    };
+};
+const applyApprovalResponses = (messages, approvals, pendingApprovals) => {
+    if (!approvals?.length) {
+        return {
+            messages,
+            pendingApprovals
+        };
+    }
+    const pendingById = new Map(pendingApprovals.map((approval) => [approval.id, approval]));
+    for (const approval of approvals) {
+        const pending = pendingById.get(approval.approvalRequestId);
+        if (!pending) {
+            throw new ValidationError(`Unknown approval request "${approval.approvalRequestId}".`);
+        }
+        if (pending.provider !== approval.provider) {
+            throw new ValidationError(`Approval request "${approval.approvalRequestId}" belongs to provider "${pending.provider}", not "${approval.provider}".`);
+        }
+    }
+    return {
+        messages: [...messages, createAgentApprovalMessage(approvals)],
+        pendingApprovals: pendingApprovals.filter((pending) => !approvals.some((approval) => approval.approvalRequestId === pending.id))
+    };
+};
+const finalizeState = (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 = getAgentApprovalRequests(newSteps.flatMap((step) => step.response?.messages ?? []));
+    if (pendingApprovals.length) {
+        state.status = "suspended";
+        state.error = undefined;
+        if (lastStep) {
+            lastStep.status = "suspended";
+        }
+    }
+    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;
+    state.finishReason = result.finishReason;
+    state.providerFinishReason = result.providerFinishReason;
+    state.usage = result.usage;
+    state.pendingApprovals = pendingApprovals;
+    state.updatedAt = Date.now();
+    return toOutput(state);
+};
+const emitTelemetryEvent = async (agent, event) => {
+    await agent.onTelemetryEvent?.(event);
+};
+const persistState = async (agent, state) => {
+    state.updatedAt = Date.now();
+    await agent.store?.save(cloneState(state));
+    await emitTelemetryEvent(agent, {
+        type: "state-saved",
+        runId: state.runId,
+        agentId: state.agentId,
+        status: state.status
+    });
+    await agent.memory?.save?.({
+        runId: state.runId,
+        agentId: state.agentId,
+        state: cloneState(state),
+        metadata: state.metadata
+    });
+};
+const approvalsFromEvents = (messages) => getAgentApprovalRequests(messages);
+const emitFinalizedStepTelemetry = async (agent, state, steps) => {
+    for (const step of steps) {
+        await emitTelemetryEvent(agent, {
+            type: "step-finish",
+            runId: state.runId,
+            agentId: state.agentId,
+            step
+        });
+    }
+};
+const emitApprovalTelemetry = async (agent, state, approvals) => {
+    for (const approval of approvals) {
+        await emitTelemetryEvent(agent, {
+            type: "approval-request",
+            runId: state.runId,
+            agentId: state.agentId,
+            approval
+        });
+    }
+};
+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
+    });
+};
+const normalizeGuardrailTrigger = (value) => value?.triggered ? value : undefined;
+const applyGuardrailFailure = (state, stage, trigger) => ({
+    ...state,
+    status: "failed",
+    error: {
+        message: trigger.reason ?? `Agent ${stage} guardrail triggered.`
+    },
+    updatedAt: Date.now()
+});
+const runGuardrails = async (agent, state, stage, guardrails, requestFactory) => {
+    for (const [index, guardrail] of (guardrails ?? []).entries()) {
+        const trigger = normalizeGuardrailTrigger(await guardrail(requestFactory(index)));
+        if (!trigger) {
+            continue;
+        }
+        await emitTelemetryEvent(agent, {
+            type: "guardrail-triggered",
+            runId: state.runId,
+            agentId: state.agentId,
+            stage,
+            reason: trigger.reason ?? `Agent ${stage} guardrail #${index + 1} triggered.`,
+            metadata: trigger.metadata
+        });
+        return trigger;
+    }
+    return undefined;
+};
+const resolveContext = async (agent, input) => {
+    let loadedState = input.state;
+    if (!loadedState && input.runId && agent.store) {
+        loadedState = await agent.store.load(input.runId);
+    }
+    const normalizedInput = loadedState ? { ...input, state: loadedState } : input;
+    ensureValidStateInput(normalizedInput);
+    const metadata = cloneMetadata(agent.metadata, loadedState?.metadata, input.metadata, input.handoff?.metadata);
+    if (loadedState) {
+        const maxSteps = input.maxSteps ?? loadedState.maxSteps;
+        const resumed = applyApprovalResponses(loadedState.messages, input.approvals, loadedState.pendingApprovals);
+        return {
+            state: {
+                ...loadedState,
+                agentId: loadedState.agentId ?? agent.id,
+                provider: agent.model.provider,
+                modelId: agent.model.modelId,
+                maxSteps,
+                messages: resumed.messages,
+                pendingApprovals: resumed.pendingApprovals,
+                metadata,
+                updatedAt: Date.now()
+            },
+            messages: resumed.messages,
+            remainingSteps: Math.max(0, maxSteps - loadedState.currentStep),
+            memoryMessages: []
+        };
+    }
+    const runId = input.runId ?? randomId("run");
+    const maxSteps = Math.max(1, input.maxSteps ?? agent.maxSteps ?? 1);
+    const prepared = await prepareFreshMessages(agent, input, runId);
+    return {
+        state: createBaseState(agent.model.provider, agent.model.modelId, prepared.messages, maxSteps, metadata, agent.id, runId, input.handoff),
+        messages: prepared.messages,
+        remainingSteps: maxSteps,
+        memoryMessages: prepared.memoryMessages
+    };
+};
+const createGenerateOptions = (agent, state, input, messages, maxSteps) => ({
+    model: agent.model,
+    messages,
+    tools: toToolSet(input.tools ?? agent.tools),
+    toolChoice: input.toolChoice,
+    toolExecution: input.toolExecution ?? agent.toolExecution,
+    toolApprovalPolicy: input.toolApprovalPolicy ?? agent.toolApprovalPolicy,
+    onToolApprovalDecision: async (event) => {
+        await emitToolApprovalTelemetry(agent, state, event);
+    },
+    maxSteps,
+    temperature: input.temperature ?? agent.temperature,
+    maxTokens: input.maxTokens ?? agent.maxTokens,
+    reasoning: input.reasoning ?? agent.reasoning,
+    providerOptions: input.providerOptions ?? agent.providerOptions,
+    abortSignal: input.abortSignal,
+    timeoutMs: input.timeoutMs,
+    maxRetries: input.maxRetries,
+    retryBackoffMs: input.retryBackoffMs
+});
+const emptyAsyncIterable = async function* () {
+    return;
+};
+const createFailedState = (state, message) => ({
+    ...state,
+    status: "failed",
+    error: {
+        message
+    },
+    updatedAt: Date.now()
+});
+const emitRunStartTelemetry = async (agent, state, memoryMessages, approvals) => {
+    await emitTelemetryEvent(agent, {
+        type: "run-start",
+        runId: state.runId,
+        agentId: state.agentId,
+        provider: state.provider,
+        modelId: state.modelId,
+        maxSteps: state.maxSteps
+    });
+    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
+        });
+    }
+};
+const emitRunFinishTelemetry = async (agent, state) => {
+    await emitTelemetryEvent(agent, {
+        type: "run-finish",
+        runId: state.runId,
+        agentId: state.agentId,
+        status: state.status,
+        state: cloneState(state)
+    });
+};
+export const createAgent = (definition) => ({
+    ...definition,
+    metadata: cloneMetadata(definition.metadata)
+});
+export const runAgent = async (agent, input = {}) => {
+    const context = await resolveContext(agent, input);
+    await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals);
+    if (context.state.status === "completed" || context.state.status === "cancelled") {
+        return toOutput(context.state);
+    }
+    if (context.state.status === "suspended" && context.state.pendingApprovals.length > 0 && !input.approvals?.length) {
+        return toOutput(context.state);
+    }
+    if (context.remainingSteps === 0) {
+        const state = createFailedState(context.state, "Agent exhausted maxSteps before reaching a terminal response.");
+        await persistState(agent, state);
+        await emitRunFinishTelemetry(agent, state);
+        return toOutput(state);
+    }
+    const inputGuardrail = await runGuardrails(agent, context.state, "input", agent.inputGuardrails, () => ({
+        runId: context.state.runId,
+        agentId: context.state.agentId,
+        messages: context.messages,
+        metadata: context.state.metadata
+    }));
+    if (inputGuardrail) {
+        const failedState = applyGuardrailFailure(context.state, "input", inputGuardrail);
+        await persistState(agent, failedState);
+        await emitRunFinishTelemetry(agent, failedState);
+        return toOutput(failedState);
+    }
+    await emitTelemetryEvent(agent, {
+        type: "step-start",
+        runId: context.state.runId,
+        agentId: context.state.agentId,
+        stepIndex: context.state.currentStep + 1
+    });
+    try {
+        const result = await generateText(createGenerateOptions(agent, context.state, input, context.messages, context.remainingSteps));
+        const newSteps = mapSteps(result.steps, context.state.currentStep, result.toolResults);
+        let output = finalizeState(context.state, result, newSteps, result.toolResults);
+        const outputGuardrail = await runGuardrails(agent, output.state, "output", agent.outputGuardrails, () => ({
+            runId: output.state.runId,
+            agentId: output.state.agentId,
+            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, approvalsFromEvents(newSteps.flatMap((step) => step.response?.messages ?? [])));
+        await persistState(agent, output.state);
+        await emitRunFinishTelemetry(agent, output.state);
+        return output;
+    }
+    catch (error) {
+        const failedState = createFailedState(context.state, error instanceof Error ? error.message : String(error));
+        await persistState(agent, failedState);
+        await emitRunFinishTelemetry(agent, failedState);
+        throw error;
+    }
+};
+export const streamAgent = (agent, input = {}) => {
+    const subscribers = new Set();
+    const history = [];
+    let done = false;
+    const publish = (value) => {
+        history.push(value);
+        for (const subscriber of subscribers) {
+            subscriber(value);
+        }
+        if (value.done) {
+            done = true;
+        }
+    };
+    const createEventStream = async function* () {
+        let cursor = 0;
+        while (true) {
+            while (cursor < history.length) {
+                const item = history[cursor];
+                cursor += 1;
+                if (item.done) {
+                    return;
+                }
+                yield item.value;
+            }
+            if (done) {
+                return;
+            }
+            await new Promise((resolve) => {
+                const subscriber = (value) => {
+                    subscribers.delete(subscriber);
+                    resolve(value);
+                };
+                subscribers.add(subscriber);
+            });
+        }
+    };
+    const runner = (async () => {
+        const context = await resolveContext(agent, input);
+        await emitRunStartTelemetry(agent, context.state, context.memoryMessages, input.approvals);
+        if (context.state.status === "completed" || context.state.status === "cancelled") {
+            publish({ done: true, value: undefined });
+            return {
+                output: toOutput(context.state),
+                textStream: emptyAsyncIterable()
+            };
+        }
+        if (context.state.status === "suspended" && context.state.pendingApprovals.length > 0 && !input.approvals?.length) {
+            publish({ done: true, value: undefined });
+            return {
+                output: toOutput(context.state),
+                textStream: emptyAsyncIterable()
+            };
+        }
+        if (context.remainingSteps === 0) {
+            const state = createFailedState(context.state, "Agent exhausted maxSteps before reaching a terminal response.");
+            await persistState(agent, state);
+            await emitRunFinishTelemetry(agent, state);
+            publish({ done: true, value: undefined });
+            return {
+                output: toOutput(state),
+                textStream: emptyAsyncIterable()
+            };
+        }
+        const inputGuardrail = await runGuardrails(agent, context.state, "input", agent.inputGuardrails, () => ({
+            runId: context.state.runId,
+            agentId: context.state.agentId,
+            messages: context.messages,
+            metadata: context.state.metadata
+        }));
+        if (inputGuardrail) {
+            const failedState = applyGuardrailFailure(context.state, "input", inputGuardrail);
+            await persistState(agent, failedState);
+            await emitRunFinishTelemetry(agent, failedState);
+            publish({
+                done: false,
+                value: {
+                    type: "error",
+                    error: new GuardrailTriggeredError("input", failedState.error?.message ?? "Agent input guardrail triggered.", {
+                        metadata: inputGuardrail.metadata
+                    })
+                }
+            });
+            publish({
+                done: false,
+                value: {
+                    type: "agent-run-finish",
+                    status: failedState.status,
+                    state: failedState
+                }
+            });
+            publish({ done: true, value: undefined });
+            return {
+                output: toOutput(failedState),
+                textStream: emptyAsyncIterable()
+            };
+        }
+        publish({
+            done: false,
+            value: {
+                type: "agent-run-start",
+                currentStep: context.state.currentStep + 1,
+                maxSteps: context.state.maxSteps
+            }
+        });
+        for (const approval of input.approvals ?? []) {
+            publish({
+                done: false,
+                value: {
+                    type: "agent-approval-resolved",
+                    approval
+                }
+            });
+        }
+        publish({
+            done: false,
+            value: {
+                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 streamResult = streamText(createGenerateOptions(agent, context.state, input, context.messages, context.remainingSteps));
+        const approvalRequests = [];
+        const eventRelay = (async () => {
+            for await (const event of streamResult.eventStream) {
+                publish({ done: false, value: event });
+                if (event.type === "provider-data" &&
+                    typeof event.data === "object" &&
+                    event.data !== null &&
+                    !Array.isArray(event.data) &&
+                    event.data.type === "mcp_approval_request" &&
+                    typeof event.data.id === "string" &&
+                    typeof event.data.name === "string" &&
+                    typeof event.data.arguments === "string") {
+                    const approval = {
+                        provider: event.provider,
+                        id: event.data.id,
+                        name: event.data.name,
+                        arguments: event.data.arguments,
+                        serverLabel: typeof event.data.server_label === "string" ? event.data.server_label : undefined,
+                        rawData: event.data
+                    };
+                    approvalRequests.push(approval);
+                    publish({
+                        done: false,
+                        value: {
+                            type: "agent-approval-request",
+                            approval
+                        }
+                    });
+                    await emitTelemetryEvent(agent, {
+                        type: "approval-request",
+                        runId: context.state.runId,
+                        agentId: context.state.agentId,
+                        approval
+                    });
+                }
+            }
+        })();
+        const output = (async () => {
+            try {
+                await eventRelay;
+                const final = await streamResult.collect();
+                const newSteps = mapSteps(final.steps, context.state.currentStep, final.toolResults);
+                let result = finalizeState(context.state, final, newSteps, final.toolResults);
+                const outputGuardrail = await runGuardrails(agent, result.state, "output", agent.outputGuardrails, () => ({
+                    runId: result.state.runId,
+                    agentId: result.state.agentId,
+                    state: cloneState(result.state),
+                    output: result,
+                    metadata: result.state.metadata
+                }));
+                if (outputGuardrail) {
+                    result = toOutput(applyGuardrailFailure(result.state, "output", outputGuardrail));
+                    publish({
+                        done: false,
+                        value: {
+                            type: "error",
+                            error: new GuardrailTriggeredError("output", result.state.error?.message ?? "Agent output guardrail triggered.", { metadata: outputGuardrail.metadata })
+                        }
+                    });
+                }
+                for (const step of newSteps) {
+                    publish({
+                        done: false,
+                        value: {
+                            type: "agent-step-finish",
+                            step
+                        }
+                    });
+                }
+                await emitFinalizedStepTelemetry(agent, result.state, newSteps);
+                if (!approvalRequests.length) {
+                    await emitApprovalTelemetry(agent, result.state, approvalsFromEvents(newSteps.flatMap((step) => step.response?.messages ?? [])));
+                }
+                await persistState(agent, result.state);
+                await emitRunFinishTelemetry(agent, result.state);
+                publish({
+                    done: false,
+                    value: {
+                        type: "agent-run-finish",
+                        status: result.status,
+                        state: result.state
+                    }
+                });
+                publish({ done: true, value: undefined });
+                return result;
+            }
+            catch (error) {
+                const failedState = createFailedState(context.state, error instanceof Error ? error.message : String(error));
+                await persistState(agent, failedState);
+                await emitRunFinishTelemetry(agent, failedState);
+                publish({
+                    done: false,
+                    value: {
+                        type: "error",
+                        error: error instanceof Error ? error : new Error(String(error))
+                    }
+                });
+                publish({
+                    done: false,
+                    value: {
+                        type: "agent-run-finish",
+                        status: failedState.status,
+                        state: failedState
+                    }
+                });
+                publish({ done: true, value: undefined });
+                throw error;
+            }
+        })();
+        return {
+            output,
+            textStream: streamResult.textStream
+        };
+    })();
+    return {
+        eventStream: createEventStream(),
+        textStream: (async function* () {
+            const started = await runner;
+            for await (const chunk of started.textStream) {
+                yield chunk;
+            }
+        })(),
+        collect: async () => (await runner).output
+    };
+};
+export const resumeAgent = async (agent, input) => runAgent(agent, input);
+//# sourceMappingURL=agent.js.map