@tangle-network/agent-runtime 0.72.0 → 0.73.0

package/dist/intelligence.d.ts

@@ -1,4 +1,4 @@
-import { c as LoopTraceEvent } from './types-K8-xkiw1.js';
+import { c as LoopTraceEvent } from './types-JufmXF2a.js';
 import { AgentProfileMcpServer } from '@tangle-network/agent-interface';
 import { T as ToolSpec } from './router-client-C7kp_ECN.js';
 import '@tangle-network/agent-eval';

package/dist/lifecycle.d.ts

@@ -0,0 +1,281 @@
+import { AgentProfileResourceRef, AgentProfileMcpServer, AgentProfileHookCommand, AgentSubagentProfile, AgentProfile } from '@tangle-network/agent-interface';
+
+/**
+ * `@tangle-network/agent-runtime/lifecycle` — artifact-lifecycle FOUNDATION.
+ *
+ * The §1.5 law says an agent IS its `AgentProfile`, and the profile is the WHOLE
+ * agent: prompt + skills + tools + mcp + hooks + subagents. This module names the
+ * discrete, individually-promotable PIECES of that profile — "artifacts" — and
+ * gives them stable ids so the rest of a self-improvement lifecycle (propose →
+ * measure → promote → ship) has something concrete to hang off.
+ *
+ * This is PHASE 1: just the two primitives the rest hangs off.
+ *   1. `ArtifactRegistry` — a typed catalog of profile artifacts with stable ids.
+ *   2. `measureMarginalLift` — the with-vs-without ablation: how much score/cost a
+ *      single artifact adds on top of a baseline profile.
+ *
+ * The per-surface lifecycles, the `BuildableSurface` author contract, and the
+ * promotion-gate wiring are deferred to later phases.
+ */
+
+/**
+ * The profile levers an artifact can target. One-to-one with the §1.5 profile
+ * surface (`prompt + skills + tools + mcp + hooks + subagents`). Each kind maps to
+ * exactly one field of `AgentProfile`, so an artifact can be applied onto a
+ * baseline profile deterministically (see `applyArtifact`).
+ */
+type ArtifactKind = 'skill' | 'tool' | 'mcp' | 'hook' | 'subagent' | 'prompt';
+/**
+ * The payload for each `ArtifactKind`. The shapes are the SAME types the
+ * `AgentProfile` field carries, so applying an artifact is a structural merge
+ * onto the profile — never a bespoke per-kind transform.
+ *
+ *   - `prompt`   — an instruction line appended to `profile.prompt.instructions`.
+ *   - `skill`    — a `SKILL.md`-style resource ref added to `profile.resources.skills`.
+ *   - `tool`     — a tool grant: `{ enabled }` set under `profile.tools[name]`.
+ *   - `mcp`      — one MCP server added under `profile.mcp[name]`.
+ *   - `hook`     — one or more hook commands added under `profile.hooks[event]`.
+ *   - `subagent` — one subagent profile added under `profile.subagents[name]`.
+ */
+interface ArtifactPayloads {
+    prompt: {
+        instruction: string;
+    };
+    skill: {
+        resource: AgentProfileResourceRef;
+    };
+    tool: {
+        enabled: boolean;
+    };
+    mcp: {
+        server: AgentProfileMcpServer;
+    };
+    hook: {
+        event: string;
+        commands: AgentProfileHookCommand[];
+    };
+    subagent: {
+        profile: AgentSubagentProfile;
+    };
+}
+/**
+ * A discrete, individually-promotable piece of an agent profile.
+ *
+ * `kind` selects the profile lever; `payload` is the kind-specific value; `key`
+ * is the profile-field key the payload lands under (the tool name, the MCP server
+ * name, the subagent name — unused for `prompt`, which appends). `id` is stable:
+ * once registered, it never changes, so a marginal-lift measurement, a promotion
+ * decision, and a ship record all reference the same artifact.
+ */
+interface ProfileArtifact<K extends ArtifactKind = ArtifactKind> {
+    /** Stable id. Assigned by the registry at register time; never reassigned. */
+    id: string;
+    kind: K;
+    /**
+     * The profile-field key this artifact lands under (e.g. the tool name, the MCP
+     * server name, the subagent name, the hook event). Optional for `prompt`
+     * (instructions append, they have no key). Defaults to `id` when applying a
+     * keyed artifact without an explicit key.
+     */
+    key?: string;
+    /** Human-facing label for review surfaces. */
+    name: string;
+    /** Optional one-line description of what this artifact does. */
+    description?: string;
+    payload: ArtifactPayloads[K];
+    /**
+     * Lifecycle status. Phase 1 tracks only `candidate` (registered, not yet
+     * promoted) and `promoted` (passed whatever gate the caller ran). The
+     * registry never auto-promotes; promotion is an explicit `promote(id)` call.
+     */
+    status: ArtifactStatus;
+    /** Free-form metadata (provenance, generation id, the measured lift, …). */
+    metadata?: Record<string, unknown>;
+}
+type ArtifactStatus = 'candidate' | 'promoted';
+/** The input to `register` — everything on `ProfileArtifact` except the
+ *  registry-owned `id` and `status`. An explicit `id` may be supplied for
+ *  deterministic/idempotent registration; otherwise the registry assigns one. */
+type ArtifactInput<K extends ArtifactKind = ArtifactKind> = Omit<ProfileArtifact<K>, 'id' | 'status'> & {
+    id?: string;
+    status?: ArtifactStatus;
+};
+
+/**
+ * `applyArtifact` — merge one `ProfileArtifact` onto an `AgentProfile`.
+ *
+ * This is the deterministic bridge between the artifact catalog and the §1.5
+ * profile law: each `ArtifactKind` lands on exactly one profile field. The merge
+ * is shallow-immutable — the input profile is never mutated; a new profile with
+ * the artifact applied is returned. This is the ONE place that knows how a
+ * `kind` maps to a profile field, so both the registry's `compose` and
+ * `measureMarginalLift`'s with/without ablation share a single source of truth.
+ */
+
+/**
+ * Return a new profile with `artifact` merged onto `base`. Keyed kinds
+ * (`tool`/`mcp`/`hook`/`subagent`) land under `artifact.key` (falling back to
+ * `artifact.id`). `prompt` appends an instruction line; `skill` appends a
+ * resource ref. Existing keys are overwritten by the artifact (the artifact is
+ * the candidate being measured/promoted, so it wins on conflict).
+ */
+declare function applyArtifact(base: AgentProfile, artifact: ProfileArtifact): AgentProfile;
+/** Apply many artifacts left-to-right; later artifacts win on key conflicts. */
+declare function applyArtifacts(base: AgentProfile, artifacts: readonly ProfileArtifact[]): AgentProfile;
+
+/**
+ * `measureMarginalLift` — the with-vs-without ablation for one artifact.
+ *
+ * "What does THIS one piece add?" is the question a lifecycle has to answer
+ * before it can promote anything. The answer is an ablation: score the baseline
+ * profile, score the baseline-plus-candidate profile, and report the delta. This
+ * is the marginal contribution of the artifact — the same shape the project's
+ * `OutcomeMeasurement` reports for an apply pass, but isolated to ONE artifact so
+ * a registry can rank candidates by what they individually earn.
+ *
+ * The measurement is selector-agnostic: it takes an `EvalRunner` the caller
+ * supplies (any function that scores a profile and reports cost), runs it twice,
+ * and subtracts. It never judges, never picks a winner, never re-scores on a
+ * holdout — those are the gate's job. It only quantifies the ablation so the gate
+ * has a real number to decide on.
+ */
+
+/**
+ * The result of running an eval over ONE profile: a composite score and the cost
+ * to obtain it. This mirrors the project's score/cost convention (`composite`
+ * from `OutcomeMeasurement`, `costUsd` from `LoopResult`), so a caller can pass a
+ * thin wrapper over `runLoop` / `runBenchmark` / `runAgentEval` directly.
+ */
+interface EvalResult {
+    /** Composite score in `[0, 1]` (higher is better) for the profile under test. */
+    composite: number;
+    /** USD cost to produce this result. */
+    costUsd: number;
+    /** Optional opaque passthrough (per-task cells, the raw report, …). */
+    details?: unknown;
+}
+/**
+ * Scores a profile. The caller wires this to whatever eval they run — a
+ * `runLoop` rollout, a `runBenchmark` campaign, a `runAgentEval` cohort — and
+ * returns the composite + cost. `signal` is forwarded for cancellation.
+ */
+type EvalRunner = (profile: AgentProfile, signal?: AbortSignal) => Promise<EvalResult>;
+interface MeasureMarginalLiftOptions {
+    /** The profile the artifact is measured ON TOP OF (the "without" arm). */
+    baseline: AgentProfile;
+    /** The single artifact whose marginal contribution we want. */
+    candidate: ProfileArtifact;
+    /** The eval that scores a profile. Run once per arm (twice total). */
+    evalRunner: EvalRunner;
+    /**
+     * A pre-computed baseline result, to skip the "without" run when the caller
+     * already scored the baseline (e.g. measuring several candidates against the
+     * same baseline). When set, the baseline arm is NOT re-run.
+     */
+    baselineResult?: EvalResult;
+    /** Forwarded to both `evalRunner` invocations for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * The marginal lift of one artifact: the with/without ablation.
+ *
+ * `scoreDelta = with.composite − without.composite`. A positive `scoreDelta` is
+ * the evidence a gate needs to promote; a negative one is the signal to drop the
+ * artifact. `costDelta` is the extra USD the artifact costs (often positive — a
+ * new tool/MCP adds calls) and lets the gate weigh lift against spend.
+ */
+interface MarginalLift {
+    /** The artifact id this measurement is for (stable, from the registry). */
+    artifactId: string;
+    /** Eval of `applyArtifact(baseline, candidate)`. */
+    withArtifact: EvalResult;
+    /** Eval of `baseline` alone. */
+    withoutArtifact: EvalResult;
+    /** `withArtifact.composite − withoutArtifact.composite`. */
+    scoreDelta: number;
+    /** `withArtifact.costUsd − withoutArtifact.costUsd`. */
+    costDelta: number;
+}
+/**
+ * Run the with/without ablation for `candidate` over `baseline` and return its
+ * marginal score/cost contribution.
+ *
+ * The "without" arm scores the baseline profile unchanged; the "with" arm scores
+ * `applyArtifact(baseline, candidate)`. Both use the same `evalRunner`, so the
+ * delta isolates the artifact's effect (eval method held constant). The baseline
+ * arm is skipped when `baselineResult` is supplied.
+ *
+ * @example
+ *   const lift = await measureMarginalLift({
+ *     baseline,
+ *     candidate: registry.get(id)!,
+ *     evalRunner: (profile) => scoreProfileOnCohort(profile),
+ *   })
+ *   if (lift.scoreDelta > 0) registry.promote(lift.artifactId)
+ */
+declare function measureMarginalLift(opts: MeasureMarginalLiftOptions): Promise<MarginalLift>;
+
+/**
+ * `ArtifactRegistry` — a typed catalog of profile artifacts with stable ids.
+ *
+ * The registry is the lifecycle's source of truth for "what pieces could go into
+ * this agent's profile". It holds `register` / `list` / `get` / `promote`, assigns
+ * stable ids, and can `compose` a subset of artifacts onto a baseline profile via
+ * the single `applyArtifact` bridge. It owns NO measurement, NO gate, NO LLM — it
+ * is a pure in-memory store so callers can persist/snapshot it however they like.
+ */
+
+/** Filter for `list`. Omit a field to leave that dimension unconstrained. */
+interface ArtifactQuery {
+    kind?: ArtifactKind;
+    status?: ArtifactStatus;
+}
+/**
+ * A typed, in-memory registry of `ProfileArtifact`s with stable ids.
+ *
+ * Ids are stable for the life of the registry: `register` assigns one (or honors
+ * a caller-supplied id idempotently), and no later operation reassigns it.
+ * Re-registering the same id REPLACES the artifact's mutable fields but preserves
+ * the id, so a re-proposed candidate keeps its identity across generations.
+ */
+declare class ArtifactRegistry {
+    private readonly artifacts;
+    private counter;
+    /**
+     * Register an artifact, returning the stored record (with its assigned id).
+     * When `input.id` is set it is honored (idempotent re-registration replaces
+     * the record under the same id); otherwise a stable id is minted as
+     * `<kind>-<n>`. `status` defaults to `'candidate'`.
+     */
+    register<K extends ArtifactKind>(input: ArtifactInput<K>): ProfileArtifact<K>;
+    /** Get an artifact by id, or `undefined` if it was never registered. */
+    get(id: string): ProfileArtifact | undefined;
+    /**
+     * List artifacts, optionally filtered by `kind` and/or `status`. Returns a new
+     * array in registration order; callers may safely sort/mutate the result.
+     */
+    list(query?: ArtifactQuery): ProfileArtifact[];
+    /**
+     * Mark an artifact `promoted`. Fails loud on an unknown id — promoting a
+     * non-existent artifact is a caller bug, not a no-op. Returns the updated
+     * record. Idempotent: promoting an already-promoted artifact is a no-op
+     * return.
+     */
+    promote(id: string): ProfileArtifact;
+    /**
+     * Compose a set of registered artifacts onto a baseline profile. With no ids
+     * given, composes every `promoted` artifact (the "ship the passing set"
+     * default). With explicit ids, composes exactly those (in id order given),
+     * failing loud on any unknown id. The applied order is the order passed (or
+     * registration order for the promoted-default), and later artifacts win on key
+     * conflicts — same semantics as `applyArtifacts`.
+     */
+    compose(base: AgentProfile, ids?: readonly string[]): AgentProfile;
+    /** Number of registered artifacts (any status). */
+    get size(): number;
+    private mintId;
+}
+/** Construct an empty `ArtifactRegistry`. */
+declare function createArtifactRegistry(): ArtifactRegistry;
+
+export { type ArtifactInput, type ArtifactKind, type ArtifactPayloads, type ArtifactQuery, ArtifactRegistry, type ArtifactStatus, type EvalResult, type EvalRunner, type MarginalLift, type MeasureMarginalLiftOptions, type ProfileArtifact, applyArtifact, applyArtifacts, createArtifactRegistry, measureMarginalLift };

package/dist/lifecycle.js

@@ -0,0 +1,174 @@
+import {
+  ValidationError
+} from "./chunk-NBV35BR6.js";
+import "./chunk-DGUM43GV.js";
+
+// src/lifecycle/apply.ts
+function applyArtifact(base, artifact) {
+  switch (artifact.kind) {
+    case "prompt": {
+      const payload = artifact.payload;
+      const instructions = [...base.prompt?.instructions ?? [], payload.instruction];
+      return { ...base, prompt: { ...base.prompt, instructions } };
+    }
+    case "skill": {
+      const payload = artifact.payload;
+      const skills = [...base.resources?.skills ?? [], payload.resource];
+      return { ...base, resources: { ...base.resources, skills } };
+    }
+    case "tool": {
+      const payload = artifact.payload;
+      const key = keyOf(artifact);
+      return { ...base, tools: { ...base.tools, [key]: payload.enabled } };
+    }
+    case "mcp": {
+      const payload = artifact.payload;
+      const key = keyOf(artifact);
+      return { ...base, mcp: { ...base.mcp, [key]: payload.server } };
+    }
+    case "hook": {
+      const payload = artifact.payload;
+      const existing = base.hooks?.[payload.event] ?? [];
+      return {
+        ...base,
+        hooks: { ...base.hooks, [payload.event]: [...existing, ...payload.commands] }
+      };
+    }
+    case "subagent": {
+      const payload = artifact.payload;
+      const key = keyOf(artifact);
+      return { ...base, subagents: { ...base.subagents, [key]: payload.profile } };
+    }
+  }
+}
+function applyArtifacts(base, artifacts) {
+  return artifacts.reduce((profile, artifact) => applyArtifact(profile, artifact), base);
+}
+function keyOf(artifact) {
+  return artifact.key ?? artifact.id;
+}
+
+// src/lifecycle/marginal-lift.ts
+async function measureMarginalLift(opts) {
+  const { baseline, candidate, evalRunner, baselineResult, signal } = opts;
+  const withoutArtifact = baselineResult ?? await evalRunner(baseline, signal);
+  const withProfile = applyArtifact(baseline, candidate);
+  const withArtifact = await evalRunner(withProfile, signal);
+  return {
+    artifactId: candidate.id,
+    withArtifact,
+    withoutArtifact,
+    scoreDelta: withArtifact.composite - withoutArtifact.composite,
+    costDelta: withArtifact.costUsd - withoutArtifact.costUsd
+  };
+}
+
+// src/lifecycle/registry.ts
+var ArtifactRegistry = class {
+  artifacts = /* @__PURE__ */ new Map();
+  counter = 0;
+  /**
+   * Register an artifact, returning the stored record (with its assigned id).
+   * When `input.id` is set it is honored (idempotent re-registration replaces
+   * the record under the same id); otherwise a stable id is minted as
+   * `<kind>-<n>`. `status` defaults to `'candidate'`.
+   */
+  register(input) {
+    const id = input.id ?? this.mintId(input.kind);
+    if (input.id !== void 0 && (input.id.length === 0 || input.id.trim() !== input.id)) {
+      throw new ValidationError(
+        `ArtifactRegistry.register: explicit id must be a non-empty, untrimmed-free string (got ${JSON.stringify(input.id)})`
+      );
+    }
+    const record = {
+      id,
+      kind: input.kind,
+      key: input.key,
+      name: input.name,
+      description: input.description,
+      payload: input.payload,
+      status: input.status ?? "candidate",
+      metadata: input.metadata
+    };
+    this.artifacts.set(id, record);
+    return record;
+  }
+  /** Get an artifact by id, or `undefined` if it was never registered. */
+  get(id) {
+    return this.artifacts.get(id);
+  }
+  /**
+   * List artifacts, optionally filtered by `kind` and/or `status`. Returns a new
+   * array in registration order; callers may safely sort/mutate the result.
+   */
+  list(query = {}) {
+    const out = [];
+    for (const artifact of this.artifacts.values()) {
+      if (query.kind !== void 0 && artifact.kind !== query.kind) continue;
+      if (query.status !== void 0 && artifact.status !== query.status) continue;
+      out.push(artifact);
+    }
+    return out;
+  }
+  /**
+   * Mark an artifact `promoted`. Fails loud on an unknown id — promoting a
+   * non-existent artifact is a caller bug, not a no-op. Returns the updated
+   * record. Idempotent: promoting an already-promoted artifact is a no-op
+   * return.
+   */
+  promote(id) {
+    const artifact = this.artifacts.get(id);
+    if (!artifact) {
+      throw new ValidationError(
+        `ArtifactRegistry.promote: no artifact with id ${JSON.stringify(id)} is registered`
+      );
+    }
+    if (artifact.status === "promoted") return artifact;
+    const promoted = { ...artifact, status: "promoted" };
+    this.artifacts.set(id, promoted);
+    return promoted;
+  }
+  /**
+   * Compose a set of registered artifacts onto a baseline profile. With no ids
+   * given, composes every `promoted` artifact (the "ship the passing set"
+   * default). With explicit ids, composes exactly those (in id order given),
+   * failing loud on any unknown id. The applied order is the order passed (or
+   * registration order for the promoted-default), and later artifacts win on key
+   * conflicts — same semantics as `applyArtifacts`.
+   */
+  compose(base, ids) {
+    const selected = ids === void 0 ? this.list({ status: "promoted" }) : ids.map((id) => {
+      const artifact = this.artifacts.get(id);
+      if (!artifact) {
+        throw new ValidationError(
+          `ArtifactRegistry.compose: no artifact with id ${JSON.stringify(id)} is registered`
+        );
+      }
+      return artifact;
+    });
+    return applyArtifacts(base, selected);
+  }
+  /** Number of registered artifacts (any status). */
+  get size() {
+    return this.artifacts.size;
+  }
+  mintId(kind) {
+    let id;
+    do {
+      this.counter += 1;
+      id = `${kind}-${this.counter}`;
+    } while (this.artifacts.has(id));
+    return id;
+  }
+};
+function createArtifactRegistry() {
+  return new ArtifactRegistry();
+}
+export {
+  ArtifactRegistry,
+  applyArtifact,
+  applyArtifacts,
+  createArtifactRegistry,
+  measureMarginalLift
+};
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lifecycle/apply.ts","../src/lifecycle/marginal-lift.ts","../src/lifecycle/registry.ts"],"sourcesContent":["/**\n * `applyArtifact` — merge one `ProfileArtifact` onto an `AgentProfile`.\n *\n * This is the deterministic bridge between the artifact catalog and the §1.5\n * profile law: each `ArtifactKind` lands on exactly one profile field. The merge\n * is shallow-immutable — the input profile is never mutated; a new profile with\n * the artifact applied is returned. This is the ONE place that knows how a\n * `kind` maps to a profile field, so both the registry's `compose` and\n * `measureMarginalLift`'s with/without ablation share a single source of truth.\n */\n\nimport type { AgentProfile } from '@tangle-network/agent-interface'\nimport type { ProfileArtifact } from './types'\n\n/**\n * Return a new profile with `artifact` merged onto `base`. Keyed kinds\n * (`tool`/`mcp`/`hook`/`subagent`) land under `artifact.key` (falling back to\n * `artifact.id`). `prompt` appends an instruction line; `skill` appends a\n * resource ref. Existing keys are overwritten by the artifact (the artifact is\n * the candidate being measured/promoted, so it wins on conflict).\n */\nexport function applyArtifact(base: AgentProfile, artifact: ProfileArtifact): AgentProfile {\n  switch (artifact.kind) {\n    case 'prompt': {\n      const payload = artifact.payload as { instruction: string }\n      const instructions = [...(base.prompt?.instructions ?? []), payload.instruction]\n      return { ...base, prompt: { ...base.prompt, instructions } }\n    }\n    case 'skill': {\n      const payload = artifact.payload as ProfileArtifact<'skill'>['payload']\n      const skills = [...(base.resources?.skills ?? []), payload.resource]\n      return { ...base, resources: { ...base.resources, skills } }\n    }\n    case 'tool': {\n      const payload = artifact.payload as ProfileArtifact<'tool'>['payload']\n      const key = keyOf(artifact)\n      return { ...base, tools: { ...base.tools, [key]: payload.enabled } }\n    }\n    case 'mcp': {\n      const payload = artifact.payload as ProfileArtifact<'mcp'>['payload']\n      const key = keyOf(artifact)\n      return { ...base, mcp: { ...base.mcp, [key]: payload.server } }\n    }\n    case 'hook': {\n      const payload = artifact.payload as ProfileArtifact<'hook'>['payload']\n      const existing = base.hooks?.[payload.event] ?? []\n      return {\n        ...base,\n        hooks: { ...base.hooks, [payload.event]: [...existing, ...payload.commands] },\n      }\n    }\n    case 'subagent': {\n      const payload = artifact.payload as ProfileArtifact<'subagent'>['payload']\n      const key = keyOf(artifact)\n      return { ...base, subagents: { ...base.subagents, [key]: payload.profile } }\n    }\n  }\n}\n\n/** Apply many artifacts left-to-right; later artifacts win on key conflicts. */\nexport function applyArtifacts(\n  base: AgentProfile,\n  artifacts: readonly ProfileArtifact[],\n): AgentProfile {\n  return artifacts.reduce((profile, artifact) => applyArtifact(profile, artifact), base)\n}\n\n/** The profile-field key a keyed artifact lands under: explicit `key` or `id`. */\nfunction keyOf(artifact: ProfileArtifact): string {\n  return artifact.key ?? artifact.id\n}\n","/**\n * `measureMarginalLift` — the with-vs-without ablation for one artifact.\n *\n * \"What does THIS one piece add?\" is the question a lifecycle has to answer\n * before it can promote anything. The answer is an ablation: score the baseline\n * profile, score the baseline-plus-candidate profile, and report the delta. This\n * is the marginal contribution of the artifact — the same shape the project's\n * `OutcomeMeasurement` reports for an apply pass, but isolated to ONE artifact so\n * a registry can rank candidates by what they individually earn.\n *\n * The measurement is selector-agnostic: it takes an `EvalRunner` the caller\n * supplies (any function that scores a profile and reports cost), runs it twice,\n * and subtracts. It never judges, never picks a winner, never re-scores on a\n * holdout — those are the gate's job. It only quantifies the ablation so the gate\n * has a real number to decide on.\n */\n\nimport type { AgentProfile } from '@tangle-network/agent-interface'\nimport { applyArtifact } from './apply'\nimport type { ProfileArtifact } from './types'\n\n/**\n * The result of running an eval over ONE profile: a composite score and the cost\n * to obtain it. This mirrors the project's score/cost convention (`composite`\n * from `OutcomeMeasurement`, `costUsd` from `LoopResult`), so a caller can pass a\n * thin wrapper over `runLoop` / `runBenchmark` / `runAgentEval` directly.\n */\nexport interface EvalResult {\n  /** Composite score in `[0, 1]` (higher is better) for the profile under test. */\n  composite: number\n  /** USD cost to produce this result. */\n  costUsd: number\n  /** Optional opaque passthrough (per-task cells, the raw report, …). */\n  details?: unknown\n}\n\n/**\n * Scores a profile. The caller wires this to whatever eval they run — a\n * `runLoop` rollout, a `runBenchmark` campaign, a `runAgentEval` cohort — and\n * returns the composite + cost. `signal` is forwarded for cancellation.\n */\nexport type EvalRunner = (profile: AgentProfile, signal?: AbortSignal) => Promise<EvalResult>\n\nexport interface MeasureMarginalLiftOptions {\n  /** The profile the artifact is measured ON TOP OF (the \"without\" arm). */\n  baseline: AgentProfile\n  /** The single artifact whose marginal contribution we want. */\n  candidate: ProfileArtifact\n  /** The eval that scores a profile. Run once per arm (twice total). */\n  evalRunner: EvalRunner\n  /**\n   * A pre-computed baseline result, to skip the \"without\" run when the caller\n   * already scored the baseline (e.g. measuring several candidates against the\n   * same baseline). When set, the baseline arm is NOT re-run.\n   */\n  baselineResult?: EvalResult\n  /** Forwarded to both `evalRunner` invocations for cancellation. */\n  signal?: AbortSignal\n}\n\n/**\n * The marginal lift of one artifact: the with/without ablation.\n *\n * `scoreDelta = with.composite − without.composite`. A positive `scoreDelta` is\n * the evidence a gate needs to promote; a negative one is the signal to drop the\n * artifact. `costDelta` is the extra USD the artifact costs (often positive — a\n * new tool/MCP adds calls) and lets the gate weigh lift against spend.\n */\nexport interface MarginalLift {\n  /** The artifact id this measurement is for (stable, from the registry). */\n  artifactId: string\n  /** Eval of `applyArtifact(baseline, candidate)`. */\n  withArtifact: EvalResult\n  /** Eval of `baseline` alone. */\n  withoutArtifact: EvalResult\n  /** `withArtifact.composite − withoutArtifact.composite`. */\n  scoreDelta: number\n  /** `withArtifact.costUsd − withoutArtifact.costUsd`. */\n  costDelta: number\n}\n\n/**\n * Run the with/without ablation for `candidate` over `baseline` and return its\n * marginal score/cost contribution.\n *\n * The \"without\" arm scores the baseline profile unchanged; the \"with\" arm scores\n * `applyArtifact(baseline, candidate)`. Both use the same `evalRunner`, so the\n * delta isolates the artifact's effect (eval method held constant). The baseline\n * arm is skipped when `baselineResult` is supplied.\n *\n * @example\n *   const lift = await measureMarginalLift({\n *     baseline,\n *     candidate: registry.get(id)!,\n *     evalRunner: (profile) => scoreProfileOnCohort(profile),\n *   })\n *   if (lift.scoreDelta > 0) registry.promote(lift.artifactId)\n */\nexport async function measureMarginalLift(opts: MeasureMarginalLiftOptions): Promise<MarginalLift> {\n  const { baseline, candidate, evalRunner, baselineResult, signal } = opts\n\n  const withoutArtifact = baselineResult ?? (await evalRunner(baseline, signal))\n  const withProfile = applyArtifact(baseline, candidate)\n  const withArtifact = await evalRunner(withProfile, signal)\n\n  return {\n    artifactId: candidate.id,\n    withArtifact,\n    withoutArtifact,\n    scoreDelta: withArtifact.composite - withoutArtifact.composite,\n    costDelta: withArtifact.costUsd - withoutArtifact.costUsd,\n  }\n}\n","/**\n * `ArtifactRegistry` — a typed catalog of profile artifacts with stable ids.\n *\n * The registry is the lifecycle's source of truth for \"what pieces could go into\n * this agent's profile\". It holds `register` / `list` / `get` / `promote`, assigns\n * stable ids, and can `compose` a subset of artifacts onto a baseline profile via\n * the single `applyArtifact` bridge. It owns NO measurement, NO gate, NO LLM — it\n * is a pure in-memory store so callers can persist/snapshot it however they like.\n */\n\nimport type { AgentProfile } from '@tangle-network/agent-interface'\nimport { ValidationError } from '../errors'\nimport { applyArtifacts } from './apply'\nimport type { ArtifactInput, ArtifactKind, ArtifactStatus, ProfileArtifact } from './types'\n\n/** Filter for `list`. Omit a field to leave that dimension unconstrained. */\nexport interface ArtifactQuery {\n  kind?: ArtifactKind\n  status?: ArtifactStatus\n}\n\n/**\n * A typed, in-memory registry of `ProfileArtifact`s with stable ids.\n *\n * Ids are stable for the life of the registry: `register` assigns one (or honors\n * a caller-supplied id idempotently), and no later operation reassigns it.\n * Re-registering the same id REPLACES the artifact's mutable fields but preserves\n * the id, so a re-proposed candidate keeps its identity across generations.\n */\nexport class ArtifactRegistry {\n  private readonly artifacts = new Map<string, ProfileArtifact>()\n  private counter = 0\n\n  /**\n   * Register an artifact, returning the stored record (with its assigned id).\n   * When `input.id` is set it is honored (idempotent re-registration replaces\n   * the record under the same id); otherwise a stable id is minted as\n   * `<kind>-<n>`. `status` defaults to `'candidate'`.\n   */\n  register<K extends ArtifactKind>(input: ArtifactInput<K>): ProfileArtifact<K> {\n    const id = input.id ?? this.mintId(input.kind)\n    if (input.id !== undefined && (input.id.length === 0 || input.id.trim() !== input.id)) {\n      throw new ValidationError(\n        `ArtifactRegistry.register: explicit id must be a non-empty, untrimmed-free string (got ${JSON.stringify(input.id)})`,\n      )\n    }\n    const record: ProfileArtifact<K> = {\n      id,\n      kind: input.kind,\n      key: input.key,\n      name: input.name,\n      description: input.description,\n      payload: input.payload,\n      status: input.status ?? 'candidate',\n      metadata: input.metadata,\n    }\n    this.artifacts.set(id, record as ProfileArtifact)\n    return record\n  }\n\n  /** Get an artifact by id, or `undefined` if it was never registered. */\n  get(id: string): ProfileArtifact | undefined {\n    return this.artifacts.get(id)\n  }\n\n  /**\n   * List artifacts, optionally filtered by `kind` and/or `status`. Returns a new\n   * array in registration order; callers may safely sort/mutate the result.\n   */\n  list(query: ArtifactQuery = {}): ProfileArtifact[] {\n    const out: ProfileArtifact[] = []\n    for (const artifact of this.artifacts.values()) {\n      if (query.kind !== undefined && artifact.kind !== query.kind) continue\n      if (query.status !== undefined && artifact.status !== query.status) continue\n      out.push(artifact)\n    }\n    return out\n  }\n\n  /**\n   * Mark an artifact `promoted`. Fails loud on an unknown id — promoting a\n   * non-existent artifact is a caller bug, not a no-op. Returns the updated\n   * record. Idempotent: promoting an already-promoted artifact is a no-op\n   * return.\n   */\n  promote(id: string): ProfileArtifact {\n    const artifact = this.artifacts.get(id)\n    if (!artifact) {\n      throw new ValidationError(\n        `ArtifactRegistry.promote: no artifact with id ${JSON.stringify(id)} is registered`,\n      )\n    }\n    if (artifact.status === 'promoted') return artifact\n    const promoted: ProfileArtifact = { ...artifact, status: 'promoted' }\n    this.artifacts.set(id, promoted)\n    return promoted\n  }\n\n  /**\n   * Compose a set of registered artifacts onto a baseline profile. With no ids\n   * given, composes every `promoted` artifact (the \"ship the passing set\"\n   * default). With explicit ids, composes exactly those (in id order given),\n   * failing loud on any unknown id. The applied order is the order passed (or\n   * registration order for the promoted-default), and later artifacts win on key\n   * conflicts — same semantics as `applyArtifacts`.\n   */\n  compose(base: AgentProfile, ids?: readonly string[]): AgentProfile {\n    const selected =\n      ids === undefined\n        ? this.list({ status: 'promoted' })\n        : ids.map((id) => {\n            const artifact = this.artifacts.get(id)\n            if (!artifact) {\n              throw new ValidationError(\n                `ArtifactRegistry.compose: no artifact with id ${JSON.stringify(id)} is registered`,\n              )\n            }\n            return artifact\n          })\n    return applyArtifacts(base, selected)\n  }\n\n  /** Number of registered artifacts (any status). */\n  get size(): number {\n    return this.artifacts.size\n  }\n\n  private mintId(kind: ArtifactKind): string {\n    let id: string\n    do {\n      this.counter += 1\n      id = `${kind}-${this.counter}`\n    } while (this.artifacts.has(id))\n    return id\n  }\n}\n\n/** Construct an empty `ArtifactRegistry`. */\nexport function createArtifactRegistry(): ArtifactRegistry {\n  return new ArtifactRegistry()\n}\n"],"mappings":"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","names":[]}

package/dist/{loop-runner-bin-B7biH0Gk.d.ts → loop-runner-bin-eD3m0rHW.d.ts}

@@ -2,8 +2,8 @@ import { Scenario } from '@tangle-network/agent-eval/campaign';
 import { SelfImproveOptions, SelfImproveResult } from '@tangle-network/agent-eval/contract';
 import { R as RunAnalystLoopOpts, a as RunAnalystLoopResult } from './types-BC3bZpH0.js';
 import { F as FactCandidate, C as CreateKbGateOptions } from './kb-gate-CuzMYGYM.js';
-import { B as Budget } from './worktree-JXGJ1MxQ.js';
-import { A as AuthoredHarness, W as WinnerStrategy, a as WorktreeFanoutOptions, b as WorktreePatchArtifact } from './worktree-fanout-DJHQy7Ux.js';
+import { B as Budget } from './worktree-DaxOvw-C.js';
+import { A as AuthoredHarness, W as WinnerStrategy, a as WorktreeFanoutOptions, b as WorktreePatchArtifact } from './worktree-fanout-DIffZohV.js';
 
 /**
  * @experimental

package/dist/loop-runner-bin.d.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-export { L as LoopRunnerCliArgs, e as LoopRunnerCliResult, p as parseLoopRunnerArgv, k as runLoopRunnerCli } from './loop-runner-bin-B7biH0Gk.js';
+export { L as LoopRunnerCliArgs, e as LoopRunnerCliResult, p as parseLoopRunnerArgv, k as runLoopRunnerCli } from './loop-runner-bin-eD3m0rHW.js';
 import '@tangle-network/agent-eval/campaign';
 import '@tangle-network/agent-eval/contract';
 import './types-BC3bZpH0.js';
 import '@tangle-network/agent-eval';
 import './kb-gate-CuzMYGYM.js';
-import './worktree-JXGJ1MxQ.js';
+import './worktree-DaxOvw-C.js';
 import 'node:child_process';
 import '@tangle-network/agent-interface';
 import '@tangle-network/sandbox';
-import './types-K8-xkiw1.js';
-import './worktree-fanout-DJHQy7Ux.js';
+import './types-JufmXF2a.js';
+import './worktree-fanout-DIffZohV.js';

package/dist/loop-runner-bin.js

@@ -2,13 +2,14 @@
 import {
   parseLoopRunnerArgv,
   runLoopRunnerCli
-} from "./chunk-HXVMLRYU.js";
-import "./chunk-P5OKDSLB.js";
+} from "./chunk-U56XGKVY.js";
 import "./chunk-FNMGYYSS.js";
-import "./chunk-PHKNOAOU.js";
-import "./chunk-55WKGOGU.js";
+import "./chunk-HPYWEFVY.js";
+import "./chunk-NCH4XUZ7.js";
 import "./chunk-VMNEQHJR.js";
-import "./chunk-VLF5RHEQ.js";
+import "./chunk-IODKUOBA.js";
+import "./chunk-T2HVQVB4.js";
+import "./chunk-NBV35BR6.js";
 import "./chunk-WIR4HOOJ.js";
 import "./chunk-DGUM43GV.js";
 export {