@cairnvibe/sdk 0.2.13 → 0.4.0

package/dist/server.d.ts

@@ -1,5 +1,8 @@
-import { type HistoryTurn, type LiveElement, type Manifest, type VerbResponse, type WebMcpTool } from "@cairnvibe/core";
+import { type CriticVerdict, type HistoryTurn, type LiveElement, type Manifest, type Plan, type Skill, type SkillSummary, type Task, type UiPatternId, type VerbResponse, type WebMcpTool } from "@cairnvibe/core";
+import { type MemoryStore } from "./memory-sqlite";
+export { KeyRotator } from "./key-rotator";
 import { KeyRotator } from "./key-rotator";
+import type { SkillStore } from "./skill-store";
 /**
  * What the agent is allowed to do, independent of which specific "do"
  * actions are registered:
@@ -14,13 +17,69 @@ export interface CreateCopilotHandlerOptions {
     /** Single API key. For groq, prefer `apiKeys` to round-robin; falls back to GROQ_API_KEYS env. */
     apiKey?: string;
     apiKeys?: string[];
+    /**
+     * A pre-built rotator to share across multiple LLM roles (verb, plan,
+     * critic) instead of each one building its own from `apiKeys`/`apiKey`/
+     * env. Real, live-found gap this closes: createVerbLLM/createPlanLLM/
+     * createCriticLLM each called createToolLLM independently, and each one
+     * built a BRAND NEW KeyRotator from the same GROQ_API_KEYS list — so a
+     * key one of them confirmed dead via a real 401 (KeyRotator.markDead)
+     * stayed invisible to the other two, which went on rediscovering the
+     * exact same dead key from scratch on every one of their own calls,
+     * wasting real round trips and, worse, stacking up wasted attempts
+     * against the SAME small number of retries each call is bounded to.
+     * Takes precedence over `apiKeys`/`apiKey`/env when provided. See
+     * groq-llm.ts in examples/demo-app for the intended usage: build one
+     * KeyRotator at module scope, pass it to all three createXLLM calls.
+     */
+    keyRotator?: KeyRotator;
     model?: string;
     /** Action ids this deployment actually supports. "do" is refused for anything else. */
     registeredActions?: string[];
+    /**
+     * Phase 4, layer 5 — real, human-written descriptions for `registeredActions`
+     * ids, e.g. `{ archiveInvoice: "Archives the invoice; cannot be undone." }`.
+     * Optional and purely additive: an id with no entry here still works
+     * exactly as before (rendered bare, no description) — this was the
+     * weakest-typed of Cairn's three action-invocation mechanisms (a
+     * registered action id carried literally zero server-visible metadata,
+     * unlike a WebMCP tool's own description or an element's `does` text);
+     * this closes that gap without changing what the model must echo back
+     * in "action" (still the bare id — see renderRegisteredActions).
+     */
+    actionDescriptions?: Record<string, string>;
     /** What the agent is allowed to do at all. Defaults to "act". See `CapabilityTier`. */
     capability?: CapabilityTier;
     /** Display name / identity for the agent, woven into its system prompt and shown in the widget. Defaults to "Cairn". */
     persona?: string;
+    /**
+     * Phase 5 step 4 — real cross-session memory for the typed/HTTP
+     * transport (packages/sdk/src/memory-sqlite.ts, or any store
+     * implementing the same interface). Optional — omitting it keeps
+     * every request exactly as memory-less as before this existed.
+     * Scoped by whatever `scopeId` string the request itself carries
+     * (`CopilotRequestSchema.scopeId`) — this SDK invents no identity of
+     * its own. Unlike the realtime relay (one persistent connection
+     * remembers a scopeId once), this transport is stateless per
+     * request: `resolveVerb`'s own callers seed from memory only when the
+     * REQUEST's own `history` arrives empty (a genuinely fresh session —
+     * see `createCopilotHandlerWithLLM`), never on every request, so a
+     * session already accumulating its own history client-side isn't
+     * re-seeded on top of itself.
+     */
+    memory?: MemoryStore;
+    /**
+     * Architecture Pillar 3 (Skill half) — real, per-deployment Skill
+     * storage (packages/sdk/src/skill-store.ts). A DIFFERENT scope axis
+     * than `memory` above — see skill-store.ts's own doc comment. Optional;
+     * omitting it keeps every request exactly as it was before this
+     * existed. Consumed by `createPlanHandler` (retrieval — a matching
+     * Skill's full instructions get surfaced to the Planner) and
+     * `createSkillSaveHandler` (the Formulator's own save side).
+     */
+    skills?: SkillStore;
+    /** The deployment-wide scope Skills are stored/looked up under when `skills` is configured. Defaults to "default" when omitted. */
+    skillsScopeId?: string;
 }
 export interface CopilotHandlerResult {
     status: number;
@@ -52,6 +111,8 @@ export declare function createCopilotHandlerWithLLM(manifest: Manifest, llm: Ver
     registeredActions?: string[];
     capability?: CapabilityTier;
     persona?: string;
+    actionDescriptions?: Record<string, string>;
+    memory?: MemoryStore;
 }): CopilotHandler;
 /**
  * The safety-critical core, shared by the HTTP handler above and the
@@ -67,15 +128,184 @@ export declare function resolveVerb(llm: VerbLLM, systemPrompt: string, manifest
     liveElements?: LiveElement[];
     webMcpTools?: WebMcpTool[];
 }): Promise<VerbResponse>;
+/**
+ * Phase 3, step 2 (see DEVELOPMENT.md/the plan file) — the Planner half
+ * of the Planner/Executor/Critic/Talker redesign. Decomposes a real end
+ * goal into an ordered task list BEFORE any execution happens, mirroring
+ * resolveVerb's own resilience discipline: never throws to the caller,
+ * degrades to a real, usable single-task fallback plan on any failure
+ * (a bad LLM response, a schema mismatch, a network error) rather than
+ * blocking the turn on a Planner hiccup. `version`/each task's `status`
+ * are harness-owned, not asked of the model (PlannerOutputSchema's own
+ * doc comment) — assembled here around the model's raw output.
+ *
+ * Deliberately does NOT yet change what the loop actually does with the
+ * result — step 2's own scope is observability only (see the doc comment
+ * on this function's call site in realtime-server.ts). The Critic (step
+ * 3) is what makes a Plan's tasks/doneContracts actually drive behavior.
+ */
+export declare function resolvePlan(llm: VerbLLM, goal: string, version?: number, manifest?: Manifest, actionsText?: string, skills?: {
+    summariesText?: string;
+    suggestedInstructions?: string;
+}): Promise<Plan>;
+/** The real, single-task plan used when the Planner call itself fails —
+ * "do the whole goal as one task" is always a valid (if unstructured)
+ * plan, so a Planner hiccup degrades the redesign back to today's
+ * behavior instead of blocking the turn. Exported so every caller that
+ * needs "a plan, even a trivial one, right now" (e.g. a Critic call that
+ * fires before a real Planner result has come back) builds the exact
+ * same shape instead of hand-rolling a duplicate literal — realtime-
+ * server.ts's own finalizeTurn and index.tsx's runTypedAgentLoop both do
+ * this, for the same reason. */
+export declare function fallbackPlan(goal: string, version: number): Plan;
+/**
+ * Phase 3, step 3 — the Critic. A genuinely SEPARATE pass over the
+ * step's real observation, decoupled from the Executor/model's own
+ * self-report — this is the direct fix for the diagnosed bug (a batch
+ * of 2 clicks succeeded, and the model kept looping 4 more iterations
+ * before giving up, never recognizing its own success). Mirrors
+ * packages/evals/src/judge.ts's own judgeScenario shape on purpose (a
+ * separate model looking at real state, forced tool call, structured
+ * verdict) — same real precedent already proven and tested in this repo,
+ * not a new pattern invented for this. Same resilience discipline as
+ * resolveVerb/resolvePlan: never throws, degrades to a real "continue"
+ * verdict (harmless — the loop just behaves as if the Critic weren't
+ * there for this one step) on any failure.
+ */
+export declare function resolveCritic(llm: VerbLLM, task: Task, goal: string, verb: VerbResponse, observation: string | null | undefined): Promise<CriticVerdict>;
+/** Same real rotation/model-selection logic as createVerbLLM/createPlanLLM,
+ * configured for the Critic's own tool instead — see resolveCritic. */
+export declare function createCriticLLM(options?: CreateCopilotHandlerOptions): VerbLLM;
 /** Builds the provider-appropriate VerbLLM from the same options createCopilotHandler accepts — reused by the realtime relay. */
 export declare function createVerbLLM(options?: CreateCopilotHandlerOptions): VerbLLM;
+/** Same real rotation/model-selection logic as createVerbLLM, configured
+ * for the Planner's own tool instead — see resolvePlan. */
+export declare function createPlanLLM(options?: CreateCopilotHandlerOptions): VerbLLM;
+/**
+ * Architecture Pillar 3 (Skill half) — the Formulator. Runs once a task
+ * genuinely completes (not per-step — cheap on purpose, matching the plan
+ * file's own framing), compiling whatever real, Critic-verified
+ * `learnedFact`s were collected along the way (CriticVerdictSchema's own
+ * doc comment is the enforcement point for "never user data") into one
+ * Skill. Deliberately DETERMINISTIC, not a fourth kind of real LLM call —
+ * every fact it compiles already passed through the Critic's own
+ * verification, so there's nothing left to "figure out" that would
+ * justify the added cost/latency/failure surface of another model round
+ * trip; see DEVELOPMENT.md's own entry for the real cost reasoning
+ * (this session already hit genuine Groq quota exhaustion more than once
+ * from cumulative call volume). Returns null when nothing was learned —
+ * the common case, not an error; a caller should simply not save anything.
+ */
+export declare function compileSkill(goal: string, learnedFacts: string[], pattern?: UiPatternId): Skill | null;
+/**
+ * Architecture Pillar 3 (Skill half) — the retrieval side. A cheap,
+ * deterministic keyword-overlap match against a NEW goal (never another
+ * real LLM call, same reasoning as compileSkill above) — real progressive
+ * disclosure: every Skill's summary is cheap enough to always list (see
+ * SkillStore's own doc comment), but only the ONE Skill whose own name
+ * shares real, significant words with the current goal gets its full
+ * instructions loaded. A caller still needs its own SkillStore.getSkill
+ * call to fetch those full instructions for whatever this returns — this
+ * function only ever sees cheap summaries, never a full Skill.
+ */
+export declare function matchSkillByGoal(summaries: SkillSummary[], goal: string): SkillSummary | null;
+/** Same rendering discipline as renderRegisteredActions — "id (description)" per Skill, for the Planner's own userMessage. */
+export declare function renderSkillSummaries(summaries: SkillSummary[]): string;
+export type PlanHandler = (body: unknown) => Promise<{
+    status: number;
+    body: Plan | {
+        error: string;
+    };
+}>;
+export type CriticHandler = (body: unknown) => Promise<{
+    status: number;
+    body: CriticVerdict | {
+        error: string;
+    };
+}>;
+/**
+ * Architecture Pillar 4 — the typed/HTTP transport's own real Planner
+ * endpoint, closing the gap the plan file names directly: "the typed/
+ * HTTP path (index.tsx's runTypedAgentLoop) has zero Planner/Critic
+ * wiring at all... today explicitly realtime-only by deferral, not by
+ * decision." A thin HTTP wrapper around the exact same resolvePlan the
+ * realtime relay already calls in-process — the LLM call itself only
+ * ever needs to happen server-side (it holds the real API key), so a
+ * client-side caller (index.tsx) reaches it over a real request instead
+ * of importing resolvePlan directly, same reasoning as createCopilotHandler
+ * itself.
+ */
+export declare function createPlanHandler(manifest: Manifest, options?: CreateCopilotHandlerOptions): PlanHandler;
+/** Same as createPlanHandler, but with the LLM injected — used by tests to fake it, same pattern as createCopilotHandlerWithLLM. */
+export declare function createPlanHandlerWithLLM(manifest: Manifest, planLLM: VerbLLM, options?: {
+    registeredActions?: string[];
+    actionDescriptions?: Record<string, string>;
+    skills?: SkillStore;
+    skillsScopeId?: string;
+}): PlanHandler;
+/** Architecture Pillar 4's Critic counterpart to createPlanHandler — see
+ * its own doc comment. A thin HTTP wrapper around the same resolveCritic
+ * the realtime relay already calls in-process. */
+export declare function createCriticHandler(options?: CreateCopilotHandlerOptions): CriticHandler;
+/** Same as createCriticHandler, but with the LLM injected — used by tests to fake it. */
+export declare function createCriticHandlerWithLLM(criticLLM: VerbLLM): CriticHandler;
+export type SkillSaveHandler = (body: unknown) => Promise<{
+    status: number;
+    body: {
+        saved: boolean;
+    } | {
+        error: string;
+    };
+}>;
+/**
+ * Architecture Pillar 3 (Skill half) — the typed transport's own save
+ * side (the Formulator's HTTP counterpart to realtime-server.ts's own
+ * in-process `compileSkill`+`saveSkill` call at the end of `finalizeTurn`).
+ * No LLM involved — `compileSkill` is deterministic (see its own doc
+ * comment for why) — so this needs no `-WithLLM` variant; it's real
+ * client-callable storage access, nothing more. The caller (index.tsx's
+ * runTypedAgentLoop) accumulates `learnedFacts` from its own Critic calls
+ * across one whole turn and posts here exactly once, after the turn
+ * concludes — never per-step, matching the Formulator's own "cheap on
+ * purpose" framing.
+ */
+export declare function createSkillSaveHandler(skills: SkillStore, skillsScopeId?: string): SkillSaveHandler;
+/**
+ * Phase 2 step 1 — a genuinely UNSTRUCTURED, streamed call: no tools, no
+ * forced choice, just the model's plain spoken answer to the user's
+ * question, delivered incrementally. Exists because a real, live spike
+ * against Groq's actual API (see DEVELOPMENT.md/the plan file's Phase 2
+ * entry) found that a FORCED tool call never streams at the field level
+ * even with stream:true — the whole structured object arrives in one
+ * chunk. Plain, unforced generation genuinely streams token-by-token on
+ * both providers, and finishes faster besides — this is what makes "LLM
+ * tokens streamed straight into TTS" possible at all.
+ */
+export interface StreamingTextLLM {
+    respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string>;
+}
 export declare class AnthropicVerbLLM implements VerbLLM {
     private client;
     private model;
     private toolSchema;
-    constructor(client: MessagesClient, model: string, toolSchema: Record<string, unknown>);
+    private toolName;
+    private toolDescription;
+    constructor(client: MessagesClient, model: string, toolSchema: Record<string, unknown>, toolName?: string, toolDescription?: string);
     respond(systemPrompt: string, userMessage: string): Promise<unknown>;
 }
+/** Minimal shape AnthropicStreamingTextLLM needs — narrow enough to fake in tests (a plain async generator, no real SDK stream class). */
+export interface StreamingMessagesClient {
+    messages: {
+        create: (params: any) => Promise<AsyncIterable<any>>;
+    };
+}
+/** No tools, no tool_choice — see StreamingTextLLM's own doc comment for why plain, unforced generation is what streams. */
+export declare class AnthropicStreamingTextLLM implements StreamingTextLLM {
+    private client;
+    private model;
+    constructor(client: StreamingMessagesClient, model: string);
+    respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string>;
+}
 /** Minimal shape GroqVerbLLM needs — narrow enough to fake in tests. */
 export interface GroqLikeClient {
     chat: {
@@ -91,11 +321,42 @@ export declare class GroqVerbLLM implements VerbLLM {
     private model;
     private toolSchema;
     private clientFactory;
-    constructor(keys: KeyRotator, model: string, toolSchema: Record<string, unknown>, clientFactory?: (apiKey: string) => GroqLikeClient);
+    private toolName;
+    private toolDescription;
+    constructor(keys: KeyRotator, model: string, toolSchema: Record<string, unknown>, clientFactory?: (apiKey: string) => GroqLikeClient, toolName?: string, toolDescription?: string);
     respond(systemPrompt: string, userMessage: string): Promise<unknown>;
     private attemptRespond;
 }
-export declare function buildVerbToolSchema(registeredActions: string[]): Record<string, unknown>;
+/** Minimal shape GroqStreamingTextLLM needs — narrow enough to fake in tests (a plain async generator, no real SDK stream class). */
+export interface GroqLikeStreamingClient {
+    chat: {
+        completions: {
+            create: (params: any) => Promise<AsyncIterable<any>>;
+        };
+    };
+}
+/** No tools, no tool_choice — see StreamingTextLLM's own doc comment for why plain, unforced generation is what streams. No retry-on-hallucinated-tool-name logic here (GroqVerbLLM's own real, live-found bug) — there's no tool to hallucinate the name of. */
+export declare class GroqStreamingTextLLM implements StreamingTextLLM {
+    private keys;
+    private model;
+    private clientFactory;
+    constructor(keys: KeyRotator, model: string, clientFactory?: (apiKey: string) => GroqLikeStreamingClient);
+    respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string>;
+}
+/**
+ * Phase 4, layer 5 — the ONE place a registered action id is rendered
+ * with its (optional) real description, shared by buildVerbToolSchema,
+ * buildSystemPrompt's own do-verb text, and resolvePlan's userMessage —
+ * so the Executor and the Planner describe the exact same capability the
+ * exact same way, and there's no risk of the three drifting out of sync.
+ * Deliberately renders "id (description)" rather than baking the
+ * description into what the model must echo back — resolveVerb's own
+ * `registeredActions.includes(parsedVerb.data.action)` check (server.ts)
+ * needs the RAW id back, verbatim, or a real registered action would
+ * silently stop being recognized.
+ */
+export declare function renderRegisteredActions(registeredActions: string[], actionDescriptions?: Record<string, string>): string;
+export declare function buildVerbToolSchema(registeredActions: string[], actionDescriptions?: Record<string, string>): Record<string, unknown>;
 /**
  * A compact route directory — NOT every element on every page. Found live
  * and necessary, not theoretical: a real 17-page production app's full
@@ -111,4 +372,4 @@ export declare function buildVerbToolSchema(registeredActions: string[]): Record
  * element detail is attached separately, per request, in resolveVerb —
  * see buildPageElements.
  */
-export declare function buildSystemPrompt(manifest: Manifest, registeredActions: string[], persona?: string): string;
+export declare function buildSystemPrompt(manifest: Manifest, registeredActions: string[], persona?: string, actionDescriptions?: Record<string, string>): string;