@vendoai/apps 0.4.0

package/dist/engine.d.ts

@@ -0,0 +1,188 @@
+import { type AppDocument, type DomainManifest, type NormalizedCatalog, type ShapeType, type ToolSemantics, type TreeV2, type VendoTheme } from "@vendoai/core";
+import type { LanguageModel } from "ai";
+import { type PipelineConfig, type PipelineEvent } from "./pipeline.js";
+import { type PinBaseline } from "./pins.js";
+/** The slice of a tool descriptor generation needs: prompt context and the
+ *  query-tool existence check. `inputSchema` (W4 pipeline) feeds the
+ *  structured-repair payload skeleton for mutation-without-payload fixes. */
+export interface HostToolInfo {
+    name: string;
+    description: string;
+    risk: string;
+    inputSchema?: Record<string, unknown>;
+}
+/** v2 spec §§1,4 — a compiled prefix of the streaming wire: always a
+ *  validateTreeV2-passing tree (valid-while-partial) plus the islands
+ *  admitted so far. */
+export interface GeneratedPartial {
+    name?: string;
+    tree: TreeV2;
+    components?: Record<string, string>;
+}
+/** Speed lane (vendo-v2-speed) — structured create timing emitted per lane.
+ *  `atMs` is milliseconds since the create() call began; `first-partial` fires
+ *  when the first compiled prefix reaches the seam (time-to-paint) and
+ *  `complete` when the lane's stream ends (with token usage). The full lane may
+ *  repair up to 3× on validation failure, so it emits one `complete` per
+ *  attempt — the LAST `full`/`complete` is the successful document; earlier
+ *  ones are failed attempts. Opt-in: nothing is emitted unless `onTiming` is
+ *  wired. */
+export interface GenerationTimingEvent {
+    lane: "paint" | "full" | "outline" | "section" | "repair" | "end-pass";
+    phase: "first-partial" | "complete";
+    atMs: number;
+    thinking: boolean;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+export interface GenerationDependencies {
+    model: LanguageModel;
+    /** The composition-normalized catalog (01 §14): propsJsonSchema is derived. */
+    catalog: NormalizedCatalog;
+    theme?: VendoTheme;
+    /** Host design rules for the generation prompt. The function form is
+     *  resolved every time prompt sections are built, so a per-call source
+     *  (e.g. `.vendo/design-rules.md`) is re-read on each create/edit. */
+    designRules?: string | (() => string | undefined);
+    pinBaselines?: readonly PinBaseline[];
+    /** v2 spec §3 — shape-card outputs keyed by tool; when present, create and
+     *  edit compiles type-check bindings and surface shape-mismatch repair. */
+    toolShapes?: Readonly<Record<string, ShapeType>>;
+    /** The host tools queries may name. When present they are listed in the
+     *  generation prompt and a query naming any other tool is a validation
+     *  error routed to repair (verify-v2: the model invents tool names). */
+    tools?: readonly HostToolInfo[];
+    /** W3 (v3 spec §Context) — per-tool field semantics from
+     *  `.vendo/semantics.json`: annotate the shape cards, drive Kit format
+     *  defaults, and feed the law checks. Keyed by tool name. */
+    semantics?: Readonly<Record<string, ToolSemantics>>;
+    /** W3 — the host's domain manifest (has / has-NOT), surfaced to generation
+     *  as fact so out-of-domain asks get a Disclaimer, never invented data. */
+    domains?: DomainManifest;
+    /** 06-apps §5 — additive, optional partial-tree streaming seam. */
+    onPartial?: (partial: GeneratedPartial) => void | Promise<void>;
+    /**
+     * v2 spec §4 — the tier-0 paint lane. The lane runs only when a streaming
+     * consumer (onPartial) is wired: the instant paint exists to reach a screen.
+     * `model` is the no-think switch — point it at a thinking-disabled model
+     * instance and the paint lane runs on it while the full lane keeps the main
+     * model. `disabled` forces the single-lane flow.
+     */
+    paint?: {
+        model?: LanguageModel;
+        disabled?: boolean;
+    };
+    /** Speed lane — opt-in structured timing seam (see GenerationTimingEvent). */
+    onTiming?: (event: GenerationTimingEvent) => void;
+    /** W4 pipeline knobs (structured repair / region-parallel / end pass). */
+    pipeline?: PipelineConfig;
+    /** W4 pipeline — opt-in per-stage diagnostics (rounds, fallbacks, timing);
+     *  nothing is emitted unless wired. */
+    onPipeline?: (event: PipelineEvent) => void;
+}
+export interface GenerationCreateInput {
+    prompt: string;
+}
+export interface GenerationEditInput {
+    app: AppDocument;
+    instruction: string;
+    repairIssues?: string[];
+}
+export type GeneratedAppDocument = Omit<AppDocument, "id">;
+/**
+ * execution-v2 Wave 3 — the engine emits ONLY tree documents now. Server code
+ * no longer rides a model "code edit" dialect: it is written BY the in-box
+ * coding agent (box-agent.ts) during graduation, and the tree gains its `fn:`
+ * bindings through this same tree-edit path afterward. The vestigial code
+ * lane (rungs 2–4 file plans) is deleted.
+ */
+export type GenerationEditResult = {
+    kind: "document";
+    document: GeneratedAppDocument;
+} | {
+    kind: "failure";
+    issues: string[];
+};
+/** 06-apps §5 — replaceable generation seam used by createApps(). */
+export interface GenerationEngine {
+    create(input: GenerationCreateInput, deps: GenerationDependencies): Promise<GeneratedAppDocument>;
+    edit(input: GenerationEditInput, deps: GenerationDependencies): Promise<GenerationEditResult>;
+}
+/** The fictional host used by the exemplars. Exported so the exemplar-validity
+ *  test compiles every exemplar against these exact tools — a broken example
+ *  teaches broken apps, so the examples are pinned by test. */
+export declare const V4_EXEMPLAR_TOOLS: HostToolInfo[];
+export declare const V4_EXEMPLARS: ReadonlyArray<{
+    title: string;
+    request: string;
+    wire: string;
+    why: string;
+}>;
+export declare const wireContractV4: (deps: GenerationDependencies) => string;
+export declare const distinctIssues: (current: string[], next: string[]) => string[];
+/** The deterministic fork core (06-apps §8): copies the TRUSTED captured
+ *  baseline into the named generated component, mints and attaches the node,
+ *  and records the pin — no model involvement, source is never retyped.
+ *  Gesture-owned forking (2026-07-21): the runtime's pins.fork surface is the
+ *  primary caller (the user's Remix gesture); the <ForkPin> extension op keeps
+ *  compiling for stored apps but is no longer taught to the model. */
+export declare const applyPinFork: (app: AppDocument, props: Record<string, unknown>, pinBaselines: readonly PinBaseline[] | undefined) => string[];
+/**
+ * Speed lane — page-open prewarm. Pays the provider import + TLS/keep-alive
+ * connection cost up front with a throwaway 1-token generation so the first
+ * real create reuses a live socket instead of opening one cold. Best-effort:
+ * any failure (no key, offline) is swallowed. Measured effect on first-paint
+ * is small (model time-to-first-token dominates), so this is a cheap
+ * worst-case guard, not a headline win — see docs/verification/vendo-v2-speed.
+ */
+export declare const prewarmModels: (models: readonly LanguageModel[]) => Promise<void>;
+/** 06-apps §§2,5; v2 spec §§2,4 — wire-backed rung-1 generation and
+ *  two-dialect edit planning. */
+export declare const modelEngine: GenerationEngine;
+/**
+ * execution-v2 Wave 3 — the graduation judgment: whether an instruction needs
+ * server capability (scheduled/background work, third-party egress, heavy
+ * logic, app-owned state) and so must ride the in-box agent (runtime graduates
+ * 1→2, delegates the server work to the box, then lands fn: bindings via the
+ * tree-edit path). A false answer keeps the edit on the pure tree path.
+ * Ambiguous words like "api" or "function" count only when they are not
+ * labeling a visible element — "make the API status card blue" must stay on
+ * the cheap tree path (ENG-349).
+ */
+export declare const instructionRequiresServer: (app: Pick<AppDocument, "ui">, instruction: string) => boolean;
+/**
+ * execution-v2 Wave 9 — the server-work ESCALATION LADDER (Yousef's economics
+ * ruling: box graduation costs minutes of model round trips; the existing
+ * automations engine covers most server-shaped needs in seconds). For a
+ * server-shaped instruction the runtime prefers, in order:
+ *
+ *   (a) "steps"   — expressible as deterministic tool calls (host + connected
+ *                   tools + existing fn: refs) with jsonata reshaping, forEach,
+ *                   and park/resume approval gates. A steps automation on the
+ *                   EXISTING automations engine; no machine.
+ *   (b) "agentic" — needs per-run judgment, but every effect is tool-reachable.
+ *                   An agentic automation (the agent-loop run model); no machine.
+ *   (c) "box"     — only when actual custom code is required (real computation,
+ *                   libraries, complex persistent state, non-tool-shaped egress,
+ *                   latency-sensitive logic). Box graduation — EXPERIMENTAL,
+ *                   gated by `experimentalMachines`.
+ *
+ * `null` means the instruction is not server-shaped at all (pure tree path).
+ * Same judge shape as {@link instructionRequiresServer}: deterministic word
+ * classes with the ENG-349 visible-element rule for ambiguous terms. A served
+ * (ui: "http") app is always box-shaped — its whole surface lives in its
+ * machine.
+ */
+export declare const serverWorkRung: (app: Pick<AppDocument, "ui">, instruction: string) => "steps" | "agentic" | "box" | null;
+/**
+ * execution-v2 Wave 4 — the 2→3 escalation judgment (same judge shape as
+ * {@link instructionRequiresServer}): whether an instruction's UI needs exceed
+ * the tree, so the box agent must build a REAL web app the machine serves
+ * (layer 3, experimental — the runtime refuses this path unless the host
+ * enabled `experimentalServedApps`). An already-served app is always a
+ * layer-3 subject: every edit of it is served-app work.
+ */
+export declare const instructionRequiresServedApp: (app: Pick<AppDocument, "ui">, instruction: string) => boolean;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

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