@lionhummer/constellation 0.5.0 → 0.9.0

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

@@ -0,0 +1,81 @@
+import { type Admission, type AdmissionReceipt, type Json, type Log, type Message, type ModelCompletedEvent, type Observations, type RequestClient, type RequestInput, type Span, type WebhookEvent } from "./index";
+/** Response-submission error codes that never succeed on retry. Generated from
+ * the server's error table and checked by its tests. */
+export declare const PERMANENT_RESPONSE_CODES: ReadonlySet<string>;
+export declare class PermanentEventError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare class HookConfigurationError extends PermanentEventError {
+    constructor(message: string);
+}
+/** Application-owned durable event checkpoints. All methods must survive process restart. */
+export interface EventStore {
+    /** Atomically retain the event before processing it.
+     * Duplicate IDs must compare equal payloads. Resolve only after durable receipt. */
+    accept(event: WebhookEvent): Promise<void>;
+    /** Serialize processing per event. Return the saved response if present; otherwise
+     * run prepare and durably store its exact result before returning. A crash can
+     * rerun prepare: tool/billing effects must use the supplied stable identities. */
+    prepare(event: WebhookEvent, prepare: () => Promise<Admission | null>): Promise<Admission | null>;
+    /** Atomically mark the event processed after its saved response settled. `receipt.outcome` is
+     * `accepted`, `already_accepted` or `event_closed`; for `event_closed`, `receipt.observationsRecorded`
+     * says whether the continuation's telemetry was kept. `null` when no response was submitted. */
+    complete(eventId: string, receipt: AdmissionReceipt | null): Promise<void>;
+    /** Durably stop retries of a rejected saved response. Replays must rethrow this rejection. */
+    reject(eventId: string, error: PermanentEventError): Promise<void>;
+    /** Persist retry count, first/last failure timestamps and latest error in the existing inbox. Non-HTTP failures use status 0; alert on age/repeated failures.
+     * If this hook throws, processEvent still rethrows the original failure, with the hook error as its `retryHookError` property. */
+    retry?(eventId: string, error: {
+        status: number;
+        code: string;
+        message: string;
+    }): Promise<void>;
+}
+export declare class EventReceiver {
+    private readonly store;
+    constructor(store: EventStore);
+    /** Call after webhook authentication. Return a successful HTTP response only after this resolves. */
+    receive(event: WebhookEvent): Promise<void>;
+}
+export declare class ClientTelemetry {
+    readonly parentSpanId?: string | undefined;
+    readonly spans: Span[];
+    readonly logs: Log[];
+    constructor(parentSpanId?: string | undefined);
+    log(level: Log["level"], message: string, attributes?: Record<string, Json>): void;
+    span<T>(name: string, attributes: Record<string, Json>, work: (telemetry: ClientTelemetry) => Promise<T>): Promise<T>;
+    snapshot(): Observations;
+}
+export type ToolResult = NonNullable<Message["toolResults"]>[number];
+export type HookContext = {
+    event: WebhookEvent;
+    signal?: AbortSignal;
+    telemetry: ClientTelemetry;
+};
+export interface AgentHooks {
+    /** Required only when continuing. Returns the complete next model input. */
+    prepareRequest?: (context: HookContext & {
+        event: ModelCompletedEvent;
+        toolResults: ToolResult[];
+    }) => Promise<Omit<RequestInput, "idempotencyKey" | "inReplyTo" | "telemetry">>;
+    tools?: Record<string, (args: Json, context: HookContext & {
+        toolCallId: string;
+        effectId: string;
+    }) => Promise<Json>>;
+    /** Defaults to continue when tools were called, otherwise stop. Deduplicate business effects by event.id. */
+    onStepComplete?: (context: HookContext & {
+        event: ModelCompletedEvent;
+        toolResults: ToolResult[];
+    }) => Promise<"continue" | "stop">;
+    /** Return normally to record failure observations and stop; throw to leave the inbox item retryable. */
+    onError?: (error: unknown, context: HookContext) => Promise<void>;
+    toolConcurrency?: number;
+}
+/** Record the client processing interval and its actual child-span hierarchy. */
+export declare function prepareResponse(event: WebhookEvent, hooks: AgentHooks, signal?: AbortSignal): Promise<Admission | null>;
+/** Process an authenticated event using an application-owned durable checkpoint.
+ * Any receipt (`accepted`, `already_accepted`, `event_closed`) completes the checkpoint; a permanent
+ * error code rejects it with PermanentEventError; anything else reports through `store.retry` and throws. */
+export declare function processEvent(client: RequestClient, store: EventStore, event: WebhookEvent, hooks: AgentHooks, signal?: AbortSignal): Promise<void>;

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

@@ -57,9 +57,14 @@ type RequestFields = {
     optionalParameters?: string[];
     /** Only headers approved by the selected provider are forwarded; others produce warnings. */
     headers?: Record<string, string>;
-    nativeContentPolicy?: "require" | "omitCompleted";
-    maxSteps?: number;
+    nativeContentPolicy?: "require" | "omitCompleted" | "omitIncompatible";
     timeoutMs?: number;
+    /** Optional per-provider limits. Omitted values use the request deadline; operator liveness watchdogs may be shorter. */
+    attemptTimeoutMs?: number;
+    firstByteTimeoutMs?: number;
+    idleTimeoutMs?: number;
+    /** Actual offering attempts, including preparation failures; default 32, maximum 256. */
+    maxProviderAttempts?: number;
     maxOutputTokens?: number;
     cache?: {
         mode: "automatic" | "explicit";
@@ -80,20 +85,53 @@ type RequestFields = {
     };
 };
 export type RequestEventModes = {
-    beforeModel?: "off" | "notify" | "wait";
-    afterModel?: "off" | "notify" | "wait";
-    afterStep?: "off" | "notify" | "wait";
-    outputDelta?: "off" | "notify";
     terminal?: "off" | "notify";
 };
 /** One execution protocol; events determine where the caller participates. */
+export type EventReference = {
+    requestId: string;
+    eventId: string;
+};
+export type Observations = {
+    spans?: Span[];
+    logs?: Log[];
+};
 export type RequestInput = RequestFields & {
     events?: RequestEventModes;
+    inReplyTo?: EventReference;
+    telemetry?: Observations;
+};
+export type ObservationResponse = {
+    action: "observe";
+    idempotencyKey: string;
+    inReplyTo: EventReference;
+    telemetry: Observations;
+    error?: {
+        code: string;
+        message: string;
+    };
 };
-export type Status = "queued" | "running" | "waiting" | "completed" | "failed" | "cancelled";
+export type Admission = RequestInput | ObservationResponse;
+/** Event-response outcome. `accepted` committed this response; `already_accepted` is an identical retry;
+ * `event_closed` means the source event closed before this continuation (nothing was scheduled). */
+export type ResponseOutcome = "accepted" | "already_accepted" | "event_closed";
+export type AdmissionReceipt = {
+    id: string;
+    scheduled?: boolean;
+    /** Present on event responses (`inReplyTo`). */
+    outcome?: ResponseOutcome;
+    /** With `event_closed`: whether the continuation's telemetry was kept as late observations. */
+    observationsRecorded?: boolean;
+};
+export type Status = "queued" | "running" | "client_processing" | "completed" | "failed" | "cancelled";
 export type RequestRecord = {
     id: string;
     externalId: string | null;
+    diagnostics?: {
+        omitted: boolean;
+        reason: string;
+        limitBytes?: number;
+    };
     workspaceId: string;
     userId: string | null;
     requestedModel: string;
@@ -158,6 +196,8 @@ export type Attempt = {
     committed: boolean;
     supplierPrice: Json;
     customerPrice: Json;
+    /** Captured supplier/customer pricing and realized accounting facts. */
+    billing?: Json;
     parameters: Json;
     usage: Json;
     supplierCost: string | null;
@@ -174,49 +214,10 @@ export type Attempt = {
     startedAt: string;
     endedAt: string | null;
 };
-export type PreparedStep = {
-    model: string;
-    instructions: string;
-    messages: Message[];
-    tools: Tool[];
-    parameters: InferenceParameters;
-    optionalParameters?: string[];
-    /** Only headers approved by the selected provider are forwarded; others produce warnings. */
-    headers?: Record<string, string>;
-    nativeContentPolicy?: "require" | "omitCompleted";
-    maxOutputTokens: number;
-    cache: RequestInput["cache"] | null;
-};
-export type PendingInput = {
-    id: string;
-    requestId: string;
-    stepId: string | null;
-    kind: "tool" | "user_input" | "before_model" | "after_model" | "after_step";
-    payload: {
-        providerCallId?: string;
-        name?: string;
-        arguments?: Json;
-        validationError?: string | null;
-        toolCalls?: ToolCall[];
-        toolResults?: Message["toolResults"];
-        usage?: Json;
-        customerCost?: string | null;
-        supplierCost?: string | null;
-        customerPrice?: Json;
-        customerPricing?: CustomerPricing;
-        billing?: BillingFacts;
-        output?: Json;
-    };
-    claimId: string | null;
-    claimUntil?: string | null;
-    response: Json;
-    resolvedAt: string | null;
-};
 export type Span = {
     id: string;
     stepId?: string | null;
     attemptId?: string | null;
-    inputId?: string | null;
     parentSpanId?: string | null;
     name: string;
     startedAt: string;
@@ -240,7 +241,6 @@ export type TimelineRow = {
     derivedFrom?: string[];
     source?: "caller" | "constellation";
     parentSpanId?: string | null;
-    inputId?: string | null;
     stepId?: string | null;
     attemptId?: string | null;
     [key: string]: Json | undefined;
@@ -248,6 +248,7 @@ export type TimelineRow = {
 export type Timeline = {
     workspaceId: string;
     externalId: string | null;
+    inReplyTo?: EventReference | null;
     rows: TimelineRow[];
     total: number;
     offset: number;
@@ -273,50 +274,36 @@ export type Inspection = {
     request: RequestRecord;
     steps: Step[];
     attempts: Attempt[];
-    inputs: PendingInput[];
     spans: Span[];
     logs: Log[];
 };
 export type RecordTypes = {
     steps: Step;
     attempts: Attempt;
-    inputs: PendingInput;
     spans: Span;
     logs: Log;
 };
-export type InputResponse = {
-    claimId?: string;
-    result?: Json;
-    isError?: boolean;
-    stepInput?: PreparedStep;
-    action?: "continue" | "wait_for_user" | "wait" | "complete" | "fail";
-};
-export type InputHandlers = {
-    checkpoints?: Partial<Record<"beforeModel" | "afterModel" | "afterStep", (payload: PendingInput["payload"], state: Inspection, context: {
-        inputId: string;
-        parentSpanId: string;
-        signal: AbortSignal;
-    }) => Promise<InputResponse>>>;
-    tools?: Record<string, (args: Json, context: {
-        inputId: string;
-        requestId: string;
-        signal?: AbortSignal;
-    }) => Promise<Json>>;
-    userInput?: (state: Inspection, context: {
-        inputId: string;
-        signal: AbortSignal;
-    }) => Promise<Json>;
-    signal?: AbortSignal;
-    consumerId?: string;
-    toolTimeoutMs?: number;
-    onUpdate?: (state: Inspection) => void;
-};
-export type RequestEvent = {
-    seq: number;
-    type: string;
-    data: Record<string, Json>;
-    timestamp: string;
+export type ModelStreamFrame = {
+    event: {
+        type: string;
+        [key: string]: Json;
+    };
+    frame: Record<string, Json>;
+};
+export type ModelDeltaEvent = {
+    id: string;
+    requestId: string;
+    sequence: number;
+    createdAt: string;
+    type: "model.delta";
+    data: {
+        stepId: string;
+        stepNumber: number;
+        attemptId: string;
+        events: ModelStreamFrame[];
+    };
 };
+export type RequestEvent = WebhookEvent | ModelDeltaEvent;
 export type Page<T> = {
     items: T[];
     total: number;
@@ -342,28 +329,46 @@ 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;
-    inputId: string;
-    kind: PendingInput["kind"];
-    payload: Record<string, Json>;
-} | {
+export type ModelCompletedEvent = {
+    id: string;
     requestId: string;
-    kind: "request.events";
-    afterSeq: number;
-    events: Json[];
-} | {
+    sequence: number;
+    createdAt: string;
+    type: "model.completed";
+    data: {
+        message: Message;
+        result: Record<string, Json>;
+        events?: Json[];
+        stepId?: string;
+        stepNumber?: number;
+        attemptId?: string;
+    };
+};
+export type WebhookEvent = ModelCompletedEvent | {
+    id: string;
     requestId: string;
-    eventSeq: number;
-    kind: "request.completed" | "request.failed" | "request.cancelled";
+    sequence: number;
+    createdAt: string;
+    type: "model.failed" | "model.cancelled";
+    data: Record<string, Json>;
 };
 export declare class ConstellationError extends Error {
     status: number;
     code: string;
     constructor(status: number, code: string, message: string);
 }
+/** Size of the server's typed observation representation, including absent optionals. */
+export declare function observationBytes(observations: Observations): number;
+/** Millisecond UTC ISO-8601 (`...sss` + `Z`). The server re-serializes timestamps with chrono,
+ * which widens 1/2-digit fractions to 3 and 4/7-digit fractions to 6/9; normalizing first keeps
+ * the client byte estimate an upper bound. Unparseable values are left for validation. */
+export declare function normalizeTimestamp(value: string): string;
+/** Copy observations with every caller-supplied timestamp in millisecond `Z` form. */
+export declare function normalizeObservations(observations: Observations): Observations;
+/** Validate response telemetry before any HTTP admission attempt. */
+export declare function validateObservations(observations: Observations): void;
 export declare function uuid7(): string;
 /** Provider-reported token counts. Missing usage is unknown, not zero. */
 export type TokenUsage = {
@@ -448,10 +453,8 @@ export type RequestTimings = {
     queueMs: number | null;
     workerPreparationMs: number | null;
     attemptMs: number | null;
-    callerWaitMs: number | null;
     phases: TimingInterval[];
     attempts: TimingInterval[];
-    callerWaits: TimingInterval[];
     asOf: string;
     complete: boolean;
     truncated: boolean;
@@ -484,14 +487,6 @@ export type RequestListQuery = {
     limit?: number;
     offset?: number;
 };
-export type StartSpanOptions = {
-    stepId?: string;
-    attemptId?: string;
-    inputId?: string;
-    parentSpanId?: string;
-    startedAt?: string;
-    attributes?: Record<string, Json>;
-};
 type ClientOptions = {
     baseUrl: string;
     apiPrefix?: "/v1" | "/internal";
@@ -501,8 +496,6 @@ type ClientOptions = {
 export declare class RequestClient {
     #private;
     constructor(options: ClientOptions);
-    /** Agent claims are leases. Keep one alive while a caller handler is running. */
-    private maintainClaim;
     /** Client-safe discovery with an execution key. */
     get models(): {
         list: (scope: ModelScope, signal?: AbortSignal) => Promise<Json>;
@@ -510,9 +503,7 @@ export declare class RequestClient {
     };
     /** Durable requests. create returns an ID; execution continues independently. */
     get requests(): {
-        create: (input: RequestInput, signal?: AbortSignal) => Promise<{
-            id: string;
-        }>;
+        submit: (input: Admission, signal?: AbortSignal) => Promise<AdmissionReceipt>;
         preview: (input: RequestInput, signal?: AbortSignal) => Promise<{
             revision: number;
             resolution: Record<string, Json>;
@@ -521,6 +512,8 @@ export declare class RequestClient {
             dispatched: false;
         }>;
         get: (id: string, signal?: AbortSignal) => Promise<Inspection>;
+        /** Committed execution state, independent of diagnostic history and its budgets. */
+        getState: (id: string, signal?: AbortSignal) => Promise<Inspection>;
         getSummary: (id: string, signal?: AbortSignal) => Promise<Inspection>;
         getTimings: (id: string, signal?: AbortSignal) => Promise<RequestTimings>;
         list: (query?: RequestListQuery, signal?: AbortSignal) => Promise<{
@@ -557,26 +550,5 @@ export declare class RequestClient {
             limit?: number;
         }, signal?: AbortSignal) => Promise<Json>;
     };
-    /** The same handlers work with webhook delivery and explicit polling. */
-    get inputs(): {
-        handle: (requestId: string, inputId: string, handlers: InputHandlers) => Promise<Inspection>;
-        poll: (requestId: string, handlers: InputHandlers) => Promise<Inspection>;
-        claim: (requestId: string, inputId: string, claimId: string, signal?: AbortSignal) => Promise<void>;
-        respond: (requestId: string, inputId: string, response: InputResponse, signal?: AbortSignal) => Promise<void>;
-    };
-    get spans(): {
-        start: (requestId: string, name: string, options?: StartSpanOptions, signal?: AbortSignal) => Promise<{
-            id: string;
-            end: (options?: {
-                endedAt?: string;
-                status?: "ok" | "error" | "cancelled";
-                attributes?: Record<string, Json>;
-            }, signal?: AbortSignal) => Promise<void>;
-        }>;
-        add: (requestId: string, spans: Span[], signal?: AbortSignal) => Promise<void>;
-    };
-    get logs(): {
-        add: (requestId: string, logs: Log[], signal?: AbortSignal) => Promise<void>;
-    };
 }
 export {};

package/dist/types/client-core/src/input-receiver.d.ts

@@ -0,0 +1,24 @@
+/** A bounded event receiver. Local scheduling is disposable: the server retains
+ * unresolved inputs and redelivers after processing claims expire. */
+export interface InputNotification {
+    requestId: string;
+    inputId: string;
+}
+export interface InputReceiverOptions {
+    maxInFlight: number;
+    process: (notification: InputNotification, signal: AbortSignal) => Promise<void>;
+    onError: (error: unknown, notification: InputNotification) => void;
+}
+export type InputAcceptance = "accepted" | "duplicate" | "busy" | "closed";
+export declare class InputReceiver {
+    #private;
+    constructor(options: InputReceiverOptions);
+    /** Return HTTP 202 for accepted/duplicate, HTTP 503 for busy/closed.
+     * Authenticate and validate notifications before calling this method.
+     * No tool execution or remote inspection is awaited by this boundary. */
+    accept(notification: InputNotification): InputAcceptance;
+    get active(): number;
+    /** Graceful shutdown stops acceptance and cancels handlers. The server remains
+     * responsible for recovering unresolved inputs; no local queue is persisted. */
+    close(): Promise<void>;
+}

package/dist/types/sdk/src/index.d.ts

@@ -1,7 +1,7 @@
 /** External server SDK. Operator APIs and cookie sessions are internal-only clients. */
 import { RequestClient, type WebhookEvent, type Json, type Page, type PageQuery, type ModelResolution, type RequestRecord, type RequestEvent, type RecordTypes, type Timeline, type TimelineRow, type RequestListQuery, type RequestRecordsQuery, type RequestTimings, type TokenUsage } from "../../client-core/src/index";
-export { ConstellationError, uuid7 } from "../../client-core/src/index";
-export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, PreparedStep, PendingInput, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, InputResponse, InputHandlers, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery, StartSpanOptions } from "../../client-core/src/index";
+export { ConstellationError, uuid7, normalizeTimestamp } from "../../client-core/src/index";
+export type { InferenceParameters, Json, Tool, ToolCall, Message, RequestEventModes, RequestInput, Admission, AdmissionReceipt, ResponseOutcome, ObservationResponse, Observations, EventReference, ModelCompletedEvent, ModelDeltaEvent, ModelStreamFrame, RequestTimings, TimingInterval, TokenUsage, TokenPrice, CustomerPricing, BillingFacts, Status, RequestRecord, Step, Attempt, Span, TimelineRow, Timeline, Log, Inspection, RecordTypes, RequestEvent, Page, PageQuery, ModelScope, ModelResolution, WebhookEvent, RequestRecordsQuery, RequestListQuery } from "../../client-core/src/index";
 /** OpenAPI contract filtered to this key's permissions and scope. */
 export type DiscoveryDocument = {
     openapi: string;
@@ -64,10 +64,6 @@ export type TelemetryRequest = OptionalContent<RequestRecord, "output" | "error"
 export type TelemetryRecords = {
     steps: OptionalContent<RecordTypes["steps"], "input" | "output" | "resolution" | "rules" | "customerPrice">;
     attempts: OptionalContent<RecordTypes["attempts"], "endpoint" | "parameters" | "supplierPrice" | "customerPrice" | "error">;
-    inputs: Partial<RecordTypes["inputs"]> & {
-        id: string;
-        requestId: string;
-    };
     spans: Partial<RecordTypes["spans"]> & {
         id: string;
         requestId: string;
@@ -88,7 +84,6 @@ export type TelemetryInspection = {
     effectiveInput?: Json;
     steps: TelemetryRecords["steps"][];
     attempts: TelemetryRecords["attempts"][];
-    inputs: TelemetryRecords["inputs"][];
     spans: TelemetryRecords["spans"][];
     logs: TelemetryRecords["logs"][];
 };
@@ -208,3 +203,5 @@ export declare class Constellation extends RequestClient {
         verify: (request: Request, expectedToken: string) => Promise<WebhookEvent>;
     };
 }
+export { PermanentEventError, HookConfigurationError, EventReceiver, prepareResponse, processEvent, ClientTelemetry, PERMANENT_RESPONSE_CODES } from "../../client-core/src/agent";
+export type { EventStore, AgentHooks, HookContext, ToolResult } from "../../client-core/src/agent";

package/examples/quickstart.mjs

@@ -30,14 +30,14 @@ if (!model) {
     messages: [{ role: "user", text: "Say hello in one short sentence." }],
     maxOutputTokens: 256,
     timeoutMs: 120_000,
-    // No tools or wait checkpoints: no webhook or input consumer is needed.
+    events: { terminal: "off", },
   };
-  const { id } = await client.requests.create(input);
+  const { id } = await client.requests.submit(input);
   console.log("Request ID:", id);
   for await (const event of client.requests.streamEvents(id, {
     signal: AbortSignal.timeout(150_000),
   })) {
-    console.log(event.seq, event.type);
+    console.log(event.sequence, event.type);
   }
   const { request } = await client.requests.getSummary(id);
   console.log("Final status:", request.status);

package/package.json

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