@tangle-network/agent-runtime 0.134.2 → 0.134.3

package/dist/util-CG3ghHfb.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"util-CG3ghHfb.js","names":[],"sources":["../src/runtime/util.ts"],"sourcesContent":["/**\n *\n * Internal loop-kernel utilities shared across the kernel, drivers, and the\n * sandbox-acquire layer. Not part of the public barrel surface.\n *\n * @experimental\n */\n\nimport type { SandboxInstance } from '@tangle-network/sandbox'\nimport type { LoopTokenUsage } from './types'\n\n/**\n * Best-effort sandbox delete. Skips instances without a `delete` (test fakes);\n * swallows errors (the platform reaps on expiry). Returns `false` when delete\n * threw, `true` otherwise, so callers can surface a leak if they choose.\n */\nexport async function deleteBoxSafe(box: SandboxInstance | undefined): Promise<boolean> {\n  if (!box || typeof (box as { delete?: unknown }).delete !== 'function') return true\n  try {\n    await box.delete()\n    return true\n  } catch {\n    return false\n  }\n}\n\n/** Short base36 id for trace correlation. Not cryptographic, not collision-free. */\nexport function randomSuffix(len = 8): string {\n  return Math.random()\n    .toString(36)\n    .slice(2, 2 + len)\n}\n\n/** Collision-resistant id for sandbox naming (find-by-name recovery must be unique). */\nexport function randomUuid(): string {\n  return crypto.randomUUID()\n}\n\n/** Construct an AbortError. Downstream code pattern-matches on `err.name`. */\nexport function abortError(): Error {\n  const err = new Error('aborted')\n  err.name = 'AbortError'\n  return err\n}\n\n/** Throw an AbortError. */\nexport function throwAbort(): never {\n  throw abortError()\n}\n\n/** Throw if the signal is already aborted; otherwise no-op. */\nexport function throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal?.aborted) throw abortError()\n}\n\n/** True for any error whose `name` is `AbortError` (the cross-kernel abort contract). */\nexport function isAbortError(err: unknown): boolean {\n  return err instanceof Error && err.name === 'AbortError'\n}\n\n/**\n * Sleep that resolves early on abort and always clears its timer so it never\n * keeps the event loop alive. Resolves (does not reject) on abort — callers\n * re-check the signal explicitly after the sleep.\n */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve()\n      return\n    }\n    let onAbort: (() => void) | undefined\n    const timer = setTimeout(() => {\n      if (onAbort && signal) signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, ms)\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer)\n        resolve()\n      }\n      signal.addEventListener('abort', onAbort, { once: true })\n    }\n  })\n}\n\n/**\n * Race a promise against a timeout. Resolves with the value if it settles in\n * time, otherwise resolves with `undefined`. Always clears the timer.\n */\nexport function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {\n  return new Promise<T | undefined>((resolve) => {\n    const timer = setTimeout(() => resolve(undefined), ms)\n    promise.then(\n      (value) => {\n        clearTimeout(timer)\n        resolve(value)\n      },\n      () => {\n        clearTimeout(timer)\n        resolve(undefined)\n      },\n    )\n  })\n}\n\ninterface StringifyOptions {\n  /** Pretty-print with 2-space indent. Default false (compact). */\n  pretty?: boolean\n  /** Truncate to this many chars, appending `…`. Default unbounded. */\n  max?: number\n}\n\n/**\n * `JSON.stringify` with a `String()` fallback on throw (cyclic / non-JSON).\n * Strings pass through unstringified so a preview of a string output is the\n * string itself, not a quoted re-encoding.\n */\nexport function stringifySafe(value: unknown, opts: StringifyOptions = {}): string {\n  let s: string\n  try {\n    if (typeof value === 'string') {\n      s = value\n    } else {\n      const json = opts.pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value)\n      s = json ?? String(value)\n    }\n  } catch {\n    s = String(value)\n  }\n  if (opts.max !== undefined && s.length > opts.max) return `${s.slice(0, opts.max)}…`\n  return s\n}\n\n/** A fresh zero token-usage accumulator. */\nexport function zeroTokenUsage(): LoopTokenUsage {\n  return { input: 0, output: 0 }\n}\n\n/** Copy a token subtotal without dropping optional provider cache telemetry. */\nexport function cloneTokenUsage(usage: LoopTokenUsage): LoopTokenUsage {\n  const cacheBreakdownUnknown =\n    usage.cacheBreakdownKnown === false || (usage.input > 0 && !hasClassifiedCacheBreakdown(usage))\n  return {\n    input: usage.input,\n    output: usage.output,\n    ...(usage.tokensKnown === false ? { tokensKnown: false as const } : {}),\n    ...(usage.freshInput !== undefined ? { freshInput: usage.freshInput } : {}),\n    ...(usage.cacheRead !== undefined ? { cacheRead: usage.cacheRead } : {}),\n    ...(usage.cacheWrite !== undefined ? { cacheWrite: usage.cacheWrite } : {}),\n    ...(cacheBreakdownUnknown ? { cacheBreakdownKnown: false as const } : {}),\n  }\n}\n\n/** True only when every positive prompt token has a consistent cache classification. */\nexport function hasCompleteCacheBreakdown(usage: LoopTokenUsage): boolean {\n  if (usage.cacheBreakdownKnown === false) return false\n  return hasClassifiedCacheBreakdown(usage)\n}\n\nfunction hasClassifiedCacheBreakdown(usage: LoopTokenUsage): boolean {\n  if (usage.input === 0) return true\n  if (\n    usage.freshInput === undefined ||\n    usage.cacheRead === undefined ||\n    usage.cacheWrite === undefined\n  ) {\n    return false\n  }\n  return usage.freshInput + usage.cacheRead + usage.cacheWrite === usage.input\n}\n\n/**\n * The token charge for one observation: every token counted ONCE, at the moment it first enters\n * the context — `input − cacheRead + output`.\n *\n * `input` is a rolled-up prompt total that re-counts a cached prefix on every turn that reads it,\n * so charging `input` makes a 100K prefix read 40 times cost 4.1M for content authored once. A\n * cache read is content that was already charged when it was written, so it is the one class the\n * charge subtracts. Under a complete split the result is exactly `freshInput + cacheWrite`. No\n * price weight is involved: this counts work, and money is a separate channel.\n *\n * The subtraction form is what makes the charge ADDITIVE. `input` and `cacheRead` both accumulate\n * through `addTokenUsage`, so the charge on an aggregate equals the sum of the charges on the\n * records that built it — including an aggregate that mixes classified and unclassified turns,\n * where the unclassified remainder is charged in full and only the reported cache reads are\n * credited. A form that read `freshInput + cacheWrite` directly loses that: one unclassified turn\n * would drop the whole aggregate to `input + output` and over-charge every classified turn with it.\n *\n * The one arithmetic guarantee: a set of classes that does not FIT inside the prompt total it\n * partitions credits nothing, so the charge is never below `output` and a class that overflows its\n * own total buys no tokens. It is not a guarantee against a provider that reports a cache read it\n * never served — that provider can under-report `input` just as easily, and the token channel is an\n * accounting unit, not a trust boundary. Prompt tokens the provider left unclassified are charged\n * in full, so a spend with no readable split charges an upper bound on newly-presented work rather\n * than a measurement, and every caller that enforces a ceiling must report the difference\n * (`BudgetPool` does it through `readout().cacheBreakdownKnown`).\n */\nexport function chargedTokens(usage: LoopTokenUsage): number {\n  return usage.input - creditedCacheRead(usage) + usage.output\n}\n\n/** `cacheRead` if the reported classes fit inside `input`, else nothing. */\nfunction creditedCacheRead(usage: LoopTokenUsage): number {\n  const { cacheRead } = usage\n  if (cacheRead === undefined) return 0\n  return classifiedTotal(usage, cacheRead) > usage.input ? 0 : cacheRead\n}\n\nfunction classifiedTotal(usage: Partial<LoopTokenUsage>, cacheRead: number): number {\n  return (usage.freshInput ?? 0) + cacheRead + (usage.cacheWrite ?? 0)\n}\n\n/**\n * Add the observed subtotal into `acc`; token and cache incompleteness are sticky.\n *\n * A delta whose classes do not FIT inside its own `input` contributes its prompt total and NO\n * classes. Folding them in would hide the overflow: the accumulator's larger `input` can absorb a\n * class total that overflowed the one delta that reported it, and `chargedTokens` would then credit\n * at the aggregate a cache read it refuses at the record. That is the one way the charge could come\n * out below the sum of the charges on the records that built it.\n */\nexport function addTokenUsage(acc: LoopTokenUsage, delta: Partial<LoopTokenUsage>): void {\n  acc.input += delta.input ?? 0\n  acc.output += delta.output ?? 0\n  if (delta.tokensKnown === false) acc.tokensKnown = false\n\n  const input = delta.input ?? 0\n  const fits = classifiedTotal(delta, delta.cacheRead ?? 0) <= input\n  if (fits) {\n    if (delta.freshInput !== undefined) acc.freshInput = (acc.freshInput ?? 0) + delta.freshInput\n    if (delta.cacheRead !== undefined) acc.cacheRead = (acc.cacheRead ?? 0) + delta.cacheRead\n    if (delta.cacheWrite !== undefined) acc.cacheWrite = (acc.cacheWrite ?? 0) + delta.cacheWrite\n  }\n\n  const classified =\n    fits &&\n    delta.freshInput !== undefined &&\n    delta.cacheRead !== undefined &&\n    delta.cacheWrite !== undefined &&\n    delta.freshInput + delta.cacheRead + delta.cacheWrite === input\n  // A provider that reports prompt input without all three classes leaves the\n  // split unknown. Do not let an earlier complete turn make the aggregate look\n  // complete after a later unclassified positive-input turn.\n  if (delta.cacheBreakdownKnown === false || (input > 0 && !classified)) {\n    acc.cacheBreakdownKnown = false\n  }\n}\n\n/**\n * Map `items` through `fn` with at most `limit` calls in flight at once,\n * preserving input order in the result. On the first `fn` rejection no NEW\n * items are picked up; already-in-flight calls are awaited, then the first\n * error is rethrown. `limit` is clamped to ≥ 1.\n *\n * Used where a burst of provisioning (e.g. forking N child boxes) must respect\n * the loop's concurrency bound instead of firing all N at once.\n */\nexport async function mapWithConcurrency<T, R>(\n  items: readonly T[],\n  limit: number,\n  fn: (item: T, index: number) => Promise<R>,\n): Promise<R[]> {\n  const bound = Math.max(1, Math.floor(limit))\n  const results = new Array<R>(items.length)\n  let next = 0\n  let failed = false\n  const worker = async (): Promise<void> => {\n    while (!failed) {\n      const i = next\n      next += 1\n      if (i >= items.length) return\n      try {\n        results[i] = await fn(items[i] as T, i)\n      } catch (err) {\n        failed = true\n        throw err\n      }\n    }\n  }\n  const workerCount = Math.min(bound, items.length)\n  await Promise.all(Array.from({ length: workerCount }, () => worker()))\n  return results\n}\n"],"mappings":";;;;;;AAgBA,eAAsB,cAAc,KAAoD;CACtF,IAAI,CAAC,OAAO,OAAQ,IAA6B,WAAW,YAAY,OAAO;CAC/E,IAAI;EACF,MAAM,IAAI,OAAO;EACjB,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAgB,aAAa,MAAM,GAAW;CAC5C,OAAO,KAAK,OAAO,CAAC,CACjB,SAAS,EAAE,CAAC,CACZ,MAAM,GAAG,IAAI,GAAG;AACrB;;AAGA,SAAgB,aAAqB;CACnC,OAAO,OAAO,WAAW;AAC3B;;AAGA,SAAgB,aAAoB;CAClC,MAAM,sBAAM,IAAI,MAAM,SAAS;CAC/B,IAAI,OAAO;CACX,OAAO;AACT;;AAGA,SAAgB,aAAoB;CAClC,MAAM,WAAW;AACnB;;AAGA,SAAgB,eAAe,QAAuC;CACpE,IAAI,QAAQ,SAAS,MAAM,WAAW;AACxC;;AAGA,SAAgB,aAAa,KAAuB;CAClD,OAAO,eAAe,SAAS,IAAI,SAAS;AAC9C;;;;;;AAOA,SAAgB,MAAM,IAAY,QAAqC;CACrE,OAAO,IAAI,SAAS,YAAY;EAC9B,IAAI,QAAQ,SAAS;GACnB,QAAQ;GACR;EACF;EACA,IAAI;EACJ,MAAM,QAAQ,iBAAiB;GAC7B,IAAI,WAAW,QAAQ,OAAO,oBAAoB,SAAS,OAAO;GAClE,QAAQ;EACV,GAAG,EAAE;EACL,IAAI,QAAQ;GACV,gBAAgB;IACd,aAAa,KAAK;IAClB,QAAQ;GACV;GACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EAC1D;CACF,CAAC;AACH;;;;;AAMA,SAAgB,YAAe,SAAqB,IAAoC;CACtF,OAAO,IAAI,SAAwB,YAAY;EAC7C,MAAM,QAAQ,iBAAiB,QAAQ,KAAA,CAAS,GAAG,EAAE;EACrD,QAAQ,MACL,UAAU;GACT,aAAa,KAAK;GAClB,QAAQ,KAAK;EACf,SACM;GACJ,aAAa,KAAK;GAClB,QAAQ,KAAA,CAAS;EACnB,CACF;CACF,CAAC;AACH;;;;;;AAcA,SAAgB,cAAc,OAAgB,OAAyB,CAAC,GAAW;CACjF,IAAI;CACJ,IAAI;EACF,IAAI,OAAO,UAAU,UACnB,IAAI;OAGJ,KADa,KAAK,SAAS,KAAK,UAAU,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,KAAK,MACpE,OAAO,KAAK;CAE5B,QAAQ;EACN,IAAI,OAAO,KAAK;CAClB;CACA,IAAI,KAAK,QAAQ,KAAA,KAAa,EAAE,SAAS,KAAK,KAAK,OAAO,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,EAAE;CAClF,OAAO;AACT;;AAGA,SAAgB,iBAAiC;CAC/C,OAAO;EAAE,OAAO;EAAG,QAAQ;CAAE;AAC/B;;AAGA,SAAgB,gBAAgB,OAAuC;CACrE,MAAM,wBACJ,MAAM,wBAAwB,SAAU,MAAM,QAAQ,KAAK,CAAC,4BAA4B,KAAK;CAC/F,OAAO;EACL,OAAO,MAAM;EACb,QAAQ,MAAM;EACd,GAAI,MAAM,gBAAgB,QAAQ,EAAE,aAAa,MAAe,IAAI,CAAC;EACrE,GAAI,MAAM,eAAe,KAAA,IAAY,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;EACzE,GAAI,MAAM,cAAc,KAAA,IAAY,EAAE,WAAW,MAAM,UAAU,IAAI,CAAC;EACtE,GAAI,MAAM,eAAe,KAAA,IAAY,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;EACzE,GAAI,wBAAwB,EAAE,qBAAqB,MAAe,IAAI,CAAC;CACzE;AACF;;AAGA,SAAgB,0BAA0B,OAAgC;CACxE,IAAI,MAAM,wBAAwB,OAAO,OAAO;CAChD,OAAO,4BAA4B,KAAK;AAC1C;AAEA,SAAS,4BAA4B,OAAgC;CACnE,IAAI,MAAM,UAAU,GAAG,OAAO;CAC9B,IACE,MAAM,eAAe,KAAA,KACrB,MAAM,cAAc,KAAA,KACpB,MAAM,eAAe,KAAA,GAErB,OAAO;CAET,OAAO,MAAM,aAAa,MAAM,YAAY,MAAM,eAAe,MAAM;AACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,cAAc,OAA+B;CAC3D,OAAO,MAAM,QAAQ,kBAAkB,KAAK,IAAI,MAAM;AACxD;;AAGA,SAAS,kBAAkB,OAA+B;CACxD,MAAM,EAAE,cAAc;CACtB,IAAI,cAAc,KAAA,GAAW,OAAO;CACpC,OAAO,gBAAgB,OAAO,SAAS,IAAI,MAAM,QAAQ,IAAI;AAC/D;AAEA,SAAS,gBAAgB,OAAgC,WAA2B;CAClF,QAAQ,MAAM,cAAc,KAAK,aAAa,MAAM,cAAc;AACpE;;;;;;;;;;AAWA,SAAgB,cAAc,KAAqB,OAAsC;CACvF,IAAI,SAAS,MAAM,SAAS;CAC5B,IAAI,UAAU,MAAM,UAAU;CAC9B,IAAI,MAAM,gBAAgB,OAAO,IAAI,cAAc;CAEnD,MAAM,QAAQ,MAAM,SAAS;CAC7B,MAAM,OAAO,gBAAgB,OAAO,MAAM,aAAa,CAAC,KAAK;CAC7D,IAAI,MAAM;EACR,IAAI,MAAM,eAAe,KAAA,GAAW,IAAI,cAAc,IAAI,cAAc,KAAK,MAAM;EACnF,IAAI,MAAM,cAAc,KAAA,GAAW,IAAI,aAAa,IAAI,aAAa,KAAK,MAAM;EAChF,IAAI,MAAM,eAAe,KAAA,GAAW,IAAI,cAAc,IAAI,cAAc,KAAK,MAAM;CACrF;CAEA,MAAM,aACJ,QACA,MAAM,eAAe,KAAA,KACrB,MAAM,cAAc,KAAA,KACpB,MAAM,eAAe,KAAA,KACrB,MAAM,aAAa,MAAM,YAAY,MAAM,eAAe;CAI5D,IAAI,MAAM,wBAAwB,SAAU,QAAQ,KAAK,CAAC,YACxD,IAAI,sBAAsB;AAE9B;;;;;;;;;;AAWA,eAAsB,mBACpB,OACA,OACA,IACc;CACd,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,KAAK,CAAC;CAC3C,MAAM,UAAU,IAAI,MAAS,MAAM,MAAM;CACzC,IAAI,OAAO;CACX,IAAI,SAAS;CACb,MAAM,SAAS,YAA2B;EACxC,OAAO,CAAC,QAAQ;GACd,MAAM,IAAI;GACV,QAAQ;GACR,IAAI,KAAK,MAAM,QAAQ;GACvB,IAAI;IACF,QAAQ,KAAK,MAAM,GAAG,MAAM,IAAS,CAAC;GACxC,SAAS,KAAK;IACZ,SAAS;IACT,MAAM;GACR;EACF;CACF;CACA,MAAM,cAAc,KAAK,IAAI,OAAO,MAAM,MAAM;CAChD,MAAM,QAAQ,IAAI,MAAM,KAAK,EAAE,QAAQ,YAAY,SAAS,OAAO,CAAC,CAAC;CACrE,OAAO;AACT"}