@lionhummer/constellation 0.5.0 → 0.6.0

package/README.md

@@ -217,3 +217,15 @@ The standard Reasoning Effort vocabulary is `none`, `minimal`, `low`, `medium`,
 For cache diagnostics, send `cache: { mode: "automatic", diagnostics: true }` on the first step. `providerResponseId` appears on attempts and in the `afterModel` checkpoint payload. Use that upstream ID as a later step’s `cache.comparisonId`, which also enables diagnostics. A successful cache hit may return no diagnostic payload. Telemetry exposes the response ID by default; raw `cacheDiagnostics` requires `include: "content"`. Diagnostics and prewarm are offering capabilities: discover support before requesting them. Invalid TTLs or unsupported required cache settings fail rather than being silently dropped.
 
 Send beta tokens as `headers: { "anthropic-beta": "your-beta-token" }`, not inside `parameters`. The provider connection must allow the header name. Unapproved, protected or malformed headers are dropped with warnings. A permitted header can still contain an upstream-unsupported beta token; the provider's own error remains visible. Cache diagnostics can add their required beta separately. Obvious may choose provider-specific prompt placement and cache boundaries while using Constellation's standard cache request.
+
+## Reasoning history and model handoffs
+
+Retain the complete `nativeContent` artifact from assistant output alongside canonical text, tool calls and results. Reasoning summaries alone cannot reconstruct signed/encrypted state. Use `nativeContentPolicy: "omitIncompatible"` on submitted or prepared steps to permit cross-family handoffs, including active tool continuations. Constellation omits only incompatible native state in the outbound attempt and records a warning; the original history remains intact. `require` excludes incompatible routes; `omitCompleted` permits omission only from completed turns.
+
+Same-protocol Claude/Responses model switches let providers verify native readability. Responses account scopes must be verified; Gemini also requires the model replay group. Preserve the exact prompt prefix for signed thinking. Provider-reported thinking drops and allowed prefix mismatches appear in provider span `attributes.reasoningTransformations`; a successful response does not prove retention. See [the HTTP contract](../../docs/api.md#provider-protocols).
+
+### Tool timing
+
+`inputs.handle` and `inputs.poll` record tool-input inspection, claim and response POST phases. A tool handler receives `context.parentSpanId` and `context.recordSpan(span)`; use the latter to attach closed preparation/execution spans without an HTTP call per phase. Child spans are batched with the tool-span close. Keep spans linked to the current input and omit arguments, results and secrets from attributes. The result POST observation is best effort: a request that has already ended rejects late telemetry, without replaying the committed response.
+
+Callback round trips include your handler's processing time. Compare the input wait, tool span and child execution phases rather than adding their overlapping durations. Monotonic `elapsedMs` values are retained in metadata-only telemetry; timestamps across hosts assume aligned clocks.

package/dist/index.js

@@ -202,7 +202,7 @@ class RequestClient {
           status: options2.status ?? closed?.status ?? "ok",
           attributes: options2.attributes ?? closed?.attributes ?? span.attributes
         };
-        return this.#addSpans(id, [closed], signal2);
+        return this.#addSpans(id, [closed, ...options2.spans ?? []], signal2);
       }
     };
   }
@@ -285,7 +285,11 @@ class RequestClient {
   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;
@@ -351,6 +355,8 @@ class RequestClient {
         }
         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;
@@ -361,8 +367,14 @@ class RequestClient {
             continue;
           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;
@@ -375,6 +387,8 @@ class RequestClient {
             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) {
@@ -383,9 +397,23 @@ class RequestClient {
             errorDetails = callerErrorDetails(error);
             result = { error: error instanceof Error ? error.message : "Tool failed" };
           }
-          await span.end({ status: isError ? "error" : "ok", ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
+          await span.end({ status: isError ? "error" : "ok", spans: phases, ...errorDetails ? { attributes: { error: errorDetails } } : {} }, activeSignal);
           await this.#claim(id, pending.id, consumerId, activeSignal);
-          await this.#respond(id, pending.id, { result, isError, claimId: 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;
       }

package/dist/types/client-core/src/index.d.ts

@@ -57,7 +57,7 @@ type RequestFields = {
     optionalParameters?: string[];
     /** Only headers approved by the selected provider are forwarded; others produce warnings. */
     headers?: Record<string, string>;
-    nativeContentPolicy?: "require" | "omitCompleted";
+    nativeContentPolicy?: "require" | "omitCompleted" | "omitIncompatible";
     maxSteps?: number;
     timeoutMs?: number;
     maxOutputTokens?: number;
@@ -183,7 +183,7 @@ export type PreparedStep = {
     optionalParameters?: string[];
     /** Only headers approved by the selected provider are forwarded; others produce warnings. */
     headers?: Record<string, string>;
-    nativeContentPolicy?: "require" | "omitCompleted";
+    nativeContentPolicy?: "require" | "omitCompleted" | "omitIncompatible";
     maxOutputTokens: number;
     cache: RequestInput["cache"] | null;
 };
@@ -300,6 +300,8 @@ export type InputHandlers = {
     tools?: Record<string, (args: Json, context: {
         inputId: string;
         requestId: string;
+        parentSpanId: string;
+        recordSpan: (span: Span) => void;
         signal?: AbortSignal;
     }) => Promise<Json>>;
     userInput?: (state: Inspection, context: {
@@ -342,7 +344,7 @@ export type ModelResolution = ModelScope & {
     optionalParameters?: string[];
     /** Only headers approved by the selected provider are forwarded; others produce warnings. */
     headers?: Record<string, string>;
-    nativeContentPolicy?: "require" | "omitCompleted";
+    nativeContentPolicy?: "require" | "omitCompleted" | "omitIncompatible";
 };
 export type WebhookEvent = {
     requestId: string;
@@ -571,6 +573,7 @@ export declare class RequestClient {
                 endedAt?: string;
                 status?: "ok" | "error" | "cancelled";
                 attributes?: Record<string, Json>;
+                spans?: Span[];
             }, signal?: AbortSignal) => Promise<void>;
         }>;
         add: (requestId: string, spans: Span[], signal?: AbortSignal) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript client for durable model requests and caller events",
   "type": "module",
   "license": "UNLICENSED",