@axiastudio/aioc 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIOC contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @axiastudio/aioc
+
+AIOC is a lightweight internal agent SDK with an IoC-oriented control plane.
+
+## Release status
+
+This package is currently in alpha and is not production-ready.
+Breaking changes may occur before a stable release.
+
+## Contact
+
+If you want to collaborate or provide feedback, write to `tiziano.lattisi@axia.studio`.
+
+## Project principles
+
+AIOC adopts the following non-negotiable principles:
+
+- **LLM outside the control plane**: critical decisions remain in deterministic components; the LLM supports but does not govern.
+- **End-to-end transparency**: each decision is traceable (inputs, context, prompt/policy version, output).
+- **Verifiable corrigibility**: prompts, policies, and materials are versioned, editable, and comparable before/after changes.
+- **Non-degeneration validation**: each correction must pass regression tests and quality checks.
+- **Bias and misalignment control**: continuous monitoring, dedicated tests, and clear mitigation/escalation mechanisms.
+- **Privacy by design and data minimization**: collect and process only what is strictly necessary, protect sensitive data by default (redaction, encryption, retention limits), and provide auditable controls for access and deletion.
+
+Governance implementation reference:
+
+- `docs/RFC-0001-governance-first-runtime.md`
+- `docs/RFC-0002-policy-gates-for-tools-and-handoffs.md`
+- `docs/RFC-0003-run-record-audit-trail-and-persistence.md`
+
+## Goals of this first scaffold
+
+- Keep a familiar API.
+- Isolate provider/runtime concerns from application agent logic.
+- Enable provider wrappers (including Mistral) behind a stable SDK surface.
+
+## Exposed primitives (v0 scaffold)
+
+- `Agent`, `RunContext`
+- `Tool`, `tool(...)`
+- agent handoffs via `Agent({ handoffs: [...] })`
+- `run(...)` with streaming support
+- run logger hook via `run(..., { logger })`
+- deterministic policy gates via `run(..., { policies })` (tool execution and handoff transitions are default-deny without explicit allow policy)
+- policy helpers `allow(...)` and `deny(...)` for deterministic policy results (including optional `publicReason` and `denyMode`)
+- tool/handoff call outputs are normalized in an envelope: `{ status, code, publicReason, data }`
+- provider setup helpers `setupMistral(...)`, `setupOpenAI(...)`, `setupProvider(...)`
+- stdout logger helper `createStdoutLogger(...)` (opt-in)
+- run record hook via `run(..., { record })` for external persistence/audit adapters
+- message helpers `user(...)`, `assistant(...)`, `system(...)`
+- `setDefaultProvider(...)`
+- error classes including `OutputGuardrailTripwireTriggered`
+- `OpenAIProvider`, `MistralProvider`
+
+Provider setup notes:
+
+- `setupMistral()` reads `MISTRAL_API_KEY` from env if no `apiKey` is passed.
+- `setupOpenAI()` reads `OPENAI_API_KEY` from env if no `apiKey` is passed.
+- `setupProvider("mistral" | "openai", ...)` provides a single entrypoint.
+- `run(...)` defaults to non-stream mode (`stream: false`).
+
+Policy deny notes:
+
+- Default deny behavior raises typed runtime errors (`ToolCallPolicyDeniedError` / `HandoffPolicyDeniedError`).
+- Policies can choose `denyMode: "tool_result"` to return a denied tool result to the model without throwing.
+
+## Test Commands
+
+- `npm run test:unit`
+- `npm run test:integration`
+- `npm run test:regression`
+- `npm run test:ci`
+
+## License
+
+- Project license: `MIT` (`LICENSE`)
+- Third-party notices: `THIRD_PARTY_NOTICES.md`

package/dist/agent.d.ts

@@ -0,0 +1,29 @@
+import { RunContext } from "./run-context";
+import type { OutputGuardrail } from "./guardrails";
+import type { Tool } from "./tool";
+import type { ModelSettings } from "./types";
+export type AgentInstructions<TContext = unknown> = string | ((runContext: RunContext<TContext>) => string | Promise<string>);
+export interface AgentConfiguration<TContext = unknown> {
+    name: string;
+    handoffDescription?: string;
+    instructions?: AgentInstructions<TContext>;
+    model?: string;
+    modelSettings?: ModelSettings;
+    tools?: Tool<TContext>[];
+    handoffs?: Agent<TContext>[];
+    outputGuardrails?: OutputGuardrail<TContext>[];
+}
+export declare class Agent<TContext = unknown> {
+    name: string;
+    handoffDescription: string;
+    instructions?: AgentInstructions<TContext>;
+    model?: string;
+    modelSettings?: ModelSettings;
+    tools: Tool<TContext>[];
+    handoffs: Agent<TContext>[];
+    outputGuardrails: OutputGuardrail<TContext>[];
+    constructor(config: AgentConfiguration<TContext>);
+    static create<TContext = unknown>(config: AgentConfiguration<TContext>): Agent<TContext>;
+    resolveInstructions(runContext: RunContext<TContext>): Promise<string | undefined>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,OAAO,IAC5C,MAAM,GACN,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAkB,CAAC,QAAQ,GAAG,OAAO;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC7B,gBAAgB,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;CAChD;AAED,qBAAa,KAAK,CAAC,QAAQ,GAAG,OAAO;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC5B,gBAAgB,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAElC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC;IAWhD,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,OAAO,EAC9B,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GACnC,KAAK,CAAC,QAAQ,CAAC;IAIZ,mBAAmB,CACvB,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAS/B"}

package/dist/agent.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+class Agent {
+    name;
+    handoffDescription;
+    instructions;
+    model;
+    modelSettings;
+    tools;
+    handoffs;
+    outputGuardrails;
+    constructor(config) {
+        this.name = config.name;
+        this.handoffDescription = config.handoffDescription ?? "";
+        this.instructions = config.instructions;
+        this.model = config.model;
+        this.modelSettings = config.modelSettings;
+        this.tools = config.tools ?? [];
+        this.handoffs = config.handoffs ?? [];
+        this.outputGuardrails = config.outputGuardrails ?? [];
+    }
+    static create(config) {
+        return new Agent(config);
+    }
+    async resolveInstructions(runContext) {
+        if (typeof this.instructions === "undefined") {
+            return undefined;
+        }
+        if (typeof this.instructions === "string") {
+            return this.instructions;
+        }
+        return this.instructions(runContext);
+    }
+}
+exports.Agent = Agent;

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+import { ModelProvider } from "./providers/base";
+export declare function setDefaultProvider(provider: ModelProvider): void;
+export declare function clearDefaultProvider(): void;
+export declare function getDefaultProvider(): ModelProvider;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIjD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAEhE;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAgB,kBAAkB,IAAI,aAAa,CAOlD"}

package/dist/config.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDefaultProvider = setDefaultProvider;
+exports.clearDefaultProvider = clearDefaultProvider;
+exports.getDefaultProvider = getDefaultProvider;
+let defaultProvider = null;
+function setDefaultProvider(provider) {
+    defaultProvider = provider;
+}
+function clearDefaultProvider() {
+    defaultProvider = null;
+}
+function getDefaultProvider() {
+    if (!defaultProvider) {
+        throw new Error("No default provider configured. Call setDefaultProvider().");
+    }
+    return defaultProvider;
+}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+import type { GuardrailFunctionOutput } from "./guardrails";
+import type { PolicyResult } from "./policy";
+export declare class AIOCError extends Error {
+    constructor(message: string);
+}
+export declare class MaxTurnsExceededError extends AIOCError {
+    constructor(maxTurns: number);
+}
+export interface OutputGuardrailTripwireResult {
+    guardrail: string;
+    output: GuardrailFunctionOutput;
+    outputText: string;
+}
+export declare class OutputGuardrailTripwireTriggered extends AIOCError {
+    result: OutputGuardrailTripwireResult;
+    constructor(result: OutputGuardrailTripwireResult);
+}
+export declare class ToolCallError extends AIOCError {
+}
+export interface ToolCallPolicyDeniedResult {
+    toolName: string;
+    policyResult: PolicyResult;
+}
+export declare class ToolCallPolicyDeniedError extends ToolCallError {
+    result: ToolCallPolicyDeniedResult;
+    constructor(result: ToolCallPolicyDeniedResult);
+}
+export interface HandoffPolicyDeniedResult {
+    fromAgent: string;
+    toAgent: string;
+    policyResult: PolicyResult;
+}
+export declare class HandoffPolicyDeniedError extends AIOCError {
+    result: HandoffPolicyDeniedResult;
+    constructor(result: HandoffPolicyDeniedResult);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,QAAQ,EAAE,MAAM;CAG7B;AAED,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,uBAAuB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,gCAAiC,SAAQ,SAAS;IAC7D,MAAM,EAAE,6BAA6B,CAAC;gBAE1B,MAAM,EAAE,6BAA6B;CAOlD;AAED,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,qBAAa,yBAA0B,SAAQ,aAAa;IAC1D,MAAM,EAAE,0BAA0B,CAAC;gBAEvB,MAAM,EAAE,0BAA0B;CAM/C;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,qBAAa,wBAAyB,SAAQ,SAAS;IACrD,MAAM,EAAE,yBAAyB,CAAC;gBAEtB,MAAM,EAAE,yBAAyB;CAM9C"}

package/dist/errors.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandoffPolicyDeniedError = exports.ToolCallPolicyDeniedError = exports.ToolCallError = exports.OutputGuardrailTripwireTriggered = exports.MaxTurnsExceededError = exports.AIOCError = void 0;
+class AIOCError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.AIOCError = AIOCError;
+class MaxTurnsExceededError extends AIOCError {
+    constructor(maxTurns) {
+        super(`Max turns exceeded: ${maxTurns}`);
+    }
+}
+exports.MaxTurnsExceededError = MaxTurnsExceededError;
+class OutputGuardrailTripwireTriggered extends AIOCError {
+    result;
+    constructor(result) {
+        const reason = result.output.reason
+            ? ` Reason: ${result.output.reason}`
+            : "";
+        super(`Output guardrail "${result.guardrail}" triggered.${reason}`);
+        this.result = result;
+    }
+}
+exports.OutputGuardrailTripwireTriggered = OutputGuardrailTripwireTriggered;
+class ToolCallError extends AIOCError {
+}
+exports.ToolCallError = ToolCallError;
+class ToolCallPolicyDeniedError extends ToolCallError {
+    result;
+    constructor(result) {
+        super(`Tool "${result.toolName}" denied by policy: ${result.policyResult.reason}`);
+        this.result = result;
+    }
+}
+exports.ToolCallPolicyDeniedError = ToolCallPolicyDeniedError;
+class HandoffPolicyDeniedError extends AIOCError {
+    result;
+    constructor(result) {
+        super(`Handoff "${result.fromAgent}" -> "${result.toAgent}" denied by policy: ${result.policyResult.reason}`);
+        this.result = result;
+    }
+}
+exports.HandoffPolicyDeniedError = HandoffPolicyDeniedError;

package/dist/examples/basic/hello-world.d.ts

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

package/dist/examples/basic/hello-world.d.ts.map

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

package/dist/examples/basic/hello-world.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const index_1 = require("../../index");
+async function main() {
+    // Minimal setup: configure default provider from MISTRAL_API_KEY.
+    (0, index_1.setupMistral)();
+    const agent = new index_1.Agent({
+        name: "Hello run agent",
+        model: "mistral-small-latest",
+        instructions: "You only respond in haikus.",
+    });
+    // Default behavior: non-stream run (stream defaults to false).
+    const result = await (0, index_1.run)(agent, "Tell me about recursion in programming. Quickly responding with a single answer is fine.");
+    process.stdout.write(`${result.finalOutput}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});

package/dist/examples/basic/run-record-sink.d.ts

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

package/dist/examples/basic/run-record-sink.d.ts.map

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

package/dist/examples/basic/run-record-sink.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const zod_1 = require("zod");
+const index_1 = require("../../index");
+function findLastToolResultEnvelope(record) {
+    const reversedItems = [...record.items].reverse();
+    const outputItem = reversedItems.find((item) => item.type === "tool_call_output_item");
+    if (!outputItem || outputItem.type !== "tool_call_output_item") {
+        return undefined;
+    }
+    return outputItem?.output;
+}
+async function runScenario(label, agent, actor, toolPolicy, sink) {
+    process.stdout.write(`\n=== Scenario: ${label} (groups: ${actor.groups.join(", ")}) ===\n`);
+    const result = await (0, index_1.run)(agent, "Summarize report Q1-2026.", {
+        context: { actor },
+        policies: { toolPolicy },
+        maxTurns: 6,
+        record: {
+            metadata: { scenario: label },
+            contextRedactor: (context) => ({
+                contextSnapshot: {
+                    actor: {
+                        ...context.actor,
+                        email: "[redacted-email]",
+                    },
+                },
+                contextRedacted: true,
+            }),
+            sink,
+        },
+    });
+    process.stdout.write(`assistant: ${result.finalOutput}\n`);
+}
+async function main() {
+    // Configure default provider from MISTRAL_API_KEY.
+    (0, index_1.setupMistral)();
+    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 }) => ({
+            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],
+    });
+    const toolPolicy = ({ runContext }) => {
+        if (!runContext.context.actor.groups.includes("finance")) {
+            return (0, index_1.deny)("deny_missing_finance_group", {
+                denyMode: "tool_result",
+                publicReason: "You are not authorized to access finance reports.",
+                policyVersion: "finance-policy.v1",
+            });
+        }
+        return (0, index_1.allow)("allow_finance_group_access", {
+            policyVersion: "finance-policy.v1",
+        });
+    };
+    const records = [];
+    const sink = {
+        write: (record) => {
+            records.push(record);
+            process.stdout.write(`[sink] runId=${record.runId} status=${record.status} decisions=${record.policyDecisions.length}\n`);
+        },
+    };
+    await runScenario("actor in finance", agent, {
+        userId: "u-finance",
+        groups: ["finance"],
+        email: "alice.finance@example.com",
+    }, toolPolicy, sink);
+    await runScenario("actor in sales", agent, {
+        userId: "u-sales",
+        groups: ["sales"],
+        email: "bob.sales@example.com",
+    }, toolPolicy, sink);
+    process.stdout.write(`\n=== Persisted records (${records.length}) ===\n`);
+    for (const record of records) {
+        const lastDecision = record.policyDecisions[record.policyDecisions.length - 1];
+        process.stdout.write([
+            `runId: ${record.runId}`,
+            `scenario: ${String(record.metadata?.scenario ?? "")}`,
+            `contextRedacted: ${String(record.contextRedacted ?? false)}`,
+            `policyDecision: ${lastDecision?.decision ?? "n/a"} (${lastDecision?.reason ?? "n/a"})`,
+            `toolResultEnvelope: ${JSON.stringify(findLastToolResultEnvelope(record))}`,
+        ].join("\n") + "\n\n");
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});

package/dist/examples/basic/tools.d.ts

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

package/dist/examples/basic/tools.d.ts.map

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

package/dist/examples/basic/tools.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const zod_1 = require("zod");
+const index_1 = require("../../index");
+async function runScenario(label, agent, toolPolicy, logger, actor) {
+    process.stdout.write(`\n=== Scenario: ${label} (groups: ${actor.groups.join(", ")}) ===\n`);
+    const stream = await (0, index_1.run)(agent, "Give me a concise summary for report Q1-2026.", {
+        stream: true,
+        context: { actor },
+        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`);
+        }
+        if (event.type === "run_item_stream_event" &&
+            event.item.type === "tool_call_output_item") {
+            process.stdout.write(`[tool result] ${JSON.stringify(event.item.output)}\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`);
+}
+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", {
+                denyMode: "tool_result",
+                publicReason: "You are not authorized to access finance reports.",
+            });
+        }
+        return (0, index_1.allow)("allow_finance_group_access");
+    };
+    // Optional logger: prints only the policy decision event to keep output readable.
+    const logger = (0, index_1.createStdoutLogger)({
+        pretty: true,
+        events: ["tool_policy_evaluated"],
+    });
+    await runScenario("actor in finance", agent, toolPolicy, logger, {
+        userId: "u-finance",
+        groups: ["finance"],
+    });
+    await runScenario("actor in sales", agent, toolPolicy, logger, {
+        userId: "u-sales",
+        groups: ["sales"],
+    });
+}
+main().catch((error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exit(1);
+});

package/dist/examples/guardrail-smoke.d.ts

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

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

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

package/dist/examples/guardrail-smoke.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 });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const index_1 = require("../index");
+class ScriptedProvider {
+    events;
+    constructor(events) {
+        this.events = events;
+    }
+    async *stream(_request) {
+        void _request;
+        for (const event of this.events) {
+            yield event;
+        }
+    }
+}
+const outputGuardrail = (0, index_1.defineOutputGuardrail)({
+    name: "block_unsafe_output",
+    execute: ({ outputText }) => ({
+        tripwireTriggered: outputText.toLowerCase().includes("unsafe"),
+        reason: "Output contains forbidden token 'unsafe'.",
+        metadata: {
+            matched: "unsafe",
+        },
+    }),
+});
+function getRawOutput(events) {
+    return events
+        .filter((event) => event.type === "raw_model_stream_event")
+        .map((event) => event.data.delta ?? "")
+        .join("");
+}
+function getMessageOutput(events) {
+    const itemEvent = events.find((event) => event.type === "run_item_stream_event" &&
+        event.item.type === "message_output_item");
+    if (!itemEvent) {
+        return null;
+    }
+    return itemEvent.item.type === "message_output_item"
+        ? itemEvent.item.content
+        : null;
+}
+function isAssistantMessage(item) {
+    return item.type === "message" && item.role === "assistant";
+}
+async function runPassingCase() {
+    (0, index_1.setDefaultProvider)(new ScriptedProvider([
+        { type: "delta", delta: "Safe " },
+        { type: "delta", delta: "answer." },
+        { type: "completed", message: "Safe answer." },
+    ]));
+    const agent = new index_1.Agent({
+        name: "Guardrail pass",
+        model: "fake-model",
+        outputGuardrails: [outputGuardrail],
+    });
+    const streamed = await (0, index_1.run)(agent, "hello", { stream: true });
+    const events = [];
+    for await (const event of streamed.toStream()) {
+        events.push(event);
+    }
+    strict_1.default.equal(getRawOutput(events), "Safe answer.");
+    strict_1.default.equal(getMessageOutput(events), "Safe answer.");
+    const assistantMessages = streamed.history.filter(isAssistantMessage);
+    strict_1.default.equal(assistantMessages.length, 1);
+    strict_1.default.equal(assistantMessages[0]?.content, "Safe answer.");
+}
+async function runTripwireCase() {
+    (0, index_1.setDefaultProvider)(new ScriptedProvider([
+        { type: "delta", delta: "unsafe answer" },
+        { type: "completed", message: "unsafe answer" },
+    ]));
+    const agent = new index_1.Agent({
+        name: "Guardrail fail",
+        model: "fake-model",
+        outputGuardrails: [outputGuardrail],
+    });
+    const streamed = await (0, index_1.run)(agent, "hello", { stream: true });
+    const events = [];
+    let capturedError = null;
+    try {
+        for await (const event of streamed.toStream()) {
+            events.push(event);
+        }
+    }
+    catch (error) {
+        capturedError = error;
+    }
+    strict_1.default.ok(capturedError instanceof index_1.OutputGuardrailTripwireTriggered);
+    strict_1.default.equal(capturedError.result.guardrail, "block_unsafe_output");
+    strict_1.default.equal(capturedError.result.output.tripwireTriggered, true);
+    strict_1.default.equal(capturedError.result.outputText, "unsafe answer");
+    strict_1.default.equal(getRawOutput(events), "");
+    strict_1.default.equal(getMessageOutput(events), null);
+    const assistantMessages = streamed.history.filter(isAssistantMessage);
+    strict_1.default.equal(assistantMessages.length, 0);
+}
+async function main() {
+    await runPassingCase();
+    await runTripwireCase();
+    process.stdout.write("Guardrail 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/hello-run.d.ts

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

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

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