@lionhummer/constellation 0.9.1 → 0.9.2

package/README.md

@@ -343,6 +343,24 @@ tools: {
 
 The SDK records `client.processing` and one span per tool automatically. A response carries at most 512 spans, 128 logs and 1 MiB of telemetry; the SDK trims larger batches and records what it omitted. Do not put secrets or personal data in span names, attributes or log messages.
 
+## Opening lines
+
+Show a one-sentence opener while the real step is prepared. The operator configures its model and prompt in Constellation.
+
+```ts
+const opener = await client.openers.create({
+  idempotencyKey: `${turnId}`,
+  workspaceId, userId, externalId: threadId,
+  message,
+  history: recentTurns, // [{ role: "user" | "assistant", text }], oldest first
+})
+if (opener) void client.openers.sentence(opener.id).then((sentence) => {
+  if (sentence && !realOutputStarted) show(sentence)
+})
+```
+
+Start the real request without waiting for the opener. `parseOpenerSentence(text)` applies the same checks to text you already have.
+
 ## Limits and timeouts
 
 | Setting | Default | Notes |
@@ -367,6 +385,7 @@ A failed provider call falls back to the next provider only before any output ha
 | `requests.submit(input)` | Start a request, continue it (`inReplyTo`), or stop it (`action: "observe"`). |
 | `requests.preview(input)` | Validate a complete input and show routing, without calling a provider. |
 | `requests.cancel(id)` | Cancel a request. |
+| `openers.create(input)`, `openers.sentence(id)` | Start an opening line for a just-sent message (null when openers are turned off), then wait for its sentence (null when skipped or failed). |
 | `requests.getState(id)` | Committed state: status, steps, attempt outcomes, usage and cost. |
 | `requests.getSummary(id)`, `requests.get(id)` | Request detail, without or with spans and logs. |
 | `requests.list(query)` | Page through requests, e.g. by `externalId` or `status`. |

package/dist/index.js

@@ -1,4 +1,15 @@
 // ../client-core/src/index.ts
+function parseOpenerSentence(raw, maxWords = 25) {
+  const text = raw.trim();
+  if (!text || /^SKIP\b/i.test(text))
+    return null;
+  const sentence = (text.match(/^.+?[.!](?=\s|[A-Z]|$)/)?.[0] ?? text).trim();
+  if (sentence.includes("`") || sentence.includes(`
+`) || sentence.split(/\s+/).length > maxWords)
+    return null;
+  return sentence;
+}
+
 class ConstellationError extends Error {
   status;
   code;
@@ -300,6 +311,30 @@ class RequestClient {
       resolve: (input, signal) => this.#call("/v1/registry/resolve", "POST", input, signal)
     };
   }
+  get openers() {
+    return {
+      create: async (input, signal) => await this.#call("/v1/openers", "POST", input, signal) ?? null,
+      sentence: async (id, options = {}) => {
+        let text = "";
+        for await (const event of this.#events(id, { signal: options.signal })) {
+          if (event.type === "model.completed") {
+            const message = event.data.message;
+            text = message?.text ?? text;
+            break;
+          }
+          if (event.type === "model.failed" || event.type === "model.cancelled")
+            return null;
+          if (event.type === "model.delta") {
+            for (const entry of event.data.events ?? []) {
+              if (entry.event?.type === "text_delta")
+                text += entry.event.delta ?? "";
+            }
+          }
+        }
+        return parseOpenerSentence(text, options.maxWords);
+      }
+    };
+  }
   get requests() {
     return {
       submit: (input, signal) => this.#submit(input, signal),
@@ -770,6 +805,7 @@ export {
   uuid7,
   processEvent,
   prepareResponse,
+  parseOpenerSentence,
   normalizeTimestamp,
   PermanentEventError,
   PERMANENT_RESPONSE_CODES,

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

@@ -304,6 +304,24 @@ export type ModelDeltaEvent = {
     };
 };
 export type RequestEvent = WebhookEvent | ModelDeltaEvent;
+export type OpenerTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+export type OpenerInput = {
+    /** Stable per turn, so a retry never admits a second opener. */
+    idempotencyKey: string;
+    workspaceId: string;
+    userId?: string;
+    externalId?: string;
+    planId?: string;
+    /** The message the user just sent. */
+    message: string;
+    /** Earlier turns, oldest first; operator settings decide how many are used. */
+    history?: OpenerTurn[];
+};
+/** The opener line to show: one sentence, no code, within `maxWords`; null for SKIP or anything else. */
+export declare function parseOpenerSentence(raw: string, maxWords?: number): string | null;
 export type Page<T> = {
     items: T[];
     total: number;
@@ -503,6 +521,22 @@ export declare class RequestClient {
         list: (scope: ModelScope, signal?: AbortSignal) => Promise<Json>;
         resolve: (input: ModelResolution, signal?: AbortSignal) => Promise<Json>;
     };
+    /**
+     * Opening lines: an operator-configured short model call, made when the user
+     * sends, naming what the assistant does first. create admits it as an
+     * ordinary request; sentence waits for it to end and returns the line to
+     * show, or null for SKIP, a failure, or an answer that breaks the format.
+     */
+    get openers(): {
+        /** The opener request, or null when the operator has turned openers off. */
+        create: (input: OpenerInput, signal?: AbortSignal) => Promise<{
+            id: string;
+        } | null>;
+        sentence: (id: string, options?: {
+            signal?: AbortSignal;
+            maxWords?: number;
+        }) => Promise<string | null>;
+    };
     /** Durable requests. create returns an ID; execution continues independently. */
     get requests(): {
         submit: (input: Admission, signal?: AbortSignal) => Promise<AdmissionReceipt>;

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, 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";
+export { ConstellationError, uuid7, normalizeTimestamp, parseOpenerSentence } 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, OpenerInput, OpenerTurn } from "../../client-core/src/index";
 /** OpenAPI contract filtered to this key's permissions and scope. */
 export type DiscoveryDocument = {
     openapi: string;

package/package.json

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