@xemahq/kernel-contracts 0.50.0 → 0.57.0

package/src/object/lib/xema-object-ref.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
-import { SpaceRef, SpaceKind, spaceRefToPath } from '../../space';
+import {
+  parseSpaceRefScopeSegments,
+  SpaceRef,
+  SpaceRefParseError,
+  spaceRefToPath,
+} from '../../space';
 import { XemaObjectKind, XemaObjectKindSchema } from './xema-object-kind';
 
 /**
@@ -69,9 +74,26 @@ const SLUG_SEGMENT = '[a-zA-Z0-9][a-zA-Z0-9_.-]*';
 const SLUG_PATTERN = new RegExp(`^${SLUG_SEGMENT}(?:/${SLUG_SEGMENT})*$`);
 const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.+-]*$/;
 
-export interface ScopeParse {
-  scope: SpaceRef;
-  consumed: number;
+/**
+ * Consume the leading scope segments of a `xema://` object ref, re-raising any
+ * scope-grammar failure as a {@link XemaObjectRefParseError} so an object-ref
+ * caller only ever has to catch ONE error type. The scope grammar itself lives
+ * in `@xemahq/kernel-contracts/space` (`parseSpaceRefScopeSegments`) — it is a
+ * SPACE grammar, and object refs, search refs and Space refs all read it from
+ * there rather than restating it.
+ */
+function parseScope(
+  segments: string[],
+  ref: string,
+): { scope: SpaceRef; consumed: number } {
+  try {
+    return parseSpaceRefScopeSegments(segments, ref);
+  } catch (err) {
+    if (err instanceof SpaceRefParseError) {
+      throw new XemaObjectRefParseError(ref, err.message);
+    }
+    throw err;
+  }
 }
 
 function requireSegment(
@@ -87,83 +109,6 @@ function requireSegment(
   return value;
 }
 
-/**
- * Parse the leading scope segments of a `xema://` ref path into a
- * {@link SpaceRef} plus the number of segments consumed. Shared by
- * {@link parseXemaObjectRef} and the search-source `parseSearchRef` helper so
- * the `xema://<scope-path>/...` scope grammar (plural `orgs`/`projects`, the
- * same one {@link spaceRefToPath} formats) lives in exactly ONE place. The
- * caller owns whatever follows the scope (a `<kind>/<slug>` for objects, a
- * `<docType>/<sourceId>` for search refs).
- */
-export function parseObjectRefScopeSegments(
-  segments: string[],
-  ref: string,
-): ScopeParse {
-  const head = requireSegment(segments, 0, ref, 'scope');
-  switch (head) {
-    case 'system':
-      return { scope: { tier: SpaceKind.System }, consumed: 1 };
-    case 'biomes': {
-      const biomeId = requireSegment(segments, 1, ref, 'biomeId');
-      return {
-        scope: { tier: SpaceKind.Biome, biomeId },
-        consumed: 2,
-      };
-    }
-    case 'users': {
-      const userId = requireSegment(segments, 1, ref, 'userId');
-      return {
-        scope: { tier: SpaceKind.User, userId },
-        consumed: 2,
-      };
-    }
-    case 'sessions': {
-      const sessionId = requireSegment(segments, 1, ref, 'sessionId');
-      return {
-        scope: { tier: SpaceKind.Session, sessionId },
-        consumed: 2,
-      };
-    }
-    case 'orgs': {
-      const orgId = requireSegment(segments, 1, ref, 'orgId');
-      if (segments.length >= 4 && segments[2] === 'projects') {
-        const projectId = requireSegment(segments, 3, ref, 'projectId');
-        // …/projects/<p>/apps/<a> — the App tier (most specific under a project).
-        if (segments.length >= 6 && segments[4] === 'apps') {
-          const appId = requireSegment(segments, 5, ref, 'appId');
-          return {
-            scope: {
-              tier: SpaceKind.App,
-              orgId,
-              projectId,
-              appId,
-            },
-            consumed: 6,
-          };
-        }
-        return {
-          scope: {
-            tier: SpaceKind.Project,
-            orgId,
-            projectId,
-          },
-          consumed: 4,
-        };
-      }
-      return {
-        scope: { tier: SpaceKind.Org, orgId },
-        consumed: 2,
-      };
-    }
-    default:
-      throw new XemaObjectRefParseError(
-        ref,
-        `unknown scope head "${head}" (expected one of: system, biomes, orgs, users, sessions)`,
-      );
-  }
-}
-
 /**
  * Parse a `XemaObjectRef` into structured parts. Fail-fast on every
  * malformed input (no silent coercion). When the `@<version>` suffix
@@ -210,7 +155,7 @@ export function parseXemaObjectRef(ref: string): XemaObjectRefParts {
     );
   }
 
-  const { scope, consumed } = parseObjectRefScopeSegments(segments, ref);
+  const { scope, consumed } = parseScope(segments, ref);
   const remaining = segments.slice(consumed);
   if (remaining.length < 2) {
     throw new XemaObjectRefParseError(

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

@@ -1,4 +1,6 @@
 // Pure, zod-free contract — safe to bundle into the browser-side bridge.
 export * from './lib/output-surface-inspect';
+// Shared bounded console/network ring buffers (also zod-free).
+export * from './lib/buffers';
 // Runtime zod validator — pulled in by agent-session-api's broker only.
 export * from './lib/step-schema';

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';