@axiastudio/aioc 0.1.2 → 0.2.0-next.2

package/README.md

@@ -8,15 +8,12 @@ Project home and documentation: [https://axiastudio.github.io/aioc](https://axia
 
 ## Release Status
 
-Current stable release: `0.1.2`.
-The stable `0.1.x` line started with `0.1.0`.
+This package is stable as of `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` 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.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.
 
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
@@ -97,7 +94,6 @@ 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 })`
@@ -266,10 +262,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` (`Accepted`)
+- `docs/RFC-0006-approval-evidence-helpers.md` (`Draft`)
 - `docs/RFC-0007-thread-state-utilities.md` (`Accepted`)
 - `docs/RFC-0008-run-stream-consumer-utilities.md` (`Accepted`)
-- `docs/RFC-0010-policy-composition-helpers.md` (`Draft`)
+- `docs/RFC-0009-governance-events-and-exporters.md` (`Experimental`)
+- `docs/RFC-0011-agent-harness-descriptor.md` (`Experimental`)
 - `docs/PRIVACY-BASELINE.md`
 
 ## Historical Snapshots

package/dist/harness-descriptor.d.ts

@@ -0,0 +1,78 @@
+import { Agent } from "./agent";
+import type { Tool } from "./tool";
+import type { NonStreamRunOptions } from "./types";
+export interface HarnessDescriptorMetadata {
+    name?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export interface HarnessRuntimeDescriptor {
+    entry_agent: string;
+    max_turns?: number;
+}
+export interface HarnessToolDescriptor {
+    target: string;
+}
+export interface HarnessAgentDescriptor {
+    name?: string;
+    handoffDescription?: string;
+    instructions?: string;
+    model?: string;
+    modelSettings?: Record<string, unknown>;
+    tools?: string[];
+    handoffs?: string[];
+}
+export interface HarnessContextReferenceDescriptor {
+    type?: string;
+    optional?: boolean;
+    [key: string]: unknown;
+}
+export type HarnessContextReferenceEntry = boolean | HarnessContextReferenceDescriptor;
+export interface HarnessContextFieldDescriptor {
+    type: string;
+    default?: unknown;
+    optional?: boolean;
+    mutable?: boolean;
+    redact?: boolean;
+    [key: string]: unknown;
+}
+export interface HarnessContextDescriptor {
+    fields?: Record<string, HarnessContextFieldDescriptor>;
+    references?: Record<string, HarnessContextReferenceEntry>;
+}
+export interface AgentHarnessDescriptor {
+    descriptor_version?: string;
+    metadata?: HarnessDescriptorMetadata;
+    runtime: HarnessRuntimeDescriptor;
+    context?: HarnessContextDescriptor;
+    tools?: Record<string, HarnessToolDescriptor>;
+    agent_defaults?: Pick<HarnessAgentDescriptor, "model" | "modelSettings" | "instructions">;
+    agents: Record<string, HarnessAgentDescriptor>;
+}
+export interface AgentHarnessRegistry<TContext = unknown> {
+    tools?: Record<string, Tool<TContext>>;
+    registryVersion?: string;
+}
+export interface CreateHarnessContextInput {
+    message?: string;
+    now?: string | Date;
+    overrides?: unknown;
+}
+export interface AgentHarnessMetadata {
+    name?: string;
+    version?: string;
+    descriptorVersion?: string;
+    descriptorHash: string;
+    registryVersion?: string;
+}
+export interface AgentHarness<TContext = unknown> {
+    entryAgent: Agent<TContext>;
+    agents: Map<string, Agent<TContext>>;
+    descriptorHash: string;
+    metadata: AgentHarnessMetadata;
+    runOptions: Omit<NonStreamRunOptions<TContext>, "stream">;
+    createContext(input?: CreateHarnessContextInput): TContext;
+}
+export declare function hashAgentHarnessDescriptor(descriptor: AgentHarnessDescriptor): string;
+export declare function buildAgentHarness<TContext = unknown>(descriptor: AgentHarnessDescriptor, registry?: AgentHarnessRegistry<TContext>): AgentHarness<TContext>;
+//# sourceMappingURL=harness-descriptor.d.ts.map

package/dist/harness-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-descriptor.d.ts","sourceRoot":"","sources":["../src/harness-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/harness-descriptor.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashAgentHarnessDescriptor = hashAgentHarnessDescriptor;
+exports.buildAgentHarness = buildAgentHarness;
+const agent_1 = require("./agent");
+const canonical_json_1 = require("./canonical-json");
+const CONTEXT_PROMPT_PLACEHOLDER = /\{\{\s*context\.([^}]+?)\s*\}\}/g;
+function cloneJsonValue(value) {
+    if (typeof value === "undefined") {
+        return undefined;
+    }
+    return JSON.parse(JSON.stringify(value));
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertPlainObject(value, label) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+}
+function assertOptionalPlainObject(value, label) {
+    if (typeof value === "undefined") {
+        return;
+    }
+    assertPlainObject(value, label);
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+}
+function validateDescriptorShape(descriptor) {
+    assertPlainObject(descriptor, "Harness descriptor");
+    assertPlainObject(descriptor.runtime, "Harness descriptor runtime");
+    assertNonEmptyString(descriptor.runtime.entry_agent, "Harness descriptor runtime.entry_agent");
+    assertPlainObject(descriptor.agents, "Harness descriptor agents");
+    if (Object.keys(descriptor.agents).length === 0) {
+        throw new Error("Harness descriptor agents must not be empty.");
+    }
+    assertOptionalPlainObject(descriptor.metadata, "Harness descriptor metadata");
+    assertOptionalPlainObject(descriptor.tools, "Harness descriptor tools");
+    assertOptionalPlainObject(descriptor.agent_defaults, "Harness descriptor agent_defaults");
+    assertOptionalPlainObject(descriptor.context, "Harness descriptor context");
+    assertOptionalPlainObject(descriptor.context?.fields, "Harness descriptor context.fields");
+    assertOptionalPlainObject(descriptor.context?.references, "Harness descriptor context.references");
+    for (const [toolId, toolDescriptor] of Object.entries(descriptor.tools ?? {})) {
+        assertPlainObject(toolDescriptor, `Harness descriptor tool "${toolId}"`);
+        assertNonEmptyString(toolDescriptor.target, `Harness descriptor tool "${toolId}".target`);
+    }
+}
+function normalizePromptPath(path, label) {
+    const segments = path
+        .split(".")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        throw new Error(`${label} cannot be empty.`);
+    }
+    for (const segment of segments) {
+        if (!/^[A-Za-z0-9_-]+$/.test(segment)) {
+            throw new Error(`${label} contains invalid segment "${segment}".`);
+        }
+    }
+    return segments.join(".");
+}
+function createPromptReferenceRules(descriptor) {
+    const rules = new Map();
+    for (const [path, reference] of Object.entries(descriptor.context?.references ?? {})) {
+        if (reference === false) {
+            continue;
+        }
+        const normalizedPath = normalizePromptPath(path, "Context reference path");
+        if (reference === true) {
+            rules.set(normalizedPath, { optional: false });
+            continue;
+        }
+        if (!isPlainObject(reference)) {
+            throw new Error(`Context reference "${path}" must be true, false, or an object.`);
+        }
+        rules.set(normalizedPath, { optional: Boolean(reference.optional) });
+    }
+    return rules;
+}
+function collectContextPromptPaths(template) {
+    const paths = new Set();
+    for (const match of template.matchAll(CONTEXT_PROMPT_PLACEHOLDER)) {
+        const rawPath = match[1];
+        if (!rawPath) {
+            continue;
+        }
+        paths.add(normalizePromptPath(rawPath, `Context prompt placeholder "${match[0]}"`));
+    }
+    return [...paths];
+}
+function readPromptPath(context, path) {
+    let cursor = context;
+    for (const segment of normalizePromptPath(path, "Context prompt path").split(".")) {
+        if (typeof cursor !== "object" || cursor === null || !(segment in cursor)) {
+            return { exists: false, value: undefined };
+        }
+        cursor = cursor[segment];
+    }
+    return { exists: true, value: cursor };
+}
+function stringifyPromptValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return String(value);
+    }
+    if (typeof value === "undefined") {
+        return "";
+    }
+    const json = JSON.stringify(value);
+    return typeof json === "undefined" ? String(value) : json;
+}
+function renderInstructionTemplate(template, context, promptAccessRules) {
+    return template.replace(CONTEXT_PROMPT_PLACEHOLDER, (placeholder, rawPath) => {
+        const path = normalizePromptPath(rawPath, `Context prompt placeholder "${placeholder}"`);
+        const rule = promptAccessRules.get(path);
+        if (!rule) {
+            throw new Error(`Harness descriptor instruction references undeclared context path "${path}".`);
+        }
+        const resolved = readPromptPath(context, path);
+        if (!resolved.exists || typeof resolved.value === "undefined") {
+            if (rule.optional) {
+                return "";
+            }
+            throw new Error(`Harness descriptor instruction could not resolve required context path "${path}".`);
+        }
+        return stringifyPromptValue(resolved.value);
+    });
+}
+function compileAgentInstructions(agentId, instructions, promptAccessRules) {
+    if (typeof instructions === "undefined") {
+        return undefined;
+    }
+    const promptPaths = collectContextPromptPaths(instructions);
+    if (promptPaths.length === 0) {
+        return instructions;
+    }
+    for (const path of promptPaths) {
+        if (!promptAccessRules.has(path)) {
+            throw new Error(`Agent "${agentId}" instruction references undeclared context path "${path}".`);
+        }
+    }
+    return (runContext) => renderInstructionTemplate(instructions, runContext.context, promptAccessRules);
+}
+function setPath(target, path, value) {
+    const segments = path.split(".").filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        throw new Error("Context field path cannot be empty.");
+    }
+    let cursor = target;
+    for (const segment of segments.slice(0, -1)) {
+        const existing = cursor[segment];
+        if (typeof existing !== "object" || existing === null) {
+            const next = {};
+            cursor[segment] = next;
+            cursor = next;
+            continue;
+        }
+        cursor = existing;
+    }
+    cursor[segments[segments.length - 1]] = value;
+}
+function mergeObject(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        const current = target[key];
+        if (current &&
+            typeof current === "object" &&
+            !Array.isArray(current) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            mergeObject(current, value);
+            continue;
+        }
+        target[key] = cloneJsonValue(value);
+    }
+}
+function resolveDefaultValue(value, input) {
+    if (value === "{{input.message}}") {
+        return input.message ?? "";
+    }
+    if (value === "{{runtime.now_iso}}") {
+        const now = input.now ?? new Date();
+        return now instanceof Date ? now.toISOString() : now;
+    }
+    return cloneJsonValue(value);
+}
+function createContextFromDescriptor(descriptor, input = {}) {
+    const context = {};
+    for (const [path, field] of Object.entries(descriptor.context?.fields ?? {})) {
+        if (!("default" in field)) {
+            continue;
+        }
+        setPath(context, path, resolveDefaultValue(field.default, input));
+    }
+    if (input.overrides &&
+        typeof input.overrides === "object" &&
+        !Array.isArray(input.overrides)) {
+        mergeObject(context, input.overrides);
+    }
+    return context;
+}
+function resolveTool(toolId, descriptor, registry) {
+    const toolDescriptor = descriptor.tools?.[toolId];
+    if (!toolDescriptor) {
+        throw new Error(`Harness descriptor references unknown tool "${toolId}".`);
+    }
+    const toolDefinition = registry.tools?.[toolDescriptor.target];
+    if (!toolDefinition) {
+        throw new Error(`Harness registry is missing target "${toolDescriptor.target}" for tool "${toolId}".`);
+    }
+    return toolDefinition;
+}
+function hashAgentHarnessDescriptor(descriptor) {
+    return `sha256:${(0, canonical_json_1.hashCanonicalJsonValue)(descriptor)}`;
+}
+function buildAgentHarness(descriptor, registry = {}) {
+    validateDescriptorShape(descriptor);
+    const descriptorHash = hashAgentHarnessDescriptor(descriptor);
+    const agents = new Map();
+    const promptAccessRules = createPromptReferenceRules(descriptor);
+    for (const [agentId, agentDescriptor] of Object.entries(descriptor.agents)) {
+        const instructions = agentDescriptor.instructions ?? descriptor.agent_defaults?.instructions;
+        const agent = new agent_1.Agent({
+            name: agentDescriptor.name ?? agentId,
+            handoffDescription: agentDescriptor.handoffDescription,
+            instructions: compileAgentInstructions(agentId, instructions, promptAccessRules),
+            model: agentDescriptor.model ?? descriptor.agent_defaults?.model,
+            modelSettings: agentDescriptor.modelSettings ??
+                descriptor.agent_defaults?.modelSettings,
+            tools: (agentDescriptor.tools ?? []).map((toolId) => resolveTool(toolId, descriptor, registry)),
+            handoffs: [],
+        });
+        agents.set(agentId, agent);
+    }
+    for (const [agentId, agentDescriptor] of Object.entries(descriptor.agents)) {
+        const agent = agents.get(agentId);
+        if (!agent) {
+            continue;
+        }
+        agent.handoffs = (agentDescriptor.handoffs ?? []).map((handoffId) => {
+            const handoffAgent = agents.get(handoffId);
+            if (!handoffAgent) {
+                throw new Error(`Harness descriptor references unknown handoff agent "${handoffId}" from "${agentId}".`);
+            }
+            return handoffAgent;
+        });
+    }
+    const entryAgent = agents.get(descriptor.runtime.entry_agent);
+    if (!entryAgent) {
+        throw new Error(`Harness descriptor entry_agent "${descriptor.runtime.entry_agent}" does not exist.`);
+    }
+    return {
+        entryAgent,
+        agents,
+        descriptorHash,
+        metadata: {
+            name: descriptor.metadata?.name,
+            version: descriptor.metadata?.version,
+            descriptorVersion: descriptor.descriptor_version,
+            descriptorHash,
+            registryVersion: registry.registryVersion,
+        },
+        runOptions: {
+            maxTurns: descriptor.runtime.max_turns,
+        },
+        createContext: (input) => createContextFromDescriptor(descriptor, input),
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export * from "./agent";
-export * from "./approval-helpers";
 export * from "./config";
 export * from "./errors";
 export * from "./guardrails";
+export * from "./harness-descriptor";
 export * from "./json";
 export * from "./logger";
 export * from "./messages";

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,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,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,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,10 +15,10 @@ 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);
+__exportStar(require("./harness-descriptor"), exports);
 __exportStar(require("./json"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./messages"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiastudio/aioc",
-  "version": "0.1.2",
+  "version": "0.2.0-next.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -22,6 +22,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: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",
     "example:rru:02-compare": "tsx src/examples/run-record-utils-minimal/02-compare-run-records.ts",
@@ -69,11 +70,13 @@
   },
   "dependencies": {
     "dotenv": "^17.2.3",
+    "js-yaml": "^4.1.1",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.15.3",
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",

package/dist/approval-helpers.d.ts

@@ -1,24 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,94 +0,0 @@
-"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));
-}