@axiastudio/aioc 0.2.0-next.2 → 0.2.1

package/README.md

@@ -8,12 +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`
@@ -94,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 })`
@@ -102,6 +109,16 @@ console.log(result.finalOutput);
 - thread history utilities `toThreadHistory(...)`, `appendUserMessage(...)`, `replaceThreadHistory(...)`, `applyRunResultHistory(...)`
 - JSON helper `toJsonValue(...)`
 
+## Experimental 0.2.x Surface
+
+- `buildAgentHarness(...)`
+- `hashAgentHarnessDescriptor(...)`
+- `loadAgentHarnessDescriptor(...)`
+- `loadAgentHarnessDescriptorFromFile(...)`
+- `AgentHarnessDescriptor` and related descriptor types
+
+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)
 
 ```ts
@@ -262,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/harness-descriptor-loader-paths.d.ts

@@ -0,0 +1,29 @@
+export interface DescriptorPathContext {
+    descriptorDir: string;
+    descriptorLabel: string;
+    rootDir: string;
+}
+export interface ResolvedPromptFile {
+    rawPath: string;
+    resolvedPath: string;
+}
+export interface LoadedDescriptorFile {
+    context: DescriptorPathContext;
+    descriptorLabel: string;
+    rootRealPath: string;
+    yaml: string;
+}
+export declare function assertNonEmptyString(value: unknown, label: string): asserts value is string;
+export declare function assertPromptFilePath(value: unknown, label: string): asserts value is string;
+export declare function assertPromptFilePathList(value: unknown, label: string): asserts value is string[];
+export declare function resolvePromptFilePath(rawPath: string, context: DescriptorPathContext, label: string): ResolvedPromptFile;
+export declare function createPathContext(options: {
+    descriptorPath?: string;
+    rootDir?: string;
+}): DescriptorPathContext;
+export declare function createPromptMap(promptMap: Record<string, string>, context: DescriptorPathContext): Map<string, string>;
+export declare function loadDescriptorFile(descriptorPath: string, options?: {
+    rootDir?: string;
+}): Promise<LoadedDescriptorFile>;
+export declare function readResolvedPromptFiles(files: ResolvedPromptFile[], label: string, rootRealPath: string): Promise<string[]>;
+//# sourceMappingURL=harness-descriptor-loader-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harness-descriptor-loader-paths.d.ts","sourceRoot":"","sources":["../src/harness-descriptor-loader-paths.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAKD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,CAIzB;AAmCD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,CAEzB;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,KAAK,IAAI,MAAM,EAAE,CAQ3B;AAiBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAOpB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,qBAAqB,CAaxB;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,qBAAqB,GAC7B,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBrB;AAED,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAED,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,kBAAkB,EAAE,EAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAUnB"}

package/dist/harness-descriptor-loader-paths.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNonEmptyString = assertNonEmptyString;
+exports.assertPromptFilePath = assertPromptFilePath;
+exports.assertPromptFilePathList = assertPromptFilePathList;
+exports.resolvePromptFilePath = resolvePromptFilePath;
+exports.createPathContext = createPathContext;
+exports.createPromptMap = createPromptMap;
+exports.loadDescriptorFile = loadDescriptorFile;
+exports.readResolvedPromptFiles = readResolvedPromptFiles;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const URL_LIKE_PATH = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+const GLOB_LIKE_PATH = /[*?[\]{}]/;
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+}
+function assertPathInsideRoot(path, rootDir, label) {
+    const relativePath = (0, node_path_1.relative)(rootDir, path);
+    if (relativePath === "" ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${node_path_1.sep}`) ||
+        (0, node_path_1.isAbsolute)(relativePath)) {
+        throw new Error(`${label} must resolve inside rootDir "${rootDir}".`);
+    }
+}
+function assertSafePath(value, label, options) {
+    assertNonEmptyString(value, label);
+    if (value.includes("\0")) {
+        throw new Error(`${label} must not contain null bytes.`);
+    }
+    if (URL_LIKE_PATH.test(value)) {
+        throw new Error(`${label} must not be a remote URL.`);
+    }
+    if (!options.allowAbsolute && (0, node_path_1.isAbsolute)(value)) {
+        throw new Error(`${label} must be relative to the descriptor file.`);
+    }
+    if (GLOB_LIKE_PATH.test(value)) {
+        throw new Error(`${label} must not use globbing characters.`);
+    }
+}
+function assertPromptFilePath(value, label) {
+    assertSafePath(value, label, { allowAbsolute: false });
+}
+function assertPromptFilePathList(value, label) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${label} must be a non-empty array of strings.`);
+    }
+    for (const [index, path] of value.entries()) {
+        assertPromptFilePath(path, `${label}[${index}]`);
+    }
+}
+function resolveInsideRoot(rawPath, context, label, options) {
+    assertSafePath(rawPath, label, options);
+    const resolvedPath = (0, node_path_1.isAbsolute)(rawPath)
+        ? (0, node_path_1.resolve)(rawPath)
+        : (0, node_path_1.resolve)(context.descriptorDir, rawPath);
+    assertPathInsideRoot(resolvedPath, context.rootDir, label);
+    return resolvedPath;
+}
+function resolvePromptFilePath(rawPath, context, label) {
+    return {
+        rawPath,
+        resolvedPath: resolveInsideRoot(rawPath, context, label, {
+            allowAbsolute: false,
+        }),
+    };
+}
+function createPathContext(options) {
+    const descriptorPath = options.descriptorPath
+        ? (0, node_path_1.resolve)(options.descriptorPath)
+        : undefined;
+    const descriptorDir = descriptorPath
+        ? (0, node_path_1.dirname)(descriptorPath)
+        : (0, node_path_1.resolve)(options.rootDir ?? process.cwd());
+    const rootDir = (0, node_path_1.resolve)(options.rootDir ?? descriptorDir);
+    return {
+        descriptorDir,
+        descriptorLabel: descriptorPath ?? "<inline descriptor>",
+        rootDir,
+    };
+}
+function createPromptMap(promptMap, context) {
+    const normalized = new Map();
+    for (const [rawPath, content] of Object.entries(promptMap)) {
+        if (typeof content !== "string") {
+            throw new Error(`Prompt map entry "${rawPath}" must be a string.`);
+        }
+        const resolvedPath = resolveInsideRoot(rawPath, context, `Prompt map key "${rawPath}"`, { allowAbsolute: true });
+        normalized.set(resolvedPath, content);
+    }
+    return normalized;
+}
+async function loadDescriptorFile(descriptorPath, options = {}) {
+    assertNonEmptyString(descriptorPath, "Harness descriptor path");
+    const resolvedDescriptorPath = (0, node_path_1.resolve)(descriptorPath);
+    const descriptorDir = (0, node_path_1.dirname)(resolvedDescriptorPath);
+    const rootDir = (0, node_path_1.resolve)(options.rootDir ?? descriptorDir);
+    const context = createPathContext({
+        descriptorPath: resolvedDescriptorPath,
+        rootDir,
+    });
+    assertPathInsideRoot(resolvedDescriptorPath, rootDir, "Harness descriptor path");
+    const rootRealPath = await (0, promises_1.realpath)(rootDir);
+    const descriptorRealPath = await (0, promises_1.realpath)(resolvedDescriptorPath);
+    assertPathInsideRoot(descriptorRealPath, rootRealPath, "Harness descriptor path");
+    return {
+        context,
+        descriptorLabel: descriptorRealPath,
+        rootRealPath,
+        yaml: await (0, promises_1.readFile)(descriptorRealPath, "utf8"),
+    };
+}
+async function readResolvedPromptFiles(files, label, rootRealPath) {
+    const contents = [];
+    for (const file of files) {
+        const promptRealPath = await (0, promises_1.realpath)(file.resolvedPath);
+        assertPathInsideRoot(promptRealPath, rootRealPath, `${label} prompt file`);
+        contents.push(await (0, promises_1.readFile)(promptRealPath, "utf8"));
+    }
+    return contents;
+}

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

@@ -0,0 +1,13 @@
+import type { AgentHarnessDescriptor } from "./harness-descriptor";
+export type AgentHarnessPromptMap = Record<string, string>;
+export interface LoadAgentHarnessDescriptorOptions {
+    descriptorPath?: string;
+    rootDir?: string;
+    promptMap?: AgentHarnessPromptMap;
+}
+export interface LoadAgentHarnessDescriptorFromFileOptions {
+    rootDir?: string;
+}
+export declare function loadAgentHarnessDescriptor(yaml: string, optionsOrPromptMap?: LoadAgentHarnessDescriptorOptions | AgentHarnessPromptMap): AgentHarnessDescriptor;
+export declare function loadAgentHarnessDescriptorFromFile(descriptorPath: string, options?: LoadAgentHarnessDescriptorFromFileOptions): Promise<AgentHarnessDescriptor>;
+//# sourceMappingURL=harness-descriptor-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"harness-descriptor-loader.d.ts","sourceRoot":"","sources":["../src/harness-descriptor-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,sBAAsB,CAAC;AAa9B,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAuC3D,MAAM,WAAW,iCAAiC;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,qBAAqB,CAAC;CACnC;AAED,MAAM,WAAW,yCAAyC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA+ND,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,kBAAkB,CAAC,EACf,iCAAiC,GACjC,qBAAqB,GACxB,sBAAsB,CAyBxB;AAED,wBAAsB,kCAAkC,CACtD,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,yCAA8C,GACtD,OAAO,CAAC,sBAAsB,CAAC,CAkBjC"}

package/dist/harness-descriptor-loader.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAgentHarnessDescriptor = loadAgentHarnessDescriptor;
+exports.loadAgentHarnessDescriptorFromFile = loadAgentHarnessDescriptorFromFile;
+const js_yaml_1 = require("js-yaml");
+const harness_descriptor_loader_paths_1 = require("./harness-descriptor-loader-paths");
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeOptions(optionsOrPromptMap) {
+    if (!optionsOrPromptMap) {
+        return {};
+    }
+    if (Object.prototype.hasOwnProperty.call(optionsOrPromptMap, "descriptorPath") ||
+        Object.prototype.hasOwnProperty.call(optionsOrPromptMap, "rootDir") ||
+        Object.prototype.hasOwnProperty.call(optionsOrPromptMap, "promptMap")) {
+        return optionsOrPromptMap;
+    }
+    return { promptMap: optionsOrPromptMap };
+}
+function parseDescriptorYaml(yaml, descriptorLabel) {
+    const parsed = (0, js_yaml_1.load)(yaml);
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Invalid harness descriptor YAML: ${descriptorLabel}`);
+    }
+    return parsed;
+}
+function collectInstructionFileReferences(descriptor, context) {
+    const references = [];
+    const defaultReference = createInstructionFileReference(descriptor.agent_defaults, "Harness descriptor agent_defaults", context);
+    if (defaultReference) {
+        references.push(defaultReference);
+    }
+    if (!isPlainObject(descriptor.agents)) {
+        return references;
+    }
+    for (const [agentId, agentDescriptor] of Object.entries(descriptor.agents)) {
+        const agentReference = createInstructionFileReference(agentDescriptor, `Harness descriptor agent "${agentId}"`, context);
+        if (agentReference) {
+            references.push(agentReference);
+        }
+    }
+    return references;
+}
+function createInstructionFileReference(value, label, context) {
+    if (!isPlainObject(value)) {
+        return undefined;
+    }
+    const input = readInstructionFilesInput(value, label);
+    if (!input) {
+        return undefined;
+    }
+    return {
+        target: value,
+        label,
+        files: input.paths.map((filePath, index) => ({
+            ...(0, harness_descriptor_loader_paths_1.resolvePromptFilePath)(filePath, context, input.paths.length === 1 ? input.label : `${input.label}[${index}]`),
+        })),
+        appendInlineInstructions: input.appendInlineInstructions,
+    };
+}
+function readInstructionFilesInput(value, label) {
+    const hasInstructionFile = hasDefined(value, "instructions_file");
+    const hasInstructionFiles = hasDefined(value, "instructions_files");
+    if (!hasInstructionFile && !hasInstructionFiles) {
+        return undefined;
+    }
+    assertInstructionFileFields(value, label, {
+        hasInstructionFile,
+        hasInstructionFiles,
+    });
+    if (hasInstructionFile) {
+        const fileLabel = `${label}.instructions_file`;
+        const rawPath = value.instructions_file;
+        (0, harness_descriptor_loader_paths_1.assertPromptFilePath)(rawPath, fileLabel);
+        return {
+            paths: [rawPath],
+            label: fileLabel,
+            appendInlineInstructions: false,
+        };
+    }
+    const filesLabel = `${label}.instructions_files`;
+    const rawPaths = value.instructions_files;
+    (0, harness_descriptor_loader_paths_1.assertPromptFilePathList)(rawPaths, filesLabel);
+    return {
+        paths: rawPaths,
+        label: filesLabel,
+        appendInlineInstructions: true,
+    };
+}
+function hasDefined(value, key) {
+    return key in value && typeof value[key] !== "undefined";
+}
+function assertInstructionFileFields(value, label, fields) {
+    const { hasInstructionFile, hasInstructionFiles } = fields;
+    if (hasInstructionFile && hasInstructionFiles) {
+        throw new Error(`${label}.instructions_file and ${label}.instructions_files are mutually exclusive.`);
+    }
+    if (hasInstructionFile && typeof value.instructions !== "undefined") {
+        throw new Error(`${label}.instructions and ${label}.instructions_file are mutually exclusive.`);
+    }
+    if (hasInstructionFiles &&
+        typeof value.instructions !== "undefined" &&
+        typeof value.instructions !== "string") {
+        throw new Error(`${label}.instructions must be a string when used with ${label}.instructions_files.`);
+    }
+}
+function materializeInstructionReference(reference, contents) {
+    const parts = [...contents];
+    const inlineInstructions = reference.target.instructions;
+    if (reference.appendInlineInstructions &&
+        typeof inlineInstructions === "string" &&
+        inlineInstructions.length > 0) {
+        parts.push(inlineInstructions);
+    }
+    reference.target.instructions = parts.join("\n\n");
+    delete reference.target.instructions_file;
+    delete reference.target.instructions_files;
+}
+function readPromptMapContents(reference, promptMap) {
+    return reference.files.map((file) => {
+        const content = promptMap.get(file.resolvedPath);
+        if (typeof content === "undefined") {
+            throw new Error(`Missing promptMap entry for ${reference.label} prompt file "${file.rawPath}".`);
+        }
+        return content;
+    });
+}
+function loadAgentHarnessDescriptor(yaml, optionsOrPromptMap) {
+    const options = normalizeOptions(optionsOrPromptMap);
+    const context = (0, harness_descriptor_loader_paths_1.createPathContext)(options);
+    const promptMap = options.promptMap
+        ? (0, harness_descriptor_loader_paths_1.createPromptMap)(options.promptMap, context)
+        : undefined;
+    const descriptor = parseDescriptorYaml(yaml, context.descriptorLabel);
+    const references = collectInstructionFileReferences(descriptor, context);
+    if (references.length > 0 && !promptMap) {
+        throw new Error("loadAgentHarnessDescriptor(...) requires promptMap when the descriptor uses instructions_file or instructions_files. Use loadAgentHarnessDescriptorFromFile(...) to read prompt files from disk.");
+    }
+    if (!promptMap) {
+        return descriptor;
+    }
+    for (const reference of references) {
+        const contents = readPromptMapContents(reference, promptMap);
+        materializeInstructionReference(reference, contents);
+    }
+    return descriptor;
+}
+async function loadAgentHarnessDescriptorFromFile(descriptorPath, options = {}) {
+    const loaded = await (0, harness_descriptor_loader_paths_1.loadDescriptorFile)(descriptorPath, options);
+    const descriptor = parseDescriptorYaml(loaded.yaml, loaded.descriptorLabel);
+    const references = collectInstructionFileReferences(descriptor, loaded.context);
+    for (const reference of references) {
+        const contents = await (0, harness_descriptor_loader_paths_1.readResolvedPromptFiles)(reference.files, reference.label, loaded.rootRealPath);
+        materializeInstructionReference(reference, contents);
+    }
+    return descriptor;
+}

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

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

package/dist/harness-descriptor.js

@@ -44,11 +44,23 @@ function validateDescriptorShape(descriptor) {
     assertOptionalPlainObject(descriptor.context, "Harness descriptor context");
     assertOptionalPlainObject(descriptor.context?.fields, "Harness descriptor context.fields");
     assertOptionalPlainObject(descriptor.context?.references, "Harness descriptor context.references");
+    assertNoUnresolvedInstructionFile(descriptor.agent_defaults, "Harness descriptor agent_defaults");
+    for (const [agentId, agentDescriptor] of Object.entries(descriptor.agents)) {
+        assertPlainObject(agentDescriptor, `Harness descriptor agent "${agentId}"`);
+        assertNoUnresolvedInstructionFile(agentDescriptor, `Harness descriptor agent "${agentId}"`);
+    }
     for (const [toolId, toolDescriptor] of Object.entries(descriptor.tools ?? {})) {
         assertPlainObject(toolDescriptor, `Harness descriptor tool "${toolId}"`);
         assertNonEmptyString(toolDescriptor.target, `Harness descriptor tool "${toolId}".target`);
     }
 }
+function assertNoUnresolvedInstructionFile(value, label) {
+    if (!isPlainObject(value) ||
+        (!("instructions_file" in value) && !("instructions_files" in value))) {
+        return;
+    }
+    throw new Error(`${label}.instructions_file/instructions_files must be materialized by loadAgentHarnessDescriptor(...) before buildAgentHarness(...).`);
+}
 function normalizePromptPath(path, label) {
     const segments = path
         .split(".")

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./agent";
+export * from "./approval-helpers";
 export * from "./config";
 export * from "./errors";
 export * from "./guardrails";
 export * from "./harness-descriptor";
+export * from "./harness-descriptor-loader";
 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,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"}
+{"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,10 +15,12 @@ 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("./harness-descriptor-loader"), 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.2.0-next.2",
+  "version": "0.2.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [