@genesislcap/ai-assistant 15.86.1 → 15.87.0

package/dist/dts/headless/headless.types.d.ts

@@ -0,0 +1,435 @@
+import type { AggregateUsage, ChatAttachment } from '@genesislcap/foundation-ai';
+import type { AutopilotHost } from '../autopilot/autopilot-driver';
+import type { WidgetTools } from '../autopilot/widget-tools';
+import type { AgenticActivityBus } from '../channel/ai-activity-bus';
+import type { AiDriver } from '../components/ai-driver/ai-driver';
+import type { AgentConfig } from '../config/config';
+import type { DebugLog } from '../state/persistence/diagnostics';
+import type { InteractionContext } from '../types/interaction-context';
+import type { InvokeResult } from '../types/interaction-surface';
+/**
+ * One action of a pending interaction, as a model reads it: a SurfaceAction cut to what is
+ * useful to choose by, with the number {@link describeInteraction} gave it. Plain data.
+ *
+ * @beta
+ */
+export interface DescribedAction {
+    /**
+     * The number the action is chosen by, when it is a numbered option: the same number the
+     * autopilot's list gives it, so "1" means the same option to both. Absent on a platform-owned
+     * action (`select`, `reply`) or a named, full-form one, which are chosen by `name`.
+     */
+    readonly n?: number;
+    /** The action's name: what `act` runs when it is not chosen by number. */
+    readonly name: string;
+    /** What the person would read on the button, when it differs from the name. */
+    readonly label?: string;
+    /** What a full-form action does, as its widget wrote it. */
+    readonly description?: string;
+    /** Whether it can be taken now. */
+    readonly enabled: boolean;
+    /** Why it cannot be, when it is not enabled and the widget said. */
+    readonly unavailable?: string;
+    /**
+     * What it takes: `'options'` (`select`: several, by number or label), `'text'` (written words)
+     * or `'fields'` (a JSON object fitting `argsSchema`). Absent: nothing.
+     */
+    readonly args?: 'options' | 'text' | 'fields';
+    /** The shape `fields` must fit, for an action that takes them. */
+    readonly argsSchema?: Readonly<Record<string, unknown>>;
+    /** Whether running it settles the interaction. */
+    readonly finishes: boolean;
+    /** Whether it is a written refinement: one that counts against a step's limit. */
+    readonly refines?: boolean;
+}
+/**
+ * What a pending interaction needs from the person, as a compact, JSON-serialisable view a model
+ * can read and answer.
+ *
+ * @beta
+ */
+export interface InteractionDescription {
+    readonly interactionId: string;
+    /** The widget type. */
+    readonly component: string;
+    /** Who holds it: `'user'`, or a claimant such as `'autopilot'`. */
+    readonly heldBy: string;
+    /**
+     * Whether the widget has a controller and so a surface to act on. `false`: nothing here can be
+     * run with `act`; `text` is all the widget says, and only a raw `resolve` can settle it.
+     */
+    readonly controller: boolean;
+    /**
+     * Whether the person can act now. A widget with no controller is ready; one with a surface is
+     * ready when it has an enabled finishing action and is not busy working.
+     */
+    readonly ready: boolean;
+    /**
+     * What the autopilot would be sent for it: the same `renderDecision` text (the widget as text,
+     * its views and facts, the numbered actions), or the widget as text alone where there is no
+     * surface.
+     */
+    readonly text: string;
+    /** Every action, in the order the list shows them. Empty with no surface. */
+    readonly actions: readonly DescribedAction[];
+    /** The views `read` takes, each with what it holds. */
+    readonly views?: Readonly<Record<string, string>>;
+    /** The surface's facts, as they stand now. */
+    readonly facts?: Readonly<Record<string, unknown>>;
+}
+/**
+ * What a headless session logs, one entry per thing that happened. Every entry has a `seq` (from
+ * 1, rising by one) and an `at` (an ISO time); `wait` is cursored by `seq`.
+ *
+ * @beta
+ */
+export type HeadlessEvent = HeadlessEventBase & (({
+    readonly type: 'decision';
+} & InteractionDescription & {
+    /** The agents that asked for it, outermost first. */
+    readonly ownerPath?: readonly string[];
+}) | {
+    readonly type: 'working';
+    readonly interactionId: string;
+    readonly component: string;
+    /** Who holds it; `'user'` when it is the person's but not ready yet. */
+    readonly heldBy: string;
+} | {
+    readonly type: 'settled';
+    readonly interactionId: string;
+    readonly component: string;
+    /** Who answered it; absent for a timeout, a stop, or one that settled by itself. */
+    readonly answeredBy?: string;
+    /** Set when the widget settled by itself and nobody answered. */
+    readonly resolvedItself?: boolean;
+    /** Set when the session settled it for a widget that settles itself in a browser. */
+    readonly auto?: boolean;
+    /** Set when the host settled it raw, bypassing the widget's actions. */
+    readonly raw?: boolean;
+} | {
+    readonly type: 'message';
+    /** One line of what the person would see, as the autopilot reads it ("Assistant: ..."). */
+    readonly text: string;
+    /** The line's full length, in characters, when `text` was cut. */
+    readonly chars?: number;
+} | {
+    readonly type: 'turn';
+    /** The driver's reason, `'done'` for a finished turn; `'error'` when it threw. */
+    readonly reason: string;
+    /** Set when the turn ended in a typed failure rather than completing. */
+    readonly failureReason?: string;
+    /** The assistant's final text for the turn, when it said any. */
+    readonly text?: string;
+    /** The text's full length, in characters, when `text` was cut. */
+    readonly chars?: number;
+} | {
+    readonly type: 'autopilot';
+    readonly mode: string;
+    readonly status: string;
+    readonly needsUser: boolean;
+    readonly working: boolean;
+    /** Why it is paused, when it said. */
+    readonly reason?: string;
+} | {
+    readonly type: 'probe';
+    /** What the host's probe reads now. */
+    readonly probe: Readonly<Record<string, unknown>>;
+    /** The keys whose values changed since the last entry. */
+    readonly changed: readonly string[];
+} | {
+    readonly type: 'error';
+    /** What failed: `'turn'`, `'auto-settle'`, `'probe'`, … */
+    readonly where: string;
+    readonly message: string;
+});
+/**
+ * The fields every {@link HeadlessEvent} has.
+ *
+ * @beta
+ */
+export interface HeadlessEventBase {
+    readonly seq: number;
+    /** When it was logged, as an ISO time. */
+    readonly at: string;
+}
+/**
+ * The type of a {@link HeadlessEvent}.
+ *
+ * @beta
+ */
+export type HeadlessEventType = HeadlessEvent['type'];
+/**
+ * Options for a {@link HeadlessSession}.
+ *
+ * @beta
+ */
+export interface HeadlessSessionOptions {
+    /** The debug-log key its meta events go under: the driver's own. Defaults to `''`. */
+    readonly sessionKey?: string;
+    /** What the host calls itself, recorded with `headless.attached`, e.g. `'cli'`. */
+    readonly label?: string;
+    /**
+     * Widgets that settle themselves in a browser when their element mounts, with no controller
+     * to act on, by widget type: each maps the widget's `data` to the result to settle it with.
+     * When one opens the session settles it with that result (once the open has completed), logs
+     * `settled` with `auto: true`, and never reports it as a `decision`.
+     */
+    readonly autoSettle?: Readonly<Record<string, (data: unknown) => unknown>>;
+    /** The widget tools `read({ tool })` may run, as for the autopilot. */
+    readonly widgetTools?: readonly WidgetTools[];
+    /**
+     * Host state shown in `state()` as `probe`, e.g. its app phase. Read again at every event; a
+     * change in any top-level value is logged as a `probe` event.
+     */
+    readonly probe?: () => Record<string, unknown>;
+    /** Whether `resolve` (settling an interaction raw) is allowed. Default `true`. */
+    readonly allowRaw?: boolean;
+    /**
+     * The autopilot, when the driver handed to the session is not itself one (a decorator wrapped
+     * over it hides it). Default: the driver, when it has the shape of an `AutopilotHost`.
+     */
+    readonly autopilot?: AutopilotLike;
+    /** The time source for `at`, in milliseconds. Default `Date.now`. */
+    readonly clock?: () => number;
+    /**
+     * Where the session is saved, as `headlessPersistence(...)` builds it: the same
+     * `sessions/<key>` snapshot and `diag/<key>` stream the browser writes. Absent: nothing is
+     * saved, and `debugLog()` is the current page's.
+     */
+    readonly persistence?: HeadlessPersistence;
+    /**
+     * What `debugLog()` reports of the host when nothing is persisted (with `persistence` its own
+     * options are used instead).
+     */
+    readonly debug?: HeadlessDebugOptions;
+    /**
+     * The bus the driver was built with (`ChatDriver`'s `activityBus` option), to hear turns end the
+     * moment they do, whoever started them. Without it a turn the session did not start is noticed
+     * by watching the driver's history and polling `isBusy()`, which is the slower route.
+     */
+    readonly activityBus?: Pick<AgenticActivityBus, 'subscribe'>;
+}
+/**
+ * What a debug log reports of the host that built it: the `meta` block's agents, state and host.
+ *
+ * @beta
+ */
+export interface HeadlessDebugOptions {
+    /** The configured agents, as the element's `agents` are. */
+    readonly agents?: () => readonly AgentConfig[];
+    /** The host's own debug state, shown as `meta.debug`. */
+    readonly debugState?: () => unknown;
+    /** The host name `meta.host` carries. The element's is `window.location.host`. Default `'headless'`. */
+    readonly host?: string;
+    /**
+     * The active model and its context window, which the element learns from the provider registry's
+     * status; the session has no registry, so the host says. Read each time they are needed.
+     */
+    readonly context?: () => {
+        model?: string;
+        contextLimit?: number;
+    } | undefined;
+}
+/**
+ * What a persistence binding is built from: the session's driver, and its debug-log key.
+ *
+ * @beta
+ */
+export interface HeadlessPersistenceHost {
+    readonly driver: AiDriver;
+    readonly sessionKey: string;
+}
+/**
+ * A session's saving, attached to a driver: it keeps what the persister reads current and asks it
+ * to save when the browser's element would. Built by `HeadlessPersistence.attach`.
+ *
+ * @beta
+ */
+export interface HeadlessPersistenceBinding {
+    /** Note the prompt a person is about to send, for the flow it may start (`flowActivationPrompt`). */
+    notePrompt(text: string): void;
+    /** Save the snapshot and append the diagnostics now, rather than at the next throttled flush. */
+    flush(): Promise<void>;
+    /** The debug log for the whole session, stitched from the stored stream (see `lifetimeDebugLog`). */
+    debugLog(): Promise<DebugLog>;
+    /** Stop watching the driver and cancel pending saves. The saved session is left as it is. */
+    dispose(): void;
+}
+/**
+ * Persistence for a {@link HeadlessSession}, as `headlessPersistence(...)` builds it. Lives apart
+ * from the session so that the session itself, and the Node entry that exports it, never reach the
+ * store, the persister or the framework they use.
+ *
+ * @beta
+ */
+export interface HeadlessPersistence {
+    /** The session key: the file under `sessions/` and the stream under `diag/`. */
+    readonly stateKey: string;
+    attach(host: HeadlessPersistenceHost): HeadlessPersistenceBinding;
+}
+/**
+ * The part of an `AutopilotHost` a session uses. `keepPaused` is optional, so a host built before it
+ * still fits; `autopilot('keepPaused')` says so when it is missing.
+ *
+ * @beta
+ */
+export type AutopilotLike = Pick<AutopilotHost, 'state' | 'subscribe' | 'pause' | 'resume' | 'stop'> & Partial<Pick<AutopilotHost, 'keepPaused'>>;
+/**
+ * What `send` may carry besides the words.
+ *
+ * @beta
+ */
+export interface HeadlessSendOptions {
+    readonly attachments?: ChatAttachment[];
+    /** Route the turn to this agent, as `SendMessageOptions.agent` does. */
+    readonly agent?: string;
+}
+/**
+ * What `act` is given besides the action: the arguments a person would fill in.
+ *
+ * @beta
+ */
+export interface HeadlessActArgs {
+    /** Written words, for an action that takes `text`, such as `reply`. */
+    readonly text?: string;
+    /** Options for `select`, by number or label. */
+    readonly options?: readonly string[];
+    /** A form's fields: an object, or JSON text of one. */
+    readonly fields?: unknown;
+}
+/**
+ * The result of `act`: the driver's, plus the interaction as it stands when it is still open.
+ *
+ * @beta
+ */
+export type HeadlessActResult = InvokeResult & {
+    /** The interaction after the action, when it is still pending. */
+    readonly description?: InteractionDescription;
+};
+/**
+ * What `read` asks for: a view of the widget, or one of the widget's tools (not both).
+ *
+ * @beta
+ */
+export interface HeadlessReadRequest {
+    /** A view's name, from the description's `views`. Absent (with no `tool`): the default read. */
+    readonly view?: string;
+    /** A widget tool's name, from `HeadlessSessionOptions.widgetTools`. */
+    readonly tool?: string;
+    /** The tool's arguments. */
+    readonly args?: Record<string, unknown>;
+}
+/**
+ * The result of `read`: what was read as text (capped), or why it was refused.
+ *
+ * @beta
+ */
+export type HeadlessReadResult = {
+    readonly ok: true;
+    readonly content: string;
+    readonly error?: never;
+} | {
+    readonly ok: false;
+    readonly content?: never;
+    readonly error: string;
+};
+/**
+ * What `wait` takes.
+ *
+ * @beta
+ */
+export interface HeadlessWaitRequest {
+    /**
+     * The cursor: the `seq` of the last event already seen. Events after it are returned. Absent:
+     * from the start of the log.
+     */
+    readonly since?: number;
+    /**
+     * The event types that end the wait. Default: `decision`, `turn`, `error`, and an `autopilot`
+     * entry that `needsUser`. One naming `autopilot` ends it on any autopilot entry.
+     */
+    readonly until?: readonly HeadlessEventType[];
+    /**
+     * The longest to wait, in milliseconds. Cut to what a timer can hold (about 24 days); a value that is
+     * not a number is no wait at all.
+     */
+    readonly maxWaitMs: number;
+    /** Ends the wait early, with status `'working'`, when it aborts: a caller that has gone away. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * What `wait` returns.
+ *
+ * @beta
+ */
+export interface HeadlessWaitResult {
+    /** Every event after `since`, up to now. */
+    readonly events: readonly HeadlessEvent[];
+    /**
+     * `'ready'`: an event the caller was waiting for is among them. `'working'`: none came in
+     * time. `'closed'`: the session was disposed.
+     */
+    readonly status: 'ready' | 'working' | 'closed';
+    /** The cursor to pass as `since` next time: the `seq` of the last event logged. */
+    readonly nextSeq: number;
+}
+/**
+ * Something else pending, besides the one `state().pending` describes.
+ *
+ * @beta
+ */
+export interface PendingSummary {
+    readonly interactionId: string;
+    readonly component: string;
+    readonly heldBy: string;
+    readonly ready: boolean;
+}
+/**
+ * What a headless session is doing now.
+ *
+ * @beta
+ */
+export interface HeadlessState {
+    /** Whether the driver is running a turn. */
+    readonly busy: boolean;
+    /** The oldest interaction the person holds and can act on, or `null`. */
+    readonly pending: InteractionDescription | null;
+    /** The other open interactions: a claimant's, or not ready yet, or behind the first. */
+    readonly others: readonly PendingSummary[];
+    /** The autopilot's state, when there is one. */
+    readonly autopilot?: {
+        readonly mode: string;
+        readonly status: string;
+        readonly needsUser: boolean;
+        readonly working: boolean;
+    };
+    /** What the conversation has cost so far, in `sumUsage`'s four buckets. */
+    readonly cost: AggregateUsage;
+    /** The host's probe, read now. */
+    readonly probe: Readonly<Record<string, unknown>>;
+    /** The `seq` of the last event logged: `wait`'s cursor. */
+    readonly lastSeq: number;
+}
+/**
+ * The input of {@link describeInteraction}: a pending interaction as the driver knows it.
+ *
+ * @beta
+ */
+export interface DescribeInteractionInput {
+    readonly ctx: InteractionContext;
+    readonly componentName: string;
+    readonly data: unknown;
+}
+/**
+ * The result of a call that may be refused: the reason, as words, in `error`.
+ *
+ * @beta
+ */
+export type HeadlessResult = {
+    readonly ok: true;
+    readonly error?: never;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+//# sourceMappingURL=headless.types.d.ts.map

package/dist/dts/headless/headless.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.types.d.ts","sourceRoot":"","sources":["../../../src/headless/headless.types.ts"],"names":[],"mappings":"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"}

package/dist/dts/headless/index.d.ts

@@ -0,0 +1,5 @@
+export { describeInteraction } from './describe-interaction';
+export { headlessCurrentDebugLog, headlessDiagnosticEntries, headlessMetaSnapshot, } from './headless-debug';
+export { HeadlessSession } from './headless-session';
+export type { AutopilotLike, DescribedAction, DescribeInteractionInput, HeadlessActArgs, HeadlessActResult, HeadlessDebugOptions, HeadlessEvent, HeadlessEventBase, HeadlessEventType, HeadlessPersistence, HeadlessPersistenceBinding, HeadlessPersistenceHost, HeadlessReadRequest, HeadlessReadResult, HeadlessResult, HeadlessSendOptions, HeadlessSessionOptions, HeadlessState, HeadlessWaitRequest, HeadlessWaitResult, InteractionDescription, PendingSummary, } from './headless.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/headless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/headless/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EACV,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,GACf,MAAM,kBAAkB,CAAC"}

package/dist/dts/headless-server/compact.d.ts

@@ -0,0 +1,52 @@
+import type { HeadlessEvent, InteractionDescription } from '../headless';
+import type { CompactDecision, CompactEvent, DecisionText } from './types';
+/** The first `lines` lines of `text`, at most `chars` characters, and its full length when it was cut. */
+export declare function firstLines(text: string, lines: number, chars: number): {
+    text: string;
+    chars?: number;
+};
+/** The keys of `source` that are set, as a new object: a field with nothing to say is dropped. */
+export declare function present<T extends Record<string, unknown>>(source: T): Partial<T>;
+export interface CompactOptions {
+    probeEvent?: {
+        name: string;
+        keys: readonly string[];
+    };
+}
+/**
+ * One session event, compact. `decision` and `working` are not reported as events: what the person is asked
+ * is the reply's `decision`, and what is working is its `working`. A message carries its first lines and
+ * its length; a probe event is the host's view of it (see `ServerOptions.probeEvent`).
+ */
+export declare function compactEvent(event: HeadlessEvent, options?: CompactOptions): CompactEvent | undefined;
+/**
+ * A decision's text without its `Now: <the preview view as JSON>` line, and nothing else (`decisionText:
+ * "lean"`). `renderDecision` writes the preview as `Now: ${capRead(JSON.stringify(view))}`: `JSON.stringify`
+ * with no indent never breaks a line, so the JSON is the one line, and `capRead` adds a second, `[Cut at …]`,
+ * only when it cut it. Both go; in their place is a pointer to `read`. The line is found by position, not
+ * by prefix alone: it follows the Views list, whose entry for the preview ends `(shown below as Now)`, so a
+ * card that itself has a line starting `Now: ` is not mistaken for it.
+ *
+ * The text comes back as it was when there is no preview to find (a card with no preview view, or a short-form
+ * decision, which shows no `Now:`), or when `views` does not name the one the Views list marks.
+ */
+export declare function leanDecisionText(text: string, views?: Readonly<Record<string, string>>): string;
+/**
+ * A decision as the reply carries it: what to read and what to choose from, and nothing empty. With
+ * `decisionText: "lean"` its `text` leaves out the preview view's JSON ({@link leanDecisionText}); nothing
+ * else about it changes.
+ */
+export declare function compactDecision(description: InteractionDescription, decisionText?: DecisionText): CompactDecision;
+/**
+ * A decision cut to what a caller who has already read the card needs: which interaction, and the actions as
+ * `n`, `name`, `enabled`. For the reply to an edit, and to a refused action, where the card has not changed
+ * enough to be worth sending again.
+ */
+export declare function shortDecision(interactionId: string, component: string, actions: ReadonlyArray<{
+    n?: number;
+    name: string;
+    enabled: boolean;
+}>): CompactDecision;
+/** What an editing action returned, as the reply carries it: whole when small, else its first characters. */
+export declare function capOutput(output: unknown): unknown;
+//# sourceMappingURL=compact.d.ts.map

package/dist/dts/headless-server/compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/headless-server/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAiB,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQ1F,0GAA0G;AAC1G,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAIlC;AAED,kGAAkG;AAClG,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQhF;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,cAAmB,GAC3B,YAAY,GAAG,SAAS,CA2D1B;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAsB/F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,sBAAsB,EACnC,YAAY,GAAE,YAAqB,GAClC,eAAe,CAyBjB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,GACrE,eAAe,CAUjB;AAKD,6GAA6G;AAC7G,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CASlD"}

package/dist/dts/headless-server/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Node-only entry point for the headless assistant protocol server
+ * (`@genesislcap/ai-assistant/headless-server`).
+ *
+ * The server speaks a small HTTP/JSON protocol over a {@link HeadlessSession}: one JSON command in,
+ * one compact JSON reply out. A coding agent or a script can drive an assistant journey with no
+ * browser. It uses `node:http` and `node:fs`, so it has an entry of its own, built for Node
+ * (`dist/headless-server.{mjs,cjs}`), and is never reachable from the package root
+ * (`src/index.ts`): a browser bundle must not see a `node:` import.
+ *
+ * It knows only a session and Node built-ins. Its imports of `../headless` are type-only, so the
+ * bundle carries no second copy of `HeadlessSession`: the session it is given comes from
+ * `@genesislcap/ai-assistant` (or `/chat-driver`), whichever the host built it with.
+ * `headless-server-entry.test.ts` holds all of this.
+ *
+ * @packageDocumentation
+ * @beta
+ */
+export { capOutput, compactDecision, compactEvent, firstLines, leanDecisionText, shortDecision, } from './compact';
+export { createHeadlessServer } from './server';
+export { DECISION_TEXTS, DEFAULT_DECISION_TEXT } from './types';
+export type { Command, CompactAction, CompactDecision, CompactEvent, Composer, DecisionText, ExtraOp, ExtraOpResult, HeadlessServer, HeadlessServerHandle, Reply, ServerOptions, Status, WorkingInfo, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/headless-server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/headless-server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,SAAS,EACT,eAAe,EACf,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChE,YAAY,EACV,OAAO,EACP,aAAa,EACb,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,KAAK,EACL,aAAa,EACb,MAAM,EACN,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/dist/dts/headless-server/server.d.ts

@@ -0,0 +1,13 @@
+import { type HeadlessServer, type ServerOptions } from './types';
+/**
+ * The headless server (PLAN §5, D7): `node:http` on 127.0.0.1, `GET /health` and `POST /cmd`.
+ *
+ * Every command is APPLIED and then LONG-POLLS (§5.5): the reply comes when the journey next needs the
+ * person (an interaction is held by them and ready), a turn ends, the run ends, or something fails, or at
+ * `maxWaitMs` with `status: "working"`. Nothing is lost on a client timeout: the command was applied before
+ * the wait, events carry `seq`, and `{op: "wait", since}` returns everything after it.
+ *
+ * The session is the only thing it drives; what the host owns is reached through {@link ServerOptions}.
+ */
+export declare function createHeadlessServer(options: ServerOptions): HeadlessServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/dts/headless-server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/headless-server/server.ts"],"names":[],"mappings":"AAeA,OAAO,EAQL,KAAK,cAAc,EAEnB,KAAK,aAAa,EAGnB,MAAM,SAAS,CAAC;AAqEjB;;;;;;;;;GASG;AAEH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CAiwB3E"}