@xemahq/kernel-contracts 0.28.0 → 0.30.0

package/src/output-surface-inspect/lib/output-surface-inspect.ts

@@ -0,0 +1,427 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// output-surface-inspect-contracts — the pure (zero-dependency) wire contract for the
+// Output Surface Inspector.
+//
+// One shared source of truth for three independently-deployed parties:
+//   • the `output-surface-inspector` agent's `browser` opencode tool (mirrors the
+//     step schema with opencode's bundled zod — it cannot import this package)
+//   • agent-session-api's OutputSurfaceInspectBroker (imports this package directly)
+//   • the Unified Output Surface Bridge injected into the output surface iframe
+//
+// This file is deliberately ZOD-FREE so the browser-side bridge can bundle it
+// without pulling a validation library into every output surface page. The runtime
+// zod schema (`InspectStepSchema`) lives in the sibling `step-schema.ts`, which
+// is type-checked back against the `InspectStep` union declared here.
+//
+// The "step language" deliberately mirrors a headless browser's verb set so a
+// future headless InspectProvider is a drop-in: `InspectTargetKind.HEADLESS`
+// would simply be a superset of `USER_TAB` — every step here stays valid.
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ─── Target backends ────────────────────────────────────────────────────────
+
+/**
+ * Which browser the inspect batch runs against. Closed set. `USER_TAB` is the
+ * only implemented provider; `HEADLESS` is reserved for a future background
+ * navigator that drives its own Playwright browser — adding it must not change
+ * any other type in this file.
+ */
+export enum InspectTargetKind {
+  UserTab = 'user-tab',
+  Headless = 'headless',
+}
+
+// ─── Step language ──────────────────────────────────────────────────────────
+
+/**
+ * Closed set of inspect step verbs. Navigation steps (`navigate`/`reload`/
+ * `back`) are *barriers*: the broker waits for the next page to re-arm the
+ * bridge before dispatching later steps.
+ */
+export enum InspectStepKind {
+  // navigation (barrier)
+  Navigate = 'navigate',
+  Reload = 'reload',
+  Back = 'back',
+  // interaction
+  Click = 'click',
+  Fill = 'fill',
+  Type = 'type',
+  Select = 'select',
+  Press = 'press',
+  Hover = 'hover',
+  // inspection
+  Snapshot = 'snapshot',
+  Evaluate = 'evaluate',
+  Console = 'console',
+  Network = 'network',
+  Page = 'page',
+  // control
+  Wait = 'wait',
+}
+
+/** Console levels the bridge captures. Closed set. */
+export enum InspectConsoleLevel {
+  Log = 'log',
+  Info = 'info',
+  Warn = 'warn',
+  Error = 'error',
+  Debug = 'debug',
+}
+
+/** Every console level — the default when a read declares no level filter. */
+export const INSPECT_CONSOLE_LEVEL_VALUES: readonly InspectConsoleLevel[] =
+  Object.values(InspectConsoleLevel);
+
+/** Per-step outcome. Closed set — every non-`ok` value is a deterministic exit. */
+export enum InspectStepStatus {
+  Ok = 'ok',
+  Error = 'error',
+  /** No bridge replied within the per-step deadline. */
+  Timeout = 'timeout',
+  /** The page unloaded mid-step (covers an unexpected navigation/refresh). */
+  PageNavigated = 'page-navigated',
+  /**
+   * The output surface navigated to an origin we do not control (external link,
+   * OAuth provider, off-site form POST) — the bridge can no longer be
+   * injected there, so inspection cannot continue until the user returns to
+   * the project output surface.
+   */
+  OffDomain = 'off-domain',
+  /** An earlier step stopped the batch, so this step never ran. */
+  Skipped = 'skipped',
+  /** No live output surface tab was attached when the batch ran. */
+  OutputSurfaceNotOpen = 'output-surface-not-open',
+}
+
+/** Why the bridge announced an imminent unload. Closed set. */
+export enum InspectUnloadReason {
+  /** A normal in-origin navigation/refresh — a new bridge will re-arm. */
+  Navigation = 'navigation',
+  /**
+   * The page is leaving our origin — no bridge can follow. The FE must
+   * surface a "return to the project output surface" affordance to the user.
+   */
+  OffDomain = 'off-domain',
+}
+
+/** Overall batch lifecycle. Closed set. */
+export enum InspectBatchStatus {
+  Pending = 'pending',
+  Running = 'running',
+  Completed = 'completed',
+  Failed = 'failed',
+}
+
+// ─── Step shapes ────────────────────────────────────────────────────────────
+//
+// Hand-authored discriminated union. `step-schema.ts` builds the matching zod
+// validator and asserts — at compile time — that the two never drift.
+
+// Optional fields on step shapes carry an explicit `| undefined` so this union
+// matches the zod schema's `z.infer` output exactly (see `step-schema.ts`'s
+// compile-time equivalence assertion under `exactOptionalPropertyTypes`).
+
+/**
+ * An element target: either a `ref` returned by a prior `snapshot` step, or a
+ * raw CSS selector. At least one must be present (enforced by the zod schema).
+ */
+export interface InspectElementTarget {
+  ref?: string | undefined;
+  selector?: string | undefined;
+}
+
+/** Filters shared by the windowed `console` / `network` reads. */
+export interface InspectWindowedRead {
+  /** Only entries from the last N ms (rolling observation window). */
+  sinceMs?: number | undefined;
+  /** Only entries newer than this cursor (from a prior read's result). */
+  sinceCursor?: number | undefined;
+  /** Case-insensitive substring filter on the entry text/url. */
+  grep?: string | undefined;
+  /** Max entries returned. Server clamps to INSPECT_READ_MAX_LIMIT. */
+  limit?: number | undefined;
+}
+
+export interface InspectNavigateStep {
+  kind: InspectStepKind.Navigate;
+  /** Path within the output surface app, e.g. `/checkout`. Not an absolute URL. */
+  path: string;
+}
+export interface InspectReloadStep {
+  kind: InspectStepKind.Reload;
+}
+export interface InspectBackStep {
+  kind: InspectStepKind.Back;
+}
+export interface InspectClickStep extends InspectElementTarget {
+  kind: InspectStepKind.Click;
+}
+export interface InspectFillStep extends InspectElementTarget {
+  kind: InspectStepKind.Fill;
+  /** Value written into the input/textarea (replaces existing content). */
+  value: string;
+}
+export interface InspectTypeStep extends InspectElementTarget {
+  kind: InspectStepKind.Type;
+  /** Text typed keystroke-by-keystroke into the focused/target element. */
+  text: string;
+}
+export interface InspectSelectStep extends InspectElementTarget {
+  kind: InspectStepKind.Select;
+  /** `<option>` value (or visible label) to select. */
+  value: string;
+}
+export interface InspectPressStep extends InspectElementTarget {
+  kind: InspectStepKind.Press;
+  /** Key name, e.g. `Enter`, `Tab`, `Escape`. */
+  key: string;
+}
+export interface InspectHoverStep extends InspectElementTarget {
+  kind: InspectStepKind.Hover;
+}
+export interface InspectSnapshotStep {
+  kind: InspectStepKind.Snapshot;
+  /** Optional CSS selector to scope the snapshot to a subtree. */
+  selector?: string | undefined;
+}
+export interface InspectEvaluateStep {
+  kind: InspectStepKind.Evaluate;
+  /** JavaScript expression evaluated in the page; result is JSON-serialized. */
+  expression: string;
+}
+export interface InspectConsoleStep extends InspectWindowedRead {
+  kind: InspectStepKind.Console;
+  levels?: InspectConsoleLevel[] | undefined;
+}
+export interface InspectNetworkStep extends InspectWindowedRead {
+  kind: InspectStepKind.Network;
+  /** Only requests that failed or returned a >=400 status. */
+  failedOnly?: boolean | undefined;
+}
+export interface InspectPageStep {
+  kind: InspectStepKind.Page;
+}
+export interface InspectWaitStep {
+  kind: InspectStepKind.Wait;
+  /** Milliseconds to wait before the next step (observation window control). */
+  ms: number;
+}
+
+/**
+ * One inspect step. Discriminated on `kind`. Kept as a hand-authored union so
+ * the browser bridge can consume it without bundling zod; `step-schema.ts`
+ * holds the runtime validator and is asserted equivalent to this type.
+ */
+export type InspectStep =
+  | InspectNavigateStep
+  | InspectReloadStep
+  | InspectBackStep
+  | InspectClickStep
+  | InspectFillStep
+  | InspectTypeStep
+  | InspectSelectStep
+  | InspectPressStep
+  | InspectHoverStep
+  | InspectSnapshotStep
+  | InspectEvaluateStep
+  | InspectConsoleStep
+  | InspectNetworkStep
+  | InspectPageStep
+  | InspectWaitStep;
+
+// ─── Results ────────────────────────────────────────────────────────────────
+
+export interface InspectConsoleEntry {
+  readonly level: InspectConsoleLevel;
+  readonly text: string;
+  /** Consecutive identical entries are collapsed; >1 means repeated. */
+  readonly count: number;
+  readonly firstAt: number;
+  readonly lastAt: number;
+  readonly source: 'console' | 'window.error' | 'unhandledrejection';
+}
+
+export interface InspectNetworkEntry {
+  readonly url: string;
+  readonly method?: string;
+  /** HTTP status — only known for `fetch`/XHR; absent for other resources. */
+  readonly status?: number;
+  readonly resourceType: string;
+  readonly startedAt: number;
+  readonly durationMs?: number;
+  readonly transferSize?: number;
+  readonly failed?: boolean;
+  readonly errorText?: string;
+}
+
+/** Bounded-read envelope shared by `console` and `network` results. */
+export interface InspectReadResult<TEntry> {
+  readonly entries: readonly TEntry[];
+  /** Total entries currently held in the buffer for this page. */
+  readonly collected: number;
+  readonly returned: number;
+  /** Entries dropped from the buffer (ring eviction) or filtered out. */
+  readonly dropped: number;
+  readonly truncated: boolean;
+  /** Pass back as `sinceCursor` on the next read for incremental polling. */
+  readonly cursor: number;
+}
+
+export interface InspectStepResult {
+  readonly kind: InspectStepKind;
+  readonly status: InspectStepStatus;
+  /** Step-specific payload (page info, snapshot tree, read envelope, …). */
+  readonly data?: unknown;
+  readonly error?: string;
+}
+
+/** Request body for `POST /sessions/:id/output-surface-inspect/batch`. */
+export interface InspectBatchRequest {
+  readonly steps: readonly InspectStep[];
+  readonly target?: InspectTargetKind;
+}
+
+/**
+ * One output surface app known for the session. Its source lives in the agent's own
+ * `/workspace` under `repos/<repoSlug>/` — the agent and the running output surface
+ * share that tree, so edits the main agent makes appear live (dev-server HMR).
+ */
+export interface InspectOutputSurfaceApp {
+  readonly name: string;
+  readonly repoSlug: string;
+  readonly kind: string;
+  readonly status: string;
+  readonly externalUrl?: string;
+}
+
+/**
+ * The runtime context a `browser` call carries back so the agent always knows
+ * *what it is operating on* — derived generically from the session's output surface
+ * apps, so it fits any interactive session (webapp-studio, design-system-builder, …).
+ */
+export interface InspectOutputSurfaceContext {
+  /** Which browser the steps ran in (`user-tab` = the user's real tab). */
+  readonly target: InspectTargetKind;
+  /** Output surface apps known for this session and where their source lives. */
+  readonly apps: readonly InspectOutputSurfaceApp[];
+  /** Absolute workspace root shared by the agent and the running output surface. */
+  readonly workspaceRoot: string;
+}
+
+/** Result of a batch — what the `browser` tool returns to the agent. */
+export interface InspectBatchResult {
+  readonly batchId: string;
+  readonly status: InspectBatchStatus;
+  readonly results: readonly InspectStepResult[];
+  /** Human-readable note when the batch ended early (e.g. output-surface-not-open). */
+  readonly note?: string;
+  /** Runtime context — present on every result so the agent stays oriented. */
+  readonly outputSurfaceContext?: InspectOutputSurfaceContext;
+}
+
+// ─── Bridge ↔ FE-relay postMessage protocol ─────────────────────────────────
+
+/** Bridge announces itself on every page load. */
+export const XEMA_INSPECT_HELLO = 'xema:inspect:hello' as const;
+/** Bridge signals an imminent page unload (covers any navigation/refresh). */
+export const XEMA_INSPECT_UNLOADING = 'xema:inspect:unloading' as const;
+/** FE relay → bridge: execute one step. */
+export const XEMA_INSPECT_COMMAND = 'xema:inspect:command' as const;
+/** Bridge → FE relay: the result of one command. */
+export const XEMA_INSPECT_RESULT = 'xema:inspect:result' as const;
+
+export interface InspectHelloMessage {
+  readonly type: typeof XEMA_INSPECT_HELLO;
+  readonly bridgeInstanceId: string;
+  readonly url: string;
+  readonly title: string;
+}
+
+export interface InspectUnloadingMessage {
+  readonly type: typeof XEMA_INSPECT_UNLOADING;
+  readonly bridgeInstanceId: string;
+  readonly reason: InspectUnloadReason;
+  /** Best-effort target URL when the bridge could observe it (off-domain). */
+  readonly targetUrl?: string;
+}
+
+export interface InspectCommandMessage {
+  readonly type: typeof XEMA_INSPECT_COMMAND;
+  readonly commandId: string;
+  readonly step: InspectStep;
+}
+
+export interface InspectResultMessage {
+  readonly type: typeof XEMA_INSPECT_RESULT;
+  readonly commandId: string;
+  readonly result: InspectStepResult;
+}
+
+// ─── Bridge → FE passive signals (not part of the command channel) ──────────
+
+/** Bridge announces the output surface app finished its first paint. */
+export const XEMA_OUTPUT_SURFACE_READY = 'xema:output-surface-ready' as const;
+/** Bridge pushes a bounded error summary — drives the FE "Try to fix" gate. */
+export const XEMA_RUNTIME_ERRORS = 'xema:runtime-errors' as const;
+/** FE → bridge: toggle click-to-comment mode. */
+export const XEMA_SET_COMMENT_MODE = 'xema:set-comment-mode' as const;
+/** Bridge → FE: the user clicked an element while comment mode was on. */
+export const XEMA_COMMENT = 'xema:comment' as const;
+
+export interface OutputSurfaceRuntimeErrorItem {
+  readonly text: string;
+  readonly count: number;
+  readonly source: 'console' | 'window.error' | 'unhandledrejection';
+}
+
+/** Bounded error summary the bridge pushes for the FE turn-completion gate. */
+export interface OutputSurfaceRuntimeErrorSummary {
+  readonly type: typeof XEMA_RUNTIME_ERRORS;
+  readonly url: string;
+  /** Total error-level entries currently buffered. */
+  readonly total: number;
+  /** Top distinct errors (deduped, capped). */
+  readonly top: readonly OutputSurfaceRuntimeErrorItem[];
+}
+
+// ─── Realtime event ─────────────────────────────────────────────────────────
+
+/** CloudEvent type carrying an inspect command from the broker to the FE relay. */
+export const SESSION_OUTPUT_SURFACE_INSPECT_COMMAND_EVENT =
+  'session.output-surface.inspect.command' as const;
+
+// ─── Limits (single source of truth; tunable) ───────────────────────────────
+
+/** Max steps a single batch may carry. */
+export const INSPECT_MAX_STEPS_PER_BATCH = 20;
+/** Per-step deadline for a non-navigating step. */
+export const INSPECT_STEP_TIMEOUT_MS = 15_000;
+/** Deadline for a navigation barrier to re-arm the bridge on the new page. */
+export const INSPECT_NAVIGATE_TIMEOUT_MS = 30_000;
+/** An output surface tab is considered live this long after its last heartbeat. */
+export const INSPECT_PRESENCE_TTL_MS = 30_000;
+/** FE relay heartbeat cadence (must be < TTL). */
+export const INSPECT_PRESENCE_HEARTBEAT_MS = 10_000;
+
+/** Console/network ring-buffer caps inside the bridge. */
+export const INSPECT_BUFFER_MAX_ENTRIES = 500;
+export const INSPECT_BUFFER_MAX_BYTES = 256 * 1024;
+/** Per-entry message/text truncation. */
+export const INSPECT_ENTRY_MAX_BYTES = 2 * 1024;
+/** `evaluate` result JSON truncation. */
+export const INSPECT_EVAL_RESULT_MAX_BYTES = 8 * 1024;
+/** Whole-batch result truncation guard. */
+export const INSPECT_BATCH_RESULT_MAX_BYTES = 32 * 1024;
+/** Windowed-read default/clamp. */
+export const INSPECT_READ_DEFAULT_LIMIT = 50;
+export const INSPECT_READ_MAX_LIMIT = 200;
+
+/** True when the step is a navigation barrier (later steps run post-load). */
+export function isInspectNavigationStep(kind: InspectStepKind): boolean {
+  return (
+    kind === InspectStepKind.Navigate ||
+    kind === InspectStepKind.Reload ||
+    kind === InspectStepKind.Back
+  );
+}

package/src/output-surface-inspect/lib/step-schema.ts

@@ -0,0 +1,107 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// step-schema.ts — the runtime zod validator for the inspect step language.
+//
+// Kept SEPARATE from `output-surface-inspect.ts` on purpose: that module is zod-free
+// so the browser-side Unified Output Surface Bridge can bundle the contract without
+// pulling a validation library into every output surface page. Only agent-session-api
+// (the broker) imports this file's `InspectStepSchema` at runtime.
+//
+// The `_assertStepContractInSync` constant below is a COMPILE-TIME guarantee
+// that this schema and the hand-authored `InspectStep` union never drift — add
+// a step kind to one without the other and the build fails.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { InspectConsoleLevel, InspectStepKind } from './output-surface-inspect';
+import type { InspectStep } from './output-surface-inspect';
+
+// An element target: either a `ref` from a prior `snapshot`, or a CSS selector.
+const elementTargetShape = {
+  ref: z.string().min(1).max(200).optional(),
+  selector: z.string().min(1).max(2000).optional(),
+};
+
+const windowedReadShape = {
+  /** Only entries from the last N ms (rolling observation window). */
+  sinceMs: z.number().int().positive().max(600_000).optional(),
+  /** Only entries newer than this cursor (from a prior read's result). */
+  sinceCursor: z.number().int().nonnegative().optional(),
+  /** Case-insensitive substring filter on the entry text/url. */
+  grep: z.string().min(1).max(400).optional(),
+  /** Max entries returned. Server clamps to INSPECT_READ_MAX_LIMIT. */
+  limit: z.number().int().positive().optional(),
+};
+
+export const InspectStepSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal(InspectStepKind.Navigate),
+    /** Path within the output surface app, e.g. `/checkout`. Not an absolute URL. */
+    path: z.string().min(1).max(2000),
+  }),
+  z.object({ kind: z.literal(InspectStepKind.Reload) }),
+  z.object({ kind: z.literal(InspectStepKind.Back) }),
+  z.object({ kind: z.literal(InspectStepKind.Click), ...elementTargetShape }),
+  z.object({
+    kind: z.literal(InspectStepKind.Fill),
+    ...elementTargetShape,
+    /** Value written into the input/textarea (replaces existing content). */
+    value: z.string().max(20_000),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Type),
+    ...elementTargetShape,
+    /** Text typed keystroke-by-keystroke into the focused/target element. */
+    text: z.string().max(20_000),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Select),
+    ...elementTargetShape,
+    /** `<option>` value (or visible label) to select. */
+    value: z.string().max(2000),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Press),
+    ...elementTargetShape,
+    /** Key name, e.g. `Enter`, `Tab`, `Escape`. */
+    key: z.string().min(1).max(40),
+  }),
+  z.object({ kind: z.literal(InspectStepKind.Hover), ...elementTargetShape }),
+  z.object({
+    kind: z.literal(InspectStepKind.Snapshot),
+    /** Optional CSS selector to scope the snapshot to a subtree. */
+    selector: z.string().min(1).max(2000).optional(),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Evaluate),
+    /** JavaScript expression evaluated in the page; result is JSON-serialized. */
+    expression: z.string().min(1).max(20_000),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Console),
+    ...windowedReadShape,
+    levels: z.array(z.enum(InspectConsoleLevel)).min(1).optional(),
+  }),
+  z.object({
+    kind: z.literal(InspectStepKind.Network),
+    ...windowedReadShape,
+    /** Only requests that failed or returned a >=400 status. */
+    failedOnly: z.boolean().optional(),
+  }),
+  z.object({ kind: z.literal(InspectStepKind.Page) }),
+  z.object({
+    kind: z.literal(InspectStepKind.Wait),
+    /** Milliseconds to wait before the next step (observation window control). */
+    ms: z.number().int().positive().max(60_000),
+  }),
+]);
+
+/**
+ * Compile-time drift guard: the schema and the hand-authored `InspectStep`
+ * union MUST stay mutually assignable. Add a step kind (or change a field) on
+ * one side without the other and one of these casts fails the build.
+ */
+const _schemaToType = (s: z.infer<typeof InspectStepSchema>): InspectStep => s;
+const _typeToSchema = (s: InspectStep): z.infer<typeof InspectStepSchema> => s;
+void _schemaToType;
+void _typeToSchema;

package/src/output-surface-inspect/runtime/index.ts

@@ -0,0 +1,7 @@
+// Browser-safe (zod-free) subset of the output-surface-inspect contract.
+//
+// The inspector bridge (`output-surface-inspector/bridge`) runs INSIDE the
+// inspected page, so it must import only pure types — never the zod
+// `step-schema` validator that the main `output-surface-inspect` entry also
+// re-exports. This `/runtime` subpath is that browser-safe surface.
+export * from '../lib/output-surface-inspect';

package/src/workspace-image/index.ts

@@ -0,0 +1,13 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace Image Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for per-org workspace image variants. Pure
+// types, closed enums, zod schemas, plus the deterministic content-hash
+// helper used to identify a variant from its declarative manifest +
+// base-image digest. Zero NestJS, zero Prisma.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/enums';
+export * from './lib/types';
+export * from './lib/hash';
+export * from './lib/schemas';

package/src/workspace-image/lib/enums.ts

@@ -0,0 +1,38 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace image — closed-domain enums ──
+//
+// Closed sets backing the per-org workspace image variants described in
+// the ImageLayerKind enumerates every layer recipe the kernel
+// understands; VariantStatus enumerates the bake lifecycle.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Closed set of layer-recipe kinds. Each kind has a strict TypeScript
+ * payload shape (see `ImageLayer` in `types.ts`).
+ *
+ * IMPORTANT: there is no `entrypoint` / `cmd` kind — the entrypoint is
+ * owned by the worker-runtime, never by an org-supplied recipe.
+ */
+export enum ImageLayerKind {
+  Apt = 'apt',
+  Dnf = 'dnf',
+  Apk = 'apk',
+  Pip = 'pip',
+  NpmGlobal = 'npm-global',
+  Env = 'env',
+  File = 'file',
+}
+
+/**
+ * Lifecycle of a single image variant. `draft` is editable in the UI;
+ * `building` is the active bake; `ready` is mountable by workers;
+ * `failed` retains the build log for debugging; `archived` keeps the row
+ * for history but disallows new use.
+ */
+export enum VariantStatus {
+  Draft = 'draft',
+  Building = 'building',
+  Ready = 'ready',
+  Failed = 'failed',
+  Archived = 'archived',
+}