@irisrun/agent 0.1.0

package/dist/agentfile.d.ts

@@ -0,0 +1,46 @@
+export interface CapabilityProfile {
+    long_running?: boolean;
+    local_subprocess?: boolean;
+    filesystem?: boolean;
+    websockets?: boolean;
+    tool_locality?: "in-process" | "local" | "remote";
+}
+export interface ToolRef {
+    ref: string;
+}
+export interface AgentfileModel {
+    apiVersion: "iris/v1";
+    kind: "Agent";
+    name: string;
+    model: string;
+    instructions: string;
+    skills: string[];
+    tools: ToolRef[];
+    connections: ToolRef[];
+    harness: {
+        bundle?: string;
+        tactics?: Record<string, string>;
+    };
+    requires: CapabilityProfile;
+    sandbox: {
+        backend: string;
+        workspace?: string;
+        network: string;
+    };
+}
+/** Parse Agentfile JSON text into a validated model (throws loudly on bad JSON or shape). */
+export declare function parseAgentfileJson(text: string): AgentfileModel;
+/**
+ * Validate a raw parsed object into an AgentfileModel. Guards every boundary
+ * (shape, required fields) and enforces the content-vs-contract split: a tool /
+ * connection entry is REJECTED if it carries an inline-behavior field
+ * (code/script/source) or a ref whose scheme is not mcp/grpc/subprocess
+ * (ADR-0005 — no behavior in the manifest). Throws loudly; never coerces.
+ */
+export declare function validateAgentfile(raw: unknown): AgentfileModel;
+/** Content paths embedded by hash: instructions, skills, then sandbox.workspace (if any). */
+export declare function contentPaths(model: AgentfileModel): string[];
+/** Contract refs pinned by digest: tools then connections. */
+export declare function contractRefs(model: AgentfileModel): ToolRef[];
+/** The scheme of a contract ref, e.g. "mcp" for "mcp://registry/x@^2". */
+export declare function refScheme(ref: string): string;

package/dist/agentfile.js

@@ -0,0 +1,161 @@
+// A contract ref must use one of these schemes; anything else (incl. an inline
+// `code`/`script`/`source` field) is inlined behavior and is rejected (ADR-0005).
+const CONTRACT_SCHEMES = ["mcp", "grpc", "subprocess"];
+const INLINE_BEHAVIOR_FIELDS = ["code", "script", "source"];
+// `requires` (the capability profile) is strict-when-present so the runtime
+// validator agrees with the published JSON schema (schema.ts): a present
+// `tool_locality` must be one of these, and a present boolean cap must be a
+// boolean. (Initiative 20260620-agentfile-schema — these were untyped before.)
+const TOOL_LOCALITIES = ["in-process", "local", "remote"];
+const BOOLEAN_CAPS = ["long_running", "local_subprocess", "filesystem", "websockets"];
+/** Parse Agentfile JSON text into a validated model (throws loudly on bad JSON or shape). */
+export function parseAgentfileJson(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`Agentfile: invalid JSON — ${e.message}`);
+    }
+    return validateAgentfile(raw);
+}
+/**
+ * Validate a raw parsed object into an AgentfileModel. Guards every boundary
+ * (shape, required fields) and enforces the content-vs-contract split: a tool /
+ * connection entry is REJECTED if it carries an inline-behavior field
+ * (code/script/source) or a ref whose scheme is not mcp/grpc/subprocess
+ * (ADR-0005 — no behavior in the manifest). Throws loudly; never coerces.
+ */
+export function validateAgentfile(raw) {
+    const o = asObject(raw, "Agentfile");
+    if (o.apiVersion !== "iris/v1") {
+        throw new Error(`Agentfile: apiVersion must be "iris/v1" (got ${JSON.stringify(o.apiVersion)})`);
+    }
+    if (o.kind !== "Agent") {
+        throw new Error(`Agentfile: kind must be "Agent" (got ${JSON.stringify(o.kind)})`);
+    }
+    const name = requireString(o, "name");
+    const model = requireString(o, "model");
+    const instructions = requireString(o, "instructions");
+    const skills = requireStringArray(o, "skills");
+    const tools = requireRefArray(o, "tools");
+    const connections = requireRefArray(o, "connections");
+    // Default ONLY when ABSENT (undefined). An explicit JSON `null` is wrong-typed
+    // — the schema types harness/requires as `object`, so a present null must be
+    // rejected, not coerced to {} (which `?? {}` would do). sandbox needs no guard:
+    // it is required, so null/absent already throws via asObject below.
+    const harness = asObject(o.harness === undefined ? {} : o.harness, "harness");
+    const requires = asObject(o.requires === undefined ? {} : o.requires, "requires");
+    validateCapabilityProfile(requires);
+    const sandbox = asObject(o.sandbox, "sandbox");
+    // Build optional sub-objects WITHOUT undefined keys — canonicalize (used for
+    // the imageDigest) rejects undefined values, and omission keeps the YAML/JSON
+    // models deep-equal. A present-but-wrong-typed `bundle`/`workspace` now throws
+    // (was silently dropped) so the runtime agrees with the JSON schema; a
+    // well-typed value behaves exactly as before, so existing digests are unchanged.
+    const harnessOut = {};
+    if (harness.bundle !== undefined) {
+        if (typeof harness.bundle !== "string")
+            throw new Error("Agentfile: harness.bundle must be a string");
+        harnessOut.bundle = harness.bundle;
+    }
+    if (harness.tactics !== undefined) {
+        harnessOut.tactics = asObject(harness.tactics, "harness.tactics");
+    }
+    const sandboxOut = {
+        backend: requireString(sandbox, "sandbox.backend", "backend"),
+        network: requireString(sandbox, "sandbox.network", "network"),
+    };
+    if (sandbox.workspace !== undefined) {
+        if (typeof sandbox.workspace !== "string")
+            throw new Error("Agentfile: sandbox.workspace must be a string");
+        sandboxOut.workspace = sandbox.workspace;
+    }
+    return {
+        apiVersion: "iris/v1",
+        kind: "Agent",
+        name,
+        model,
+        instructions,
+        skills,
+        tools,
+        connections,
+        harness: harnessOut,
+        requires: requires,
+        sandbox: sandboxOut,
+    };
+}
+// Strict-when-present validation of the capability profile (`requires`), so the
+// runtime agrees with the published JSON schema. Unknown keys are still ignored
+// (retained in the model) — only the KNOWN fields are type-checked when present.
+function validateCapabilityProfile(o) {
+    for (const cap of BOOLEAN_CAPS) {
+        if (cap in o && typeof o[cap] !== "boolean") {
+            throw new Error(`Agentfile: requires.${cap} must be a boolean`);
+        }
+    }
+    const tl = o.tool_locality;
+    if (tl !== undefined && !TOOL_LOCALITIES.includes(tl)) {
+        throw new Error(`Agentfile: requires.tool_locality must be one of ${TOOL_LOCALITIES.join("/")} (got ${JSON.stringify(tl)})`);
+    }
+}
+function asObject(v, what) {
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(`Agentfile: ${what} must be an object`);
+    }
+    return v;
+}
+function requireString(o, label, key = label) {
+    const v = o[key];
+    if (typeof v !== "string" || v.length === 0) {
+        throw new Error(`Agentfile: required field "${label}" must be a non-empty string`);
+    }
+    return v;
+}
+function requireStringArray(o, key) {
+    const v = o[key];
+    if (!Array.isArray(v) || !v.every((x) => typeof x === "string")) {
+        throw new Error(`Agentfile: "${key}" must be an array of strings`);
+    }
+    return v;
+}
+// Validate a tools/connections array, rejecting inlined behavior (ADR-0005).
+function requireRefArray(o, key) {
+    const v = o[key];
+    if (!Array.isArray(v)) {
+        throw new Error(`Agentfile: "${key}" must be an array`);
+    }
+    return v.map((entry, i) => {
+        const e = asObject(entry, `${key}[${i}]`);
+        for (const field of INLINE_BEHAVIOR_FIELDS) {
+            if (field in e) {
+                throw new Error(`Agentfile: ${key}[${i}] carries inline behavior ("${field}") — tools are contracts referenced by digest, not inlined code (ADR-0005)`);
+            }
+        }
+        const ref = e.ref;
+        if (typeof ref !== "string" || ref.length === 0) {
+            throw new Error(`Agentfile: ${key}[${i}].ref must be a non-empty string`);
+        }
+        const scheme = refScheme(ref);
+        if (!CONTRACT_SCHEMES.includes(scheme)) {
+            throw new Error(`Agentfile: ${key}[${i}] ref scheme "${scheme}" is not a contract scheme (must be one of ${CONTRACT_SCHEMES.join("/")}) — got "${ref}"`);
+        }
+        return { ref };
+    });
+}
+/** Content paths embedded by hash: instructions, skills, then sandbox.workspace (if any). */
+export function contentPaths(model) {
+    const paths = [model.instructions, ...model.skills];
+    if (model.sandbox.workspace !== undefined)
+        paths.push(model.sandbox.workspace);
+    return paths;
+}
+/** Contract refs pinned by digest: tools then connections. */
+export function contractRefs(model) {
+    return [...model.tools, ...model.connections];
+}
+/** The scheme of a contract ref, e.g. "mcp" for "mcp://registry/x@^2". */
+export function refScheme(ref) {
+    const i = ref.indexOf("://");
+    return i > 0 ? ref.slice(0, i) : "";
+}

package/dist/bundle.d.ts

@@ -0,0 +1,13 @@
+import { type Json } from "@irisrun/core";
+export interface BundleDefinition {
+    id: string;
+    version: string;
+    seams: string[];
+    location?: string;
+    [k: string]: Json | undefined;
+}
+export interface BundleResolver {
+    resolve(ref: string): Promise<BundleDefinition | null>;
+}
+/** sha256 over the canonical behavior surface — stable across location float. */
+export declare function bundleDigest(def: BundleDefinition): string;

package/dist/bundle.js

@@ -0,0 +1,31 @@
+// Bundle resolution + digest (spec §4.2, ADR-0004) — the M6 strengthening of the
+// M4 tactic pin. A tactic BUNDLE (e.g. `@irisrun/bundle-coding`) is distributed like
+// a tool contract: an Agentfile `harness.bundle` ref (e.g. "iris/coding@^1")
+// resolves — via an injected BundleResolver, mirroring the M4 RegistryResolver —
+// to a concrete BundleDefinition, and the image pins `bundleDigest(def)` (a real
+// content digest over the BEHAVIOR SURFACE) instead of the M4 sha256Hex(id)
+// placeholder. The digest is STABLE across a floating `location` (re-resolve by
+// stable ref, not by location — [[lrn-resolve-by-stable-ref-not-floating-location]])
+// yet detects any change to the behavior surface (id/version/seams/...).
+// Host-side (node:crypto + @irisrun/core canonicalize).
+import { createHash } from "node:crypto";
+import { canonicalize } from "@irisrun/core";
+// The behavior surface the digest is computed over: the full definition MINUS the
+// floating `location` (and any undefined fields, which canonicalize rejects). Two
+// definitions that differ only in `location` produce the SAME surface → the SAME
+// digest (the ADR-0004 float-impl property); any behavior-surface change differs.
+function behaviorSurface(def) {
+    const surface = {};
+    for (const [k, v] of Object.entries(def)) {
+        if (k === "location")
+            continue; // floats — excluded from the digest
+        if (v === undefined)
+            continue; // canonicalize rejects undefined
+        surface[k] = v;
+    }
+    return surface;
+}
+/** sha256 over the canonical behavior surface — stable across location float. */
+export function bundleDigest(def) {
+    return createHash("sha256").update(canonicalize(behaviorSurface(def))).digest("hex");
+}

package/dist/image.d.ts

@@ -0,0 +1,41 @@
+import { type Json } from "@irisrun/core";
+import { type AgentfileModel, type CapabilityProfile } from "./agentfile.js";
+import { type Lock, type LockTool } from "./lock.js";
+import type { RegistryResolver } from "./resolver.js";
+import { type BundleResolver } from "./bundle.js";
+export interface AgentImage {
+    agentfile: AgentfileModel;
+    lock: Lock;
+    content: Record<string, string>;
+}
+export interface BuildOptions {
+    resolver: RegistryResolver;
+    readFile: (path: string) => Promise<Uint8Array>;
+    resolveBundle?: BundleResolver;
+}
+export declare function sha256Hex(bytes: Uint8Array | string): string;
+export declare function normalizeContentKey(path: string): string;
+export declare function canonicalImageOf(image: AgentImage): Json;
+export declare function computeImageDigest(image: AgentImage): string;
+/**
+ * Resolve + pin contracts, embed content by hash, validate capabilities, and emit
+ * a content-addressed image. Deterministic: identical inputs → identical
+ * `imageDigest`.
+ */
+export declare function buildImage(model: AgentfileModel, opts: BuildOptions): Promise<AgentImage>;
+export interface ImageInspection {
+    name: string;
+    model: string;
+    imageDigest: string;
+    tools: LockTool[];
+    content: Record<string, string>;
+    tactics: Record<string, {
+        id: string;
+        digest: string;
+    }>;
+    capabilities: CapabilityProfile;
+}
+/** Human-readable resolved intent of an image (what `iris inspect` prints). */
+export declare function inspectImage(image: AgentImage): ImageInspection;
+export declare function writeOciLayout(dir: string, image: AgentImage): Promise<void>;
+export declare function readOciLayout(dir: string, ref?: string): Promise<AgentImage>;

package/dist/image.js

@@ -0,0 +1,144 @@
+// Image build (spec §3.5): resolve + pin → embed content by hash → compute the
+// content-addressed, deterministic imageDigest = sha256(canonicalize(canonical
+// image)). The canonical image EXCLUDES the self-referential imageDigest field;
+// content values are base64 STRINGS (canonicalize rejects Buffer/Uint8Array) and
+// content keys are normalized (forward-slash, relative) for cross-platform
+// determinism. Host-side (node:crypto + @irisrun/core canonicalize).
+import { createHash } from "node:crypto";
+import { mkdir, writeFile, readFile as fsReadFile } from "node:fs/promises";
+import { join } from "node:path";
+import { canonicalize } from "@irisrun/core";
+import { contentPaths, contractRefs, } from "./agentfile.js";
+import { resolveLockTools, validateCapabilities, } from "./lock.js";
+import { bundleDigest } from "./bundle.js";
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// Normalize a content path to a canonical, platform-independent key: forward
+// slashes, no leading "./". So two builds on different OSes key the same file
+// identically (canonicalize sorts keys lexicographically).
+export function normalizeContentKey(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function toBase64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+// The image MINUS its self-referential imageDigest — the bytes the digest is
+// computed over (and recomputed by verify). Used by both build and verify.
+export function canonicalImageOf(image) {
+    const { imageDigest: _omit, ...lockSansDigest } = image.lock;
+    return {
+        agentfile: image.agentfile,
+        lock: lockSansDigest,
+        content: image.content,
+    };
+}
+export function computeImageDigest(image) {
+    return sha256Hex(canonicalize(canonicalImageOf(image)));
+}
+/**
+ * Resolve + pin contracts, embed content by hash, validate capabilities, and emit
+ * a content-addressed image. Deterministic: identical inputs → identical
+ * `imageDigest`.
+ */
+export async function buildImage(model, opts) {
+    // 1. Resolve + pin every tool/connection contract.
+    const tools = await resolveLockTools(contractRefs(model), opts.resolver);
+    // 2. Validate the capability profile against the resolved tools (loud).
+    validateCapabilities(model.requires, tools);
+    // 3. Embed content by hash (base64 value + sha256 hash, normalized key).
+    const content = {};
+    const contentHashes = {};
+    for (const path of contentPaths(model)) {
+        const bytes = await opts.readFile(path);
+        const key = normalizeContentKey(path);
+        content[key] = toBase64(bytes);
+        contentHashes[key] = sha256Hex(bytes);
+    }
+    // 4. Pin the harness (bundle + explicit tactics) deterministically.
+    const tactics = {};
+    if (model.harness.bundle !== undefined) {
+        const id = model.harness.bundle;
+        if (opts.resolveBundle !== undefined) {
+            // M6: resolve the bundle ref to a definition and pin its REAL content digest.
+            // The id stays the STABLE Agentfile ref (re-resolved by verify, location floats).
+            const def = await opts.resolveBundle.resolve(id);
+            if (def === null) {
+                throw new Error(`build: dangling bundle ref — "${id}" did not resolve to a bundle definition`);
+            }
+            tactics.bundle = { id, digest: bundleDigest(def) };
+        }
+        else {
+            // Back-compat (every M4 path): keep the sha256Hex(id) placeholder unchanged.
+            tactics.bundle = { id, digest: sha256Hex(id) };
+        }
+    }
+    for (const [seam, id] of Object.entries(model.harness.tactics ?? {})) {
+        tactics[seam] = { id, digest: sha256Hex(id) };
+    }
+    // 5. Assemble the lock (imageDigest filled below) and compute the digest over
+    //    the imageDigest-less canonical image.
+    const lock = {
+        imageDigest: "",
+        model: { id: model.model },
+        content: contentHashes,
+        tools,
+        tactics,
+        capabilities: model.requires,
+    };
+    const image = { agentfile: model, lock, content };
+    image.lock.imageDigest = computeImageDigest(image);
+    return image;
+}
+/** Human-readable resolved intent of an image (what `iris inspect` prints). */
+export function inspectImage(image) {
+    return {
+        name: image.agentfile.name,
+        model: image.agentfile.model,
+        imageDigest: image.lock.imageDigest,
+        tools: image.lock.tools,
+        content: image.lock.content,
+        tactics: image.lock.tactics,
+        capabilities: image.lock.capabilities,
+    };
+}
+// --- OCI image layout (local, files-only — spec §3.5) -------------------------
+// Real registry push/pull (+ cosign) is the manual smoke; this is the install-free
+// path. Shape: `oci-layout` + `index.json` + `blobs/sha256/<hex>`.
+const IRIS_IMAGE_MEDIA_TYPE = "application/vnd.iris.agent.image+json";
+export async function writeOciLayout(dir, image) {
+    const blob = canonicalize(image); // canonical bytes → stable blob
+    const manifestDigest = sha256Hex(blob);
+    await mkdir(join(dir, "blobs", "sha256"), { recursive: true });
+    await writeFile(join(dir, "oci-layout"), JSON.stringify({ imageLayoutVersion: "1.0.0" }));
+    await writeFile(join(dir, "blobs", "sha256", manifestDigest), blob);
+    const index = {
+        schemaVersion: 2,
+        manifests: [
+            {
+                mediaType: IRIS_IMAGE_MEDIA_TYPE,
+                digest: `sha256:${manifestDigest}`,
+                size: Buffer.byteLength(blob),
+                annotations: { "org.opencontainers.image.ref.name": image.lock.imageDigest },
+            },
+        ],
+    };
+    await writeFile(join(dir, "index.json"), JSON.stringify(index, null, 2));
+}
+// Note: the manifest blob's own digest (over the full image, incl. imageDigest) is
+// NOT the imageDigest (computed over the imageDigest-LESS canonical image). Both
+// are internally consistent; the ref.name annotation carries the imageDigest.
+export async function readOciLayout(dir, ref) {
+    const index = JSON.parse(await fsReadFile(join(dir, "index.json"), "utf8"));
+    const manifests = index.manifests ?? [];
+    // Select by ref.name annotation when a ref is given; else the sole manifest.
+    const manifest = ref !== undefined
+        ? manifests.find((m) => m.annotations?.["org.opencontainers.image.ref.name"] === ref)
+        : manifests[0];
+    if (!manifest?.digest) {
+        throw new Error(`readOciLayout: ${ref !== undefined ? `no manifest matching ref "${ref}"` : "no manifest"} in ${join(dir, "index.json")}`);
+    }
+    const digest = manifest.digest.replace(/^sha256:/, "");
+    const blob = await fsReadFile(join(dir, "blobs", "sha256", digest), "utf8");
+    return JSON.parse(blob);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export declare const PACKAGE = "@irisrun/agent";
+export { parseAgentfileJson, validateAgentfile, contentPaths, contractRefs, refScheme, } from "./agentfile.js";
+export type { AgentfileModel, CapabilityProfile, ToolRef, } from "./agentfile.js";
+export { parseAgentfileYaml, parseYamlValue } from "./yaml.js";
+export { AGENTFILE_SCHEMA, agentfileSchemaJson, checkAgainstSchema } from "./schema.js";
+export { makeLocalResolver, refBase } from "./resolver.js";
+export type { RegistryResolver } from "./resolver.js";
+export { resolveLockTools, validateCapabilities } from "./lock.js";
+export type { Lock, LockTool } from "./lock.js";
+export { buildImage, sha256Hex, normalizeContentKey, canonicalImageOf, computeImageDigest, inspectImage, writeOciLayout, readOciLayout, } from "./image.js";
+export type { AgentImage, BuildOptions, ImageInspection } from "./image.js";
+export { verifyImage } from "./verify.js";
+export type { VerifyOptions } from "./verify.js";
+export { bundleDigest } from "./bundle.js";
+export type { BundleDefinition, BundleResolver } from "./bundle.js";
+export { latestRecord, governingDigest, migrateDefinition } from "./pin.js";
+export type { MigrateOptions } from "./pin.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+// @irisrun/agent — public surface (host-side; zero external deps).
+export const PACKAGE = "@irisrun/agent";
+export { parseAgentfileJson, validateAgentfile, contentPaths, contractRefs, refScheme, } from "./agentfile.js";
+export { parseAgentfileYaml, parseYamlValue } from "./yaml.js";
+export { AGENTFILE_SCHEMA, agentfileSchemaJson, checkAgainstSchema } from "./schema.js";
+export { makeLocalResolver, refBase } from "./resolver.js";
+export { resolveLockTools, validateCapabilities } from "./lock.js";
+export { buildImage, sha256Hex, normalizeContentKey, canonicalImageOf, computeImageDigest, inspectImage, writeOciLayout, readOciLayout, } from "./image.js";
+export { verifyImage } from "./verify.js";
+export { bundleDigest } from "./bundle.js";
+export { latestRecord, governingDigest, migrateDefinition } from "./pin.js";

package/dist/lock.d.ts

@@ -0,0 +1,39 @@
+import { type ToolContract } from "@irisrun/tools";
+import type { CapabilityProfile, ToolRef } from "./agentfile.js";
+import type { RegistryResolver } from "./resolver.js";
+export interface LockTool {
+    name: string;
+    ref: string;
+    contractDigest: string;
+    transport: "mcp" | "grpc" | "subprocess";
+    location: string;
+    retrySafe: boolean;
+}
+export interface Lock {
+    imageDigest: string;
+    model: {
+        id: string;
+        digest?: string;
+    };
+    content: Record<string, string>;
+    tools: LockTool[];
+    tactics: Record<string, {
+        id: string;
+        digest: string;
+    }>;
+    capabilities: CapabilityProfile;
+}
+/**
+ * Resolve each ref to a concrete contract and pin it. A ref that resolves to
+ * nothing → loud dangling-ref error; a resolver returning an `in-process`
+ * contract for an Agentfile ref → loud reject (in-process is not authorable, so
+ * the lock's `mcp|grpc|subprocess` union stays sound).
+ */
+export declare function resolveLockTools(refs: ToolRef[], resolver: RegistryResolver): Promise<LockTool[]>;
+/**
+ * Validate the capability profile against the resolved tools (spec §3.3 step 4),
+ * loudly (no silent inconsistency): a `remote` locality forbids subprocess tools,
+ * and any subprocess tool requires `local_subprocess: true`.
+ */
+export declare function validateCapabilities(requires: CapabilityProfile, tools: LockTool[]): void;
+export type { ToolContract };

package/dist/lock.js

@@ -0,0 +1,46 @@
+// The lockfile (spec §3.4) — pins model + tools/connections (by contractDigest) +
+// tactics + capabilities + the embedded content hashes. `imageDigest` is filled by
+// the image build (§3.5). This module owns the tool-resolution + pinning + the
+// capability validation; Task 4 completes content/model/tactics. Host-side.
+import { contractDigest } from "@irisrun/tools";
+/**
+ * Resolve each ref to a concrete contract and pin it. A ref that resolves to
+ * nothing → loud dangling-ref error; a resolver returning an `in-process`
+ * contract for an Agentfile ref → loud reject (in-process is not authorable, so
+ * the lock's `mcp|grpc|subprocess` union stays sound).
+ */
+export async function resolveLockTools(refs, resolver) {
+    const out = [];
+    for (const { ref } of refs) {
+        const contract = await resolver.resolve(ref);
+        if (contract === null) {
+            throw new Error(`build: dangling tool ref — "${ref}" did not resolve to a contract`);
+        }
+        if (contract.transport === "in-process") {
+            throw new Error(`build: tool ref "${ref}" resolved to an in-process contract, which is not authorable in an Agentfile (use mcp/grpc/subprocess)`);
+        }
+        out.push({
+            name: contract.name,
+            ref, // the stable registry handle — re-resolved by verify (location floats)
+            contractDigest: contractDigest(contract),
+            transport: contract.transport,
+            location: contract.location,
+            retrySafe: contract.retrySafe,
+        });
+    }
+    return out;
+}
+/**
+ * Validate the capability profile against the resolved tools (spec §3.3 step 4),
+ * loudly (no silent inconsistency): a `remote` locality forbids subprocess tools,
+ * and any subprocess tool requires `local_subprocess: true`.
+ */
+export function validateCapabilities(requires, tools) {
+    const hasSubprocess = tools.some((t) => t.transport === "subprocess");
+    if (requires.tool_locality === "remote" && hasSubprocess) {
+        throw new Error(`build: capability profile is inconsistent — tool_locality "remote" forbids subprocess:// tools`);
+    }
+    if (hasSubprocess && requires.local_subprocess !== true) {
+        throw new Error(`build: a subprocess:// tool requires the "local_subprocess" capability, but requires.local_subprocess is not true`);
+    }
+}

package/dist/pin.d.ts

@@ -0,0 +1,32 @@
+import type { StateStore, JournalRecord } from "@irisrun/core";
+/**
+ * The latest journal record, read SNAPSHOT-SAFELY. After a snapshot the journal
+ * holds only `seq > snapshotSeq`; the terminal `wait`/`finish` marker is committed
+ * after the snapshot seq (the engine snapshots only in the effect branch), so it
+ * always survives `truncateJournal`. Mirrors the engine's recovery read offset.
+ * Returns null for a never-started session (empty journal + no snapshot).
+ */
+export declare function latestRecord(store: StateStore, sessionId: string): Promise<JournalRecord | null>;
+/**
+ * The governing image digest a session is pinned to = the `defDigest` of its
+ * latest journal record. `null` ⇒ a never-started session → the caller adopts the
+ * run layout's imageDigest as the birth pin. A LIVE session re-runs under its own
+ * governing digest, so a redeploy (a new image digest) does not change its pin.
+ */
+export declare function governingDigest(store: StateStore, sessionId: string): Promise<string | null>;
+export interface MigrateOptions {
+    from: string;
+    to: string;
+    holderId?: string;
+    now?: number;
+}
+/**
+ * Migrate a LIVE session's pinned definition `from`→`to` at a turn boundary
+ * (ADR-0004 hold-and-migrate). Appends an `upgraded {from,to,atTurn}` marker
+ * stamped with `defDigest: to`; subsequent turns run with `defDigest = to`. Refuses
+ * LOUDLY when the session has not started, is mid-turn, or its governing digest is
+ * not `from`. `atTurn` = the boundary journal sequence (the engine emits no
+ * turn-start marker to count). Reference impl: core `migrateSession` (the
+ * acquireLease → snapshot-aware seq → fenced append pattern). engine.ts untouched.
+ */
+export declare function migrateDefinition(store: StateStore, sessionId: string, opts: MigrateOptions): Promise<void>;

package/dist/pin.js

@@ -0,0 +1,77 @@
+// Session pinning + definition migration (spec §3.7, ADR-0002/0004) — ZERO engine
+// change. A session pins the image digest as its governing `defDigest` (the engine
+// already stamps every record). Pinning/migration ride the EXISTING per-record
+// defDigest + the `upgraded` marker; this module uses only the StateStore port +
+// journal types + the lease. Host-side.
+import { acquireLease, releaseLease, encode, decode } from "@irisrun/core";
+/**
+ * The latest journal record, read SNAPSHOT-SAFELY. After a snapshot the journal
+ * holds only `seq > snapshotSeq`; the terminal `wait`/`finish` marker is committed
+ * after the snapshot seq (the engine snapshots only in the effect branch), so it
+ * always survives `truncateJournal`. Mirrors the engine's recovery read offset.
+ * Returns null for a never-started session (empty journal + no snapshot).
+ */
+export async function latestRecord(store, sessionId) {
+    const snap = await store.readLatestSnapshot(sessionId);
+    const tail = await store.readJournal(sessionId, (snap?.upToSeq ?? -1) + 1);
+    const row = tail.at(-1);
+    return row ? decode(row.bytes) : null;
+}
+/**
+ * The governing image digest a session is pinned to = the `defDigest` of its
+ * latest journal record. `null` ⇒ a never-started session → the caller adopts the
+ * run layout's imageDigest as the birth pin. A LIVE session re-runs under its own
+ * governing digest, so a redeploy (a new image digest) does not change its pin.
+ */
+export async function governingDigest(store, sessionId) {
+    const last = await latestRecord(store, sessionId);
+    return last ? last.defDigest : null;
+}
+// Markers that mark a turn boundary (the engine emits these; `turn_started` is
+// intentionally NOT used — the engine never emits it).
+const TURN_TERMINAL_MARKERS = new Set(["wait", "finish"]);
+/**
+ * Migrate a LIVE session's pinned definition `from`→`to` at a turn boundary
+ * (ADR-0004 hold-and-migrate). Appends an `upgraded {from,to,atTurn}` marker
+ * stamped with `defDigest: to`; subsequent turns run with `defDigest = to`. Refuses
+ * LOUDLY when the session has not started, is mid-turn, or its governing digest is
+ * not `from`. `atTurn` = the boundary journal sequence (the engine emits no
+ * turn-start marker to count). Reference impl: core `migrateSession` (the
+ * acquireLease → snapshot-aware seq → fenced append pattern). engine.ts untouched.
+ */
+export async function migrateDefinition(store, sessionId, opts) {
+    const holderId = opts.holderId ?? "migrator";
+    const lease = await acquireLease(store, sessionId, holderId);
+    if (!lease.ok) {
+        throw new Error(`migrateDefinition: could not acquire lease for '${sessionId}' (contended, current ${lease.current})`);
+    }
+    const fence = lease.fence;
+    try {
+        const last = await latestRecord(store, sessionId);
+        if (last === null) {
+            throw new Error(`migrateDefinition: cannot migrate '${sessionId}' — it has not started (no journal)`);
+        }
+        const marker = last.kind === "marker" ? last.payload.marker : undefined;
+        if (last.kind !== "marker" || marker === undefined || !TURN_TERMINAL_MARKERS.has(marker)) {
+            throw new Error(`migrateDefinition: '${sessionId}' is not at a turn boundary (latest record is ${last.kind}${marker ? `/${marker}` : ""}) — migrate only between turns`);
+        }
+        if (last.defDigest !== opts.from) {
+            throw new Error(`migrateDefinition: '${sessionId}' governing digest is ${last.defDigest}, not the expected from=${opts.from}`);
+        }
+        const nextSeq = last.seq + 1;
+        const record = {
+            seq: nextSeq,
+            ts: opts.now ?? 0, // reducers MUST NOT read ts (determinism contract)
+            defDigest: opts.to,
+            kind: "marker",
+            payload: { marker: "upgraded", from: opts.from, to: opts.to, atTurn: nextSeq },
+        };
+        const res = await store.append(sessionId, nextSeq, [encode(record)], fence);
+        if (!res.ok) {
+            throw new Error(`migrateDefinition: append failed at seq ${nextSeq} (${res.reason})`);
+        }
+    }
+    finally {
+        await releaseLease(store, sessionId, fence);
+    }
+}

package/dist/resolver.d.ts

@@ -0,0 +1,12 @@
+import type { ToolContract } from "@irisrun/tools";
+export interface RegistryResolver {
+    resolve(ref: string): Promise<ToolContract | null>;
+}
+/** Strip a trailing `@<range>` from a ref, e.g. `mcp://r/x@^2` → `mcp://r/x`. */
+export declare function refBase(ref: string): string;
+/**
+ * A resolver over an in-memory `refBase → ToolContract` map (install-free). Both
+ * `mcp://r/x@^2` and `mcp://r/x@^3` resolve via the shared base `mcp://r/x`,
+ * modelling "pin the contract, float the implementation" (ADR-0004).
+ */
+export declare function makeLocalResolver(map: Record<string, ToolContract>): RegistryResolver;

package/dist/resolver.js

@@ -0,0 +1,16 @@
+/** Strip a trailing `@<range>` from a ref, e.g. `mcp://r/x@^2` → `mcp://r/x`. */
+export function refBase(ref) {
+    const at = ref.lastIndexOf("@");
+    const scheme = ref.indexOf("://");
+    return scheme >= 0 && at > scheme + 2 ? ref.slice(0, at) : ref;
+}
+/**
+ * A resolver over an in-memory `refBase → ToolContract` map (install-free). Both
+ * `mcp://r/x@^2` and `mcp://r/x@^3` resolve via the shared base `mcp://r/x`,
+ * modelling "pin the contract, float the implementation" (ADR-0004).
+ */
+export function makeLocalResolver(map) {
+    return {
+        resolve: (ref) => Promise.resolve(map[refBase(ref)] ?? map[ref] ?? null),
+    };
+}

package/dist/schema.d.ts

@@ -0,0 +1,11 @@
+export declare const AGENTFILE_SCHEMA: {
+    [k: string]: unknown;
+};
+/** Canonical pretty-printed JSON text of the schema (e.g. `iris schema > file`). */
+export declare function agentfileSchemaJson(): string;
+/**
+ * Validate a value against the Agentfile schema. Returns a list of
+ * "path: message" errors (empty ⇒ valid). NEVER throws on a malformed instance
+ * (only a malformed *schema*, which is this file's own code, could throw).
+ */
+export declare function checkAgainstSchema(value: unknown): string[];

package/dist/schema.js

@@ -0,0 +1,238 @@
+// The PUBLISHED Agentfile schema (JSON Schema draft 2020-12) + a zero-dep
+// checker that interprets it. The schema is a SECOND surface over the same
+// contract `validateAgentfile` (agentfile.ts) enforces — the two are pinned to
+// agree by a shared conformance corpus (tests/agentfile-schema.test.ts), so a
+// published schema can never silently drift from the runtime validator (the
+// provider-adapter "one shared conformance suite" idea applied to validation).
+//
+// Why a hand-rolled checker instead of an off-the-shelf JSON-Schema lib: the
+// repo is zero-runtime-deps. `checkAgainstSchema` interprets ONLY the keyword
+// subset this schema uses (documented in `validateNode`), so the schema stays
+// executable in-repo and by any consumer that vendors this file. Host-side.
+// The schema is intentionally LENIENT on unknown keys (`additionalProperties:
+// true` at every level) to match the runtime validator, which ignores unknown
+// keys (forward-compat: a future Agentfile field must not fail an old schema).
+// The closed constraints are exactly what `validateAgentfile` enforces.
+export const AGENTFILE_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://iris.run/schema/agentfile/v1.json",
+    title: "Iris Agentfile (iris/v1, kind Agent)",
+    description: "An Iris Agentfile: a declarative RECIPE that references content (embedded by hash) and tool/connection contracts (pinned by digest). It carries NO executable behavior (ADR-0005).",
+    type: "object",
+    required: [
+        "apiVersion",
+        "kind",
+        "name",
+        "model",
+        "instructions",
+        "skills",
+        "tools",
+        "connections",
+        "sandbox",
+    ],
+    properties: {
+        $schema: {
+            type: "string",
+            description: "Optional editor/CI schema URI. Ignored by Iris — dropped from the parsed model, so it never affects the image digest.",
+        },
+        apiVersion: { const: "iris/v1", description: 'Schema version. Must be "iris/v1".' },
+        kind: { const: "Agent", description: 'Resource kind. Must be "Agent".' },
+        name: { type: "string", minLength: 1, description: "Agent name (non-empty)." },
+        model: {
+            type: "string",
+            minLength: 1,
+            description: 'Provider-prefixed model id, e.g. "anthropic/claude-x".',
+        },
+        instructions: {
+            type: "string",
+            minLength: 1,
+            description: "Path to the instructions file — CONTENT, embedded by hash.",
+        },
+        skills: {
+            type: "array",
+            items: { type: "string" },
+            description: "Paths to skill files — CONTENT, embedded by hash.",
+        },
+        tools: {
+            type: "array",
+            items: { $ref: "#/$defs/contractRef" },
+            description: "Tool CONTRACT refs (mcp/grpc/subprocess), pinned by digest.",
+        },
+        connections: {
+            type: "array",
+            items: { $ref: "#/$defs/contractRef" },
+            description: "Connection CONTRACT refs (mcp/grpc/subprocess), pinned by digest.",
+        },
+        harness: { $ref: "#/$defs/harness" },
+        requires: { $ref: "#/$defs/capabilityProfile" },
+        sandbox: { $ref: "#/$defs/sandbox" },
+    },
+    additionalProperties: true,
+    $defs: {
+        contractRef: {
+            type: "object",
+            required: ["ref"],
+            properties: {
+                ref: {
+                    type: "string",
+                    minLength: 1,
+                    pattern: "^(mcp|grpc|subprocess)://",
+                    description: "Contract ref. Scheme must be mcp, grpc, or subprocess.",
+                },
+                // ADR-0005: a tool/connection is a contract referenced by digest, never
+                // inlined code. A present code/script/source field validates against the
+                // boolean `false` subschema → rejected.
+                code: false,
+                script: false,
+                source: false,
+            },
+            additionalProperties: true,
+        },
+        capabilityProfile: {
+            type: "object",
+            properties: {
+                long_running: { type: "boolean" },
+                local_subprocess: { type: "boolean" },
+                filesystem: { type: "boolean" },
+                websockets: { type: "boolean" },
+                tool_locality: {
+                    enum: ["in-process", "local", "remote"],
+                    description: "Where tools run. One of in-process, local, remote.",
+                },
+            },
+            additionalProperties: true,
+        },
+        sandbox: {
+            type: "object",
+            required: ["backend", "network"],
+            properties: {
+                backend: { type: "string", minLength: 1 },
+                network: { type: "string", minLength: 1 },
+                workspace: {
+                    type: "string",
+                    description: "Optional workspace path — CONTENT, embedded by hash.",
+                },
+            },
+            additionalProperties: true,
+        },
+        harness: {
+            type: "object",
+            properties: {
+                bundle: { type: "string" },
+                tactics: { type: "object" },
+            },
+            additionalProperties: true,
+        },
+    },
+};
+/** Canonical pretty-printed JSON text of the schema (e.g. `iris schema > file`). */
+export function agentfileSchemaJson() {
+    return JSON.stringify(AGENTFILE_SCHEMA, null, 2);
+}
+/**
+ * Validate a value against the Agentfile schema. Returns a list of
+ * "path: message" errors (empty ⇒ valid). NEVER throws on a malformed instance
+ * (only a malformed *schema*, which is this file's own code, could throw).
+ */
+export function checkAgainstSchema(value) {
+    const errors = [];
+    validateNode(value, AGENTFILE_SCHEMA, "", errors);
+    return errors;
+}
+// The supported JSON-Schema subset: boolean subschemas (true/false), `$ref`
+// (only "#/$defs/<name>"), `type` (string|boolean|number|integer|array|object),
+// `const`, `enum`, `minLength`, `pattern` (compiled with `new RegExp(pattern)` —
+// DEFAULT flags only, so `^` anchors to string-start, matching refScheme), plus
+// `required`, `properties`, and `items`. Unknown keys are NOT constrained (the
+// schema is `additionalProperties: true` everywhere by design); any other schema
+// keyword is ignored.
+function validateNode(value, schema, path, errors) {
+    if (schema === true)
+        return;
+    if (schema === false) {
+        errors.push(`${path || "(root)"}: not allowed`);
+        return;
+    }
+    if (typeof schema.$ref === "string") {
+        const resolved = resolveRef(schema.$ref);
+        validateNode(value, resolved, path, errors);
+        return;
+    }
+    // `const` / `enum` apply regardless of type.
+    if ("const" in schema && value !== schema.const) {
+        errors.push(`${path || "(root)"}: must equal ${JSON.stringify(schema.const)}`);
+        return;
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        errors.push(`${path || "(root)"}: must be one of ${JSON.stringify(schema.enum)}`);
+        return;
+    }
+    if (typeof schema.type === "string" && !typeMatches(value, schema.type)) {
+        errors.push(`${path || "(root)"}: must be of type ${schema.type}`);
+        return; // stop — deeper keywords assume the type holds
+    }
+    if (typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            errors.push(`${path || "(root)"}: must be a non-empty string`);
+        }
+        if (typeof schema.pattern === "string" && !new RegExp(schema.pattern).test(value)) {
+            errors.push(`${path || "(root)"}: must match ${schema.pattern}`);
+        }
+    }
+    if (Array.isArray(value) && schema.items !== undefined) {
+        value.forEach((item, i) => validateNode(item, schema.items, `${path}[${i}]`, errors));
+    }
+    if (isPlainObject(value)) {
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (!(key in value))
+                    errors.push(`${joinPath(path, key)}: required (missing)`);
+            }
+        }
+        // Validate only PRESENT, KNOWN properties. The Agentfile schema is
+        // `additionalProperties: true` at every level by design (forward-compat,
+        // matching the runtime's lenient-on-unknown-keys behavior), so unknown keys
+        // are intentionally not constrained.
+        const props = isPlainObject(schema.properties) ? schema.properties : undefined;
+        if (props) {
+            for (const key of Object.keys(value)) {
+                if (key in props)
+                    validateNode(value[key], props[key], joinPath(path, key), errors);
+            }
+        }
+    }
+}
+function resolveRef(ref) {
+    const prefix = "#/$defs/";
+    if (!ref.startsWith(prefix))
+        throw new Error(`Agentfile schema: unsupported $ref "${ref}"`);
+    const defs = AGENTFILE_SCHEMA.$defs;
+    const node = defs?.[ref.slice(prefix.length)];
+    if (node === undefined)
+        throw new Error(`Agentfile schema: unknown $ref "${ref}"`);
+    return node;
+}
+function typeMatches(value, type) {
+    switch (type) {
+        case "object":
+            return isPlainObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return Number.isInteger(value);
+        default:
+            return true; // unknown type keyword — do not constrain
+    }
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function joinPath(path, key) {
+    return path === "" ? key : `${path}.${key}`;
+}

package/dist/verify.d.ts

@@ -0,0 +1,8 @@
+import { type AgentImage } from "./image.js";
+import type { RegistryResolver } from "./resolver.js";
+import { type BundleResolver } from "./bundle.js";
+export interface VerifyOptions {
+    resolver: RegistryResolver;
+    resolveBundle?: BundleResolver;
+}
+export declare function verifyImage(image: AgentImage, opts: VerifyOptions): Promise<void>;

package/dist/verify.js

@@ -0,0 +1,58 @@
+// Integrity verification (spec §3.6, ADR-0006 §4) — throws LOUDLY on any failure
+// (no silent corruption, [[lrn-no-silent-policy-widening]]). Checks, in order:
+// (1) every embedded content hash matches its bytes; (2) every tool contractDigest
+// is still resolvable + unchanged; (3) the recomputed imageDigest equals the
+// stored one (recompute strips the self-referential field, exactly as build does).
+// Host-side.
+import { contractDigest } from "@irisrun/tools";
+import { sha256Hex, computeImageDigest } from "./image.js";
+import { bundleDigest } from "./bundle.js";
+export async function verifyImage(image, opts) {
+    // 1. content hashes match the embedded bytes
+    for (const [path, hash] of Object.entries(image.lock.content)) {
+        const b64 = image.content[path];
+        if (b64 === undefined) {
+            throw new Error(`verify: content "${path}" is recorded in the lock but missing from the image`);
+        }
+        const actual = sha256Hex(Buffer.from(b64, "base64"));
+        if (actual !== hash) {
+            throw new Error(`verify: content hash mismatch for "${path}" — lock ${hash}, actual ${actual}`);
+        }
+    }
+    // 2. every tool contract is still resolvable (BY ITS STABLE ref — not location,
+    //    which floats per ADR-0004) and its digest unchanged
+    for (const tool of image.lock.tools) {
+        const contract = await opts.resolver.resolve(tool.ref);
+        if (contract === null) {
+            throw new Error(`verify: dangling tool — "${tool.name}" (${tool.ref}) is no longer resolvable`);
+        }
+        const digest = contractDigest(contract);
+        if (digest !== tool.contractDigest) {
+            throw new Error(`verify: contractDigest changed for "${tool.name}" — lock ${tool.contractDigest}, resolved ${digest}`);
+        }
+    }
+    // 3. recomputed imageDigest equals the stored one (computeImageDigest strips the
+    //    self-referential imageDigest field, exactly as buildImage does)
+    const recomputed = computeImageDigest(image);
+    if (recomputed !== image.lock.imageDigest) {
+        throw new Error(`verify: imageDigest mismatch — stored ${image.lock.imageDigest}, recomputed ${recomputed}`);
+    }
+    // 4. (M6, NET-NEW) re-resolve the pinned tactic bundle by its STABLE id/ref (NOT
+    //    a floating location, ADR-0004), recompute bundleDigest, and assert it equals
+    //    the pinned digest. This catches a CONTENT-tampered bundle whose pinned lock
+    //    digest is left unchanged — invisible to the imageDigest check above. Skipped
+    //    entirely when no resolveBundle is injected (M4 back-compat).
+    if (opts.resolveBundle !== undefined) {
+        const pinned = image.lock.tactics.bundle;
+        if (pinned !== undefined) {
+            const def = await opts.resolveBundle.resolve(pinned.id);
+            if (def === null) {
+                throw new Error(`verify: dangling tactic bundle — "${pinned.id}" is no longer resolvable`);
+            }
+            const digest = bundleDigest(def);
+            if (digest !== pinned.digest) {
+                throw new Error(`verify: bundle digest changed for "${pinned.id}" — lock ${pinned.digest}, resolved ${digest}`);
+            }
+        }
+    }
+}

package/dist/yaml.d.ts

@@ -0,0 +1,6 @@
+import type { Json } from "@irisrun/core";
+import { type AgentfileModel } from "./agentfile.js";
+/** Parse a YAML-subset Agentfile into a validated model (throws loudly on bad/unsupported YAML). */
+export declare function parseAgentfileYaml(text: string): AgentfileModel;
+/** Parse the YAML-subset into a plain JSON value (the raw, pre-validation tree). */
+export declare function parseYamlValue(text: string): Json;

package/dist/yaml.js

@@ -0,0 +1,148 @@
+import { validateAgentfile } from "./agentfile.js";
+/** Parse a YAML-subset Agentfile into a validated model (throws loudly on bad/unsupported YAML). */
+export function parseAgentfileYaml(text) {
+    return validateAgentfile(parseYamlValue(text));
+}
+/** Parse the YAML-subset into a plain JSON value (the raw, pre-validation tree). */
+export function parseYamlValue(text) {
+    const lines = lex(text);
+    if (lines.length === 0)
+        return {};
+    const [value, next] = parseBlock(lines, 0, lines[0].indent);
+    if (next !== lines.length) {
+        throw new Error(`Agentfile YAML: unexpected indentation at line ${lines[next].lineNo}`);
+    }
+    return value;
+}
+// Tokenize: strip comments + blank lines, reject unsupported constructs, record indent.
+function lex(text) {
+    const out = [];
+    const rawLines = text.split("\n");
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = rawLines[i];
+        const lineNo = i + 1;
+        if (raw.trim() === "")
+            continue;
+        if (raw.trimStart().startsWith("#"))
+            continue; // full-line comment
+        if (raw.trimStart().startsWith("---") || raw.trimStart().startsWith("...")) {
+            throw new Error(`Agentfile YAML: multi-document markers are unsupported (line ${lineNo})`);
+        }
+        const indentMatch = raw.match(/^[ \t]*/)[0];
+        if (indentMatch.includes("\t")) {
+            throw new Error(`Agentfile YAML: tab indentation is unsupported — use spaces (line ${lineNo})`);
+        }
+        const indent = indentMatch.length;
+        const content = stripInlineComment(raw.slice(indent)).trimEnd();
+        if (content === "")
+            continue;
+        out.push({ indent, content, lineNo });
+    }
+    return out;
+}
+// Strip a trailing ` # comment` — QUOTE-AWARE so a quoted value containing ` #`
+// (e.g. `name: 'a #b'`) is never truncated, and `mcp://`/`subprocess://` values
+// (no whitespace before `#`) are never affected. Cuts at the first `#` that is
+// preceded by whitespace AND outside a quoted span.
+function stripInlineComment(s) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (c === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (c === "#" && !inSingle && !inDouble && i > 0 && /\s/.test(s[i - 1])) {
+            return s.slice(0, i);
+        }
+    }
+    return s;
+}
+// Parse a block (map or sequence) at `indent`, starting at line `i`.
+function parseBlock(lines, i, indent) {
+    if (lines[i].content.startsWith("- "))
+        return parseSeq(lines, i, indent);
+    return parseMap(lines, i, indent);
+}
+function parseMap(lines, i, indent) {
+    const obj = {};
+    while (i < lines.length && lines[i].indent === indent) {
+        const line = lines[i];
+        if (line.content.startsWith("- ")) {
+            throw new Error(`Agentfile YAML: unexpected sequence item in a map (line ${line.lineNo})`);
+        }
+        const colon = line.content.indexOf(":");
+        if (colon < 0) {
+            throw new Error(`Agentfile YAML: expected "key: value" (line ${line.lineNo})`);
+        }
+        const key = line.content.slice(0, colon).trim();
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            throw new Error(`Agentfile YAML: duplicate key "${key}" (line ${line.lineNo})`);
+        }
+        const rest = line.content.slice(colon + 1).trim();
+        if (rest === "") {
+            // a nested block on the following deeper-indented lines
+            if (i + 1 < lines.length && lines[i + 1].indent > indent) {
+                const [child, next] = parseBlock(lines, i + 1, lines[i + 1].indent);
+                obj[key] = child;
+                i = next;
+            }
+            else {
+                obj[key] = null; // empty block
+                i++;
+            }
+        }
+        else {
+            obj[key] = parseScalar(rest, line.lineNo);
+            i++;
+        }
+    }
+    return [obj, i];
+}
+function parseSeq(lines, i, indent) {
+    const arr = [];
+    while (i < lines.length && lines[i].indent === indent && lines[i].content.startsWith("- ")) {
+        const line = lines[i];
+        const item = line.content.slice(2).trim();
+        const colon = item.indexOf(":");
+        if (colon > 0 && !looksScalar(item)) {
+            // inline single-key map, e.g. "- ref: mcp://..."
+            const key = item.slice(0, colon).trim();
+            const val = item.slice(colon + 1).trim();
+            arr.push({ [key]: parseScalar(val, line.lineNo) });
+        }
+        else {
+            arr.push(parseScalar(item, line.lineNo));
+        }
+        i++;
+    }
+    return [arr, i];
+}
+// A bare scalar item in a sequence (no "key:" map shape). True when there is no
+// top-level colon-space that would indicate an inline map.
+function looksScalar(item) {
+    return !/^[A-Za-z0-9_.-]+:\s/.test(item) && !/^[A-Za-z0-9_.-]+:$/.test(item);
+}
+function parseScalar(s, lineNo) {
+    if (s.startsWith("[") || s.startsWith("{")) {
+        throw new Error(`Agentfile YAML: flow collections ([..]/{..}) are unsupported (line ${lineNo})`);
+    }
+    if (s.startsWith("&") || s.startsWith("*")) {
+        throw new Error(`Agentfile YAML: anchors/aliases (&/*) are unsupported (line ${lineNo})`);
+    }
+    if (s === "true")
+        return true;
+    if (s === "false")
+        return false;
+    if (s === "null" || s === "~")
+        return null;
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    if (/^-?\d+$/.test(s))
+        return Number.parseInt(s, 10);
+    if (/^-?\d*\.\d+$/.test(s))
+        return Number.parseFloat(s);
+    return s;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@irisrun/agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Iris agent image toolchain — Agentfile model + parsers, builder (resolve/embed/pin/validate), content-addressed inspectable image + OCI layout, lockfile, integrity verify, and session pinning + definition migration. Host-side, zero external deps.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.1.0",
+    "@irisrun/tools": "^0.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/agent"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}