@jigs.design/server 0.0.0-stage → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,481 @@
+import { Advice, DesignCheckCode, Placement } from "./design.js";
+import { ConfirmationStore } from "./confirm.js";
+import { EditFailureReason } from "@jigs.design/compiler";
+import { PromptMode } from "@jigs.design/prompt";
+import { ActionDefinition, CallPolicy, Catalog, Host, InputOf, MutationDefinition, OutputOf, ProcedureDefinition, Procedures } from "@jigs.design/host";
+import { ChatBlock, ChatBlockStatus, Diagnostic, Invalidation, Message, PickleErrorData, Program, SessionEvent } from "@jigs.design/runtime";
+import { z } from "zod";
+//#region src/types.d.ts
+/**
+ * Tokens a model call used. The cache counts are part of `inputTokens`,
+ * and only there when the provider reports them: input read from its
+ * prompt cache, and input written to it.
+ */
+export interface Usage {
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+/**
+ * Why the server calls `model`: a session turn's answer, a repair round in a
+ * session, or the repair of a chat block that closed with errors.
+ */
+export type ModelRequestKind = "chat-repair" | "repair" | "session";
+export interface ModelRequest<TContext, TOptions> {
+  ctx: TContext;
+  kind: ModelRequestKind;
+  /** The conversation, with the server's repair turns added. */
+  messages: ReadonlyArray<Message>;
+  options: TOptions;
+  signal: AbortSignal;
+  /** The document prompt rendered from the host, with the server's `instructions`. */
+  system: string;
+  /**
+   * The start of `system` that is the same on every turn: the language and
+   * the catalog, before the instructions and procedures. Mark it for a
+   * provider's prompt cache, as `aiSdkModel` does.
+   */
+  systemPrefix: string;
+}
+/**
+ * The product's call to its LLM. Yield text as it arrives. A generator may
+ * return `{ usage }`, which reaches `onTurn`.
+ */
+export type ModelFunction<TContext, TOptions> = (request: ModelRequest<TContext, TOptions>) => AsyncIterable<string>;
+/** What became of a reply written as SEARCH/REPLACE edits. */
+export interface TurnEdits {
+  /** False when an edit did not apply, so the reply was not used. */
+  applied: boolean;
+  /** The complete edit blocks in the reply. */
+  blocks: number;
+  /**
+   * Why the first edit that failed did: its SEARCH text is not in the
+   * source (`"missing"`) or is there more than once (`"ambiguous"`), the
+   * block is broken (`"malformed"`), or the edit left a tag unclosed or
+   * closed one twice (`"broken"`).
+   */
+  reason?: EditFailureReason;
+}
+/** One reply from `model` in a turn, and what came of it. */
+export interface TurnRound {
+  /**
+   * The design checks' advice after this round, numbered like
+   * `diagnostics`. It never makes the round invalid; empty when an edit
+   * failed to apply.
+   */
+  advice: ReadonlyArray<Advice>;
+  /**
+   * The diagnostics after this round, before any later repair, numbered by
+   * the lines of the sent source. Empty when an edit failed to apply, since
+   * nothing compiled.
+   */
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /** Set when the reply was SEARCH/REPLACE edits. */
+  edits?: TurnEdits;
+  /**
+   * "answer" for the model's reply to the user, "repair" for each round
+   * after it. Every round of a "chat-repair" turn is a repair: the reply
+   * that wrote the block was the answer.
+   */
+  kind: "answer" | "repair";
+  /**
+   * Set when the server rewrote the reply instead of asking for a repair.
+   * `diagnostics` and `advice` are then those of the rewritten source,
+   * which is what the turn stores.
+   */
+  rewrites?: ReadonlyArray<TurnRewrite>;
+  /** This round's tokens, when `model` returned them; zeros otherwise. */
+  usage: Usage;
+}
+/**
+ * A change the server made to the model's source in place of a repair round:
+ * `use_before_declare`, markup above the `{@body}` lines whose names it
+ * reads, moved those lines to the top. The program is unchanged.
+ */
+export interface TurnRewrite {
+  /** The diagnostic the rewrite answered. */
+  code: "use_before_declare";
+  /**
+   * How many of the page's `{@body}` lines moved: to the top from below
+   * markup, including from tags such as `<card>`, or within the top.
+   */
+  moved: number;
+}
+export interface Turn<TContext, TOptions> {
+  /** The design checks' advice on the source sent with `done`; empty when the turn did not finish. */
+  advice: ReadonlyArray<Advice>;
+  /** False when the turn was stopped or failed before `done`. */
+  completed: boolean;
+  ctx: TContext;
+  /** The diagnostics sent with `done`; empty when the turn did not finish. */
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /**
+   * Milliseconds from the start of the turn to its first `program` event;
+   * null when it sent none. A chat repair sends its block once, when it is
+   * done, so for one this is the time to the repaired block.
+   */
+  firstProgramMs: number | null;
+  /** A session turn, or the repair of a chat block, which is a turn of its own. */
+  kind: "chat-repair" | "session";
+  messages: ReadonlyArray<Message>;
+  options: TOptions;
+  /**
+   * Rounds after the first: repairs of errors, and requests for the whole
+   * document after an edit failed. `rounds` tells them apart.
+   */
+  repairs: number;
+  /**
+   * Every reply `model` finished in this turn, in order. A reply cut off by
+   * a stop or a failure is not a round.
+   */
+  rounds: ReadonlyArray<TurnRound>;
+  /** The checked source sent with `done`, with its pragma; null when the turn did not finish. */
+  source: string | null;
+  usage: Usage;
+}
+export interface CallContext<TContext> {
+  ctx: TContext;
+  signal: AbortSignal;
+}
+/**
+ * A value as `run` may return it: readonly all the way down, so a frozen or
+ * readonly array is fine. The output schema parses it either way.
+ */
+type DeepReadonly<T> = T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
+/** What `run` may return for a procedure. */
+type RunOutput<P extends ProcedureDefinition> = DeepReadonly<OutputOf<P>>;
+/**
+ * One function per query and mutation. Actions have none: the page handles
+ * them, and the server only checks their input.
+ */
+export type RunFunctions<TProcedures extends Procedures, TContext> = { readonly [K in keyof TProcedures as TProcedures[K] extends ActionDefinition ? never : K]: (input: InputOf<TProcedures[K]>, call: CallContext<TContext>) => RunOutput<TProcedures[K]> | Promise<RunOutput<TProcedures[K]>>; };
+export type ContextFunction<TContext> = (request: Request) => TContext | Promise<TContext>;
+/** The names of a host's mutations. */
+type MutationName<TProcedures extends Procedures> = { [K in keyof TProcedures & string]: TProcedures[K] extends MutationDefinition ? K : never; }[keyof TProcedures & string];
+/**
+ * A mutation call the server's `policy` option decides on, one member per
+ * mutation, so checking `name` narrows `input`.
+ */
+export type PolicyCall<TProcedures extends Procedures, TContext> = { [K in MutationName<TProcedures>]: {
+  ctx: TContext;
+  /** The input its schema parsed; `undefined` when it takes none. */
+  input: InputOf<TProcedures[K]>;
+  name: K;
+}; }[MutationName<TProcedures>];
+/**
+ * How a call ended, for `onCall`. A confirmed mutation reports twice: once
+ * as "requires-action" when the server asks the page, and once as
+ * "confirmed" when it ran with the user's approval.
+ */
+export type CallReportOutcome = "confirmed" | "denied" | "error" | "requires-action" | "success";
+/** One call to a query, mutation or action, as `onCall` receives it. */
+export interface CallReport<TContext> {
+  ctx: TContext;
+  /** From the call's arrival to its outcome, in milliseconds. */
+  durationMs: number;
+  /** What the browser received, when `outcome` is not "success". */
+  error?: PickleErrorData;
+  /**
+   * The parsed input, or the input as the browser sent it when the call
+   * failed before its input parsed.
+   */
+  input: unknown;
+  /** The kind the call declared. */
+  kind: ProcedureDefinition["kind"];
+  name: string;
+  /**
+   * "denied" when a policy or a bad confirmation refused the call, "error"
+   * for any other failure, including one `run` threw.
+   */
+  outcome: CallReportOutcome;
+}
+export interface ErrorInfo {
+  /** The procedure, for a call. */
+  name?: string;
+  /** The request it came from: a call, a session turn, or a chat turn with its repairs. */
+  type: "call" | "chat" | "session";
+}
+/**
+ * `TContext` is inferred from `context`; `run` only reads it (`NoInfer`), so
+ * a mistake in one `run` function is reported at that function.
+ */
+export interface PickleServerOptions<TProcedures extends Procedures, TCatalog extends Catalog, TContext, TOptions, TSpecName extends string = never> {
+  /** Origins whose views may call this server and embed its frame. */
+  allowedOrigins?: ReadonlyArray<string>;
+  /**
+   * Where used confirmation tokens are recorded. The default keeps them in
+   * this process's memory, so it is only valid for one server process;
+   * behind a load balancer, pass a shared store.
+   */
+  confirmations?: ConfirmationStore;
+  /**
+   * Who a confirmation token is for, from `ctx`, such as the user's id. A
+   * token only works for the subject it was issued to. Required with
+   * `secret`.
+   */
+  confirmSubject?: (ctx: NoInfer<TContext>) => string;
+  /**
+   * What every call and turn receives as `ctx`, from the request: usually
+   * the signed-in user. Required; a server with none writes `() => undefined`.
+   */
+  context: ContextFunction<TContext>;
+  /**
+   * Design checks whose advice gets a repair round, as errors do: at most
+   * one per turn or chat block, within `maxRepairs`. Default none, since a
+   * repair round is a full model call.
+   */
+  designRepair?: ReadonlyArray<DesignCheckCode>;
+  host: Host<TProcedures, TCatalog>;
+  /**
+   * The app's own instructions to the model, such as its persona, today's
+   * date or its safety rules. Every prompt carries them: document-mode
+   * sessions, `prompt("chat")`, and the repairs of both.
+   */
+  instructions?: string;
+  /** The largest request body accepted, in bytes. Default 1,000,000. */
+  maxBodyBytes?: number;
+  /** Repair rounds after a turn that ends with errors. Default 1. */
+  maxRepairs?: number;
+  model?: ModelFunction<TContext, TOptions>;
+  /** The clock confirmation tokens expire by, in ms since the epoch. Default `Date.now`. */
+  now?: () => number;
+  /**
+   * Runs after every call to a query, mutation or action, including ones
+   * refused before `run`. The response does not wait for it, and a value it
+   * throws or rejects with goes to `onError`.
+   */
+  onCall?: (call: CallReport<NoInfer<TContext>>) => Promise<void> | void;
+  onError?: (cause: unknown, info: ErrorInfo) => void;
+  onTurn?: (turn: Turn<TContext, TOptions>) => Promise<void> | void;
+  /** Schema for the app options sent with each turn. */
+  options?: z.ZodType<TOptions>;
+  /** This server's origin, when the request URL does not show it (behind a proxy). */
+  origin?: string;
+  /**
+   * Decides a mutation call's policy from its `ctx` and parsed input, after
+   * the input parses and before `run`; `undefined` keeps the host's. A
+   * value it throws goes to `onError`, and the call is denied.
+   */
+  policy?: (call: PolicyCall<NoInfer<TProcedures>, NoInfer<TContext>>) => CallPolicy | undefined;
+  /**
+   * While a reply streams, the least time between two program updates, in
+   * ms. Each update carries the whole program, so a long reply that changed
+   * it at every line sent it hundreds of times. The first program goes out
+   * at once, a newer one replaces one still waiting, and the reply's last
+   * program always goes out. Default 250; 0 sends every change.
+   */
+  programIntervalMs?: number;
+  run: RunFunctions<NoInfer<TProcedures>, NoInfer<TContext>>;
+  /**
+   * Signs confirmation tokens, at least 32 characters; keep it out of the
+   * browser. Required, with `confirmSubject`, when a mutation's policy is
+   * "confirm": the server refuses to start without it.
+   */
+  secret?: string;
+  /**
+   * Stored specs by name, compiled once at startup. A diagnostic worse than
+   * info stops the server, as a bad recipe does. Read one with `spec(name)`.
+   */
+  specs?: Readonly<Record<TSpecName, string>>;
+}
+export interface CompileOptions {
+  /**
+   * Where the UI sits, for the design checks: a whole document (default),
+   * or a block of a chat reply, which also counts its actions.
+   */
+  placement?: Placement;
+  /**
+   * Throw a `PickleCompileError` when the source has an error or warning
+   * diagnostic. Default true; pass false to get the program and the
+   * diagnostics instead, as a session turn does.
+   */
+  strict?: boolean;
+}
+/**
+ * What one call returns: the parsed output, or an error the browser may see.
+ * A mutation's also lists the queries it refreshed (`invalidate`).
+ */
+export type CallOutcome = {
+  data: unknown;
+  invalidate?: ReadonlyArray<Invalidation>;
+} | {
+  error: PickleErrorData;
+} | {
+  requiresAction: RequiresAction;
+};
+/**
+ * The first answer to a call whose policy is "confirm": the mutation has
+ * not run. The page shows `message` and, when the user approves, sends the
+ * call again with `token` as `confirmation`.
+ */
+export interface RequiresAction {
+  /** What to ask the user, written by the host. */
+  message: string;
+  /** Single use, bound to this call and subject, valid for five minutes. */
+  token: string;
+}
+export interface CallRequest {
+  /** The token from a `requiresAction` answer, once the user approved. */
+  confirmation?: string;
+  /** Plain JSON from the browser; parsed with the procedure's input schema. */
+  input?: unknown;
+  /**
+   * The procedure's kind, as the program's procedure table declares it. A
+   * call whose kind is not the host's is refused with `BAD_INPUT`.
+   */
+  kind: ProcedureDefinition["kind"];
+  name: string;
+}
+export interface SessionRequest {
+  /** Plain JSON from the browser; parsed with the messages schema. */
+  messages: unknown;
+  /** Plain JSON from the browser; parsed with the `options` schema. */
+  options?: unknown;
+}
+/** An earlier block of the conversation, as the chat stored it. */
+export interface ChatBlockSource {
+  id: string;
+  /** Its checked source; with or without the pragma line. */
+  source: string;
+}
+/**
+ * One block of a chat reply and what came of it, from `ChatTurn.results`:
+ * enough to count first-pass failures, failed edits and repairs.
+ */
+export interface ChatBlockResult {
+  /**
+   * The design checks' advice on the block as the reply closed it, numbered
+   * like `diagnostics`; empty when `diagnostics` is. A repair's rounds
+   * carry their own.
+   */
+  advice: ReadonlyArray<Advice>;
+  /**
+   * The block's diagnostics as the reply closed it, before any repair,
+   * numbered by the lines of its source. Empty when it has `error` or an
+   * edit that did not apply.
+   */
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /** Set when the block was SEARCH/REPLACE edits to an earlier block. */
+  edits?: TurnEdits;
+  /**
+   * Set when the block is done without a program of its own: an edit to an
+   * id the conversation does not have (`NOT_FOUND`), a block past the
+   * reply's limit (`RATE_LIMITED`), or an edit or repair that failed
+   * (`INTERNAL`). The same error the block carries.
+   */
+  error?: PickleErrorData;
+  /** False for Pickle the model wrote without a fence. */
+  fenced: boolean;
+  id: string;
+  key: string;
+  /**
+   * The rounds of the block's repair, the ones its "chat-repair" turn gives
+   * `onTurn`; empty when it had none. The last one's diagnostics are the
+   * block's own after the repair.
+   */
+  repairs: ReadonlyArray<TurnRound>;
+  /**
+   * Set when the server rewrote the block instead of asking for a repair;
+   * `diagnostics` and `advice` are then those of the rewritten source.
+   */
+  rewrites?: ReadonlyArray<TurnRewrite>;
+  /** "repairing" until its repair settles, then "done". */
+  status: Exclude<ChatBlockStatus, "streaming">;
+}
+/** Prose to show as it arrives, or a block that appeared or changed. */
+export type ChatEvent = {
+  block: ChatBlock;
+  type: "block";
+} | {
+  text: string;
+  type: "text";
+};
+export interface ChatOptions {
+  /**
+   * The conversation's earlier blocks, oldest first: edits apply to the
+   * latest version of an id, and versions count on from them. Sources from
+   * the browser are only compiled, never trusted as programs.
+   */
+  blocks?: ReadonlyArray<ChatBlockSource>;
+  /** Plain JSON for the `options` schema, which repairs pass to `model`. */
+  options?: unknown;
+  /**
+   * The user's message this reply answers. A repair shows it to the model,
+   * so the fixed block still does what was asked.
+   */
+  prompt?: string | undefined;
+  /** Stops repairs, and `stream`, when the turn is abandoned. */
+  signal?: AbortSignal;
+}
+/**
+ * One chat reply. Feed it the model's text: `push` and `end` return prose
+ * and blocks as they complete, `repair` fixes a block that closed with
+ * errors, and `stream` does all three over an async iterable.
+ */
+export interface ChatTurn {
+  /** Closes a block left open when the reply ends. */
+  end: () => Array<ChatEvent>;
+  /** Any slice of the reply; returns what it completed. */
+  push: (delta: string) => Array<ChatEvent>;
+  /**
+   * For a block with status "repairing": a document-mode session turn on
+   * it, through `model`. Yields the block once more, done. Any other block
+   * comes back unchanged.
+   */
+  repair: (block: ChatBlock) => AsyncIterable<ChatBlock>;
+  /**
+   * Each block the reply has closed so far, in order, and what came of it.
+   * Read it once `stream` ends, or after `end` and every `repair`, to count
+   * the reply's failures.
+   */
+  results: () => Array<ChatBlockResult>;
+  /** `push`, `end` and `repair` together; ends after every repair settles. */
+  stream: (reply: AsyncIterable<string>) => AsyncIterable<ChatEvent>;
+  /** The chat-mode prompt, `prompt("chat")`, with the server's `instructions`. */
+  system: string;
+  /** The start of `system` that is the same on every turn, as on `ModelRequest`. */
+  systemPrefix: string;
+}
+export interface PickleServer<TContext, TSpecName extends string = never> {
+  call: (request: CallRequest, context: CallContext<TContext>) => Promise<CallOutcome>;
+  /**
+   * Starts a chat reply for `request`. It refuses the request as `handler`
+   * would (an `Origin` that may not call this server, or a body that is not
+   * JSON), then runs `context` and parses `blocks` and `options`. Each
+   * failure rejects with a `PickleError`. See `ChatTurn`.
+   */
+  chat: (request: Request, options?: ChatOptions) => Promise<ChatTurn>;
+  /** Checks and compiles a source with no model. Strict unless told otherwise. */
+  compile: (source: string, options?: CompileOptions) => Promise<{
+    /** The design checks' advice, numbered like `diagnostics`. */
+    advice: ReadonlyArray<Advice>;
+    diagnostics: ReadonlyArray<Diagnostic>;
+    program: Program;
+  }>;
+  /** The sandbox frame document, with its own content security policy. */
+  frame: (request?: Request) => Response;
+  handler: (request: Request) => Promise<Response>;
+  /** The largest request body `handler` accepts, in bytes. */
+  maxBodyBytes: number;
+  /**
+   * The system prompt for this host. "document" (default) is what sessions
+   * use: every reply is one UI. "chat" is Markdown with UIs in fenced
+   * `pickle` blocks.
+   */
+  prompt: (mode?: PromptMode) => string;
+  /**
+   * The start of `prompt(mode)` that is the same on every turn: the
+   * language and the catalog, before the instructions and procedures. Mark
+   * it for a provider's prompt cache (`cachedInstructions` in
+   * `@jigs.design/ai-sdk`).
+   */
+  promptPrefix: (mode?: PromptMode) => string;
+  session: (body: SessionRequest, context: CallContext<TContext>) => AsyncIterable<SessionEvent>;
+  /** A spec from `specs`, compiled at startup. */
+  spec: (name: TSpecName) => Program;
+  /** Changes whenever the compiler, the runtime or the host does. */
+  version: string;
+}
+//#endregion
+export type { EditFailureReason };

package/dist/usage.d.ts

@@ -0,0 +1,5 @@
+import { Usage } from "./types.js";
+//#region src/usage.d.ts
+/** `a` and `b` added up. A cache count is kept when either reports one. */
+export declare function addUsage(a: Usage, b: Usage): Usage;
+//#endregion

package/dist/usage.js

@@ -0,0 +1,13 @@
+//#region src/usage.ts
+/** `a` and `b` added up. A cache count is kept when either reports one. */
+function addUsage(a, b) {
+	const total = {
+		inputTokens: a.inputTokens + b.inputTokens,
+		outputTokens: a.outputTokens + b.outputTokens
+	};
+	if (a.cacheReadTokens !== void 0 || b.cacheReadTokens !== void 0) total.cacheReadTokens = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+	if (a.cacheWriteTokens !== void 0 || b.cacheWriteTokens !== void 0) total.cacheWriteTokens = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+	return total;
+}
+//#endregion
+export { addUsage };

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@jigs.design/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "createPickleServer: checks and streams programs, runs procedures, and serves the sandbox frame.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/server"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jigs.design/prompt": "0.1.1",
+    "@jigs.design/runtime": "0.1.1",
+    "@jigs.design/host": "0.1.1",
+    "@jigs.design/compiler": "0.1.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
+  }
 }