@xemahq/kernel-contracts 0.49.3 → 0.56.0

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

@@ -0,0 +1,252 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// buffers.ts — bounded console / network ring buffers.
+//
+// SHARED, not per-target. Both inspect executors observe continuously and let
+// the agent pull windows on demand:
+//   • the in-page bridge (`output-surface-inspector/bridge`) patches console
+//     and fetch/XHR in the user's tab;
+//   • the governed headless executor subscribes to the equivalent
+//     browser-level events.
+// A `console` / `network` step must mean exactly the same thing on both, so
+// the ring eviction, the consecutive-duplicate collapse, the filtering and the
+// `{entries, collected, returned, dropped, truncated, cursor}` envelope live
+// here once instead of being reimplemented per target.
+//
+// Deliberately zod-free and DOM-free so the browser bridge can bundle it.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import {
+  clampInspectReadLimit,
+  INSPECT_BUFFER_MAX_BYTES,
+  INSPECT_BUFFER_MAX_ENTRIES,
+  INSPECT_CONSOLE_LEVEL_VALUES,
+  INSPECT_ENTRY_MAX_BYTES,
+  InspectConsoleLevel,
+} from './output-surface-inspect';
+import type {
+  InspectConsoleEntry,
+  InspectNetworkEntry,
+  InspectReadResult,
+  OutputSurfaceRuntimeErrorItem,
+} from './output-surface-inspect';
+
+function clip(text: string, max: number): string {
+  if (text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, max)}…[+${text.length - max} chars]`;
+}
+
+// Mutable entries — `cursor` is a monotonic id assigned on insert; `count`
+// and `lastAt` mutate when consecutive identical console lines collapse.
+interface ConsoleRecord extends Omit<InspectConsoleEntry, 'count' | 'lastAt'> {
+  cursor: number;
+  count: number;
+  lastAt: number;
+}
+interface NetworkRecord extends InspectNetworkEntry {
+  cursor: number;
+}
+
+abstract class RingBuffer<T extends { cursor: number }> {
+  protected entries: T[] = [];
+  protected nextCursor = 1;
+  /** Entries evicted by the ring (so reads can report `dropped`). */
+  protected evicted = 0;
+  private bytes = 0;
+
+  protected sizeOf(entry: T): number {
+    try {
+      return JSON.stringify(entry).length;
+    } catch {
+      return INSPECT_ENTRY_MAX_BYTES;
+    }
+  }
+
+  protected append(entry: T): void {
+    entry.cursor = this.nextCursor++;
+    this.entries.push(entry);
+    this.bytes += this.sizeOf(entry);
+    while (
+      this.entries.length > INSPECT_BUFFER_MAX_ENTRIES ||
+      (this.bytes > INSPECT_BUFFER_MAX_BYTES && this.entries.length > 1)
+    ) {
+      const dropped = this.entries.shift();
+      if (!dropped) {
+        break;
+      }
+      this.bytes -= this.sizeOf(dropped);
+      this.evicted += 1;
+    }
+  }
+
+  /** Total entries ever held minus what is currently retained. */
+  get totalCollected(): number {
+    return this.entries.length + this.evicted;
+  }
+}
+
+/** Filters shared by both windowed reads. `limit` is clamped by the buffer. */
+export interface InspectBufferReadOptions {
+  sinceMs?: number | undefined;
+  sinceCursor?: number | undefined;
+  grep?: string | undefined;
+  limit?: number | undefined;
+}
+
+export interface InspectConsoleReadOptions extends InspectBufferReadOptions {
+  levels?: readonly InspectConsoleLevel[] | undefined;
+}
+
+export interface InspectNetworkReadOptions extends InspectBufferReadOptions {
+  failedOnly?: boolean | undefined;
+}
+
+/**
+ * Drop the internal `cursor` bookkeeping field. The cursor is a buffer detail —
+ * it is reported ONCE per read (as the envelope's `cursor`), never per entry.
+ */
+function withoutCursor<TRecord extends { cursor: number }>(
+  record: TRecord,
+): Omit<TRecord, 'cursor'> {
+  const copy: Record<string, unknown> = { ...record };
+  delete copy.cursor;
+  return copy as Omit<TRecord, 'cursor'>;
+}
+
+/** Assemble the shared read envelope from a filtered set. */
+function envelope<TEntry, TRecord extends { cursor: number }>(
+  all: readonly TRecord[],
+  matched: readonly TRecord[],
+  limit: number,
+  collected: number,
+  evicted: number,
+  sinceCursor: number | undefined,
+): InspectReadResult<TEntry> {
+  const window = matched.slice(-limit);
+  const maxCursor = all.reduce((m, e) => Math.max(m, e.cursor), sinceCursor ?? 0);
+  return {
+    entries: window.map((record) => withoutCursor(record) as TEntry),
+    collected,
+    returned: window.length,
+    dropped: evicted + (matched.length - window.length),
+    truncated: matched.length > window.length,
+    cursor: maxCursor,
+  };
+}
+
+export class ConsoleBuffer extends RingBuffer<ConsoleRecord> {
+  push(input: {
+    level: InspectConsoleLevel;
+    text: string;
+    source: InspectConsoleEntry['source'];
+  }): void {
+    const text = clip(input.text, INSPECT_ENTRY_MAX_BYTES);
+    const now = Date.now();
+    const last = this.entries[this.entries.length - 1];
+    // Collapse consecutive identical lines (level+source+text) into a count.
+    if (
+      last !== undefined &&
+      last.level === input.level &&
+      last.source === input.source &&
+      last.text === text
+    ) {
+      last.count += 1;
+      last.lastAt = now;
+      return;
+    }
+    this.append({
+      cursor: 0,
+      level: input.level,
+      text,
+      source: input.source,
+      count: 1,
+      firstAt: now,
+      lastAt: now,
+    });
+  }
+
+  /** Bounded error summary for the passive `xema:runtime-errors` push. */
+  errorSummary(maxDistinct: number): {
+    total: number;
+    top: OutputSurfaceRuntimeErrorItem[];
+  } {
+    const errors = this.entries.filter(
+      (e) => e.level === InspectConsoleLevel.Error,
+    );
+    const total = errors.reduce((sum, e) => sum + e.count, 0);
+    const top = [...errors]
+      .sort((a, b) => b.count - a.count)
+      .slice(0, maxDistinct)
+      .map((e) => ({ text: e.text, count: e.count, source: e.source }));
+    return { total, top };
+  }
+
+  read(opts: InspectConsoleReadOptions): InspectReadResult<InspectConsoleEntry> {
+    const cutoff = opts.sinceMs ? Date.now() - opts.sinceMs : 0;
+    const grep = opts.grep?.toLowerCase();
+    const levels =
+      opts.levels && opts.levels.length > 0
+        ? opts.levels
+        : INSPECT_CONSOLE_LEVEL_VALUES;
+    const matched = this.entries.filter(
+      (e) =>
+        e.lastAt >= cutoff &&
+        (opts.sinceCursor === undefined || e.cursor > opts.sinceCursor) &&
+        levels.includes(e.level) &&
+        (!grep || e.text.toLowerCase().includes(grep)),
+    );
+    return envelope<InspectConsoleEntry, ConsoleRecord>(
+      this.entries,
+      matched,
+      clampInspectReadLimit(opts.limit),
+      this.totalCollected,
+      this.evicted,
+      opts.sinceCursor,
+    );
+  }
+}
+
+export class NetworkBuffer extends RingBuffer<NetworkRecord> {
+  push(input: InspectNetworkEntry): void {
+    this.append({ cursor: 0, ...input });
+  }
+
+  /** Update the most recent matching in-flight request (by url+method). */
+  complete(
+    url: string,
+    method: string | undefined,
+    patch: Partial<InspectNetworkEntry>,
+  ): void {
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const e = this.entries[i];
+      if (e === undefined) {
+        continue;
+      }
+      if (e.url === url && e.method === method && e.durationMs === undefined) {
+        Object.assign(e, patch);
+        return;
+      }
+    }
+  }
+
+  read(opts: InspectNetworkReadOptions): InspectReadResult<InspectNetworkEntry> {
+    const cutoff = opts.sinceMs ? Date.now() - opts.sinceMs : 0;
+    const grep = opts.grep?.toLowerCase();
+    const matched = this.entries.filter(
+      (e) =>
+        e.startedAt >= cutoff &&
+        (opts.sinceCursor === undefined || e.cursor > opts.sinceCursor) &&
+        (!grep || e.url.toLowerCase().includes(grep)) &&
+        (!opts.failedOnly || e.failed === true || (e.status ?? 0) >= 400),
+    );
+    return envelope<InspectNetworkEntry, NetworkRecord>(
+      this.entries,
+      matched,
+      clampInspectReadLimit(opts.limit),
+      this.totalCollected,
+      this.evicted,
+      opts.sinceCursor,
+    );
+  }
+}

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

@@ -21,10 +21,19 @@
 // ─── 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.
+ * Which browser the inspect batch runs against. Closed set.
+ *
+ * • `UserTab` — the user's own live output-surface tab. The broker relays each
+ *   step to the injected bridge and results return out-of-band. The tab is
+ *   ATTACHED: it already shows a page, and it can never leave the project
+ *   origin (doing so loses the bridge — see {@link InspectStepStatus.OffDomain}).
+ * • `Headless` — a governed headless browser the platform opens for the batch
+ *   (`web-access-api`). It is SELF-OPENED: there is no pre-existing page, so
+ *   the batch MUST begin with a `navigate` step carrying an absolute `url`, and
+ *   an off-origin page is inspectable instead of being a dead end.
+ *
+ * The step language, the limits, the statuses and {@link InspectBatchResult}
+ * are IDENTICAL for both — only the transport differs.
  */
 export enum InspectTargetKind {
   UserTab = 'user-tab',
@@ -143,10 +152,32 @@ export interface InspectWindowedRead {
   limit?: number | undefined;
 }
 
+/**
+ * Go somewhere. Carries EXACTLY ONE of `path` or `url` — never both, never
+ * neither (enforced by `InspectStepSchema`, not by convention).
+ *
+ * The two are deliberately separate fields rather than one overloaded string:
+ * a target that cannot leave its origin (`InspectTargetKind.UserTab`) must be
+ * able to REFUSE an absolute navigation fail-fast, which is impossible if the
+ * caller's intent is hidden inside the syntax of a single value.
+ */
 export interface InspectNavigateStep {
   kind: InspectStepKind.Navigate;
-  /** Path within the output surface app, e.g. `/checkout`. Not an absolute URL. */
-  path: string;
+  /**
+   * Origin-RELATIVE path, e.g. `/checkout`, resolved against the page the step
+   * runs on. Requires a page to already be open, so it can never be the FIRST
+   * step of a self-opened (`Headless`) batch — there is no origin to resolve
+   * against yet.
+   */
+  path?: string | undefined;
+  /**
+   * ABSOLUTE `http(s)` URL. Only a target that opens its OWN browser
+   * (`InspectTargetKind.Headless`) can honour it: an attached user tab that
+   * left the project origin would lose the injected bridge, so the broker
+   * refuses a `url` navigate on `InspectTargetKind.UserTab` with an actionable
+   * error rather than producing an `off-domain` dead end.
+   */
+  url?: string | undefined;
 }
 export interface InspectReloadStep {
   kind: InspectStepKind.Reload;
@@ -417,6 +448,23 @@ export const INSPECT_BATCH_RESULT_MAX_BYTES = 32 * 1024;
 export const INSPECT_READ_DEFAULT_LIMIT = 50;
 export const INSPECT_READ_MAX_LIMIT = 200;
 
+/**
+ * Max nodes ONE `snapshot` step returns. Shared by every target's executor so
+ * a snapshot means the same thing in the user's tab and in the headless
+ * browser — the agent's `ref` budget must not depend on which target ran.
+ */
+export const INSPECT_SNAPSHOT_MAX_NODES = 200;
+/**
+ * The elements a `snapshot` step collects: interactive controls plus the
+ * landmark/heading structure that makes the outline navigable. Shared for the
+ * same reason as {@link INSPECT_SNAPSHOT_MAX_NODES}.
+ */
+export const INSPECT_SNAPSHOT_SELECTOR =
+  'a[href],button,input,textarea,select,[role],[onclick],' +
+  'h1,h2,h3,h4,h5,h6,nav,main,header,footer,form,[data-comment-id]';
+/** Attribute an executor stamps on snapshotted elements to mint a stable `ref`. */
+export const INSPECT_SNAPSHOT_REF_ATTR = 'data-xema-inspect-ref';
+
 /** True when the step is a navigation barrier (later steps run post-load). */
 export function isInspectNavigationStep(kind: InspectStepKind): boolean {
   return (
@@ -425,3 +473,14 @@ export function isInspectNavigationStep(kind: InspectStepKind): boolean {
     kind === InspectStepKind.Back
   );
 }
+
+/**
+ * Resolve a windowed read's `limit` against the shared default/ceiling. One
+ * implementation so every target clamps identically.
+ */
+export function clampInspectReadLimit(limit: number | undefined): number {
+  if (limit === undefined || limit <= 0) {
+    return INSPECT_READ_DEFAULT_LIMIT;
+  }
+  return Math.min(limit, INSPECT_READ_MAX_LIMIT);
+}

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

@@ -33,11 +33,23 @@ const windowedReadShape = {
   limit: z.number().int().positive().optional(),
 };
 
-export const InspectStepSchema = z.discriminatedUnion('kind', [
+/**
+ * Absolute-URL matcher for `navigate.url`. A deliberate literal scheme check
+ * rather than a generic "is this a URL" helper: the ONLY schemes an inspect
+ * target may open are http(s), and the service re-parses the value anyway.
+ */
+const ABSOLUTE_HTTP_URL = /^https?:\/\//i;
+
+const InspectStepVariantSchema = 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),
+    /**
+     * Origin-relative path, e.g. `/checkout`. Mutually exclusive with `url`
+     * (see the exactly-one refinement below).
+     */
+    path: z.string().min(1).max(2000).optional(),
+    /** Absolute http(s) URL. Only a self-opened target can honour it. */
+    url: z.string().min(1).max(2000).regex(ABSOLUTE_HTTP_URL).optional(),
   }),
   z.object({ kind: z.literal(InspectStepKind.Reload) }),
   z.object({ kind: z.literal(InspectStepKind.Back) }),
@@ -96,6 +108,27 @@ export const InspectStepSchema = z.discriminatedUnion('kind', [
   }),
 ]);
 
+/**
+ * The step validator.
+ *
+ * The `navigate` verb carries EXACTLY ONE of `path` / `url`. That is enforced
+ * here, at the single source of truth, so no executor has to guess what an
+ * empty or doubly-specified navigate means. `path` and `url` are NOT
+ * interchangeable spellings of the same thing: `path` is an in-origin move a
+ * user tab can follow, `url` is an origin change only a self-opened
+ * (headless) target can honour.
+ */
+export const InspectStepSchema = InspectStepVariantSchema.refine(
+  (step) =>
+    step.kind !== InspectStepKind.Navigate ||
+    (step.path === undefined) !== (step.url === undefined),
+  {
+    message:
+      'A "navigate" step must carry exactly one of `path` (origin-relative, e.g. "/checkout") ' +
+      'or `url` (absolute http(s), only honoured by a self-opened target such as "headless").',
+  },
+);
+
 /**
  * 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

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

@@ -5,3 +5,4 @@
 // `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';
+export * from '../lib/buffers';

package/src/search/index.ts

@@ -16,4 +16,5 @@
 // contributed (declarative); INSTANCES are event-fed (runtime).
 // ═══════════════════════════════════════════════════════════════════════════
 
+export * from './lib/route-template';
 export * from './lib/search-contribution';