@coreplane/switchboard 0.0.0 → 1.18.1

package/dist/assets/src/core/trace/attrs.ts

@@ -0,0 +1,203 @@
+/** Span attributes: one flat key union with a value domain per key, and the
+ *  keys each span name may carry (docs/reference/specs/tracing.md). Literal unions,
+ *  numbers and booleans only; the string-valued keys (`host`, `route`,
+ *  `command`, `agent`, `model`) come from closed tables at the emitter — a
+ *  model is the parsed `<provider>/<model>` ref the registry resolved, never
+ *  the typed directive — and are validated as sanitized identifiers here.
+ *  `traceId` and free text are not attrs — an error's message has its own
+ *  field. */
+
+export type Backend = "local" | "resident" | "sandbox" | "e2b";
+export type Channel = "slack" | "http" | "mcp" | "cli";
+
+/** Every attribute key any span may carry, with its value domain. */
+export interface AttrDomain {
+  // request
+  channel: Channel;
+  status: "completed" | "failed" | "refused" | "stopped";
+  queuedBeforeMs: number;
+  queuedBehindMs: number;
+  runId: string;
+  // slack.receive
+  caughtUp: boolean;
+  files: number;
+  dedupe: "fresh" | "duplicate";
+  // dispatch.* / run.* / post.*
+  outcome: string;
+  count: number;
+  backend: Backend;
+  // run.command
+  command: string;
+  // model.turn
+  /** The `<provider>/<model>` that took the turn — a ship run's children answer
+   *  on different models, and the run page badges the switch per step. */
+  model: string;
+  stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "other";
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  ttftMs: number;
+  thinkingMs: number;
+  textMs: number;
+  blocks: number;
+  finale: boolean;
+  // model.block.<kind>
+  index: number;
+  // tool.*
+  callId: string;
+  ok: boolean;
+  exitCode: number;
+  infra: boolean;
+  execMs: number;
+  serverMs: number;
+  attempts: number;
+  timeoutMs: number;
+  budget: "full" | "clipped";
+  token: "fresh" | "expiring" | "expired";
+  // exec.*
+  tokenExpiresInMin: number;
+  attempt: number;
+  delayMs: number;
+  // github.*, http.client, <worker>.fetch
+  scope: "read" | "write";
+  cached: boolean;
+  expiresInMs: number;
+  method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  route: string;
+  host: string;
+  httpStatus: number;
+  // mcp.*
+  bytes: number;
+  // ship.round
+  agent: string;
+  // resident grafts
+  waitedMs: number;
+  clockSkewMs: number;
+  timedOut: boolean;
+  abandoned: boolean;
+  // the bot's own roots (item 20): slack.catch_up, drain, deploy.step.<worker>
+  signal: "SIGTERM" | "SIGINT" | "other";
+  channels: number;
+  missed: number;
+  orphans: number;
+  skipped: number;
+  runs: number;
+  handed: number;
+  sealed: number;
+  abandonedRuns: number;
+  // the Workers' own roots (item 25): resident.watchdog, state.alarm
+  residents: number;
+  swept: number;
+}
+
+export type SpanAttrKey = keyof AttrDomain;
+
+export type SpanAttrs = { readonly [K in SpanAttrKey]?: AttrDomain[K] };
+
+/** The string-valued keys, and the shape their values must have: an identifier
+ *  from a closed table, never free text (no whitespace, no `?`/`&`, at most 64
+ *  chars). */
+const IDENTIFIER_KEYS: ReadonlySet<SpanAttrKey> = new Set<SpanAttrKey>([
+  "runId",
+  "outcome",
+  "command",
+  "route",
+  "host",
+  "callId",
+  "agent",
+  "model",
+]);
+const IDENTIFIER_RE = /^[A-Za-z0-9_./:@+-]{1,64}$/;
+
+/** Validate one attrs bag: known keys, value in domain, identifiers sanitized.
+ *  Returns the offending keys (empty when valid); emitters and tests use it,
+ *  the tracer itself never throws over an attr. */
+export function invalidAttrKeys(attrs: SpanAttrs): string[] {
+  const bad: string[] = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value === undefined) continue;
+    if (!(key in ATTR_TYPE)) {
+      bad.push(key);
+      continue;
+    }
+    const expected = ATTR_TYPE[key as SpanAttrKey];
+    if (expected === "string") {
+      if (typeof value !== "string") bad.push(key);
+      else if (IDENTIFIER_KEYS.has(key as SpanAttrKey) && !IDENTIFIER_RE.test(value)) bad.push(key);
+    } else if (typeof value !== expected) {
+      bad.push(key);
+    } else if (typeof value === "number" && !Number.isFinite(value)) {
+      bad.push(key);
+    }
+  }
+  return bad;
+}
+
+/** The runtime type of each key — the one place the domain is spelled twice
+ *  (type and value), kept adjacent so they cannot drift. */
+const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
+  channel: "string",
+  status: "string",
+  queuedBeforeMs: "number",
+  queuedBehindMs: "number",
+  runId: "string",
+  caughtUp: "boolean",
+  files: "number",
+  dedupe: "string",
+  outcome: "string",
+  count: "number",
+  backend: "string",
+  command: "string",
+  model: "string",
+  stopReason: "string",
+  inputTokens: "number",
+  outputTokens: "number",
+  cacheReadTokens: "number",
+  cacheWriteTokens: "number",
+  ttftMs: "number",
+  thinkingMs: "number",
+  textMs: "number",
+  blocks: "number",
+  finale: "boolean",
+  index: "number",
+  callId: "string",
+  ok: "boolean",
+  exitCode: "number",
+  infra: "boolean",
+  execMs: "number",
+  serverMs: "number",
+  attempts: "number",
+  timeoutMs: "number",
+  budget: "string",
+  token: "string",
+  tokenExpiresInMin: "number",
+  attempt: "number",
+  delayMs: "number",
+  scope: "string",
+  cached: "boolean",
+  expiresInMs: "number",
+  method: "string",
+  route: "string",
+  host: "string",
+  httpStatus: "number",
+  bytes: "number",
+  agent: "string",
+  waitedMs: "number",
+  clockSkewMs: "number",
+  timedOut: "boolean",
+  abandoned: "boolean",
+  signal: "string",
+  channels: "number",
+  missed: "number",
+  orphans: "number",
+  skipped: "number",
+  runs: "number",
+  handed: "number",
+  sealed: "number",
+  abandonedRuns: "number",
+  residents: "number",
+  swept: "number",
+};
+
+export const ATTR_KEYS: readonly SpanAttrKey[] = Object.keys(ATTR_TYPE) as SpanAttrKey[];

package/dist/assets/src/core/trace/classify.ts

@@ -0,0 +1,49 @@
+/** Error classification: mark a thrown error with our kind and the peer's own
+ *  discriminator at the point that knows them (an HTTP status, the resident's
+ *  `needs`, the leading token of a resident reason), and read the mark back at
+ *  any depth. A span that fails with a classified error records `errorKind` and
+ *  `errorCode` and no message at all — free text from a remote body never
+ *  reaches a span, a log line or the wire (docs/reference/specs/tracing.md). */
+import type { ErrorKind } from "./types.js";
+
+export interface ErrorClassification {
+  kind: ErrorKind;
+  code?: string;
+}
+
+const MARKS = new WeakMap<object, ErrorClassification>();
+
+/** How far `classificationOf` follows `cause` links. */
+export const CAUSE_DEPTH = 5;
+
+const CODE_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+/** Mark `err` (any object; a non-object is returned unmarked) and return it, so
+ *  `throw classifyError(new Error(...), { kind: "http", code: "503" })` reads
+ *  naturally. A `code` that is not a short identifier is dropped: a code is the
+ *  peer's discriminator, never its prose. */
+export function classifyError<E>(err: E, c: ErrorClassification): E {
+  if (err !== null && typeof err === "object") {
+    MARKS.set(err, c.code !== undefined && CODE_RE.test(c.code) ? { kind: c.kind, code: c.code } : { kind: c.kind });
+  }
+  return err;
+}
+
+/** The classification on `err` or on any `cause` beneath it, to `CAUSE_DEPTH`. */
+export function classificationOf(err: unknown): ErrorClassification | undefined {
+  let cur: unknown = err;
+  for (let depth = 0; depth <= CAUSE_DEPTH && cur !== null && typeof cur === "object"; depth++) {
+    const mark = MARKS.get(cur);
+    if (mark) return mark;
+    cur = (cur as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
+/** An HTTP status as an `errorCode`: an integer in 100..599, stringified;
+ *  anything else is no code. */
+export function httpStatusCode(status: unknown): string | undefined {
+  return typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599
+    ? String(status)
+    : undefined;
+}

package/dist/assets/src/core/trace/clock.ts

@@ -0,0 +1,6 @@
+import type { Clock } from "./types.js";
+
+/** The ONLY production file that reads the wall clock. Everything else takes a
+ *  `Clock` (docs/reference/specs/tracing.md: the clock ratchet forces the allowlist of
+ *  direct reads to zero). */
+export const systemClock: Clock = () => Date.now();

package/dist/assets/src/core/trace/context.ts

@@ -0,0 +1,9 @@
+import type { SpanContext } from "./types.js";
+
+/** Production `SpanContext`: the identity (Null Object). `span(fn)` enters it
+ *  around `fn`, and it does nothing, so the primitive carries no async-context
+ *  machinery and no Node dependency. The no-gaps test supplies an
+ *  `AsyncLocalStorage`-backed one instead (src/core/testing/alsContext.ts). */
+export const identityContext: SpanContext = {
+  run: (_span, fn) => fn(),
+};

package/dist/assets/src/core/trace/ids.ts

@@ -0,0 +1,23 @@
+/** Trace and span ids in the W3C shape: 16 and 8 random bytes as lowercase hex,
+ *  never all zero. Bare `crypto.getRandomValues` so Node and the Workers share
+ *  one implementation. */
+
+function randomHex(bytes: number): string {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  let out = "";
+  for (const b of buf) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+
+export function newTraceId(): string {
+  let id = randomHex(16);
+  while (/^0+$/.test(id)) id = randomHex(16);
+  return id;
+}
+
+export function newSpanId(): string {
+  let id = randomHex(8);
+  while (/^0+$/.test(id)) id = randomHex(8);
+  return id;
+}

package/dist/assets/src/core/trace/partition.ts

@@ -0,0 +1,235 @@
+/** The partition (docs/reference/specs/tracing.md): every instant of a run's window
+ *  belongs to exactly one of seven terms —
+ *
+ *    window = getting ready + thinking + tools + finishing up
+ *           + Switchboard overhead + not recorded + not loaded
+ *
+ *  Three passes. (1) Claim: every counted span's interval, clipped to the
+ *  window, claims the instants no deeper counted span already claimed (deepest
+ *  wins; ties by earlier start, then id), so concurrent siblings count once and
+ *  a tool inside a turn is tools, not thinking. Background subtrees claim
+ *  nothing; uncounted spans are structure only. An open span (no end) runs to
+ *  the window end on a live window; on a finished window, where nothing can
+ *  still be running so a missing end was lost, a counted open span is cut at the
+ *  first loss interval after its start. (2) Losses: `lost` intervals (seq gaps,
+ *  `spans_dropped` notes) become not recorded and `elided` ones (a live
+ *  replay's budget) not loaded, each minus the instants a counted span claims;
+ *  where the two overlap, lost wins. (3) Overhead is the residual. */
+import type { Bucket, RunOwner } from "./streamSpans.js";
+import { classOf } from "./streamSpans.js";
+import type { SpanRecord } from "./types.js";
+
+export interface Window {
+  start: number;
+  end: number;
+}
+
+export interface LossInterval {
+  from: number;
+  to: number;
+  kind: "lost" | "elided";
+}
+
+export interface PartitionInput {
+  window: Window;
+  owner: RunOwner;
+  /** True for a record and for a live page after the `finished` frame. */
+  finished: boolean;
+  losses: readonly LossInterval[];
+}
+
+export interface Partition {
+  windowMs: number;
+  gettingReadyMs: number;
+  thinkingMs: number;
+  toolsMs: number;
+  finishingUpMs: number;
+  overheadMs: number;
+  notRecordedMs: number;
+  notLoadedMs: number;
+  /** Instants covered only by background spans — part of overhead, reported
+   *  so the no-gaps test can account for them exactly. */
+  backgroundOnlyMs: number;
+}
+
+interface Claim {
+  start: number;
+  end: number;
+  bucket: Bucket;
+  depth: number;
+  startedAt: number;
+  spanId: string;
+}
+
+export function partition(spans: readonly SpanRecord[], input: PartitionInput): Partition {
+  const { window, owner, finished } = input;
+  const windowMs = Math.max(0, window.end - window.start);
+  const byId = new Map(spans.map((s) => [s.spanId, s]));
+
+  // Depth over the input set; an orphan (parent not in the set) is depth 1.
+  const depthMemo = new Map<string, number>();
+  const depthOf = (s: SpanRecord): number => {
+    const memo = depthMemo.get(s.spanId);
+    if (memo !== undefined) return memo;
+    depthMemo.set(s.spanId, 1); // cycle guard
+    const parent = s.parentSpanId ? byId.get(s.parentSpanId) : undefined;
+    const d = parent ? depthOf(parent) + 1 : 1;
+    depthMemo.set(s.spanId, d);
+    return d;
+  };
+  const underBackground = (s: SpanRecord): boolean => {
+    let cur: SpanRecord | undefined = s;
+    const seen = new Set<string>();
+    while (cur && !seen.has(cur.spanId)) {
+      seen.add(cur.spanId);
+      if (classOf(cur.name, owner)?.kind === "background") return true;
+      cur = cur.parentSpanId ? byId.get(cur.parentSpanId) : undefined;
+    }
+    return false;
+  };
+
+  const lossStarts = input.losses.map((l) => Math.max(window.start, l.from)).sort((a, b) => a - b);
+  const clipEnd = (s: SpanRecord): number => {
+    if (s.endedAt !== undefined) return Math.min(window.end, s.endedAt);
+    if (!finished) return window.end;
+    // Finished window: a counted open span's end was lost — cut at the next loss.
+    const next = lossStarts.find((at) => at > s.startedAt);
+    return next === undefined ? window.end : Math.min(window.end, next);
+  };
+
+  const claims: Claim[] = [];
+  const backgroundIntervals: Array<[number, number]> = [];
+  for (const s of spans) {
+    const cls = classOf(s.name, owner);
+    if (!cls) continue;
+    const start = Math.max(window.start, s.startedAt);
+    if (cls.kind === "background") {
+      const end = Math.min(window.end, s.endedAt ?? window.end);
+      if (end > start) backgroundIntervals.push([start, end]);
+      continue;
+    }
+    if (cls.kind !== "counted" || underBackground(s)) continue;
+    const end = clipEnd(s);
+    if (end <= start) continue;
+    claims.push({ start, end, bucket: cls.bucket, depth: depthOf(s), startedAt: s.startedAt, spanId: s.spanId });
+  }
+  claims.sort(
+    (a, b) =>
+      b.depth - a.depth || a.startedAt - b.startedAt || (a.spanId < b.spanId ? -1 : a.spanId > b.spanId ? 1 : 0),
+  );
+
+  // Elementary intervals from every boundary in play.
+  const points = new Set<number>([window.start, window.end]);
+  for (const c of claims) {
+    points.add(c.start);
+    points.add(c.end);
+  }
+  for (const l of input.losses) {
+    points.add(clamp(l.from, window));
+    points.add(clamp(l.to, window));
+  }
+  for (const [a, b] of backgroundIntervals) {
+    points.add(a);
+    points.add(b);
+  }
+  const sorted = [...points].filter((p) => p >= window.start && p <= window.end).sort((a, b) => a - b);
+
+  const buckets: Record<Bucket, number> = { getting_ready: 0, thinking: 0, tools: 0, finishing_up: 0 };
+  let notRecorded = 0;
+  let notLoaded = 0;
+  let backgroundOnly = 0;
+  for (let i = 0; i + 1 < sorted.length; i++) {
+    const a = sorted[i];
+    const b = sorted[i + 1];
+    const len = b - a;
+    if (len <= 0) continue;
+    const claim = claims.find((c) => c.start <= a && c.end >= b);
+    if (claim) {
+      buckets[claim.bucket] += len;
+      continue;
+    }
+    const lost = input.losses.some((l) => l.kind === "lost" && clamp(l.from, window) <= a && clamp(l.to, window) >= b);
+    if (lost) {
+      notRecorded += len;
+      continue;
+    }
+    const elided = input.losses.some(
+      (l) => l.kind === "elided" && clamp(l.from, window) <= a && clamp(l.to, window) >= b,
+    );
+    if (elided) {
+      notLoaded += len;
+      continue;
+    }
+    if (backgroundIntervals.some(([s, e]) => s <= a && e >= b)) backgroundOnly += len;
+  }
+  const counted = buckets.getting_ready + buckets.thinking + buckets.tools + buckets.finishing_up;
+  return {
+    windowMs,
+    gettingReadyMs: buckets.getting_ready,
+    thinkingMs: buckets.thinking,
+    toolsMs: buckets.tools,
+    finishingUpMs: buckets.finishing_up,
+    overheadMs: Math.max(0, windowMs - counted - notRecorded - notLoaded),
+    notRecordedMs: notRecorded,
+    notLoadedMs: notLoaded,
+    backgroundOnlyMs: backgroundOnly,
+  };
+}
+
+function clamp(at: number, w: Window): number {
+  return Math.min(w.end, Math.max(w.start, at));
+}
+
+/** The seven terms as the printed shape: totals and buckets floored to whole
+ *  seconds, the residual absorbing the rounding so the printed items always sum
+ *  to the printed total, and no bucket printing `0s`. */
+export interface PrintedShape {
+  totalS: number;
+  items: Array<{ term: PrintedTerm; s: number }>;
+}
+export type PrintedTerm =
+  "getting ready" | "thinking" | "in tools" | "finishing up" | "Switchboard overhead" | "not recorded" | "not loaded";
+
+export function printedShape(p: Partition): PrintedShape {
+  const totalS = Math.floor(p.windowMs / 1000);
+  const floored: Array<[PrintedTerm, number]> = [
+    ["getting ready", Math.floor(p.gettingReadyMs / 1000)],
+    ["thinking", Math.floor(p.thinkingMs / 1000)],
+    ["in tools", Math.floor(p.toolsMs / 1000)],
+    ["finishing up", Math.floor(p.finishingUpMs / 1000)],
+    ["not recorded", Math.floor(p.notRecordedMs / 1000)],
+    ["not loaded", Math.floor(p.notLoadedMs / 1000)],
+  ];
+  const sum = floored.reduce((a, [, s]) => a + s, 0);
+  const items = floored.filter(([, s]) => s > 0).map(([term, s]) => ({ term, s }));
+  const overhead = totalS - sum;
+  if (overhead > 0) items.push({ term: "Switchboard overhead", s: overhead });
+  // Order: the four counted words, then overhead, then the two loss terms.
+  const order: PrintedTerm[] = [
+    "getting ready",
+    "thinking",
+    "in tools",
+    "finishing up",
+    "Switchboard overhead",
+    "not recorded",
+    "not loaded",
+  ];
+  items.sort((a, b) => order.indexOf(a.term) - order.indexOf(b.term));
+  return { totalS, items };
+}
+
+/** A bucket is informative at 5 % of the window or 2 s; the shape is shown when
+ *  at least two are. */
+export function isInformative(p: Partition): boolean {
+  const terms = [
+    p.gettingReadyMs,
+    p.thinkingMs,
+    p.toolsMs,
+    p.finishingUpMs,
+    p.overheadMs,
+    p.notRecordedMs,
+    p.notLoadedMs,
+  ];
+  const informative = terms.filter((ms) => ms >= 2000 || (p.windowMs > 0 && ms / p.windowMs >= 0.05)).length;
+  return informative >= 2;
+}

package/dist/assets/src/core/trace/sinks.ts

@@ -0,0 +1,68 @@
+/** The process log sink and the Null Object sink (docs/reference/specs/tracing.md).
+ *
+ *  A `LogSink` writes one JSON line per span end:
+ *  `{"span","traceId","spanId","parentSpanId","startedAt","ms","status",
+ *    "errorKind"?,"errorCode"?,"errorMessage"?,"attrs"}` — never text, summary
+ *  or output; attrs are the validated bag the span carried. Verbosity:
+ *  `roots` prints roots only (one or two lines per run), `slow` prints roots
+ *  plus every span of `slowMs` or more. */
+import type { SpanRecord, SpanSink } from "./types.js";
+
+export type TracingLogLevel = "roots" | "slow";
+export const TRACING_LOG_LEVELS: readonly TracingLogLevel[] = ["roots", "slow"];
+export const SLOW_SPAN_MS = 1000;
+
+export interface LogSinkOptions {
+  level: TracingLogLevel;
+  write: (line: string) => void;
+  slowMs?: number;
+}
+
+export interface LogLine {
+  span: string;
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  startedAt: number;
+  ms: number;
+  status: "ok" | "error";
+  errorKind?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  attrs: Record<string, string | number | boolean>;
+}
+
+export function logLineOf(rec: SpanRecord): LogLine {
+  return {
+    span: rec.name,
+    traceId: rec.traceId,
+    spanId: rec.spanId,
+    ...(rec.parentSpanId ? { parentSpanId: rec.parentSpanId } : {}),
+    startedAt: rec.startedAt,
+    ms: rec.durationMs ?? 0,
+    status: rec.status ?? "ok",
+    ...(rec.errorKind ? { errorKind: rec.errorKind } : {}),
+    ...(rec.errorCode ? { errorCode: rec.errorCode } : {}),
+    ...(rec.errorMessage ? { errorMessage: rec.errorMessage } : {}),
+    attrs: Object.fromEntries(Object.entries(rec.attrs).filter(([, v]) => v !== undefined)) as LogLine["attrs"],
+  };
+}
+
+export function createLogSink(opts: LogSinkOptions): SpanSink {
+  const slowMs = opts.slowMs ?? SLOW_SPAN_MS;
+  return {
+    onEnd(rec) {
+      // A root is this process's own: one with no parent, or one that adopted a
+      // remote parent (a Worker continuing the bot's trace). Without the second
+      // clause every sub-second adopted request stayed unlogged at `slow` while
+      // the same request without context printed — the opposite of useful.
+      const isRoot = rec.parentSpanId === undefined || rec.adopted === true;
+      if (!isRoot && (opts.level === "roots" || (rec.durationMs ?? 0) < slowMs)) return;
+      opts.write(JSON.stringify(logLineOf(rec)));
+    },
+  };
+}
+
+/** A sink that observes nothing — what a request's stream and card sinks are
+ *  until they are bound (Null Object). */
+export const NULL_SINK: SpanSink = { onEnd: () => {} };