@eir-labs/coltrane 0.14.8 → 0.15.0

package/dist/src/genome_schema.d.ts

@@ -231,10 +231,337 @@ export declare const SkillSchema: z.ZodObject<{
     fixtures?: unknown[] | undefined;
     md?: string | undefined;
 }>;
-export declare const AgentSchema: z.ZodObject<{
+export declare const AgentObjectSchema: z.ZodObject<{
     slug: z.ZodString;
     primitives: z.ZodReadonly<z.ZodArray<z.ZodEnum<["SENSE", "INTERPRET", "JUDGE", "PLAN", "CREATE", "VERIFY"]>, "many">>;
     input_types: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    /** The inputs this agent CANNOT WORK WITHOUT in ANY placement — the per-agent MANDATE that
+     *  `input_types` (the capability ENVELOPE: what the agent CAN consume across all roles) cannot
+     *  express. `composeStandard` refuses a chair whose `input_contract` omits any of these, because
+     *  that placement would run the agent's method against an input that never arrives. Every entry
+     *  MUST also appear in `input_types` — an agent cannot REQUIRE an input outside its own envelope;
+     *  the cross-field rule on `AgentSchema` (the `.superRefine` below) enforces that at PARSE.
+     *
+     *  OPTIONAL with NO default — deliberately, exactly like `turn_budget`/`tier`. A `.default([])`
+     *  would make the field non-optional on the `Agent` output type (breaking hand-rolled `Agent`
+     *  literals such as `tests/genome_write_roundtrip.test.ts`'s `sensor`) and would ADD
+     *  `required_inputs: []` to every existing agent on write-back, breaking byte-equivalent round-trip.
+     *  Absent stays absent; a Zod object drops an undeclared key, so the field must be declared HERE to
+     *  be retained. */
+    required_inputs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    output_types: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    domain: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    identity: z.ZodString;
+    method: z.ZodString;
+    constraints: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    behavioral_primitives: z.ZodReadonly<z.ZodTuple<[z.ZodEnum<["explorer", "analyst", "critic", "synthesizer", "planner", "executor", "audience_modeler"]>, z.ZodEnum<["explorer", "analyst", "critic", "synthesizer", "planner", "executor", "audience_modeler"]>], null>>;
+    allowed_tools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    disallowed_tools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    /** REFERENCES into the shared repertoire (`skills/<slug>/`): the off-the-shelf method, bound by
+     *  name, resolved against the genome's skills map at run time. A slug that resolves to no
+     *  package is a dangling binding (loader) and a dead name when a chair requires it (runtime). */
+    skill_slugs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    /** The agent's OWN skills, carried on its record rather than referenced by name.
+     *
+     *  An agent is the thing closest to its own work, so it is the agent that grows technique — and
+     *  grown technique has to be portable: the same player seated in a second institution brings its
+     *  method along instead of waiting for that institution's repertoire to contain it. Institution
+     *  data never rides along; a carried skill declares `hydration` slots and the seating fills them.
+     *
+     *  Relationship to `skill_slugs`: slugs name the SHARED repertoire, `skills` are the agent's own.
+     *  Resolution unions the two, carried-first, so a carried definition SHADOWS a same-slug
+     *  repertoire package (the player's own technique is the one that plays) and a slug covered by a
+     *  carried definition is not a dangling binding. */
+    skills: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        version: z.ZodOptional<z.ZodNumber>;
+        skill_type: z.ZodOptional<z.ZodString>;
+        input_type: z.ZodOptional<z.ZodString>;
+        output_type: z.ZodOptional<z.ZodString>;
+        corpus: z.ZodOptional<z.ZodString>;
+        determinism_ratio: z.ZodOptional<z.ZodNumber>;
+        permission: z.ZodOptional<z.ZodObject<{
+            tier: z.ZodOptional<z.ZodNumber>;
+            network: z.ZodOptional<z.ZodObject<{
+                allow: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+                methods: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+                max_requests: z.ZodOptional<z.ZodNumber>;
+                max_bytes: z.ZodOptional<z.ZodNumber>;
+            }, "strip", z.ZodTypeAny, {
+                allow: string[];
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            }, {
+                allow?: string[] | undefined;
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            tier?: number | undefined;
+            network?: {
+                allow: string[];
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        }, {
+            tier?: number | undefined;
+            network?: {
+                allow?: string[] | undefined;
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        /** Slot name → the declared shape of what fills it. See HydrationSlotSchema: the method is the
+         *  agent's, the slot data is the institution's (or the gig's). */
+        hydration: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            binding: z.ZodOptional<z.ZodEnum<["institution", "gig"]>>;
+        }, "strip", z.ZodTypeAny, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }>>>;
+        fixtures: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+        code: z.ZodOptional<z.ZodString>;
+        md: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow: string[];
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }, {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow?: string[] | undefined;
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }>, "many">>>;
+    model_tier: z.ZodOptional<z.ZodEnum<["economy", "standard", "premium"]>>;
+    max_tool_calls: z.ZodOptional<z.ZodNumber>;
+    max_token_budget: z.ZodOptional<z.ZodNumber>;
+    code_tool_access: z.ZodOptional<z.ZodEnum<["none", "read", "write", "full"]>>;
+    depth_profile: z.ZodOptional<z.ZodEnum<["skim", "quick", "standard", "deep"]>>;
+    browser_grant: z.ZodOptional<z.ZodObject<{
+        allowed_origins: z.ZodArray<z.ZodString, "many">;
+        blocked_origins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        trace_dir: z.ZodOptional<z.ZodString>;
+        isolated: z.ZodOptional<z.ZodBoolean>;
+        headless: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    }, {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    primitives: readonly ("SENSE" | "INTERPRET" | "JUDGE" | "PLAN" | "CREATE" | "VERIFY")[];
+    input_types: readonly string[];
+    output_types: readonly string[];
+    domain: string | null;
+    identity: string;
+    method: string;
+    constraints: readonly string[];
+    behavioral_primitives: readonly ["explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler", "explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler"];
+    depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
+    allowed_tools?: readonly string[] | undefined;
+    disallowed_tools?: readonly string[] | undefined;
+    skill_slugs?: readonly string[] | undefined;
+    skills?: readonly {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow: string[];
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }[] | undefined;
+    model_tier?: "standard" | "economy" | "premium" | undefined;
+    max_tool_calls?: number | undefined;
+    max_token_budget?: number | undefined;
+    code_tool_access?: "none" | "read" | "write" | "full" | undefined;
+    browser_grant?: {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    } | undefined;
+}, {
+    slug: string;
+    primitives: readonly ("SENSE" | "INTERPRET" | "JUDGE" | "PLAN" | "CREATE" | "VERIFY")[];
+    identity: string;
+    method: string;
+    constraints: readonly string[];
+    behavioral_primitives: readonly ["explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler", "explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler"];
+    input_types?: readonly string[] | undefined;
+    output_types?: readonly string[] | undefined;
+    domain?: string | null | undefined;
+    depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
+    allowed_tools?: readonly string[] | undefined;
+    disallowed_tools?: readonly string[] | undefined;
+    skill_slugs?: readonly string[] | undefined;
+    skills?: readonly {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow?: string[] | undefined;
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }[] | undefined;
+    model_tier?: "standard" | "economy" | "premium" | undefined;
+    max_tool_calls?: number | undefined;
+    max_token_budget?: number | undefined;
+    code_tool_access?: "none" | "read" | "write" | "full" | undefined;
+    browser_grant?: {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    } | undefined;
+}>;
+/**
+ * The agent AUTHORING/parse surface: the plain `AgentObjectSchema` plus the one cross-field rule a
+ * single field cannot state — every `required_inputs` entry must also be an `input_types` entry.
+ *
+ * Mirrors the `VenueSchema` / `VenueObjectSchema` split below. The inner `AgentObjectSchema` is a
+ * plain `ZodObject`, so it retains `.shape` — which `zodToMcpProps(AgentObjectSchema)` (the advertised
+ * MCP surface) and `Object.keys(AgentObjectSchema.shape)` (server.ts's hosted-write key list) both
+ * need. `AgentSchema` wraps it in a `.superRefine`, a `ZodEffects` that has NEITHER — so those two
+ * consumers read the inner object while every `.parse`/`.safeParse` caller (`defineAgent`, the loader)
+ * gets the cross-field rule for free. An agent that requires an input outside its own capability
+ * envelope is MALFORMED, not merely un-composable, so it is refused at PARSE — earlier and closer to
+ * the author than the compose-time chair refusal, which is a different question (does THIS placement
+ * supply it?).
+ */
+export declare const AgentSchema: z.ZodEffects<z.ZodObject<{
+    slug: z.ZodString;
+    primitives: z.ZodReadonly<z.ZodArray<z.ZodEnum<["SENSE", "INTERPRET", "JUDGE", "PLAN", "CREATE", "VERIFY"]>, "many">>;
+    input_types: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    /** The inputs this agent CANNOT WORK WITHOUT in ANY placement — the per-agent MANDATE that
+     *  `input_types` (the capability ENVELOPE: what the agent CAN consume across all roles) cannot
+     *  express. `composeStandard` refuses a chair whose `input_contract` omits any of these, because
+     *  that placement would run the agent's method against an input that never arrives. Every entry
+     *  MUST also appear in `input_types` — an agent cannot REQUIRE an input outside its own envelope;
+     *  the cross-field rule on `AgentSchema` (the `.superRefine` below) enforces that at PARSE.
+     *
+     *  OPTIONAL with NO default — deliberately, exactly like `turn_budget`/`tier`. A `.default([])`
+     *  would make the field non-optional on the `Agent` output type (breaking hand-rolled `Agent`
+     *  literals such as `tests/genome_write_roundtrip.test.ts`'s `sensor`) and would ADD
+     *  `required_inputs: []` to every existing agent on write-back, breaking byte-equivalent round-trip.
+     *  Absent stays absent; a Zod object drops an undeclared key, so the field must be declared HERE to
+     *  be retained. */
+    required_inputs: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
     output_types: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
     domain: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     identity: z.ZodString;
@@ -416,6 +743,117 @@ export declare const AgentSchema: z.ZodObject<{
     constraints: readonly string[];
     behavioral_primitives: readonly ["explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler", "explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler"];
     depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
+    allowed_tools?: readonly string[] | undefined;
+    disallowed_tools?: readonly string[] | undefined;
+    skill_slugs?: readonly string[] | undefined;
+    skills?: readonly {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow: string[];
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }[] | undefined;
+    model_tier?: "standard" | "economy" | "premium" | undefined;
+    max_tool_calls?: number | undefined;
+    max_token_budget?: number | undefined;
+    code_tool_access?: "none" | "read" | "write" | "full" | undefined;
+    browser_grant?: {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    } | undefined;
+}, {
+    slug: string;
+    primitives: readonly ("SENSE" | "INTERPRET" | "JUDGE" | "PLAN" | "CREATE" | "VERIFY")[];
+    identity: string;
+    method: string;
+    constraints: readonly string[];
+    behavioral_primitives: readonly ["explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler", "explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler"];
+    input_types?: readonly string[] | undefined;
+    output_types?: readonly string[] | undefined;
+    domain?: string | null | undefined;
+    depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
+    allowed_tools?: readonly string[] | undefined;
+    disallowed_tools?: readonly string[] | undefined;
+    skill_slugs?: readonly string[] | undefined;
+    skills?: readonly {
+        slug: string;
+        version?: number | undefined;
+        code?: string | undefined;
+        description?: string | undefined;
+        skill_type?: string | undefined;
+        input_type?: string | undefined;
+        output_type?: string | undefined;
+        corpus?: string | undefined;
+        determinism_ratio?: number | undefined;
+        permission?: {
+            tier?: number | undefined;
+            network?: {
+                allow?: string[] | undefined;
+                methods?: string[] | undefined;
+                max_requests?: number | undefined;
+                max_bytes?: number | undefined;
+            } | undefined;
+        } | undefined;
+        timeout_ms?: number | undefined;
+        hydration?: Record<string, {
+            type: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            binding?: "institution" | "gig" | undefined;
+        }> | undefined;
+        fixtures?: unknown[] | undefined;
+        md?: string | undefined;
+    }[] | undefined;
+    model_tier?: "standard" | "economy" | "premium" | undefined;
+    max_tool_calls?: number | undefined;
+    max_token_budget?: number | undefined;
+    code_tool_access?: "none" | "read" | "write" | "full" | undefined;
+    browser_grant?: {
+        allowed_origins: string[];
+        blocked_origins?: string[] | undefined;
+        trace_dir?: string | undefined;
+        isolated?: boolean | undefined;
+        headless?: boolean | undefined;
+    } | undefined;
+}>, {
+    slug: string;
+    primitives: readonly ("SENSE" | "INTERPRET" | "JUDGE" | "PLAN" | "CREATE" | "VERIFY")[];
+    input_types: readonly string[];
+    output_types: readonly string[];
+    domain: string | null;
+    identity: string;
+    method: string;
+    constraints: readonly string[];
+    behavioral_primitives: readonly ["explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler", "explorer" | "analyst" | "critic" | "synthesizer" | "planner" | "executor" | "audience_modeler"];
+    depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
     allowed_tools?: readonly string[] | undefined;
     disallowed_tools?: readonly string[] | undefined;
     skill_slugs?: readonly string[] | undefined;
@@ -470,6 +908,7 @@ export declare const AgentSchema: z.ZodObject<{
     output_types?: readonly string[] | undefined;
     domain?: string | null | undefined;
     depth_profile?: "skim" | "quick" | "standard" | "deep" | undefined;
+    required_inputs?: readonly string[] | undefined;
     allowed_tools?: readonly string[] | undefined;
     disallowed_tools?: readonly string[] | undefined;
     skill_slugs?: readonly string[] | undefined;
@@ -2756,8 +3195,15 @@ export type VenueOutput = z.output<typeof VenueSchema>;
  */
 export declare function venueDefect(venue: VenueOutput): string | null;
 type JsonType = "string" | "number" | "boolean" | "array" | "object";
-/** The MCP `properties` map (field → JSON type) for a genome class schema. */
-export declare function zodToMcpProps(schema: z.ZodObject<z.ZodRawShape>): Record<string, JsonType>;
+/** The MCP `properties` map (field → JSON type) for a genome class schema.
+ *
+ *  Accepts either a plain `ZodObject` or a `.superRefine`/`.refine`-wrapped one (a `ZodEffects`, e.g.
+ *  `AgentSchema` with its `required_inputs ⊆ input_types` rule): a cross-field-refined class has no
+ *  own `.shape`, so unwrap to the inner object before reading it. This mirrors `jsonTypeOf`'s own
+ *  effects-unwrapping (`_def.schema`) and lets a refined class advertise its field surface without a
+ *  parallel object-schema sibling threaded to every call site. Passing the inner `…ObjectSchema`
+ *  directly (as venue does) still works — the guard is a no-op on a plain object. */
+export declare function zodToMcpProps(schema: z.ZodTypeAny): Record<string, JsonType>;
 /** How a Resource REFILLS, expressed in the resource's OWN unit — a monthly seat renews, a one-off
  *  purchase does not, a rate-based capacity decays. `quantity` is a magnitude in the SAME unit the
  *  Resource declares; `per_period` is the cadence it renews over (absent for a one-off). NOTHING

package/dist/src/genome_schema.js

@@ -84,10 +84,24 @@ export const SkillSchema = z.object({
 });
 // ── Agent — the template class, migrated end-to-end. z.input = AgentDef (what you author,
 //    optionals allowed); z.output = Agent (defaults applied). One definition, both types. ──
-export const AgentSchema = z.object({
+export const AgentObjectSchema = z.object({
     slug: z.string(),
     primitives: z.array(PrimitiveSchema).readonly(),
     input_types: z.array(z.string()).readonly().default([]),
+    /** The inputs this agent CANNOT WORK WITHOUT in ANY placement — the per-agent MANDATE that
+     *  `input_types` (the capability ENVELOPE: what the agent CAN consume across all roles) cannot
+     *  express. `composeStandard` refuses a chair whose `input_contract` omits any of these, because
+     *  that placement would run the agent's method against an input that never arrives. Every entry
+     *  MUST also appear in `input_types` — an agent cannot REQUIRE an input outside its own envelope;
+     *  the cross-field rule on `AgentSchema` (the `.superRefine` below) enforces that at PARSE.
+     *
+     *  OPTIONAL with NO default — deliberately, exactly like `turn_budget`/`tier`. A `.default([])`
+     *  would make the field non-optional on the `Agent` output type (breaking hand-rolled `Agent`
+     *  literals such as `tests/genome_write_roundtrip.test.ts`'s `sensor`) and would ADD
+     *  `required_inputs: []` to every existing agent on write-back, breaking byte-equivalent round-trip.
+     *  Absent stays absent; a Zod object drops an undeclared key, so the field must be declared HERE to
+     *  be retained. */
+    required_inputs: z.array(z.string()).readonly().optional(),
     output_types: z.array(z.string()).readonly().default([]),
     domain: z.string().nullable().default(null),
     identity: z.string(),
@@ -121,6 +135,34 @@ export const AgentSchema = z.object({
     depth_profile: DepthSchema.optional(),
     browser_grant: BrowserGrantSchema.optional(),
 });
+/**
+ * The agent AUTHORING/parse surface: the plain `AgentObjectSchema` plus the one cross-field rule a
+ * single field cannot state — every `required_inputs` entry must also be an `input_types` entry.
+ *
+ * Mirrors the `VenueSchema` / `VenueObjectSchema` split below. The inner `AgentObjectSchema` is a
+ * plain `ZodObject`, so it retains `.shape` — which `zodToMcpProps(AgentObjectSchema)` (the advertised
+ * MCP surface) and `Object.keys(AgentObjectSchema.shape)` (server.ts's hosted-write key list) both
+ * need. `AgentSchema` wraps it in a `.superRefine`, a `ZodEffects` that has NEITHER — so those two
+ * consumers read the inner object while every `.parse`/`.safeParse` caller (`defineAgent`, the loader)
+ * gets the cross-field rule for free. An agent that requires an input outside its own capability
+ * envelope is MALFORMED, not merely un-composable, so it is refused at PARSE — earlier and closer to
+ * the author than the compose-time chair refusal, which is a different question (does THIS placement
+ * supply it?).
+ */
+export const AgentSchema = AgentObjectSchema.superRefine((agent, ctx) => {
+    const envelope = new Set(agent.input_types ?? []);
+    for (const req of agent.required_inputs ?? []) {
+        if (envelope.has(req))
+            continue;
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["required_inputs"],
+            message: `required_inputs entry "${req}" is not in input_types [${(agent.input_types ?? []).join(", ")}] — ` +
+                `an agent cannot REQUIRE an input outside its capability envelope. Add "${req}" to input_types, ` +
+                `or drop it from required_inputs.`,
+        });
+    }
+});
 // ── Chair / Phase / Standard — the schema is the DNA; the runtime Standard (resolved agents) is a
 //    transform output and stays a derived type in composition.ts. The FILE/compose shape is here. ──
 export const ChairSchema = z.object({
@@ -1071,9 +1113,17 @@ function jsonTypeOf(schema) {
         return "array";
     return "object";
 }
-/** The MCP `properties` map (field → JSON type) for a genome class schema. */
+/** The MCP `properties` map (field → JSON type) for a genome class schema.
+ *
+ *  Accepts either a plain `ZodObject` or a `.superRefine`/`.refine`-wrapped one (a `ZodEffects`, e.g.
+ *  `AgentSchema` with its `required_inputs ⊆ input_types` rule): a cross-field-refined class has no
+ *  own `.shape`, so unwrap to the inner object before reading it. This mirrors `jsonTypeOf`'s own
+ *  effects-unwrapping (`_def.schema`) and lets a refined class advertise its field surface without a
+ *  parallel object-schema sibling threaded to every call site. Passing the inner `…ObjectSchema`
+ *  directly (as venue does) still works — the guard is a no-op on a plain object. */
 export function zodToMcpProps(schema) {
-    return Object.fromEntries(Object.entries(schema.shape).map(([k, v]) => [k, jsonTypeOf(v)]));
+    const obj = (schema instanceof z.ZodEffects ? schema._def.schema : schema);
+    return Object.fromEntries(Object.entries(obj.shape).map(([k, v]) => [k, jsonTypeOf(v)]));
 }
 // ── The committed-work objects — Tour / Booking / Resource, the binding middle place ──────────────
 //