@axiastudio/aioc 0.2.0-next.1 → 0.2.0

package/README.md

@@ -15,6 +15,8 @@ The core runtime surface is compatibility-managed. Breaking changes to the stabl
 
 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.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.
+
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
 - Historical alpha contract snapshot: `docs/ALPHA-CONTRACT.md`
@@ -102,6 +104,16 @@ console.log(result.finalOutput);
 - thread history utilities `toThreadHistory(...)`, `appendUserMessage(...)`, `replaceThreadHistory(...)`, `applyRunResultHistory(...)`
 - JSON helper `toJsonValue(...)`
 
+## Experimental 0.2.0 Surface
+
+- `buildAgentHarness(...)`
+- `hashAgentHarnessDescriptor(...)`
+- `loadAgentHarnessDescriptor(...)`
+- `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.
+
 ## Policy Gate (Minimal)
 
 ```ts
@@ -266,6 +278,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-0011-agent-harness-descriptor.md` (`Experimental`)
 - `docs/PRIVACY-BASELINE.md`
 
 ## Historical Snapshots

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

@@ -14,6 +14,53 @@ function cloneJsonValue(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");
+    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(".")
@@ -188,6 +235,7 @@ 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);

package/dist/index.d.ts

@@ -3,6 +3,7 @@ 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,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

@@ -19,6 +19,7 @@ __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.1",
+  "version": "0.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [