@tangle-network/agent-runtime 0.101.1 → 0.102.1

package/dist/{types-B3vAW0Oq.d.ts → types-CLat4bT9.d.ts}

@@ -799,4 +799,4 @@ interface ExecCtx {
     parentSpanId?: string;
 }
 
-export { type AgentRunSpec as A, type LoopIterationEndedPayload as B, type LoopIterationStartedPayload as C, type Driver as D, type ExecCtx as E, type LoopPlanDescription as F, type LoopPlanPayload as G, type LoopStartedPayload as H, type Iteration as I, type LoopTeardownFailedPayload as J, type MountManifestEntry as K, type LoopTokenUsage as L, type MountRecorder as M, type RunProvenance as N, type OutputAdapter as O, type ValidationCtx as P, type RuntimeHooks as R, type SandboxClient as S, type Validator as V, type LoopSandboxPlacement as a, type LoopTraceEvent as b, type RuntimeDecisionEvidenceRef as c, type RuntimeDecisionKind as d, type RuntimeDecisionPoint as e, type RuntimeHookContext as f, type RuntimeHookErrorContext as g, type RuntimeHookEvent as h, type RuntimeHookPhase as i, type RuntimeHookTarget as j, type RuntimeRunHandle as k, type RuntimeRunPersistenceAdapter as l, type RuntimeRunRow as m, composeRuntimeHooks as n, defineRuntimeHooks as o, notifyRuntimeDecisionPoint as p, notifyRuntimeHookEvent as q, type LoopTraceEmitter as r, startRuntimeRun as s, type LoopWinner as t, type LoopLineageOptions as u, type LoopResult as v, type SelectionReceipt as w, type LoopDecisionPayload as x, type LoopEndedPayload as y, type LoopIterationDispatchPayload as z };
+export { type AgentRunSpec as A, type LoopIterationEndedPayload as B, type LoopIterationStartedPayload as C, type Driver as D, type ExecCtx as E, type LoopPlanDescription as F, type LoopPlanPayload as G, type LoopStartedPayload as H, type Iteration as I, type LoopTeardownFailedPayload as J, type MountManifestEntry as K, type LoopTokenUsage as L, type MountRecorder as M, type RunProvenance as N, type OutputAdapter as O, type ValidationCtx as P, type RuntimeHooks as R, type SandboxClient as S, type Validator as V, type SelectionReceipt as a, type LoopSandboxPlacement as b, type LoopTraceEvent as c, type LoopTraceEmitter as d, type RuntimeDecisionEvidenceRef as e, type RuntimeDecisionKind as f, type RuntimeDecisionPoint as g, type RuntimeHookContext as h, type RuntimeHookErrorContext as i, type RuntimeHookEvent as j, type RuntimeHookPhase as k, type RuntimeHookTarget as l, type RuntimeRunHandle as m, type RuntimeRunPersistenceAdapter as n, type RuntimeRunRow as o, composeRuntimeHooks as p, defineRuntimeHooks as q, notifyRuntimeDecisionPoint as r, notifyRuntimeHookEvent as s, startRuntimeRun as t, type LoopWinner as u, type LoopLineageOptions as v, type LoopResult as w, type LoopDecisionPayload as x, type LoopEndedPayload as y, type LoopIterationDispatchPayload as z };

package/dist/{types-CmnA2iL3.d.ts → types-D870JlH0.d.ts}

@@ -1,7 +1,7 @@
 import { DefaultVerdict } from '@tangle-network/agent-eval';
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { BackendType } from '@tangle-network/sandbox';
-import { L as LoopTokenUsage, R as RuntimeHooks } from './types-B3vAW0Oq.js';
+import { L as LoopTokenUsage, R as RuntimeHooks } from './types-CLat4bT9.js';
 
 /**
  *
@@ -497,4 +497,4 @@ interface WidenGate<Out> {
     readonly judgeExempt?: boolean;
 }
 
-export type { Agent as A, Budget as B, ExecutorFactory as E, NodeId as N, Runtime as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, ResultBlobStore as a, SupervisedResult as b, Executor as c, AgentSpec as d, ExecutorRegistry as e, SpawnJournal as f, RootHandle as g, Settled as h, Spend as i, SpawnEvent as j, Supervisor as k, ExecutorContext as l, ExecutorResult as m, SupervisorOpts as n };
+export type { Agent as A, Budget as B, ExecutorFactory as E, NodeId as N, Runtime as R, Scope as S, TreeView as T, UsageEvent as U, WidenGate as W, ResultBlobStore as a, SupervisedResult as b, Executor as c, Settled as d, Spend as e, AgentSpec as f, SpawnJournal as g, ExecutorRegistry as h, RootHandle as i, SpawnEvent as j, Supervisor as k, ExecutorContext as l, ExecutorResult as m, SupervisorOpts as n };

package/dist/{worktree-fanout-DCA3G4bO.d.ts → worktree-fanout-DsIR4d6w.d.ts}

@@ -1,239 +1,10 @@
 import { AgentProfile } from '@tangle-network/agent-interface';
 import { AnalystFinding, DefaultVerdict } from '@tangle-network/agent-eval';
-import { d as AgentSpec, e as ExecutorRegistry, B as Budget, A as Agent, f as SpawnJournal, a as ResultBlobStore, g as RootHandle, b as SupervisedResult, N as NodeId, h as Settled, i as Spend, S as Scope, c as Executor } from './types-CmnA2iL3.js';
-import { R as RuntimeHooks, I as Iteration } from './types-B3vAW0Oq.js';
+import { N as NodeId, d as Settled, e as Spend, f as AgentSpec, S as Scope, g as SpawnJournal, a as ResultBlobStore, h as ExecutorRegistry, B as Budget, A as Agent, i as RootHandle, b as SupervisedResult, c as Executor } from './types-D870JlH0.js';
+import { I as Iteration, R as RuntimeHooks } from './types-CLat4bT9.js';
 import { BackendType } from '@tangle-network/sandbox';
-import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-C80jiRfN.js';
-import { L as LocalHarness, r as runLocalHarness } from './local-harness-ZqCx51u7.js';
-
-/**
- *
- * The personify layer — the "act like X" knob on top of the recursive keystone.
- *
- * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
- * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
- * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
- * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
- *
- * This layer adds exactly that content seam without inventing a second engine:
- *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
- *    executor), a root `directive` (the goal framing handed to the chosen shape), a
- *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
- *    `definePersona` builds it; it is data, not behavior.
- *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
- *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
- *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
- *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
- *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
- *
- * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
- * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
- * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
- * world-model / memory field is additive (a new optional key), never a breaking change.
- *
- * @experimental
- */
-
-/**
- * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
- * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
- * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
- * MUST name why); impls fail loud on it rather than emitting a vacuous block.
- *
- * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
- * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
- */
-type Outcome<D> = {
-    kind: 'done';
-    deliverable: D;
-} | {
-    kind: 'blocked';
-    blockers: string[];
-};
-/**
- * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
- * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
- * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
- *
- * The framework never reads `directive`/`context` semantically; it threads them to the shape
- * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
- * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
- * persona string is ever hardcoded in a shape or the engine.
- *
- * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
- */
-interface Persona<D = unknown> {
-    /** Stable persona name — used as the trace/journal label root, never as content. */
-    readonly name: string;
-    /**
-     * The root agent's executor mapping (profile + harness + optional BYO executor). The
-     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
-     * are derived from / resolved against the same persona registry (see `ShapeContext`).
-     */
-    readonly root: AgentSpec;
-    /** The goal framing handed to the shape — the "what to achieve", not "how". */
-    readonly directive: string;
-    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
-     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
-    readonly context: PersonaContext;
-    /**
-     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
-     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
-     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
-     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
-     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
-     */
-    readonly executors: PersonaExecutors;
-    /**
-     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
-     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
-     */
-    readonly extensions?: Readonly<Record<string, unknown>>;
-    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
-     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
-    readonly __deliverable?: D;
-}
-/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
- *  own role/audience/constraints; the framework treats it as opaque content. */
-interface PersonaContext {
-    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
-    readonly role: string;
-    /** Optional freeform framing the persona's prompts/profiles consume. */
-    readonly notes?: string;
-    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
-    readonly [key: string]: unknown;
-}
-/**
- * How a persona supplies executor resolution. Either a pre-built registry (factories already
- * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
- * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
- */
-interface PersonaExecutors {
-    /** A registry whose factories already capture their seams. Highest precedence. */
-    readonly registry?: ExecutorRegistry;
-    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
-    readonly seams?: Readonly<Record<string, unknown>>;
-}
-/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
- *  the executors-supplied invariant check and freeze the record. */
-interface DefinePersonaInput<D = unknown> {
-    readonly name: string;
-    readonly root: AgentSpec;
-    readonly directive: string;
-    readonly context: PersonaContext;
-    readonly executors: PersonaExecutors;
-    readonly extensions?: Readonly<Record<string, unknown>>;
-    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
-     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
-    readonly __deliverable?: D;
-}
-/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
- *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
-type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
-/**
- * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
- * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
- * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
- * against them and fails closed, so an over-eager shape can never overspend.
- */
-interface ShapeBudget {
-    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
-    readonly perChild: Budget;
-    /** Max children a fanout step may open in one round (the shape's structural width). */
-    readonly fanout: number;
-}
-/**
- * The construction context a `LoopShape` factory receives. Carries the persona's resolved
- * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
- * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
- * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
- * registry directly — it asks the context, keeping resolution single-sourced.
- */
-interface ShapeContext<D = unknown> {
-    readonly persona: Persona<D>;
-    readonly budget: ShapeBudget;
-    /**
-     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
-     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
-     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
-     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
-     */
-    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
-    /** Derive a child `AgentSpec` from the persona's root spec with an overridden profile —
-     *  the seam a shape uses to give a worker a narrower role/prompt than the root persona. */
-    childSpec(profile: AgentProfile, harness?: BackendType | null): AgentSpec;
-    /** The scope analyst (selector≠judge firewall) the combinator steers from. Absent ⇒ the
-     *  dormant default (empty findings → gates read deliverables/state only). */
-    readonly analyst?: ScopeAnalyst<D>;
-}
-/**
- * A reusable act-body factory. Given the persona's content + seams (`ShapeContext`), it
- * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
- * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
- * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
- * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
- */
-type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
-/**
- * The open shape registry — the extension point that makes a new loop-shape ONE file + one
- * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
- * `succeeded` before `value`); `register` fails loud on a duplicate name.
- */
-interface ShapeRegistry {
-    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
-    resolve<Task, D>(name: string): {
-        succeeded: true;
-        value: LoopShape<Task, D>;
-    } | {
-        succeeded: false;
-        error: string;
-    };
-    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
-    names(): string[];
-}
-/**
- * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
- * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
- * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
- * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
- *
- * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
- * default registry). The journal/blobs default to in-memory impls in the engine when omitted
- * (durable FS impls are passed explicitly for a persisted run).
- */
-interface RunPersonifiedOptions<Task, D> {
-    readonly persona: Persona<D>;
-    /** A resolved shape factory OR a registered shape name. */
-    readonly shape: LoopShape<Task, D> | string;
-    readonly task: Task;
-    readonly budget: Budget;
-    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
-    readonly shapeBudget?: Partial<ShapeBudget>;
-    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
-    readonly runId?: string;
-    readonly journal?: SpawnJournal;
-    readonly blobs?: ResultBlobStore;
-    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
-    readonly maxDepth?: number;
-    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
-    readonly maxRestarts?: number;
-    readonly withinMs?: number;
-    /** A live root handle to attach (view/signal/abort) before the run starts. */
-    readonly handle?: RootHandle<Outcome<D>>;
-    readonly now?: () => number;
-    readonly signal?: AbortSignal;
-    /** Optional scope analyst threaded into the shape's ShapeContext so loopUntil/widen steer
-     *  on trace-derived findings instead of the dormant empty default. */
-    readonly analyst?: ScopeAnalyst<D>;
-    /**
-     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
-     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
-     * trace export). Absent ⇒ no stream (the run is silent, as today).
-     */
-    readonly hooks?: RuntimeHooks;
-}
-/** The composed run signature. */
-type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
+import { W as WorktreeHarnessResult, G as GitRunner, a as WorktreeCheckRunner, D as DeliverableSpec } from './completion-gate-C6dhVN-N.js';
+import { L as LocalHarness, r as runLocalHarness } from './local-harness-CtK9dSny.js';
 
 /**
  *
@@ -767,6 +538,235 @@ interface EqualKOnCostOptions {
 /** `equalKOnCost(arms, opts)` — the cross-arm equal-compute check on conserved cost. */
 type EqualKOnCost = (arms: ReadonlyArray<EqualKArm>, options?: EqualKOnCostOptions) => EqualKVerdict;
 
+/**
+ *
+ * The personify layer — the "act like X" knob on top of the recursive keystone.
+ *
+ * The keystone (`src/loops/supervise/`) is pure STRUCTURE: a recursive `Agent` atom inside
+ * a budget-conserving `Scope`, an `ExecutorRegistry` mapping an `AgentSpec` to a runtime,
+ * and a `Supervisor` that runs a root agent to a typed `SupervisedResult`. It carries no
+ * CONTENT — no model, no prompt, no goal framing, no notion of "who this loop is".
+ *
+ * This layer adds exactly that content seam without inventing a second engine:
+ *  - A `Persona` is a thin record: the root `AgentSpec` (profile + harness + optional BYO
+ *    executor), a root `directive` (the goal framing handed to the chosen shape), a
+ *    `context` blob (who the loop is acting as), and the executor seams the registry needs.
+ *    `definePersona` builds it; it is data, not behavior.
+ *  - A `LoopShape` is a reusable act-body FACTORY: `(ctx: ShapeContext) => Agent`. The shape
+ *    owns the STRUCTURE (how to decompose / fan out / verify / synthesize); the persona's
+ *    content parameterizes it. A new shape is ONE file + one `registerShape` call.
+ *  - `Outcome<D>` is the contract every shape synthesizes into: a finished deliverable OR a
+ *    list of concrete blockers — "100% done or 100%-defined blockers", never a vague middle.
+ *
+ * Layering: this module imports ONLY keystone runtime types (`./supervise/types`) and the
+ * substrate `AgentProfile`/`BackendType`. It typechecks standalone — no impl, no engine.
+ * Extensibility is structural: `Persona` carries an open `extensions` bag so a later
+ * world-model / memory field is additive (a new optional key), never a breaking change.
+ *
+ * @experimental
+ */
+
+/**
+ * The terminal contract Drew wants: a loop returns a FINISHED deliverable, or the concrete
+ * list of blockers that stopped it — never a half-done best-effort coercion. A `blocked`
+ * outcome with an empty `blockers` list is a contract violation (a shape that can't finish
+ * MUST name why); impls fail loud on it rather than emitting a vacuous block.
+ *
+ * `Outcome` is the `Out` type a personified `Agent`/`Supervisor` is parameterized by, so the
+ * keystone's typed `SupervisedResult<Outcome<D>>` carries it end to end with no coercion.
+ */
+type Outcome<D> = {
+    kind: 'done';
+    deliverable: D;
+} | {
+    kind: 'blocked';
+    blockers: string[];
+};
+/**
+ * The "act like X" record. A thin composition over the keystone's `AgentSpec`: it pairs the
+ * root spec (the executor mapping for the root agent the shape builds) with the CONTENT a
+ * shape consumes — the goal framing (`directive`) and who the loop is acting as (`context`).
+ *
+ * The framework never reads `directive`/`context` semantically; it threads them to the shape
+ * verbatim through `ShapeContext`. This is the rule the mandate names: the FRAMEWORK is
+ * structure, the PERSONA carries model/prompt/tools/directive. No model name, prompt, or
+ * persona string is ever hardcoded in a shape or the engine.
+ *
+ * `D` is the deliverable type this persona's loops produce; it flows into `Outcome<D>`.
+ */
+interface Persona<D = unknown> {
+    /** Stable persona name — used as the trace/journal label root, never as content. */
+    readonly name: string;
+    /**
+     * The root agent's executor mapping (profile + harness + optional BYO executor). The
+     * shape's root `Agent` carries THIS as its `executorSpec`; child specs the shape spawns
+     * are derived from / resolved against the same persona registry (see `ShapeContext`).
+     */
+    readonly root: AgentSpec;
+    /** The goal framing handed to the shape — the "what to achieve", not "how". */
+    readonly directive: string;
+    /** Who the loop is acting as — the opaque persona context blob the shape may inject into
+     *  child tasks. Opaque to the framework; only the persona's profiles/prompts interpret it. */
+    readonly context: PersonaContext;
+    /**
+     * The executor seams (router endpoint+key, sandbox client, cli bin) the built-in runtimes
+     * read off `ExecutorContext.seams`, OR a fully pre-configured registry. The supervisor
+     * threads an EMPTY seam bag to the root scope, so a persona that uses built-in metered
+     * runtimes MUST supply a registry whose factories close over their seams (or BYO executors
+     * on each `AgentSpec`). Carried here so `runPersonified` can build `SupervisorOpts.executors`.
+     */
+    readonly executors: PersonaExecutors;
+    /**
+     * Forward-compatible extension bag — a later world-model / memory / tool-budget field is an
+     * additive key here, never a breaking change to the `Persona` shape. Opaque to the engine.
+     */
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: binds the persona to its deliverable type so `runPersonified` infers `D` from
+     *  the persona and the chosen shape must agree. Type-only — never present at runtime. */
+    readonly __deliverable?: D;
+}
+/** The persona context blob — who the loop is acting as. Open by intent: a persona names its
+ *  own role/audience/constraints; the framework treats it as opaque content. */
+interface PersonaContext {
+    /** The role the loop embodies ("senior staff engineer", "equity research analyst", …). */
+    readonly role: string;
+    /** Optional freeform framing the persona's prompts/profiles consume. */
+    readonly notes?: string;
+    /** Open content bag — persona-specific fields a shape's child tasks may carry. */
+    readonly [key: string]: unknown;
+}
+/**
+ * How a persona supplies executor resolution. Either a pre-built registry (factories already
+ * closed over their seams) OR the raw seam bag the engine uses to construct a registry +
+ * thread the seams onto each spawn. Exactly one is required — fail loud if neither is set.
+ */
+interface PersonaExecutors {
+    /** A registry whose factories already capture their seams. Highest precedence. */
+    readonly registry?: ExecutorRegistry;
+    /** Raw seams to thread onto built-in runtimes (`router`/`sandbox`/`cli` keys). */
+    readonly seams?: Readonly<Record<string, unknown>>;
+}
+/** The minimal input to build a `Persona`. Mirrors `Persona` but lets the builder default
+ *  the executors-supplied invariant check and freeze the record. */
+interface DefinePersonaInput<D = unknown> {
+    readonly name: string;
+    readonly root: AgentSpec;
+    readonly directive: string;
+    readonly context: PersonaContext;
+    readonly executors: PersonaExecutors;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+    /** Phantom: pins the input's deliverable type so `definePersona<D>` returns a `Persona<D>`
+     *  the caller's shape must agree with. Type-only — never supplied at a call site. */
+    readonly __deliverable?: D;
+}
+/** Builds a frozen `Persona`, failing loud on the executors-supplied invariant (neither a
+ *  registry nor seams = an unresolvable persona). Pure — no I/O, no engine. */
+type DefinePersona = <D = unknown>(input: DefinePersonaInput<D>) => Persona<D>;
+/**
+ * Budget knobs a shape reads to size its fanout/children WITHOUT owning the conserved pool.
+ * The root budget lives on `SupervisorOpts.budget`; the shape only needs the per-child
+ * sizing hints + the fanout width it is allowed to open. All ceilings — the pool reserves
+ * against them and fails closed, so an over-eager shape can never overspend.
+ */
+interface ShapeBudget {
+    /** Per-child spawn budget the shape reserves for each leaf/sub-loop it opens. */
+    readonly perChild: Budget;
+    /** Max children a fanout step may open in one round (the shape's structural width). */
+    readonly fanout: number;
+}
+/**
+ * The construction context a `LoopShape` factory receives. Carries the persona's resolved
+ * executor seams + the budget knobs, plus the ONE helper a shape needs to spawn a child
+ * through the keystone: `spawnChild` resolves an `AgentSpec` (or a persona-derived child
+ * profile) into an `Agent` the shape hands to `scope.spawn`. The shape never touches the
+ * registry directly — it asks the context, keeping resolution single-sourced.
+ */
+interface ShapeContext<D = unknown> {
+    readonly persona: Persona<D>;
+    readonly budget: ShapeBudget;
+    /**
+     * Wrap an `AgentSpec` into a leaf `Agent` carrying it as `executorSpec`, so the shape can
+     * `scope.spawn(spawnChild(spec), task, opts)`. `name` labels the child for traces. The
+     * returned agent's `act` is never invoked by the keystone (it is spawned, not run) — the
+     * spec drives the resolved `Executor`; `act` exists only to satisfy the `Agent` shape.
+     */
+    spawnChild(name: string, spec: AgentSpec): Agent<unknown, Outcome<D>>;
+    /** Derive a child `AgentSpec` from the persona's root spec with an overridden profile —
+     *  the seam a shape uses to give a worker a narrower role/prompt than the root persona. */
+    childSpec(profile: AgentProfile, harness?: BackendType | null): AgentSpec;
+    /** The scope analyst (selector≠judge firewall) the combinator steers from. Absent ⇒ the
+     *  dormant default (empty findings → gates read deliverables/state only). */
+    readonly analyst?: ScopeAnalyst<D>;
+}
+/**
+ * A reusable act-body factory. Given the persona's content + seams (`ShapeContext`), it
+ * returns the root `Agent<Task, Outcome<D>>` whose `act` decomposes the task, fans out
+ * children through `scope.spawn`, verifies/selects across their settlements (selector≠judge:
+ * via `settledToIteration` + `defaultSelectWinner`, never re-ranking behind the driver), and
+ * synthesizes the terminal `Outcome<D>`. The shape is STRUCTURE; the persona is CONTENT.
+ */
+type LoopShape<Task, D> = (ctx: ShapeContext<D>) => Agent<Task, Outcome<D>>;
+/**
+ * The open shape registry — the extension point that makes a new loop-shape ONE file + one
+ * `registerShape` call with zero edits elsewhere. `resolve` returns a typed outcome (inspect
+ * `succeeded` before `value`); `register` fails loud on a duplicate name.
+ */
+interface ShapeRegistry {
+    register<Task, D>(name: string, factory: LoopShape<Task, D>): void;
+    resolve<Task, D>(name: string): {
+        succeeded: true;
+        value: LoopShape<Task, D>;
+    } | {
+        succeeded: false;
+        error: string;
+    };
+    /** The registered shape names — for diagnostics + a fail-loud "unknown shape" message. */
+    names(): string[];
+}
+/**
+ * The end-to-end entrypoint. Builds the persona's root `Agent` from the chosen shape, then
+ * runs it through a fresh `createSupervisor` over the persona's executors + the supplied
+ * budget/journal/blobs. Returns the keystone's typed `SupervisedResult<Outcome<D>>` — a
+ * `winner` carries the synthesized `Outcome<D>`; a `no-winner` is never coerced into one.
+ *
+ * `shape` is either a resolved `LoopShape` or a registered shape NAME (resolved through the
+ * default registry). The journal/blobs default to in-memory impls in the engine when omitted
+ * (durable FS impls are passed explicitly for a persisted run).
+ */
+interface RunPersonifiedOptions<Task, D> {
+    readonly persona: Persona<D>;
+    /** A resolved shape factory OR a registered shape name. */
+    readonly shape: LoopShape<Task, D> | string;
+    readonly task: Task;
+    readonly budget: Budget;
+    /** Per-child sizing + fanout width handed to the shape. Defaults derive from `budget`. */
+    readonly shapeBudget?: Partial<ShapeBudget>;
+    /** Trace/journal root key. Defaults to the persona name + a run discriminator in the engine. */
+    readonly runId?: string;
+    readonly journal?: SpawnJournal;
+    readonly blobs?: ResultBlobStore;
+    /** Runtime recursion-depth ceiling, paired with the conserved pool. */
+    readonly maxDepth?: number;
+    /** OTP intensity breaker bounds, forwarded to the supervisor verbatim. */
+    readonly maxRestarts?: number;
+    readonly withinMs?: number;
+    /** A live root handle to attach (view/signal/abort) before the run starts. */
+    readonly handle?: RootHandle<Outcome<D>>;
+    readonly now?: () => number;
+    readonly signal?: AbortSignal;
+    /** Optional scope analyst threaded into the shape's ShapeContext so loopUntil/widen steer
+     *  on trace-derived findings instead of the dormant empty default. */
+    readonly analyst?: ScopeAnalyst<D>;
+    /**
+     * Lifecycle stream sink, forwarded to `SupervisorOpts.hooks` so the root `Scope`'s
+     * `agent.spawn`/`agent.child` events flow to an observer (e.g. the Intelligence SDK's
+     * trace export). Absent ⇒ no stream (the run is silent, as today).
+     */
+    readonly hooks?: RuntimeHooks;
+}
+/** The composed run signature. */
+type RunPersonified = <Task, D>(options: RunPersonifiedOptions<Task, D>) => Promise<SupervisedResult<Outcome<D>>>;
+
 /**
  *
  * The mechanical patch gate — the SINGLE source of the no-op / always-on secret-path floor /
@@ -984,4 +984,4 @@ interface WorktreeFanoutOptions extends PatchDeliverableOptions {
  */
 declare function worktreeFanout<Task>(options: WorktreeFanoutOptions): CombinatorShape<Task, WorktreePatchArtifact>;
 
-export { type Widen as $, type AuthoredHarness as A, type Panel as B, type CorpusRecord as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type PanelJudge as G, type PanelVerdict as H, type PatchDeliverableOptions as I, type PersonaContext as J, type PersonaExecutors as K, type LoopUntilSpec as L, type Pipeline as M, type RenderCorpusToInstructions as N, type Outcome as O, type PanelSpec as P, type RunPersonified as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type ShapeBudget as U, type VerifySpec as V, type WinnerStrategy as W, type ShapeContext as X, type TrajectoryNode as Y, type TrajectoryReportFn as Z, type Verify as _, type WorktreeFanoutOptions as a, type WidenDecision as a0, type WidenLineage as a1, type WorktreeCliExecutorOptions as a2, createWorktreeCliExecutor as a3, patchDelivered as a4, worktreeFanout as a5, type WorktreePatchArtifact as b, type Corpus as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DefinePersona as t, type EqualKOnCost as u, type Fanout as v, type FanoutSynthesis as w, type FlatWidenGate as x, type LoopUntil as y, type LoopUntilState as z };
+export { type Widen as $, type AuthoredHarness as A, type Panel as B, type Corpus as C, type DefinePersonaInput as D, type EqualKArm as E, type FanoutOptions as F, type PanelJudge as G, type PanelVerdict as H, type PatchDeliverableOptions as I, type PersonaContext as J, type PersonaExecutors as K, type LoopUntilSpec as L, type Pipeline as M, type RenderCorpusToInstructions as N, type Outcome as O, type PanelSpec as P, type RunPersonified as Q, type RenderCorpusToInstructionsOptions as R, type ScopeAnalyzeInput as S, type TrajectoryReportOptions as T, type ShapeBudget as U, type VerifySpec as V, type WinnerStrategy as W, type ShapeContext as X, type TrajectoryNode as Y, type TrajectoryReportFn as Z, type Verify as _, type WorktreeFanoutOptions as a, type WidenDecision as a0, type WidenLineage as a1, type WorktreeCliExecutorOptions as a2, createWorktreeCliExecutor as a3, patchDelivered as a4, worktreeFanout as a5, type WorktreePatchArtifact as b, type CorpusRecord as c, type AssertTraceDerivedFindings as d, type SteerContext as e, type ScopeAnalyst as f, type CombinatorShape as g, type ScopeWidenGate as h, type PipelineStage as i, type FanoutWinnerSelector as j, type WidenSpec as k, type CorpusFilter as l, type Persona as m, type RunPersonifiedOptions as n, type ShapeRegistry as o, type LoopShape as p, type EqualKOnCostOptions as q, type EqualKVerdict as r, type TrajectoryReport as s, type DefinePersona as t, type EqualKOnCost as u, type Fanout as v, type FanoutSynthesis as w, type FlatWidenGate as x, type LoopUntil as y, type LoopUntilState as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.101.1",
+  "version": "0.102.1",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -87,6 +87,7 @@
   },
   "bin": {
     "agent-runtime-mcp": "./dist/mcp/bin.js",
+    "agent-runtime-memory-mcp": "./dist/mcp/memory-bin.js",
     "agent-runtime-loop": "./dist/loop-runner-bin.js"
   },
   "files": [
@@ -120,8 +121,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@tangle-network/agent-eval": "0.122.8",
-    "@tangle-network/agent-interface": "0.31.0",
+    "@tangle-network/agent-eval": "0.123.0",
+    "@tangle-network/agent-interface": "0.32.0",
     "@tangle-network/sandbox": "^0.11.1",
     "@types/node": "^25.9.3",
     "@types/tar-stream": "3.1.4",
@@ -152,8 +153,8 @@
   "license": "MIT",
   "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.122.8 <0.123.0",
-    "@tangle-network/agent-interface": ">=0.31.0 <0.32.0",
+    "@tangle-network/agent-eval": ">=0.122.8 <0.124.0",
+    "@tangle-network/agent-interface": ">=0.32.0 <0.33.0",
     "@tangle-network/sandbox": ">=0.11.1 <1.0.0",
     "playwright": "^1.40.0"
   },