@agent-surface/core 0.7.0 → 0.8.0

package/dist/chunk-77YRWAXY.js

@@ -0,0 +1,915 @@
+// 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/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/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 (typeof id !== "string" || 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;
+var SHORTENED_MARKER = "_0_";
+var INSTANCE_MARKER = "_at_";
+function hash36(input, length) {
+  let out = "";
+  for (let round = 0; out.length < length; round++) {
+    let hash = (2166136261 ^ round) >>> 0;
+    for (let i = 0; i < input.length; i++) {
+      hash ^= input.charCodeAt(i);
+      hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    out += hash.toString(36).padStart(7, "0");
+  }
+  return out.slice(0, length);
+}
+function rawWireName(id, instanceId) {
+  const encoded = id.replace(":", "_").replaceAll(".", "__");
+  return instanceId ? `${encoded}${INSTANCE_MARKER}${instanceId}` : encoded;
+}
+function encodeWireName(id) {
+  return encodeWireNameForInstance(id);
+}
+function encodeWireNameForInstance(id, instanceId, level = 0) {
+  const raw = rawWireName(id, instanceId);
+  if (level === 0 && raw.length <= MAX_WIRE_NAME_LENGTH && !id.includes("_")) return raw;
+  const hashLength = 7 + level * 2;
+  const keep = MAX_WIRE_NAME_LENGTH - SHORTENED_MARKER.length - hashLength;
+  const hash = hash36(`${id}#${instanceId ?? ""}#${level}`, hashLength);
+  return `${raw.slice(0, keep)}${SHORTENED_MARKER}${hash}`;
+}
+function assignWireNames(entries) {
+  const keyOf = (e) => `${e.id}#${e.instanceId ?? ""}`;
+  const level = /* @__PURE__ */ new Map();
+  const MAX_LEVEL = 3;
+  let names = entries.map((e) => encodeWireNameForInstance(e.id, e.instanceId));
+  for (let round = 0; round <= MAX_LEVEL; round++) {
+    const byName2 = /* @__PURE__ */ new Map();
+    entries.forEach((entry, i) => {
+      const set = byName2.get(names[i]) ?? /* @__PURE__ */ new Set();
+      set.add(keyOf(entry));
+      byName2.set(names[i], set);
+    });
+    const colliding = /* @__PURE__ */ new Set();
+    for (const [, keys] of byName2) {
+      if (keys.size > 1) for (const key of keys) colliding.add(key);
+    }
+    if (colliding.size === 0) break;
+    if (round === MAX_LEVEL) {
+      const ranked = [...colliding].sort();
+      names = entries.map((entry, i) => {
+        const rank = ranked.indexOf(keyOf(entry));
+        if (rank < 0) return names[i];
+        const suffix = `${SHORTENED_MARKER}${rank}`;
+        const base = encodeWireNameForInstance(entry.id, entry.instanceId, MAX_LEVEL);
+        return `${base.slice(0, MAX_WIRE_NAME_LENGTH - suffix.length)}${suffix}`;
+      });
+      break;
+    }
+    for (const key of colliding) level.set(key, (level.get(key) ?? 0) + 1);
+    names = entries.map(
+      (entry) => encodeWireNameForInstance(entry.id, entry.instanceId, level.get(keyOf(entry)) ?? 0)
+    );
+  }
+  const byName = /* @__PURE__ */ new Map();
+  entries.forEach((entry, i) => byName.set(names[i], entry.id));
+  return { names, byName };
+}
+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);
+  if (/_{3,}/.test(rest)) return void 0;
+  const path = rest.replaceAll("__", ".");
+  if (path.split(".").some((segment) => segment === "")) return void 0;
+  const id = `${plane}:${path}`;
+  if (id.includes("_") || !parseCapabilityId(id) || encodeWireName(id) !== name) return void 0;
+  return id;
+}
+
+// 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/internal.ts
+var DEV_WARN = /* @__PURE__ */ Symbol("agent-surface.dev-warn");
+var INTERNALS = /* @__PURE__ */ Symbol("agent-surface.internals");
+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 ?? []],
+      concurrency: act.concurrency
+    });
+  }
+  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),
+      concurrency: binding.config.concurrency
+    };
+  });
+  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(),
+    concurrencyGroups: /* @__PURE__ */ new Map()
+  };
+}
+function concurrencyGroupFor(cap, limits) {
+  const declared = cap.kind === "action" ? cap.concurrency : cap.concurrency;
+  const fallbackDepth = limits.actionQueueDepth;
+  if (declared === void 0) {
+    return cap.kind === "action" ? { key: "instance", max: 1, depth: fallbackDepth } : { key: `proc:${cap.capabilityId}`, max: 1, depth: fallbackDepth };
+  }
+  const depth = declared.queueDepth ?? fallbackDepth;
+  switch (declared.mode) {
+    case "instance":
+      return { key: "instance", max: 1, depth };
+    case "capability":
+      return { key: `cap:${cap.capabilityId}`, max: 1, depth };
+    case "key":
+      return { key: `key:${declared.key}`, max: 1, depth };
+    case "parallel":
+      return { key: `par:${cap.capabilityId}`, max: declared.max, depth };
+  }
+}
+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/snapshot.ts
+var DEFAULT_CONSUMER = { 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_CONSUMER;
+  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 contextualNote;
+      const describe = proc.binding.config.describe;
+      if (describe) {
+        try {
+          const contextual = describe();
+          if (contextual) contextualNote = contextual;
+        } catch {
+        }
+      }
+      procedures.push({
+        procedureId: proc.capabilityId,
+        // Never merged with `contextualNote` (D28): the manifest text is the
+        // stable half, and folding volatile text in is what churned the
+        // provider's cached prompt prefix.
+        description: proc.baseDescription,
+        ...contextualNote !== void 0 ? { contextualNote } : {},
+        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);
+  }
+}
+
+export {
+  AGENT_CAPABILITY_ERROR_CODES,
+  AgentSurfaceError,
+  isAgentSurfaceError,
+  AgentSurfaceDefinitionError,
+  CONFIRMATION_ESCALATION,
+  evaluateDiscovery,
+  composeAuthorizeChain,
+  composeInvokeChain,
+  authenticated,
+  hasPermission,
+  tenantBoundary,
+  environment,
+  rateLimit,
+  requireConfirmation,
+  audit,
+  MAX_ID_LENGTH,
+  isValidComponentType,
+  isValidCapabilityName,
+  isValidInstanceId,
+  formatViewCapabilityId,
+  formatDomainCapabilityId,
+  parseCapabilityId,
+  MAX_WIRE_NAME_LENGTH,
+  encodeWireName,
+  encodeWireNameForInstance,
+  assignWireNames,
+  decodeWireName,
+  jsonDeepEqual,
+  deepFreeze,
+  isJsonValue,
+  byteLength,
+  randomBase62,
+  truncate,
+  canonicalJson,
+  fnv1a64,
+  DEV_WARN,
+  INTERNALS,
+  DevDefectError,
+  componentKey,
+  maxConfirmation,
+  nextRegistrationId,
+  normalizeRegistration,
+  concurrencyGroupFor,
+  computeAvailability,
+  policiesFor,
+  buildPolicyContext,
+  consumerKeyOf,
+  addTombstone,
+  DEFAULT_CONSUMER,
+  matchesScope,
+  sortRegistrations,
+  createSnapshot
+};
+//# sourceMappingURL=chunk-77YRWAXY.js.map