@axiastudio/aioc 0.2.2 → 0.2.4

package/README.md

@@ -1,14 +1,29 @@
 # @axiastudio/aioc
 
-AIOC is a governance-first SDK for LLM agents: models can propose actions, while deterministic policies and runtime controls enforce decisions.
-It provides default-deny gates for tools and handoffs, end-to-end auditability (run records, prompt snapshots, request fingerprints), and a foundation for verifiable iteration on prompts and policies.
-AIOC is designed for enterprise and public-sector contexts with privacy-by-design and high-accountability (AI Act-style) governance requirements.
+AIOC is a deterministic governance kernel for LLM agents: models can propose actions, while application-owned policies and runtime controls decide what is actually allowed to happen.
+It is built around default-deny gates for tools and handoffs, portable audit artifacts (`RunRecord`, prompt snapshots, request fingerprints), and replay/compare workflows for verifiable iteration on prompts and policies.
+AIOC is designed for enterprise and public-sector contexts where governance cannot be outsourced to an observability dashboard, hosted trace store, or framework-owned approval workflow.
 
 Project home and documentation: [https://axiastudio.github.io/aioc](https://axiastudio.github.io/aioc)
 
+## Positioning
+
+AIOC does not try to be a full agent platform, hosted tracing product, evaluation suite, or human-review workflow engine.
+Those systems are useful, but they make governance-sensitive decisions about storage, retention, access, escalation, and audit semantics.
+
+AIOC keeps the enforcement boundary inside the application instead:
+
+- the model proposes; deterministic policy code authorizes or denies
+- execution-impacting capabilities are deny-by-default
+- audit evidence is emitted as portable records rather than owned by a required control plane
+- persistence, approvals, retention, access control, monitoring, and deployment remain host-application responsibilities
+
+In short: AIOC treats observability as evidence, not as governance itself.
+Its core job is to make agent execution boundaries explicit, testable, auditable, and hard to bypass.
+
 ## Release Status
 
-Current stable release: `0.2.2`.
+Current stable release: `0.2.4`.
 The stable line started with `0.1.0`.
 The core runtime surface is compatibility-managed. Breaking changes to the stable surface should ship only with explicit migration guidance and release notes.
 
@@ -21,6 +36,18 @@ AIOC `0.1.2` adds approval evidence helpers for application-owned approval workf
 AIOC `0.2.0` adds implemented runtime utilities and the Agent Harness Descriptor API. The core runtime remains compatibility-managed; descriptor shape and loader helpers are now part of the supported `0.2.x` surface and may evolve across `0.x` minor releases only with explicit migration guidance.
 AIOC `0.2.1` realigns the `0.2.x` package line with the current `main` history after `0.2.0` was published from the descriptor release branch.
 AIOC `0.2.2` completes the descriptor instruction-composition surface with reusable `instruction_parts`, ordered `instructions_sequence`, and boolean `where` gates.
+AIOC `0.2.3` adds RFC-0010 policy composition helpers for exact-name tool and handoff policy dispatch without changing runtime enforcement semantics.
+AIOC `0.2.4` adds experimental governance-event packages and an OpenTelemetry Logs exporter for reduced, operational observability events derived from `RunRecord` values.
+
+### Experimental Packages
+
+`@axiastudio/aioc-governance-events` implements the RFC-0009 governance-event
+mapper outside the core runtime package. It derives reduced, redacted,
+event-shaped records from `RunRecord` values.
+
+`@axiastudio/aioc-export-otel` maps those governance events to OpenTelemetry
+Logs. Both packages remain experimental while real exporter usage validates the
+schema and operational shape.
 
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
@@ -242,6 +269,7 @@ This repository also contains `aioc-inspect`, a private reference example UI for
 | `npm run example:approval-required` | Minimal approval-required tool + policy flow | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:approval-evidence` | Approval evidence passed through context and reevaluated by policy | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:tool-policy` | Straight tool + policy flow with allowed execution | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
+| `npm run example:policy-composition` | Exact-name tool policy dispatch with fallback deny | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:run-record` | Run-record persistence with redaction + audit | Yes (`AIOC_EXAMPLE_PROVIDER` + matching provider API key) |
 | `npm run example:rru:01-extract` | Minimal `extractToolCalls(...)` | No |
 | `npm run example:rru:02-compare` | Minimal `compareRunRecords(...)` | No |
@@ -284,7 +312,7 @@ AIOC adopts the following non-negotiable principles:
 - `docs/RFC-0007-thread-state-utilities.md` (`Accepted`)
 - `docs/RFC-0008-run-stream-consumer-utilities.md` (`Accepted`)
 - `docs/RFC-0009-governance-events-and-exporters.md` (`Experimental`)
-- `docs/RFC-0010-policy-composition-helpers.md` (`Draft`)
+- `docs/RFC-0010-policy-composition-helpers.md` (`Accepted`)
 - `docs/RFC-0011-agent-harness-descriptor.md` (`Accepted`)
 - `docs/PRIVACY-BASELINE.md`
 

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./json";
 export * from "./logger";
 export * from "./messages";
 export * from "./policy";
+export * from "./policy-composition";
 export * from "./proposal-hashing";
 export * from "./provider-setup";
 export * from "./providers/base";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -25,6 +25,7 @@ __exportStar(require("./json"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./messages"), exports);
 __exportStar(require("./policy"), exports);
+__exportStar(require("./policy-composition"), exports);
 __exportStar(require("./proposal-hashing"), exports);
 __exportStar(require("./provider-setup"), exports);
 __exportStar(require("./providers/base"), exports);

package/dist/policy-composition.d.ts

@@ -0,0 +1,6 @@
+import { type HandoffPolicy, type ToolPolicy } from "./policy";
+export type ToolPolicyMap<TContext = unknown> = Record<string, ToolPolicy<TContext>>;
+export type HandoffPolicyMap<TContext = unknown> = Record<string, HandoffPolicy<TContext>>;
+export declare function composeToolPolicies<TContext = unknown>(policies: ToolPolicyMap<TContext>): ToolPolicy<TContext>;
+export declare function composeHandoffPolicies<TContext = unknown>(policies: HandoffPolicyMap<TContext>): HandoffPolicy<TContext>;
+//# sourceMappingURL=policy-composition.d.ts.map

package/dist/policy-composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-composition.d.ts","sourceRoot":"","sources":["../src/policy-composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAErE,MAAM,MAAM,aAAa,CAAC,QAAQ,GAAG,OAAO,IAAI,MAAM,CACpD,MAAM,EACN,UAAU,CAAC,QAAQ,CAAC,CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,QAAQ,GAAG,OAAO,IAAI,MAAM,CACvD,MAAM,EACN,aAAa,CAAC,QAAQ,CAAC,CACxB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,OAAO,EACpD,QAAQ,EAAE,aAAa,CAAC,QAAQ,CAAC,GAChC,UAAU,CAAC,QAAQ,CAAC,CAUtB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,GAAG,OAAO,EACvD,QAAQ,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GACnC,aAAa,CAAC,QAAQ,CAAC,CAUzB"}

package/dist/policy-composition.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeToolPolicies = composeToolPolicies;
+exports.composeHandoffPolicies = composeHandoffPolicies;
+const policy_1 = require("./policy");
+function composeToolPolicies(policies) {
+    return (input) => {
+        const policy = policies[input.toolName] ?? policies["*"];
+        if (policy) {
+            return policy(input);
+        }
+        return (0, policy_1.deny)(`deny_unconfigured_tool_${input.toolName}`);
+    };
+}
+function composeHandoffPolicies(policies) {
+    return (input) => {
+        const policy = policies[input.toAgentName] ?? policies["*"];
+        if (policy) {
+            return policy(input);
+        }
+        return (0, policy_1.deny)(`deny_unconfigured_handoff_${input.toAgentName}`);
+    };
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@axiastudio/aioc",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "test": "npm run test:ci",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -22,6 +25,7 @@
     "example:approval-required": "tsx src/examples/basic/approval-required.ts",
     "example:approval-evidence": "tsx src/examples/basic/approval-evidence.ts",
     "example:tool-policy": "tsx src/examples/basic/tools.ts",
+    "example:policy-composition": "tsx src/examples/basic/policy-composition.ts",
     "example:harness": "tsx src/examples/harness-descriptor/customer-support.ts",
     "example:run-record": "tsx src/examples/basic/run-record-sink.ts",
     "example:rru:01-extract": "tsx src/examples/run-record-utils-minimal/01-extract-tool-calls.ts",
@@ -34,6 +38,14 @@
     "docs:dev": "npm run docs:sync && cd apps/aioc-docs && zsh -lc 'npm run dev'",
     "docs:build": "npm run docs:sync && cd apps/aioc-docs && zsh -lc 'npm run build'",
     "docs:preview": "cd apps/aioc-docs && zsh -lc 'npm run preview'",
+    "packages:build": "npm run governance-events:build && npm run build -w @axiastudio/aioc-export-otel && npm run build -w @axiastudio/aioc-inspect-ui",
+    "packages:test": "npm run governance-events:test && npm run export-otel:test",
+    "governance-events:build": "npm run build && npm run build -w @axiastudio/aioc-governance-events",
+    "governance-events:test": "npm run build && npm test -w @axiastudio/aioc-governance-events",
+    "export-otel:build": "npm run governance-events:build && npm run build -w @axiastudio/aioc-export-otel",
+    "export-otel:test": "npm run governance-events:build && npm test -w @axiastudio/aioc-export-otel",
+    "export-otel:console": "npm run governance-events:build && npm run console -w @axiastudio/aioc-export-otel",
+    "export-otel:signoz": "npm run governance-events:build && npm run signoz -w @axiastudio/aioc-export-otel",
     "test:mistral": "tsx src/examples/mistral-smoke.ts",
     "prepack": "npm run build:package"
   },