@axiastudio/aioc 0.1.0-alpha.0

package/dist/examples/onboarding-governance-tutorial.js

@@ -0,0 +1,342 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const zod_1 = require("zod");
+const index_1 = require("../index");
+const POLICY_VERSION = "onboarding-policy.v1";
+class SequencedProvider {
+    turns;
+    index = 0;
+    constructor(turns) {
+        this.turns = turns;
+    }
+    async *stream(_request) {
+        void _request;
+        const events = this.turns[this.index] ?? [];
+        this.index += 1;
+        for (const event of events) {
+            yield event;
+        }
+    }
+}
+function asObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return {};
+    }
+    return value;
+}
+function asBoolean(value, fallback = false) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function allow(reason, metadata) {
+    return {
+        decision: "allow",
+        reason,
+        policyVersion: POLICY_VERSION,
+        metadata,
+    };
+}
+function deny(reason, metadata) {
+    return {
+        decision: "deny",
+        reason,
+        policyVersion: POLICY_VERSION,
+        metadata,
+    };
+}
+function createPolicies() {
+    const toolPolicy = ({ toolName, parsedArguments, runContext, }) => {
+        const context = runContext.context;
+        const args = asObject(parsedArguments);
+        const privileged = asBoolean(args.privileged);
+        if (toolName === "create_corporate_identity") {
+            if (!context.actor.groups.includes("onboarding-admin")) {
+                return deny("deny_missing_onboarding_admin_group");
+            }
+            return allow("allow_onboarding_admin_identity_creation");
+        }
+        if (toolName === "activate_access") {
+            if (!context.compliance.mandatoryTrainingCompleted) {
+                return deny("deny_missing_compliance_training");
+            }
+            if (privileged && !context.approvals.securityApproved) {
+                return deny("deny_missing_security_approval");
+            }
+            return allow("allow_access_activation_requirements_met", {
+                privileged,
+            });
+        }
+        return deny("deny_tool_not_allowlisted");
+    };
+    const handoffPolicy = ({ fromAgentName, toAgentName, handoffPayload, runContext, }) => {
+        const context = runContext.context;
+        const payload = asObject(handoffPayload);
+        const privileged = asBoolean(payload.privileged);
+        if (fromAgentName !== "Onboarding Coordinator" ||
+            toAgentName !== "Security Agent") {
+            return deny("deny_handoff_not_allowlisted");
+        }
+        if (privileged && !context.approvals.managerApproved) {
+            return deny("deny_missing_manager_approval");
+        }
+        if (privileged && !context.approvals.securityApproved) {
+            return deny("deny_missing_security_approval");
+        }
+        return allow("allow_privileged_escalation_path", {
+            privileged,
+        });
+    };
+    return {
+        toolPolicy,
+        handoffPolicy,
+    };
+}
+function maskEmail(email) {
+    const [local, domain] = email.split("@");
+    if (!domain) {
+        return "[REDACTED]";
+    }
+    if (local.length < 2) {
+        return `*@${domain}`;
+    }
+    return `${local[0]}***${local[local.length - 1]}@${domain}`;
+}
+function redactContext(context) {
+    return {
+        contextSnapshot: {
+            ...context,
+            actor: {
+                ...context.actor,
+                email: maskEmail(context.actor.email),
+            },
+            pii: {
+                taxId: "[REDACTED]",
+                personalPhone: "[REDACTED]",
+            },
+        },
+        contextRedacted: true,
+    };
+}
+function createContext(input) {
+    return {
+        tenantId: "corp-acme",
+        employeeId: input.employeeId,
+        actor: {
+            userId: "hr-ops-01",
+            groups: [...input.groups],
+            email: "hr.ops@corp.example",
+        },
+        compliance: {
+            mandatoryTrainingCompleted: input.mandatoryTrainingCompleted,
+        },
+        approvals: {
+            managerApproved: input.managerApproved,
+            securityApproved: input.securityApproved,
+        },
+        runtimeState: {
+            identityCreated: false,
+            accessActivated: false,
+        },
+        pii: {
+            taxId: "AAABBB99C99Z999Z",
+            personalPhone: "+39-555-123-456",
+        },
+    };
+}
+function createAgentGraph() {
+    const createCorporateIdentity = (0, index_1.tool)({
+        name: "create_corporate_identity",
+        description: "Create identity in enterprise IAM.",
+        parameters: zod_1.z.object({}),
+        execute: (_input, runContext) => {
+            if (runContext) {
+                runContext.context.runtimeState.identityCreated = true;
+            }
+            return {
+                identityCreated: true,
+            };
+        },
+    });
+    const activateAccess = (0, index_1.tool)({
+        name: "activate_access",
+        description: "Activate application access.",
+        parameters: zod_1.z.object({
+            app: zod_1.z.string(),
+            privileged: zod_1.z.boolean().default(false),
+        }),
+        execute: (input, runContext) => {
+            if (runContext) {
+                runContext.context.runtimeState.accessActivated = true;
+            }
+            return {
+                activated: true,
+                app: input.app,
+                privileged: input.privileged,
+            };
+        },
+    });
+    const securityAgent = new index_1.Agent({
+        name: "Security Agent",
+        model: "fake-model",
+        tools: [activateAccess],
+    });
+    return new index_1.Agent({
+        name: "Onboarding Coordinator",
+        model: "fake-model",
+        tools: [createCorporateIdentity, activateAccess],
+        handoffs: [securityAgent],
+    });
+}
+function createHappyPathTurns() {
+    return [
+        [
+            {
+                type: "tool_call",
+                callId: "call-1",
+                name: "create_corporate_identity",
+                arguments: "{}",
+            },
+        ],
+        [
+            {
+                type: "tool_call",
+                callId: "call-2",
+                name: "handoff_to_security_agent",
+                arguments: JSON.stringify({
+                    privileged: true,
+                    app: "ERP_FINANCE",
+                }),
+            },
+        ],
+        [
+            {
+                type: "tool_call",
+                callId: "call-3",
+                name: "activate_access",
+                arguments: JSON.stringify({
+                    privileged: true,
+                    app: "ERP_FINANCE",
+                }),
+            },
+        ],
+        [
+            {
+                type: "completed",
+                message: "Onboarding completed: identity and privileged access are active.",
+            },
+        ],
+    ];
+}
+function createHandoffDenyTurns() {
+    return [
+        [
+            {
+                type: "tool_call",
+                callId: "call-1",
+                name: "create_corporate_identity",
+                arguments: "{}",
+            },
+        ],
+        [
+            {
+                type: "tool_call",
+                callId: "call-2",
+                name: "handoff_to_security_agent",
+                arguments: JSON.stringify({
+                    privileged: true,
+                    app: "ERP_FINANCE",
+                }),
+            },
+        ],
+    ];
+}
+function printRunRecord(label, record) {
+    process.stdout.write(`\n=== ${label} ===\n`);
+    process.stdout.write(`status: ${record.status}\n`);
+    process.stdout.write(`agentName: ${record.agentName}\n`);
+    process.stdout.write(`question: ${record.question}\n`);
+    process.stdout.write(`response: ${record.response}\n`);
+    process.stdout.write(`contextRedacted: ${String(record.contextRedacted)}\n`);
+    process.stdout.write(`redactedTaxId: ${record.contextSnapshot.pii.taxId}\n`);
+    process.stdout.write("policyDecisions:\n");
+    for (const decision of record.policyDecisions) {
+        process.stdout.write(`- turn=${decision.turn} resource=${decision.resource.kind}:${decision.resource.name} decision=${decision.decision} reason=${decision.reason} policyVersion=${decision.policyVersion ?? "n/a"}\n`);
+    }
+}
+async function runScenario(input) {
+    const records = [];
+    const policies = createPolicies();
+    const agent = createAgentGraph();
+    (0, index_1.setDefaultProvider)(new SequencedProvider(input.turns));
+    try {
+        const result = await (0, index_1.run)(agent, `Onboard employee ${input.context.employeeId} for privileged ERP access.`, {
+            context: input.context,
+            policies,
+            record: {
+                metadata: {
+                    scenario: input.label,
+                },
+                contextRedactor: redactContext,
+                sink: (record) => {
+                    records.push(record);
+                },
+            },
+        });
+        process.stdout.write(`\n[${input.label}] result: ${result.finalOutput}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof index_1.HandoffPolicyDeniedError)) {
+            throw error;
+        }
+        process.stdout.write(`\n[${input.label}] failed: ${error.result.policyResult.reason}\n`);
+    }
+    strict_1.default.equal(records.length, 1);
+    return {
+        outcome: records[0]?.status ?? "failed",
+        record: records[0],
+    };
+}
+async function main() {
+    const t0 = await runScenario({
+        label: "t0_allow",
+        context: createContext({
+            employeeId: "E-200",
+            groups: ["onboarding-admin"],
+            mandatoryTrainingCompleted: true,
+            managerApproved: true,
+            securityApproved: true,
+        }),
+        turns: createHappyPathTurns(),
+    });
+    const t1 = await runScenario({
+        label: "t1_deny",
+        context: createContext({
+            employeeId: "E-200",
+            groups: ["onboarding-admin"],
+            mandatoryTrainingCompleted: true,
+            managerApproved: true,
+            securityApproved: false,
+        }),
+        turns: createHandoffDenyTurns(),
+    });
+    printRunRecord("RunRecord @ t0 (allow)", t0.record);
+    printRunRecord("RunRecord @ t1 (deny)", t1.record);
+    const t0HandoffDecision = t0.record.policyDecisions.find((decision) => decision.resource.kind === "handoff");
+    const t1HandoffDecision = t1.record.policyDecisions.find((decision) => decision.resource.kind === "handoff");
+    strict_1.default.equal(t0.outcome, "completed");
+    strict_1.default.equal(t1.outcome, "failed");
+    strict_1.default.equal(t0HandoffDecision?.reason, "allow_privileged_escalation_path");
+    strict_1.default.equal(t1HandoffDecision?.reason, "deny_missing_security_approval");
+    process.stdout.write("\n=== Comparison ===\n");
+    process.stdout.write(`t0 handoff reason: ${t0HandoffDecision?.reason ?? "n/a"}\n`);
+    process.stdout.write(`t1 handoff reason: ${t1HandoffDecision?.reason ?? "n/a"}\n`);
+    process.stdout.write("Tutorial completed.\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/examples/policy-smoke.d.ts

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

package/dist/examples/policy-smoke.d.ts.map

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

package/dist/examples/policy-smoke.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const zod_1 = require("zod");
+const index_1 = require("../index");
+class SequencedProvider {
+    turns;
+    index = 0;
+    constructor(turns) {
+        this.turns = turns;
+    }
+    async *stream(_request) {
+        void _request;
+        const events = this.turns[this.index] ?? [];
+        this.index += 1;
+        for (const event of events) {
+            yield event;
+        }
+    }
+}
+function createAgent(onExecute) {
+    const ping = (0, index_1.tool)({
+        name: "ping",
+        description: "Simple test tool",
+        parameters: zod_1.z.object({}),
+        execute: () => {
+            onExecute();
+            return { ok: true };
+        },
+    });
+    return new index_1.Agent({
+        name: "Policy smoke agent",
+        model: "fake-model",
+        tools: [ping],
+    });
+}
+function createToolProposalRun() {
+    return [
+        [
+            {
+                type: "tool_call",
+                callId: "call-1",
+                name: "ping",
+                arguments: "{}",
+            },
+        ],
+        [{ type: "completed", message: "done" }],
+    ];
+}
+async function runAllowCase() {
+    let executions = 0;
+    (0, index_1.setDefaultProvider)(new SequencedProvider(createToolProposalRun()));
+    const toolPolicy = () => (0, index_1.allow)("allow_ping");
+    const result = await (0, index_1.run)(createAgent(() => (executions += 1)), "hello", {
+        policies: {
+            toolPolicy,
+        },
+    });
+    strict_1.default.equal(result.finalOutput, "done");
+    strict_1.default.equal(executions, 1);
+}
+async function runMissingPolicyCase() {
+    let executions = 0;
+    (0, index_1.setDefaultProvider)(new SequencedProvider(createToolProposalRun()));
+    await strict_1.default.rejects(() => (0, index_1.run)(createAgent(() => (executions += 1)), "hello"), (error) => {
+        strict_1.default.ok(error instanceof index_1.ToolCallPolicyDeniedError);
+        strict_1.default.equal(error.result.policyResult.reason, "policy_not_configured");
+        return true;
+    });
+    strict_1.default.equal(executions, 0);
+}
+async function runDenyCase() {
+    let executions = 0;
+    (0, index_1.setDefaultProvider)(new SequencedProvider(createToolProposalRun()));
+    const toolPolicy = () => (0, index_1.deny)("tool_not_allowlisted");
+    await strict_1.default.rejects(() => (0, index_1.run)(createAgent(() => (executions += 1)), "hello", {
+        policies: {
+            toolPolicy,
+        },
+    }), (error) => {
+        strict_1.default.ok(error instanceof index_1.ToolCallPolicyDeniedError);
+        strict_1.default.equal(error.result.policyResult.reason, "tool_not_allowlisted");
+        return true;
+    });
+    strict_1.default.equal(executions, 0);
+}
+async function runPolicyErrorCase() {
+    let executions = 0;
+    (0, index_1.setDefaultProvider)(new SequencedProvider(createToolProposalRun()));
+    const toolPolicy = () => {
+        throw new Error("policy exploded");
+    };
+    await strict_1.default.rejects(() => (0, index_1.run)(createAgent(() => (executions += 1)), "hello", {
+        policies: {
+            toolPolicy,
+        },
+    }), (error) => {
+        strict_1.default.ok(error instanceof index_1.ToolCallPolicyDeniedError);
+        strict_1.default.equal(error.result.policyResult.reason, "policy_error");
+        strict_1.default.equal(error.result.policyResult.metadata?.errorName, "Error");
+        return true;
+    });
+    strict_1.default.equal(executions, 0);
+}
+async function runInvalidPolicyResultCase() {
+    let executions = 0;
+    (0, index_1.setDefaultProvider)(new SequencedProvider(createToolProposalRun()));
+    const toolPolicy = (() => ({
+        decision: "allow",
+    }));
+    await strict_1.default.rejects(() => (0, index_1.run)(createAgent(() => (executions += 1)), "hello", {
+        policies: {
+            toolPolicy,
+        },
+    }), (error) => {
+        strict_1.default.ok(error instanceof index_1.ToolCallPolicyDeniedError);
+        strict_1.default.equal(error.result.policyResult.reason, "invalid_policy_result");
+        return true;
+    });
+    strict_1.default.equal(executions, 0);
+}
+async function main() {
+    await runAllowCase();
+    await runMissingPolicyCase();
+    await runDenyCase();
+    await runPolicyErrorCase();
+    await runInvalidPolicyResultCase();
+    process.stdout.write("Policy smoke 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/examples/support/scripted-provider.d.ts

@@ -0,0 +1,8 @@
+import type { ModelProvider, ProviderEvent, ProviderRequest } from "../../providers/base";
+export declare class ScriptedProvider implements ModelProvider {
+    private readonly turns;
+    private index;
+    constructor(turns: ProviderEvent[][]);
+    stream<TContext = unknown>(_request: ProviderRequest<TContext>): AsyncIterable<ProviderEvent>;
+}
+//# sourceMappingURL=scripted-provider.d.ts.map

package/dist/examples/support/scripted-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-provider.d.ts","sourceRoot":"","sources":["../../../src/examples/support/scripted-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAI9B,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,KAAK,CAAK;gBAEN,KAAK,EAAE,aAAa,EAAE,EAAE;IAI7B,MAAM,CAAC,QAAQ,GAAG,OAAO,EAC9B,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC,GAClC,aAAa,CAAC,aAAa,CAAC;CAShC"}

package/dist/examples/support/scripted-provider.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScriptedProvider = void 0;
+// Small deterministic provider used by examples:
+// each "turn" is pre-scripted, so behavior is predictable and easy to learn.
+class ScriptedProvider {
+    turns;
+    index = 0;
+    constructor(turns) {
+        this.turns = turns;
+    }
+    async *stream(_request) {
+        void _request;
+        const events = this.turns[this.index] ?? [];
+        this.index += 1;
+        for (const event of events) {
+            yield event;
+        }
+    }
+}
+exports.ScriptedProvider = ScriptedProvider;

package/dist/examples/tool-policy-finance.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=tool-policy-finance.d.ts.map

package/dist/examples/tool-policy-finance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy-finance.d.ts","sourceRoot":"","sources":["../../src/examples/tool-policy-finance.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/examples/tool-policy-finance.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const zod_1 = require("zod");
+const index_1 = require("../index");
+async function main() {
+    // Minimal provider setup from env (MISTRAL_API_KEY).
+    (0, index_1.setupMistral)();
+    // One tool: read a finance report by id.
+    const getFinanceReport = (0, index_1.tool)({
+        name: "get_finance_report",
+        description: "Return summary fields for a finance report.",
+        parameters: zod_1.z.object({
+            reportId: zod_1.z.string(),
+        }),
+        execute: async ({ reportId }) => {
+            return {
+                reportId,
+                revenue: 1240000,
+                costs: 820000,
+                margin: 420000,
+                currency: "EUR",
+            };
+        },
+    });
+    const agent = new index_1.Agent({
+        name: "Finance Analyst Agent",
+        model: "mistral-small-latest",
+        instructions: "If asked about a finance report, call get_finance_report first, then provide a short business summary.",
+        tools: [getFinanceReport],
+    });
+    // Policy gate: the tool is allowed only to users in 'finance' group.
+    const toolPolicy = ({ runContext }) => {
+        const hasFinanceAccess = runContext.context.actor.groups.includes("finance");
+        if (!hasFinanceAccess) {
+            return (0, index_1.deny)("deny_missing_finance_group", {
+                policyVersion: "finance-policy.v1",
+            });
+        }
+        return (0, index_1.allow)("allow_finance_group_access", {
+            policyVersion: "finance-policy.v1",
+        });
+    };
+    // Optional logger: prints only the policy decision event to keep output readable.
+    const logger = (0, index_1.createStdoutLogger)({
+        pretty: true,
+        events: ["tool_policy_evaluated"],
+    });
+    const stream = await (0, index_1.run)(agent, "Give me a concise summary for report Q1-2026.", {
+        stream: true,
+        context: {
+            actor: {
+                userId: "u-42",
+                groups: ["finance"],
+            },
+        },
+        policies: {
+            toolPolicy,
+        },
+        logger,
+        maxTurns: 6,
+    });
+    for await (const event of stream.toStream()) {
+        if (event.type === "run_item_stream_event" &&
+            event.item.type === "tool_call_item") {
+            process.stdout.write(`\n[tool call] ${event.item.name} ${JSON.stringify(event.item.arguments)}\n\n`);
+        }
+        if (event.type === "raw_model_stream_event") {
+            process.stdout.write(event.data.delta ?? "");
+        }
+    }
+    process.stdout.write(`\n\nCompleted. Last agent: ${stream.lastAgent.name}. History items: ${stream.history.length}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});

package/dist/examples/tool-run.d.ts

@@ -0,0 +1,2 @@
+import "dotenv/config";
+//# sourceMappingURL=tool-run.d.ts.map

package/dist/examples/tool-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-run.d.ts","sourceRoot":"","sources":["../../src/examples/tool-run.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/examples/tool-run.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const zod_1 = require("zod");
+const index_1 = require("../index");
+async function main() {
+    // Minimal provider setup from env (MISTRAL_API_KEY).
+    (0, index_1.setupMistral)();
+    // One tool: read a finance report by id.
+    const getFinanceReport = (0, index_1.tool)({
+        name: "get_finance_report",
+        description: "Return summary fields for a finance report.",
+        parameters: zod_1.z.object({
+            reportId: zod_1.z.string(),
+        }),
+        execute: async ({ reportId }) => {
+            return {
+                reportId,
+                revenue: 1240000,
+                costs: 820000,
+                margin: 420000,
+                currency: "EUR",
+            };
+        },
+    });
+    const agent = new index_1.Agent({
+        name: "Finance Analyst Agent",
+        model: "mistral-small-latest",
+        instructions: "If asked about a finance report, call get_finance_report first, then provide a short business summary.",
+        tools: [getFinanceReport],
+    });
+    // Policy gate: the tool is allowed only to users in 'finance' group.
+    const toolPolicy = ({ runContext }) => {
+        const hasFinanceAccess = runContext.context.actor.groups.includes("finance");
+        if (!hasFinanceAccess) {
+            return (0, index_1.deny)("deny_missing_finance_group", {
+                policyVersion: "finance-policy.v1",
+            });
+        }
+        return (0, index_1.allow)("allow_finance_group_access", {
+            policyVersion: "finance-policy.v1",
+        });
+    };
+    const stream = await (0, index_1.run)(agent, "Give me a concise summary for report Q1-2026.", {
+        stream: true,
+        context: {
+            actor: {
+                userId: "u-42",
+                groups: ["finance"],
+            },
+        },
+        policies: {
+            toolPolicy,
+        },
+    });
+    for await (const event of stream.toStream()) {
+        if (event.type === "run_item_stream_event" &&
+            event.item.type === "tool_call_item") {
+            process.stdout.write(`\n[tool call] ${event.item.name} ${JSON.stringify(event.item.arguments)}\n\n`);
+        }
+        if (event.type === "raw_model_stream_event") {
+            process.stdout.write(event.data.delta ?? "");
+        }
+    }
+    process.stdout.write(`\n\nCompleted. Last agent: ${stream.lastAgent.name}. History items: ${stream.history.length}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});