@tangle-network/agent-eval 0.45.0 → 0.47.0

package/dist/adapters/http.d.ts

@@ -1,4 +1,4 @@
-import { S as Scenario, D as DispatchFn, g as DispatchContext } from '../types-BURGZ8Ug.js';
+import { S as Scenario, g as DispatchFn, D as DispatchContext } from '../types-8u72Gc76.js';
 
 /**
  * # `@tangle-network/agent-eval/adapters/http` — distributed Dispatch over HTTP.

package/dist/adapters/http.js

@@ -37,7 +37,9 @@ function httpDispatch(opts) {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
-            ...authValue ? { Authorization: authValue.startsWith("Bearer ") ? authValue : `Bearer ${authValue}` } : {},
+            ...authValue ? {
+              Authorization: authValue.startsWith("Bearer ") ? authValue : `Bearer ${authValue}`
+            } : {},
             ...opts.headers
           },
           body: JSON.stringify(body),
@@ -67,12 +69,15 @@ function httpDispatch(opts) {
 function sleep(ms) {
   return new Promise((resolve) => {
     const t = setTimeout(resolve, ms);
-    if (typeof t.unref === "function") t.unref();
+    if (typeof t.unref === "function")
+      t.unref();
   });
 }
 async function runDispatchServer(opts) {
   if (opts.auth === void 0) {
-    throw new Error("runDispatchServer: 'auth' is required (pass a bearer-token string, or `auth: false` explicitly for a closed-network test deployment).");
+    throw new Error(
+      "runDispatchServer: 'auth' is required (pass a bearer-token string, or `auth: false` explicitly for a closed-network test deployment)."
+    );
   }
   const path = opts.path ?? "/dispatch";
   const maxBytes = opts.maxBodyBytes ?? 10 * 1024 * 1024;
@@ -113,7 +118,9 @@ async function runDispatchServer(opts) {
         }
         chunks.push(buf);
       }
-      const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      const body = JSON.parse(
+        Buffer.concat(chunks).toString("utf8")
+      );
       cellId = body.cellId;
       const ctx = opts.contextFactory ? await opts.contextFactory(body, aborter.signal) : {
         cellId: body.cellId,

package/dist/adapters/http.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/http.ts"],"sourcesContent":["/**\n * # `@tangle-network/agent-eval/adapters/http` — distributed Dispatch over HTTP.\n *\n * Decouples driver and worker. The driver (running `runImprovementLoop` or\n * `runCampaign`) can live anywhere — your VPC, a dev laptop, a cron VM. The\n * workers (running the actual agent) can live anywhere else — different\n * regions, different clouds, different boxes — as long as they speak HTTP.\n *\n * Both sides:\n *\n *   - **`httpDispatch({ url | resolveUrl, ... })`** — client. Returns a\n *     `Dispatch` that POSTs `{ scenario, ctx }` to a worker URL and parses\n *     the artifact back. AbortSignal-aware, retries on idempotent errors,\n *     bounded timeout per call.\n *   - **`runDispatchServer({ dispatch, port, ... })`** — server. Wraps your\n *     local `Dispatch` as an HTTP endpoint. Handles auth, JSON parsing,\n *     error mapping, and cancellation when the client aborts.\n *\n * # Topology examples\n *\n * **Single-worker:** driver on box A, worker on box B. Set\n * `httpDispatch({ url: 'https://box-b/dispatch' })`.\n *\n * **Multi-region:** N workers across regions. Use `httpDispatch({ resolveUrl })`\n * with a function that picks the URL per cell from `ctx.placement`. Combined\n * with `cellPlacement` on `RunCampaignOptions`, the substrate fans cells\n * across geographies in parallel.\n *\n * **Driver-as-a-service:** driver runs as a long-lived process or service\n * (holds optimization state across generations); workers are stateless\n * HTTP services that can scale horizontally per cell.\n */\n\nimport type { Dispatch, DispatchContext, Scenario } from '../contract'\n\n// ── Client ───────────────────────────────────────────────────────────\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars -- TArtifact is unused\n//  in this options interface but kept as a parameter so callers can write\n//  `HttpDispatchOptions<MyScenario, MyArtifact>` symmetrically with\n//  `Dispatch<MyScenario, MyArtifact>`. Marking it unused at the position\n//  where it bites.\nexport interface HttpDispatchOptions<TScenario extends Scenario, _TArtifact> {\n  /** Static endpoint URL. Mutually exclusive with `resolveUrl`. */\n  url?: string\n  /**\n   * Dynamic per-cell URL resolver. Receives the scenario + the substrate\n   * placement key (from `RunCampaignOptions.cellPlacement`) and returns the\n   * worker URL to invoke. Mutually exclusive with `url`.\n   */\n  resolveUrl?: (input: { scenario: TScenario; placement?: string; cellId: string }) => string\n  /** Bearer token or static auth string set as `Authorization`. */\n  auth?: string | (() => string | Promise<string>)\n  /** Extra headers merged into every request. */\n  headers?: Record<string, string>\n  /** Per-call timeout in ms. Default 5 minutes. */\n  timeoutMs?: number\n  /** How many idempotent retries on 5xx / network errors. Default 2. */\n  retries?: number\n  /** Optional fetch override (auth wrappers, custom agent, mocks). */\n  fetchImpl?: typeof fetch\n}\n\nexport interface HttpDispatchRequestBody<TScenario extends Scenario> {\n  scenario: TScenario\n  cellId: string\n  rep: number\n  generation?: number\n  seed: number\n  placement?: string\n  cycleId?: string\n}\n\nexport interface HttpDispatchResponseBody<TArtifact> {\n  artifact: TArtifact\n}\n\nfunction resolveAuth(auth: HttpDispatchOptions<Scenario, unknown>['auth']): Promise<string | null> {\n  if (!auth) return Promise.resolve(null)\n  if (typeof auth === 'string') return Promise.resolve(auth)\n  return Promise.resolve(auth())\n}\n\n/**\n * Wrap a remote HTTP endpoint as a `Dispatch`. The remote side should run\n * `runDispatchServer` (or any service that speaks the same wire shape).\n *\n * Cancellation: the substrate's per-cell `AbortSignal` is forwarded; the\n * server's `runDispatchServer` translates the resulting `AbortError` into\n * a 499 (client-closed) so the client doesn't retry.\n */\nexport function httpDispatch<TScenario extends Scenario, TArtifact>(\n  opts: HttpDispatchOptions<TScenario, TArtifact>,\n): Dispatch<TScenario, TArtifact> {\n  if (!opts.url && !opts.resolveUrl) {\n    throw new Error('httpDispatch: pass exactly one of `url` or `resolveUrl`.')\n  }\n  if (opts.url && opts.resolveUrl) {\n    throw new Error('httpDispatch: pass exactly one of `url` or `resolveUrl`, not both.')\n  }\n  const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000\n  const maxRetries = opts.retries ?? 2\n  const f: typeof fetch = opts.fetchImpl ?? ((...args) => fetch(...args))\n\n  return async (scenario, ctx) => {\n    const url = opts.url ?? opts.resolveUrl!({ scenario, placement: ctx.placement, cellId: ctx.cellId })\n    const authValue = await resolveAuth(opts.auth)\n    const body: HttpDispatchRequestBody<TScenario> = {\n      scenario,\n      cellId: ctx.cellId,\n      rep: ctx.rep,\n      generation: ctx.generation,\n      seed: ctx.seed,\n      placement: ctx.placement,\n      cycleId: ctx.cycleId,\n    }\n\n    let lastError: unknown\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      // Compose the request signal: caller's signal OR our timeout.\n      const ourTimeout = AbortSignal.timeout(timeoutMs)\n      const combinedSignal = AbortSignal.any([ctx.signal, ourTimeout])\n      try {\n        const res = await f(url, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            ...(authValue ? { Authorization: authValue.startsWith('Bearer ') ? authValue : `Bearer ${authValue}` } : {}),\n            ...opts.headers,\n          },\n          body: JSON.stringify(body),\n          signal: combinedSignal,\n        })\n        if (!res.ok) {\n          // 4xx is non-retryable (caller error, auth, bad scenario shape).\n          // 5xx / 408 / 429 / 502 / 503 / 504 are retryable.\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(`httpDispatch ${url} failed (${res.status}): ${text.slice(0, 500)}`)\n          }\n          // exponential backoff with jitter\n          await sleep(2 ** attempt * 200 + Math.random() * 200)\n          continue\n        }\n        const parsed = (await res.json()) as HttpDispatchResponseBody<TArtifact>\n        return parsed.artifact\n      } catch (err) {\n        // Caller-driven abort is terminal — never retry.\n        if (ctx.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('httpDispatch exhausted retries')\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    const t = setTimeout(resolve, ms)\n    // Don't keep node process alive purely for backoff sleeps.\n    if (typeof (t as { unref?: () => void }).unref === 'function') (t as { unref: () => void }).unref()\n  })\n}\n\n// ── Server ───────────────────────────────────────────────────────────\n\nexport interface RunDispatchServerOptions<TScenario extends Scenario, TArtifact> {\n  /** The Dispatch this server exposes — what runs when a request lands. */\n  dispatch: Dispatch<TScenario, TArtifact>\n  /** TCP port to bind. */\n  port: number\n  /** Optional bind host; defaults to 0.0.0.0. */\n  host?: string\n  /** Required for any non-test deployment: the bearer token clients must\n   *  send. The substrate refuses to start without auth unless `auth: false`\n   *  is set explicitly (intended ONLY for closed-network/internal testing). */\n  auth: string | false\n  /** Path the server listens on. Default `/dispatch`. */\n  path?: string\n  /**\n   * Per-request handler that wraps `dispatch` with whatever context the\n   * worker side needs to construct a `DispatchContext` — typically the\n   * trace writer, artifact writer, and cost meter. The substrate provides\n   * synthetic-but-typed defaults if not supplied; production deployments\n   * should wire real ones (e.g. ship traces to your OTel collector).\n   */\n  contextFactory?: (req: HttpDispatchRequestBody<TScenario>, signal: AbortSignal) => Promise<DispatchContext>\n  /** Optional max payload size for the request body (bytes). Default 10 MB. */\n  maxBodyBytes?: number\n  /** Hook for observability — called on every successful or failed turn. */\n  onRequest?: (event: {\n    cellId: string\n    durationMs: number\n    success: boolean\n    error?: unknown\n  }) => void\n}\n\nexport interface DispatchServerHandle {\n  /** The actual bound port (useful when `port: 0` requests an ephemeral port). */\n  port: number\n  /** Stop accepting new connections and drain existing ones. */\n  close: () => Promise<void>\n}\n\n/**\n * Start an HTTP server exposing a local `Dispatch` over the wire. Pair with\n * `httpDispatch` on the driver side.\n *\n * Wire shape:\n *\n *   POST /dispatch\n *   Authorization: Bearer <token>\n *   Body: HttpDispatchRequestBody\n *   200 OK: HttpDispatchResponseBody\n *   401: missing/invalid auth\n *   408: per-request timeout exceeded\n *   499: client aborted before completion\n *   500: dispatch threw\n *\n * The server is `node:http`-based to keep the runtime dependency surface\n * minimal — works in plain Node, sandbox, or any container.\n */\nexport async function runDispatchServer<TScenario extends Scenario, TArtifact>(\n  opts: RunDispatchServerOptions<TScenario, TArtifact>,\n): Promise<DispatchServerHandle> {\n  if (opts.auth === undefined) {\n    throw new Error(\"runDispatchServer: 'auth' is required (pass a bearer-token string, or `auth: false` explicitly for a closed-network test deployment).\")\n  }\n  const path = opts.path ?? '/dispatch'\n  const maxBytes = opts.maxBodyBytes ?? 10 * 1024 * 1024\n  const expectedAuth = typeof opts.auth === 'string' ? `Bearer ${opts.auth.replace(/^Bearer\\s+/, '')}` : null\n\n  // Lazy-import node:http so the file is usable from non-Node bundlers\n  // that import the client side only (e.g. an edge driver shipping\n  // httpDispatch alone). Server side is opt-in by calling this function.\n  const { createServer } = await import('node:http')\n\n  const server = createServer(async (req, res) => {\n    const start = Date.now()\n    let cellId = 'unknown'\n    let success = false\n    let errCaught: unknown\n\n    try {\n      if (req.method !== 'POST' || req.url?.split('?')[0] !== path) {\n        res.statusCode = 404\n        res.end('not found')\n        return\n      }\n      if (expectedAuth) {\n        const got = req.headers['authorization']\n        if (got !== expectedAuth) {\n          res.statusCode = 401\n          res.end('unauthorized')\n          return\n        }\n      }\n\n      // Read body up to maxBytes\n      const chunks: Buffer[] = []\n      let totalBytes = 0\n      const aborter = new AbortController()\n      req.on('close', () => {\n        if (!res.writableEnded) aborter.abort()\n      })\n\n      for await (const chunk of req) {\n        const buf = chunk as Buffer\n        totalBytes += buf.length\n        if (totalBytes > maxBytes) {\n          res.statusCode = 413\n          res.end('payload too large')\n          return\n        }\n        chunks.push(buf)\n      }\n\n      const body = JSON.parse(Buffer.concat(chunks).toString('utf8')) as HttpDispatchRequestBody<TScenario>\n      cellId = body.cellId\n\n      const ctx: DispatchContext = opts.contextFactory\n        ? await opts.contextFactory(body, aborter.signal)\n        : {\n            cellId: body.cellId,\n            rep: body.rep,\n            generation: body.generation,\n            seed: body.seed,\n            signal: aborter.signal,\n            placement: body.placement,\n            cycleId: body.cycleId,\n            trace: NOOP_TRACE,\n            artifacts: NOOP_ARTIFACTS,\n            cost: NOOP_COST,\n          }\n\n      const artifact = await opts.dispatch(body.scenario, ctx)\n      const responseBody: HttpDispatchResponseBody<TArtifact> = { artifact }\n\n      res.statusCode = 200\n      res.setHeader('content-type', 'application/json')\n      res.end(JSON.stringify(responseBody))\n      success = true\n    } catch (err) {\n      errCaught = err\n      // Client-cancelled — they don't care about the result.\n      if ((err as Error)?.name === 'AbortError') {\n        res.statusCode = 499\n        res.end('client aborted')\n        return\n      }\n      res.statusCode = 500\n      res.setHeader('content-type', 'application/json')\n      res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))\n    } finally {\n      opts.onRequest?.({\n        cellId,\n        durationMs: Date.now() - start,\n        success,\n        error: errCaught,\n      })\n    }\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(opts.port, opts.host ?? '0.0.0.0', () => resolve())\n  })\n\n  const addr = server.address()\n  const boundPort = typeof addr === 'object' && addr ? addr.port : opts.port\n\n  return {\n    port: boundPort,\n    close: () =>\n      new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()))\n      }),\n  }\n}\n\n// ── No-op default ctx machinery (worker can replace via contextFactory) ──\n\nconst NOOP_TRACE = {\n  span: () => ({\n    end: () => {},\n    setAttribute: () => {},\n    setStatus: () => {},\n    recordException: () => {},\n    addEvent: () => {},\n  }),\n} as unknown as DispatchContext['trace']\n\nconst NOOP_ARTIFACTS = {\n  write: async () => undefined,\n  read: async () => undefined,\n  list: async () => [],\n} as unknown as DispatchContext['artifacts']\n\nconst NOOP_COST = {\n  record: () => {},\n  total: () => 0,\n} as unknown as DispatchContext['cost']\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/adapters/http.ts"],"sourcesContent":["/**\n * # `@tangle-network/agent-eval/adapters/http` — distributed Dispatch over HTTP.\n *\n * Decouples driver and worker. The driver (running `runImprovementLoop` or\n * `runCampaign`) can live anywhere — your VPC, a dev laptop, a cron VM. The\n * workers (running the actual agent) can live anywhere else — different\n * regions, different clouds, different boxes — as long as they speak HTTP.\n *\n * Both sides:\n *\n *   - **`httpDispatch({ url | resolveUrl, ... })`** — client. Returns a\n *     `Dispatch` that POSTs `{ scenario, ctx }` to a worker URL and parses\n *     the artifact back. AbortSignal-aware, retries on idempotent errors,\n *     bounded timeout per call.\n *   - **`runDispatchServer({ dispatch, port, ... })`** — server. Wraps your\n *     local `Dispatch` as an HTTP endpoint. Handles auth, JSON parsing,\n *     error mapping, and cancellation when the client aborts.\n *\n * # Topology examples\n *\n * **Single-worker:** driver on box A, worker on box B. Set\n * `httpDispatch({ url: 'https://box-b/dispatch' })`.\n *\n * **Multi-region:** N workers across regions. Use `httpDispatch({ resolveUrl })`\n * with a function that picks the URL per cell from `ctx.placement`. Combined\n * with `cellPlacement` on `RunCampaignOptions`, the substrate fans cells\n * across geographies in parallel.\n *\n * **Driver-as-a-service:** driver runs as a long-lived process or service\n * (holds optimization state across generations); workers are stateless\n * HTTP services that can scale horizontally per cell.\n */\n\nimport type { Dispatch, DispatchContext, Scenario } from '../contract'\n\n// ── Client ───────────────────────────────────────────────────────────\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars -- TArtifact is unused\n//  in this options interface but kept as a parameter so callers can write\n//  `HttpDispatchOptions<MyScenario, MyArtifact>` symmetrically with\n//  `Dispatch<MyScenario, MyArtifact>`. Marking it unused at the position\n//  where it bites.\nexport interface HttpDispatchOptions<TScenario extends Scenario, _TArtifact> {\n  /** Static endpoint URL. Mutually exclusive with `resolveUrl`. */\n  url?: string\n  /**\n   * Dynamic per-cell URL resolver. Receives the scenario + the substrate\n   * placement key (from `RunCampaignOptions.cellPlacement`) and returns the\n   * worker URL to invoke. Mutually exclusive with `url`.\n   */\n  resolveUrl?: (input: { scenario: TScenario; placement?: string; cellId: string }) => string\n  /** Bearer token or static auth string set as `Authorization`. */\n  auth?: string | (() => string | Promise<string>)\n  /** Extra headers merged into every request. */\n  headers?: Record<string, string>\n  /** Per-call timeout in ms. Default 5 minutes. */\n  timeoutMs?: number\n  /** How many idempotent retries on 5xx / network errors. Default 2. */\n  retries?: number\n  /** Optional fetch override (auth wrappers, custom agent, mocks). */\n  fetchImpl?: typeof fetch\n}\n\nexport interface HttpDispatchRequestBody<TScenario extends Scenario> {\n  scenario: TScenario\n  cellId: string\n  rep: number\n  generation?: number\n  seed: number\n  placement?: string\n  cycleId?: string\n}\n\nexport interface HttpDispatchResponseBody<TArtifact> {\n  artifact: TArtifact\n}\n\nfunction resolveAuth(auth: HttpDispatchOptions<Scenario, unknown>['auth']): Promise<string | null> {\n  if (!auth) return Promise.resolve(null)\n  if (typeof auth === 'string') return Promise.resolve(auth)\n  return Promise.resolve(auth())\n}\n\n/**\n * Wrap a remote HTTP endpoint as a `Dispatch`. The remote side should run\n * `runDispatchServer` (or any service that speaks the same wire shape).\n *\n * Cancellation: the substrate's per-cell `AbortSignal` is forwarded; the\n * server's `runDispatchServer` translates the resulting `AbortError` into\n * a 499 (client-closed) so the client doesn't retry.\n */\nexport function httpDispatch<TScenario extends Scenario, TArtifact>(\n  opts: HttpDispatchOptions<TScenario, TArtifact>,\n): Dispatch<TScenario, TArtifact> {\n  if (!opts.url && !opts.resolveUrl) {\n    throw new Error('httpDispatch: pass exactly one of `url` or `resolveUrl`.')\n  }\n  if (opts.url && opts.resolveUrl) {\n    throw new Error('httpDispatch: pass exactly one of `url` or `resolveUrl`, not both.')\n  }\n  const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000\n  const maxRetries = opts.retries ?? 2\n  const f: typeof fetch = opts.fetchImpl ?? ((...args) => fetch(...args))\n\n  return async (scenario, ctx) => {\n    const url =\n      opts.url ?? opts.resolveUrl!({ scenario, placement: ctx.placement, cellId: ctx.cellId })\n    const authValue = await resolveAuth(opts.auth)\n    const body: HttpDispatchRequestBody<TScenario> = {\n      scenario,\n      cellId: ctx.cellId,\n      rep: ctx.rep,\n      generation: ctx.generation,\n      seed: ctx.seed,\n      placement: ctx.placement,\n      cycleId: ctx.cycleId,\n    }\n\n    let lastError: unknown\n    for (let attempt = 0; attempt <= maxRetries; attempt++) {\n      // Compose the request signal: caller's signal OR our timeout.\n      const ourTimeout = AbortSignal.timeout(timeoutMs)\n      const combinedSignal = AbortSignal.any([ctx.signal, ourTimeout])\n      try {\n        const res = await f(url, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            ...(authValue\n              ? {\n                  Authorization: authValue.startsWith('Bearer ')\n                    ? authValue\n                    : `Bearer ${authValue}`,\n                }\n              : {}),\n            ...opts.headers,\n          },\n          body: JSON.stringify(body),\n          signal: combinedSignal,\n        })\n        if (!res.ok) {\n          // 4xx is non-retryable (caller error, auth, bad scenario shape).\n          // 5xx / 408 / 429 / 502 / 503 / 504 are retryable.\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(`httpDispatch ${url} failed (${res.status}): ${text.slice(0, 500)}`)\n          }\n          // exponential backoff with jitter\n          await sleep(2 ** attempt * 200 + Math.random() * 200)\n          continue\n        }\n        const parsed = (await res.json()) as HttpDispatchResponseBody<TArtifact>\n        return parsed.artifact\n      } catch (err) {\n        // Caller-driven abort is terminal — never retry.\n        if (ctx.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('httpDispatch exhausted retries')\n  }\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    const t = setTimeout(resolve, ms)\n    // Don't keep node process alive purely for backoff sleeps.\n    if (typeof (t as { unref?: () => void }).unref === 'function')\n      (t as { unref: () => void }).unref()\n  })\n}\n\n// ── Server ───────────────────────────────────────────────────────────\n\nexport interface RunDispatchServerOptions<TScenario extends Scenario, TArtifact> {\n  /** The Dispatch this server exposes — what runs when a request lands. */\n  dispatch: Dispatch<TScenario, TArtifact>\n  /** TCP port to bind. */\n  port: number\n  /** Optional bind host; defaults to 0.0.0.0. */\n  host?: string\n  /** Required for any non-test deployment: the bearer token clients must\n   *  send. The substrate refuses to start without auth unless `auth: false`\n   *  is set explicitly (intended ONLY for closed-network/internal testing). */\n  auth: string | false\n  /** Path the server listens on. Default `/dispatch`. */\n  path?: string\n  /**\n   * Per-request handler that wraps `dispatch` with whatever context the\n   * worker side needs to construct a `DispatchContext` — typically the\n   * trace writer, artifact writer, and cost meter. The substrate provides\n   * synthetic-but-typed defaults if not supplied; production deployments\n   * should wire real ones (e.g. ship traces to your OTel collector).\n   */\n  contextFactory?: (\n    req: HttpDispatchRequestBody<TScenario>,\n    signal: AbortSignal,\n  ) => Promise<DispatchContext>\n  /** Optional max payload size for the request body (bytes). Default 10 MB. */\n  maxBodyBytes?: number\n  /** Hook for observability — called on every successful or failed turn. */\n  onRequest?: (event: {\n    cellId: string\n    durationMs: number\n    success: boolean\n    error?: unknown\n  }) => void\n}\n\nexport interface DispatchServerHandle {\n  /** The actual bound port (useful when `port: 0` requests an ephemeral port). */\n  port: number\n  /** Stop accepting new connections and drain existing ones. */\n  close: () => Promise<void>\n}\n\n/**\n * Start an HTTP server exposing a local `Dispatch` over the wire. Pair with\n * `httpDispatch` on the driver side.\n *\n * Wire shape:\n *\n *   POST /dispatch\n *   Authorization: Bearer <token>\n *   Body: HttpDispatchRequestBody\n *   200 OK: HttpDispatchResponseBody\n *   401: missing/invalid auth\n *   408: per-request timeout exceeded\n *   499: client aborted before completion\n *   500: dispatch threw\n *\n * The server is `node:http`-based to keep the runtime dependency surface\n * minimal — works in plain Node, sandbox, or any container.\n */\nexport async function runDispatchServer<TScenario extends Scenario, TArtifact>(\n  opts: RunDispatchServerOptions<TScenario, TArtifact>,\n): Promise<DispatchServerHandle> {\n  if (opts.auth === undefined) {\n    throw new Error(\n      \"runDispatchServer: 'auth' is required (pass a bearer-token string, or `auth: false` explicitly for a closed-network test deployment).\",\n    )\n  }\n  const path = opts.path ?? '/dispatch'\n  const maxBytes = opts.maxBodyBytes ?? 10 * 1024 * 1024\n  const expectedAuth =\n    typeof opts.auth === 'string' ? `Bearer ${opts.auth.replace(/^Bearer\\s+/, '')}` : null\n\n  // Lazy-import node:http so the file is usable from non-Node bundlers\n  // that import the client side only (e.g. an edge driver shipping\n  // httpDispatch alone). Server side is opt-in by calling this function.\n  const { createServer } = await import('node:http')\n\n  const server = createServer(async (req, res) => {\n    const start = Date.now()\n    let cellId = 'unknown'\n    let success = false\n    let errCaught: unknown\n\n    try {\n      if (req.method !== 'POST' || req.url?.split('?')[0] !== path) {\n        res.statusCode = 404\n        res.end('not found')\n        return\n      }\n      if (expectedAuth) {\n        const got = req.headers['authorization']\n        if (got !== expectedAuth) {\n          res.statusCode = 401\n          res.end('unauthorized')\n          return\n        }\n      }\n\n      // Read body up to maxBytes\n      const chunks: Buffer[] = []\n      let totalBytes = 0\n      const aborter = new AbortController()\n      req.on('close', () => {\n        if (!res.writableEnded) aborter.abort()\n      })\n\n      for await (const chunk of req) {\n        const buf = chunk as Buffer\n        totalBytes += buf.length\n        if (totalBytes > maxBytes) {\n          res.statusCode = 413\n          res.end('payload too large')\n          return\n        }\n        chunks.push(buf)\n      }\n\n      const body = JSON.parse(\n        Buffer.concat(chunks).toString('utf8'),\n      ) as HttpDispatchRequestBody<TScenario>\n      cellId = body.cellId\n\n      const ctx: DispatchContext = opts.contextFactory\n        ? await opts.contextFactory(body, aborter.signal)\n        : {\n            cellId: body.cellId,\n            rep: body.rep,\n            generation: body.generation,\n            seed: body.seed,\n            signal: aborter.signal,\n            placement: body.placement,\n            cycleId: body.cycleId,\n            trace: NOOP_TRACE,\n            artifacts: NOOP_ARTIFACTS,\n            cost: NOOP_COST,\n          }\n\n      const artifact = await opts.dispatch(body.scenario, ctx)\n      const responseBody: HttpDispatchResponseBody<TArtifact> = { artifact }\n\n      res.statusCode = 200\n      res.setHeader('content-type', 'application/json')\n      res.end(JSON.stringify(responseBody))\n      success = true\n    } catch (err) {\n      errCaught = err\n      // Client-cancelled — they don't care about the result.\n      if ((err as Error)?.name === 'AbortError') {\n        res.statusCode = 499\n        res.end('client aborted')\n        return\n      }\n      res.statusCode = 500\n      res.setHeader('content-type', 'application/json')\n      res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))\n    } finally {\n      opts.onRequest?.({\n        cellId,\n        durationMs: Date.now() - start,\n        success,\n        error: errCaught,\n      })\n    }\n  })\n\n  await new Promise<void>((resolve, reject) => {\n    server.once('error', reject)\n    server.listen(opts.port, opts.host ?? '0.0.0.0', () => resolve())\n  })\n\n  const addr = server.address()\n  const boundPort = typeof addr === 'object' && addr ? addr.port : opts.port\n\n  return {\n    port: boundPort,\n    close: () =>\n      new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()))\n      }),\n  }\n}\n\n// ── No-op default ctx machinery (worker can replace via contextFactory) ──\n\nconst NOOP_TRACE = {\n  span: () => ({\n    end: () => {},\n    setAttribute: () => {},\n    setStatus: () => {},\n    recordException: () => {},\n    addEvent: () => {},\n  }),\n} as unknown as DispatchContext['trace']\n\nconst NOOP_ARTIFACTS = {\n  write: async () => undefined,\n  read: async () => undefined,\n  list: async () => [],\n} as unknown as DispatchContext['artifacts']\n\nconst NOOP_COST = {\n  record: () => {},\n  total: () => 0,\n} as unknown as DispatchContext['cost']\n"],"mappings":"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","names":[]}

package/dist/adapters/langchain.d.ts

@@ -1,4 +1,4 @@
-import { S as Scenario, n as JudgeScore, D as DispatchFn, J as JudgeConfig } from '../types-BURGZ8Ug.js';
+import { S as Scenario, n as JudgeScore, g as DispatchFn, J as JudgeConfig } from '../types-8u72Gc76.js';
 
 /**
  * # `@tangle-network/agent-eval/adapters/langchain` — wrap any LangChain

package/dist/campaign/index.d.ts

@@ -1,6 +1,6 @@
-export { C as CampaignStorage, D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, O as OpenAutoPrOptions, m as OpenAutoPrResult, R as RunCampaignOptions, a as RunEvalOptions, b as RunImprovementLoopOptions, c as RunImprovementLoopResult, n as RunOptimizationOptions, o as RunOptimizationResult, d as composeGate, e as defaultProductionGate, f as evolutionaryDriver, g as fsCampaignStorage, h as gepaDriver, i as heldOutGate, j as inMemoryCampaignStorage, p as openAutoPr, r as runCampaign, k as runEval, l as runImprovementLoop, q as runOptimization, s as surfaceHash } from '../run-improvement-loop-pJ4yrx4X.js';
-import { L as LabeledScenarioStore, q as LabeledScenarioWrite, r as LabeledScenarioSampleArgs, s as LabeledScenarioRecord, f as CodeSurface } from '../types-BURGZ8Ug.js';
-export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, g as DispatchContext, D as DispatchFn, G as Gate, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, I as ImprovementDriver, t as JudgeAggregate, J as JudgeConfig, m as JudgeDimension, n as JudgeScore, u as LabeledScenarioSource, M as MutableSurface, o as Mutator, O as OptimizerConfig, P as ProposeContext, R as RedactionStatus, S as Scenario, v as ScenarioAggregate, p as SessionScript, T as TraceSpan } from '../types-BURGZ8Ug.js';
+export { C as CampaignStorage, D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, O as OpenAutoPrOptions, m as OpenAutoPrResult, a as RunCampaignOptions, b as RunEvalOptions, c as RunImprovementLoopOptions, R as RunImprovementLoopResult, n as RunOptimizationOptions, o as RunOptimizationResult, d as composeGate, e as defaultProductionGate, f as evolutionaryDriver, g as fsCampaignStorage, h as gepaDriver, i as heldOutGate, j as inMemoryCampaignStorage, p as openAutoPr, r as runCampaign, k as runEval, l as runImprovementLoop, q as runOptimization, s as surfaceHash } from '../run-improvement-loop-Bfam3MT1.js';
+import { L as LabeledScenarioStore, q as LabeledScenarioWrite, r as LabeledScenarioSampleArgs, s as LabeledScenarioRecord, f as CodeSurface } from '../types-8u72Gc76.js';
+export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, D as DispatchContext, g as DispatchFn, G as Gate, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, I as ImprovementDriver, t as JudgeAggregate, J as JudgeConfig, m as JudgeDimension, n as JudgeScore, u as LabeledScenarioSource, M as MutableSurface, o as Mutator, O as OptimizerConfig, P as ProposeContext, R as RedactionStatus, S as Scenario, v as ScenarioAggregate, p as SessionScript, T as TraceSpan } from '../types-8u72Gc76.js';
 import '../llm-client-BXVRUZyX.js';
 import '../errors-mje_cKOs.js';
 import '../raw-provider-sink-C46HDghv.js';

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

@@ -1,6 +1,9 @@
-export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, f as CodeSurface, D as Dispatch, g as DispatchContext, G as Gate, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, I as ImprovementDriver, J as JudgeConfig, m as JudgeDimension, n as JudgeScore, M as MutableSurface, o as Mutator, O as OptimizerConfig, S as Scenario, p as SessionScript } from '../types-BURGZ8Ug.js';
-export { C as CampaignStorage, D as DefaultProductionGateOptions, E as EvolutionaryDriverOptions, G as GepaDriverOptions, H as HeldOutGateOptions, R as RunCampaignOptions, a as RunEvalOptions, b as RunImprovementLoopOptions, c as RunImprovementLoopResult, 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-pJ4yrx4X.js';
+import { S as Scenario, M as MutableSurface, D as DispatchContext, J as JudgeConfig, I as ImprovementDriver, G as Gate } from '../types-8u72Gc76.js';
+export { C as CampaignAggregates, a as CampaignArtifactWriter, b as CampaignCellResult, c as CampaignCostMeter, d as CampaignResult, e as CampaignTraceWriter, f as CodeSurface, g as Dispatch, h as GateContext, i as GateDecision, j as GateResult, k as GenerationCandidate, l as GenerationRecord, m as JudgeDimension, n as JudgeScore, o as Mutator, O as OptimizerConfig, p as SessionScript } from '../types-8u72Gc76.js';
+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';
@@ -8,3 +11,215 @@ import '@tangle-network/agent-runtime';
 import '../red-team-30II1T4o.js';
 import '../dataset-BlwAtYYf.js';
 import '../store-Db2Bv8Cf.js';
+
+/**
+ * # `selfImprove()` — the LAND-tier one-shot.
+ *
+ * The cheapest possible call site to run a real closed-loop self-
+ * improvement over your agent. Wraps `runImprovementLoop` with smart
+ * defaults and a budget-shaped options API; every escape hatch the
+ * substrate exposes is reachable from here without losing the
+ * one-function feel.
+ *
+ * Defaults picked to match the LAND-tier story:
+ *   - In-memory storage (no filesystem touch).
+ *   - `gepaDriver` reflective mutation with copywriting-flavored primitives
+ *     (override `driver` or `mutationPrimitives` for any domain).
+ *   - `defaultProductionGate` with `deltaThreshold: 0.05`.
+ *   - Held-out split = 25% of scenarios, deterministic by id hash.
+ *   - 3 generations × population 2 (raise via `budget` for more search).
+ *   - `autoOnPromote: 'none'` (we don't open PRs unless you ask).
+ *
+ * Want one-click? Provide `agent` + `scenarios` + `judge`. Done.
+ * Want distributed? Pass `cellPlacement` + an `httpDispatch`-backed
+ * agent. Want a code-tier surface? Pass a `MutableSurface` + your own
+ * `driver`. Same function.
+ */
+
+interface SelfImproveBudget {
+    /** Hard $ ceiling across all cells in baseline + every generation. Cells
+     *  beyond the ceiling are skipped (cost-aware, not aborted). */
+    dollars?: number;
+    /** How many improvement generations to explore. Default 3. Set 0 to
+     *  skip improvement entirely (selfImprove becomes a baseline-only run). */
+    generations?: number;
+    /** Candidates the driver proposes per generation. Default 2. */
+    populationSize?: number;
+    /** Max concurrent cells across the loop. Default 2. */
+    maxConcurrency?: number;
+    /** Fraction of `scenarios` held out from training, used for the gate.
+     *  Default 0.25. Ignored when `holdoutScenarios` is set explicitly. */
+    holdoutFraction?: number;
+    /** Explicit held-out scenarios; overrides `holdoutFraction`. */
+    holdoutScenarios?: Scenario[];
+}
+interface SelfImproveLlm {
+    /** Endpoint base URL. Default Tangle Router. */
+    baseUrl?: string;
+    /** Bearer token. Default `process.env.OPENAI_API_KEY`. */
+    apiKey?: string;
+    /** Model id used by `gepaDriver` reflection. Default
+     *  `anthropic/claude-sonnet-4.6`. */
+    model?: string;
+}
+type SelfImproveProgressEvent = {
+    kind: 'baseline.started';
+    scenarios: number;
+} | {
+    kind: 'baseline.completed';
+    compositeMean: number;
+    durationMs: number;
+} | {
+    kind: 'generation.started';
+    index: number;
+    populationSize: number;
+} | {
+    kind: 'generation.completed';
+    index: number;
+    bestComposite: number;
+    durationMs: number;
+} | {
+    kind: 'gate.decided';
+    decision: string;
+    lift: number;
+};
+interface SelfImproveOptions<TScenario extends Scenario, TArtifact> {
+    /**
+     * Your agent — a function that takes the current `MutableSurface`
+     * (typically a system prompt the loop is optimizing) plus the
+     * scenario + cell ctx, and returns the artifact your judge scores.
+     *
+     * Same shape as `RunOptimizationOptions.dispatchWithSurface`. Wrap a
+     * plain `Dispatch` if you don't have a surface seam:
+     *
+     *   agent: (_surface, scenario, ctx) => yourPlainDispatch(scenario, ctx)
+     *
+     * That mode evaluates without mutating any surface — useful as a
+     * baseline-only run (set `budget.generations = 0`).
+     */
+    agent: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+    /** Scenarios to evaluate against. Train/holdout split is computed from
+     *  these unless `budget.holdoutScenarios` is set explicitly. */
+    scenarios: TScenario[];
+    /** Judge that scores artifacts. Bring your own; use `langchainJudge`
+     *  from `/adapters/langchain` for a Runnable-shaped one. */
+    judge: JudgeConfig<TArtifact, TScenario>;
+    /** Starting surface — system prompt, JSON config, anything `MutableSurface`
+     *  accepts. The driver mutates this each generation. */
+    baselineSurface: MutableSurface;
+    /** Budget + loop shape. All fields optional; defaults pick the LAND-tier
+     *  story. */
+    budget?: SelfImproveBudget;
+    /** Custom driver. Default is `gepaDriver` configured from `llm` +
+     *  `mutationPrimitives`. */
+    driver?: ImprovementDriver;
+    /** Default-driver overrides — used when `driver` is unset. */
+    mutationPrimitives?: string[];
+    driverTarget?: string;
+    /** Custom gate. Default is `defaultProductionGate` with
+     *  `deltaThreshold: 0.05` on the held-out split. */
+    gate?: Gate<TArtifact, TScenario>;
+    /** LLM config consumed by the default `gepaDriver`. Ignored if you pass
+     *  your own `driver`. */
+    llm?: SelfImproveLlm;
+    /** Storage backend. Default `inMemoryCampaignStorage()` — nothing
+     *  persists past the call. Pass `fsCampaignStorage()` to write to disk. */
+    storage?: CampaignStorage;
+    /** Run directory (logical for in-memory storage, real path for fs).
+     *  Default `mem://selfImprove-<timestamp>`. */
+    runDir?: string;
+    /** Distributed-driver seam — same as `RunCampaignOptions.cellPlacement`.
+     *  Returns an opaque placement key the substrate forwards to your agent
+     *  as `ctx.placement`. Combined with `httpDispatch` from
+     *  `/adapters/http`, fans cells across regions. */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
+    /** Streaming hook — fires on baseline + each generation + gate decision.
+     *  Consumer routes events wherever (UI, dashboard, logs). */
+    onProgress?: (event: SelfImproveProgressEvent) => void;
+    /** Auto-promotion behavior on a ship decision. Default `'none'` — we
+     *  return the winner; you ship it however you ship. `'pr'` opens a
+     *  GitHub PR via `openAutoPr`; requires `ghOwner` + `ghRepo`. */
+    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. */
+    baseline: {
+        compositeMean: number;
+        perScenario: Record<string, number>;
+    };
+    /** Composite mean on the held-out set, winner run. */
+    winner: {
+        compositeMean: number;
+        perScenario: Record<string, number>;
+        surface: MutableSurface;
+    };
+    /** `winner.compositeMean - baselineOnHoldout.compositeMean`. Positive
+     *  means the gate observed improvement. */
+    lift: number;
+    /** `defaultProductionGate.decide()` result. */
+    gateDecision: 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
+    /** Number of generations actually explored (may be less than the
+     *  budget if the driver gave up early). */
+    generationsExplored: number;
+    /** Wall-clock total. */
+    durationMs: number;
+    /** Total cost across baseline + every generation. */
+    totalCostUsd: number;
+    /**
+     * Raw substrate result for advanced inspection — full per-generation
+     * candidates, full campaign artifacts, all judge scores. Useful for
+     * debugging or reporting beyond the summary.
+     */
+    raw: RunImprovementLoopResult<TArtifact, TScenario>;
+}
+/**
+ * One-shot self-improvement loop. See module docstring for defaults +
+ * extension points.
+ *
+ * @example Minimum (LAND tier):
+ *
+ *   const result = await selfImprove({
+ *     agent: (surface, scenario, ctx) => myAgent(surface, scenario, ctx.signal),
+ *     scenarios,
+ *     judge,
+ *     baselineSurface: DEFAULT_PROMPT,
+ *   })
+ *   console.log(`lift: ${result.lift.toFixed(3)} (${result.gateDecision})`)
+ *
+ * @example Distributed (workers in three regions):
+ *
+ *   await selfImprove({
+ *     agent: httpDispatch({ resolveUrl: ({ placement }) => REGION_URLS[placement!] }),
+ *     scenarios,
+ *     judge,
+ *     baselineSurface: DEFAULT_PROMPT,
+ *     cellPlacement: ({ scenario }) => scenario.region,
+ *     budget: { maxConcurrency: 12 },
+ *   })
+ */
+declare function selfImprove<TScenario extends Scenario, TArtifact>(opts: SelfImproveOptions<TScenario, TArtifact>): Promise<SelfImproveResult<TScenario, TArtifact>>;
+
+export { CampaignStorage, DispatchContext, Gate, ImprovementDriver, JudgeConfig, MutableSurface, RunImprovementLoopResult, Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, selfImprove };