@lionhummer/constellation 0.6.0 → 0.9.0

package/dist/index.js

@@ -1,21 +1,3 @@
-// ../client-core/src/error-details.ts
-function callerErrorDetails(error) {
-  let cause = error;
-  const seen = new Set;
-  for (let depth = 0;depth < 8 && cause instanceof Error && !seen.has(cause); depth++) {
-    seen.add(cause);
-    if (!(cause.cause instanceof Error))
-      break;
-    cause = cause.cause;
-  }
-  const record = cause && typeof cause === "object" ? cause : {};
-  const name = cause instanceof Error ? cause.name.slice(0, 80) : "CallerError";
-  const code = typeof record.code === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(record.code) ? record.code : undefined;
-  const raw = cause instanceof Error ? cause.message : "Caller handler threw a non-Error value";
-  const message = (/Failed query:|\bparams:/i.test(raw) ? "Caller database operation failed; see caller logs" : raw).replace(/\b(?:Bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(/((?:password|token|secret|api[_-]?key)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]").replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@").slice(0, 512);
-  return { name, message, ...code ? { code } : {} };
-}
-
 // ../client-core/src/index.ts
 class ConstellationError extends Error {
   status;
@@ -27,6 +9,66 @@ class ConstellationError extends Error {
     this.name = "ConstellationError";
   }
 }
+function observationBytes(observations) {
+  const spans = (observations.spans ?? []).map((s) => ({ ...s, stepId: s.stepId ?? null, attemptId: s.attemptId ?? null, parentSpanId: s.parentSpanId ?? null, endedAt: s.endedAt ?? null, attributes: s.attributes ?? null }));
+  const logs = (observations.logs ?? []).map((l) => ({ ...l, stepId: l.stepId ?? null, spanId: l.spanId ?? null, attributes: l.attributes ?? null }));
+  return new TextEncoder().encode(JSON.stringify({ spans, logs })).byteLength;
+}
+var TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})$/i;
+function normalizeTimestamp(value) {
+  const match = TIMESTAMP.exec(value);
+  if (!match)
+    return value;
+  const millis = Date.parse(`${match[1]}.${(match[2] ?? "").padEnd(3, "0").slice(0, 3)}${match[3].toUpperCase()}`);
+  if (!Number.isFinite(millis))
+    return value;
+  const normalized = new Date(millis).toISOString();
+  return /^\d{4}-/.test(normalized) ? normalized : value;
+}
+function normalizeObservations(observations) {
+  return {
+    ...observations,
+    ...observations.spans ? { spans: observations.spans.map((span) => ({
+      ...span,
+      startedAt: normalizeTimestamp(span.startedAt),
+      ...span.endedAt ? { endedAt: normalizeTimestamp(span.endedAt) } : {}
+    })) } : {},
+    ...observations.logs ? { logs: observations.logs.map((log) => ({ ...log, timestamp: normalizeTimestamp(log.timestamp) })) } : {}
+  };
+}
+function validateObservations(observations) {
+  const spans = observations.spans ?? [], logs = observations.logs ?? [];
+  const ids = new Set;
+  const uuid = (id) => !id || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id) && id !== "00000000-0000-0000-0000-000000000000";
+  const attributes = (value) => value == null || typeof value === "object" && !Array.isArray(value);
+  const invalid = () => {
+    throw new ConstellationError(400, "invalid_telemetry", "Telemetry exceeds limits or contains invalid observations");
+  };
+  if (spans.length > 512 || logs.length > 128 || observationBytes(observations) > 1024 * 1024)
+    invalid();
+  for (const span of spans) {
+    const start = Date.parse(span.startedAt), end = span.endedAt ? Date.parse(span.endedAt) : NaN;
+    if (!span.id || !uuid(span.id) || !uuid(span.stepId) || !uuid(span.attemptId) || !uuid(span.parentSpanId) || !attributes(span.attributes) || ids.has(span.id) || !span.name.trim() || new TextEncoder().encode(span.name).byteLength > 256 || !Number.isFinite(start) || !Number.isFinite(end) || end < start || !["ok", "error", "cancelled"].includes(span.status) || span.parentSpanId === span.id)
+      invalid();
+    ids.add(span.id);
+  }
+  const parents = new Map(spans.map((span) => [span.id, span.parentSpanId]));
+  for (const span of spans) {
+    const seen = new Set;
+    let id = span.id;
+    while (id) {
+      if (seen.has(id))
+        invalid();
+      seen.add(id);
+      id = parents.get(id) ?? undefined;
+    }
+  }
+  for (const log of logs) {
+    if (!log.id || !uuid(log.id) || !uuid(log.stepId) || !uuid(log.spanId) || !attributes(log.attributes) || ids.has(log.id) || !log.message || new TextEncoder().encode(log.message).byteLength > 8192 || !["debug", "info", "warn", "error"].includes(log.level) || !Number.isFinite(Date.parse(log.timestamp)))
+      invalid();
+    ids.add(log.id);
+  }
+}
 function uuid7() {
   const bytes = crypto.getRandomValues(new Uint8Array(16));
   let ms = Date.now();
@@ -39,7 +81,6 @@ function uuid7() {
   const h = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
   return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
 }
-var terminal = (s) => ["completed", "failed", "cancelled"].includes(s);
 function queryString(values) {
   const params = new URLSearchParams;
   for (const [key, value] of Object.entries(values))
@@ -61,14 +102,6 @@ async function pause(ms, signal) {
     signal?.addEventListener("abort", abort, { once: true });
   });
 }
-async function bounded(promise, signal) {
-  signal.throwIfAborted();
-  return new Promise((resolve, reject) => {
-    const abort = () => reject(signal.reason);
-    signal.addEventListener("abort", abort, { once: true });
-    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
-  });
-}
 
 class RequestClient {
   #fetcher;
@@ -99,8 +132,22 @@ class RequestClient {
     }
     return response.status === 204 ? undefined : response.json();
   }
-  #submit(input, signal) {
-    return this.#call("/v1/requests", "POST", input, signal);
+  async#submit(input, signal) {
+    const prepared = JSON.parse(JSON.stringify(input));
+    if (prepared.telemetry) {
+      prepared.telemetry = normalizeObservations(prepared.telemetry);
+      validateObservations(prepared.telemetry);
+    }
+    for (let attempt = 0;; attempt++) {
+      try {
+        return await this.#call("/v1/requests", "POST", prepared, signal);
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (attempt >= 2 || error instanceof ConstellationError && error.status !== 429 && error.status < 500)
+          throw error;
+        await pause(100 * 2 ** attempt, signal);
+      }
+    }
   }
   #inspect(id, signal) {
     return this.#call(`/v1/requests/${encodeURIComponent(id)}`, "GET", undefined, signal);
@@ -132,80 +179,18 @@ class RequestClient {
         params.set(k, String(v));
     return this.#call(`/v1/requests?${params}`, "GET", undefined, signal);
   }
-  #cancel(id, signal) {
-    return this.#call(`/v1/requests/${encodeURIComponent(id)}/cancel`, "POST", {}, signal);
-  }
-  #claim(id, inputId, claimId, signal) {
-    return this.#call(`/v1/requests/${encodeURIComponent(id)}/inputs/${encodeURIComponent(inputId)}/claim`, "POST", { claimId }, signal);
-  }
-  maintainClaim(id, inputId, claimId, externalSignal) {
-    const controller = new AbortController;
-    const signal = externalSignal ? AbortSignal.any([externalSignal, controller.signal]) : controller.signal;
-    const renewal = (async () => {
-      while (!signal.aborted) {
-        try {
-          await pause(15000, signal);
-        } catch {
-          return;
-        }
-        if (signal.aborted)
-          return;
-        try {
-          await this.#claim(id, inputId, claimId, signal);
-        } catch (error) {
-          controller.abort(error);
-          return;
-        }
-      }
-    })();
-    return {
-      signal,
-      stop: async () => {
-        controller.abort();
-        await renewal;
+  async#cancel(id, signal) {
+    for (let attempt = 0;; attempt++) {
+      try {
+        return await this.#call(`/v1/requests/${encodeURIComponent(id)}/cancel`, "POST", {}, signal);
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (attempt >= 7 || !(error instanceof ConstellationError) || error.status !== 409 || error.code !== "conflict")
+          throw error;
+        await pause(Math.min(25 * 2 ** attempt, 200), signal);
       }
-    };
-  }
-  async#whileClaimed(id, inputId, claimId, leased, operation, signal) {
-    const lease = leased ? this.maintainClaim(id, inputId, claimId, signal) : null;
-    try {
-      return await operation(lease?.signal ?? signal);
-    } finally {
-      await lease?.stop();
     }
   }
-  #respond(id, inputId, response, signal) {
-    return this.#call(`/v1/requests/${encodeURIComponent(id)}/inputs/${encodeURIComponent(inputId)}`, "POST", response, signal);
-  }
-  #addSpans(id, spans, signal) {
-    return this.#call(`/v1/requests/${encodeURIComponent(id)}/spans`, "POST", spans, signal);
-  }
-  #addLogs(id, logs, signal) {
-    return this.#call(`/v1/requests/${encodeURIComponent(id)}/logs`, "POST", logs, signal);
-  }
-  async#startSpan(id, name, options = {}, signal) {
-    const span = {
-      id: uuid7(),
-      name,
-      startedAt: options.startedAt ?? new Date().toISOString(),
-      status: "running",
-      ...options
-    };
-    await this.#addSpans(id, [span], signal);
-    let closed;
-    return {
-      id: span.id,
-      end: (options2 = {}, signal2) => {
-        closed = {
-          ...span,
-          endedAt: options2.endedAt ?? closed?.endedAt ?? new Date().toISOString(),
-          status: options2.status ?? closed?.status ?? "ok",
-          attributes: options2.attributes ?? closed?.attributes ?? span.attributes
-        };
-        return this.#addSpans(id, [closed, ...options2.spans ?? []], signal2);
-      }
-    };
-  }
   async* #events(id, options = {}) {
     let after = options.after ?? 0;
     while (true) {
@@ -227,6 +212,11 @@ class RequestClient {
       if (!response)
         continue;
       if (!response.ok || !response.body) {
+        if (response.status === 429 || response.status >= 500) {
+          await response.body?.cancel();
+          await pause(500, options.signal);
+          continue;
+        }
         throw new ConstellationError(response.status, "stream_error", `Event stream returned ${response.status}`);
       }
       const reader = response.body.pipeThrough(new TextDecoderStream).getReader();
@@ -250,12 +240,10 @@ class RequestClient {
             if (!data)
               continue;
             const event = JSON.parse(data);
-            if (event.seq <= after)
+            if (event.sequence <= after)
               continue;
-            after = event.seq;
+            after = event.sequence;
             yield event;
-            if (["request.completed", "request.failed", "request.cancelled"].includes(event.type))
-              return;
           }
         }
       } catch {
@@ -263,166 +251,39 @@ class RequestClient {
       } finally {
         await reader.cancel().catch(() => {});
       }
-      const inspection = await this.#inspect(id, options.signal);
-      if (terminal(inspection.request.status)) {
-        const tail = await this.#call(`/v1/requests/${encodeURIComponent(id)}/events?after=${after}`, "GET", undefined, options.signal);
-        for (const event of tail.items) {
-          if (event.seq <= after)
-            continue;
-          after = event.seq;
-          yield event;
+      const inspection = await this.#replayRead(`/v1/requests/${encodeURIComponent(id)}/state`, options.signal);
+      if (["completed", "failed", "cancelled"].includes(inspection.request.status)) {
+        while (true) {
+          const before = after;
+          const tail = await this.#replayRead(`/v1/requests/${encodeURIComponent(id)}/events?after=${after}`, options.signal);
+          for (const event of tail.items) {
+            if (event.sequence <= after)
+              continue;
+            after = event.sequence;
+            yield event;
+          }
+          if (tail.items.length === 0)
+            return;
+          if (after === before)
+            throw new Error("Replay page did not advance the event cursor");
         }
-        if (tail.items.length < 500)
-          return;
-        continue;
       }
       await pause(500, options.signal);
     }
   }
-  async#handleInput(id, inputId, options = {}) {
-    return this.#processInputs(id, { ...options, targetInputId: inputId });
-  }
-  async#processInputs(id, options = {}) {
-    const consumerId = options.consumerId ?? uuid7();
-    while (true) {
-      const inspectStarted = new Date().toISOString();
-      const inspectClock = performance.now();
-      const state = await this.#inspect(id, options.signal);
-      const inspectEnded = new Date().toISOString();
-      const inspectMs = performance.now() - inspectClock;
-      options.onUpdate?.(state);
-      if (terminal(state.request.status))
-        return state;
-      if (options.targetInputId) {
-        const target = state.inputs.find((input) => input.id === options.targetInputId);
-        if (!target)
-          throw new Error(`Input ${options.targetInputId} is not in request ${id}`);
-        if (target.resolvedAt)
-          return state;
-      }
-      let handled = false;
-      for (const pending of state.inputs.filter((i) => !i.resolvedAt && (!options.targetInputId || i.id === options.targetInputId))) {
-        if (pending.claimId && pending.claimId !== consumerId && !(pending.claimUntil && Date.parse(pending.claimUntil) <= Date.now()))
-          continue;
-        if (pending.kind === "before_model" || pending.kind === "after_model" || pending.kind === "after_step") {
-          const name = pending.kind === "before_model" ? "beforeModel" : pending.kind === "after_model" ? "afterModel" : "afterStep";
-          const handler = options.checkpoints?.[name];
-          if (!handler)
-            continue;
-          try {
-            await this.#claim(id, pending.id, consumerId, options.signal);
-          } catch (error) {
-            if (error instanceof ConstellationError && error.status === 409)
-              continue;
-            throw error;
-          }
-          await this.#whileClaimed(id, pending.id, consumerId, true, async (activeSignal) => {
-            const span = await this.#startSpan(id, `caller.${name}`, { stepId: pending.stepId ?? undefined, inputId: pending.id }, activeSignal);
-            let closed = false;
-            try {
-              const signal = activeSignal ? AbortSignal.any([activeSignal, AbortSignal.timeout(options.toolTimeoutMs ?? 30000)]) : AbortSignal.timeout(options.toolTimeoutMs ?? 30000);
-              const response = await bounded(handler(pending.payload, state, { inputId: pending.id, parentSpanId: span.id, signal }), signal);
-              await span.end({}, activeSignal);
-              closed = true;
-              await this.#claim(id, pending.id, consumerId, activeSignal);
-              await this.#respond(id, pending.id, { ...response, claimId: consumerId }, activeSignal);
-            } catch (error) {
-              if (!activeSignal?.aborted && !closed)
-                await span.end({ status: "error", attributes: { error: callerErrorDetails(error) } }, activeSignal).catch(() => {});
-              throw error;
-            }
-          }, options.signal);
-          handled = true;
-          continue;
-        }
-        const userInput = options.userInput;
-        if (pending.kind === "user_input" && userInput) {
-          try {
-            await this.#claim(id, pending.id, consumerId, options.signal);
-          } catch (error) {
-            if (error instanceof ConstellationError && error.status === 409)
-              continue;
-            throw error;
-          }
-          await this.#whileClaimed(id, pending.id, consumerId, true, async (activeSignal) => {
-            const signal = activeSignal ? AbortSignal.any([activeSignal, AbortSignal.timeout(options.toolTimeoutMs ?? 30000)]) : AbortSignal.timeout(options.toolTimeoutMs ?? 30000);
-            const result = await bounded(userInput(state, { inputId: pending.id, signal }), signal);
-            await this.#claim(id, pending.id, consumerId, activeSignal);
-            await this.#respond(id, pending.id, { result, claimId: consumerId }, activeSignal);
-          }, options.signal);
-          handled = true;
-          continue;
-        }
-        if (pending.kind !== "tool")
-          continue;
-        const claimStarted = new Date().toISOString();
-        const claimClock = performance.now();
-        const tool = options.tools?.[pending.payload.name ?? ""];
-        if (!tool && !pending.payload.validationError)
-          continue;
-        try {
-          await this.#claim(id, pending.id, consumerId, options.signal);
-        } catch (error) {
-          if (error instanceof ConstellationError && error.status === 409)
-            continue;
+  async#replayRead(path, signal) {
+    for (;; ) {
+      signal?.throwIfAborted();
+      try {
+        return await this.#call(path, "GET", undefined, signal);
+      } catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof ConstellationError && error.status !== 429 && error.status < 500)
           throw error;
-        }
-        const claimEnded = new Date().toISOString();
-        const claimMs = performance.now() - claimClock;
-        await this.#whileClaimed(id, pending.id, consumerId, true, async (activeSignal) => {
-          const span = await this.#startSpan(id, `tool.${pending.payload.name}`, { stepId: pending.stepId ?? undefined, inputId: pending.id }, activeSignal);
-          const phases = [
-            { id: uuid7(), inputId: pending.id, name: "caller.input.inspect", startedAt: inspectStarted, endedAt: inspectEnded, status: "ok", attributes: { elapsedMs: inspectMs } },
-            { id: uuid7(), inputId: pending.id, name: "caller.input.claim", startedAt: claimStarted, endedAt: claimEnded, status: "ok", attributes: { elapsedMs: claimMs } }
-          ];
-          let result;
-          let isError = false;
-          let errorDetails;
-          try {
-            if (pending.payload.validationError)
-              throw new Error(pending.payload.validationError);
-            if (!tool)
-              throw new Error("Tool unavailable");
-            const toolSignal = activeSignal ? AbortSignal.any([activeSignal, AbortSignal.timeout(options.toolTimeoutMs ?? 30000)]) : AbortSignal.timeout(options.toolTimeoutMs ?? 30000);
-            result = await bounded(tool(pending.payload.arguments ?? {}, {
-              inputId: pending.id,
-              requestId: id,
-              parentSpanId: span.id,
-              recordSpan: (phase) => phases.push({ ...phase, inputId: pending.id, parentSpanId: span.id }),
-              signal: toolSignal
-            }), toolSignal);
-          } catch (error) {
-            activeSignal?.throwIfAborted();
-            isError = true;
-            errorDetails = callerErrorDetails(error);
-            result = { error: error instanceof Error ? error.message : "Tool failed" };
-          }
-          await span.end({ status: isError ? "error" : "ok", spans: phases, ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
-          await this.#claim(id, pending.id, consumerId, activeSignal);
-          const responseStarted = new Date().toISOString();
-          const responseClock = performance.now();
-          let responseStatus = "ok";
-          try {
-            await this.#respond(id, pending.id, { result, isError, claimId: consumerId }, activeSignal);
-          } catch (error) {
-            responseStatus = "error";
-            throw error;
-          } finally {
-            const responseSpan = { id: uuid7(), inputId: pending.id, name: "caller.input.respond", startedAt: responseStarted, endedAt: new Date().toISOString(), status: responseStatus, attributes: { elapsedMs: performance.now() - responseClock } };
-            await this.#addSpans(id, [responseSpan], activeSignal ? AbortSignal.any([activeSignal, AbortSignal.timeout(2000)]) : AbortSignal.timeout(2000)).catch((error) => {
-              if (!(error instanceof ConstellationError && (error.status === 409 || error.status === 404)))
-                console.warn("Constellation input-response timing could not be recorded");
-            });
-          }
-        }, options.signal);
-        handled = true;
-      }
-      if (options.targetInputId) {
-        if (!handled)
-          throw new Error(`Input ${options.targetInputId} could not be handled`);
-        return this.#inspect(id, options.signal);
+        if (error instanceof SyntaxError)
+          throw error;
+        await pause(500, signal);
       }
-      await pause(500, options.signal);
     }
   }
   get models() {
@@ -433,9 +294,10 @@ class RequestClient {
   }
   get requests() {
     return {
-      create: (input, signal) => this.#submit(input, signal),
+      submit: (input, signal) => this.#submit(input, signal),
       preview: (input, signal) => this.#resolve(input, signal),
       get: (id, signal) => this.#inspect(id, signal),
+      getState: (id, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/state`, "GET", undefined, signal),
       getSummary: (id, signal) => this.#inspectSummary(id, signal),
       getTimings: (id, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/timings`, "GET", undefined, signal),
       list: (query = {}, signal) => this.#list(query, signal),
@@ -450,22 +312,306 @@ class RequestClient {
       getHttpBody: (id, attemptId, query, signal) => this.#call(`/v1/requests/${encodeURIComponent(id)}/http/${encodeURIComponent(attemptId)}/body${queryString(query)}`, "GET", undefined, signal)
     };
   }
-  get inputs() {
-    return {
-      handle: (requestId, inputId, handlers) => this.#handleInput(requestId, inputId, handlers),
-      poll: (requestId, handlers) => this.#processInputs(requestId, handlers),
-      claim: (requestId, inputId, claimId, signal) => this.#claim(requestId, inputId, claimId, signal),
-      respond: (requestId, inputId, response, signal) => this.#respond(requestId, inputId, response, signal)
-    };
+}
+// ../client-core/src/error-details.ts
+function callerErrorDetails(error) {
+  let cause = error;
+  const seen = new Set;
+  for (let depth = 0;depth < 8 && cause instanceof Error && !seen.has(cause); depth++) {
+    seen.add(cause);
+    if (!(cause.cause instanceof Error))
+      break;
+    cause = cause.cause;
   }
-  get spans() {
+  const record = cause && typeof cause === "object" ? cause : {};
+  const name = cause instanceof Error ? cause.name.slice(0, 80) : "CallerError";
+  const code = typeof record.code === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(record.code) ? record.code : undefined;
+  const raw = cause instanceof Error ? cause.message : "Caller handler threw a non-Error value";
+  const message = (/Failed query:|\bparams:/i.test(raw) ? "Caller database operation failed; see caller logs" : raw).replace(/\b(?:Bearer\s+)[^\s,;]+/gi, "Bearer [redacted]").replace(/((?:password|token|secret|api[_-]?key)\s*[=:]\s*)[^\s,;]+/gi, "$1[redacted]").replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, "$1[redacted]@").slice(0, 512);
+  return { name, message, ...code ? { code } : {} };
+}
+
+// ../client-core/src/permanent-codes.json
+var permanent_codes_default = [
+  "bad_request",
+  "observations_expired",
+  "response_conflict"
+];
+
+// ../client-core/src/agent.ts
+var PERMANENT_RESPONSE_CODES = new Set(permanent_codes_default);
+function truncateUtf8(value, limit) {
+  let result = "", bytes = 0;
+  for (const raw of value) {
+    const point = raw.codePointAt(0);
+    const char = point >= 55296 && point <= 57343 ? "�" : raw;
+    const width = new TextEncoder().encode(char).byteLength;
+    if (bytes + width > limit)
+      break;
+    result += char;
+    bytes += width;
+  }
+  return result;
+}
+function cleanJson(value) {
+  if (typeof value === "string")
+    return truncateUtf8(value, Infinity);
+  if (Array.isArray(value))
+    return value.map(cleanJson);
+  if (value && typeof value === "object")
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [truncateUtf8(key, Infinity), cleanJson(item)]));
+  return value;
+}
+
+class PermanentEventError extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "PermanentEventError";
+  }
+}
+
+class HookConfigurationError extends PermanentEventError {
+  constructor(message) {
+    super(400, "invalid_hook_configuration", message);
+    this.name = "HookConfigurationError";
+  }
+}
+
+class EventReceiver {
+  store;
+  constructor(store) {
+    this.store = store;
+  }
+  async receive(event) {
+    await this.store.accept(event);
+  }
+}
+
+class ClientTelemetry {
+  parentSpanId;
+  spans = [];
+  logs = [];
+  constructor(parentSpanId) {
+    this.parentSpanId = parentSpanId;
+  }
+  log(level, message, attributes) {
+    this.logs.push({
+      id: uuid7(),
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      spanId: this.parentSpanId,
+      attributes
+    });
+  }
+  async span(name, attributes, work) {
+    const id = uuid7();
+    const startedAt = new Date().toISOString();
+    const started = performance.now();
+    const child = new ClientTelemetry(id);
+    let status = "ok";
+    let failure;
+    try {
+      return await work(child);
+    } catch (error) {
+      status = "error";
+      failure = callerErrorDetails(error);
+      throw error;
+    } finally {
+      this.spans.push({
+        id,
+        name,
+        parentSpanId: this.parentSpanId,
+        startedAt,
+        endedAt: new Date().toISOString(),
+        status,
+        attributes: {
+          ...attributes,
+          elapsedMs: performance.now() - started,
+          ...failure ? { error: failure } : {}
+        }
+      }, ...child.spans);
+      this.logs.push(...child.logs);
+    }
+  }
+  snapshot() {
+    const spans = structuredClone(this.spans.slice(0, 512));
+    const logs = structuredClone(this.logs.slice(0, 128));
+    for (const span of spans) {
+      span.name = truncateUtf8(span.name, 256).trim() || "(unnamed span)";
+      if (span.attributes)
+        span.attributes = cleanJson(span.attributes);
+      if (span.endedAt && span.endedAt < span.startedAt)
+        span.endedAt = span.startedAt;
+    }
+    for (const log of logs) {
+      log.message = truncateUtf8(log.message, 8192);
+      if (log.attributes)
+        log.attributes = cleanJson(log.attributes);
+      if (!log.message)
+        log.message = "(empty log)";
+    }
+    const bytes = () => observationBytes({ spans, logs });
+    if (bytes() > 1024 * 1024) {
+      for (const item of [...spans, ...logs]) {
+        if (new TextEncoder().encode(JSON.stringify(item.attributes ?? {})).byteLength > 4096)
+          item.attributes = { omitted: true, reason: "telemetry_byte_limit" };
+      }
+    }
+    while (bytes() > 1024 * 1024 && (logs.length || spans.length > 1)) {
+      if (logs.length)
+        logs.pop();
+      else
+        spans.pop();
+    }
+    const ids = new Set(spans.map((span) => span.id));
+    for (const log of logs)
+      if (log.spanId && !ids.has(log.spanId))
+        delete log.spanId;
+    if (spans.length && (spans.length < this.spans.length || logs.length < this.logs.length)) {
+      spans[0].attributes = { ...spans[0].attributes, omittedSpans: this.spans.length - spans.length, omittedLogs: this.logs.length - logs.length };
+    }
+    while (bytes() > 1024 * 1024) {
+      if (logs.length)
+        logs.pop();
+      else if (spans.length > 1)
+        spans.pop();
+      else if (spans.length)
+        spans[0].attributes = { omitted: true, reason: "telemetry_byte_limit" };
+      else
+        break;
+    }
+    return { spans, logs };
+  }
+}
+async function prepareResponseBody(event, hooks, telemetry, signal) {
+  const context = { event, signal, telemetry };
+  const observe = () => ({
+    action: "observe",
+    idempotencyKey: event.id,
+    inReplyTo: { requestId: event.requestId, eventId: event.id },
+    telemetry: telemetry.snapshot()
+  });
+  signal?.throwIfAborted();
+  if (event.type !== "model.completed") {
+    await telemetry.span("client.model_error", { type: event.type }, async (t) => {
+      await hooks.onError?.(event.data, { ...context, telemetry: t });
+    });
+    return observe();
+  }
+  try {
+    const calls = event.data.message.toolCalls ?? [];
+    const ids = new Set(calls.map((c) => c.id));
+    if (ids.size !== calls.length)
+      throw new Error("Duplicate tool-call IDs in model result");
+    const concurrency = hooks.toolConcurrency ?? 8;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 128)
+      throw new HookConfigurationError("toolConcurrency must be between 1 and 128");
+    const results = new Array(calls.length);
+    let next = 0;
+    const executions = await Promise.allSettled(Array.from({ length: Math.min(concurrency, calls.length) }, async () => {
+      for (;; ) {
+        const index = next++;
+        if (index >= calls.length)
+          return;
+        signal?.throwIfAborted();
+        const call = calls[index];
+        const handler = hooks.tools?.[call.name];
+        if (!handler)
+          throw new HookConfigurationError(`No handler for tool ${call.name}`);
+        const result = await telemetry.span(`tool.${call.name}`, { toolCallId: call.id }, (t) => handler(call.arguments, {
+          ...context,
+          telemetry: t,
+          toolCallId: call.id,
+          effectId: JSON.stringify([event.id, call.id])
+        }));
+        results[index] = { id: call.id, result };
+      }
+    }));
+    const failed = executions.find((result) => result.status === "rejected");
+    if (failed)
+      throw failed.reason;
+    const decision = await telemetry.span("client.step_complete", {}, (t) => hooks.onStepComplete ? hooks.onStepComplete({
+      ...context,
+      event,
+      toolResults: results,
+      telemetry: t
+    }) : Promise.resolve(calls.length ? "continue" : "stop"));
+    if (decision === "stop")
+      return observe();
+    if (!hooks.prepareRequest)
+      throw new HookConfigurationError("prepareRequest is required to continue");
+    const input = await telemetry.span("client.prepare_request", {}, (t) => hooks.prepareRequest({
+      ...context,
+      event,
+      toolResults: results,
+      telemetry: t
+    }));
     return {
-      start: (requestId, name, options = {}, signal) => this.#startSpan(requestId, name, options, signal),
-      add: (requestId, spans, signal) => this.#addSpans(requestId, spans, signal)
+      ...input,
+      idempotencyKey: event.id,
+      inReplyTo: { requestId: event.requestId, eventId: event.id },
+      telemetry: telemetry.snapshot()
     };
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (!hooks.onError) {
+      if (!(error instanceof HookConfigurationError))
+        throw error;
+      telemetry.log("error", error.message, { code: "invalid_hook_configuration" });
+      return { ...observe(), error: { code: error.code, message: error.message } };
+    }
+    await telemetry.span("client.error", { error: callerErrorDetails(error) }, (t) => hooks.onError(error, { ...context, telemetry: t }));
+    return observe();
   }
-  get logs() {
-    return { add: (requestId, logs, signal) => this.#addLogs(requestId, logs, signal) };
+}
+async function prepareResponse(event, hooks, signal) {
+  const telemetry = new ClientTelemetry;
+  const response = await telemetry.span("client.processing", { eventId: event.id, eventType: event.type }, (child) => prepareResponseBody(event, hooks, child, signal));
+  if (response)
+    response.telemetry = telemetry.snapshot();
+  return response;
+}
+async function processEvent(client, store, event, hooks, signal) {
+  let stage = "prepare";
+  try {
+    const response = await store.prepare(event, () => prepareResponse(event, hooks, signal));
+    let receipt = null;
+    if (response) {
+      stage = "submit";
+      try {
+        receipt = await client.requests.submit(response, signal);
+      } catch (error) {
+        if (error instanceof ConstellationError && PERMANENT_RESPONSE_CODES.has(error.code)) {
+          const rejection = new PermanentEventError(error.status, error.code, error.message);
+          await store.reject(event.id, rejection);
+          throw rejection;
+        }
+        throw error;
+      }
+      if ("action" in response && response.action === "observe" && response.error) {
+        const failure = new HookConfigurationError(response.error.message);
+        await store.reject(event.id, failure);
+        throw failure;
+      }
+    }
+    stage = "checkpoint";
+    await store.complete(event.id, receipt);
+  } catch (error) {
+    if (!(error instanceof PermanentEventError) && store.retry) {
+      const detail = error instanceof ConstellationError ? { status: error.status, code: error.code, message: error.message } : { status: 0, code: error instanceof Error && error.name === "TimeoutError" ? "timeout" : stage === "submit" ? "transport_error" : `event_${stage}_failed`, message: error instanceof Error ? error.message : "Event processing failed" };
+      try {
+        await store.retry(event.id, detail);
+      } catch (monitorError) {
+        if (error && typeof error === "object")
+          Object.assign(error, { retryHookError: monitorError });
+      }
+    }
+    throw error;
   }
 }
 
@@ -598,15 +744,14 @@ class Constellation extends RequestClient {
         const event = body;
         if (typeof event.requestId !== "string" || !event.requestId)
           throw new Error("Invalid Constellation request ID");
-        if (typeof event.inputId === "string" && ["tool", "before_model", "after_model", "after_step", "user_input"].includes(String(event.kind))) {
-          if (request.headers.get("x-constellation-input-id") !== event.inputId || !event.payload || typeof event.payload !== "object" || Array.isArray(event.payload))
-            throw new Error("Invalid Constellation input notification");
+        if (typeof event.id === "string" && event.id && Number.isSafeInteger(event.sequence) && typeof event.createdAt === "string" && Number.isFinite(Date.parse(event.createdAt)) && event.data && typeof event.data === "object" && !Array.isArray(event.data) && ["model.completed", "model.failed", "model.cancelled"].includes(String(event.type))) {
+          if (event.type === "model.completed") {
+            const data = event.data;
+            if (!data.message || typeof data.message !== "object" || data.message.role !== "assistant" || !data.result || typeof data.result !== "object")
+              throw new Error("Invalid completed model result");
+          }
           return event;
         }
-        if (event.kind === "request.events" && Number.isSafeInteger(event.afterSeq) && Array.isArray(event.events))
-          return event;
-        if (["request.completed", "request.failed", "request.cancelled"].includes(String(event.kind)) && Number.isSafeInteger(event.eventSeq))
-          return event;
         throw new Error("Unknown Constellation webhook event");
       }
     };
@@ -614,6 +759,14 @@ class Constellation extends RequestClient {
 }
 export {
   uuid7,
+  processEvent,
+  prepareResponse,
+  normalizeTimestamp,
+  PermanentEventError,
+  PERMANENT_RESPONSE_CODES,
+  HookConfigurationError,
+  EventReceiver,
   ConstellationError,
-  Constellation
+  Constellation,
+  ClientTelemetry
 };