@axiastudio/aioc 0.1.0-alpha.0

package/dist/run.js

@@ -0,0 +1,497 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamedRunResult = void 0;
+exports.run = run;
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+const messages_1 = require("./messages");
+const run_log_emitter_1 = require("./run-log-emitter");
+const run_recorder_runtime_1 = require("./run-recorder-runtime");
+const run_context_1 = require("./run-context");
+const zod_1 = require("zod");
+function normalizeInput(input) {
+    if (typeof input === "string") {
+        return [(0, messages_1.user)(input)];
+    }
+    return [...input];
+}
+function parseArguments(rawArguments) {
+    const trimmed = rawArguments.trim();
+    if (!trimmed) {
+        return {};
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return {
+            __raw: rawArguments,
+        };
+    }
+}
+function resolveAgentModel(agent) {
+    const model = agent.model?.trim();
+    if (!model) {
+        throw new Error(`Agent "${agent.name}" has no model configured. Set "model" explicitly.`);
+    }
+    return model;
+}
+function sanitizeToolSegment(input) {
+    const sanitized = input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return sanitized || "agent";
+}
+function buildTurnTools(agent) {
+    const handoffRegistry = new Map();
+    const handoffTools = [];
+    const reservedNames = new Set(agent.tools.map((tool) => tool.name));
+    for (const handoffAgent of agent.handoffs) {
+        const baseName = `handoff_to_${sanitizeToolSegment(handoffAgent.name)}`;
+        let toolName = baseName;
+        let suffix = 2;
+        while (reservedNames.has(toolName) || handoffRegistry.has(toolName)) {
+            toolName = `${baseName}_${suffix}`;
+            suffix += 1;
+        }
+        handoffRegistry.set(toolName, handoffAgent);
+        reservedNames.add(toolName);
+        handoffTools.push({
+            name: toolName,
+            description: handoffAgent.handoffDescription
+                ? `Handoff to agent "${handoffAgent.name}". ${handoffAgent.handoffDescription}`
+                : `Handoff to agent "${handoffAgent.name}".`,
+            parameters: zod_1.z.object({}).passthrough(),
+            execute: () => ({ handoffTo: handoffAgent.name }),
+        });
+    }
+    return {
+        providerTools: [...agent.tools, ...handoffTools],
+        handoffRegistry,
+    };
+}
+function toErrorMetadata(error) {
+    if (error instanceof Error) {
+        return {
+            errorName: error.name,
+            errorMessage: error.message,
+        };
+    }
+    return {
+        errorName: "Error",
+        errorMessage: String(error),
+    };
+}
+function createDeniedPolicyResult(reason, metadata) {
+    return {
+        decision: "deny",
+        reason,
+        metadata,
+    };
+}
+function shouldReturnDeniedAsToolResult(policyResult) {
+    return (policyResult.decision === "deny" && policyResult.denyMode === "tool_result");
+}
+function toAllowedToolResultEnvelope(data) {
+    return {
+        status: "ok",
+        code: null,
+        publicReason: null,
+        data,
+    };
+}
+function toDeniedToolResultEnvelope(policyResult) {
+    return {
+        status: "denied",
+        code: policyResult.reason,
+        publicReason: policyResult.publicReason?.trim() || "Action not allowed.",
+        data: null,
+    };
+}
+function isPolicyResult(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    const validDecision = candidate.decision === "allow" || candidate.decision === "deny";
+    const validPublicReason = typeof candidate.publicReason === "undefined" ||
+        typeof candidate.publicReason === "string";
+    const validDenyMode = typeof candidate.denyMode === "undefined" ||
+        candidate.denyMode === "throw" ||
+        candidate.denyMode === "tool_result";
+    return (validDecision &&
+        typeof candidate.reason === "string" &&
+        candidate.reason.trim().length > 0 &&
+        validPublicReason &&
+        validDenyMode);
+}
+async function evaluateToolPolicy(agent, call, parsedArguments, runContext, turn, policies) {
+    const policy = policies?.toolPolicy;
+    if (!policy) {
+        return createDeniedPolicyResult("policy_not_configured");
+    }
+    let rawResult;
+    try {
+        rawResult = await policy({
+            agentName: agent.name,
+            toolName: call.name,
+            rawArguments: call.arguments,
+            parsedArguments,
+            runContext,
+            turn,
+        });
+    }
+    catch (error) {
+        return createDeniedPolicyResult("policy_error", toErrorMetadata(error));
+    }
+    if (!isPolicyResult(rawResult)) {
+        return createDeniedPolicyResult("invalid_policy_result");
+    }
+    return rawResult;
+}
+async function evaluateHandoffPolicy(fromAgent, toAgent, call, handoffPayload, runContext, turn, policies) {
+    const policy = policies?.handoffPolicy;
+    if (!policy) {
+        return createDeniedPolicyResult("policy_not_configured");
+    }
+    let rawResult;
+    try {
+        rawResult = await policy({
+            fromAgentName: fromAgent.name,
+            toAgentName: toAgent.name,
+            handoffPayload,
+            runContext,
+            turn,
+        });
+    }
+    catch (error) {
+        return createDeniedPolicyResult("policy_error", toErrorMetadata(error));
+    }
+    if (!isPolicyResult(rawResult)) {
+        return createDeniedPolicyResult("invalid_policy_result");
+    }
+    return rawResult;
+}
+async function executeToolCall(agent, call, parsedArguments, runContext, turn, logEmitter, policies, onPolicyDecision) {
+    const definition = agent.tools.find((tool) => tool.name === call.name);
+    if (!definition) {
+        throw new errors_1.ToolCallError(`Tool "${call.name}" is not registered.`);
+    }
+    const policyResult = await evaluateToolPolicy(agent, call, parsedArguments, runContext, turn, policies);
+    await logEmitter.toolPolicyEvaluated(agent.name, turn, call.name, call.callId, policyResult.decision, policyResult.reason, policyResult.policyVersion, policyResult.metadata);
+    onPolicyDecision?.({
+        turn,
+        callId: call.callId,
+        decision: policyResult.decision,
+        reason: policyResult.reason,
+        policyVersion: policyResult.policyVersion,
+        resource: {
+            kind: "tool",
+            name: call.name,
+        },
+        metadata: policyResult.metadata,
+    });
+    if (policyResult.decision !== "allow") {
+        if (shouldReturnDeniedAsToolResult(policyResult)) {
+            return toDeniedToolResultEnvelope(policyResult);
+        }
+        throw new errors_1.ToolCallPolicyDeniedError({
+            toolName: call.name,
+            policyResult,
+        });
+    }
+    const validated = definition.parameters.parse(parsedArguments);
+    const toolOutput = await definition.execute(validated, runContext);
+    return toAllowedToolResultEnvelope(toolOutput);
+}
+async function evaluateOutputGuardrails(agent, runContext, history, outputText, logEmitter, turn, onGuardrailDecision) {
+    for (const guardrail of agent.outputGuardrails) {
+        await logEmitter.outputGuardrailStarted(agent.name, turn, guardrail.name);
+        const output = await guardrail.execute({
+            agent,
+            runContext,
+            outputText,
+            history: [...history],
+        });
+        if (output.tripwireTriggered) {
+            onGuardrailDecision?.({
+                turn,
+                guardrailName: guardrail.name,
+                decision: "triggered",
+                reason: output.reason,
+                metadata: output.metadata,
+            });
+            await logEmitter.outputGuardrailTriggered(agent.name, turn, guardrail.name, output.reason);
+            throw new errors_1.OutputGuardrailTripwireTriggered({
+                guardrail: guardrail.name,
+                output,
+                outputText,
+            });
+        }
+        onGuardrailDecision?.({
+            turn,
+            guardrailName: guardrail.name,
+            decision: "pass",
+        });
+        await logEmitter.outputGuardrailPassed(agent.name, turn, guardrail.name);
+    }
+}
+async function* runLoop(state, provider, runContext, maxTurns, logger, policies, onPolicyDecision, onGuardrailDecision) {
+    const logEmitter = new run_log_emitter_1.RunLogEmitter(logger);
+    await logEmitter.runStarted(state.lastAgent.name, maxTurns, state.history.length);
+    yield {
+        type: "agent_updated_stream_event",
+        agent: state.lastAgent,
+    };
+    await logEmitter.agentActivated(state.lastAgent.name, 1);
+    let activeTurn = 0;
+    try {
+        for (let turn = 0; turn < maxTurns; turn += 1) {
+            activeTurn = turn + 1;
+            const currentAgent = state.lastAgent;
+            await logEmitter.turnStarted(currentAgent.name, activeTurn);
+            const { providerTools, handoffRegistry } = buildTurnTools(currentAgent);
+            const providerStream = provider.stream({
+                model: resolveAgentModel(currentAgent),
+                systemPrompt: await currentAgent.resolveInstructions(runContext),
+                messages: state.history,
+                tools: providerTools,
+                modelSettings: currentAgent.modelSettings,
+            });
+            let outputText = "";
+            const pendingToolCalls = [];
+            let sawDelta = false;
+            const hasOutputGuardrails = currentAgent.outputGuardrails.length > 0;
+            const bufferedDeltas = [];
+            for await (const modelEvent of providerStream) {
+                if (modelEvent.type === "delta") {
+                    sawDelta = true;
+                    outputText += modelEvent.delta;
+                    if (hasOutputGuardrails) {
+                        bufferedDeltas.push(modelEvent.delta);
+                    }
+                    else {
+                        yield {
+                            type: "raw_model_stream_event",
+                            data: { delta: modelEvent.delta },
+                        };
+                    }
+                    continue;
+                }
+                if (modelEvent.type === "tool_call") {
+                    pendingToolCalls.push({
+                        callId: modelEvent.callId,
+                        name: modelEvent.name,
+                        arguments: modelEvent.arguments,
+                    });
+                    continue;
+                }
+                if (!sawDelta && modelEvent.message) {
+                    outputText = modelEvent.message;
+                }
+            }
+            if (hasOutputGuardrails) {
+                await evaluateOutputGuardrails(currentAgent, runContext, state.history, outputText, logEmitter, activeTurn, onGuardrailDecision);
+                for (const delta of bufferedDeltas) {
+                    yield {
+                        type: "raw_model_stream_event",
+                        data: { delta },
+                    };
+                }
+            }
+            if (pendingToolCalls.length > 0) {
+                for (const call of pendingToolCalls) {
+                    const callItemArguments = parseArguments(call.arguments);
+                    const callItem = {
+                        type: "tool_call_item",
+                        callId: call.callId,
+                        name: call.name,
+                        arguments: callItemArguments,
+                        rawItem: {
+                            type: "function_call",
+                            id: call.callId,
+                            name: call.name,
+                            arguments: call.arguments,
+                        },
+                    };
+                    state.history.push(callItem);
+                    yield {
+                        type: "run_item_stream_event",
+                        item: callItem,
+                    };
+                    await logEmitter.toolCallStarted(currentAgent.name, activeTurn, call.name, call.callId);
+                    const handoffTarget = handoffRegistry.get(call.name);
+                    let toolOutput;
+                    let handoffTransitioned = false;
+                    try {
+                        if (handoffTarget) {
+                            const handoffPolicyResult = await evaluateHandoffPolicy(currentAgent, handoffTarget, call, callItemArguments, runContext, activeTurn, policies);
+                            await logEmitter.handoffPolicyEvaluated(currentAgent.name, activeTurn, call.name, call.callId, handoffTarget.name, handoffPolicyResult.decision, handoffPolicyResult.reason, handoffPolicyResult.policyVersion, handoffPolicyResult.metadata);
+                            onPolicyDecision?.({
+                                turn: activeTurn,
+                                callId: call.callId,
+                                decision: handoffPolicyResult.decision,
+                                reason: handoffPolicyResult.reason,
+                                policyVersion: handoffPolicyResult.policyVersion,
+                                resource: {
+                                    kind: "handoff",
+                                    name: handoffTarget.name,
+                                },
+                                metadata: handoffPolicyResult.metadata,
+                            });
+                            if (handoffPolicyResult.decision !== "allow") {
+                                if (shouldReturnDeniedAsToolResult(handoffPolicyResult)) {
+                                    toolOutput = toDeniedToolResultEnvelope(handoffPolicyResult);
+                                }
+                                else {
+                                    throw new errors_1.HandoffPolicyDeniedError({
+                                        fromAgent: currentAgent.name,
+                                        toAgent: handoffTarget.name,
+                                        policyResult: handoffPolicyResult,
+                                    });
+                                }
+                            }
+                            else {
+                                toolOutput = toAllowedToolResultEnvelope({
+                                    handoffTo: handoffTarget.name,
+                                    accepted: true,
+                                    payload: callItemArguments,
+                                });
+                                state.lastAgent = handoffTarget;
+                                handoffTransitioned = true;
+                            }
+                        }
+                        else {
+                            toolOutput = await executeToolCall(currentAgent, call, callItemArguments, runContext, activeTurn, logEmitter, policies, onPolicyDecision);
+                        }
+                    }
+                    catch (error) {
+                        await logEmitter.toolCallFailed(currentAgent.name, activeTurn, call.name, call.callId, error);
+                        throw error;
+                    }
+                    await logEmitter.toolCallCompleted(currentAgent.name, activeTurn, call.name, call.callId);
+                    const outputItem = {
+                        type: "tool_call_output_item",
+                        callId: call.callId,
+                        output: toolOutput,
+                        rawItem: {
+                            type: "function_call_result",
+                            call_id: call.callId,
+                            output: toolOutput,
+                        },
+                    };
+                    state.history.push(outputItem);
+                    yield {
+                        type: "run_item_stream_event",
+                        item: outputItem,
+                    };
+                    if (handoffTransitioned) {
+                        yield {
+                            type: "agent_updated_stream_event",
+                            agent: state.lastAgent,
+                        };
+                        await logEmitter.agentActivated(state.lastAgent.name, activeTurn);
+                    }
+                }
+                continue;
+            }
+            const outputItem = {
+                type: "message_output_item",
+                content: outputText,
+            };
+            yield {
+                type: "run_item_stream_event",
+                item: outputItem,
+            };
+            state.history.push({
+                type: "message",
+                role: "assistant",
+                content: outputText,
+            });
+            await logEmitter.runCompleted(currentAgent.name, activeTurn, outputText.length);
+            return;
+        }
+        throw new errors_1.MaxTurnsExceededError(maxTurns);
+    }
+    catch (error) {
+        await logEmitter.runFailed(state.lastAgent.name, activeTurn || undefined, error);
+        throw error;
+    }
+}
+class StreamedRunResult {
+    consumed = false;
+    stream;
+    state;
+    constructor(stream, state) {
+        this.stream = stream;
+        this.state = state;
+    }
+    toStream() {
+        if (this.consumed) {
+            throw new Error("This stream can only be consumed once.");
+        }
+        this.consumed = true;
+        return this.stream;
+    }
+    get history() {
+        return this.state.history;
+    }
+    get lastAgent() {
+        return this.state.lastAgent;
+    }
+}
+exports.StreamedRunResult = StreamedRunResult;
+async function run(startingAgent, input, options = {}) {
+    const runContext = new run_context_1.RunContext((options.context ?? {}));
+    const state = {
+        history: normalizeInput(input),
+        lastAgent: startingAgent,
+    };
+    const provider = (0, config_1.getDefaultProvider)();
+    const maxTurns = options.maxTurns ?? 10;
+    const runRecorder = await run_recorder_runtime_1.RunRecorder.create({
+        input,
+        context: runContext.context,
+        providerName: provider.constructor.name,
+        recordOptions: options.record,
+    });
+    const rawStream = runLoop(state, provider, runContext, maxTurns, options.logger, options.policies, runRecorder.onPolicyDecision, runRecorder.onGuardrailDecision);
+    const runRecordSnapshot = () => ({
+        agentName: state.lastAgent.name,
+        model: state.lastAgent.model,
+        items: state.history,
+    });
+    const stream = (async function* () {
+        try {
+            for await (const event of rawStream) {
+                if (event.type === "run_item_stream_event" &&
+                    event.item.type === "message_output_item") {
+                    runRecorder.onMessageOutput(event.item.content);
+                }
+                yield event;
+            }
+            await runRecorder.emitCompleted(runRecordSnapshot());
+        }
+        catch (error) {
+            await runRecorder.emitFailed(runRecordSnapshot(), error);
+            throw error;
+        }
+    })();
+    if (options.stream === true) {
+        return new StreamedRunResult(stream, state);
+    }
+    let finalOutput = "";
+    for await (const event of stream) {
+        if (event.type === "run_item_stream_event" &&
+            event.item.type === "message_output_item") {
+            finalOutput = event.item.content;
+        }
+    }
+    return {
+        finalOutput,
+        history: state.history,
+        lastAgent: state.lastAgent,
+    };
+}

package/dist/tests/integration/chat-completions.integration.d.ts

@@ -0,0 +1,2 @@
+export declare function runChatCompletionsIntegrationTests(): Promise<void>;
+//# sourceMappingURL=chat-completions.integration.d.ts.map

package/dist/tests/integration/chat-completions.integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-completions.integration.d.ts","sourceRoot":"","sources":["../../../src/tests/integration/chat-completions.integration.ts"],"names":[],"mappings":"AAmBA,wBAAsB,kCAAkC,IAAI,OAAO,CAAC,IAAI,CAAC,CA8GxE"}

package/dist/tests/integration/chat-completions.integration.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChatCompletionsIntegrationTests = runChatCompletionsIntegrationTests;
+const strict_1 = __importDefault(require("node:assert/strict"));
+const zod_1 = require("zod");
+const messages_1 = require("../../messages");
+const tool_1 = require("../../tool");
+const chat_completions_1 = require("../../providers/chat-completions");
+function createSseBody(chunks) {
+    const encoder = new TextEncoder();
+    return new ReadableStream({
+        start(controller) {
+            for (const chunk of chunks) {
+                controller.enqueue(encoder.encode(chunk));
+            }
+            controller.close();
+        },
+    });
+}
+async function runChatCompletionsIntegrationTests() {
+    const originalFetch = globalThis.fetch;
+    let capturedBody = "";
+    const streamBody = createSseBody([
+        `data: ${JSON.stringify({ choices: [{ delta: { content: "Ciao " } }] })}\n\n`,
+        `data: ${JSON.stringify({
+            choices: [
+                {
+                    delta: {
+                        tool_calls: [
+                            {
+                                index: 0,
+                                id: "call_1",
+                                function: {
+                                    name: "lookup",
+                                    arguments: JSON.stringify({ q: "aioc" }),
+                                },
+                            },
+                        ],
+                    },
+                },
+            ],
+        })}\n\n`,
+        `data: ${JSON.stringify({ choices: [{ finish_reason: "tool_calls" }] })}\n\n`,
+        "data: [DONE]\n\n",
+    ]);
+    globalThis.fetch = (async (_input, init) => {
+        capturedBody = String(init?.body ?? "");
+        return new Response(streamBody, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/event-stream",
+            },
+        });
+    });
+    try {
+        const lookupTool = (0, tool_1.tool)({
+            name: "lookup",
+            description: "Lookup docs",
+            parameters: zod_1.z.object({
+                q: zod_1.z.string(),
+            }),
+            execute: () => ({ ok: true }),
+        });
+        const provider = new chat_completions_1.ChatCompletionsProvider({
+            apiKey: "test-key",
+            baseURL: "https://example.test/v1/",
+        });
+        const events = [];
+        for await (const event of provider.stream({
+            model: "test-model",
+            systemPrompt: "System instructions",
+            messages: [(0, messages_1.user)("Hi")],
+            tools: [lookupTool],
+            modelSettings: {
+                temperature: 0.1,
+                top_p: 0.9,
+                ignored_setting: true,
+            },
+        })) {
+            events.push(event);
+        }
+        const payload = JSON.parse(capturedBody);
+        strict_1.default.equal(payload.model, "test-model");
+        strict_1.default.equal(payload.stream, true);
+        strict_1.default.equal(payload.temperature, 0.1);
+        strict_1.default.equal(payload.top_p, 0.9);
+        strict_1.default.equal(payload.ignored_setting, undefined);
+        strict_1.default.equal(payload.tool_choice, "auto");
+        const messages = payload.messages;
+        strict_1.default.equal(messages[0]?.role, "system");
+        strict_1.default.equal(messages[0]?.content, "System instructions");
+        strict_1.default.equal(messages[1]?.role, "user");
+        strict_1.default.equal(messages[1]?.content, "Hi");
+        const tools = payload.tools;
+        strict_1.default.equal(tools.length, 1);
+        strict_1.default.equal(tools[0]?.function?.name, "lookup");
+        strict_1.default.equal(events[0]?.type, "delta");
+        strict_1.default.equal(events[0].delta, "Ciao ");
+        strict_1.default.equal(events[1]?.type, "tool_call");
+        strict_1.default.equal(events[1].name, "lookup");
+        strict_1.default.equal(events[2]?.type, "completed");
+        strict_1.default.equal(events[2].finishReason, "tool_calls");
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+}

package/dist/tests/integration/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/tests/integration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tests/integration/index.ts"],"names":[],"mappings":""}

package/dist/tests/integration/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chat_completions_integration_1 = require("./chat-completions.integration");
+async function main() {
+    await (0, chat_completions_integration_1.runChatCompletionsIntegrationTests)();
+    process.stdout.write("Integration tests passed.\n");
+}
+main().catch((error) => {
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+});

package/dist/tests/regression/handoff-policy-trace.regression.d.ts

@@ -0,0 +1,2 @@
+export declare function runHandoffPolicyTraceRegressionTests(): Promise<void>;
+//# sourceMappingURL=handoff-policy-trace.regression.d.ts.map

package/dist/tests/regression/handoff-policy-trace.regression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-policy-trace.regression.d.ts","sourceRoot":"","sources":["../../../src/tests/regression/handoff-policy-trace.regression.ts"],"names":[],"mappings":"AAaA,wBAAsB,oCAAoC,IAAI,OAAO,CAAC,IAAI,CAAC,CA4G1E"}