@axiastudio/aioc 0.2.0 → 0.2.1

package/README.md

@@ -8,14 +8,18 @@ Project home and documentation: [https://axiastudio.github.io/aioc](https://axia
 
 ## Release Status
 
-This package is stable as of `0.1.0`.
+Current stable release: `0.2.1`.
+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.
 
 ### Stable Scope
 
-AIOC `0.1.0` stabilizes the core runtime surface, public documentation aligned to the exported contract, `RunRecord` and replay/compare workflows, and the governance-first runtime model validated in real applications beyond toy examples.
+AIOC `0.1.0` stabilized the core runtime surface, public documentation aligned to the exported contract, `RunRecord` and replay/compare workflows, and the governance-first runtime model validated in real applications beyond toy examples.
+AIOC `0.1.1` adds thread-history utilities, the run-output stream adapter, and provider-specific instruction-role documentation without changing the stable governance model.
+AIOC `0.1.2` adds approval evidence helpers for application-owned approval workflows.
 
 AIOC `0.2.0` adds implemented runtime utilities and an experimental Agent Harness Descriptor surface. The core runtime remains compatibility-managed; descriptor shape and loader helpers may still evolve across `0.x` minor releases 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.
 
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
@@ -96,6 +100,7 @@ console.log(result.finalOutput);
 - handoffs via `Agent({ handoffs: [...] })`
 - `run(...)` with streaming support (`stream` defaults to `false`)
 - policy helpers `allow(...)` / `deny(...)` / `requireApproval(...)`
+- approval evidence helpers `createApprovalRequestSeed(...)`, `toApprovedProposalHashes(...)`, `toActiveApprovalGrantMap(...)`
 - provider setup helpers `setupMistral(...)`, `setupOpenAI(...)`, `setupProvider(...)`
 - run logger hook `run(..., { logger })`
 - run record hook `run(..., { record })`
@@ -104,7 +109,7 @@ console.log(result.finalOutput);
 - thread history utilities `toThreadHistory(...)`, `appendUserMessage(...)`, `replaceThreadHistory(...)`, `applyRunResultHistory(...)`
 - JSON helper `toJsonValue(...)`
 
-## Experimental 0.2.0 Surface
+## Experimental 0.2.x Surface
 
 - `buildAgentHarness(...)`
 - `hashAgentHarnessDescriptor(...)`
@@ -112,7 +117,7 @@ console.log(result.finalOutput);
 - `loadAgentHarnessDescriptorFromFile(...)`
 - `AgentHarnessDescriptor` and related descriptor types
 
-The Agent Harness Descriptor is included in `0.2.0` as an experimental `aioc.agent_graph.v0` descriptor surface. Use it for controlled configuration, examples, and evaluation harnesses; keep executable tools, policies, providers, persistence, approvals, and deployment configuration in application code.
+The Agent Harness Descriptor is included in the `0.2.x` line as an experimental `aioc.agent_graph.v0` descriptor surface. Use it for controlled configuration, examples, and evaluation harnesses; keep executable tools, policies, providers, persistence, approvals, and deployment configuration in application code.
 
 ## Policy Gate (Minimal)
 
@@ -274,10 +279,11 @@ AIOC adopts the following non-negotiable principles:
 - `docs/RFC-0003-run-record-audit-trail-and-persistence.md` (`Accepted`)
 - `docs/RFC-0004-policy-outcomes-and-approval-model.md` (`Accepted`)
 - `docs/RFC-0005-suspended-proposals-and-approval-lifecycle.md` (`Accepted`)
-- `docs/RFC-0006-approval-evidence-helpers.md` (`Draft`)
+- `docs/RFC-0006-approval-evidence-helpers.md` (`Accepted`)
 - `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-0011-agent-harness-descriptor.md` (`Experimental`)
 - `docs/PRIVACY-BASELINE.md`
 

package/dist/approval-helpers.d.ts

@@ -0,0 +1,24 @@
+import type { SuspendedProposal } from "./run-record";
+export interface ApprovalGrant {
+    proposalHash: string;
+    approvedAt: string;
+    expiresAt?: string;
+    revokedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ApprovalRequestSeed {
+    proposalHash: string;
+    kind: "tool" | "handoff";
+    reason: string;
+    publicReason?: string;
+    policyVersion?: string;
+    expiresAt?: string;
+    resourceName: string;
+    canonicalPayloadJson: string;
+}
+export declare function createApprovalRequestSeed(proposal: SuspendedProposal): ApprovalRequestSeed;
+export declare function isApprovalGrantActive(grant: ApprovalGrant, now?: string): boolean;
+export declare function findActiveApprovalGrant(proposalHash: string, grants: readonly ApprovalGrant[], now?: string): ApprovalGrant | null;
+export declare function toActiveApprovalGrantMap(grants: readonly ApprovalGrant[], now?: string): Record<string, ApprovalGrant>;
+export declare function toApprovedProposalHashes(grants: readonly ApprovalGrant[], now?: string): string[];
+//# sourceMappingURL=approval-helpers.d.ts.map

package/dist/approval-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-helpers.d.ts","sourceRoot":"","sources":["../src/approval-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAsCD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,iBAAiB,GAC1B,mBAAmB,CAoBrB;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,EACpB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAYT;AAED,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,GAAG,CAAC,EAAE,MAAM,GACX,aAAa,GAAG,IAAI,CAgBtB;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAe/B;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,EAAE,CAEV"}

package/dist/approval-helpers.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApprovalRequestSeed = createApprovalRequestSeed;
+exports.isApprovalGrantActive = isApprovalGrantActive;
+exports.findActiveApprovalGrant = findActiveApprovalGrant;
+exports.toActiveApprovalGrantMap = toActiveApprovalGrantMap;
+exports.toApprovedProposalHashes = toApprovedProposalHashes;
+function parseTimestamp(value, label) {
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp)) {
+        throw new Error(`${label} must be a valid timestamp.`);
+    }
+    return timestamp;
+}
+function getNowTimestamp(now) {
+    return parseTimestamp(now ?? new Date().toISOString(), "now");
+}
+function isGrantNewer(candidate, current) {
+    return (parseTimestamp(candidate.approvedAt, "grant.approvedAt") >
+        parseTimestamp(current.approvedAt, "grant.approvedAt"));
+}
+function getProposalMetadata(proposal) {
+    return {
+        ...(typeof proposal.publicReason !== "undefined"
+            ? { publicReason: proposal.publicReason }
+            : {}),
+        ...(typeof proposal.policyVersion !== "undefined"
+            ? { policyVersion: proposal.policyVersion }
+            : {}),
+        ...(typeof proposal.expiresAt !== "undefined"
+            ? { expiresAt: proposal.expiresAt }
+            : {}),
+    };
+}
+function createApprovalRequestSeed(proposal) {
+    if (proposal.kind === "tool") {
+        return {
+            proposalHash: proposal.proposalHash,
+            kind: proposal.kind,
+            reason: proposal.reason,
+            ...getProposalMetadata(proposal),
+            resourceName: proposal.toolName,
+            canonicalPayloadJson: proposal.argsCanonicalJson,
+        };
+    }
+    return {
+        proposalHash: proposal.proposalHash,
+        kind: proposal.kind,
+        reason: proposal.reason,
+        ...getProposalMetadata(proposal),
+        resourceName: proposal.toAgentName,
+        canonicalPayloadJson: proposal.payloadCanonicalJson,
+    };
+}
+function isApprovalGrantActive(grant, now) {
+    if (typeof grant.revokedAt !== "undefined") {
+        return false;
+    }
+    if (typeof grant.expiresAt === "undefined") {
+        return true;
+    }
+    return (parseTimestamp(grant.expiresAt, "grant.expiresAt") >= getNowTimestamp(now));
+}
+function findActiveApprovalGrant(proposalHash, grants, now) {
+    let match = null;
+    for (const grant of grants) {
+        if (grant.proposalHash !== proposalHash) {
+            continue;
+        }
+        if (!isApprovalGrantActive(grant, now)) {
+            continue;
+        }
+        if (!match || isGrantNewer(grant, match)) {
+            match = grant;
+        }
+    }
+    return match;
+}
+function toActiveApprovalGrantMap(grants, now) {
+    const grantMap = {};
+    for (const grant of grants) {
+        if (!isApprovalGrantActive(grant, now)) {
+            continue;
+        }
+        const current = grantMap[grant.proposalHash];
+        if (!current || isGrantNewer(grant, current)) {
+            grantMap[grant.proposalHash] = grant;
+        }
+    }
+    return grantMap;
+}
+function toApprovedProposalHashes(grants, now) {
+    return Object.keys(toActiveApprovalGrantMap(grants, now));
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./agent";
+export * from "./approval-helpers";
 export * from "./config";
 export * from "./errors";
 export * from "./guardrails";

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,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,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

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./agent"), exports);
+__exportStar(require("./approval-helpers"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./guardrails"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiastudio/aioc",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [