dsh-agent-team-ui-testing 0.1.1 → 0.1.3

package/core/contracts.js

@@ -0,0 +1,240 @@
+/**
+ * Public contract constants for the cross-environment foundation (v1).
+ *
+ * This module is pure data: no I/O, no clocks, no browser/platform imports. Every constant is
+ * frozen so adapters and the host share one authoritative vocabulary instead of re-declaring
+ * string literals. See docs/internal/cross-environment-foundation-m0.md §2-§5.
+ */
+
+/** Contract version shared by all three adapter classes. A mismatch is ADAPTER_UNSUPPORTED. */
+export const CONTRACT_VERSION = 1;
+
+/** The three adapter classes; each has a different call direction (M0 §2). */
+export const ADAPTER_CLASSES = Object.freeze({
+  TARGET: 'target',
+  CAPABILITY: 'capability',
+  P0: 'p0',
+});
+
+/** Engineering support: does an implementation exist for this environment/capability? */
+export const SUPPORT = Object.freeze({
+  SUPPORTED: 'supported',
+  UNSUPPORTED: 'unsupported',
+  PLANNED: 'planned',
+});
+
+/** Live availability: can the operation run right now? Never conflate with support. */
+export const AVAILABILITY = Object.freeze({
+  AVAILABLE: 'available',
+  UNAVAILABLE: 'unavailable',
+  NOT_PROBED: 'not-probed',
+  BUSY: 'busy',
+});
+
+/** Per-axis readiness statuses. Axes are reported independently, never as one boolean. */
+export const READINESS_STATUS = Object.freeze({
+  OK: 'ok',
+  DEGRADED: 'degraded',
+  FAILED: 'failed',
+  NOT_PROBED: 'not-probed',
+  UNSUPPORTED: 'unsupported',
+  DISABLED: 'disabled',
+  BOUND: 'bound',
+  UNBOUND: 'unbound',
+  STALE: 'stale',
+});
+
+/** The six readiness axes, in report order (M0 §5.2). */
+export const READINESS_AXES = Object.freeze([
+  'support',
+  'enabled',
+  'dependency',
+  'connection',
+  'target',
+  'capability',
+]);
+
+/**
+ * Web runtime providers and their engineering support — the **single truth** for "can this browser
+ * actually execute?".
+ *
+ * - `supported`: a driver exists (chrome).
+ * - `pending`: the user may express intent (`providers.<id>.enabled=true`) but no driver exists yet,
+ *   so it is *not* an implemented provider: registration does not count it, readiness reports
+ *   `not-probed / provider-driver-pending`, execution refuses with ADAPTER_UNSUPPORTED + `driver-pending`.
+ * - `unsupported`: no driver and none planned in this milestone.
+ *
+ * Flipping `edge` to `supported` is the one and only switch point (slice ③, once the vendor launcher,
+ * candidate paths and product-identity check exist). Never add a second "is edge usable?" judgement.
+ */
+export const WEB_PROVIDER_SUPPORT = Object.freeze({
+  chrome: 'supported',
+  // Slice ③: the Edge vendor launcher exists, so `edge` is implemented. **This is the one switch
+  // point** — driver, readiness, registration and execution all derive from this table.
+  edge: 'supported',
+  firefox: 'unsupported',
+});
+
+/**
+ * Machine-readable provider `reason` values. One concept, one spelling: driver refusal, readiness
+ * and tool errors must all use these constants (a `reason` is a detail, never a public error code).
+ */
+export const WEB_PROVIDER_REASONS = Object.freeze({
+  /** A provider whose driver is not wired yet (firefox today). */
+  DRIVER_PENDING: 'driver-pending',
+  /** No such provider id at all. */
+  UNKNOWN_PROVIDER: 'unknown-provider',
+  /** The user (or workspace) switch is off. */
+  PROVIDER_DISABLED: 'provider-disabled',
+  /** The whole target environment is off. */
+  ENVIRONMENT_DISABLED: 'environment-disabled',
+  /** Provider has no driver and none is planned. */
+  PROVIDER_UNSUPPORTED: 'provider-unsupported',
+  /** This provider's executable is missing on this machine. */
+  EXECUTABLE_MISSING: 'executable-missing',
+  /** An explicit override exists but is not usable (never a reason to run another vendor). */
+  OVERRIDE_INVALID: 'override-invalid',
+  /** The launched product gave no identity evidence and the provider needs it (non-chrome). */
+  IDENTITY_UNVERIFIED: 'identity-unverified',
+  /** The launched product identified as a different vendor. */
+  IDENTITY_MISMATCH: 'identity-mismatch',
+});
+
+/**
+ * Product-identity rule per vendor, used after the transport is up ("CDP connected" is not proof).
+ *
+ * `requires`: substrings the `Browser.getVersion.product` string must contain.
+ * `forbids`: substrings that must not appear (chrome must not be an Edge endpoint).
+ * `failClosedOnMissing`: no evidence is a rejection (multi-vendor providers) or tolerated
+ * (chrome, whose already-accepted startup path must not gain a new failure mode).
+ * A new vendor is one line here — never another if/else in the driver.
+ */
+export const WEB_PROVIDER_VENDOR = Object.freeze({
+  chrome: Object.freeze({ requires: Object.freeze(['Chrome/']), forbids: Object.freeze(['Edg/']), failClosedOnMissing: false }),
+  edge: Object.freeze({ requires: Object.freeze(['Edg/']), forbids: Object.freeze([]), failClosedOnMissing: true }),
+});
+
+/**
+ * Profile directory suffix per provider: Chrome and Edge must never share a headed profile.
+ */
+export const WEB_PROVIDER_PROFILE_SUFFIX = Object.freeze({ chrome: 'chrome', edge: 'edge', firefox: 'firefox' });
+
+/** Known environments. Only web/fake have implementations in this milestone. */
+export const ENVIRONMENTS = Object.freeze({
+  WEB: 'web',
+  FAKE: 'fake',
+  LINUX: 'linux-desktop',
+  ANDROID: 'android',
+  MINIPROGRAM: 'mini-program',
+});
+
+/**
+ * Canonical capability ids per environment. This is the adapter catalog: it is intentionally
+ * independent from `enabledEnvironments`, which only decides whether an environment may be used.
+ */
+export const ENVIRONMENT_CAPABILITIES = Object.freeze({
+  web: Object.freeze([
+    'web.t1',
+    'web.t2',
+    'web.t3',
+    'web.t4',
+    'web.network',
+    'web.tabs',
+    // P0-D annotations (docs/viewport-control.md): the Agent annotation write surface.
+    'web.p0.annotations',
+    'web.p0.capture',
+    'web.p0.network',
+    'web.p0.display',
+    'web.p0.canvas',
+    'web.p0.targets',
+  ]),
+  fake: Object.freeze([
+    'fake.t1',
+    'fake.t2',
+    'fake.t3',
+    'fake.network',
+    'fake.p0.capture',
+    'fake.p0.network',
+    'fake.p0.display',
+    'fake.p0.canvas',
+    'fake.p0.targets',
+  ]),
+});
+
+/** Named capability ids used by tools/readiness. `p0.network` is part of the adapter catalog. */
+export const CAPABILITY_IDS = Object.freeze({
+  WEB: Object.freeze({
+    T1: 'web.t1',
+    T2: 'web.t2',
+    T3: 'web.t3',
+    T4: 'web.t4',
+    NETWORK: 'web.network',
+    TABS: 'web.tabs',
+    ANNOTATIONS: 'web.p0.annotations',
+    CAPTURE: 'web.p0.capture',
+    DISPLAY: 'web.p0.display',
+    CANVAS: 'web.p0.canvas',
+    TARGETS: 'web.p0.targets',
+  }),
+  FAKE: Object.freeze({
+    T1: 'fake.t1',
+    T2: 'fake.t2',
+    T3: 'fake.t3',
+    NETWORK: 'fake.network',
+    CAPTURE: 'fake.p0.capture',
+    DISPLAY: 'fake.p0.display',
+    CANVAS: 'fake.p0.canvas',
+    TARGETS: 'fake.p0.targets',
+  }),
+});
+
+/** Stable machine error codes. Unknown codes normalize to INTERNAL in core/errors.js. */
+export const ERROR_CODES = Object.freeze({
+  ADAPTER_NOT_FOUND: 'ADAPTER_NOT_FOUND',
+  ADAPTER_UNSUPPORTED: 'ADAPTER_UNSUPPORTED',
+  ADAPTER_DISABLED: 'ADAPTER_DISABLED',
+  CONFIG_CONFLICT: 'CONFIG_CONFLICT',
+  CONFIG_INVALID: 'CONFIG_INVALID',
+  CONFIG_STALE: 'CONFIG_STALE',
+  TARGET_NOT_BOUND: 'TARGET_NOT_BOUND',
+  TARGET_GONE: 'TARGET_GONE',
+  GENERATION_MISMATCH: 'GENERATION_MISMATCH',
+  CAPABILITY_UNSUPPORTED: 'CAPABILITY_UNSUPPORTED',
+  CAPABILITY_UNAVAILABLE: 'CAPABILITY_UNAVAILABLE',
+  DEPENDENCY_MISSING: 'DEPENDENCY_MISSING',
+  CONNECTION_UNTRUSTED: 'CONNECTION_UNTRUSTED',
+  PROBE_TIMEOUT: 'PROBE_TIMEOUT',
+  PROVIDER_UNAVAILABLE: 'PROVIDER_UNAVAILABLE',
+  EVIDENCE_INCOMPLETE: 'EVIDENCE_INCOMPLETE',
+  FORBIDDEN: 'FORBIDDEN',
+  // Team/page access model (M1, ruling §7.3). Registered here as well as in ERROR_TAXONOMY so
+  // the constant table and the classification table cannot drift apart: a code that exists in one
+  // and not the other is exactly how a permission refusal ends up reported as INTERNAL.
+  TAB_FORBIDDEN: 'TAB_FORBIDDEN',
+  TAB_NOT_FOUND: 'TAB_NOT_FOUND',
+  TAB_LIMIT: 'TAB_LIMIT',
+  TAB_CONTROL_CHANGED: 'TAB_CONTROL_CHANGED',
+  TAB_OWNERSHIP_STALE: 'TAB_OWNERSHIP_STALE',
+  TAB_IDENTITY_UNAVAILABLE: 'TAB_IDENTITY_UNAVAILABLE',
+  TAB_OBSERVATION_STALE: 'TAB_OBSERVATION_STALE',
+  OBSERVATION_UNAVAILABLE: 'OBSERVATION_UNAVAILABLE',
+  RUNTIME_LIMIT: 'RUNTIME_LIMIT',
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  OUTPUT_WRITE_FAILED: 'OUTPUT_WRITE_FAILED',
+  INTERNAL: 'INTERNAL',
+});
+
+/** All known capability ids as a lookup set (web + fake adapter catalogs). */
+const CAPABILITY_ID_SET = new Set(
+  Object.values(ENVIRONMENT_CAPABILITIES).flatMap((ids) => ids),
+);
+
+/**
+ * True when `id` is a capability id declared by a shipped adapter catalog.
+ *
+ * Deliberately membership-based: an arbitrary dotted string is not a capability. New
+ * environments must add their catalog above before their ids become valid.
+ */
+export function isCapabilityId(id) {
+  return typeof id === 'string' && CAPABILITY_ID_SET.has(id);
+}

package/core/errors.js

@@ -0,0 +1,156 @@
+/**
+ * Normalized error type for the cross-environment foundation.
+ *
+ * Adapters may throw anything; callers branch on `code`/`category`/`retryable` instead of message
+ * text. Unknown codes degrade to INTERNAL without losing the original message or details.
+ */
+import { ERROR_CODES } from './contracts.js';
+
+/** Error categories shared by every adapter class. */
+export const ERROR_CATEGORIES = Object.freeze({
+  INPUT: 'input',
+  STATE: 'state',
+  CAPABILITY: 'capability',
+  ENVIRONMENT: 'environment',
+  CONFIG: 'config',
+  TARGET: 'target',
+  EVIDENCE: 'evidence',
+  // `authorization` is deliberately its own category (ruling §7.3): "you may not do this" is a
+  // policy answer, not a broken capability and not a bug. Folding it into `capability` would make
+  // a permission refusal indistinguishable from "this browser cannot do that at all".
+  AUTHORIZATION: 'authorization',
+  // `resource` is a declared budget (4/8 pages, 32 metadata entries), which is a capacity answer
+  // rather than a target answer, so it never collapses into `target`.
+  RESOURCE: 'resource',
+  INTERNAL: 'internal',
+});
+
+/**
+ * code -> [category, retryable]. Retryable means "the same call may succeed later" (busy,
+ * timeout, gone target), not "the input was wrong".
+ */
+export const ERROR_TAXONOMY = Object.freeze({
+  ADAPTER_NOT_FOUND: [ERROR_CATEGORIES.ENVIRONMENT, false],
+  ADAPTER_UNSUPPORTED: [ERROR_CATEGORIES.CAPABILITY, false],
+  ADAPTER_DISABLED: [ERROR_CATEGORIES.CONFIG, false],
+  CONFIG_CONFLICT: [ERROR_CATEGORIES.CONFIG, true],
+  CONFIG_INVALID: [ERROR_CATEGORIES.CONFIG, false],
+  CONFIG_STALE: [ERROR_CATEGORIES.CONFIG, true],
+  TARGET_NOT_BOUND: [ERROR_CATEGORIES.TARGET, false],
+  TARGET_GONE: [ERROR_CATEGORIES.TARGET, true],
+  GENERATION_MISMATCH: [ERROR_CATEGORIES.STATE, false],
+  CAPABILITY_UNSUPPORTED: [ERROR_CATEGORIES.CAPABILITY, false],
+  CAPABILITY_UNAVAILABLE: [ERROR_CATEGORIES.ENVIRONMENT, true],
+  DEPENDENCY_MISSING: [ERROR_CATEGORIES.ENVIRONMENT, false],
+  CONNECTION_UNTRUSTED: [ERROR_CATEGORIES.ENVIRONMENT, true],
+  PROBE_TIMEOUT: [ERROR_CATEGORIES.ENVIRONMENT, true],
+  PROVIDER_UNAVAILABLE: [ERROR_CATEGORIES.ENVIRONMENT, true],
+  EVIDENCE_INCOMPLETE: [ERROR_CATEGORIES.EVIDENCE, false],
+  FORBIDDEN: [ERROR_CATEGORIES.CAPABILITY, false],
+  // Team/page access model (M1, ruling §7.3). These are *classified* answers, so they must be
+  // registered here: `AdapterError` normalizes an unknown code to INTERNAL, which would turn a
+  // permission or staleness refusal into "the plugin is broken" for every caller that branches on
+  // `category`. The three legacy tab codes were only known to browser-safety.js and degraded to
+  // INTERNAL on this side; registering them here is the missing half of the same table.
+  TAB_FORBIDDEN: [ERROR_CATEGORIES.AUTHORIZATION, false],
+  TAB_NOT_FOUND: [ERROR_CATEGORIES.TARGET, false],
+  TAB_LIMIT: [ERROR_CATEGORIES.RESOURCE, false],
+  TAB_CONTROL_CHANGED: [ERROR_CATEGORIES.STATE, false],
+  TAB_OWNERSHIP_STALE: [ERROR_CATEGORIES.STATE, false],
+  TAB_IDENTITY_UNAVAILABLE: [ERROR_CATEGORIES.AUTHORIZATION, false],
+  TAB_OBSERVATION_STALE: [ERROR_CATEGORIES.STATE, true],
+  OBSERVATION_UNAVAILABLE: [ERROR_CATEGORIES.CAPABILITY, false],
+  RUNTIME_LIMIT: [ERROR_CATEGORIES.RESOURCE, true],
+  INVALID_ARGUMENT: [ERROR_CATEGORIES.INPUT, false],
+  OUTPUT_WRITE_FAILED: [ERROR_CATEGORIES.INTERNAL, true],
+  INTERNAL: [ERROR_CATEGORIES.INTERNAL, false],
+});
+
+const OPTION_KEYS = new Set(['category', 'retryable', 'details', 'cause']);
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeCode(code) {
+  return typeof code === 'string' && Object.hasOwn(ERROR_TAXONOMY, code)
+    ? code
+    : ERROR_CODES.INTERNAL;
+}
+
+/**
+ * Error thrown by core helpers and adapters.
+ *
+ * @param {string} code Stable machine code; unknown codes become INTERNAL.
+ * @param {string} [message] Human-readable message. When omitted, a code-derived message is used.
+ * @param {object} [detailsOrOptions] Either a plain details object, or
+ *   `{category, retryable, details, cause}`. A bare object containing any of those keys is
+ *   treated as options; anything else is treated as `details`.
+ */
+export class AdapterError extends Error {
+  constructor(code = ERROR_CODES.INTERNAL, message, detailsOrOptions) {
+    const known = typeof code === 'string' && Object.hasOwn(ERROR_TAXONOMY, code);
+    const normalized = normalizeCode(code);
+    const [defaultCategory, defaultRetryable] = ERROR_TAXONOMY[normalized];
+
+    const looksLikeOptions = isPlainObject(detailsOrOptions)
+      && Object.keys(detailsOrOptions).some((key) => OPTION_KEYS.has(key));
+    const options = looksLikeOptions ? detailsOrOptions : {};
+    const bareDetails = isPlainObject(detailsOrOptions) && !looksLikeOptions
+      ? detailsOrOptions
+      : undefined;
+
+    const details = options.details !== undefined ? options.details : bareDetails;
+    const resolvedMessage = typeof message === 'string' && message.length > 0
+      ? message
+      : `${normalized}${details === undefined ? '' : ': operation failed'}`;
+
+    super(resolvedMessage);
+    this.name = 'AdapterError';
+    this.code = normalized;
+    this.category = options.category ?? defaultCategory;
+    this.retryable = options.retryable ?? defaultRetryable;
+    this.details = details === undefined ? {} : details;
+    if (!known && typeof code === 'string' && code.length > 0) {
+      // Preserve what the caller asked for without pretending it is a supported code.
+      this.details = { ...this.details, requestedCode: code };
+    }
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+
+  /** JSON-safe representation; `cause` is summarized rather than serialized. */
+  payload() {
+    const payload = {
+      name: this.name,
+      code: this.code,
+      category: this.category,
+      retryable: this.retryable,
+      message: this.message,
+      details: this.details ?? {},
+    };
+    if (this.cause !== undefined) {
+      payload.cause = this.cause instanceof Error
+        ? { name: this.cause.name, message: this.cause.message }
+        : String(this.cause);
+    }
+    return payload;
+  }
+}
+
+/**
+ * Coerce any thrown value into an AdapterError.
+ *
+ * - AdapterError passes through unchanged (the original code is preserved).
+ * - Error keeps its message and gains `details.causeName`.
+ * - Any other value is stringified, never silently dropped.
+ */
+export function asAdapterError(error, fallbackCode = ERROR_CODES.INTERNAL) {
+  if (error instanceof AdapterError) return error;
+  if (error instanceof Error) {
+    return new AdapterError(fallbackCode, error.message, {
+      details: { causeName: error.name },
+      cause: error,
+    });
+  }
+  return new AdapterError(fallbackCode, String(error));
+}

package/core/evidence.js

@@ -0,0 +1,141 @@
+/**
+ * Evidence envelopes and a bounded in-memory store.
+ *
+ * Every observation must be traceable to scope/session/target/generation/configRevision/
+ * operation/source/capturedAt. The store is intentionally memory-only: writing evidence files is
+ * the host's job, not a pure core concern.
+ */
+import { CONTRACT_VERSION, ERROR_CODES } from './contracts.js';
+import { AdapterError } from './errors.js';
+
+/** Required envelope keys (values may be null where the concept genuinely does not exist). */
+export const EVIDENCE_REQUIRED_FIELDS = Object.freeze([
+  'version',
+  'scope',
+  'session',
+  'target',
+  'generation',
+  'configRevision',
+  'operation',
+  'source',
+  'capturedAt',
+]);
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {{scope?:object, session?:object, target?:object|null, generation?:number|null,
+ *   configRevision?:number|null, operation?:object, source?:object, capturedAt?:number|null,
+ *   extra?:object}} [input]
+ */
+export function createEvidenceEnvelope({
+  scope = null,
+  session = null,
+  target = null,
+  generation = null,
+  configRevision = null,
+  operation = null,
+  source = null,
+  capturedAt = null,
+  extra,
+} = {}) {
+  const extras = isPlainObject(extra) ? extra : {};
+  return {
+    ...extras,
+    version: CONTRACT_VERSION,
+    scope,
+    session,
+    target,
+    generation,
+    configRevision,
+    operation,
+    source,
+    capturedAt,
+  };
+}
+
+/** Shallow-merge a patch into an envelope; the version stays fixed at CONTRACT_VERSION. */
+export function mergeEvidence(base, patch) {
+  const left = isPlainObject(base) ? base : {};
+  const right = isPlainObject(patch) ? patch : {};
+  const merged = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    if (value !== undefined) merged[key] = value;
+  }
+  merged.version = CONTRACT_VERSION;
+  return merged;
+}
+
+/**
+ * @returns {{ok:boolean, missing:string[]}} `missing` lists required keys that are absent or
+ *   explicitly undefined; explicit `null` is accepted (e.g. an unbound target).
+ */
+export function validateEvidence(envelope) {
+  if (!isPlainObject(envelope)) {
+    return { ok: false, missing: [...EVIDENCE_REQUIRED_FIELDS] };
+  }
+  const missing = EVIDENCE_REQUIRED_FIELDS.filter(
+    (field) => !Object.hasOwn(envelope, field) || envelope[field] === undefined,
+  );
+  return { ok: missing.length === 0, missing };
+}
+
+let storeCounter = 0;
+
+/**
+ * Bounded FIFO evidence store.
+ *
+ * `add` assigns an `evidenceId` when absent; `get` looks it up. No file I/O and no implicit
+ * timestamps.
+ */
+export class EvidenceStore {
+  constructor({ limit = 256 } = {}) {
+    if (!Number.isInteger(limit) || limit <= 0) {
+      throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, 'EvidenceStore limit must be a positive integer', {
+        details: { field: 'limit', value: Number.isFinite(limit) ? limit : null },
+      });
+    }
+    this.limit = limit;
+    this._entries = [];
+    this._byId = new Map();
+  }
+
+  /** Store an envelope; oldest entries are evicted once the limit is exceeded. */
+  add(envelope) {
+    if (!isPlainObject(envelope)) {
+      throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, 'evidence envelope must be an object', {
+        details: { field: 'envelope' },
+      });
+    }
+    const evidenceId = typeof envelope.evidenceId === 'string' && envelope.evidenceId.length > 0
+      ? envelope.evidenceId
+      : `ev-${++storeCounter}`;
+    const entry = { ...envelope, evidenceId };
+    this._entries.push(entry);
+    this._byId.set(evidenceId, entry);
+    while (this._entries.length > this.limit) {
+      const evicted = this._entries.shift();
+      this._byId.delete(evicted.evidenceId);
+    }
+    return entry;
+  }
+
+  get(evidenceId) {
+    return this._byId.get(evidenceId);
+  }
+
+  list() {
+    return [...this._entries];
+  }
+
+  clear() {
+    this._entries = [];
+    this._byId.clear();
+  }
+
+  get size() {
+    return this._entries.length;
+  }
+}