@agent-surface/core 0.1.0 → 0.3.0

package/dist/index.js

@@ -102,29 +102,81 @@ function parseCapabilityId(id) {
   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;
+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 hash.toString(36).padStart(7, "0").slice(0, 7);
+  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) {
-  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 encodeWireNameForInstance(id, instanceId, level = 0) {
+  const raw = rawWireName(id, instanceId);
+  if (level === 0 && raw.length <= MAX_WIRE_NAME_LENGTH) 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) {
+  if (name.includes(SHORTENED_MARKER) || name.includes(INSTANCE_MARKER)) return void 0;
   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}`;
+  const id = `${plane}:${name.slice(planeEnd + 1).replaceAll("__", ".")}`;
+  if (id.includes("_") || !parseCapabilityId(id) || encodeWireName(id) !== name) return void 0;
+  return id;
 }
 
 // src/utils.ts
@@ -645,7 +697,8 @@ var ACTION_KEYS = /* @__PURE__ */ new Set([
   "execute",
   "policies",
   "meta",
-  "timeoutMs"
+  "timeoutMs",
+  "concurrency"
 ]);
 var VIEW_EFFECTS = /* @__PURE__ */ new Set(["local-state", "navigation"]);
 var SERVER_EFFECTS = /* @__PURE__ */ new Set([
@@ -666,6 +719,29 @@ function checkMeta(meta, where, limits) {
     fail("LIMIT_EXCEEDED", `${where}: meta exceeds ${limits.maxMetaBytes} bytes`);
   }
 }
+function checkConcurrency(concurrency, where) {
+  if (concurrency === void 0) return;
+  if (typeof concurrency !== "object" || concurrency === null) {
+    fail("INVALID_DEFINITION", `${where}: concurrency must be an object`);
+  }
+  const { mode } = concurrency;
+  if (!["instance", "capability", "key", "parallel"].includes(mode)) {
+    fail("INVALID_DEFINITION", `${where}: invalid concurrency mode "${String(mode)}"`);
+  }
+  if (mode === "key" && (typeof concurrency.key !== "string" || concurrency.key.length === 0)) {
+    fail("INVALID_DEFINITION", `${where}: concurrency mode "key" requires a non-empty key`);
+  }
+  if (mode === "parallel" && (typeof concurrency.max !== "number" || !Number.isInteger(concurrency.max) || concurrency.max < 1)) {
+    fail(
+      "INVALID_DEFINITION",
+      `${where}: concurrency mode "parallel" requires an integer max \u2265 1 (unbounded parallelism is not offered)`
+    );
+  }
+  const depth = concurrency.queueDepth;
+  if (depth !== void 0 && (!Number.isInteger(depth) || depth < 0)) {
+    fail("INVALID_DEFINITION", `${where}: concurrency queueDepth must be a non-negative integer`);
+  }
+}
 function checkSchema(schema, where, limits) {
   if (schema === void 0) return;
   if (typeof schema !== "object" || schema === null || typeof schema.parse !== "function" || typeof schema.jsonSchema !== "object") {
@@ -774,6 +850,7 @@ function validateComponentDefinition(def, limits, opts) {
     checkSchema(act.input, `${where} input`, limits);
     checkSchema(act.output, `${where} output`, limits);
     checkMeta(act.meta, where, limits);
+    checkConcurrency(act.concurrency, where);
   }
   const procedures = def.procedures ?? [];
   if (procedures.length > 0 && !opts.hasProcedureExecutor) {
@@ -803,6 +880,7 @@ function validateComponentDefinition(def, limits, opts) {
       fail("INVALID_DEFINITION", `procedure "${ref.path}": invalid confirmation escalation`);
     }
     checkMeta(binding.config.meta, `procedure "${ref.path}"`, limits);
+    checkConcurrency(binding.config.concurrency, `procedure "${ref.path}"`);
   }
 }
 
@@ -1354,7 +1432,8 @@ function normalizeRegistration(def, id) {
       auditLevel: act.audit ?? "metadata",
       meta: act.meta ? jsonClone(act.meta) : void 0,
       timeoutMs: act.timeoutMs,
-      policies: [...act.policies ?? []]
+      policies: [...act.policies ?? []],
+      concurrency: act.concurrency
     });
   }
   const hasView = observations.size > 0 || actions.size > 0;
@@ -1386,7 +1465,8 @@ function normalizeRegistration(def, id) {
       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)
+      contextLink: binding.contextLink ?? (hasView ? { type: def.type, instanceId } : void 0),
+      concurrency: binding.config.concurrency
     };
   });
   return {
@@ -1410,9 +1490,27 @@ function normalizeRegistration(def, id) {
     enabled: def.enabled !== false,
     availabilityOverrides: /* @__PURE__ */ new Map(),
     inFlight: /* @__PURE__ */ new Set(),
-    actionQueue: { running: false, waiting: [] }
+    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];
@@ -2000,7 +2098,7 @@ async function executeAction(internals, args, cap) {
       }
     }
     const queueStart = internals.now();
-    const slot = await acquireActionSlot(internals, reg);
+    const slot = await acquireActionSlot(internals, reg, cap);
     args.setTimings({ queueWaitMs: internals.now() - queueStart });
     if (slot === "overflow") {
       return finalize({ status: "error", error: queueFull(250) });
@@ -2034,7 +2132,7 @@ async function executeAction(internals, args, cap) {
       args.setAuditPayload(void 0, output.value);
       return finalize({ status: "ok", output: output.value });
     } finally {
-      releaseActionSlot(reg);
+      releaseActionSlot(internals, reg, cap);
     }
   };
   return runInvokePolicies(args, parsedInput, run);
@@ -2102,40 +2200,50 @@ async function executeProcedure(internals, args, cap) {
       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 queueStart = internals.now();
+    const slot = await acquireActionSlot(internals, reg, cap);
+    args.setTimings({ queueWaitMs: internals.now() - queueStart });
+    if (slot === "overflow") {
+      return finalize({ status: "error", error: queueFull(250) });
+    }
+    try {
+      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 });
+    } finally {
+      releaseActionSlot(internals, reg, cap);
     }
-    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);
 }
@@ -2384,21 +2492,32 @@ function executeWithGuards(internals, reg, opts) {
     }
   });
 }
-async function acquireActionSlot(internals, reg) {
-  if (!reg.actionQueue.running) {
-    reg.actionQueue.running = true;
+async function acquireActionSlot(internals, reg, cap) {
+  const { key, max, depth } = concurrencyGroupFor(cap, internals.limits);
+  let group = reg.concurrencyGroups.get(key);
+  if (!group) {
+    group = { running: 0, max, depth, waiting: [] };
+    reg.concurrencyGroups.set(key, group);
+  }
+  if (group.running < group.max) {
+    group.running += 1;
     return "ok";
   }
-  if (reg.actionQueue.waiting.length >= internals.limits.actionQueueDepth) {
+  if (group.waiting.length >= group.depth) {
+    if (group.running === 0 && group.waiting.length === 0) reg.concurrencyGroups.delete(key);
     return "overflow";
   }
-  await new Promise((resolve) => reg.actionQueue.waiting.push(resolve));
+  await new Promise((resolve) => group.waiting.push(resolve));
   return "ok";
 }
-function releaseActionSlot(reg) {
-  const next = reg.actionQueue.waiting.shift();
-  if (next) next();
-  else reg.actionQueue.running = false;
+function releaseActionSlot(internals, reg, cap) {
+  const { key } = concurrencyGroupFor(cap, internals.limits);
+  const group = reg.concurrencyGroups.get(key);
+  if (!group) return;
+  const next = group.waiting.shift();
+  if (!next) group.running -= 1;
+  else next();
+  if (group.running === 0 && group.waiting.length === 0) reg.concurrencyGroups.delete(key);
 }
 function acquireObservationSlot(internals, consumerKey) {
   const adm = internals.observationAdmission;
@@ -2453,6 +2572,12 @@ function drainObservationQueues(internals) {
 
 // src/snapshot.ts
 var DEFAULT_CONSUMER2 = { id: "anonymous", kind: "embedded" };
+function stableDescriptionOf(descriptor) {
+  const note = descriptor.contextualNote;
+  if (!note) return descriptor.description;
+  if (descriptor.description === note) return "";
+  return descriptor.description.endsWith(` ${note}`) ? descriptor.description.slice(0, -(note.length + 1)) : descriptor.description;
+}
 function matchesScope(type, scope) {
   if (!scope || scope.length === 0) return true;
   return scope.some((prefix) => type === prefix || type.startsWith(`${prefix}.`));
@@ -2558,18 +2683,20 @@ function createSnapshot(internals, ctx) {
       const available = availability.available && decision.decision === "expose";
       const reason = decision.decision === "disable" ? decision.reason : availability.reason;
       if (!available && !includeUnavailable) continue;
-      let description = proc.baseDescription;
+      let contextualNote;
       const describe = proc.binding.config.describe;
       if (describe) {
         try {
           const contextual = describe();
-          if (contextual) description = `${description} ${contextual}`.trim();
+          if (contextual) contextualNote = contextual;
         } catch {
         }
       }
+      const description = contextualNote && internals.mergesContextualNote ? `${proc.baseDescription} ${contextualNote}`.trim() : proc.baseDescription;
       procedures.push({
         procedureId: proc.capabilityId,
         description,
+        ...contextualNote !== void 0 ? { contextualNote } : {},
         inputSchema: proc.reducedInputSchema,
         ...proc.outputJsonSchema ? { outputSchema: proc.outputJsonSchema } : {},
         effect: proc.effect,
@@ -2636,6 +2763,7 @@ function createAgentSurfaceRegistry(options) {
   const internals = {
     environment: environment2,
     limits,
+    mergesContextualNote: options?.snapshotMergesContextualNote ?? true,
     surfaceId: `srf_${randomBase62(22)}`,
     version: 0,
     registrations: /* @__PURE__ */ new Map(),
@@ -2927,14 +3055,22 @@ var EMPTY_INPUT_SCHEMA = {
   properties: {},
   additionalProperties: false
 };
-function describePrefix(plane, effect, confirmation, available, unavailableReason) {
+function describePrefix(plane, effect, confirmation) {
   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;
+  return `[${parts.join(" \xB7 ")}]`;
+}
+function legacyDescription(prefix, description, state) {
+  const unavailable = state.available ? "" : ` [currently unavailable${state.unavailableReason ? `: ${state.unavailableReason}` : ""}]`;
+  const note = state.note ? ` ${state.note}` : "";
+  return `${prefix}${unavailable} ${description}${note}`;
+}
+function availabilityState(descriptor) {
+  return {
+    available: descriptor.available,
+    ...descriptor.unavailableReason !== void 0 ? { unavailableReason: descriptor.unavailableReason } : {},
+    ...descriptor.contextualNote !== void 0 ? { note: descriptor.contextualNote } : {}
+  };
 }
 function createAgentToolset(registry, options) {
   const mode = options.mode ?? "direct";
@@ -2943,12 +3079,19 @@ function createAgentToolset(registry, options) {
       "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)."
     );
   }
+  if (options.budget !== void 0 && mode !== "meta") {
+    throw new Error(
+      "createAgentToolset: `budget` applies to mode 'meta' only \u2014 in 'direct' mode it would silently drop tools. Pass a `scope` to bound a direct catalog instead (docs/09 \xA7meta-tools-mode)."
+    );
+  }
   const confirmationsMode = options.confirmations ?? (options.topology === "remote" ? "two-phase" : "wait");
+  const descriptionIncludesState = options.descriptionIncludesState ?? true;
   const listeners = /* @__PURE__ */ new Set();
   const pendingWaits = /* @__PURE__ */ new Set();
   let disposed = false;
   let cachedVersion;
   let cachedTools;
+  let cachedWireNames = /* @__PURE__ */ new Map();
   let cachedSignature;
   async function waitForConfirmation(confirmationId) {
     if (disposed) return;
@@ -2960,15 +3103,16 @@ function createAgentToolset(registry, options) {
       pendingWaits.delete(controller);
     }
   }
-  async function invokeThroughSurface(entry, input, toolCallId) {
-    const invocationId = toolCallId ?? `inv_${randomBase62(12)}`;
+  async function invokeThroughSurface(entry, input, toolCallId, overrides) {
+    const invocationId = overrides?.invocationId ?? toolCallId ?? `inv_${randomBase62(12)}`;
     const base = {
       invocationId,
       capabilityId: entry.capabilityId,
       ...entry.instanceId !== void 0 ? { instanceId: entry.instanceId } : {},
-      registrationId: entry.registrationId,
+      ...entry.registrationId !== void 0 ? { registrationId: entry.registrationId } : {},
       surfaceVersion: entry.surfaceVersion,
-      ...input !== void 0 ? { input } : {}
+      ...input !== void 0 ? { input } : {},
+      ...overrides?.confirmationId !== void 0 ? { confirmationId: overrides.confirmationId } : {}
     };
     let result = await registry.invoke(base, { consumer: options.consumer });
     if (confirmationsMode === "wait" && result.status === "error" && result.error.code === "CONFIRMATION_REQUIRED") {
@@ -2990,26 +3134,32 @@ function createAgentToolset(registry, options) {
       ...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({
+    const pending = [];
+    const push = (capabilityId, kind, registrationId, instanceId, prefix, description, inputSchema, state, nameSuffix) => {
+      const suffix = nameSuffix ?? instanceId;
+      pending.push({
         // Providers require unique tool names: multi-instance capabilities
         // are disambiguated with an `_at_<instance>` suffix (docs/09).
-        name: encodeWireNameForInstance(capabilityId, nameSuffix ?? instanceId),
+        wire: { id: capabilityId, ...suffix !== void 0 ? { instanceId: suffix } : {} },
+        entry: {
+          capabilityId,
+          registrationId,
+          ...instanceId !== void 0 ? { instanceId } : {},
+          surfaceVersion: snapshot.surfaceVersion,
+          kind
+        },
+        prefix,
         description,
         inputSchema,
-        execute: (input, call) => invokeThroughSurface(entry, input, call.toolCallId)
+        state
       });
     };
+    const typeCounts = /* @__PURE__ */ new Map();
+    for (const component of snapshot.components) {
+      typeCounts.set(component.type, (typeCounts.get(component.type) ?? 0) + 1);
+    }
     for (const component of snapshot.components) {
-      const multiInstance = snapshot.components.filter((c) => c.type === component.type).length > 1;
+      const multiInstance = (typeCounts.get(component.type) ?? 0) > 1;
       const instanceId = multiInstance ? component.instanceId : void 0;
       for (const obs of component.observations) {
         push(
@@ -3017,8 +3167,10 @@ function createAgentToolset(registry, options) {
           "observation",
           component.registrationId,
           instanceId,
-          `${describePrefix("view", "read", "never", obs.available, obs.unavailableReason)} ${obs.description}`,
-          EMPTY_INPUT_SCHEMA
+          describePrefix("view", "read", "never"),
+          obs.description,
+          EMPTY_INPUT_SCHEMA,
+          availabilityState(obs)
         );
       }
       for (const act of component.actions) {
@@ -3027,8 +3179,10 @@ function createAgentToolset(registry, options) {
           "action",
           component.registrationId,
           instanceId,
-          `${describePrefix("view", act.effect, act.confirmation, act.available, act.unavailableReason)} ${act.description}`,
-          act.inputSchema
+          describePrefix("view", act.effect, act.confirmation),
+          act.description,
+          act.inputSchema,
+          availabilityState(act)
         );
       }
     }
@@ -3043,19 +3197,30 @@ function createAgentToolset(registry, options) {
         "procedure",
         proc.registrationId,
         void 0,
-        `${describePrefix("domain", proc.effect, proc.confirmation, proc.available, proc.unavailableReason)} ${proc.description}`,
+        describePrefix("domain", proc.effect, proc.confirmation),
+        // The stable half only: a contextual note travels in `state.note`.
+        stableDescriptionOf(proc),
         proc.inputSchema,
+        availabilityState(proc),
         needsSuffix ? proc.context?.instanceId ?? proc.registrationId.replace(/[^A-Za-z0-9_-]/g, "") : void 0
       );
     }
-    return tools;
+    const assignment = assignWireNames(pending.map((p) => p.wire));
+    const tools = pending.map((p, i) => ({
+      name: assignment.names[i],
+      description: descriptionIncludesState ? legacyDescription(p.prefix, p.description, p.state) : `${p.prefix} ${p.description}`,
+      inputSchema: p.inputSchema,
+      state: p.state,
+      execute: (input, call) => invokeThroughSurface(p.entry, input, call.toolCallId)
+    }));
+    return { tools, wireNames: assignment.byName };
   }
   function buildMetaTools() {
     const snapshotFor = () => registry.snapshot({
       consumer: options.consumer,
       ...options.scope ? { scope: options.scope } : {}
     });
-    return [
+    const verbs = [
       {
         name: "surface_discover",
         description: "[meta] Discover the current agent surface: components, capabilities, procedures, availability, schemas.",
@@ -3065,16 +3230,19 @@ function createAgentToolset(registry, options) {
           additionalProperties: false
         },
         async execute(input) {
-          const scope = input?.scope;
+          const requested = input?.scope;
+          const effective = intersectScope(options.scope, requested);
           const snapshot = registry.snapshot({
             consumer: options.consumer,
-            ...scope ? { scope } : options.scope ? { scope: options.scope } : {}
+            ...effective.scope ? { scope: effective.scope } : {},
+            ...options.budget ? { budget: options.budget } : {}
           });
+          const projected = effective.empty ? { ...snapshot, components: [], procedures: [] } : snapshot;
           return {
             status: "ok",
             invocationId: `inv_${randomBase62(12)}`,
             capabilityId: "meta:surface.discover",
-            output: JSON.parse(JSON.stringify(snapshot)),
+            output: JSON.parse(JSON.stringify(projected)),
             surfaceVersion: snapshot.surfaceVersion
           };
         }
@@ -3094,10 +3262,12 @@ function createAgentToolset(registry, options) {
         async execute(input, call) {
           const req = input;
           const snapshot = snapshotFor();
+          const registrationId = findRegistrationId(snapshot, req.capabilityId, req.instanceId);
           return invokeThroughSurface(
             {
               capabilityId: req.capabilityId,
-              registrationId: findRegistrationId(snapshot, req.capabilityId, req.instanceId) ?? "",
+              // Unresolved → let the registry answer (AS-ADAPTER-003).
+              ...registrationId !== void 0 ? { registrationId } : {},
               ...req.instanceId !== void 0 ? { instanceId: req.instanceId } : {},
               surfaceVersion: snapshot.surfaceVersion,
               kind: "observation"
@@ -3109,7 +3279,7 @@ function createAgentToolset(registry, options) {
       },
       {
         name: "surface_act",
-        description: "[meta] Invoke an action or procedure by capabilityId.",
+        description: "[meta] Invoke an action or procedure by capabilityId. Echo the surfaceVersion you discovered so a surface that changed underneath a destructive plan is rejected rather than executed.",
         inputSchema: {
           type: "object",
           properties: {
@@ -3117,7 +3287,8 @@ function createAgentToolset(registry, options) {
             instanceId: { type: "string" },
             input: {},
             invocationId: { type: "string" },
-            confirmationId: { type: "string" }
+            confirmationId: { type: "string" },
+            surfaceVersion: { type: "string" }
           },
           required: ["capabilityId"],
           additionalProperties: false
@@ -3125,39 +3296,26 @@ function createAgentToolset(registry, options) {
         async execute(input, call) {
           const req = input;
           const snapshot = snapshotFor();
-          const invocationId = req.invocationId ?? call.toolCallId ?? `inv_${randomBase62(12)}`;
-          let result = await registry.invoke(
+          const registrationId = findRegistrationId(snapshot, req.capabilityId, req.instanceId);
+          return invokeThroughSurface(
             {
-              invocationId,
               capabilityId: req.capabilityId,
+              ...registrationId !== void 0 ? { registrationId } : {},
               ...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 } : {}
+              surfaceVersion: req.surfaceVersion ?? snapshot.surfaceVersion,
+              kind: "action"
             },
-            { consumer: options.consumer }
+            req.input,
+            call.toolCallId,
+            {
+              ...req.invocationId !== void 0 ? { invocationId: req.invocationId } : {},
+              ...req.confirmationId !== void 0 ? { confirmationId: req.confirmationId } : {}
+            }
           );
-          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;
         }
       }
     ];
+    return verbs.map((verb) => ({ ...verb, state: { available: true } }));
   }
   function computeTools() {
     if (mode === "meta") {
@@ -3166,18 +3324,21 @@ function createAgentToolset(registry, options) {
     }
     const version = registry.getVersion();
     if (cachedTools && cachedVersion === version) return cachedTools;
-    cachedTools = buildDirectTools();
+    const built = buildDirectTools();
+    cachedTools = built.tools;
+    cachedWireNames = built.wireNames;
     cachedVersion = version;
     return cachedTools;
   }
   function signatureOf(tools) {
     return JSON.stringify(
-      tools.map((t) => [t.name, t.description, t.inputSchema])
+      tools.map((t) => [t.name, t.description, t.inputSchema, t.state])
     );
   }
   const unsubscribe = registry.subscribe((event) => {
     if (disposed || event.type !== "surface-changed") return;
     cachedVersion = void 0;
+    if (mode === "meta") return;
     const tools = computeTools();
     const signature = signatureOf(tools);
     if (signature === cachedSignature) return;
@@ -3195,6 +3356,11 @@ function createAgentToolset(registry, options) {
       cachedSignature ??= signatureOf(tools);
       return tools;
     },
+    wireNameMap() {
+      if (mode === "meta") return /* @__PURE__ */ new Map();
+      computeTools();
+      return cachedWireNames;
+    },
     subscribe(listener) {
       listeners.add(listener);
       return () => {
@@ -3210,6 +3376,21 @@ function createAgentToolset(registry, options) {
     }
   };
 }
+function intersectScope(floor, requested) {
+  const hasFloor = floor !== void 0 && floor.length > 0;
+  if (requested === void 0 || requested.length === 0) {
+    return hasFloor ? { scope: floor, empty: false } : { empty: false };
+  }
+  if (!hasFloor) return { scope: requested, empty: false };
+  const out = /* @__PURE__ */ new Set();
+  for (const f of floor) {
+    for (const r of requested) {
+      if (r === f || r.startsWith(`${f}.`)) out.add(r);
+      else if (f.startsWith(`${r}.`)) out.add(f);
+    }
+  }
+  return out.size > 0 ? { scope: [...out], empty: false } : { empty: true };
+}
 function findRegistrationId(snapshot, capabilityId, instanceId) {
   const matches = [];
   for (const component of snapshot.components) {
@@ -3235,6 +3416,7 @@ export {
   MAX_ID_LENGTH,
   MAX_WIRE_NAME_LENGTH,
   action,
+  assignWireNames,
   audit,
   authenticated,
   composeInvokeChain,
@@ -3263,6 +3445,7 @@ export {
   parseCapabilityId,
   rateLimit,
   requireConfirmation,
+  stableDescriptionOf,
   tenantBoundary,
   validateComponentDefinition,
   validateJsonSchemaDocument,