@tangle-network/agent-eval 0.46.0 → 0.47.0

package/dist/chunk-ZQABFCVJ.js

@@ -0,0 +1,85 @@
+// src/hosted/types.ts
+var HOSTED_WIRE_VERSION = "2026-05-26.v1";
+
+// src/hosted/client.ts
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t.unref === "function") t.unref();
+  });
+}
+async function post(tenant, path, body, opts = {}) {
+  const timeoutMs = tenant.timeoutMs ?? 3e4;
+  const maxRetries = tenant.retries ?? 2;
+  const f = tenant.fetchImpl ?? ((...args) => fetch(...args));
+  const url = `${tenant.endpoint.replace(/\/$/, "")}${path}`;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const ourTimeout = AbortSignal.timeout(timeoutMs);
+    const combinedSignal = opts.signal ? AbortSignal.any([opts.signal, ourTimeout]) : ourTimeout;
+    try {
+      const headers = {
+        "content-type": "application/json",
+        authorization: `Bearer ${tenant.apiKey}`,
+        "x-tangle-tenant-id": tenant.tenantId,
+        "x-tangle-wire-version": HOSTED_WIRE_VERSION
+      };
+      if (opts.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
+      const res = await f(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: combinedSignal
+      });
+      if (!res.ok) {
+        const retryable = res.status >= 500 || res.status === 408 || res.status === 429;
+        if (!retryable || attempt === maxRetries) {
+          const text = await res.text().catch(() => "");
+          throw new Error(`hosted ingest ${url} failed (${res.status}): ${text.slice(0, 500)}`);
+        }
+        await sleep(2 ** attempt * 200 + Math.random() * 200);
+        continue;
+      }
+      return await res.json();
+    } catch (err) {
+      if (opts.signal?.aborted) throw err;
+      lastError = err;
+      if (attempt === maxRetries) throw err;
+      await sleep(2 ** attempt * 200 + Math.random() * 200);
+    }
+  }
+  throw lastError ?? new Error("hosted ingest exhausted retries");
+}
+function createHostedClient(tenant) {
+  return {
+    tenant,
+    wireVersion: HOSTED_WIRE_VERSION,
+    async ingestEvalRun(event, idempotencyKey) {
+      return this.ingestEvalRuns([event], idempotencyKey);
+    },
+    async ingestEvalRuns(events, idempotencyKey) {
+      const body = { wireVersion: HOSTED_WIRE_VERSION, events };
+      return post(
+        tenant,
+        "/v1/ingest/eval-runs",
+        body,
+        { idempotencyKey }
+      );
+    },
+    async ingestTraces(spans, idempotencyKey) {
+      const body = { wireVersion: HOSTED_WIRE_VERSION, spans };
+      return post(
+        tenant,
+        "/v1/ingest/traces",
+        body,
+        { idempotencyKey }
+      );
+    }
+  };
+}
+
+export {
+  HOSTED_WIRE_VERSION,
+  createHostedClient
+};
+//# sourceMappingURL=chunk-ZQABFCVJ.js.map

package/dist/chunk-ZQABFCVJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hosted/types.ts","../src/hosted/client.ts"],"sourcesContent":["/**\n * # Hosted-tier wire format — the schema that EVERY orchestrator (ours,\n * a partner's self-hosted one, a future open implementation) must accept.\n *\n * **Stability:** every type in this file is committed under semver. New\n * minors only ADD optional fields. Breaking changes mean a major bump\n * (`HostedWireVersion` literal increment).\n *\n * The wire format is two event streams in one transport:\n *\n *   1. **Eval-run events** (`POST /v1/ingest/eval-runs`). Posted when a\n *      campaign / improvement-loop completes (or per-generation if\n *      streaming). Carries the structured result + per-cell scores +\n *      surface diffs the orchestrator stores for the dashboard.\n *\n *   2. **Trace spans** (`POST /v1/ingest/traces`). Standard OTLP-shaped\n *      spans with a few additional attributes so the orchestrator can\n *      pivot from eval-run → underlying execution. Compatible with any\n *      OTel collector.\n *\n * Both endpoints are authenticated with a bearer token + a tenant id\n * header. Tenants isolate everything downstream of ingest; no tenant\n * ever sees another tenant's data.\n */\n\nimport type { GateDecision, MutableSurface } from '../campaign/types'\n\nexport const HOSTED_WIRE_VERSION = '2026-05-26.v1' as const\nexport type HostedWireVersion = typeof HOSTED_WIRE_VERSION\n\n// ── Transport headers ───────────────────────────────────────────────\n\n/** Every ingest request carries these. */\nexport interface HostedIngestHeaders {\n  /** Bearer token. The orchestrator validates against the tenant key. */\n  authorization: `Bearer ${string}`\n  /** Stable tenant id (the orchestrator-side primary key for the tenant). */\n  'x-tangle-tenant-id': string\n  /** Wire-version pin so the server can reject incompatible payloads. */\n  'x-tangle-wire-version': HostedWireVersion\n  /** Optional idempotency key for retry-safe ingest. */\n  'idempotency-key'?: string\n}\n\n// ── Eval-run event ──────────────────────────────────────────────────\n\n/** Lifecycle stages of an eval-run as the substrate reports them. */\nexport type EvalRunStatus = 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored'\n\nexport interface EvalRunCellScore {\n  /** Stable scenario id from the consumer's scenario set. */\n  scenarioId: string\n  /** Repetition index when reps > 1; 0 for the default. */\n  rep: number\n  /** Composite score across all judges + dimensions for this cell. */\n  compositeMean: number\n  /** Per-judge → per-dimension scores; null where the judge did not run. */\n  dimensions: Record<string, Record<string, number>>\n  /** Per-cell error message if the dispatch threw. Null on success. */\n  errorMessage?: string\n}\n\nexport interface EvalRunGenerationSnapshot {\n  /** Generation index. 0 is baseline. */\n  index: number\n  /** Candidate surface fingerprint (stable hash) — pivot key into the\n   *  trace stream to fetch the underlying execution. */\n  surfaceHash: string\n  /** The candidate surface itself. May be omitted to avoid PII when the\n   *  consumer prefers not to ship verbatim prompts. */\n  surface?: MutableSurface\n  /** Per-cell scores for this generation. */\n  cells: EvalRunCellScore[]\n  /** Aggregate composite mean across all cells in this generation. */\n  compositeMean: number\n  /** Total $ spent across this generation. */\n  costUsd: number\n  /** Wall-clock duration of this generation. */\n  durationMs: number\n}\n\n/**\n * The top-level eval-run event. One ingest call per logical eval-run;\n * generations stream in incrementally via repeated calls with the same\n * `runId`. The orchestrator deduplicates by `(runId, generation.index)`.\n */\nexport interface EvalRunEvent {\n  /** Stable run id (the substrate's `runId`). UUID or substrate-generated. */\n  runId: string\n  /** Where this run was happening — derived from `RunCampaignOptions.runDir`. */\n  runDir: string\n  /** ISO-8601 timestamp the substrate recorded the event. */\n  timestamp: string\n  /** Lifecycle stage this event represents. */\n  status: EvalRunStatus\n  /** Free-form consumer tags (env, branch, model id, etc.). Searchable. */\n  labels: Record<string, string>\n  /** Baseline campaign snapshot. Present when status >= baseline-complete. */\n  baseline?: EvalRunGenerationSnapshot\n  /** Per-generation snapshots. Streams in; orchestrator appends. */\n  generations: EvalRunGenerationSnapshot[]\n  /** Final gate decision. Present when status >= gate-decided. */\n  gateDecision?: GateDecision\n  /** Held-out lift = winner-on-holdout - baseline-on-holdout. */\n  holdoutLift?: number\n  /** Total $ spent across baseline + every generation. */\n  totalCostUsd: number\n  /** Total wall-clock duration. */\n  totalDurationMs: number\n  /** Error message if status === 'errored'. */\n  errorMessage?: string\n}\n\n// ── Trace span event ────────────────────────────────────────────────\n\n/**\n * OTel-shape span with a few additional attributes for eval-run pivoting.\n * Compatible with any OTLP collector — `name`, `traceId`, `spanId`,\n * `startTimeUnixNano`, `endTimeUnixNano`, `attributes` are stock OTel.\n */\nexport interface TraceSpanEvent {\n  traceId: string\n  spanId: string\n  parentSpanId?: string\n  name: string\n  startTimeUnixNano: number\n  endTimeUnixNano: number\n  attributes: Record<string, string | number | boolean>\n  events?: Array<{ timeUnixNano: number; name: string; attributes?: Record<string, string | number | boolean> }>\n  status?: { code: 'OK' | 'ERROR' | 'UNSET'; message?: string }\n  /** Pivot back into the eval-run stream. */\n  'tangle.runId'?: string\n  /** Pivot to the specific generation. */\n  'tangle.generation'?: number\n  /** Pivot to the specific cell. */\n  'tangle.cellId'?: string\n  /** Pivot to the specific scenario. */\n  'tangle.scenarioId'?: string\n}\n\n// ── Ingest request bodies ───────────────────────────────────────────\n\nexport interface IngestEvalRunsRequest {\n  wireVersion: HostedWireVersion\n  events: EvalRunEvent[]\n}\n\nexport interface IngestTracesRequest {\n  wireVersion: HostedWireVersion\n  spans: TraceSpanEvent[]\n}\n\nexport interface IngestResponse {\n  /** Accepted events / spans count. */\n  accepted: number\n  /** Rejected events with reasons (validation failures, dup idempotency key, etc.). */\n  rejected: Array<{ index: number; reason: string }>\n}\n","/**\n * # Hosted-tier ingest client.\n *\n * Ships eval-run events + trace spans to any orchestrator (ours, a\n * partner's self-hosted one, or a future open implementation) that\n * speaks the wire format in `./types.ts`.\n *\n * Three modes:\n *   - **Ours:** point at `https://orchestrator.tangle.tools/v1`. We\n *     handle ingest + storage + dashboard.\n *   - **Self-hosted:** point at whatever URL runs the reference receiver\n *     from `examples/hosted-ingest-server/`.\n *   - **Off (default):** when `hostedTenant` is unset, nothing is sent.\n *     Everything stays local.\n */\n\nimport {\n  HOSTED_WIRE_VERSION,\n  type EvalRunEvent,\n  type HostedWireVersion,\n  type IngestEvalRunsRequest,\n  type IngestResponse,\n  type IngestTracesRequest,\n  type TraceSpanEvent,\n} from './types'\n\nexport interface HostedTenant {\n  /** Orchestrator endpoint base URL (no trailing slash). Required. */\n  endpoint: string\n  /** Bearer token issued by the orchestrator. Required. */\n  apiKey: string\n  /** Tenant id — the orchestrator's primary key for this consumer. Required. */\n  tenantId: string\n  /** Optional `fetch` override (auth wrappers, custom agent, test mocks). */\n  fetchImpl?: typeof fetch\n  /** Per-call timeout in ms. Default 30s. */\n  timeoutMs?: number\n  /** Retries on 5xx / network errors. Default 2. */\n  retries?: number\n}\n\nexport interface HostedClient {\n  ingestEvalRun(event: EvalRunEvent, idempotencyKey?: string): Promise<IngestResponse>\n  ingestEvalRuns(events: EvalRunEvent[], idempotencyKey?: string): Promise<IngestResponse>\n  ingestTraces(spans: TraceSpanEvent[], idempotencyKey?: string): Promise<IngestResponse>\n  readonly tenant: HostedTenant\n  readonly wireVersion: HostedWireVersion\n}\n\ninterface RequestOptions {\n  idempotencyKey?: string\n  signal?: AbortSignal\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    const t = setTimeout(resolve, ms)\n    if (typeof (t as { unref?: () => void }).unref === 'function') (t as { unref: () => void }).unref()\n  })\n}\n\nasync function post<TReq, TRes>(\n  tenant: HostedTenant,\n  path: string,\n  body: TReq,\n  opts: RequestOptions = {},\n): Promise<TRes> {\n  const timeoutMs = tenant.timeoutMs ?? 30_000\n  const maxRetries = tenant.retries ?? 2\n  const f: typeof fetch = tenant.fetchImpl ?? ((...args) => fetch(...args))\n  const url = `${tenant.endpoint.replace(/\\/$/, '')}${path}`\n\n  let lastError: unknown\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    const ourTimeout = AbortSignal.timeout(timeoutMs)\n    const combinedSignal = opts.signal ? AbortSignal.any([opts.signal, ourTimeout]) : ourTimeout\n    try {\n      const headers: Record<string, string> = {\n        'content-type': 'application/json',\n        authorization: `Bearer ${tenant.apiKey}`,\n        'x-tangle-tenant-id': tenant.tenantId,\n        'x-tangle-wire-version': HOSTED_WIRE_VERSION,\n      }\n      if (opts.idempotencyKey) headers['idempotency-key'] = opts.idempotencyKey\n\n      const res = await f(url, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(body),\n        signal: combinedSignal,\n      })\n      if (!res.ok) {\n        const retryable = res.status >= 500 || res.status === 408 || res.status === 429\n        if (!retryable || attempt === maxRetries) {\n          const text = await res.text().catch(() => '')\n          throw new Error(`hosted ingest ${url} failed (${res.status}): ${text.slice(0, 500)}`)\n        }\n        await sleep(2 ** attempt * 200 + Math.random() * 200)\n        continue\n      }\n      return (await res.json()) as TRes\n    } catch (err) {\n      if (opts.signal?.aborted) throw err\n      lastError = err\n      if (attempt === maxRetries) throw err\n      await sleep(2 ** attempt * 200 + Math.random() * 200)\n    }\n  }\n  throw lastError ?? new Error('hosted ingest exhausted retries')\n}\n\nexport function createHostedClient(tenant: HostedTenant): HostedClient {\n  return {\n    tenant,\n    wireVersion: HOSTED_WIRE_VERSION,\n\n    async ingestEvalRun(event, idempotencyKey) {\n      return this.ingestEvalRuns([event], idempotencyKey)\n    },\n\n    async ingestEvalRuns(events, idempotencyKey) {\n      const body: IngestEvalRunsRequest = { wireVersion: HOSTED_WIRE_VERSION, events }\n      return post<IngestEvalRunsRequest, IngestResponse>(\n        tenant,\n        '/v1/ingest/eval-runs',\n        body,\n        { idempotencyKey },\n      )\n    },\n\n    async ingestTraces(spans, idempotencyKey) {\n      const body: IngestTracesRequest = { wireVersion: HOSTED_WIRE_VERSION, spans }\n      return post<IngestTracesRequest, IngestResponse>(\n        tenant,\n        '/v1/ingest/traces',\n        body,\n        { idempotencyKey },\n      )\n    },\n  }\n}\n"],"mappings":";AA2BO,IAAM,sBAAsB;;;AC2BnC,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,IAAI,WAAW,SAAS,EAAE;AAChC,QAAI,OAAQ,EAA6B,UAAU,WAAY,CAAC,EAA4B,MAAM;AAAA,EACpG,CAAC;AACH;AAEA,eAAe,KACb,QACA,MACA,MACA,OAAuB,CAAC,GACT;AACf,QAAM,YAAY,OAAO,aAAa;AACtC,QAAM,aAAa,OAAO,WAAW;AACrC,QAAM,IAAkB,OAAO,cAAc,IAAI,SAAS,MAAM,GAAG,IAAI;AACvE,QAAM,MAAM,GAAG,OAAO,SAAS,QAAQ,OAAO,EAAE,CAAC,GAAG,IAAI;AAExD,MAAI;AACJ,WAAS,UAAU,GAAG,WAAW,YAAY,WAAW;AACtD,UAAM,aAAa,YAAY,QAAQ,SAAS;AAChD,UAAM,iBAAiB,KAAK,SAAS,YAAY,IAAI,CAAC,KAAK,QAAQ,UAAU,CAAC,IAAI;AAClF,QAAI;AACF,YAAM,UAAkC;AAAA,QACtC,gBAAgB;AAAA,QAChB,eAAe,UAAU,OAAO,MAAM;AAAA,QACtC,sBAAsB,OAAO;AAAA,QAC7B,yBAAyB;AAAA,MAC3B;AACA,UAAI,KAAK,eAAgB,SAAQ,iBAAiB,IAAI,KAAK;AAE3D,YAAM,MAAM,MAAM,EAAE,KAAK;AAAA,QACvB,QAAQ;AAAA,QACR;AAAA,QACA,MAAM,KAAK,UAAU,IAAI;AAAA,QACzB,QAAQ;AAAA,MACV,CAAC;AACD,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,YAAY,IAAI,UAAU,OAAO,IAAI,WAAW,OAAO,IAAI,WAAW;AAC5E,YAAI,CAAC,aAAa,YAAY,YAAY;AACxC,gBAAM,OAAO,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC5C,gBAAM,IAAI,MAAM,iBAAiB,GAAG,YAAY,IAAI,MAAM,MAAM,KAAK,MAAM,GAAG,GAAG,CAAC,EAAE;AAAA,QACtF;AACA,cAAM,MAAM,KAAK,UAAU,MAAM,KAAK,OAAO,IAAI,GAAG;AACpD;AAAA,MACF;AACA,aAAQ,MAAM,IAAI,KAAK;AAAA,IACzB,SAAS,KAAK;AACZ,UAAI,KAAK,QAAQ,QAAS,OAAM;AAChC,kBAAY;AACZ,UAAI,YAAY,WAAY,OAAM;AAClC,YAAM,MAAM,KAAK,UAAU,MAAM,KAAK,OAAO,IAAI,GAAG;AAAA,IACtD;AAAA,EACF;AACA,QAAM,aAAa,IAAI,MAAM,iCAAiC;AAChE;AAEO,SAAS,mBAAmB,QAAoC;AACrE,SAAO;AAAA,IACL;AAAA,IACA,aAAa;AAAA,IAEb,MAAM,cAAc,OAAO,gBAAgB;AACzC,aAAO,KAAK,eAAe,CAAC,KAAK,GAAG,cAAc;AAAA,IACpD;AAAA,IAEA,MAAM,eAAe,QAAQ,gBAAgB;AAC3C,YAAM,OAA8B,EAAE,aAAa,qBAAqB,OAAO;AAC/E,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA,EAAE,eAAe;AAAA,MACnB;AAAA,IACF;AAAA,IAEA,MAAM,aAAa,OAAO,gBAAgB;AACxC,YAAM,OAA4B,EAAE,aAAa,qBAAqB,MAAM;AAC5E,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA,EAAE,eAAe;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/contract/index.d.ts

@@ -3,6 +3,7 @@ export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCell
 import { C as CampaignStorage, R as RunImprovementLoopResult } from '../run-improvement-loop-Bfam3MT1.js';
 export { D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, a as RunCampaignOptions, b as RunEvalOptions, c as RunImprovementLoopOptions, d as composeGate, e as defaultProductionGate, f as evolutionaryDriver, g as fsCampaignStorage, h as gepaDriver, i as heldOutGate, j as inMemoryCampaignStorage, r as runCampaign, k as runEval, l as runImprovementLoop } from '../run-improvement-loop-Bfam3MT1.js';
 export { D as DeploymentOutcome, F as FileSystemOutcomeStore, a as FileSystemOutcomeStoreOptions, I as InMemoryOutcomeStore, O as OutcomeStore } from '../outcome-store-BxJ3DQKJ.js';
+import { HostedTenant } from '../hosted/index.js';
 import '../llm-client-BXVRUZyX.js';
 import '../errors-mje_cKOs.js';
 import '../raw-provider-sink-C46HDghv.js';
@@ -145,6 +146,23 @@ interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {
     autoOnPromote?: 'pr' | 'none';
     ghOwner?: string;
     ghRepo?: string;
+    /**
+     * Opt-in: ship eval-run events to a hosted orchestrator (ours, your
+     * self-hosted one, or any compatible implementation of the
+     * `docs/hosted-ingest-spec.md` wire format). When set, the substrate
+     * POSTs the final `EvalRunEvent` to `${endpoint}/v1/ingest/eval-runs`
+     * after the loop completes. Failures are logged but do not fail the
+     * loop — local result is always returned.
+     *
+     * For our orchestrator: `{ endpoint: 'https://orchestrator.tangle.tools/v1', apiKey, tenantId }`.
+     *
+     * For your self-hosted: any URL serving the wire format. See
+     * `examples/hosted-ingest-server/` for the reference receiver.
+     */
+    hostedTenant?: HostedTenant;
+    /** Free-form labels attached to the hosted event (env, branch, model id,
+     *  etc.). Ignored when `hostedTenant` is unset. */
+    hostedLabels?: Record<string, string>;
 }
 interface SelfImproveResult<TScenario extends Scenario, TArtifact> {
     /** Composite mean across all scenarios, baseline run. */

package/dist/contract/index.js

@@ -7,6 +7,9 @@ import {
   runEval,
   runImprovementLoop
 } from "../chunk-HRKOCLQA.js";
+import {
+  createHostedClient
+} from "../chunk-ZQABFCVJ.js";
 import {
   fsCampaignStorage,
   inMemoryCampaignStorage,
@@ -74,7 +77,9 @@ async function selfImprove(opts) {
     holdout: explicitHoldout
   } : splitTrainHoldout(opts.scenarios, holdoutFraction);
   if (train.length === 0) {
-    throw new Error("selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.");
+    throw new Error(
+      "selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios."
+    );
   }
   if (holdout.length === 0) {
     throw new Error("selfImprove: holdout split is empty. Pass more scenarios.");
@@ -134,7 +139,7 @@ async function selfImprove(opts) {
     (sum, gen) => sum + gen.surfaces.reduce((s, sf) => s + sf.campaign.aggregates.totalCostUsd, 0),
     0
   );
-  return {
+  const summary = {
     baseline,
     winner: {
       ...winnerStats,
@@ -147,6 +152,81 @@ async function selfImprove(opts) {
     totalCostUsd: totalCost,
     raw: result
   };
+  if (opts.hostedTenant) {
+    try {
+      await shipEvalRunToHosted(opts.hostedTenant, opts, summary, result, runDir);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[agent-eval] hosted ingest failed (continuing): ${msg}`);
+    }
+  }
+  return summary;
+}
+async function shipEvalRunToHosted(tenant, opts, summary, raw, runDir) {
+  const client = createHostedClient(tenant);
+  function snapshotFromCampaign(index, surface, campaign, durationMs) {
+    const cells = campaign.cells.map((cell) => {
+      const judgeScores = Object.values(cell.judgeScores);
+      const composite = judgeScores.length === 0 ? 0 : judgeScores.reduce((s, j) => s + j.composite, 0) / judgeScores.length;
+      return {
+        scenarioId: cell.scenarioId,
+        rep: cell.rep,
+        compositeMean: composite,
+        dimensions: Object.fromEntries(
+          Object.entries(cell.judgeScores).map(([name, score]) => [name, score.dimensions])
+        ),
+        errorMessage: cell.error ?? void 0
+      };
+    });
+    const compositeMean = cells.length === 0 ? 0 : cells.reduce((s, c) => s + c.compositeMean, 0) / cells.length;
+    return {
+      index,
+      surfaceHash: typeof surface === "string" ? hashString(surface) : hashString(JSON.stringify(surface ?? "")),
+      surface,
+      cells,
+      compositeMean,
+      costUsd: campaign.aggregates.totalCostUsd,
+      durationMs
+    };
+  }
+  const generations = [];
+  generations.push(snapshotFromCampaign(0, opts.baselineSurface, raw.baselineCampaign, 0));
+  for (const gen of raw.generations) {
+    const winner = gen.surfaces.reduce(
+      (best, s) => s.campaign.aggregates.cellsExecuted > 0 && (best === void 0 || averageComposite(s.campaign) > averageComposite(best.campaign)) ? s : best,
+      gen.surfaces[0]
+    );
+    if (!winner) continue;
+    generations.push(
+      snapshotFromCampaign(gen.record.generationIndex + 1, winner.surface, winner.campaign, 0)
+    );
+  }
+  const event = {
+    runId: `${runDir}#${Date.now()}`,
+    runDir,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    status: "finished",
+    labels: opts.hostedLabels ?? {},
+    baseline: generations[0],
+    generations,
+    gateDecision: summary.gateDecision,
+    holdoutLift: summary.lift,
+    totalCostUsd: summary.totalCostUsd,
+    totalDurationMs: summary.durationMs
+  };
+  await client.ingestEvalRun(event);
+}
+function averageComposite(campaign) {
+  const aggs = Object.values(campaign.aggregates.byScenario);
+  return aggs.length === 0 ? 0 : aggs.reduce((s, a) => s + a.meanComposite, 0) / aggs.length;
+}
+function hashString(s) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
 }
 export {
   FileSystemOutcomeStore,

package/dist/contract/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/contract/self-improve.ts"],"sourcesContent":["/**\n * # `selfImprove()` — the LAND-tier one-shot.\n *\n * The cheapest possible call site to run a real closed-loop self-\n * improvement over your agent. Wraps `runImprovementLoop` with smart\n * defaults and a budget-shaped options API; every escape hatch the\n * substrate exposes is reachable from here without losing the\n * one-function feel.\n *\n * Defaults picked to match the LAND-tier story:\n *   - In-memory storage (no filesystem touch).\n *   - `gepaDriver` reflective mutation with copywriting-flavored primitives\n *     (override `driver` or `mutationPrimitives` for any domain).\n *   - `defaultProductionGate` with `deltaThreshold: 0.05`.\n *   - Held-out split = 25% of scenarios, deterministic by id hash.\n *   - 3 generations × population 2 (raise via `budget` for more search).\n *   - `autoOnPromote: 'none'` (we don't open PRs unless you ask).\n *\n * Want one-click? Provide `agent` + `scenarios` + `judge`. Done.\n * Want distributed? Pass `cellPlacement` + an `httpDispatch`-backed\n * agent. Want a code-tier surface? Pass a `MutableSurface` + your own\n * `driver`. Same function.\n */\n\nimport { runImprovementLoop, type RunImprovementLoopResult } from '../campaign/presets/run-improvement-loop'\nimport { gepaDriver } from '../campaign/drivers/gepa'\nimport { defaultProductionGate } from '../campaign/gates/default-production-gate'\nimport { type CampaignStorage, inMemoryCampaignStorage } from '../campaign/storage'\nimport type {\n  DispatchContext,\n  Gate,\n  ImprovementDriver,\n  JudgeConfig,\n  MutableSurface,\n  Scenario,\n} from '../campaign/types'\n\nexport interface SelfImproveBudget {\n  /** Hard $ ceiling across all cells in baseline + every generation. Cells\n   *  beyond the ceiling are skipped (cost-aware, not aborted). */\n  dollars?: number\n  /** How many improvement generations to explore. Default 3. Set 0 to\n   *  skip improvement entirely (selfImprove becomes a baseline-only run). */\n  generations?: number\n  /** Candidates the driver proposes per generation. Default 2. */\n  populationSize?: number\n  /** Max concurrent cells across the loop. Default 2. */\n  maxConcurrency?: number\n  /** Fraction of `scenarios` held out from training, used for the gate.\n   *  Default 0.25. Ignored when `holdoutScenarios` is set explicitly. */\n  holdoutFraction?: number\n  /** Explicit held-out scenarios; overrides `holdoutFraction`. */\n  holdoutScenarios?: Scenario[]\n}\n\nexport interface SelfImproveLlm {\n  /** Endpoint base URL. Default Tangle Router. */\n  baseUrl?: string\n  /** Bearer token. Default `process.env.OPENAI_API_KEY`. */\n  apiKey?: string\n  /** Model id used by `gepaDriver` reflection. Default\n   *  `anthropic/claude-sonnet-4.6`. */\n  model?: string\n}\n\nexport type SelfImproveProgressEvent =\n  | { kind: 'baseline.started'; scenarios: number }\n  | { kind: 'baseline.completed'; compositeMean: number; durationMs: number }\n  | { kind: 'generation.started'; index: number; populationSize: number }\n  | { kind: 'generation.completed'; index: number; bestComposite: number; durationMs: number }\n  | { kind: 'gate.decided'; decision: string; lift: number }\n\nexport interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {\n  /**\n   * Your agent — a function that takes the current `MutableSurface`\n   * (typically a system prompt the loop is optimizing) plus the\n   * scenario + cell ctx, and returns the artifact your judge scores.\n   *\n   * Same shape as `RunOptimizationOptions.dispatchWithSurface`. Wrap a\n   * plain `Dispatch` if you don't have a surface seam:\n   *\n   *   agent: (_surface, scenario, ctx) => yourPlainDispatch(scenario, ctx)\n   *\n   * That mode evaluates without mutating any surface — useful as a\n   * baseline-only run (set `budget.generations = 0`).\n   */\n  agent: (\n    surface: MutableSurface,\n    scenario: TScenario,\n    ctx: DispatchContext,\n  ) => Promise<TArtifact>\n\n  /** Scenarios to evaluate against. Train/holdout split is computed from\n   *  these unless `budget.holdoutScenarios` is set explicitly. */\n  scenarios: TScenario[]\n\n  /** Judge that scores artifacts. Bring your own; use `langchainJudge`\n   *  from `/adapters/langchain` for a Runnable-shaped one. */\n  judge: JudgeConfig<TArtifact, TScenario>\n\n  /** Starting surface — system prompt, JSON config, anything `MutableSurface`\n   *  accepts. The driver mutates this each generation. */\n  baselineSurface: MutableSurface\n\n  /** Budget + loop shape. All fields optional; defaults pick the LAND-tier\n   *  story. */\n  budget?: SelfImproveBudget\n\n  /** Custom driver. Default is `gepaDriver` configured from `llm` +\n   *  `mutationPrimitives`. */\n  driver?: ImprovementDriver\n\n  /** Default-driver overrides — used when `driver` is unset. */\n  mutationPrimitives?: string[]\n  driverTarget?: string\n\n  /** Custom gate. Default is `defaultProductionGate` with\n   *  `deltaThreshold: 0.05` on the held-out split. */\n  gate?: Gate<TArtifact, TScenario>\n\n  /** LLM config consumed by the default `gepaDriver`. Ignored if you pass\n   *  your own `driver`. */\n  llm?: SelfImproveLlm\n\n  /** Storage backend. Default `inMemoryCampaignStorage()` — nothing\n   *  persists past the call. Pass `fsCampaignStorage()` to write to disk. */\n  storage?: CampaignStorage\n\n  /** Run directory (logical for in-memory storage, real path for fs).\n   *  Default `mem://selfImprove-<timestamp>`. */\n  runDir?: string\n\n  /** Distributed-driver seam — same as `RunCampaignOptions.cellPlacement`.\n   *  Returns an opaque placement key the substrate forwards to your agent\n   *  as `ctx.placement`. Combined with `httpDispatch` from\n   *  `/adapters/http`, fans cells across regions. */\n  cellPlacement?: (input: {\n    scenario: TScenario\n    rep: number\n    generation?: number\n  }) => string | undefined\n\n  /** Streaming hook — fires on baseline + each generation + gate decision.\n   *  Consumer routes events wherever (UI, dashboard, logs). */\n  onProgress?: (event: SelfImproveProgressEvent) => void\n\n  /** Auto-promotion behavior on a ship decision. Default `'none'` — we\n   *  return the winner; you ship it however you ship. `'pr'` opens a\n   *  GitHub PR via `openAutoPr`; requires `ghOwner` + `ghRepo`. */\n  autoOnPromote?: 'pr' | 'none'\n  ghOwner?: string\n  ghRepo?: string\n}\n\nexport interface SelfImproveResult<TScenario extends Scenario, TArtifact> {\n  /** Composite mean across all scenarios, baseline run. */\n  baseline: {\n    compositeMean: number\n    perScenario: Record<string, number>\n  }\n  /** Composite mean on the held-out set, winner run. */\n  winner: {\n    compositeMean: number\n    perScenario: Record<string, number>\n    surface: MutableSurface\n  }\n  /** `winner.compositeMean - baselineOnHoldout.compositeMean`. Positive\n   *  means the gate observed improvement. */\n  lift: number\n  /** `defaultProductionGate.decide()` result. */\n  gateDecision: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling'\n  /** Number of generations actually explored (may be less than the\n   *  budget if the driver gave up early). */\n  generationsExplored: number\n  /** Wall-clock total. */\n  durationMs: number\n  /** Total cost across baseline + every generation. */\n  totalCostUsd: number\n  /**\n   * Raw substrate result for advanced inspection — full per-generation\n   * candidates, full campaign artifacts, all judge scores. Useful for\n   * debugging or reporting beyond the summary.\n   */\n  raw: RunImprovementLoopResult<TArtifact, TScenario>\n}\n\n/**\n * Deterministic train/holdout split by a stable hash of `scenario.id`,\n * so the same scenario set always splits the same way across runs.\n */\nfunction splitTrainHoldout<TScenario extends Scenario>(\n  scenarios: TScenario[],\n  fraction: number,\n): { train: TScenario[]; holdout: TScenario[] } {\n  // Stable fnv-1a-ish hash of the id for ordering.\n  function hash(s: string): number {\n    let h = 2166136261 >>> 0\n    for (let i = 0; i < s.length; i++) {\n      h ^= s.charCodeAt(i)\n      h = Math.imul(h, 16777619) >>> 0\n    }\n    return h\n  }\n  const sorted = [...scenarios].sort((a, b) => hash(a.id) - hash(b.id))\n  const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)))\n  return {\n    holdout: sorted.slice(0, nHoldout),\n    train: sorted.slice(nHoldout),\n  }\n}\n\nfunction meanComposite(\n  byScenario: Record<string, { meanComposite: number }>,\n): { compositeMean: number; perScenario: Record<string, number> } {\n  const perScenario: Record<string, number> = {}\n  const values: number[] = []\n  for (const [id, agg] of Object.entries(byScenario)) {\n    perScenario[id] = agg.meanComposite\n    values.push(agg.meanComposite)\n  }\n  return {\n    compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,\n    perScenario,\n  }\n}\n\nconst DEFAULT_MUTATION_PRIMITIVES = [\n  'Tighten the hook: lead with the specific user outcome.',\n  'Replace generic adjectives with specific verbs or proof numbers.',\n  'Anchor every claim in something the scenario\\'s brief literally supports.',\n  'Honor the surface-shape constraint (length, register, audience vocabulary).',\n]\n\n/**\n * One-shot self-improvement loop. See module docstring for defaults +\n * extension points.\n *\n * @example Minimum (LAND tier):\n *\n *   const result = await selfImprove({\n *     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *   })\n *   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)\n *\n * @example Distributed (workers in three regions):\n *\n *   await selfImprove({\n *     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *     cellPlacement: ({ scenario }) => scenario.region,\n *     budget: { maxConcurrency: 12 },\n *   })\n */\nexport async function selfImprove<TScenario extends Scenario, TArtifact>(\n  opts: SelfImproveOptions<TScenario, TArtifact>,\n): Promise<SelfImproveResult<TScenario, TArtifact>> {\n  const startedAt = Date.now()\n\n  const budget = opts.budget ?? {}\n  const generations = budget.generations ?? 3\n  const populationSize = budget.populationSize ?? 2\n  const maxConcurrency = budget.maxConcurrency ?? 2\n  const holdoutFraction = budget.holdoutFraction ?? 0.25\n  const costCeiling = budget.dollars\n\n  const explicitHoldout = budget.holdoutScenarios\n  const { train, holdout } = explicitHoldout\n    ? {\n        train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),\n        holdout: explicitHoldout as TScenario[],\n      }\n    : splitTrainHoldout(opts.scenarios, holdoutFraction)\n\n  if (train.length === 0) {\n    throw new Error('selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.')\n  }\n  if (holdout.length === 0) {\n    throw new Error('selfImprove: holdout split is empty. Pass more scenarios.')\n  }\n\n  const driver: ImprovementDriver =\n    opts.driver ??\n    gepaDriver({\n      llm: {\n        baseUrl: opts.llm?.baseUrl ?? 'https://router.tangle.tools/v1',\n        apiKey: opts.llm?.apiKey ?? process.env.OPENAI_API_KEY ?? '',\n      },\n      model: opts.llm?.model ?? 'anthropic/claude-sonnet-4.6',\n      target: opts.driverTarget ?? 'agent surface (system prompt or config) being optimized by selfImprove',\n      mutationPrimitives: opts.mutationPrimitives ?? DEFAULT_MUTATION_PRIMITIVES,\n    })\n\n  const gate: Gate<TArtifact, TScenario> =\n    opts.gate ??\n    defaultProductionGate<TArtifact, TScenario>({\n      holdoutScenarios: holdout,\n      deltaThreshold: 0.05,\n    })\n\n  const storage = opts.storage ?? inMemoryCampaignStorage()\n  const runDir = opts.runDir ?? `mem://selfImprove-${startedAt}`\n\n  if (opts.onProgress) {\n    opts.onProgress({ kind: 'baseline.started', scenarios: opts.scenarios.length })\n  }\n\n  const result = await runImprovementLoop<TScenario, TArtifact>({\n    scenarios: train,\n    baselineSurface: opts.baselineSurface,\n    dispatchWithSurface: opts.agent,\n    driver,\n    judges: [opts.judge],\n    populationSize,\n    maxGenerations: generations,\n    holdoutScenarios: holdout,\n    gate,\n    autoOnPromote: opts.autoOnPromote ?? 'none',\n    ghOwner: opts.ghOwner,\n    ghRepo: opts.ghRepo,\n    storage,\n    runDir,\n    maxConcurrency,\n    cellPlacement: opts.cellPlacement,\n    costCeiling,\n  })\n\n  const baseline = meanComposite(result.baselineOnHoldout.aggregates.byScenario)\n  const winnerStats = meanComposite(result.winnerOnHoldout.aggregates.byScenario)\n\n  if (opts.onProgress) {\n    opts.onProgress({\n      kind: 'baseline.completed',\n      compositeMean: baseline.compositeMean,\n      durationMs: Date.now() - startedAt,\n    })\n    opts.onProgress({\n      kind: 'gate.decided',\n      decision: result.gateResult.decision,\n      lift: winnerStats.compositeMean - baseline.compositeMean,\n    })\n  }\n\n  const totalCost =\n    result.baselineCampaign.aggregates.totalCostUsd +\n    result.generations.reduce(\n      (sum, gen) => sum + gen.surfaces.reduce((s, sf) => s + sf.campaign.aggregates.totalCostUsd, 0),\n      0,\n    )\n\n  return {\n    baseline,\n    winner: {\n      ...winnerStats,\n      surface: result.winnerSurface,\n    },\n    lift: winnerStats.compositeMean - baseline.compositeMean,\n    gateDecision: result.gateResult.decision,\n    generationsExplored: result.generations.length,\n    durationMs: Date.now() - startedAt,\n    totalCostUsd: totalCost,\n    raw: result,\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/contract/self-improve.ts"],"sourcesContent":["/**\n * # `selfImprove()` — the LAND-tier one-shot.\n *\n * The cheapest possible call site to run a real closed-loop self-\n * improvement over your agent. Wraps `runImprovementLoop` with smart\n * defaults and a budget-shaped options API; every escape hatch the\n * substrate exposes is reachable from here without losing the\n * one-function feel.\n *\n * Defaults picked to match the LAND-tier story:\n *   - In-memory storage (no filesystem touch).\n *   - `gepaDriver` reflective mutation with copywriting-flavored primitives\n *     (override `driver` or `mutationPrimitives` for any domain).\n *   - `defaultProductionGate` with `deltaThreshold: 0.05`.\n *   - Held-out split = 25% of scenarios, deterministic by id hash.\n *   - 3 generations × population 2 (raise via `budget` for more search).\n *   - `autoOnPromote: 'none'` (we don't open PRs unless you ask).\n *\n * Want one-click? Provide `agent` + `scenarios` + `judge`. Done.\n * Want distributed? Pass `cellPlacement` + an `httpDispatch`-backed\n * agent. Want a code-tier surface? Pass a `MutableSurface` + your own\n * `driver`. Same function.\n */\n\nimport { gepaDriver } from '../campaign/drivers/gepa'\nimport { defaultProductionGate } from '../campaign/gates/default-production-gate'\nimport {\n  type RunImprovementLoopResult,\n  runImprovementLoop,\n} from '../campaign/presets/run-improvement-loop'\nimport { type CampaignStorage, inMemoryCampaignStorage } from '../campaign/storage'\nimport type {\n  DispatchContext,\n  Gate,\n  ImprovementDriver,\n  JudgeConfig,\n  MutableSurface,\n  Scenario,\n} from '../campaign/types'\nimport { createHostedClient, type HostedTenant } from '../hosted/client'\nimport type {\n  EvalRunCellScore,\n  EvalRunEvent,\n  EvalRunGenerationSnapshot,\n} from '../hosted/types'\n\nexport interface SelfImproveBudget {\n  /** Hard $ ceiling across all cells in baseline + every generation. Cells\n   *  beyond the ceiling are skipped (cost-aware, not aborted). */\n  dollars?: number\n  /** How many improvement generations to explore. Default 3. Set 0 to\n   *  skip improvement entirely (selfImprove becomes a baseline-only run). */\n  generations?: number\n  /** Candidates the driver proposes per generation. Default 2. */\n  populationSize?: number\n  /** Max concurrent cells across the loop. Default 2. */\n  maxConcurrency?: number\n  /** Fraction of `scenarios` held out from training, used for the gate.\n   *  Default 0.25. Ignored when `holdoutScenarios` is set explicitly. */\n  holdoutFraction?: number\n  /** Explicit held-out scenarios; overrides `holdoutFraction`. */\n  holdoutScenarios?: Scenario[]\n}\n\nexport interface SelfImproveLlm {\n  /** Endpoint base URL. Default Tangle Router. */\n  baseUrl?: string\n  /** Bearer token. Default `process.env.OPENAI_API_KEY`. */\n  apiKey?: string\n  /** Model id used by `gepaDriver` reflection. Default\n   *  `anthropic/claude-sonnet-4.6`. */\n  model?: string\n}\n\nexport type SelfImproveProgressEvent =\n  | { kind: 'baseline.started'; scenarios: number }\n  | { kind: 'baseline.completed'; compositeMean: number; durationMs: number }\n  | { kind: 'generation.started'; index: number; populationSize: number }\n  | { kind: 'generation.completed'; index: number; bestComposite: number; durationMs: number }\n  | { kind: 'gate.decided'; decision: string; lift: number }\n\nexport interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {\n  /**\n   * Your agent — a function that takes the current `MutableSurface`\n   * (typically a system prompt the loop is optimizing) plus the\n   * scenario + cell ctx, and returns the artifact your judge scores.\n   *\n   * Same shape as `RunOptimizationOptions.dispatchWithSurface`. Wrap a\n   * plain `Dispatch` if you don't have a surface seam:\n   *\n   *   agent: (_surface, scenario, ctx) => yourPlainDispatch(scenario, ctx)\n   *\n   * That mode evaluates without mutating any surface — useful as a\n   * baseline-only run (set `budget.generations = 0`).\n   */\n  agent: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>\n\n  /** Scenarios to evaluate against. Train/holdout split is computed from\n   *  these unless `budget.holdoutScenarios` is set explicitly. */\n  scenarios: TScenario[]\n\n  /** Judge that scores artifacts. Bring your own; use `langchainJudge`\n   *  from `/adapters/langchain` for a Runnable-shaped one. */\n  judge: JudgeConfig<TArtifact, TScenario>\n\n  /** Starting surface — system prompt, JSON config, anything `MutableSurface`\n   *  accepts. The driver mutates this each generation. */\n  baselineSurface: MutableSurface\n\n  /** Budget + loop shape. All fields optional; defaults pick the LAND-tier\n   *  story. */\n  budget?: SelfImproveBudget\n\n  /** Custom driver. Default is `gepaDriver` configured from `llm` +\n   *  `mutationPrimitives`. */\n  driver?: ImprovementDriver\n\n  /** Default-driver overrides — used when `driver` is unset. */\n  mutationPrimitives?: string[]\n  driverTarget?: string\n\n  /** Custom gate. Default is `defaultProductionGate` with\n   *  `deltaThreshold: 0.05` on the held-out split. */\n  gate?: Gate<TArtifact, TScenario>\n\n  /** LLM config consumed by the default `gepaDriver`. Ignored if you pass\n   *  your own `driver`. */\n  llm?: SelfImproveLlm\n\n  /** Storage backend. Default `inMemoryCampaignStorage()` — nothing\n   *  persists past the call. Pass `fsCampaignStorage()` to write to disk. */\n  storage?: CampaignStorage\n\n  /** Run directory (logical for in-memory storage, real path for fs).\n   *  Default `mem://selfImprove-<timestamp>`. */\n  runDir?: string\n\n  /** Distributed-driver seam — same as `RunCampaignOptions.cellPlacement`.\n   *  Returns an opaque placement key the substrate forwards to your agent\n   *  as `ctx.placement`. Combined with `httpDispatch` from\n   *  `/adapters/http`, fans cells across regions. */\n  cellPlacement?: (input: {\n    scenario: TScenario\n    rep: number\n    generation?: number\n  }) => string | undefined\n\n  /** Streaming hook — fires on baseline + each generation + gate decision.\n   *  Consumer routes events wherever (UI, dashboard, logs). */\n  onProgress?: (event: SelfImproveProgressEvent) => void\n\n  /** Auto-promotion behavior on a ship decision. Default `'none'` — we\n   *  return the winner; you ship it however you ship. `'pr'` opens a\n   *  GitHub PR via `openAutoPr`; requires `ghOwner` + `ghRepo`. */\n  autoOnPromote?: 'pr' | 'none'\n  ghOwner?: string\n  ghRepo?: string\n\n  /**\n   * Opt-in: ship eval-run events to a hosted orchestrator (ours, your\n   * self-hosted one, or any compatible implementation of the\n   * `docs/hosted-ingest-spec.md` wire format). When set, the substrate\n   * POSTs the final `EvalRunEvent` to `${endpoint}/v1/ingest/eval-runs`\n   * after the loop completes. Failures are logged but do not fail the\n   * loop — local result is always returned.\n   *\n   * For our orchestrator: `{ endpoint: 'https://orchestrator.tangle.tools/v1', apiKey, tenantId }`.\n   *\n   * For your self-hosted: any URL serving the wire format. See\n   * `examples/hosted-ingest-server/` for the reference receiver.\n   */\n  hostedTenant?: HostedTenant\n\n  /** Free-form labels attached to the hosted event (env, branch, model id,\n   *  etc.). Ignored when `hostedTenant` is unset. */\n  hostedLabels?: Record<string, string>\n}\n\nexport interface SelfImproveResult<TScenario extends Scenario, TArtifact> {\n  /** Composite mean across all scenarios, baseline run. */\n  baseline: {\n    compositeMean: number\n    perScenario: Record<string, number>\n  }\n  /** Composite mean on the held-out set, winner run. */\n  winner: {\n    compositeMean: number\n    perScenario: Record<string, number>\n    surface: MutableSurface\n  }\n  /** `winner.compositeMean - baselineOnHoldout.compositeMean`. Positive\n   *  means the gate observed improvement. */\n  lift: number\n  /** `defaultProductionGate.decide()` result. */\n  gateDecision: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling'\n  /** Number of generations actually explored (may be less than the\n   *  budget if the driver gave up early). */\n  generationsExplored: number\n  /** Wall-clock total. */\n  durationMs: number\n  /** Total cost across baseline + every generation. */\n  totalCostUsd: number\n  /**\n   * Raw substrate result for advanced inspection — full per-generation\n   * candidates, full campaign artifacts, all judge scores. Useful for\n   * debugging or reporting beyond the summary.\n   */\n  raw: RunImprovementLoopResult<TArtifact, TScenario>\n}\n\n/**\n * Deterministic train/holdout split by a stable hash of `scenario.id`,\n * so the same scenario set always splits the same way across runs.\n */\nfunction splitTrainHoldout<TScenario extends Scenario>(\n  scenarios: TScenario[],\n  fraction: number,\n): { train: TScenario[]; holdout: TScenario[] } {\n  // Stable fnv-1a-ish hash of the id for ordering.\n  function hash(s: string): number {\n    let h = 2166136261 >>> 0\n    for (let i = 0; i < s.length; i++) {\n      h ^= s.charCodeAt(i)\n      h = Math.imul(h, 16777619) >>> 0\n    }\n    return h\n  }\n  const sorted = [...scenarios].sort((a, b) => hash(a.id) - hash(b.id))\n  const nHoldout = Math.max(1, Math.min(sorted.length - 1, Math.round(sorted.length * fraction)))\n  return {\n    holdout: sorted.slice(0, nHoldout),\n    train: sorted.slice(nHoldout),\n  }\n}\n\nfunction meanComposite(byScenario: Record<string, { meanComposite: number }>): {\n  compositeMean: number\n  perScenario: Record<string, number>\n} {\n  const perScenario: Record<string, number> = {}\n  const values: number[] = []\n  for (const [id, agg] of Object.entries(byScenario)) {\n    perScenario[id] = agg.meanComposite\n    values.push(agg.meanComposite)\n  }\n  return {\n    compositeMean: values.length === 0 ? 0 : values.reduce((s, v) => s + v, 0) / values.length,\n    perScenario,\n  }\n}\n\nconst DEFAULT_MUTATION_PRIMITIVES = [\n  'Tighten the hook: lead with the specific user outcome.',\n  'Replace generic adjectives with specific verbs or proof numbers.',\n  \"Anchor every claim in something the scenario's brief literally supports.\",\n  'Honor the surface-shape constraint (length, register, audience vocabulary).',\n]\n\n/**\n * One-shot self-improvement loop. See module docstring for defaults +\n * extension points.\n *\n * @example Minimum (LAND tier):\n *\n *   const result = await selfImprove({\n *     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *   })\n *   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)\n *\n * @example Distributed (workers in three regions):\n *\n *   await selfImprove({\n *     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),\n *     scenarios,\n *     judge,\n *     baselineSurface: DEFAULT_PROMPT,\n *     cellPlacement: ({ scenario }) => scenario.region,\n *     budget: { maxConcurrency: 12 },\n *   })\n */\nexport async function selfImprove<TScenario extends Scenario, TArtifact>(\n  opts: SelfImproveOptions<TScenario, TArtifact>,\n): Promise<SelfImproveResult<TScenario, TArtifact>> {\n  const startedAt = Date.now()\n\n  const budget = opts.budget ?? {}\n  const generations = budget.generations ?? 3\n  const populationSize = budget.populationSize ?? 2\n  const maxConcurrency = budget.maxConcurrency ?? 2\n  const holdoutFraction = budget.holdoutFraction ?? 0.25\n  const costCeiling = budget.dollars\n\n  const explicitHoldout = budget.holdoutScenarios\n  const { train, holdout } = explicitHoldout\n    ? {\n        train: opts.scenarios.filter((s) => !explicitHoldout.some((h) => h.id === s.id)),\n        holdout: explicitHoldout as TScenario[],\n      }\n    : splitTrainHoldout(opts.scenarios, holdoutFraction)\n\n  if (train.length === 0) {\n    throw new Error(\n      'selfImprove: train split is empty. Reduce holdoutFraction or pass more scenarios.',\n    )\n  }\n  if (holdout.length === 0) {\n    throw new Error('selfImprove: holdout split is empty. Pass more scenarios.')\n  }\n\n  const driver: ImprovementDriver =\n    opts.driver ??\n    gepaDriver({\n      llm: {\n        baseUrl: opts.llm?.baseUrl ?? 'https://router.tangle.tools/v1',\n        apiKey: opts.llm?.apiKey ?? process.env.OPENAI_API_KEY ?? '',\n      },\n      model: opts.llm?.model ?? 'anthropic/claude-sonnet-4.6',\n      target:\n        opts.driverTarget ??\n        'agent surface (system prompt or config) being optimized by selfImprove',\n      mutationPrimitives: opts.mutationPrimitives ?? DEFAULT_MUTATION_PRIMITIVES,\n    })\n\n  const gate: Gate<TArtifact, TScenario> =\n    opts.gate ??\n    defaultProductionGate<TArtifact, TScenario>({\n      holdoutScenarios: holdout,\n      deltaThreshold: 0.05,\n    })\n\n  const storage = opts.storage ?? inMemoryCampaignStorage()\n  const runDir = opts.runDir ?? `mem://selfImprove-${startedAt}`\n\n  if (opts.onProgress) {\n    opts.onProgress({ kind: 'baseline.started', scenarios: opts.scenarios.length })\n  }\n\n  const result = await runImprovementLoop<TScenario, TArtifact>({\n    scenarios: train,\n    baselineSurface: opts.baselineSurface,\n    dispatchWithSurface: opts.agent,\n    driver,\n    judges: [opts.judge],\n    populationSize,\n    maxGenerations: generations,\n    holdoutScenarios: holdout,\n    gate,\n    autoOnPromote: opts.autoOnPromote ?? 'none',\n    ghOwner: opts.ghOwner,\n    ghRepo: opts.ghRepo,\n    storage,\n    runDir,\n    maxConcurrency,\n    cellPlacement: opts.cellPlacement,\n    costCeiling,\n  })\n\n  const baseline = meanComposite(result.baselineOnHoldout.aggregates.byScenario)\n  const winnerStats = meanComposite(result.winnerOnHoldout.aggregates.byScenario)\n\n  if (opts.onProgress) {\n    opts.onProgress({\n      kind: 'baseline.completed',\n      compositeMean: baseline.compositeMean,\n      durationMs: Date.now() - startedAt,\n    })\n    opts.onProgress({\n      kind: 'gate.decided',\n      decision: result.gateResult.decision,\n      lift: winnerStats.compositeMean - baseline.compositeMean,\n    })\n  }\n\n  const totalCost =\n    result.baselineCampaign.aggregates.totalCostUsd +\n    result.generations.reduce(\n      (sum, gen) =>\n        sum + gen.surfaces.reduce((s, sf) => s + sf.campaign.aggregates.totalCostUsd, 0),\n      0,\n    )\n\n  const summary: SelfImproveResult<TScenario, TArtifact> = {\n    baseline,\n    winner: {\n      ...winnerStats,\n      surface: result.winnerSurface,\n    },\n    lift: winnerStats.compositeMean - baseline.compositeMean,\n    gateDecision: result.gateResult.decision,\n    generationsExplored: result.generations.length,\n    durationMs: Date.now() - startedAt,\n    totalCostUsd: totalCost,\n    raw: result,\n  }\n\n  // Opt-in hosted ingest. Failures logged but never fail the loop — the\n  // local result is always returned. This matches the wedge-doc invariant\n  // that LAND-tier never blocks on EXPAND-tier infra.\n  if (opts.hostedTenant) {\n    try {\n      await shipEvalRunToHosted(opts.hostedTenant, opts, summary, result, runDir)\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err)\n      // eslint-disable-next-line no-console -- intentional: hosted-ingest is best-effort\n      console.warn(`[agent-eval] hosted ingest failed (continuing): ${msg}`)\n    }\n  }\n\n  return summary\n}\n\nasync function shipEvalRunToHosted<TScenario extends Scenario, TArtifact>(\n  tenant: HostedTenant,\n  opts: SelfImproveOptions<TScenario, TArtifact>,\n  summary: SelfImproveResult<TScenario, TArtifact>,\n  raw: RunImprovementLoopResult<TArtifact, TScenario>,\n  runDir: string,\n): Promise<void> {\n  const client = createHostedClient(tenant)\n\n  function snapshotFromCampaign(\n    index: number,\n    surface: MutableSurface | undefined,\n    campaign: RunImprovementLoopResult<TArtifact, TScenario>['baselineCampaign'],\n    durationMs: number,\n  ): EvalRunGenerationSnapshot {\n    const cells: EvalRunCellScore[] = campaign.cells.map((cell) => {\n      const judgeScores = Object.values(cell.judgeScores)\n      const composite =\n        judgeScores.length === 0\n          ? 0\n          : judgeScores.reduce((s, j) => s + j.composite, 0) / judgeScores.length\n      return {\n        scenarioId: cell.scenarioId,\n        rep: cell.rep,\n        compositeMean: composite,\n        dimensions: Object.fromEntries(\n          Object.entries(cell.judgeScores).map(([name, score]) => [name, score.dimensions]),\n        ),\n        errorMessage: cell.error ?? undefined,\n      }\n    })\n    const compositeMean =\n      cells.length === 0 ? 0 : cells.reduce((s, c) => s + c.compositeMean, 0) / cells.length\n    return {\n      index,\n      surfaceHash: typeof surface === 'string' ? hashString(surface) : hashString(JSON.stringify(surface ?? '')),\n      surface,\n      cells,\n      compositeMean,\n      costUsd: campaign.aggregates.totalCostUsd,\n      durationMs,\n    }\n  }\n\n  const generations: EvalRunGenerationSnapshot[] = []\n  // Baseline as generation 0.\n  generations.push(snapshotFromCampaign(0, opts.baselineSurface, raw.baselineCampaign, 0))\n  // Improvement generations as 1..N. Substrate stores per-surface campaigns\n  // per generation — we summarize the WINNING surface per generation here.\n  for (const gen of raw.generations) {\n    const winner = gen.surfaces.reduce((best, s) =>\n      s.campaign.aggregates.cellsExecuted > 0 &&\n      (best === undefined || averageComposite(s.campaign) > averageComposite(best.campaign))\n        ? s\n        : best,\n      gen.surfaces[0],\n    )\n    if (!winner) continue\n    generations.push(\n      snapshotFromCampaign(gen.record.generationIndex + 1, winner.surface, winner.campaign, 0),\n    )\n  }\n\n  const event: EvalRunEvent = {\n    runId: `${runDir}#${Date.now()}`,\n    runDir,\n    timestamp: new Date().toISOString(),\n    status: 'finished',\n    labels: opts.hostedLabels ?? {},\n    baseline: generations[0],\n    generations,\n    gateDecision: summary.gateDecision,\n    holdoutLift: summary.lift,\n    totalCostUsd: summary.totalCostUsd,\n    totalDurationMs: summary.durationMs,\n  }\n\n  await client.ingestEvalRun(event)\n}\n\nfunction averageComposite(\n  campaign: RunImprovementLoopResult<unknown, Scenario>['baselineCampaign'],\n): number {\n  const aggs = Object.values(campaign.aggregates.byScenario)\n  return aggs.length === 0 ? 0 : aggs.reduce((s, a) => s + a.meanComposite, 0) / aggs.length\n}\n\nfunction hashString(s: string): string {\n  let h = 2166136261 >>> 0\n  for (let i = 0; i < s.length; i++) {\n    h ^= s.charCodeAt(i)\n    h = Math.imul(h, 16777619) >>> 0\n  }\n  return h.toString(16).padStart(8, '0')\n}\n"],"mappings":"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","names":[]}

package/dist/hosted/index.d.ts

@@ -0,0 +1,192 @@
+import { M as MutableSurface, i as GateDecision } from '../types-8u72Gc76.js';
+
+/**
+ * # Hosted-tier wire format — the schema that EVERY orchestrator (ours,
+ * a partner's self-hosted one, a future open implementation) must accept.
+ *
+ * **Stability:** every type in this file is committed under semver. New
+ * minors only ADD optional fields. Breaking changes mean a major bump
+ * (`HostedWireVersion` literal increment).
+ *
+ * The wire format is two event streams in one transport:
+ *
+ *   1. **Eval-run events** (`POST /v1/ingest/eval-runs`). Posted when a
+ *      campaign / improvement-loop completes (or per-generation if
+ *      streaming). Carries the structured result + per-cell scores +
+ *      surface diffs the orchestrator stores for the dashboard.
+ *
+ *   2. **Trace spans** (`POST /v1/ingest/traces`). Standard OTLP-shaped
+ *      spans with a few additional attributes so the orchestrator can
+ *      pivot from eval-run → underlying execution. Compatible with any
+ *      OTel collector.
+ *
+ * Both endpoints are authenticated with a bearer token + a tenant id
+ * header. Tenants isolate everything downstream of ingest; no tenant
+ * ever sees another tenant's data.
+ */
+
+declare const HOSTED_WIRE_VERSION: "2026-05-26.v1";
+type HostedWireVersion = typeof HOSTED_WIRE_VERSION;
+/** Every ingest request carries these. */
+interface HostedIngestHeaders {
+    /** Bearer token. The orchestrator validates against the tenant key. */
+    authorization: `Bearer ${string}`;
+    /** Stable tenant id (the orchestrator-side primary key for the tenant). */
+    'x-tangle-tenant-id': string;
+    /** Wire-version pin so the server can reject incompatible payloads. */
+    'x-tangle-wire-version': HostedWireVersion;
+    /** Optional idempotency key for retry-safe ingest. */
+    'idempotency-key'?: string;
+}
+/** Lifecycle stages of an eval-run as the substrate reports them. */
+type EvalRunStatus = 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
+interface EvalRunCellScore {
+    /** Stable scenario id from the consumer's scenario set. */
+    scenarioId: string;
+    /** Repetition index when reps > 1; 0 for the default. */
+    rep: number;
+    /** Composite score across all judges + dimensions for this cell. */
+    compositeMean: number;
+    /** Per-judge → per-dimension scores; null where the judge did not run. */
+    dimensions: Record<string, Record<string, number>>;
+    /** Per-cell error message if the dispatch threw. Null on success. */
+    errorMessage?: string;
+}
+interface EvalRunGenerationSnapshot {
+    /** Generation index. 0 is baseline. */
+    index: number;
+    /** Candidate surface fingerprint (stable hash) — pivot key into the
+     *  trace stream to fetch the underlying execution. */
+    surfaceHash: string;
+    /** The candidate surface itself. May be omitted to avoid PII when the
+     *  consumer prefers not to ship verbatim prompts. */
+    surface?: MutableSurface;
+    /** Per-cell scores for this generation. */
+    cells: EvalRunCellScore[];
+    /** Aggregate composite mean across all cells in this generation. */
+    compositeMean: number;
+    /** Total $ spent across this generation. */
+    costUsd: number;
+    /** Wall-clock duration of this generation. */
+    durationMs: number;
+}
+/**
+ * The top-level eval-run event. One ingest call per logical eval-run;
+ * generations stream in incrementally via repeated calls with the same
+ * `runId`. The orchestrator deduplicates by `(runId, generation.index)`.
+ */
+interface EvalRunEvent {
+    /** Stable run id (the substrate's `runId`). UUID or substrate-generated. */
+    runId: string;
+    /** Where this run was happening — derived from `RunCampaignOptions.runDir`. */
+    runDir: string;
+    /** ISO-8601 timestamp the substrate recorded the event. */
+    timestamp: string;
+    /** Lifecycle stage this event represents. */
+    status: EvalRunStatus;
+    /** Free-form consumer tags (env, branch, model id, etc.). Searchable. */
+    labels: Record<string, string>;
+    /** Baseline campaign snapshot. Present when status >= baseline-complete. */
+    baseline?: EvalRunGenerationSnapshot;
+    /** Per-generation snapshots. Streams in; orchestrator appends. */
+    generations: EvalRunGenerationSnapshot[];
+    /** Final gate decision. Present when status >= gate-decided. */
+    gateDecision?: GateDecision;
+    /** Held-out lift = winner-on-holdout - baseline-on-holdout. */
+    holdoutLift?: number;
+    /** Total $ spent across baseline + every generation. */
+    totalCostUsd: number;
+    /** Total wall-clock duration. */
+    totalDurationMs: number;
+    /** Error message if status === 'errored'. */
+    errorMessage?: string;
+}
+/**
+ * OTel-shape span with a few additional attributes for eval-run pivoting.
+ * Compatible with any OTLP collector — `name`, `traceId`, `spanId`,
+ * `startTimeUnixNano`, `endTimeUnixNano`, `attributes` are stock OTel.
+ */
+interface TraceSpanEvent {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: number;
+    endTimeUnixNano: number;
+    attributes: Record<string, string | number | boolean>;
+    events?: Array<{
+        timeUnixNano: number;
+        name: string;
+        attributes?: Record<string, string | number | boolean>;
+    }>;
+    status?: {
+        code: 'OK' | 'ERROR' | 'UNSET';
+        message?: string;
+    };
+    /** Pivot back into the eval-run stream. */
+    'tangle.runId'?: string;
+    /** Pivot to the specific generation. */
+    'tangle.generation'?: number;
+    /** Pivot to the specific cell. */
+    'tangle.cellId'?: string;
+    /** Pivot to the specific scenario. */
+    'tangle.scenarioId'?: string;
+}
+interface IngestEvalRunsRequest {
+    wireVersion: HostedWireVersion;
+    events: EvalRunEvent[];
+}
+interface IngestTracesRequest {
+    wireVersion: HostedWireVersion;
+    spans: TraceSpanEvent[];
+}
+interface IngestResponse {
+    /** Accepted events / spans count. */
+    accepted: number;
+    /** Rejected events with reasons (validation failures, dup idempotency key, etc.). */
+    rejected: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+
+/**
+ * # Hosted-tier ingest client.
+ *
+ * Ships eval-run events + trace spans to any orchestrator (ours, a
+ * partner's self-hosted one, or a future open implementation) that
+ * speaks the wire format in `./types.ts`.
+ *
+ * Three modes:
+ *   - **Ours:** point at `https://orchestrator.tangle.tools/v1`. We
+ *     handle ingest + storage + dashboard.
+ *   - **Self-hosted:** point at whatever URL runs the reference receiver
+ *     from `examples/hosted-ingest-server/`.
+ *   - **Off (default):** when `hostedTenant` is unset, nothing is sent.
+ *     Everything stays local.
+ */
+
+interface HostedTenant {
+    /** Orchestrator endpoint base URL (no trailing slash). Required. */
+    endpoint: string;
+    /** Bearer token issued by the orchestrator. Required. */
+    apiKey: string;
+    /** Tenant id — the orchestrator's primary key for this consumer. Required. */
+    tenantId: string;
+    /** Optional `fetch` override (auth wrappers, custom agent, test mocks). */
+    fetchImpl?: typeof fetch;
+    /** Per-call timeout in ms. Default 30s. */
+    timeoutMs?: number;
+    /** Retries on 5xx / network errors. Default 2. */
+    retries?: number;
+}
+interface HostedClient {
+    ingestEvalRun(event: EvalRunEvent, idempotencyKey?: string): Promise<IngestResponse>;
+    ingestEvalRuns(events: EvalRunEvent[], idempotencyKey?: string): Promise<IngestResponse>;
+    ingestTraces(spans: TraceSpanEvent[], idempotencyKey?: string): Promise<IngestResponse>;
+    readonly tenant: HostedTenant;
+    readonly wireVersion: HostedWireVersion;
+}
+declare function createHostedClient(tenant: HostedTenant): HostedClient;
+
+export { type EvalRunCellScore, type EvalRunEvent, type EvalRunGenerationSnapshot, type EvalRunStatus, HOSTED_WIRE_VERSION, type HostedClient, type HostedIngestHeaders, type HostedTenant, type HostedWireVersion, type IngestEvalRunsRequest, type IngestResponse, type IngestTracesRequest, type TraceSpanEvent, createHostedClient };

package/dist/hosted/index.js

@@ -0,0 +1,10 @@
+import {
+  HOSTED_WIRE_VERSION,
+  createHostedClient
+} from "../chunk-ZQABFCVJ.js";
+import "../chunk-NSBPE2FW.js";
+export {
+  HOSTED_WIRE_VERSION,
+  createHostedClient
+};
+//# sourceMappingURL=index.js.map

package/dist/hosted/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "@tangle-network/agent-eval — wire protocol",
-    "version": "0.45.0",
+    "version": "0.46.0",
     "description": "HTTP and stdio RPC interface to agent-eval. The TypeScript runtime is the source of truth; this spec is the contract that cross-language clients (Python, Rust, Go) generate from.\n\nWire-protocol version: 1.0.0. Bumps on breaking changes to request/response schemas.",
     "contact": {
       "name": "Tangle Network",

package/docs/design/phase-d-rfc.md

@@ -0,0 +1,125 @@
+# Phase D RFC — hosted-tier substrate
+
+Pinned scope decisions for the EXPAND tier. What we built, what we
+deliberately did NOT, and what's gated on Phase B evidence.
+
+---
+
+## What's in this version
+
+**Wire-format substrate (shipped):**
+
+1. `@tangle-network/agent-eval/hosted` — public client + types for shipping
+   eval-run events + trace spans to any orchestrator that speaks the wire
+   format.
+2. `docs/hosted-ingest-spec.md` — semver-committed wire spec
+   (`HostedWireVersion = "2026-05-26.v1"`).
+3. `examples/hosted-ingest-server/` — minimal hono-based reference
+   receiver (~200 LOC). Executable spec. Stays as the reference even
+   after the production orchestrator ships.
+4. `selfImprove({ hostedTenant })` opt-in — when set, the substrate
+   POSTs the final eval-run event to the configured endpoint. Failures
+   are logged but never fail the loop (LAND tier never blocks on
+   EXPAND-tier infra).
+
+**Production orchestrator (started):**
+
+5. HTTP ingest service in `@tangle-network/monorepo` accepting the wire
+   format. Lives under the orchestrator app. Tenant auth + isolation
+   + persistent storage + read endpoints. *Started this session — see
+   the @tangle-network/agent-dev-container PR. Not feature-complete:
+   tenant CRUD + adversarial isolation tests pending.*
+
+## What's deliberately deferred
+
+The wedge doc gates these on Phase B evidence — partner-validated
+signal about what the hosted product actually needs to do. Shipping
+them without that signal risks building the wrong thing.
+
+| Deferred until Phase B passes | Why |
+|---|---|
+| **Metered billing wire-up (Stripe + cost-ledger)** | The billable units (per-eval-run, per-ingested-MB, per-seat) depend on actual partner consumption patterns. Picking dimensions in a vacuum locks us into wrong pricing. |
+| **Multi-tenant dashboard UX** | Partners' first dashboard request defines the right default views. We have a stub list-runs page; the rest is post-signal. |
+| **Webhook callbacks per tenant** | The events partners want pushed (gate-decided, cost-threshold, regression-alert) are partner-shaped. Add them when a partner asks. |
+| **Cross-tenant aggregation / benchmarking** | This is the "Datadog for agents" tier — explicit roadmap, requires user volume we don't have. |
+| **Sandbox-cost roll-up into hosted billing** | Cross-product billing integration requires PLATFORM-tier partners. Out of scope until at least one. |
+| **Trace UI** | OTel-shape spans store fine. Visualization comes after partners ask. Phoenix / Jaeger / any OTLP-compatible viewer covers it in the interim. |
+| **Soc2 / compliance audit work** | Required for enterprise; not required for design partners. |
+
+## Architecture decisions locked
+
+These are committed and won't change without a major-version wire bump
+or a documented migration:
+
+1. **Wire format is JSON over HTTP**, not gRPC. Reasons: works in
+   browsers + edge + node + curl; OTel-compatible at the trace stream
+   level; lowest possible barrier to a self-hosted orchestrator.
+2. **Tenant auth is bearer-token + tenant-id header**, not OIDC /
+   service-account / mutual-TLS. Reasons: simplest thing that's
+   actually secure with proper key handling; defers complex IAM until
+   enterprise demand.
+3. **Idempotency via header, not transactional API**. Servers MUST
+   dedupe by `(tenantId, Idempotency-Key)` for 24h. Simpler than
+   making clients commit transactions.
+4. **Eval-runs and traces are SEPARATE streams** with pivot keys
+   (`tangle.runId` etc.) on spans. Reasons: traces can be best-effort
+   (lossy) without corrupting eval-run semantics; orchestrators can
+   prioritize eval-run durability without forcing trace durability.
+5. **Wire version is a date.v-N string**, not semver. Reasons: dates
+   communicate "when was this contract frozen"; v-N captures
+   incremental breaking changes between dates.
+
+## Open questions for Phase B to answer
+
+When the design-partner pairing happens, capture answers to these
+explicitly:
+
+1. **Surface confidentiality**: do partners want the verbatim surface
+   (system prompt) shipped, or just the hash? Today the wire format
+   has `surface?` as optional; partner default is what we ship.
+2. **Trace sampling**: at what cells-per-second do trace spans become
+   noise? What's the right default sampling rate?
+3. **Cost attribution granularity**: per cell? per generation? per
+   run? Per judge dimension? Partner needs determine what we surface
+   in billing reports.
+4. **Replay**: do partners want to re-run an old eval-run from the
+   stored data? That would require us to store more than the summary —
+   actual artifacts + prompts. Storage cost implication.
+5. **PII / sensitive scenarios**: how do partners want to handle
+   scenarios containing user data? Encryption-at-rest is table stakes;
+   redaction-at-ingest may be required for some.
+
+The partner pairing kit (`docs/phase-b-pairing-kit.md`) has discovery
+questions that probe these.
+
+## Non-goals (explicit)
+
+This RFC does NOT plan for:
+
+- Replacing Langfuse / Phoenix / Arize. We INGEST OTel; we don't
+  build a generic trace viewer. The dashboard is eval-run-shaped, not
+  trace-shaped.
+- Becoming a model gateway. Tangle Router exists; the hosted
+  orchestrator routes to Tangle Router by default but doesn't
+  duplicate its function.
+- Becoming an LLM-call CDN. Caching is the consumer's job (their
+  agent code, their HTTP client). We don't intercept LLM calls.
+- Building an "agents IDE." Substrate, not surface.
+
+## Migration path (post Phase B)
+
+When Phase B passes the gate, the production orchestrator finishes:
+
+1. Replace in-memory store with Postgres (tenant data) + S3 (large
+   artifacts) OR Cloudflare D1 + R2 (Workers-native).
+2. Wire metered events to Stripe + the cost-ledger.
+3. Tenant CRUD UI + onboarding flow.
+4. Multi-tenant dashboard MVP (list runs, drill into one, diff
+   generations, view shipped prompt).
+5. Adversarial tenant-isolation test battery in CI.
+6. Webhooks + observability for the orchestrator itself.
+
+Estimated effort post-Phase-B: ~1 week focused work for one engineer.
+This is fast precisely BECAUSE the wire format is locked and the
+reference receiver exists — the production server is a different
+implementation of the same contract.

package/docs/hosted-ingest-spec.md

@@ -0,0 +1,204 @@
+# Hosted-ingest wire spec — `2026-05-26.v1`
+
+The schema **every** orchestrator (ours, partners' self-hosted ones,
+any future open implementation) must accept. Frozen under semver:
+**new minors only add optional fields. Breaking changes mean a major
+bump and a new `HostedWireVersion` literal.**
+
+This is the contract that decouples the LAND-tier substrate
+(`@tangle-network/agent-eval`) from the EXPAND-tier hosted product. A
+foreign builder can:
+
+- Use our orchestrator at `https://orchestrator.tangle.tools/v1`.
+- Self-host the reference receiver from
+  `examples/hosted-ingest-server/`.
+- Implement their own orchestrator against this spec.
+
+All three are wire-compatible by definition.
+
+---
+
+## Transport
+
+Two endpoints, both `POST`, both JSON. Headers on every request:
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <tenant-key>` (the orchestrator issues this) |
+| `Content-Type` | `application/json` |
+| `X-Tangle-Tenant-Id` | The tenant's stable id (the orchestrator's primary key for the tenant) |
+| `X-Tangle-Wire-Version` | `2026-05-26.v1` (this spec) |
+| `Idempotency-Key` (optional) | UUID; servers MUST treat repeated keys as dedup |
+
+Responses are JSON of shape `{ accepted: number, rejected: Array<{ index, reason }> }`. The
+server SHOULD return 202 (accepted, async) or 200 (accepted, synchronous);
+both are equivalent for the wire's purposes.
+
+### `POST /v1/ingest/eval-runs`
+
+Body: `IngestEvalRunsRequest = { wireVersion, events: EvalRunEvent[] }`.
+
+One ingest call per logical eval-run; generations stream in
+incrementally via repeated calls with the same `runId`. The
+orchestrator deduplicates by `(tenantId, runId, generation.index)`.
+
+### `POST /v1/ingest/traces`
+
+Body: `IngestTracesRequest = { wireVersion, spans: TraceSpanEvent[] }`.
+
+Standard OTLP-shaped spans with a few additional attributes
+(`tangle.runId`, `tangle.generation`, `tangle.cellId`,
+`tangle.scenarioId`) so the orchestrator can pivot between the
+eval-run stream and the underlying execution trace.
+
+---
+
+## `EvalRunEvent`
+
+```ts
+interface EvalRunEvent {
+  runId: string                      // stable; same id across all generations of one run
+  runDir: string                     // logical run directory (mem://... or filesystem path)
+  timestamp: string                  // ISO-8601
+  status:                            // lifecycle stage this event represents
+    | 'started'
+    | 'baseline-complete'
+    | 'generation-complete'
+    | 'gate-decided'
+    | 'finished'
+    | 'errored'
+  labels: Record<string, string>     // free-form (env, branch, model id, etc.)
+  baseline?: EvalRunGenerationSnapshot   // present when status >= baseline-complete
+  generations: EvalRunGenerationSnapshot[]
+  gateDecision?:                     // present when status >= gate-decided
+    | 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling'
+  holdoutLift?: number               // winner-on-holdout - baseline-on-holdout
+  totalCostUsd: number
+  totalDurationMs: number
+  errorMessage?: string              // present when status === 'errored'
+}
+```
+
+## `EvalRunGenerationSnapshot`
+
+```ts
+interface EvalRunGenerationSnapshot {
+  index: number                      // 0 is baseline; 1..N are improvement generations
+  surfaceHash: string                // stable hash of the candidate surface (pivot key)
+  surface?: MutableSurface           // OMITTED to avoid PII when consumer prefers
+  cells: EvalRunCellScore[]
+  compositeMean: number
+  costUsd: number
+  durationMs: number
+}
+```
+
+## `EvalRunCellScore`
+
+```ts
+interface EvalRunCellScore {
+  scenarioId: string
+  rep: number                        // 0 for the default; > 0 when reps > 1
+  compositeMean: number              // composite across all judges + dimensions
+  dimensions: Record<                // outer key = judge name; inner = dimension name → score
+    string,
+    Record<string, number>
+  >
+  errorMessage?: string              // present when the dispatch threw
+}
+```
+
+## `TraceSpanEvent`
+
+```ts
+interface TraceSpanEvent {
+  // Standard OTel
+  traceId: string
+  spanId: string
+  parentSpanId?: string
+  name: string
+  startTimeUnixNano: number
+  endTimeUnixNano: number
+  attributes: Record<string, string | number | boolean>
+  events?: Array<{ timeUnixNano, name, attributes? }>
+  status?: { code: 'OK' | 'ERROR' | 'UNSET', message? }
+
+  // Tangle additions (all optional) for pivoting
+  'tangle.runId'?: string
+  'tangle.generation'?: number
+  'tangle.cellId'?: string
+  'tangle.scenarioId'?: string
+}
+```
+
+---
+
+## Server requirements
+
+Any orchestrator implementing this spec MUST:
+
+1. **Validate auth**: reject without `Authorization` header (401), with a
+   mismatched bearer token (401), or without a recognized `X-Tangle-Tenant-Id`
+   (404).
+2. **Validate wire version**: reject incompatible wire versions (400 with
+   a clear error message). The major component is the breaking-change axis.
+3. **Validate tenant isolation**: queries with `tenantId` X never return
+   data tagged with `tenantId` Y. Test this adversarially.
+4. **Honor idempotency**: when an `Idempotency-Key` matches a prior
+   request from the same tenant in the last 24h, return the same response
+   without double-processing.
+5. **Persist eval-runs durably**: at least the event + cell scores must
+   survive an orchestrator restart. Trace spans MAY be best-effort.
+6. **Provide read access**: GET endpoints for the tenant to list + fetch
+   their own runs. Wire format for reads is NOT part of this spec — each
+   orchestrator can pick its own (REST + JSON, gRPC, GraphQL).
+
+Servers SHOULD also:
+
+- Provide a webhook callback per tenant for `gate-decided` events.
+- Provide a billable-events emitter (Stripe meter / equivalent) per ingest
+  call so consumption can be metered.
+- Provide a dashboard or API to view + diff per-scenario lifts over time.
+
+---
+
+## Reference implementation
+
+`examples/hosted-ingest-server/` — a minimal hono-based receiver. ~200
+LOC. Validates auth, accepts ingest, stores in memory, exposes a
+read endpoint. Runs anywhere Node runs.
+
+```sh
+TENANT_KEY=dev-token TENANT_ID=acme pnpm tsx examples/hosted-ingest-server/server.ts
+```
+
+In another terminal:
+
+```sh
+HOSTED_ENDPOINT=http://localhost:8080 \
+HOSTED_TENANT_KEY=dev-token \
+HOSTED_TENANT_ID=acme \
+pnpm tsx examples/foreign-agent-quickstart/index.ts
+```
+
+The quickstart's eval-run gets POSTed to the reference receiver; the
+receiver's `GET /v1/runs` lists it back.
+
+---
+
+## Versioning
+
+`HostedWireVersion` is `"2026-05-26.v1"`.
+
+- Adding an optional field → no version change.
+- Adding a new endpoint or new event type → minor wire bump
+  (`2026-05-26.v2`).
+- Changing the shape of an existing field, removing a field, or
+  changing semantics of an existing field → major wire bump
+  (`2026-11-XX.v1`); a server may accept both versions during a
+  transition window.
+
+Servers MUST reject requests with `X-Tangle-Wire-Version` they don't
+support, with a 400 listing the versions they DO accept.
+
+The version string IS the spec id — pin against it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-eval",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Substrate for self-improving agents: traces, verifiable rewards, preferences, GEPA / reflective mutation, auto-research, replay, sequential anytime-valid stats, and release gates.",
   "homepage": "https://github.com/tangle-network/agent-eval#readme",
   "repository": {
@@ -119,6 +119,11 @@
       "import": "./dist/adapters/http.js",
       "default": "./dist/adapters/http.js"
     },
+    "./hosted": {
+      "types": "./dist/hosted/index.d.ts",
+      "import": "./dist/hosted/index.js",
+      "default": "./dist/hosted/index.js"
+    },
     "./openapi.json": {
       "default": "./dist/openapi.json"
     }