@axiastudio/aioc 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,7 @@ Project home and documentation: [https://axiastudio.github.io/aioc](https://axia
 
 ## Release Status
 
-Current stable release: `0.2.1`.
+Current stable release: `0.2.2`.
 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.
 
@@ -18,8 +18,9 @@ AIOC `0.1.0` stabilized the core runtime surface, public documentation aligned t
 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.0` adds implemented runtime utilities and the Agent Harness Descriptor API. The core runtime remains compatibility-managed; descriptor shape and loader helpers are now part of the supported `0.2.x` surface and may evolve across `0.x` minor releases only with explicit migration guidance.
 AIOC `0.2.1` realigns the `0.2.x` package line with the current `main` history after `0.2.0` was published from the descriptor release branch.
+AIOC `0.2.2` completes the descriptor instruction-composition surface with reusable `instruction_parts`, ordered `instructions_sequence`, and boolean `where` gates.
 
 - Release notes: `CHANGELOG.md`
 - Historical beta contract snapshot: `docs/BETA-CONTRACT.md`
@@ -109,7 +110,7 @@ console.log(result.finalOutput);
 - thread history utilities `toThreadHistory(...)`, `appendUserMessage(...)`, `replaceThreadHistory(...)`, `applyRunResultHistory(...)`
 - JSON helper `toJsonValue(...)`
 
-## Experimental 0.2.x Surface
+## Agent Harness Descriptor
 
 - `buildAgentHarness(...)`
 - `hashAgentHarnessDescriptor(...)`
@@ -117,7 +118,7 @@ console.log(result.finalOutput);
 - `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.
+The Agent Harness Descriptor is included in the supported `0.2.x` API surface as the `aioc.agent_graph.v0` descriptor contract. 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)
 
@@ -284,7 +285,7 @@ AIOC adopts the following non-negotiable principles:
 - `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/RFC-0011-agent-harness-descriptor.md` (`Accepted`)
 - `docs/PRIVACY-BASELINE.md`
 
 ## Historical Snapshots

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

@@ -1 +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"}
+{"version":3,"file":"harness-descriptor-loader.d.ts","sourceRoot":"","sources":["../src/harness-descriptor-loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,sBAAsB,CAAC;AAa9B,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAoE3D,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;AAkeD,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,kBAAkB,CAAC,EACf,iCAAiC,GACjC,qBAAqB,GACxB,sBAAsB,CAuCxB;AAED,wBAAsB,kCAAkC,CACtD,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,yCAA8C,GACtD,OAAO,CAAC,sBAAsB,CAAC,CA0CjC"}

package/dist/harness-descriptor-loader.js

@@ -42,6 +42,23 @@ function collectInstructionFileReferences(descriptor, context) {
     }
     return references;
 }
+function collectInstructionSequenceReferences(descriptor, context) {
+    const references = [];
+    const defaultReference = createInstructionSequenceReference(descriptor.agent_defaults, "Harness descriptor agent_defaults", descriptor, context);
+    if (defaultReference) {
+        references.push(defaultReference);
+    }
+    if (!isPlainObject(descriptor.agents)) {
+        return references;
+    }
+    for (const [agentId, agentDescriptor] of Object.entries(descriptor.agents)) {
+        const agentReference = createInstructionSequenceReference(agentDescriptor, `Harness descriptor agent "${agentId}"`, descriptor, context);
+        if (agentReference) {
+            references.push(agentReference);
+        }
+    }
+    return references;
+}
 function createInstructionFileReference(value, label, context) {
     if (!isPlainObject(value)) {
         return undefined;
@@ -59,6 +76,102 @@ function createInstructionFileReference(value, label, context) {
         appendInlineInstructions: input.appendInlineInstructions,
     };
 }
+function createInstructionSequenceReference(value, label, descriptor, context) {
+    if (!isPlainObject(value) || !hasDefined(value, "instructions_sequence")) {
+        return undefined;
+    }
+    assertInstructionSequenceFields(value, label);
+    const rawItems = value.instructions_sequence;
+    if (!Array.isArray(rawItems) || rawItems.length === 0) {
+        throw new Error(`${label}.instructions_sequence must be a non-empty array.`);
+    }
+    return {
+        target: value,
+        label,
+        items: rawItems.map((item, index) => readInstructionSequenceItem(item, `${label}.instructions_sequence[${index}]`, descriptor, context)),
+    };
+}
+function assertInstructionSequenceFields(value, label) {
+    for (const field of [
+        "instructions",
+        "instructions_file",
+        "instructions_files",
+    ]) {
+        if (hasDefined(value, field)) {
+            throw new Error(`${label}.instructions_sequence is mutually exclusive with ${label}.${field}.`);
+        }
+    }
+}
+function readInstructionSequenceItem(value, label, descriptor, context) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    const hasFile = hasDefined(value, "file");
+    const hasRef = hasDefined(value, "ref");
+    const hasText = hasDefined(value, "text");
+    const definedKinds = [hasFile, hasRef, hasText].filter(Boolean).length;
+    if (definedKinds !== 1) {
+        throw new Error(`${label} must define exactly one of file, ref, or text.`);
+    }
+    const where = readInstructionWhere(value.where, label);
+    if (hasFile) {
+        const fileLabel = `${label}.file`;
+        (0, harness_descriptor_loader_paths_1.assertPromptFilePath)(value.file, fileLabel);
+        return {
+            kind: "file",
+            file: (0, harness_descriptor_loader_paths_1.resolvePromptFilePath)(value.file, context, fileLabel),
+            ...(where ? { where } : {}),
+        };
+    }
+    if (hasRef) {
+        const refLabel = `${label}.ref`;
+        const ref = readNonEmptyString(value.ref, refLabel);
+        return {
+            kind: "ref",
+            text: resolveInstructionPartReference(descriptor, ref, refLabel),
+            ...(where ? { where } : {}),
+        };
+    }
+    return {
+        kind: "text",
+        text: readString(value.text, `${label}.text`),
+        ...(where ? { where } : {}),
+    };
+}
+function readInstructionWhere(value, label) {
+    if (typeof value === "undefined") {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new Error(`${label}.where must be an object.`);
+    }
+    return {
+        context: readNonEmptyString(value.context, `${label}.where.context`),
+    };
+}
+function readString(value, label) {
+    if (typeof value !== "string") {
+        throw new Error(`${label} must be a string.`);
+    }
+    return value;
+}
+function readNonEmptyString(value, label) {
+    const text = readString(value, label);
+    if (text.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return text;
+}
+function resolveInstructionPartReference(descriptor, ref, label) {
+    const catalog = descriptor.instruction_parts;
+    if (!isPlainObject(catalog)) {
+        throw new Error(`${label} references instruction part "${ref}", but descriptor.instruction_parts is not defined.`);
+    }
+    if (!(ref in catalog)) {
+        throw new Error(`${label} references unknown instruction part "${ref}".`);
+    }
+    return readString(catalog[ref], `descriptor.instruction_parts.${ref}`);
+}
 function readInstructionFilesInput(value, label) {
     const hasInstructionFile = hasDefined(value, "instructions_file");
     const hasInstructionFiles = hasDefined(value, "instructions_files");
@@ -68,6 +181,7 @@ function readInstructionFilesInput(value, label) {
     assertInstructionFileFields(value, label, {
         hasInstructionFile,
         hasInstructionFiles,
+        hasInstructionSequence: hasDefined(value, "instructions_sequence"),
     });
     if (hasInstructionFile) {
         const fileLabel = `${label}.instructions_file`;
@@ -92,13 +206,16 @@ function hasDefined(value, key) {
     return key in value && typeof value[key] !== "undefined";
 }
 function assertInstructionFileFields(value, label, fields) {
-    const { hasInstructionFile, hasInstructionFiles } = fields;
+    const { hasInstructionFile, hasInstructionFiles, hasInstructionSequence } = 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 (hasInstructionSequence && (hasInstructionFile || hasInstructionFiles)) {
+        throw new Error(`${label}.instructions_sequence is mutually exclusive with ${label}.instructions_file/instructions_files.`);
+    }
     if (hasInstructionFiles &&
         typeof value.instructions !== "undefined" &&
         typeof value.instructions !== "string") {
@@ -117,6 +234,21 @@ function materializeInstructionReference(reference, contents) {
     delete reference.target.instructions_file;
     delete reference.target.instructions_files;
 }
+function sequenceRequiresPromptFiles(reference) {
+    return reference.items.some((item) => item.kind === "file");
+}
+function materializeInstructionSequenceReference(reference, contents) {
+    let fileContentIndex = 0;
+    const parts = reference.items.map((item) => {
+        const text = item.kind === "file" ? contents[fileContentIndex++] : item.text;
+        return {
+            text: text ?? "",
+            ...(item.where ? { where: item.where } : {}),
+        };
+    });
+    reference.target.instructions = parts;
+    delete reference.target.instructions_sequence;
+}
 function readPromptMapContents(reference, promptMap) {
     return reference.files.map((file) => {
         const content = promptMap.get(file.resolvedPath);
@@ -126,6 +258,17 @@ function readPromptMapContents(reference, promptMap) {
         return content;
     });
 }
+function readPromptMapSequenceContents(reference, promptMap) {
+    return reference.items
+        .filter((item) => item.kind === "file")
+        .map((item) => {
+        const content = promptMap.get(item.file.resolvedPath);
+        if (typeof content === "undefined") {
+            throw new Error(`Missing promptMap entry for ${reference.label} prompt file "${item.file.rawPath}".`);
+        }
+        return content;
+    });
+}
 function loadAgentHarnessDescriptor(yaml, optionsOrPromptMap) {
     const options = normalizeOptions(optionsOrPromptMap);
     const context = (0, harness_descriptor_loader_paths_1.createPathContext)(options);
@@ -134,15 +277,23 @@ function loadAgentHarnessDescriptor(yaml, optionsOrPromptMap) {
         : 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.");
+    const sequenceReferences = collectInstructionSequenceReferences(descriptor, context);
+    const hasPromptFileReferences = references.length > 0 ||
+        sequenceReferences.some((reference) => sequenceRequiresPromptFiles(reference));
+    if (hasPromptFileReferences && !promptMap) {
+        throw new Error("loadAgentHarnessDescriptor(...) requires promptMap when the descriptor uses instructions_file, instructions_files, or instructions_sequence file items. Use loadAgentHarnessDescriptorFromFile(...) to read prompt files from disk.");
     }
-    if (!promptMap) {
-        return descriptor;
+    if (promptMap) {
+        for (const reference of references) {
+            const contents = readPromptMapContents(reference, promptMap);
+            materializeInstructionReference(reference, contents);
+        }
     }
-    for (const reference of references) {
-        const contents = readPromptMapContents(reference, promptMap);
-        materializeInstructionReference(reference, contents);
+    for (const reference of sequenceReferences) {
+        const contents = promptMap
+            ? readPromptMapSequenceContents(reference, promptMap)
+            : [];
+        materializeInstructionSequenceReference(reference, contents);
     }
     return descriptor;
 }
@@ -150,9 +301,19 @@ 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);
+    const sequenceReferences = collectInstructionSequenceReferences(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);
     }
+    for (const reference of sequenceReferences) {
+        const files = reference.items
+            .filter((item) => item.kind === "file")
+            .map((item) => item.file);
+        const contents = files.length > 0
+            ? await (0, harness_descriptor_loader_paths_1.readResolvedPromptFiles)(files, reference.label, loaded.rootRealPath)
+            : [];
+        materializeInstructionSequenceReference(reference, contents);
+    }
     return descriptor;
 }

package/dist/harness-descriptor.d.ts

@@ -16,12 +16,20 @@ export interface HarnessToolDescriptor {
 export interface HarnessAgentDescriptor {
     name?: string;
     handoffDescription?: string;
-    instructions?: string;
+    instructions?: HarnessInstructionsDescriptor;
     model?: string;
     modelSettings?: Record<string, unknown>;
     tools?: string[];
     handoffs?: string[];
 }
+export interface HarnessInstructionWhereDescriptor {
+    context: string;
+}
+export interface HarnessInstructionPartDescriptor {
+    text: string;
+    where?: HarnessInstructionWhereDescriptor;
+}
+export type HarnessInstructionsDescriptor = string | HarnessInstructionPartDescriptor[];
 export interface HarnessContextReferenceDescriptor {
     type?: string;
     optional?: boolean;
@@ -45,6 +53,7 @@ export interface AgentHarnessDescriptor {
     metadata?: HarnessDescriptorMetadata;
     runtime: HarnessRuntimeDescriptor;
     context?: HarnessContextDescriptor;
+    instruction_parts?: Record<string, string>;
     tools?: Record<string, HarnessToolDescriptor>;
     agent_defaults?: Pick<HarnessAgentDescriptor, "model" | "modelSettings" | "instructions">;
     agents: Record<string, HarnessAgentDescriptor>;

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

@@ -1 +1 @@
-{"version":3,"file":"harness-descriptor.d.ts","sourceRoot":"","sources":["../src/harness-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA0B,MAAM,SAAS,CAAC;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iCAAiC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,4BAA4B,GACpC,OAAO,GACP,iCAAiC,CAAC;AAEtC,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,OAAO,EAAE,wBAAwB,CAAC;IAClC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,IAAI,CACnB,sBAAsB,EACtB,OAAO,GAAG,eAAe,GAAG,cAAc,CAC3C,CAAC;IACF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB,CAAC,QAAQ,GAAG,OAAO;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,UAAU,EAAE,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1D,aAAa,CAAC,KAAK,CAAC,EAAE,yBAAyB,GAAG,QAAQ,CAAC;CAC5D;AA4XD,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,sBAAsB,GACjC,MAAM,CAER;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAClD,UAAU,EAAE,sBAAsB,EAClC,QAAQ,GAAE,oBAAoB,CAAC,QAAQ,CAAM,GAC5C,YAAY,CAAC,QAAQ,CAAC,CAqExB"}
+{"version":3,"file":"harness-descriptor.d.ts","sourceRoot":"","sources":["../src/harness-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/harness-descriptor.js

@@ -40,6 +40,7 @@ function validateDescriptorShape(descriptor) {
     }
     assertOptionalPlainObject(descriptor.metadata, "Harness descriptor metadata");
     assertOptionalPlainObject(descriptor.tools, "Harness descriptor tools");
+    assertOptionalPlainObject(descriptor.instruction_parts, "Harness descriptor instruction_parts");
     assertOptionalPlainObject(descriptor.agent_defaults, "Harness descriptor agent_defaults");
     assertOptionalPlainObject(descriptor.context, "Harness descriptor context");
     assertOptionalPlainObject(descriptor.context?.fields, "Harness descriptor context.fields");
@@ -56,10 +57,12 @@ function validateDescriptorShape(descriptor) {
 }
 function assertNoUnresolvedInstructionFile(value, label) {
     if (!isPlainObject(value) ||
-        (!("instructions_file" in value) && !("instructions_files" in value))) {
+        (!("instructions_file" in value) &&
+            !("instructions_files" in value) &&
+            !("instructions_sequence" in value))) {
         return;
     }
-    throw new Error(`${label}.instructions_file/instructions_files must be materialized by loadAgentHarnessDescriptor(...) before buildAgentHarness(...).`);
+    throw new Error(`${label}.instructions_file/instructions_files/instructions_sequence must be materialized by loadAgentHarnessDescriptor(...) before buildAgentHarness(...).`);
 }
 function normalizePromptPath(path, label) {
     const segments = path
@@ -90,7 +93,10 @@ function createPromptReferenceRules(descriptor) {
         if (!isPlainObject(reference)) {
             throw new Error(`Context reference "${path}" must be true, false, or an object.`);
         }
-        rules.set(normalizedPath, { optional: Boolean(reference.optional) });
+        rules.set(normalizedPath, {
+            optional: Boolean(reference.optional),
+            type: typeof reference.type === "string" ? reference.type : undefined,
+        });
     }
     return rules;
 }
@@ -147,19 +153,105 @@ function renderInstructionTemplate(template, context, promptAccessRules) {
         return stringifyPromptValue(resolved.value);
     });
 }
+function readWhereContextValue(context, path) {
+    return readPromptPath(context, path);
+}
+function assertInstructionWhere(where, label) {
+    if (!isPlainObject(where)) {
+        throw new Error(`${label}.where must be an object.`);
+    }
+    assertNonEmptyString(where.context, `${label}.where.context`);
+}
+function assertInstructionPart(part, label) {
+    if (!isPlainObject(part)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    if (typeof part.text !== "string") {
+        throw new Error(`${label}.text must be a string.`);
+    }
+    if (typeof part.where !== "undefined") {
+        assertInstructionWhere(part.where, label);
+    }
+}
+function assertInstructionParts(agentId, instructions) {
+    instructions.forEach((part, index) => assertInstructionPart(part, `Agent "${agentId}" instructions[${index}]`));
+}
+function collectInstructionPartPromptPaths(instructions) {
+    const paths = new Set();
+    for (const part of instructions) {
+        for (const path of collectContextPromptPaths(part.text)) {
+            paths.add(path);
+        }
+    }
+    return [...paths];
+}
+function collectInstructionWherePaths(instructions) {
+    const paths = new Set();
+    for (const part of instructions) {
+        if (!part.where) {
+            continue;
+        }
+        paths.add(normalizePromptPath(part.where.context, "Instruction where.context path"));
+    }
+    return [...paths];
+}
+function assertDeclaredPromptPaths(agentId, paths, promptAccessRules) {
+    for (const path of paths) {
+        if (!promptAccessRules.has(path)) {
+            throw new Error(`Agent "${agentId}" instruction references undeclared context path "${path}".`);
+        }
+    }
+}
+function assertDeclaredBooleanWherePaths(agentId, paths, promptAccessRules) {
+    for (const path of paths) {
+        const rule = promptAccessRules.get(path);
+        if (!rule) {
+            throw new Error(`Agent "${agentId}" instruction where references undeclared context path "${path}".`);
+        }
+        if (rule.type !== "boolean") {
+            throw new Error(`Agent "${agentId}" instruction where context path "${path}" must be declared with type "boolean".`);
+        }
+    }
+}
+function shouldIncludeInstructionPart(part, context) {
+    if (!part.where) {
+        return true;
+    }
+    const path = normalizePromptPath(part.where.context, "Instruction where.context path");
+    const resolved = readWhereContextValue(context, path);
+    if (!resolved.exists || typeof resolved.value === "undefined") {
+        throw new Error(`Harness descriptor instruction where could not resolve context path "${path}".`);
+    }
+    if (typeof resolved.value !== "boolean") {
+        throw new Error(`Harness descriptor instruction where context path "${path}" must resolve to a boolean.`);
+    }
+    return resolved.value === true;
+}
+function renderInstructionParts(instructions, context, promptAccessRules) {
+    const parts = [];
+    for (const part of instructions) {
+        if (!shouldIncludeInstructionPart(part, context)) {
+            continue;
+        }
+        parts.push(renderInstructionTemplate(part.text, context, promptAccessRules));
+    }
+    return parts.join("\n\n");
+}
 function compileAgentInstructions(agentId, instructions, promptAccessRules) {
     if (typeof instructions === "undefined") {
         return undefined;
     }
+    if (Array.isArray(instructions)) {
+        assertInstructionParts(agentId, instructions);
+        assertDeclaredPromptPaths(agentId, collectInstructionPartPromptPaths(instructions), promptAccessRules);
+        assertDeclaredBooleanWherePaths(agentId, collectInstructionWherePaths(instructions), promptAccessRules);
+        return (runContext) => renderInstructionParts(instructions, runContext.context, promptAccessRules);
+    }
     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}".`);
-        }
-    }
+    assertDeclaredPromptPaths(agentId, promptPaths, promptAccessRules);
     return (runContext) => renderInstructionTemplate(instructions, runContext.context, promptAccessRules);
 }
 function setPath(target, path, value) {

package/package.json

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