@agent-surface/core 0.1.0

package/dist/index.js

@@ -0,0 +1,3271 @@
+// src/types.ts
+var DEFAULT_LIMITS = {
+  maxComponentDescription: 500,
+  maxCapabilityDescription: 300,
+  maxMetaBytes: 2048,
+  maxOutputBytes: 32768,
+  maxSchemaBytes: 16384,
+  maxSchemaDepth: 8,
+  observationTimeoutMs: 5e3,
+  actionTimeoutMs: 1e4,
+  procedureTimeoutMs: 3e4,
+  actionQueueDepth: 2,
+  maxConcurrentObservationsPerConsumer: 8,
+  maxConcurrentObservationsTotal: 32,
+  maxQueuedObservationsPerConsumer: 8,
+  dedupeCacheSize: 200,
+  dedupeCacheTtlMs: 6e5,
+  tombstoneSize: 100,
+  tombstoneTtlMs: 3e5,
+  confirmationTtlMs: 12e4,
+  maxPendingConfirmations: 32
+};
+
+// src/errors.ts
+var AGENT_CAPABILITY_ERROR_CODES = [
+  "CAPABILITY_NOT_FOUND",
+  "CAPABILITY_NOT_AVAILABLE",
+  "AMBIGUOUS_INSTANCE",
+  "COMPONENT_UNMOUNTED",
+  "STALE_CAPABILITY",
+  "INVOCATION_CONFLICT",
+  "INVALID_INPUT",
+  "NOT_AUTHENTICATED",
+  "NOT_AUTHORIZED",
+  "PRECONDITION_FAILED",
+  "CONFIRMATION_REQUIRED",
+  "CONFIRMATION_INVALID",
+  "RATE_LIMITED",
+  "TIMEOUT",
+  "CANCELLED",
+  "EXECUTION_FAILED"
+];
+var AgentSurfaceError = class extends Error {
+  payload;
+  constructor(payload, opts) {
+    super(payload.message, opts);
+    this.name = "AgentSurfaceError";
+    this.payload = payload;
+  }
+};
+function isAgentSurfaceError(e) {
+  return e instanceof AgentSurfaceError || typeof e === "object" && e !== null && e.name === "AgentSurfaceError" && typeof e.payload === "object";
+}
+var AgentSurfaceDefinitionError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`[${code}] ${message}`);
+    this.name = "AgentSurfaceDefinitionError";
+    this.code = code;
+  }
+};
+
+// src/ids.ts
+var MAX_ID_LENGTH = 128;
+var SEGMENT_RE = /^[a-z][a-z0-9-]*$/;
+var CAPABILITY_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
+var INSTANCE_ID_RE = /^[A-Za-z0-9_-]+$/;
+function isValidComponentType(type) {
+  if (type.length === 0 || type.length > MAX_ID_LENGTH) return false;
+  return type.split(".").every((seg) => SEGMENT_RE.test(seg));
+}
+function isValidCapabilityName(name) {
+  return CAPABILITY_NAME_RE.test(name);
+}
+function isValidInstanceId(id) {
+  return id.length > 0 && id.length <= MAX_ID_LENGTH && INSTANCE_ID_RE.test(id);
+}
+function formatViewCapabilityId(componentType, name) {
+  return `view:${componentType}.${name}`;
+}
+function formatDomainCapabilityId(path) {
+  return `domain:${path}`;
+}
+function parseCapabilityId(id) {
+  if (id.length > MAX_ID_LENGTH) return void 0;
+  if (id.startsWith("view:")) {
+    const rest = id.slice("view:".length);
+    const lastDot = rest.lastIndexOf(".");
+    if (lastDot <= 0) return void 0;
+    const componentType = rest.slice(0, lastDot);
+    const name = rest.slice(lastDot + 1);
+    if (!isValidComponentType(componentType) || !isValidCapabilityName(name)) {
+      return void 0;
+    }
+    return { plane: "view", componentType, name };
+  }
+  if (id.startsWith("domain:")) {
+    const path = id.slice("domain:".length);
+    if (path.length === 0) return void 0;
+    return { plane: "domain", path };
+  }
+  return void 0;
+}
+var MAX_WIRE_NAME_LENGTH = 64;
+function fnv1aHash36(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(36).padStart(7, "0").slice(0, 7);
+}
+function encodeWireName(id) {
+  return encodeWireNameForInstance(id);
+}
+function encodeWireNameForInstance(id, instanceId) {
+  const raw = id.replace(":", "_").replaceAll(".", "__") + (instanceId ? `_at_${instanceId}` : "");
+  if (raw.length <= MAX_WIRE_NAME_LENGTH) return raw;
+  return `${raw.slice(0, 56)}_${fnv1aHash36(`${id}#${instanceId ?? ""}`)}`;
+}
+function decodeWireName(name) {
+  const planeEnd = name.indexOf("_");
+  if (planeEnd <= 0) return void 0;
+  const plane = name.slice(0, planeEnd);
+  if (plane !== "view" && plane !== "domain") return void 0;
+  const rest = name.slice(planeEnd + 1).replaceAll("__", ".");
+  return `${plane}:${rest}`;
+}
+
+// src/utils.ts
+function jsonDeepEqual(a, b) {
+  if (a === b) return true;
+  if (a === void 0 || b === void 0) return false;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => jsonDeepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    return ka.length === kb.length && ka.every(
+      (k, i) => k === kb[i] && jsonDeepEqual(
+        a[k],
+        b[k]
+      )
+    );
+  }
+  return false;
+}
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const key of Object.keys(value)) {
+      deepFreeze(value[key]);
+    }
+  }
+  return value;
+}
+function jsonClone(value) {
+  return value === void 0 ? value : JSON.parse(JSON.stringify(value));
+}
+function isJsonValue(value, depth = 0) {
+  if (depth > 64) return false;
+  if (value === null) return true;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((v) => isJsonValue(v, depth + 1));
+  if (t === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return false;
+    return Object.values(value).every(
+      (v) => v === void 0 || isJsonValue(v, depth + 1)
+    );
+  }
+  return false;
+}
+function byteLength(value) {
+  const s = JSON.stringify(value);
+  return s === void 0 ? 0 : s.length;
+}
+var ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function randomBase62(length) {
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += ALPHABET[Math.floor(Math.random() * ALPHABET.length)];
+  }
+  return out;
+}
+function truncate(s, max) {
+  return s.length <= max ? s : s.slice(0, Math.max(0, max - 1)) + "\u2026";
+}
+function canonicalJson(value) {
+  if (value === void 0 || value === null) return "null";
+  const t = typeof value;
+  if (t === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("canonicalJson: non-finite numbers are not JsonValues");
+    }
+    return JSON.stringify(Object.is(value, -0) ? 0 : value);
+  }
+  if (t === "string" || t === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalJson(v ?? null)).join(",")}]`;
+  }
+  const entries = Object.keys(value).sort().filter((k) => value[k] !== void 0).map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`);
+  return `{${entries.join(",")}}`;
+}
+function fnv1a64(input) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = hash * prime & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// src/schema.ts
+var AgentSchemaError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(issues.map((i) => `${i.path || "$"}: ${i.message}`).join("; ") || "Invalid value");
+    this.name = "AgentSchemaError";
+    this.issues = issues;
+  }
+};
+function fromStandardSchema(schema, options) {
+  return {
+    jsonSchema: options.jsonSchema,
+    parse(value) {
+      const result = schema["~standard"].validate(value);
+      if (result instanceof Promise) {
+        throw new AgentSchemaError([
+          { path: "", message: "Async schema validation is not supported in v0.1" }
+        ]);
+      }
+      if (result.issues) {
+        throw new AgentSchemaError(
+          result.issues.map((issue) => ({
+            path: (issue.path ?? []).map((p) => String(typeof p === "object" && p !== null && "key" in p ? p.key : p)).join("."),
+            message: issue.message
+          }))
+        );
+      }
+      return result.value;
+    }
+  };
+}
+function fromJsonSchema(schema) {
+  return {
+    jsonSchema: schema,
+    parse(value) {
+      const issues = validateValueAgainstSchema(value, schema, schema, "");
+      if (issues.length > 0) throw new AgentSchemaError(issues);
+      return value;
+    }
+  };
+}
+var emptyObjectSchema = fromJsonSchema({
+  type: "object",
+  properties: {},
+  additionalProperties: false
+});
+var ALLOWED_KEYWORDS = /* @__PURE__ */ new Set([
+  "type",
+  "enum",
+  "const",
+  // objects
+  "properties",
+  "required",
+  "additionalProperties",
+  // arrays
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  // strings
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  // numbers
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  // unions
+  "anyOf",
+  // annotations
+  "description",
+  "default",
+  "examples",
+  "title",
+  "deprecated",
+  // refs
+  "$defs",
+  "$ref",
+  // tolerated (converter noise), ignored at validation time
+  "$schema",
+  "$id"
+]);
+var REJECTED_KEYWORDS = /* @__PURE__ */ new Set([
+  "oneOf",
+  "allOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "patternProperties",
+  "dependentRequired",
+  "dependentSchemas",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "prefixItems",
+  "contains",
+  "propertyNames"
+]);
+var ALLOWED_TYPES = /* @__PURE__ */ new Set([
+  "object",
+  "array",
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "null"
+]);
+var ALLOWED_FORMATS = /* @__PURE__ */ new Set(["date-time", "date", "uuid", "email", "uri"]);
+function validateJsonSchemaDocument(schema, limits) {
+  const size = byteLength(schema);
+  if (size > limits.maxSchemaBytes) {
+    return { ok: false, reason: `schema serializes to ${size} bytes (max ${limits.maxSchemaBytes})` };
+  }
+  return walkSchemaDocument(schema, "", 0, limits.maxSchemaDepth);
+}
+function walkSchemaDocument(node, path, depth, maxDepth) {
+  if (depth > maxDepth) {
+    return { ok: false, reason: `schema nesting exceeds depth ${maxDepth} at ${path || "$"}` };
+  }
+  if (typeof node === "boolean") {
+    return { ok: false, reason: `boolean schema not supported at ${path || "$"}` };
+  }
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    return { ok: false, reason: `schema must be an object at ${path || "$"}` };
+  }
+  const obj = node;
+  for (const key of Object.keys(obj)) {
+    if (REJECTED_KEYWORDS.has(key) || !ALLOWED_KEYWORDS.has(key)) {
+      return { ok: false, reason: `unsupported keyword "${key}" at ${path || "$"}` };
+    }
+  }
+  if ("$ref" in obj) {
+    const ref = obj.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#/$defs/")) {
+      return { ok: false, reason: `only internal "#/$defs/..." refs are supported at ${path || "$"}` };
+    }
+  }
+  if ("type" in obj) {
+    const t = obj.type;
+    const types = Array.isArray(t) ? t : [t];
+    for (const one of types) {
+      if (typeof one !== "string" || !ALLOWED_TYPES.has(one)) {
+        return { ok: false, reason: `unsupported type "${String(one)}" at ${path || "$"}` };
+      }
+    }
+  }
+  if ("format" in obj) {
+    const f = obj.format;
+    if (typeof f !== "string" || !ALLOWED_FORMATS.has(f)) {
+      return { ok: false, reason: `unsupported format "${String(obj.format)}" at ${path || "$"}` };
+    }
+  }
+  if ("additionalProperties" in obj && typeof obj.additionalProperties !== "boolean") {
+    return {
+      ok: false,
+      reason: `additionalProperties must be a boolean at ${path || "$"}`
+    };
+  }
+  if ("items" in obj) {
+    if (Array.isArray(obj.items)) {
+      return { ok: false, reason: `tuple "items" arrays are not supported at ${path || "$"}` };
+    }
+    const r = walkSchemaDocument(obj.items, `${path}.items`, depth + 1, maxDepth);
+    if (!r.ok) return r;
+  }
+  if ("properties" in obj) {
+    const props = obj.properties;
+    if (typeof props !== "object" || props === null || Array.isArray(props)) {
+      return { ok: false, reason: `properties must be an object at ${path || "$"}` };
+    }
+    for (const [name, sub] of Object.entries(props)) {
+      const r = walkSchemaDocument(sub, `${path}.properties.${name}`, depth + 1, maxDepth);
+      if (!r.ok) return r;
+    }
+  }
+  if ("anyOf" in obj) {
+    if (!Array.isArray(obj.anyOf) || obj.anyOf.length === 0) {
+      return { ok: false, reason: `anyOf must be a non-empty array at ${path || "$"}` };
+    }
+    for (let i = 0; i < obj.anyOf.length; i++) {
+      const r = walkSchemaDocument(obj.anyOf[i], `${path}.anyOf[${i}]`, depth + 1, maxDepth);
+      if (!r.ok) return r;
+    }
+  }
+  if ("$defs" in obj) {
+    const defs = obj.$defs;
+    if (typeof defs !== "object" || defs === null || Array.isArray(defs)) {
+      return { ok: false, reason: `$defs must be an object at ${path || "$"}` };
+    }
+    for (const [name, sub] of Object.entries(defs)) {
+      const r = walkSchemaDocument(sub, `${path}.$defs.${name}`, depth + 1, maxDepth);
+      if (!r.ok) return r;
+    }
+  }
+  return { ok: true };
+}
+var FORMAT_VALIDATORS = {
+  "date-time": (s) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/.test(s),
+  date: (s) => /^\d{4}-\d{2}-\d{2}$/.test(s),
+  uuid: (s) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s),
+  email: (s) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s),
+  uri: (s) => /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(s)
+};
+function typeOfValue(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  const t = typeof value;
+  if (t === "number") return "number";
+  return t;
+}
+function matchesType(value, type) {
+  switch (type) {
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    default:
+      return false;
+  }
+}
+function validateValueAgainstSchema(value, schema, root, path) {
+  if (typeof schema !== "object" || schema === null) return [];
+  let node = schema;
+  if (typeof node.$ref === "string") {
+    const ref = node.$ref;
+    const defName = ref.slice("#/$defs/".length);
+    const defs = root.$defs;
+    const resolved = defs?.[defName];
+    if (typeof resolved !== "object" || resolved === null) {
+      return [{ path, message: `unresolvable $ref "${ref}"` }];
+    }
+    node = resolved;
+  }
+  const issues = [];
+  if ("const" in node) {
+    if (!jsonDeepEqual(value, node.const)) {
+      issues.push({ path, message: `must equal the constant ${JSON.stringify(node.const)}` });
+      return issues;
+    }
+  }
+  if (Array.isArray(node.enum)) {
+    const ok = node.enum.some((candidate) => jsonDeepEqual(value, candidate));
+    if (!ok) {
+      issues.push({ path, message: `must be one of ${JSON.stringify(node.enum)}` });
+      return issues;
+    }
+  }
+  if (Array.isArray(node.anyOf)) {
+    const anyOk = node.anyOf.some(
+      (branch) => validateValueAgainstSchema(value, branch, root, path).length === 0
+    );
+    if (!anyOk) {
+      issues.push({ path, message: "does not match any allowed variant" });
+      return issues;
+    }
+  }
+  if ("type" in node) {
+    const types = Array.isArray(node.type) ? node.type : [node.type];
+    const ok = types.some((t) => typeof t === "string" && matchesType(value, t));
+    if (!ok) {
+      issues.push({
+        path,
+        message: `expected ${types.join(" | ")}, got ${typeOfValue(value)}`
+      });
+      return issues;
+    }
+  }
+  if (typeof value === "string") {
+    if (typeof node.minLength === "number" && value.length < node.minLength) {
+      issues.push({ path, message: `must be at least ${node.minLength} characters` });
+    }
+    if (typeof node.maxLength === "number" && value.length > node.maxLength) {
+      issues.push({ path, message: `must be at most ${node.maxLength} characters` });
+    }
+    if (typeof node.pattern === "string") {
+      let re;
+      try {
+        re = new RegExp(node.pattern);
+      } catch {
+      }
+      if (re && !re.test(value)) {
+        issues.push({ path, message: `must match pattern ${node.pattern}` });
+      }
+    }
+    if (typeof node.format === "string") {
+      const check = FORMAT_VALIDATORS[node.format];
+      if (check && !check(value)) {
+        issues.push({ path, message: `must be a valid ${node.format}` });
+      }
+    }
+  }
+  if (typeof value === "number") {
+    if (typeof node.minimum === "number" && value < node.minimum) {
+      issues.push({ path, message: `must be >= ${node.minimum}` });
+    }
+    if (typeof node.maximum === "number" && value > node.maximum) {
+      issues.push({ path, message: `must be <= ${node.maximum}` });
+    }
+    if (typeof node.exclusiveMinimum === "number" && value <= node.exclusiveMinimum) {
+      issues.push({ path, message: `must be > ${node.exclusiveMinimum}` });
+    }
+    if (typeof node.exclusiveMaximum === "number" && value >= node.exclusiveMaximum) {
+      issues.push({ path, message: `must be < ${node.exclusiveMaximum}` });
+    }
+    if (typeof node.multipleOf === "number" && node.multipleOf > 0) {
+      const quotient = value / node.multipleOf;
+      if (Math.abs(quotient - Math.round(quotient)) > 1e-9) {
+        issues.push({ path, message: `must be a multiple of ${node.multipleOf}` });
+      }
+    }
+  }
+  if (Array.isArray(value)) {
+    if (typeof node.minItems === "number" && value.length < node.minItems) {
+      issues.push({ path, message: `must have at least ${node.minItems} items` });
+    }
+    if (typeof node.maxItems === "number" && value.length > node.maxItems) {
+      issues.push({ path, message: `must have at most ${node.maxItems} items` });
+    }
+    if (node.uniqueItems === true) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const item of value) {
+        const key = JSON.stringify(item);
+        if (seen.has(key)) {
+          issues.push({ path, message: "items must be unique" });
+          break;
+        }
+        seen.add(key);
+      }
+    }
+    if (node.items !== void 0) {
+      value.forEach((item, i) => {
+        issues.push(...validateValueAgainstSchema(item, node.items, root, `${path}[${i}]`));
+      });
+    }
+  }
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const record = value;
+    const props = node.properties ?? {};
+    if (Array.isArray(node.required)) {
+      for (const req of node.required) {
+        if (typeof req === "string" && record[req] === void 0) {
+          issues.push({ path: path ? `${path}.${req}` : req, message: "is required" });
+        }
+      }
+    }
+    for (const [name, sub] of Object.entries(props)) {
+      if (record[name] !== void 0) {
+        issues.push(
+          ...validateValueAgainstSchema(record[name], sub, root, path ? `${path}.${name}` : name)
+        );
+      }
+    }
+    if (node.additionalProperties === false) {
+      for (const key of Object.keys(record)) {
+        if (!(key in props)) {
+          issues.push({
+            path: path ? `${path}.${key}` : key,
+            message: "is not an allowed property"
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+// src/definition.ts
+function observation(def) {
+  return def;
+}
+function action(def) {
+  return def;
+}
+function defineAgentComponent(def) {
+  return def;
+}
+var COMPONENT_KEYS = /* @__PURE__ */ new Set([
+  "type",
+  "instanceId",
+  "description",
+  "parent",
+  "meta",
+  "internal",
+  "policies",
+  "origin",
+  "priority",
+  "enabled",
+  "observations",
+  "actions",
+  "procedures"
+]);
+var OBSERVATION_KEYS = /* @__PURE__ */ new Set([
+  "description",
+  "output",
+  "read",
+  "when",
+  "unavailableReason",
+  "policies",
+  "meta",
+  "timeoutMs"
+]);
+var ACTION_KEYS = /* @__PURE__ */ new Set([
+  "description",
+  "input",
+  "output",
+  "effect",
+  "idempotent",
+  "reversible",
+  "confirmation",
+  "audit",
+  "when",
+  "unavailableReason",
+  "precondition",
+  "execute",
+  "policies",
+  "meta",
+  "timeoutMs"
+]);
+var VIEW_EFFECTS = /* @__PURE__ */ new Set(["local-state", "navigation"]);
+var SERVER_EFFECTS = /* @__PURE__ */ new Set([
+  "server-query",
+  "server-mutation",
+  "external-side-effect",
+  "destructive"
+]);
+function fail(code, message) {
+  throw new AgentSurfaceDefinitionError(code, message);
+}
+function checkMeta(meta, where, limits) {
+  if (meta === void 0) return;
+  if (!isJsonValue(meta) || typeof meta !== "object" || Array.isArray(meta)) {
+    fail("INVALID_DEFINITION", `${where}: meta must be a JsonValue record`);
+  }
+  if (byteLength(meta) > limits.maxMetaBytes) {
+    fail("LIMIT_EXCEEDED", `${where}: meta exceeds ${limits.maxMetaBytes} bytes`);
+  }
+}
+function checkSchema(schema, where, limits) {
+  if (schema === void 0) return;
+  if (typeof schema !== "object" || schema === null || typeof schema.parse !== "function" || typeof schema.jsonSchema !== "object") {
+    fail("INVALID_DEFINITION", `${where}: expected an AgentSchema ({ jsonSchema, parse })`);
+  }
+  const result = validateJsonSchemaDocument(schema.jsonSchema, limits);
+  if (!result.ok) fail("UNSUPPORTED_SCHEMA", `${where}: ${result.reason}`);
+}
+function validateComponentDefinition(def, limits, opts) {
+  if (typeof def !== "object" || def === null) {
+    fail("INVALID_DEFINITION", "definition must be an object");
+  }
+  for (const key of Object.keys(def)) {
+    if (!COMPONENT_KEYS.has(key)) {
+      fail("INVALID_DEFINITION", `unknown definition field "${key}"`);
+    }
+  }
+  if (typeof def.type !== "string" || !isValidComponentType(def.type)) {
+    fail("INVALID_ID", `invalid component type "${String(def.type)}"`);
+  }
+  const instanceId = def.instanceId ?? "default";
+  if (!isValidInstanceId(instanceId)) {
+    fail("INVALID_ID", `invalid instanceId "${instanceId}" for component "${def.type}"`);
+  }
+  if (typeof def.description !== "string" || def.description.trim().length === 0) {
+    fail("INVALID_DEFINITION", `component "${def.type}": description is required and must be non-empty`);
+  }
+  if (def.description.length > limits.maxComponentDescription) {
+    fail(
+      "LIMIT_EXCEEDED",
+      `component "${def.type}": description exceeds ${limits.maxComponentDescription} chars`
+    );
+  }
+  if (def.parent !== void 0) {
+    if (typeof def.parent !== "object" || def.parent === null || typeof def.parent.type !== "string" || !isValidComponentType(def.parent.type) || def.parent.instanceId !== void 0 && !isValidInstanceId(def.parent.instanceId)) {
+      fail("INVALID_DEFINITION", `component "${def.type}": invalid parent link`);
+    }
+  }
+  checkMeta(def.meta, `component "${def.type}"`, limits);
+  if (def.priority !== void 0 && typeof def.priority !== "number") {
+    fail("INVALID_DEFINITION", `component "${def.type}": priority must be a number`);
+  }
+  if (def.origin !== void 0 && typeof def.origin !== "string") {
+    fail("INVALID_DEFINITION", `component "${def.type}": origin must be a string`);
+  }
+  const seenNames = /* @__PURE__ */ new Set();
+  const checkName = (name, kind) => {
+    if (!isValidCapabilityName(name)) {
+      fail("INVALID_ID", `component "${def.type}": invalid ${kind} name "${name}"`);
+    }
+    const capabilityId = formatViewCapabilityId(def.type, name);
+    if (capabilityId.length > MAX_ID_LENGTH) {
+      fail("INVALID_ID", `capability id "${capabilityId}" exceeds ${MAX_ID_LENGTH} chars`);
+    }
+    if (seenNames.has(name)) {
+      fail("DUPLICATE_CAPABILITY", `component "${def.type}": duplicate capability name "${name}"`);
+    }
+    seenNames.add(name);
+  };
+  for (const [name, obs] of Object.entries(def.observations ?? {})) {
+    checkName(name, "observation");
+    const where = `observation "${def.type}.${name}"`;
+    for (const key of Object.keys(obs)) {
+      if (!OBSERVATION_KEYS.has(key)) fail("INVALID_DEFINITION", `${where}: unknown field "${key}"`);
+    }
+    if (typeof obs.description !== "string" || obs.description.trim().length === 0) {
+      fail("INVALID_DEFINITION", `${where}: description is required`);
+    }
+    if (obs.description.length > limits.maxCapabilityDescription) {
+      fail("LIMIT_EXCEEDED", `${where}: description exceeds ${limits.maxCapabilityDescription} chars`);
+    }
+    if (typeof obs.read !== "function") fail("INVALID_DEFINITION", `${where}: read() is required`);
+    checkSchema(obs.output, `${where} output`, limits);
+    if (obs.output === void 0) fail("INVALID_DEFINITION", `${where}: output schema is required`);
+    checkMeta(obs.meta, where, limits);
+  }
+  for (const [name, act] of Object.entries(def.actions ?? {})) {
+    checkName(name, "action");
+    const where = `action "${def.type}.${name}"`;
+    for (const key of Object.keys(act)) {
+      if (!ACTION_KEYS.has(key)) fail("INVALID_DEFINITION", `${where}: unknown field "${key}"`);
+    }
+    if (typeof act.description !== "string" || act.description.trim().length === 0) {
+      fail("INVALID_DEFINITION", `${where}: description is required`);
+    }
+    if (act.description.length > limits.maxCapabilityDescription) {
+      fail("LIMIT_EXCEEDED", `${where}: description exceeds ${limits.maxCapabilityDescription} chars`);
+    }
+    if (typeof act.execute !== "function") fail("INVALID_DEFINITION", `${where}: execute() is required`);
+    if (!VIEW_EFFECTS.has(act.effect)) {
+      if (SERVER_EFFECTS.has(act.effect)) {
+        fail(
+          "PLANE_VIOLATION",
+          `${where}: view actions cannot declare server effect "${act.effect}" \u2014 define an oRPC procedure and reference it (docs/05)`
+        );
+      }
+      fail("INVALID_DEFINITION", `${where}: effect must be "local-state" or "navigation"`);
+    }
+    if (act.confirmation !== void 0 && !["never", "optional", "required"].includes(act.confirmation)) {
+      fail("INVALID_DEFINITION", `${where}: invalid confirmation "${act.confirmation}"`);
+    }
+    if (act.audit !== void 0 && !["none", "metadata", "full"].includes(act.audit)) {
+      fail("INVALID_DEFINITION", `${where}: invalid audit level "${act.audit}"`);
+    }
+    if (act.input === void 0) fail("INVALID_DEFINITION", `${where}: input schema is required`);
+    checkSchema(act.input, `${where} input`, limits);
+    checkSchema(act.output, `${where} output`, limits);
+    checkMeta(act.meta, where, limits);
+  }
+  const procedures = def.procedures ?? [];
+  if (procedures.length > 0 && !opts.hasProcedureExecutor) {
+    fail(
+      "PLANE_VIOLATION",
+      `component "${def.type}": procedure bindings require an installed procedure executor (registry.setProcedureExecutor)`
+    );
+  }
+  for (const binding of procedures) {
+    if (typeof binding !== "object" || binding === null || binding.kind !== "procedure-binding") {
+      fail("INVALID_DEFINITION", `component "${def.type}": invalid procedure binding`);
+    }
+    const ref = binding.ref;
+    if (typeof ref !== "object" || ref === null || typeof ref.path !== "string" || ref.path.length === 0 || typeof ref.id !== "string" || ref.id !== `domain:${ref.path}` || typeof ref.description !== "string") {
+      fail("INVALID_DEFINITION", `component "${def.type}": procedure binding has an invalid ref`);
+    }
+    if (!SERVER_EFFECTS.has(ref.effect)) {
+      fail(
+        "PLANE_VIOLATION",
+        `procedure "${ref.path}": effect must be one of server-query | server-mutation | external-side-effect | destructive`
+      );
+    }
+    if (typeof binding.reducedInputSchema !== "object" || binding.reducedInputSchema === null) {
+      fail("INVALID_DEFINITION", `procedure "${ref.path}": missing reduced input schema`);
+    }
+    if (binding.config.confirmation !== void 0 && !["optional", "required"].includes(binding.config.confirmation)) {
+      fail("INVALID_DEFINITION", `procedure "${ref.path}": invalid confirmation escalation`);
+    }
+    checkMeta(binding.config.meta, `procedure "${ref.path}"`, limits);
+  }
+}
+
+// src/policy.ts
+var CONFIRMATION_ESCALATION = /* @__PURE__ */ Symbol("agent-surface.confirmation-escalation");
+function evaluateDiscovery(policies, ctx) {
+  let disable;
+  for (const policy of policies) {
+    if (!policy.onDiscovery) continue;
+    let decision;
+    try {
+      decision = policy.onDiscovery(ctx);
+    } catch {
+      return { decision: "hide" };
+    }
+    if (decision.decision === "hide") return decision;
+    if (decision.decision === "disable" && !disable) disable = decision;
+  }
+  return disable ?? { decision: "expose" };
+}
+function composeAuthorizeChain(policies, ctx, core) {
+  let index = -1;
+  const dispatch = (i) => {
+    if (i <= index) {
+      return Promise.reject(new Error("policy next() called multiple times"));
+    }
+    index = i;
+    const policy = policies[i];
+    if (!policy) return core();
+    if (!policy.onAuthorize) return dispatch(i + 1);
+    return policy.onAuthorize(ctx, () => dispatch(i + 1));
+  };
+  return dispatch(0);
+}
+function composeInvokeChain(policies, ctx, core) {
+  let index = -1;
+  const dispatch = (i) => {
+    if (i <= index) {
+      return Promise.reject(new Error("policy next() called multiple times"));
+    }
+    index = i;
+    const policy = policies[i];
+    if (!policy) return core();
+    if (!policy.onInvoke) return dispatch(i + 1);
+    return policy.onInvoke(ctx, () => dispatch(i + 1));
+  };
+  return dispatch(0);
+}
+function authenticated(opts) {
+  const key = opts?.key ?? "user";
+  return {
+    name: "authenticated",
+    onDiscovery(ctx) {
+      return ctx.host[key] ? { decision: "expose" } : { decision: "hide" };
+    },
+    async onAuthorize(ctx, next) {
+      if (!ctx.host[key]) {
+        throw new AgentSurfaceError({
+          code: "NOT_AUTHENTICATED",
+          message: "Sign-in is required before this capability can be used. Ask the user to sign in.",
+          retry: "no"
+        });
+      }
+      return next();
+    }
+  };
+}
+function hasPermission(permission, check) {
+  return {
+    name: `has-permission(${permission})`,
+    onDiscovery(ctx) {
+      return check({ ...ctx.host }, permission) ? { decision: "expose" } : { decision: "hide" };
+    },
+    async onAuthorize(ctx, next) {
+      if (!check({ ...ctx.host }, permission)) {
+        throw new AgentSurfaceError({
+          code: "NOT_AUTHORIZED",
+          message: "The current user is not authorized to use this capability.",
+          retry: "no",
+          details: { origin: "client" }
+        });
+      }
+      return next();
+    }
+  };
+}
+function tenantBoundary(opts) {
+  const matches = (ctx) => {
+    const current = opts.current({ ...ctx.host });
+    const expected = opts.expected(ctx);
+    return expected === void 0 || current === expected;
+  };
+  return {
+    name: "tenant-boundary",
+    onDiscovery(ctx) {
+      return matches(ctx) ? { decision: "expose" } : { decision: "hide" };
+    },
+    async onAuthorize(ctx, next) {
+      if (!matches(ctx)) {
+        throw new AgentSurfaceError({
+          code: "NOT_AUTHORIZED",
+          message: "This capability belongs to a different tenant.",
+          retry: "no",
+          details: { origin: "client" }
+        });
+      }
+      return next();
+    }
+  };
+}
+function environment(allowed) {
+  return {
+    name: "environment",
+    onDiscovery(ctx) {
+      return allowed.includes(ctx.environment) ? { decision: "expose" } : { decision: "hide" };
+    },
+    async onAuthorize(ctx, next) {
+      if (!allowed.includes(ctx.environment)) {
+        throw new AgentSurfaceError({
+          code: "CAPABILITY_NOT_FOUND",
+          message: "This capability does not exist in the current surface.",
+          retry: "after-refresh"
+        });
+      }
+      return next();
+    }
+  };
+}
+function rateLimit(opts) {
+  const hits = /* @__PURE__ */ new Map();
+  return {
+    name: "rate-limit",
+    async onAuthorize(ctx, next) {
+      const key = `${ctx.consumer.kind}:${ctx.consumer.id} ${ctx.capabilityId}`;
+      const now = ctx.now();
+      const windowStart = now - opts.windowMs;
+      const list = (hits.get(key) ?? []).filter((t) => t > windowStart);
+      if (list.length >= opts.limit) {
+        const retryAfterMs = Math.max(0, (list[0] ?? now) + opts.windowMs - now);
+        throw new AgentSurfaceError({
+          code: "RATE_LIMITED",
+          message: "Too many calls to this capability. Wait before retrying.",
+          retry: "after-delay",
+          details: { reason: "rate", retryAfterMs }
+        });
+      }
+      list.push(now);
+      hits.set(key, list);
+      return next();
+    }
+  };
+}
+function requireConfirmation(opts) {
+  const policy = {
+    name: "require-confirmation"
+  };
+  policy[CONFIRMATION_ESCALATION] = { if: opts?.if, summary: opts?.summary };
+  return policy;
+}
+function audit(sink, level = "metadata") {
+  return {
+    name: "audit",
+    async onInvoke(ctx, next) {
+      const startedAt = ctx.now();
+      sink?.record({
+        at: new Date(startedAt).toISOString(),
+        type: "invocation-started",
+        capabilityId: ctx.capabilityId,
+        registrationId: ctx.registrationId,
+        invocationId: ctx.invocationId,
+        consumerId: ctx.consumer.id,
+        ...level === "full" ? { payload: { input: ctx.effectiveInput } } : {}
+      });
+      const result = await next();
+      sink?.record({
+        at: new Date(ctx.now()).toISOString(),
+        type: "invocation-settled",
+        capabilityId: ctx.capabilityId,
+        registrationId: ctx.registrationId,
+        invocationId: ctx.invocationId,
+        consumerId: ctx.consumer.id,
+        status: result.status,
+        ...result.status === "error" ? { code: result.error.code } : {},
+        durationMs: ctx.now() - startedAt,
+        ...level === "full" && result.status === "ok" && result.output !== void 0 ? { payload: { output: result.output } } : {}
+      });
+      return result;
+    }
+  };
+}
+
+// src/audit.ts
+function memoryAuditSink(opts) {
+  const capacity = opts?.capacity ?? 1e3;
+  const buffer = [];
+  return {
+    record(event) {
+      buffer.push(event);
+      if (buffer.length > capacity) buffer.splice(0, buffer.length - capacity);
+    },
+    events() {
+      return [...buffer];
+    }
+  };
+}
+function consoleAuditSink() {
+  return {
+    record(event) {
+      console.debug("[agent-surface audit]", event.type, event);
+    }
+  };
+}
+function safeRecord(sink, event) {
+  if (!sink) return;
+  try {
+    sink.record(event);
+  } catch (err) {
+    console.error("[agent-surface] audit sink threw", err);
+  }
+}
+
+// src/events.ts
+var EventDispatcher = class {
+  constructor(reportError) {
+    this.reportError = reportError;
+  }
+  reportError;
+  listeners = /* @__PURE__ */ new Set();
+  queue = [];
+  draining = false;
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(event) {
+    this.queue.push(event);
+    if (this.draining) return;
+    this.draining = true;
+    try {
+      let next;
+      while ((next = this.queue.shift()) !== void 0) {
+        for (const listener of [...this.listeners]) {
+          try {
+            listener(next);
+          } catch (err) {
+            this.reportError(err);
+          }
+        }
+      }
+    } finally {
+      this.draining = false;
+    }
+  }
+  clear() {
+    this.listeners.clear();
+    this.queue.length = 0;
+  }
+};
+
+// src/confirmation.ts
+var MAX_RETAINED_RESOLVED = 200;
+var ConfirmationStore = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  records = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  /** Creates (or re-uses a matching pending) confirmation record.
+   * Returns "overflow" when the bounded pending store is full (D24):
+   * the caller fails RATE_LIMITED and no record is created. */
+  request(request) {
+    for (const record2 of this.records.values()) {
+      if (record2.state === "pending" && record2.digest === request.digest) {
+        return this.view(record2);
+      }
+    }
+    if (this.pendingCount() >= this.opts.maxPending) return "overflow";
+    const now = this.opts.now();
+    const record = {
+      confirmationId: `cnf_${randomBase62(12)}`,
+      capabilityId: request.capabilityId,
+      registrationId: request.registrationId,
+      consumerKey: request.consumerKey,
+      effect: request.effect,
+      summary: request.summary,
+      input: request.input,
+      digest: request.digest,
+      requestedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + this.opts.ttlMs).toISOString(),
+      state: "pending",
+      waiters: []
+    };
+    record.timer = setTimeout(() => this.expire(record.confirmationId), this.opts.ttlMs);
+    this.records.set(record.confirmationId, record);
+    this.trim();
+    this.opts.emit({
+      type: "confirmation-requested",
+      confirmationId: record.confirmationId,
+      capabilityId: record.capabilityId,
+      expiresAt: record.expiresAt
+    });
+    this.opts.audit({
+      type: "confirmation-requested",
+      capabilityId: record.capabilityId,
+      registrationId: record.registrationId,
+      consumerId: record.consumerKey,
+      invocationId: void 0
+    });
+    this.notify();
+    return this.view(record);
+  }
+  pendingCount() {
+    let count = 0;
+    for (const record of this.records.values()) {
+      if (record.state === "pending") count += 1;
+    }
+    return count;
+  }
+  resolve(confirmationId, resolution) {
+    const record = this.records.get(confirmationId);
+    if (!record || record.state !== "pending") return;
+    if (record.timer) clearTimeout(record.timer);
+    if (resolution.approved) {
+      record.state = "approved";
+      record.approvedAt = new Date(this.opts.now()).toISOString();
+      this.opts.emit({ type: "confirmation-resolved", confirmationId, outcome: "approved" });
+      this.opts.audit({
+        type: "confirmation-approved",
+        capabilityId: record.capabilityId,
+        registrationId: record.registrationId,
+        consumerId: record.consumerKey
+      });
+      this.settleWaiters(record, "approved");
+    } else {
+      record.state = "denied";
+      record.denyReason = resolution.reason;
+      this.opts.emit({ type: "confirmation-resolved", confirmationId, outcome: "denied" });
+      this.opts.audit({
+        type: "confirmation-denied",
+        capabilityId: record.capabilityId,
+        registrationId: record.registrationId,
+        consumerId: record.consumerKey
+      });
+      this.settleWaiters(record, "denied");
+    }
+    this.notify();
+  }
+  expire(confirmationId) {
+    const record = this.records.get(confirmationId);
+    if (!record || record.state !== "pending") return;
+    if (record.timer) clearTimeout(record.timer);
+    record.state = "expired";
+    record.expiresAt = new Date(this.opts.now()).toISOString();
+    this.opts.emit({ type: "confirmation-resolved", confirmationId, outcome: "expired" });
+    this.opts.audit({
+      type: "confirmation-expired",
+      capabilityId: record.capabilityId,
+      registrationId: record.registrationId,
+      consumerId: record.consumerKey
+    });
+    this.settleWaiters(record, "expired");
+    this.notify();
+  }
+  /** Evidence validation + single-use consumption (docs/06 rules 2–5).
+   * Matching is digest-first AND exact-value on the effective input —
+   * never hash-only (AS-CONFIRM-002). */
+  consume(evidence) {
+    const record = this.records.get(evidence.confirmationId);
+    if (!record) return { ok: false, kind: "invalid", reason: "mismatch" };
+    const matches = record.digest === evidence.digest && jsonDeepEqual(record.input, evidence.input);
+    switch (record.state) {
+      case "pending":
+        return matches ? { ok: false, kind: "pending-again", record: this.view(record) } : { ok: false, kind: "invalid", reason: "mismatch" };
+      case "denied":
+        return { ok: false, kind: "invalid", reason: "denied" };
+      case "expired":
+        return { ok: false, kind: "invalid", reason: "expired" };
+      case "consumed":
+        return { ok: false, kind: "invalid", reason: "consumed" };
+      case "approved": {
+        if (Date.parse(record.expiresAt) < this.opts.now()) {
+          record.state = "expired";
+          return { ok: false, kind: "invalid", reason: "expired" };
+        }
+        if (!matches) return { ok: false, kind: "invalid", reason: "mismatch" };
+        record.state = "consumed";
+        this.opts.audit({
+          type: "confirmation-consumed",
+          capabilityId: record.capabilityId,
+          registrationId: record.registrationId,
+          consumerId: record.consumerKey
+        });
+        return { ok: true, approvedAt: record.approvedAt ?? record.requestedAt };
+      }
+    }
+  }
+  pending() {
+    return [...this.records.values()].filter((r) => r.state === "pending").map((r) => this.view(r));
+  }
+  waitFor(confirmationId, opts) {
+    const record = this.records.get(confirmationId);
+    if (!record) return Promise.resolve("expired");
+    if (record.state === "approved" || record.state === "consumed") return Promise.resolve("approved");
+    if (record.state === "denied") return Promise.resolve("denied");
+    if (record.state === "expired") return Promise.resolve("expired");
+    return new Promise((resolvePromise) => {
+      const waiter = (outcome) => resolvePromise(outcome);
+      record.waiters.push(waiter);
+      opts?.signal?.addEventListener(
+        "abort",
+        () => {
+          const i = record.waiters.indexOf(waiter);
+          if (i >= 0) record.waiters.splice(i, 1);
+          resolvePromise("expired");
+        },
+        { once: true }
+      );
+    });
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /** Expires every pending record (dispose path). */
+  disposeAll() {
+    for (const record of [...this.records.values()]) {
+      if (record.state === "pending") this.expire(record.confirmationId);
+    }
+    this.listeners.clear();
+  }
+  controller() {
+    return {
+      pending: () => this.pending(),
+      resolve: (id, resolution) => this.resolve(id, resolution),
+      waitFor: (id, opts) => this.waitFor(id, opts),
+      subscribe: (listener) => this.subscribe(listener),
+      forceExpire: (id) => this.expire(id)
+    };
+  }
+  view(record) {
+    return {
+      confirmationId: record.confirmationId,
+      capabilityId: record.capabilityId,
+      registrationId: record.registrationId,
+      consumerKey: record.consumerKey,
+      effect: record.effect,
+      summary: record.summary,
+      input: record.input,
+      requestedAt: record.requestedAt,
+      expiresAt: record.expiresAt
+    };
+  }
+  settleWaiters(record, outcome) {
+    const waiters = record.waiters.splice(0);
+    for (const waiter of waiters) waiter(outcome);
+  }
+  notify() {
+    const snapshot = this.pending();
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(snapshot);
+      } catch {
+      }
+    }
+  }
+  trim() {
+    const resolved = [...this.records.values()].filter((r) => r.state !== "pending");
+    if (resolved.length <= MAX_RETAINED_RESOLVED) return;
+    for (const record of resolved.slice(0, resolved.length - MAX_RETAINED_RESOLVED)) {
+      this.records.delete(record.confirmationId);
+    }
+  }
+};
+
+// src/internal.ts
+var DevDefectError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentSurfaceDevDefectError";
+  }
+};
+function componentKey(type, instanceId) {
+  return `${type}\0${instanceId}`;
+}
+var CONFIRMATION_RANK = {
+  never: 0,
+  optional: 1,
+  required: 2
+};
+function maxConfirmation(...levels) {
+  return levels.reduce((acc, l) => CONFIRMATION_RANK[l] > CONFIRMATION_RANK[acc] ? l : acc, "never");
+}
+function defaultConfirmationFor(effect) {
+  switch (effect) {
+    case "server-query":
+      return "never";
+    case "server-mutation":
+      return "optional";
+    case "external-side-effect":
+    case "destructive":
+      return "required";
+  }
+}
+function defaultAuditFor(effect) {
+  return effect === "external-side-effect" || effect === "destructive" ? "full" : "metadata";
+}
+var registrationCounter = 0;
+function nextRegistrationId(random) {
+  registrationCounter += 1;
+  return `reg_${registrationCounter.toString(36).padStart(4, "0")}${random()}`;
+}
+function normalizeRegistration(def, id) {
+  const instanceId = def.instanceId ?? "default";
+  const observations = /* @__PURE__ */ new Map();
+  for (const [name, obs] of Object.entries(def.observations ?? {})) {
+    observations.set(name, {
+      kind: "observation",
+      name,
+      capabilityId: formatViewCapabilityId(def.type, name),
+      description: obs.description,
+      outputSchema: obs.output,
+      jsonSchema: jsonClone(obs.output.jsonSchema),
+      meta: obs.meta ? jsonClone(obs.meta) : void 0,
+      timeoutMs: obs.timeoutMs,
+      policies: [...obs.policies ?? []],
+      auditLevel: "none"
+    });
+  }
+  const actions = /* @__PURE__ */ new Map();
+  for (const [name, act] of Object.entries(def.actions ?? {})) {
+    actions.set(name, {
+      kind: "action",
+      name,
+      capabilityId: formatViewCapabilityId(def.type, name),
+      description: act.description,
+      inputSchema: act.input,
+      inputJsonSchema: jsonClone(act.input.jsonSchema),
+      outputSchema: act.output,
+      outputJsonSchema: act.output ? jsonClone(act.output.jsonSchema) : void 0,
+      effect: act.effect,
+      idempotent: act.idempotent ?? false,
+      reversible: act.reversible ?? true,
+      confirmation: act.confirmation ?? "never",
+      auditLevel: act.audit ?? "metadata",
+      meta: act.meta ? jsonClone(act.meta) : void 0,
+      timeoutMs: act.timeoutMs,
+      policies: [...act.policies ?? []]
+    });
+  }
+  const hasView = observations.size > 0 || actions.size > 0;
+  const procedures = (def.procedures ?? []).map((binding) => {
+    const boundKeys = [...binding.boundKeys];
+    const overridable = new Set(binding.config.overridableFields ?? []);
+    const lockedKeys = binding.lockedKeys ? [...binding.lockedKeys] : boundKeys.filter((k) => !overridable.has(k));
+    const effect = binding.ref.effect;
+    return {
+      kind: "procedure",
+      binding,
+      capabilityId: binding.ref.id,
+      path: binding.ref.path,
+      effect,
+      requiresApproval: binding.ref.requiresApproval === true,
+      baseDescription: binding.ref.description,
+      fullInputSchema: jsonClone(binding.ref.inputSchema),
+      reducedInputSchema: jsonClone(binding.reducedInputSchema),
+      outputJsonSchema: binding.ref.outputSchema ? jsonClone(binding.ref.outputSchema) : void 0,
+      boundKeys,
+      lockedKeys,
+      overridableKeys: overridable,
+      confirmationFloor: maxConfirmation(
+        defaultConfirmationFor(effect),
+        binding.config.confirmation ?? "never",
+        binding.ref.requiresApproval === true ? "required" : "never"
+      ),
+      idempotent: effect === "server-query",
+      auditLevel: defaultAuditFor(effect),
+      meta: binding.config.meta ? jsonClone(binding.config.meta) : void 0,
+      policies: [...binding.config.policies ?? []],
+      contextLink: binding.contextLink ?? (hasView ? { type: def.type, instanceId } : void 0)
+    };
+  });
+  return {
+    id,
+    key: componentKey(def.type, instanceId),
+    type: def.type,
+    instanceId,
+    description: def.description,
+    parent: def.parent ? { type: def.parent.type, instanceId: def.parent.instanceId ?? "default" } : void 0,
+    meta: def.meta ? jsonClone(def.meta) : void 0,
+    internal: Object.freeze({ ...def.internal ?? {} }),
+    origin: def.origin ?? "first-party",
+    priority: def.priority ?? 0,
+    definition: def,
+    componentPolicies: [...def.policies ?? []],
+    observations,
+    actions,
+    procedures,
+    procedureOnly: !hasView && procedures.length > 0,
+    status: "active",
+    enabled: def.enabled !== false,
+    availabilityOverrides: /* @__PURE__ */ new Map(),
+    inFlight: /* @__PURE__ */ new Set(),
+    actionQueue: { running: false, waiting: [] }
+  };
+}
+function liveAvailabilityHooks(reg, cap) {
+  if (cap.kind === "observation") {
+    const live = reg.definition.observations?.[cap.name];
+    return { when: live?.when, unavailableReason: live?.unavailableReason };
+  }
+  if (cap.kind === "action") {
+    const live = reg.definition.actions?.[cap.name];
+    return { when: live?.when, unavailableReason: live?.unavailableReason };
+  }
+  return { when: cap.binding.config.when, unavailableReason: cap.binding.config.unavailableReason };
+}
+function computeAvailability(internals, reg, cap) {
+  if (reg.status !== "active") {
+    return { available: false, reason: "component-unregistered" };
+  }
+  if (!reg.enabled) {
+    return { available: false, reason: "component-disabled" };
+  }
+  const overrideKey = cap.kind === "procedure" ? cap.path : cap.name;
+  const override = reg.availabilityOverrides.get(overrideKey) ?? reg.availabilityOverrides.get(cap.capabilityId);
+  if (override && override.available === false) {
+    return { available: false, reason: override.reason ?? "unavailable" };
+  }
+  const hooks = liveAvailabilityHooks(reg, cap);
+  if (hooks.when) {
+    let result;
+    try {
+      result = hooks.when() !== false;
+    } catch (err) {
+      internals.devWarn(
+        `[agent-surface] when() threw for ${cap.capabilityId}; treating as unavailable`,
+        err
+      );
+      return { available: false, reason: "when-error" };
+    }
+    if (!result) {
+      let reason = "Currently unavailable";
+      const ur = hooks.unavailableReason;
+      try {
+        if (typeof ur === "function") reason = ur();
+        else if (typeof ur === "string") reason = ur;
+      } catch {
+      }
+      return { available: false, reason };
+    }
+  }
+  return { available: true };
+}
+function policiesFor(internals, reg, cap) {
+  return [...internals.registryPolicies, ...reg.componentPolicies, ...cap.policies];
+}
+function buildPolicyContext(internals, reg, cap, consumer, host) {
+  return {
+    capabilityId: cap.capabilityId,
+    plane: cap.kind === "procedure" ? "domain" : "view",
+    kind: cap.kind,
+    effect: cap.kind === "observation" ? "read" : cap.effect,
+    registrationId: reg.id,
+    consumer,
+    host,
+    meta: { component: reg.meta, capability: cap.meta },
+    internal: reg.internal,
+    environment: internals.environment,
+    now: () => internals.now()
+  };
+}
+function consumerKeyOf(consumer) {
+  return `${consumer.kind}:${consumer.id}`;
+}
+function pruneTombstones(internals) {
+  const now = internals.now();
+  for (const [id, tomb] of internals.tombstones) {
+    if (tomb.expiresAt <= now) internals.tombstones.delete(id);
+  }
+  while (internals.tombstones.size > internals.limits.tombstoneSize) {
+    const oldest = internals.tombstones.keys().next().value;
+    if (oldest === void 0) break;
+    internals.tombstones.delete(oldest);
+  }
+}
+function addTombstone(internals, reg) {
+  const capabilityIds = /* @__PURE__ */ new Set();
+  for (const obs of reg.observations.values()) capabilityIds.add(obs.capabilityId);
+  for (const act of reg.actions.values()) capabilityIds.add(act.capabilityId);
+  for (const proc of reg.procedures) capabilityIds.add(proc.capabilityId);
+  internals.tombstones.set(reg.id, {
+    registrationId: reg.id,
+    type: reg.type,
+    instanceId: reg.instanceId,
+    capabilityIds,
+    expiresAt: internals.now() + internals.limits.tombstoneTtlMs
+  });
+  pruneTombstones(internals);
+}
+
+// src/invoke.ts
+var DEFAULT_CONSUMER = { id: "anonymous", kind: "embedded" };
+function notFound() {
+  return {
+    code: "CAPABILITY_NOT_FOUND",
+    message: "This capability does not exist in the current surface. Refresh the surface catalog before the next step.",
+    retry: "after-refresh"
+  };
+}
+function notAvailable(reason) {
+  return {
+    code: "CAPABILITY_NOT_AVAILABLE",
+    message: `This capability exists but is currently unavailable${reason ? `: ${reason}` : ""}. Perform the enabling step first, then refresh.`,
+    retry: "after-refresh",
+    ...reason !== void 0 ? { details: { reason } } : {}
+  };
+}
+function unmounted(phase) {
+  return {
+    code: "COMPONENT_UNMOUNTED",
+    message: phase === "mid-flight" ? "The owning view unmounted while this capability was executing. Verify state before repeating a non-idempotent action." : "The owning view is no longer mounted. Refresh the surface catalog.",
+    retry: "after-refresh",
+    details: { phase }
+  };
+}
+function stale(reason, liveRegistrationId) {
+  return {
+    code: "STALE_CAPABILITY",
+    message: "The invocation references a superseded surface snapshot. Refresh the catalog and re-resolve the target.",
+    retry: "after-refresh",
+    details: { reason, ...liveRegistrationId ? { liveRegistrationId } : {} }
+  };
+}
+function invocationConflict() {
+  return {
+    code: "INVOCATION_CONFLICT",
+    message: "This invocation id was already used for a different request. Use a fresh invocation id if the new request is intentional.",
+    retry: "with-changes",
+    details: { reason: "id-reused-with-different-request" }
+  };
+}
+function queueFull(retryAfterMs) {
+  return {
+    code: "RATE_LIMITED",
+    message: "The queue for this capability is full. Retry shortly.",
+    retry: "after-delay",
+    details: { reason: "queue-full", retryAfterMs }
+  };
+}
+function cancelled(message) {
+  return { code: "CANCELLED", message, retry: "yes" };
+}
+function executionFailed(reason, opts) {
+  const messages = {
+    "handler-error": "The capability failed to execute.",
+    "output-invalid": "The capability produced an invalid output.",
+    "output-too-large": "The capability produced an output exceeding the size limit.",
+    transport: "The server call failed."
+  };
+  return {
+    code: "EXECUTION_FAILED",
+    message: messages[reason] ?? "The capability failed to execute.",
+    retry: opts?.transient ? "after-delay" : "no",
+    details: {
+      reason,
+      ...opts?.transient ? { transient: true, retryAfterMs: 1e3 } : {}
+    }
+  };
+}
+function requestFingerprint(request) {
+  return fnv1a64(
+    canonicalJson({
+      capabilityId: request.capabilityId,
+      registrationId: request.registrationId ?? null,
+      instanceId: request.instanceId ?? null,
+      surfaceVersion: request.surfaceVersion ?? null,
+      input: request.input ?? null,
+      confirmationId: request.confirmationId ?? null
+    })
+  );
+}
+function performInvoke(internals, request, options) {
+  if (internals.disposed) {
+    throw new Error("invoke() called on a disposed registry");
+  }
+  const invocationId = request.invocationId ?? `inv_${randomBase62(12)}`;
+  const consumer = options?.consumer ?? DEFAULT_CONSUMER;
+  const consumerKey = consumerKeyOf(consumer);
+  const fingerprint = requestFingerprint(request);
+  const dedupeKey = `${consumerKey} ${invocationId}`;
+  pruneDedupe(internals);
+  const existing = internals.dedupe.get(dedupeKey);
+  if (existing) {
+    if (existing.kind === "inflight") {
+      if (existing.fingerprint === fingerprint) return existing.promise;
+      return Promise.resolve(conflictResult(internals, request, invocationId, consumer));
+    }
+    if (existing.expiresAt > internals.now()) {
+      if (existing.fingerprint === fingerprint) return Promise.resolve(existing.result);
+      return Promise.resolve(conflictResult(internals, request, invocationId, consumer));
+    }
+    internals.dedupe.delete(dedupeKey);
+  }
+  const promise = runPipeline(internals, request, invocationId, consumer, consumerKey, options);
+  internals.dedupe.set(dedupeKey, { kind: "inflight", fingerprint, promise });
+  promise.then(
+    (result) => {
+      const terminal = result.status === "ok" || result.error.code !== "CONFIRMATION_REQUIRED" && result.error.code !== "RATE_LIMITED";
+      if (terminal) {
+        internals.dedupe.set(dedupeKey, {
+          kind: "terminal",
+          fingerprint,
+          result,
+          expiresAt: internals.now() + internals.limits.dedupeCacheTtlMs
+        });
+        pruneDedupe(internals);
+      } else {
+        internals.dedupe.delete(dedupeKey);
+      }
+    },
+    () => {
+      internals.dedupe.delete(dedupeKey);
+    }
+  );
+  return promise;
+}
+function conflictResult(internals, request, invocationId, consumer) {
+  internals.emit({
+    type: "invocation-started",
+    invocationId,
+    capabilityId: request.capabilityId,
+    consumerId: consumer.id
+  });
+  const error = invocationConflict();
+  const result = {
+    status: "error",
+    invocationId,
+    capabilityId: request.capabilityId,
+    error,
+    surfaceVersion: String(internals.version)
+  };
+  internals.emit({
+    type: "invocation-settled",
+    invocationId,
+    capabilityId: request.capabilityId,
+    status: "error",
+    code: error.code,
+    durationMs: 0
+  });
+  internals.recordAudit({
+    type: "invocation-settled",
+    capabilityId: request.capabilityId,
+    invocationId,
+    consumerId: consumerKeyOf(consumer),
+    status: "error",
+    code: error.code,
+    durationMs: 0
+  });
+  return result;
+}
+function pruneDedupe(internals) {
+  const now = internals.now();
+  for (const [id, entry] of internals.dedupe) {
+    if (entry.kind === "terminal" && entry.expiresAt <= now) internals.dedupe.delete(id);
+  }
+  while (internals.dedupe.size > internals.limits.dedupeCacheSize) {
+    const oldest = internals.dedupe.keys().next().value;
+    if (oldest === void 0) break;
+    const entry = internals.dedupe.get(oldest);
+    if (entry?.kind === "inflight") break;
+    internals.dedupe.delete(oldest);
+  }
+}
+async function runPipeline(internals, request, invocationId, consumer, consumerKey, options) {
+  const startVersion = internals.version;
+  const startedAt = internals.now();
+  internals.emit({
+    type: "invocation-started",
+    invocationId,
+    capabilityId: request.capabilityId,
+    consumerId: consumer.id
+  });
+  let resolvedAuditLevel = "metadata";
+  let resolvedRegistrationId;
+  let inputForAudit;
+  let outputForAudit;
+  let queueWaitMsForAudit;
+  let executionMsForAudit;
+  const finalize = (body) => {
+    const surfaceVersion = String(internals.version);
+    const surfaceChanged = internals.version !== startVersion ? true : void 0;
+    const result = body.status === "ok" ? {
+      status: "ok",
+      invocationId,
+      capabilityId: request.capabilityId,
+      ...body.output !== void 0 ? { output: body.output } : {},
+      surfaceVersion,
+      ...surfaceChanged ? { surfaceChanged } : {}
+    } : {
+      status: "error",
+      invocationId,
+      capabilityId: request.capabilityId,
+      error: body.error,
+      surfaceVersion,
+      ...surfaceChanged ? { surfaceChanged } : {}
+    };
+    const durationMs = internals.now() - startedAt;
+    internals.emit({
+      type: "invocation-settled",
+      invocationId,
+      capabilityId: request.capabilityId,
+      status: result.status,
+      ...result.status === "error" ? { code: result.error.code } : {},
+      durationMs
+    });
+    if (resolvedAuditLevel !== "none") {
+      internals.recordAudit({
+        type: "invocation-settled",
+        capabilityId: request.capabilityId,
+        registrationId: resolvedRegistrationId,
+        invocationId,
+        consumerId: consumerKey,
+        status: result.status,
+        ...result.status === "error" ? { code: result.error.code } : {},
+        durationMs,
+        ...queueWaitMsForAudit !== void 0 ? { queueWaitMs: queueWaitMsForAudit } : {},
+        ...executionMsForAudit !== void 0 ? { executionMs: executionMsForAudit } : {},
+        ...resolvedAuditLevel === "full" ? {
+          payload: {
+            ...inputForAudit !== void 0 ? { input: inputForAudit } : {},
+            ...outputForAudit !== void 0 ? { output: outputForAudit } : {}
+          }
+        } : {}
+      });
+    }
+    return result;
+  };
+  try {
+    const resolved = resolveTarget(internals, request);
+    if ("error" in resolved) return finalize({ status: "error", error: resolved.error });
+    const { reg, cap } = resolved;
+    resolvedRegistrationId = reg.id;
+    resolvedAuditLevel = cap.auditLevel;
+    if (request.surfaceVersion !== void 0 && request.surfaceVersion !== String(internals.version) && cap.kind === "procedure" && (cap.effect === "destructive" || cap.effect === "external-side-effect")) {
+      return finalize({ status: "error", error: stale("surface-version-mismatch") });
+    }
+    if (resolvedAuditLevel !== "none") {
+      internals.recordAudit({
+        type: "invocation-started",
+        capabilityId: cap.capabilityId,
+        registrationId: reg.id,
+        invocationId,
+        consumerId: consumerKey
+      });
+    }
+    const availability = computeAvailability(internals, reg, cap);
+    if (!availability.available) {
+      return finalize({ status: "error", error: notAvailable(availability.reason) });
+    }
+    const host = internals.host();
+    const chain = policiesFor(internals, reg, cap);
+    const policyCtx = buildPolicyContext(internals, reg, cap, consumer, host);
+    const discovery = evaluateDiscovery(
+      chain.filter((p) => !p.onAuthorize && !p.onInvoke),
+      policyCtx
+    );
+    if (discovery.decision === "hide") {
+      return finalize({ status: "error", error: notFound() });
+    }
+    if (discovery.decision === "disable") {
+      return finalize({ status: "error", error: notAvailable(discovery.reason) });
+    }
+    const escalations = chain.map((p) => p[CONFIRMATION_ESCALATION]).filter((e) => e !== void 0);
+    const core = () => executeCore(internals, {
+      request,
+      invocationId,
+      consumer,
+      consumerKey,
+      host,
+      reg,
+      cap,
+      chain,
+      policyCtx,
+      escalations,
+      options,
+      finalize,
+      setAuditPayload: (input, output) => {
+        if (input !== void 0) inputForAudit = input;
+        if (output !== void 0) outputForAudit = output;
+      },
+      setTimings: (timings) => {
+        if (timings.queueWaitMs !== void 0) queueWaitMsForAudit = timings.queueWaitMs;
+        if (timings.executionMs !== void 0) executionMsForAudit = timings.executionMs;
+      }
+    });
+    try {
+      return await composeAuthorizeChain(chain, policyCtx, core);
+    } catch (err) {
+      if (isAgentSurfaceError(err)) {
+        return finalize({ status: "error", error: err.payload });
+      }
+      throw err;
+    }
+  } catch (err) {
+    if (err instanceof DevDefectError) throw err;
+    if (isAgentSurfaceError(err)) {
+      return finalize({ status: "error", error: err.payload });
+    }
+    internals.devError("[agent-surface] invocation pipeline failure", err);
+    return finalize({ status: "error", error: executionFailed("handler-error") });
+  }
+}
+function resolveTarget(internals, request) {
+  const parsed = parseCapabilityId(request.capabilityId);
+  if (!parsed) return { error: notFound() };
+  let candidates = [];
+  if (parsed.plane === "view") {
+    for (const reg of internals.registrations.values()) {
+      if (reg.status !== "active" || reg.type !== parsed.componentType) continue;
+      const cap = reg.observations.get(parsed.name) ?? reg.actions.get(parsed.name);
+      if (cap) candidates.push({ reg, cap });
+    }
+  } else {
+    for (const reg of internals.registrations.values()) {
+      if (reg.status !== "active") continue;
+      for (const proc of reg.procedures) {
+        if (proc.path === parsed.path) candidates.push({ reg, cap: proc });
+      }
+    }
+  }
+  if (request.instanceId !== void 0) {
+    candidates = candidates.filter((c) => c.reg.instanceId === request.instanceId);
+  }
+  candidates.sort(
+    (a, b) => a.reg.instanceId < b.reg.instanceId ? -1 : a.reg.instanceId > b.reg.instanceId ? 1 : 0
+  );
+  if (request.registrationId !== void 0) {
+    const live = candidates.find((c) => c.reg.id === request.registrationId);
+    if (live) return live;
+    const tombstone = internals.tombstones.get(request.registrationId);
+    const tombstoned = tombstone !== void 0 && tombstone.expiresAt > internals.now();
+    if (candidates.length > 0) {
+      const reason = tombstoned ? "registration-replaced" : "surface-reloaded";
+      return { error: stale(reason, candidates[0]?.reg.id) };
+    }
+    if (tombstoned) {
+      return { error: unmounted("resolve") };
+    }
+    return { error: notFound() };
+  }
+  if (candidates.length === 0) {
+    for (const tomb of internals.tombstones.values()) {
+      if (tomb.expiresAt <= internals.now()) continue;
+      if (tomb.capabilityIds.has(request.capabilityId)) {
+        return { error: unmounted("resolve") };
+      }
+    }
+    return { error: notFound() };
+  }
+  if (candidates.length > 1) {
+    const instances = candidates.map((c) => {
+      const entry = {
+        instanceId: c.reg.instanceId,
+        registrationId: c.reg.id
+      };
+      if (c.cap.kind === "procedure") {
+        if (c.cap.contextLink) entry.context = { ...c.cap.contextLink };
+      } else {
+        entry.description = c.reg.description;
+      }
+      return entry;
+    });
+    return {
+      error: {
+        code: "AMBIGUOUS_INSTANCE",
+        message: "More than one live instance matches this capability. Re-issue the call with an explicit instanceId or registrationId.",
+        retry: "with-changes",
+        details: { instances }
+      }
+    };
+  }
+  return candidates[0];
+}
+async function executeCore(internals, args) {
+  const { cap } = args;
+  if (cap.kind === "observation") return executeObservation(internals, args, cap);
+  if (cap.kind === "action") return executeAction(internals, args, cap);
+  return executeProcedure(internals, args, cap);
+}
+function runInvokePolicies(args, effectiveInput, downstream) {
+  const invokeCtx = {
+    ...args.policyCtx,
+    invocationId: args.invocationId,
+    effectiveInput
+  };
+  return composeInvokeChain(args.chain, invokeCtx, downstream);
+}
+async function executeObservation(internals, args, cap) {
+  const { reg, invocationId, consumer, consumerKey, host, options, finalize } = args;
+  const readCtx = {
+    capabilityId: cap.capabilityId,
+    registrationId: reg.id,
+    consumer,
+    host
+  };
+  const run = async () => {
+    const queueStart = internals.now();
+    const slot = await acquireObservationSlot(internals, consumerKey);
+    args.setTimings({ queueWaitMs: internals.now() - queueStart });
+    if (slot === "overflow") {
+      return finalize({ status: "error", error: queueFull(250) });
+    }
+    if (slot === "cancelled") {
+      return finalize({
+        status: "error",
+        error: { ...cancelled("The registry was disposed."), retry: "no" }
+      });
+    }
+    try {
+      const timeoutMs = options?.timeoutMs ?? cap.timeoutMs ?? internals.limits.observationTimeoutMs;
+      const executeStart = internals.now();
+      const outcome = await executeWithGuards(internals, reg, {
+        invocationId,
+        capabilityId: cap.capabilityId,
+        timeoutMs,
+        externalSignal: options?.signal,
+        idempotent: true,
+        run: () => {
+          const live = reg.definition.observations?.[cap.name];
+          if (!live) throw new Error("observation handler missing");
+          return live.read(readCtx);
+        }
+      });
+      args.setTimings({ executionMs: internals.now() - executeStart });
+      if (!outcome.ok) return finalize({ status: "error", error: outcome.payload });
+      const output = settleOutput(internals, outcome.value, cap.outputSchema);
+      if ("error" in output) return finalize({ status: "error", error: output.error });
+      return finalize({ status: "ok", output: output.value });
+    } finally {
+      releaseObservationSlot(internals, consumerKey);
+    }
+  };
+  return runInvokePolicies(args, {}, run);
+}
+async function executeAction(internals, args, cap) {
+  const { request, reg, invocationId, consumer, host, options, finalize } = args;
+  let parsedInput;
+  try {
+    parsedInput = cap.inputSchema.parse(request.input);
+  } catch (err) {
+    return finalize({ status: "error", error: invalidInput(err) });
+  }
+  args.setAuditPayload(parsedInput, void 0);
+  const readCtx = {
+    capabilityId: cap.capabilityId,
+    registrationId: reg.id,
+    consumer,
+    host
+  };
+  const run = async () => {
+    const confirmation = gateConfirmation(internals, {
+      ...args,
+      effectiveInput: parsedInput,
+      declared: cap.confirmation,
+      description: cap.description,
+      effect: cap.effect
+    });
+    if ("error" in confirmation) return finalize({ status: "error", error: confirmation.error });
+    const livePrecondition = reg.definition.actions?.[cap.name]?.precondition;
+    if (livePrecondition) {
+      try {
+        const failure = livePrecondition(parsedInput, readCtx);
+        if (failure && typeof failure.message === "string") {
+          return finalize({
+            status: "error",
+            error: preconditionFailed(failure.message, failure.details)
+          });
+        }
+      } catch (err) {
+        if (isAgentSurfaceError(err)) return finalize({ status: "error", error: err.payload });
+        if (!(err instanceof Error) && typeof err === "object" && err !== null && typeof err.message === "string") {
+          const failure = err;
+          return finalize({
+            status: "error",
+            error: preconditionFailed(failure.message, failure.details)
+          });
+        }
+        internals.devError(`[agent-surface] precondition threw for ${cap.capabilityId}`, err);
+        return finalize({ status: "error", error: executionFailed("handler-error") });
+      }
+    }
+    const queueStart = internals.now();
+    const slot = await acquireActionSlot(internals, reg);
+    args.setTimings({ queueWaitMs: internals.now() - queueStart });
+    if (slot === "overflow") {
+      return finalize({ status: "error", error: queueFull(250) });
+    }
+    try {
+      const timeoutMs = options?.timeoutMs ?? cap.timeoutMs ?? internals.limits.actionTimeoutMs;
+      const executeStart = internals.now();
+      const outcome = await executeWithGuards(internals, reg, {
+        invocationId,
+        capabilityId: cap.capabilityId,
+        timeoutMs,
+        externalSignal: options?.signal,
+        idempotent: cap.idempotent,
+        navigationSettlement: cap.effect === "navigation",
+        run: (signal) => {
+          const live = reg.definition.actions?.[cap.name];
+          if (!live) throw new Error("action handler missing");
+          const actionCtx = {
+            ...readCtx,
+            invocationId,
+            signal,
+            ...confirmation.evidence ? { confirmation: confirmation.evidence } : {}
+          };
+          return live.execute(parsedInput, actionCtx);
+        }
+      });
+      args.setTimings({ executionMs: internals.now() - executeStart });
+      if (!outcome.ok) return finalize({ status: "error", error: outcome.payload });
+      const output = settleOutput(internals, outcome.value, cap.outputSchema);
+      if ("error" in output) return finalize({ status: "error", error: output.error });
+      args.setAuditPayload(void 0, output.value);
+      return finalize({ status: "ok", output: output.value });
+    } finally {
+      releaseActionSlot(reg);
+    }
+  };
+  return runInvokePolicies(args, parsedInput, run);
+}
+async function executeProcedure(internals, args, cap) {
+  const { request, reg, invocationId, consumer, options, finalize } = args;
+  const agentInput = request.input ?? {};
+  if (typeof agentInput !== "object" || agentInput === null || Array.isArray(agentInput)) {
+    return finalize({
+      status: "error",
+      error: invalidInput(new AgentSchemaError([{ path: "", message: "input must be an object" }]))
+    });
+  }
+  const suppliedLocked = Object.keys(agentInput).filter((k) => cap.lockedKeys.includes(k));
+  if (suppliedLocked.length > 0) {
+    return finalize({
+      status: "error",
+      error: {
+        code: "INVALID_INPUT",
+        message: "Some fields are bound to the application's UI state and cannot be supplied by the agent. Omit them and retry.",
+        retry: "with-changes",
+        details: { lockedFields: suppliedLocked }
+      }
+    });
+  }
+  try {
+    fromJsonSchema(cap.reducedInputSchema).parse(agentInput);
+  } catch (err) {
+    return finalize({ status: "error", error: invalidInput(err) });
+  }
+  let bound = {};
+  const bind = cap.binding.config.bind;
+  if (bind) {
+    try {
+      bound = bind() ?? {};
+    } catch (err) {
+      internals.devWarn(`[agent-surface] bind() threw for ${cap.capabilityId}`, err);
+      return finalize({ status: "error", error: bindingFailed() });
+    }
+  }
+  const effective = {};
+  for (const [key, value] of Object.entries(agentInput)) {
+    if (!cap.lockedKeys.includes(key)) effective[key] = value;
+  }
+  for (const key of cap.boundKeys) {
+    const agentSupplied = cap.overridableKeys.has(key) && agentInput[key] !== void 0;
+    if (!agentSupplied && bound[key] !== void 0) effective[key] = bound[key];
+  }
+  try {
+    fromJsonSchema(cap.fullInputSchema).parse(effective);
+  } catch (err) {
+    internals.devWarn(
+      `[agent-surface] merged input for ${cap.capabilityId} failed full-schema validation`,
+      err
+    );
+    return finalize({ status: "error", error: bindingFailed() });
+  }
+  args.setAuditPayload(effective, void 0);
+  const run = async () => {
+    const confirmation = gateConfirmation(internals, {
+      ...args,
+      effectiveInput: effective,
+      declared: cap.confirmationFloor,
+      description: cap.baseDescription,
+      effect: cap.effect
+    });
+    if ("error" in confirmation) return finalize({ status: "error", error: confirmation.error });
+    const executor = internals.executor;
+    if (!executor) {
+      return finalize({ status: "error", error: executionFailed("transport") });
+    }
+    const timeoutMs = options?.timeoutMs ?? internals.limits.procedureTimeoutMs;
+    const executeStart = internals.now();
+    const outcome = await executeWithGuards(internals, reg, {
+      invocationId,
+      capabilityId: cap.capabilityId,
+      timeoutMs,
+      externalSignal: options?.signal,
+      idempotent: cap.idempotent,
+      run: (signal) => executor.execute({
+        path: cap.path,
+        input: effective,
+        info: {
+          invocationId,
+          consumer,
+          signal,
+          ...confirmation.evidence ? { confirmation: confirmation.evidence } : {}
+        }
+      }),
+      procedureErrors: true
+    });
+    args.setTimings({ executionMs: internals.now() - executeStart });
+    if (!outcome.ok) return finalize({ status: "error", error: outcome.payload });
+    const output = settleOutput(
+      internals,
+      outcome.value,
+      cap.outputJsonSchema ? fromJsonSchema(cap.outputJsonSchema) : void 0
+    );
+    if ("error" in output) return finalize({ status: "error", error: output.error });
+    args.setAuditPayload(void 0, output.value);
+    return finalize({ status: "ok", output: output.value });
+  };
+  return runInvokePolicies(args, effective, run);
+}
+function gateConfirmation(internals, args) {
+  const { request, reg, cap, consumerKey, escalations, effectiveInput, declared } = args;
+  const activeEscalations = escalations.filter((e) => {
+    if (!e.if) return true;
+    try {
+      return e.if({ ...args.policyCtx, effectiveInput });
+    } catch {
+      return true;
+    }
+  });
+  const effective = maxConfirmation(declared, activeEscalations.length > 0 ? "required" : "never");
+  if (effective !== "required") return {};
+  const summaryComposer = activeEscalations.find((e) => e.summary)?.summary;
+  let summary;
+  try {
+    summary = summaryComposer ? summaryComposer(effectiveInput) : `${args.description} \u2014 input: ${JSON.stringify(effectiveInput)}`;
+  } catch {
+    summary = args.description;
+  }
+  summary = truncate(summary, 300);
+  const digest = canonicalJson({
+    surfaceId: internals.surfaceId,
+    registrationId: reg.id,
+    capabilityId: cap.capabilityId,
+    consumerKey,
+    effectiveInput,
+    effect: args.effect
+  });
+  if (request.confirmationId) {
+    const consumed = internals.confirmations.consume({
+      confirmationId: request.confirmationId,
+      digest,
+      input: effectiveInput
+    });
+    if (consumed.ok) {
+      return { evidence: { id: request.confirmationId, approvedAt: consumed.approvedAt } };
+    }
+    if (consumed.kind === "pending-again") {
+      return { error: confirmationRequired(consumed.record, args.effect) };
+    }
+    return {
+      error: {
+        code: "CONFIRMATION_INVALID",
+        message: consumed.reason === "denied" ? "The user declined this action. Do not retry; respect the decision." : consumed.reason === "expired" ? "The confirmation expired. Request a fresh confirmation." : consumed.reason === "consumed" ? "This confirmation was already used. Request a fresh confirmation if the action is still needed." : "The confirmation does not match this exact invocation.",
+        retry: consumed.reason === "expired" ? "with-confirmation" : "no",
+        details: { reason: consumed.reason }
+      }
+    };
+  }
+  const record = internals.confirmations.request({
+    capabilityId: cap.capabilityId,
+    registrationId: reg.id,
+    consumerKey,
+    effect: args.policyCtx.effect,
+    input: effectiveInput,
+    summary,
+    digest
+  });
+  if (record === "overflow") {
+    return { error: queueFull(1e3) };
+  }
+  return { error: confirmationRequired(record, args.effect) };
+}
+function confirmationRequired(record, effect) {
+  return {
+    code: "CONFIRMATION_REQUIRED",
+    message: "User approval is required for this action. Wait for the user to resolve the confirmation, then retry with the confirmationId.",
+    retry: "with-confirmation",
+    details: {
+      confirmationId: record.confirmationId,
+      summary: record.summary,
+      expiresAt: record.expiresAt,
+      effect,
+      origin: "client"
+    }
+  };
+}
+function invalidInput(err) {
+  const issues = err instanceof AgentSchemaError ? err.issues.map((i) => ({ path: i.path, message: i.message })) : [{ path: "", message: "Input failed schema validation" }];
+  return {
+    code: "INVALID_INPUT",
+    message: "The input does not match the capability's schema. Fix the listed issues and retry.",
+    retry: "with-changes",
+    details: { issues }
+  };
+}
+function preconditionFailed(message, details) {
+  return {
+    code: "PRECONDITION_FAILED",
+    message: truncate(message, 300),
+    retry: "with-changes",
+    ...details ? { details } : {}
+  };
+}
+function bindingFailed() {
+  return {
+    code: "PRECONDITION_FAILED",
+    message: "The UI-derived input binding could not be evaluated. Refresh the surface and check availability before retrying.",
+    retry: "after-refresh",
+    details: { reason: "binding-failed" }
+  };
+}
+function settleOutput(internals, value, schema) {
+  if (value === void 0) return {};
+  let parsed = value;
+  if (schema) {
+    try {
+      parsed = schema.parse(value);
+    } catch (err) {
+      internals.devError("[agent-surface] output failed schema validation", err);
+      return { error: executionFailed("output-invalid") };
+    }
+  }
+  if (!isJsonValue(parsed)) {
+    if (internals.environment !== "production") {
+      throw new DevDefectError(
+        "capability output is not a JsonValue (functions, symbols, bigints, Dates, or cycles are defects \u2014 docs/03 \xA7serialization)"
+      );
+    }
+    return { error: executionFailed("output-invalid") };
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(parsed);
+  } catch {
+    if (internals.environment !== "production") {
+      throw new DevDefectError("capability output cannot be serialized to JSON");
+    }
+    return { error: executionFailed("output-invalid") };
+  }
+  if (serialized.length > internals.limits.maxOutputBytes) {
+    return { error: executionFailed("output-too-large") };
+  }
+  return { value: parsed };
+}
+function executeWithGuards(internals, reg, opts) {
+  return new Promise((resolve) => {
+    const controller = new AbortController();
+    let settled = false;
+    let timer;
+    const entry = {
+      onUnregister() {
+        controller.abort();
+        if (!opts.navigationSettlement) {
+          finish({ ok: false, payload: unmounted("mid-flight") });
+        }
+      },
+      onDispose() {
+        controller.abort();
+        finish({
+          ok: false,
+          payload: { code: "CANCELLED", message: "The registry was disposed.", retry: "no" }
+        });
+      }
+    };
+    const onExternalAbort = () => {
+      controller.abort();
+      finish({
+        ok: false,
+        payload: cancelled("The invocation was cancelled by the host.")
+      });
+    };
+    const finish = (outcome) => {
+      if (settled) return false;
+      settled = true;
+      if (timer !== void 0) clearTimeout(timer);
+      reg.inFlight.delete(entry);
+      opts.externalSignal?.removeEventListener("abort", onExternalAbort);
+      resolve(outcome);
+      return true;
+    };
+    const lateSettlement = () => {
+      internals.recordAudit({
+        type: "late-settlement",
+        capabilityId: opts.capabilityId,
+        registrationId: reg.id,
+        invocationId: opts.invocationId
+      });
+    };
+    const handlerError = (err) => {
+      if (isAgentSurfaceError(err)) return { ok: false, payload: err.payload };
+      if (opts.navigationSettlement && controller.signal.aborted) {
+        return { ok: false, payload: cancelled("The navigation was abandoned after its owner unmounted.") };
+      }
+      internals.devError(`[agent-surface] handler failed for ${opts.capabilityId}`, err);
+      return {
+        ok: false,
+        payload: executionFailed(opts.procedureErrors ? "transport" : "handler-error", {
+          transient: opts.procedureErrors === true && typeof err === "object" && err !== null && err.transient === true
+        })
+      };
+    };
+    if (internals.disposed) {
+      resolve({
+        ok: false,
+        payload: { code: "CANCELLED", message: "The registry was disposed.", retry: "no" }
+      });
+      return;
+    }
+    if (reg.status !== "active") {
+      resolve({ ok: false, payload: unmounted("mid-flight") });
+      return;
+    }
+    if (opts.externalSignal?.aborted) {
+      resolve({
+        ok: false,
+        payload: cancelled("The invocation was cancelled by the host.")
+      });
+      return;
+    }
+    opts.externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+    timer = setTimeout(() => {
+      controller.abort();
+      finish({
+        ok: false,
+        payload: {
+          code: "TIMEOUT",
+          message: opts.idempotent ? "The capability timed out. It is idempotent; retrying with a new invocationId is safe." : "The capability timed out and side effects may or may not have occurred. Verify state with an observation before repeating.",
+          retry: opts.idempotent ? "yes" : "no",
+          details: { timeoutMs: opts.timeoutMs, idempotent: opts.idempotent }
+        }
+      });
+    }, opts.timeoutMs);
+    reg.inFlight.add(entry);
+    let returned;
+    try {
+      returned = opts.run(controller.signal);
+    } catch (err) {
+      finish(handlerError(err));
+      return;
+    }
+    if (returned !== null && (typeof returned === "object" || typeof returned === "function") && typeof returned.then === "function") {
+      returned.then(
+        (value) => {
+          if (!finish({ ok: true, value })) lateSettlement();
+        },
+        (err) => {
+          if (!finish(handlerError(err))) lateSettlement();
+        }
+      );
+    } else {
+      finish({ ok: true, value: returned });
+    }
+  });
+}
+async function acquireActionSlot(internals, reg) {
+  if (!reg.actionQueue.running) {
+    reg.actionQueue.running = true;
+    return "ok";
+  }
+  if (reg.actionQueue.waiting.length >= internals.limits.actionQueueDepth) {
+    return "overflow";
+  }
+  await new Promise((resolve) => reg.actionQueue.waiting.push(resolve));
+  return "ok";
+}
+function releaseActionSlot(reg) {
+  const next = reg.actionQueue.waiting.shift();
+  if (next) next();
+  else reg.actionQueue.running = false;
+}
+function acquireObservationSlot(internals, consumerKey) {
+  const adm = internals.observationAdmission;
+  const perCap = internals.limits.maxConcurrentObservationsPerConsumer;
+  const totalCap = internals.limits.maxConcurrentObservationsTotal;
+  const held = adm.perConsumer.get(consumerKey) ?? 0;
+  if (held < perCap && adm.total < totalCap) {
+    adm.perConsumer.set(consumerKey, held + 1);
+    adm.total += 1;
+    return Promise.resolve("ok");
+  }
+  let queued = 0;
+  for (const waiter of adm.waiting) {
+    if (waiter.consumerKey === consumerKey) queued += 1;
+  }
+  if (queued >= internals.limits.maxQueuedObservationsPerConsumer) {
+    return Promise.resolve("overflow");
+  }
+  return new Promise((resolve) => {
+    adm.waiting.push({
+      consumerKey,
+      admit: (admitted) => resolve(admitted ? "ok" : "cancelled")
+    });
+  });
+}
+function releaseObservationSlot(internals, consumerKey) {
+  const adm = internals.observationAdmission;
+  adm.total = Math.max(0, adm.total - 1);
+  const held = adm.perConsumer.get(consumerKey) ?? 0;
+  if (held <= 1) adm.perConsumer.delete(consumerKey);
+  else adm.perConsumer.set(consumerKey, held - 1);
+  const perCap = internals.limits.maxConcurrentObservationsPerConsumer;
+  const totalCap = internals.limits.maxConcurrentObservationsTotal;
+  for (let i = 0; i < adm.waiting.length; i++) {
+    const waiter = adm.waiting[i];
+    if (!waiter) continue;
+    const waiterHeld = adm.perConsumer.get(waiter.consumerKey) ?? 0;
+    if (waiterHeld < perCap && adm.total < totalCap) {
+      adm.waiting.splice(i, 1);
+      adm.perConsumer.set(waiter.consumerKey, waiterHeld + 1);
+      adm.total += 1;
+      waiter.admit(true);
+      return;
+    }
+  }
+}
+function drainObservationQueues(internals) {
+  const adm = internals.observationAdmission;
+  const waiting = adm.waiting.splice(0);
+  for (const waiter of waiting) waiter.admit(false);
+}
+
+// src/snapshot.ts
+var DEFAULT_CONSUMER2 = { id: "anonymous", kind: "embedded" };
+function matchesScope(type, scope) {
+  if (!scope || scope.length === 0) return true;
+  return scope.some((prefix) => type === prefix || type.startsWith(`${prefix}.`));
+}
+function sortRegistrations(regs) {
+  return regs.sort((a, b) => {
+    if (a.priority !== b.priority) return b.priority - a.priority;
+    if (a.type !== b.type) return a.type < b.type ? -1 : 1;
+    return a.instanceId < b.instanceId ? -1 : a.instanceId > b.instanceId ? 1 : 0;
+  });
+}
+function createSnapshot(internals, ctx) {
+  const consumer = ctx?.consumer ?? DEFAULT_CONSUMER2;
+  const includeUnavailable = ctx?.includeUnavailable ?? true;
+  const host = internals.host();
+  const regs = sortRegistrations(
+    [...internals.registrations.values()].filter((r) => r.status === "active")
+  );
+  const components = [];
+  const componentPriority = [];
+  const procedures = [];
+  for (const reg of regs) {
+    const inScopeForComponents = matchesScope(reg.type, ctx?.scope);
+    if (!reg.procedureOnly && inScopeForComponents) {
+      const observations = [];
+      const actions = [];
+      let definedCount = 0;
+      let hiddenCount = 0;
+      for (const obs of reg.observations.values()) {
+        definedCount += 1;
+        const chain = policiesFor(internals, reg, obs);
+        const policyCtx = buildPolicyContext(internals, reg, obs, consumer, host);
+        const decision = evaluateDiscovery(chain, policyCtx);
+        if (decision.decision === "hide") {
+          hiddenCount += 1;
+          continue;
+        }
+        const availability = computeAvailability(internals, reg, obs);
+        const available = availability.available && decision.decision === "expose";
+        const reason = decision.decision === "disable" ? decision.reason : availability.reason;
+        if (!available && !includeUnavailable) continue;
+        observations.push({
+          capabilityId: obs.capabilityId,
+          name: obs.name,
+          description: obs.description,
+          outputSchema: obs.jsonSchema,
+          available,
+          ...available ? {} : { unavailableReason: reason },
+          ...obs.meta ? { meta: obs.meta } : {}
+        });
+      }
+      for (const act of reg.actions.values()) {
+        definedCount += 1;
+        const chain = policiesFor(internals, reg, act);
+        const policyCtx = buildPolicyContext(internals, reg, act, consumer, host);
+        const decision = evaluateDiscovery(chain, policyCtx);
+        if (decision.decision === "hide") {
+          hiddenCount += 1;
+          continue;
+        }
+        const availability = computeAvailability(internals, reg, act);
+        const available = availability.available && decision.decision === "expose";
+        const reason = decision.decision === "disable" ? decision.reason : availability.reason;
+        if (!available && !includeUnavailable) continue;
+        actions.push({
+          capabilityId: act.capabilityId,
+          name: act.name,
+          description: act.description,
+          inputSchema: act.inputJsonSchema,
+          ...act.outputJsonSchema ? { outputSchema: act.outputJsonSchema } : {},
+          effect: act.effect,
+          idempotent: act.idempotent,
+          reversible: act.reversible,
+          confirmation: act.confirmation,
+          available,
+          ...available ? {} : { unavailableReason: reason },
+          ...act.meta ? { meta: act.meta } : {}
+        });
+      }
+      const allHidden = definedCount > 0 && hiddenCount === definedCount;
+      if (!allHidden) {
+        components.push({
+          type: reg.type,
+          instanceId: reg.instanceId,
+          registrationId: reg.id,
+          description: reg.description,
+          ...reg.parent ? { parent: reg.parent } : {},
+          ...reg.meta ? { meta: reg.meta } : {},
+          observations,
+          actions
+        });
+        componentPriority.push(reg.priority);
+      }
+    }
+    for (const proc of reg.procedures) {
+      const scopeMatch = proc.contextLink ? matchesScope(proc.contextLink.type, ctx?.scope) : matchesScope(proc.path, ctx?.scope);
+      if (!scopeMatch) continue;
+      const chain = policiesFor(internals, reg, proc);
+      const policyCtx = buildPolicyContext(internals, reg, proc, consumer, host);
+      const decision = evaluateDiscovery(chain, policyCtx);
+      if (decision.decision === "hide") continue;
+      const availability = computeAvailability(internals, reg, proc);
+      const available = availability.available && decision.decision === "expose";
+      const reason = decision.decision === "disable" ? decision.reason : availability.reason;
+      if (!available && !includeUnavailable) continue;
+      let description = proc.baseDescription;
+      const describe = proc.binding.config.describe;
+      if (describe) {
+        try {
+          const contextual = describe();
+          if (contextual) description = `${description} ${contextual}`.trim();
+        } catch {
+        }
+      }
+      procedures.push({
+        procedureId: proc.capabilityId,
+        description,
+        inputSchema: proc.reducedInputSchema,
+        ...proc.outputJsonSchema ? { outputSchema: proc.outputJsonSchema } : {},
+        effect: proc.effect,
+        confirmation: proc.confirmationFloor,
+        available,
+        ...available ? {} : { unavailableReason: reason },
+        boundFields: proc.boundKeys.map((path) => ({
+          path,
+          locked: proc.lockedKeys.includes(path),
+          source: "ui-state"
+        })),
+        registrationId: reg.id,
+        ...proc.contextLink ? { context: proc.contextLink } : {},
+        ...proc.meta ? { meta: proc.meta } : {}
+      });
+    }
+  }
+  let dropped = 0;
+  const budget = ctx?.budget;
+  if (budget?.maxComponents !== void 0 && components.length > budget.maxComponents) {
+    dropped += components.length - budget.maxComponents;
+    dropLowestPriority(components, componentPriority, components.length - budget.maxComponents);
+  }
+  if (budget?.maxBytes !== void 0) {
+    while (components.length > 0 && byteLength(components) > budget.maxBytes) {
+      dropLowestPriority(components, componentPriority, 1);
+      dropped += 1;
+    }
+  }
+  const snapshot = {
+    surfaceId: internals.surfaceId,
+    surfaceVersion: String(internals.version),
+    capturedAt: new Date(internals.now()).toISOString(),
+    ...internals.routeFn?.() ? { route: internals.routeFn() } : {},
+    components,
+    procedures,
+    ...dropped > 0 ? { truncated: { droppedComponents: dropped } } : {}
+  };
+  return deepFreeze(snapshot);
+}
+function dropLowestPriority(components, priorities, count) {
+  for (let n = 0; n < count && components.length > 0; n++) {
+    let lowestIndex = 0;
+    for (let i = 1; i < priorities.length; i++) {
+      if ((priorities[i] ?? 0) <= (priorities[lowestIndex] ?? 0)) lowestIndex = i;
+    }
+    components.splice(lowestIndex, 1);
+    priorities.splice(lowestIndex, 1);
+  }
+}
+
+// src/registry.ts
+function createAgentSurfaceRegistry(options) {
+  const environment2 = options?.environment ?? "production";
+  const limits = { ...DEFAULT_LIMITS, ...options?.limits ?? {} };
+  const now = options?.now ?? (() => Date.now());
+  const auditSink = options?.audit ?? (environment2 === "development" ? combineSinks(memoryAuditSink(), consoleAuditSink()) : memoryAuditSink());
+  let surfaceChangedScheduled = false;
+  const dispatcher = new EventDispatcher((err) => {
+    if (environment2 === "development") {
+      console.error("[agent-surface] event listener threw", err);
+    }
+  });
+  const internals = {
+    environment: environment2,
+    limits,
+    surfaceId: `srf_${randomBase62(22)}`,
+    version: 0,
+    registrations: /* @__PURE__ */ new Map(),
+    byKey: /* @__PURE__ */ new Map(),
+    tombstones: /* @__PURE__ */ new Map(),
+    dedupe: /* @__PURE__ */ new Map(),
+    observationAdmission: { total: 0, perConsumer: /* @__PURE__ */ new Map(), waiting: [] },
+    dispatcher,
+    confirmations: void 0,
+    // set below
+    executor: void 0,
+    disposed: false,
+    registryPolicies: [...options?.policies ?? []],
+    auditSink,
+    contextFn: options?.context,
+    routeFn: options?.route,
+    now,
+    bumpVersion() {
+      internals.version += 1;
+      if (!surfaceChangedScheduled) {
+        surfaceChangedScheduled = true;
+        queueMicrotask(() => {
+          surfaceChangedScheduled = false;
+          if (internals.disposed) return;
+          internals.emit({ type: "surface-changed", surfaceVersion: String(internals.version) });
+        });
+      }
+    },
+    emit(event) {
+      dispatcher.emit(event);
+    },
+    recordAudit(event) {
+      safeRecord(auditSink, { at: new Date(now()).toISOString(), ...event });
+    },
+    host() {
+      try {
+        return internals.contextFn?.() ?? {};
+      } catch (err) {
+        internals.devWarn("[agent-surface] RegistryOptions.context() threw", err);
+        return {};
+      }
+    },
+    devWarn(...args) {
+      if (environment2 === "development") {
+        console.warn(...args);
+      }
+    },
+    devError(...args) {
+      if (environment2 === "development") {
+        console.error(...args);
+      }
+    }
+  };
+  internals.confirmations = new ConfirmationStore({
+    ttlMs: limits.confirmationTtlMs,
+    maxPending: limits.maxPendingConfirmations,
+    now,
+    emit: (event) => internals.emit(event),
+    audit: (event) => internals.recordAudit(event)
+  });
+  const onDuplicateInstance = options?.onDuplicateInstance ?? "reject";
+  const duplicateSuffixPolicy = options?.duplicateSuffixPolicy ?? "warn";
+  function deadHandle() {
+    const id = nextRegistrationId(() => randomBase62(6));
+    return {
+      registrationId: id,
+      status: "rejected",
+      update() {
+        internals.devWarn("[agent-surface] update() called on a rejected registration handle");
+      },
+      invalidate() {
+        internals.devWarn("[agent-surface] invalidate() called on a rejected registration handle");
+      },
+      unregister() {
+      }
+    };
+  }
+  function unregisterInternal(reg) {
+    if (reg.status !== "active") return;
+    reg.status = "unregistered";
+    internals.registrations.delete(reg.id);
+    if (internals.byKey.get(reg.key) === reg.id) internals.byKey.delete(reg.key);
+    addTombstone(internals, reg);
+    for (const entry of [...reg.inFlight]) {
+      entry.onUnregister();
+    }
+    internals.bumpVersion();
+    internals.emit({
+      type: "component-unregistered",
+      registrationId: reg.id,
+      componentType: reg.type,
+      instanceId: reg.instanceId
+    });
+    internals.recordAudit({
+      type: "unregistration",
+      registrationId: reg.id,
+      capabilityId: void 0
+    });
+  }
+  function checkSuffixCollisions(def) {
+    if (duplicateSuffixPolicy === "off") return;
+    const paths = internals.executor?.paths;
+    if (!paths || paths.length === 0) return;
+    const names = [
+      ...Object.keys(def.observations ?? {}),
+      ...Object.keys(def.actions ?? {})
+    ];
+    for (const name of names) {
+      const candidatePath = `${def.type}.${name}`;
+      if (paths.includes(candidatePath)) {
+        const viewCapabilityId = formatViewCapabilityId(def.type, name);
+        const domainProcedureId = `domain:${candidatePath}`;
+        if (duplicateSuffixPolicy === "error") {
+          throw new AgentSurfaceDefinitionError(
+            "PLANE_VIOLATION",
+            `view capability "${viewCapabilityId}" collides with domain procedure "${domainProcedureId}" \u2014 reference the procedure instead of redefining it (docs/05)`
+          );
+        }
+        internals.devWarn(
+          `[agent-surface] suspicious suffix collision: "${viewCapabilityId}" vs "${domainProcedureId}"`
+        );
+        internals.emit({ type: "collision-suspected", viewCapabilityId, domainProcedureId });
+        internals.recordAudit({
+          type: "collision-suspected",
+          capabilityId: viewCapabilityId
+        });
+      }
+    }
+  }
+  const registry = {
+    surfaceId: internals.surfaceId,
+    register(definition) {
+      if (internals.disposed) throw new Error("register() called on a disposed registry");
+      validateComponentDefinition(definition, limits, {
+        hasProcedureExecutor: internals.executor !== void 0
+      });
+      checkSuffixCollisions(definition);
+      const instanceId = definition.instanceId ?? "default";
+      if (options?.onRegister) {
+        let verdict = "accept";
+        try {
+          verdict = options.onRegister({
+            definition,
+            ...environment2 === "development" ? { stack: new Error().stack } : {}
+          });
+        } catch (err) {
+          internals.devError("[agent-surface] onRegister guard threw; rejecting", err);
+          verdict = "reject";
+        }
+        if (verdict === "reject") {
+          internals.emit({
+            type: "component-rejected",
+            componentType: definition.type,
+            instanceId,
+            reason: "guard"
+          });
+          internals.recordAudit({ type: "registration-rejected" });
+          internals.devError(
+            `[agent-surface] registration of "${definition.type}" (${instanceId}) rejected by guard`
+          );
+          return deadHandle();
+        }
+      }
+      const key = componentKey(definition.type, instanceId);
+      const existingId = internals.byKey.get(key);
+      if (existingId !== void 0) {
+        if (onDuplicateInstance === "reject") {
+          internals.emit({
+            type: "component-rejected",
+            componentType: definition.type,
+            instanceId,
+            reason: "duplicate"
+          });
+          internals.recordAudit({ type: "registration-rejected" });
+          internals.devError(
+            `[agent-surface] duplicate registration of "${definition.type}" (${instanceId}); first-wins (onDuplicateInstance: "reject")`
+          );
+          return deadHandle();
+        }
+        const existing = internals.registrations.get(existingId);
+        if (existing) unregisterInternal(existing);
+      }
+      const reg = normalizeRegistration(definition, nextRegistrationId(() => randomBase62(6)));
+      internals.registrations.set(reg.id, reg);
+      internals.byKey.set(reg.key, reg.id);
+      internals.bumpVersion();
+      internals.emit({
+        type: "component-registered",
+        registrationId: reg.id,
+        componentType: reg.type,
+        instanceId: reg.instanceId
+      });
+      internals.recordAudit({ type: "registration", registrationId: reg.id });
+      return {
+        get registrationId() {
+          return reg.id;
+        },
+        get status() {
+          return reg.status === "active" ? "active" : "unregistered";
+        },
+        update(patch) {
+          if (reg.status !== "active") {
+            internals.devWarn(
+              `[agent-surface] update() called after unregistration of "${reg.type}"`
+            );
+            return;
+          }
+          let changed = false;
+          if (patch.enabled !== void 0 && patch.enabled !== reg.enabled) {
+            reg.enabled = patch.enabled;
+            changed = true;
+          }
+          if (patch.availability) {
+            for (const [name, value] of Object.entries(patch.availability)) {
+              const prev = reg.availabilityOverrides.get(name);
+              if (!prev || prev.available !== value.available || prev.reason !== value.reason) {
+                reg.availabilityOverrides.set(name, {
+                  available: value.available,
+                  ...value.reason !== void 0 ? { reason: value.reason } : {}
+                });
+                changed = true;
+                const capabilityId = reg.observations.get(name)?.capabilityId ?? reg.actions.get(name)?.capabilityId ?? reg.procedures.find((p) => p.path === name)?.capabilityId ?? name;
+                internals.emit({
+                  type: "availability-changed",
+                  registrationId: reg.id,
+                  capabilityId,
+                  available: value.available
+                });
+              }
+            }
+          }
+          if (changed) internals.bumpVersion();
+        },
+        invalidate() {
+          if (reg.status !== "active") return;
+          internals.bumpVersion();
+        },
+        unregister() {
+          unregisterInternal(reg);
+        }
+      };
+    },
+    snapshot(context) {
+      if (internals.disposed) throw new Error("snapshot() called on a disposed registry");
+      return createSnapshot(internals, context);
+    },
+    invoke(request, invokeOptions) {
+      return performInvoke(internals, request, invokeOptions);
+    },
+    subscribe(listener) {
+      return dispatcher.subscribe(listener);
+    },
+    confirmations: internals.confirmations.controller(),
+    setProcedureExecutor(executor) {
+      internals.executor = executor;
+    },
+    getVersion() {
+      return String(internals.version);
+    },
+    dispose() {
+      if (internals.disposed) return;
+      for (const reg of [...internals.registrations.values()]) {
+        for (const entry of [...reg.inFlight]) {
+          entry.onDispose();
+        }
+        reg.status = "unregistered";
+      }
+      drainObservationQueues(internals);
+      internals.registrations.clear();
+      internals.byKey.clear();
+      internals.confirmations.disposeAll();
+      internals.disposed = true;
+      dispatcher.clear();
+    }
+  };
+  return registry;
+}
+function combineSinks(...sinks) {
+  return {
+    record(event) {
+      for (const sink of sinks) safeRecord(sink, event);
+    }
+  };
+}
+
+// src/toolset.ts
+var EMPTY_INPUT_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+function describePrefix(plane, effect, confirmation, available, unavailableReason) {
+  const parts = [plane, effect];
+  if (confirmation === "required") parts.push("requires confirmation");
+  let prefix = `[${parts.join(" \xB7 ")}]`;
+  if (!available) {
+    prefix += ` [currently unavailable${unavailableReason ? `: ${unavailableReason}` : ""}]`;
+  }
+  return prefix;
+}
+function createAgentToolset(registry, options) {
+  const mode = options.mode ?? "direct";
+  if (options.confirmations === void 0 && options.topology === void 0) {
+    throw new Error(
+      "createAgentToolset: declare a topology ('embedded' | 'remote') or an explicit confirmations mode ('wait' | 'two-phase'). Embedded loops default to 'wait', remote loops to 'two-phase' (docs/09 \xA7confirmation-topology)."
+    );
+  }
+  const confirmationsMode = options.confirmations ?? (options.topology === "remote" ? "two-phase" : "wait");
+  const listeners = /* @__PURE__ */ new Set();
+  const pendingWaits = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let cachedVersion;
+  let cachedTools;
+  let cachedSignature;
+  async function waitForConfirmation(confirmationId) {
+    if (disposed) return;
+    const controller = new AbortController();
+    pendingWaits.add(controller);
+    try {
+      await registry.confirmations.waitFor(confirmationId, { signal: controller.signal });
+    } finally {
+      pendingWaits.delete(controller);
+    }
+  }
+  async function invokeThroughSurface(entry, input, toolCallId) {
+    const invocationId = toolCallId ?? `inv_${randomBase62(12)}`;
+    const base = {
+      invocationId,
+      capabilityId: entry.capabilityId,
+      ...entry.instanceId !== void 0 ? { instanceId: entry.instanceId } : {},
+      registrationId: entry.registrationId,
+      surfaceVersion: entry.surfaceVersion,
+      ...input !== void 0 ? { input } : {}
+    };
+    let result = await registry.invoke(base, { consumer: options.consumer });
+    if (confirmationsMode === "wait" && result.status === "error" && result.error.code === "CONFIRMATION_REQUIRED") {
+      const confirmationId = result.error.details?.confirmationId;
+      if (typeof confirmationId === "string") {
+        await waitForConfirmation(confirmationId);
+        if (disposed) return result;
+        result = await registry.invoke(
+          { ...base, confirmationId },
+          { consumer: options.consumer }
+        );
+      }
+    }
+    return result;
+  }
+  function buildDirectTools() {
+    const snapshot = registry.snapshot({
+      consumer: options.consumer,
+      ...options.scope ? { scope: options.scope } : {},
+      includeUnavailable: true
+    });
+    const tools = [];
+    const push = (capabilityId, kind, registrationId, instanceId, description, inputSchema, nameSuffix) => {
+      const entry = {
+        capabilityId,
+        registrationId,
+        ...instanceId !== void 0 ? { instanceId } : {},
+        surfaceVersion: snapshot.surfaceVersion,
+        kind
+      };
+      tools.push({
+        // Providers require unique tool names: multi-instance capabilities
+        // are disambiguated with an `_at_<instance>` suffix (docs/09).
+        name: encodeWireNameForInstance(capabilityId, nameSuffix ?? instanceId),
+        description,
+        inputSchema,
+        execute: (input, call) => invokeThroughSurface(entry, input, call.toolCallId)
+      });
+    };
+    for (const component of snapshot.components) {
+      const multiInstance = snapshot.components.filter((c) => c.type === component.type).length > 1;
+      const instanceId = multiInstance ? component.instanceId : void 0;
+      for (const obs of component.observations) {
+        push(
+          obs.capabilityId,
+          "observation",
+          component.registrationId,
+          instanceId,
+          `${describePrefix("view", "read", "never", obs.available, obs.unavailableReason)} ${obs.description}`,
+          EMPTY_INPUT_SCHEMA
+        );
+      }
+      for (const act of component.actions) {
+        push(
+          act.capabilityId,
+          "action",
+          component.registrationId,
+          instanceId,
+          `${describePrefix("view", act.effect, act.confirmation, act.available, act.unavailableReason)} ${act.description}`,
+          act.inputSchema
+        );
+      }
+    }
+    const procedureCounts = /* @__PURE__ */ new Map();
+    for (const proc of snapshot.procedures) {
+      procedureCounts.set(proc.procedureId, (procedureCounts.get(proc.procedureId) ?? 0) + 1);
+    }
+    for (const proc of snapshot.procedures) {
+      const needsSuffix = (procedureCounts.get(proc.procedureId) ?? 0) > 1;
+      push(
+        proc.procedureId,
+        "procedure",
+        proc.registrationId,
+        void 0,
+        `${describePrefix("domain", proc.effect, proc.confirmation, proc.available, proc.unavailableReason)} ${proc.description}`,
+        proc.inputSchema,
+        needsSuffix ? proc.context?.instanceId ?? proc.registrationId.replace(/[^A-Za-z0-9_-]/g, "") : void 0
+      );
+    }
+    return tools;
+  }
+  function buildMetaTools() {
+    const snapshotFor = () => registry.snapshot({
+      consumer: options.consumer,
+      ...options.scope ? { scope: options.scope } : {}
+    });
+    return [
+      {
+        name: "surface_discover",
+        description: "[meta] Discover the current agent surface: components, capabilities, procedures, availability, schemas.",
+        inputSchema: {
+          type: "object",
+          properties: { scope: { type: "array", items: { type: "string" } } },
+          additionalProperties: false
+        },
+        async execute(input) {
+          const scope = input?.scope;
+          const snapshot = registry.snapshot({
+            consumer: options.consumer,
+            ...scope ? { scope } : options.scope ? { scope: options.scope } : {}
+          });
+          return {
+            status: "ok",
+            invocationId: `inv_${randomBase62(12)}`,
+            capabilityId: "meta:surface.discover",
+            output: JSON.parse(JSON.stringify(snapshot)),
+            surfaceVersion: snapshot.surfaceVersion
+          };
+        }
+      },
+      {
+        name: "surface_read",
+        description: "[meta] Invoke an observation by capabilityId and return its output.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            capabilityId: { type: "string" },
+            instanceId: { type: "string" }
+          },
+          required: ["capabilityId"],
+          additionalProperties: false
+        },
+        async execute(input, call) {
+          const req = input;
+          const snapshot = snapshotFor();
+          return invokeThroughSurface(
+            {
+              capabilityId: req.capabilityId,
+              registrationId: findRegistrationId(snapshot, req.capabilityId, req.instanceId) ?? "",
+              ...req.instanceId !== void 0 ? { instanceId: req.instanceId } : {},
+              surfaceVersion: snapshot.surfaceVersion,
+              kind: "observation"
+            },
+            void 0,
+            call.toolCallId
+          );
+        }
+      },
+      {
+        name: "surface_act",
+        description: "[meta] Invoke an action or procedure by capabilityId.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            capabilityId: { type: "string" },
+            instanceId: { type: "string" },
+            input: {},
+            invocationId: { type: "string" },
+            confirmationId: { type: "string" }
+          },
+          required: ["capabilityId"],
+          additionalProperties: false
+        },
+        async execute(input, call) {
+          const req = input;
+          const snapshot = snapshotFor();
+          const invocationId = req.invocationId ?? call.toolCallId ?? `inv_${randomBase62(12)}`;
+          let result = await registry.invoke(
+            {
+              invocationId,
+              capabilityId: req.capabilityId,
+              ...req.instanceId !== void 0 ? { instanceId: req.instanceId } : {},
+              ...findRegistrationId(snapshot, req.capabilityId, req.instanceId) ? { registrationId: findRegistrationId(snapshot, req.capabilityId, req.instanceId) } : {},
+              surfaceVersion: snapshot.surfaceVersion,
+              ...req.input !== void 0 ? { input: req.input } : {},
+              ...req.confirmationId !== void 0 ? { confirmationId: req.confirmationId } : {}
+            },
+            { consumer: options.consumer }
+          );
+          if (confirmationsMode === "wait" && result.status === "error" && result.error.code === "CONFIRMATION_REQUIRED" && typeof result.error.details?.confirmationId === "string") {
+            const confirmationId = result.error.details.confirmationId;
+            await waitForConfirmation(confirmationId);
+            if (disposed) return result;
+            result = await registry.invoke(
+              {
+                invocationId,
+                capabilityId: req.capabilityId,
+                ...req.instanceId !== void 0 ? { instanceId: req.instanceId } : {},
+                surfaceVersion: snapshot.surfaceVersion,
+                ...req.input !== void 0 ? { input: req.input } : {},
+                confirmationId
+              },
+              { consumer: options.consumer }
+            );
+          }
+          return result;
+        }
+      }
+    ];
+  }
+  function computeTools() {
+    if (mode === "meta") {
+      cachedTools ??= buildMetaTools();
+      return cachedTools;
+    }
+    const version = registry.getVersion();
+    if (cachedTools && cachedVersion === version) return cachedTools;
+    cachedTools = buildDirectTools();
+    cachedVersion = version;
+    return cachedTools;
+  }
+  function signatureOf(tools) {
+    return JSON.stringify(
+      tools.map((t) => [t.name, t.description, t.inputSchema])
+    );
+  }
+  const unsubscribe = registry.subscribe((event) => {
+    if (disposed || event.type !== "surface-changed") return;
+    cachedVersion = void 0;
+    const tools = computeTools();
+    const signature = signatureOf(tools);
+    if (signature === cachedSignature) return;
+    cachedSignature = signature;
+    for (const listener of [...listeners]) {
+      try {
+        listener(tools);
+      } catch {
+      }
+    }
+  });
+  return {
+    tools() {
+      const tools = computeTools();
+      cachedSignature ??= signatureOf(tools);
+      return tools;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose() {
+      disposed = true;
+      unsubscribe();
+      listeners.clear();
+      for (const controller of [...pendingWaits]) controller.abort();
+      pendingWaits.clear();
+    }
+  };
+}
+function findRegistrationId(snapshot, capabilityId, instanceId) {
+  const matches = [];
+  for (const component of snapshot.components) {
+    if (instanceId !== void 0 && component.instanceId !== instanceId) continue;
+    const all = [
+      ...component.observations,
+      ...component.actions
+    ];
+    if (all.some((c) => c.capabilityId === capabilityId)) matches.push(component.registrationId);
+  }
+  for (const proc of snapshot.procedures) {
+    if (proc.procedureId === capabilityId) matches.push(proc.registrationId);
+  }
+  return matches.length === 1 ? matches[0] : void 0;
+}
+export {
+  AGENT_CAPABILITY_ERROR_CODES,
+  AgentSchemaError,
+  AgentSurfaceDefinitionError,
+  AgentSurfaceError,
+  CONFIRMATION_ESCALATION,
+  DEFAULT_LIMITS,
+  MAX_ID_LENGTH,
+  MAX_WIRE_NAME_LENGTH,
+  action,
+  audit,
+  authenticated,
+  composeInvokeChain,
+  consoleAuditSink,
+  createAgentSurfaceRegistry,
+  createAgentToolset,
+  decodeWireName,
+  defineAgentComponent,
+  emptyObjectSchema,
+  encodeWireName,
+  encodeWireNameForInstance,
+  environment,
+  evaluateDiscovery,
+  formatDomainCapabilityId,
+  formatViewCapabilityId,
+  fromJsonSchema,
+  fromStandardSchema,
+  hasPermission,
+  isAgentSurfaceError,
+  isValidCapabilityName,
+  isValidComponentType,
+  isValidInstanceId,
+  jsonDeepEqual,
+  memoryAuditSink,
+  observation,
+  parseCapabilityId,
+  rateLimit,
+  requireConfirmation,
+  tenantBoundary,
+  validateComponentDefinition,
+  validateJsonSchemaDocument,
+  validateValueAgainstSchema
+};
+//# sourceMappingURL=index.js.map