@agent-surface/core 0.2.0 → 0.4.0

package/README.md

@@ -40,7 +40,8 @@ registry.register(
 
 const toolset = createAgentToolset(registry, {
   consumer: { id: "copilot", kind: "embedded" },
-});
+  topology: "embedded",   // required (D26): embedded → confirmations "wait",
+});                       // remote → "two-phase". No global default.
 ```
 
 React apps should use [`@agent-surface/react`](https://www.npmjs.com/package/@agent-surface/react) instead of calling `register` directly. Full specification: [docs](https://github.com/Wiseair-srl/agent-surface/tree/main/docs).

package/dist/index.d.ts

@@ -136,13 +136,41 @@ declare function encodeWireName(id: string): string;
  * Wire name disambiguated per instance: providers require UNIQUE tool names,
  * so when several live instances expose the same capability the adapter
  * appends `_at_<instanceId>` (docs/09 rule 7 — the id↔name map stays
- * authoritative; instance ids never contain "." so decoding stays possible
- * by stripping the suffix).
+ * authoritative).
+ *
+ * The result is ALWAYS ≤ 64 characters (`AS-WIRE-004`) and deterministic for a
+ * given `(id, instanceId, level)` (`AS-WIRE-005`). `level` escalates the hash
+ * when a catalog would otherwise emit the same name twice — see
+ * {@link assignWireNames}, which owns that check; callers with a whole catalog
+ * in hand should use it rather than this function directly.
+ */
+declare function encodeWireNameForInstance(id: string, instanceId?: string, level?: number): string;
+interface WireNameEntry {
+    /** Canonical capability id. */
+    id: string;
+    /** Instance disambiguator, when several live instances share the id. */
+    instanceId?: string;
+}
+interface WireNameAssignment {
+    /** Emitted names, positionally aligned with the input entries. */
+    names: string[];
+    /** wireName → canonical id. Authoritative; shortened names are not decodable. */
+    byName: ReadonlyMap<string, string>;
+}
+/**
+ * Assigns wire names to a whole catalog, guaranteeing uniqueness within it
+ * (`AS-WIRE-006`). Two distinct entries that collide are BOTH re-encoded at the
+ * next hash level, so the outcome depends on the set of entries and not on
+ * their order (`AS-WIRE-005`). Escalation is bounded; the last level appends
+ * the entry's rank among the colliding keys, which terminates by construction.
  */
-declare function encodeWireNameForInstance(id: string, instanceId?: string): string;
+declare function assignWireNames(entries: readonly WireNameEntry[]): WireNameAssignment;
 /**
- * Reverses `encodeWireName` for non-truncated names. Truncated names cannot
- * be decoded — the adapter's id↔name map is authoritative (docs/09 rule 7).
+ * Reverses `encodeWireName` for names that were encoded faithfully, and returns
+ * `undefined` for every name that was not — shortened names and per-instance
+ * names among them (`AS-WIRE-007`: consult `toolset.wireNameMap()` instead).
+ * Returning a plausible-but-wrong canonical id would take the audit identity
+ * with it, so this refuses anything it cannot re-encode byte-identically.
  */
 declare function decodeWireName(name: string): string | undefined;
 
@@ -671,6 +699,15 @@ interface AgentSurfaceSnapshot {
     truncated?: {
         droppedComponents: number;
     };
+    /**
+     * [Experimental] Present iff a configured scope floor refused part of a
+     * requested scope (D27) — set by the adapter, never by `snapshot()`, which
+     * has no floor to intersect against. Empty `components` alongside this marker
+     * means the request fell outside the floor, not that the surface is empty.
+     */
+    scopeRejected?: {
+        prefixes: string[];
+    };
 }
 interface AgentComponentDescriptor {
     type: string;
@@ -710,7 +747,20 @@ interface AgentActionDescriptor {
 }
 interface AgentProcedureDescriptor {
     procedureId: string;
+    /**
+     * The manifest description. Stable across snapshots — the contextual
+     * `describe()` output is `contextualNote`, not part of this string, unless
+     * the registry was created with `snapshotMergesContextualNote: true`
+     * (the 0.2 default, removed in a later minor — D28).
+     */
     description: string;
+    /**
+     * Volatile: this snapshot's contextual `describe()` output, if any. Always
+     * populated, in both merge modes, so a host can migrate before the default
+     * moves. Use {@link stableDescriptionOf} to recover the note-free
+     * description without parsing.
+     */
+    contextualNote?: string;
     /** Agent-facing (reduced) input schema per binding rule 1 (docs/05). */
     inputSchema: JsonSchema;
     outputSchema?: JsonSchema;
@@ -733,6 +783,15 @@ interface AgentProcedureDescriptor {
     meta?: Record<string, JsonValue>;
 }
 type AgentCapabilityDescriptorUnion = AgentObservationDescriptor | AgentActionDescriptor | AgentProcedureDescriptor;
+/**
+ * The note-free description of a descriptor, whichever way the registry was
+ * configured to compose it (D28). The merge rule is `${description} ${note}`,
+ * so the split is exact — no host ever has to parse a prefix it did not write.
+ */
+declare function stableDescriptionOf(descriptor: {
+    description: string;
+    contextualNote?: string;
+}): string;
 
 interface RegistrationCandidate {
     definition: AgentComponentDefinition;
@@ -756,6 +815,15 @@ interface RegistryOptions {
     /** Route descriptor for snapshots (host wires its router here). */
     route?: () => AgentRouteInfo | undefined;
     limits?: Partial<AgentSurfaceLimits>;
+    /**
+     * D28 compatibility flag. `true` (default, for one minor) folds a procedure
+     * reference's contextual `describe()` output into
+     * `AgentProcedureDescriptor.description`, as 0.1 did. `false` keeps the two
+     * apart, so `description` is stable across snapshots and the live text is
+     * read from `contextualNote`. Populated either way; the default flips in a
+     * later minor and the flag is then removed.
+     */
+    snapshotMergesContextualNote?: boolean;
     /** Injectable clock (docs/08 determinism); default Date.now. */
     now?: () => number;
 }
@@ -791,7 +859,12 @@ declare function createAgentSurfaceRegistry(options?: RegistryOptions): AgentSur
 
 interface AgentToolsetOptions {
     consumer: AgentConsumer;
-    /** "direct": one tool per capability. "meta": 3 generic tools. [meta: Experimental] */
+    /**
+     * "direct": one tool per capability — provider-native input typing, catalog
+     * size linear in the surface. "meta": three fixed tools with lazy discovery —
+     * constant tool-block size, one extra round trip before the first act.
+     * Default "direct"; see the selection guide in docs/09 §choosing-a-mode.
+     */
     mode?: "direct" | "meta";
     /**
      * Loop topology (D26). Sets the confirmation-mode default: "embedded" →
@@ -824,18 +897,50 @@ interface AgentToolsetOptions {
         maxComponents?: number;
         maxBytes?: number;
     };
+    /**
+     * D28 compatibility flag. `true` (default, for one minor) composes
+     * availability and the contextual note into `description`, as 0.1 did.
+     * `false` keeps `description` free of live state, so the provider tool block
+     * is byte-stable across steps and prompt-prefix caching survives; the host
+     * renders `AgentTool.state` outside the tool definitions (docs/09
+     * §rendering-capability-state). `state` is populated either way.
+     */
+    descriptionIncludesState?: boolean;
 }
 interface AgentTool {
-    /** Wire-safe name (docs/09 §wire-names), ≤ 64 chars. */
+    /** Wire-safe name (docs/09 §wire-names), ≤ 64 chars, unique in this catalog. */
     name: string;
+    /**
+     * Plane + effect + confirmation prefix, then the authored description.
+     * With `descriptionIncludesState: false` this contains NO live state — it is
+     * safe in a provider tool block with prompt-prefix caching across steps.
+     */
     description: string;
     inputSchema: JsonSchema;
+    /**
+     * Volatile: re-derived on every snapshot. Hosts render this OUTSIDE the tool
+     * block (e.g. a trailing system message) so availability stays honest without
+     * invalidating the cached prefix (D28).
+     */
+    state: {
+        available: boolean;
+        unavailableReason?: string;
+        /** Live text contributed by a contextual binding's `describe()`. */
+        note?: string;
+    };
     execute(input: JsonValue, call: {
         toolCallId?: string;
     }): Promise<AgentInvocationResult>;
 }
 interface AgentToolset {
     tools(): AgentTool[];
+    /**
+     * wireName → canonical capability id, for the catalog `tools()` last built.
+     * Authoritative: shortened names are not decodable by string surgery, so a
+     * host MUST consult this rather than reversing names itself (D30). Empty in
+     * "meta" mode, whose three tool names are not capability ids.
+     */
+    wireNameMap(): ReadonlyMap<string, string>;
     /** Fires when tools() would return a different catalog. */
     subscribe(listener: (tools: AgentTool[]) => void): Unsubscribe;
     dispose(): void;
@@ -845,4 +950,4 @@ declare function createAgentToolset(registry: AgentSurfaceRegistry, options: Age
 /** Deep equality over JsonValue (order-sensitive for arrays, docs/06 rule 2). */
 declare function jsonDeepEqual(a: JsonValue | undefined, b: JsonValue | undefined): boolean;
 
-export { AGENT_CAPABILITY_ERROR_CODES, type AgentActionContext, type AgentActionDefinition, type AgentActionDescriptor, type AgentAuthorizationContext, type AgentCapabilityDescriptorUnion, type AgentCapabilityErrorCode, type AgentCapabilityErrorPayload, type AgentComponentDefinition, type AgentComponentDescriptor, type AgentConcurrency, type AgentConsumer, type AgentEffect, type AgentEnvironment, type AgentErrorRetry, type AgentInvocation, type AgentInvocationPolicyContext, type AgentInvocationResult, type AgentObservationDefinition, type AgentObservationDescriptor, type AgentPlane, type AgentPolicy, type AgentPolicyContext, type AgentProcedureBinding, type AgentProcedureBindingRuntimeConfig, type AgentProcedureDescriptor, type AgentProcedureEffect, type AgentProcedureExecutor, type AgentProcedureRefDescriptor, type AgentReadContext, type AgentRegistrationHandle, type AgentRouteInfo, type AgentSchema, AgentSchemaError, type AgentSchemaIssue, AgentSurfaceDefinitionError, type AgentSurfaceDefinitionErrorCode, AgentSurfaceError, type AgentSurfaceEvent, type AgentSurfaceLimits, type AgentSurfaceRegistry, type AgentSurfaceSnapshot, type AgentTool, type AgentToolset, type AgentToolsetOptions, type AuditEvent, type AuditSink, CONFIRMATION_ESCALATION, type ConfirmationController, type ConfirmationEscalation, DEFAULT_LIMITS, type DiscoveryDecision, type InvokeOptions, type JsonSchema, type JsonValue, MAX_ID_LENGTH, MAX_WIRE_NAME_LENGTH, type ParsedCapabilityId, type PendingConfirmation, type PreconditionFailure, type ProcedureCallInfo, type RegistrationCandidate, type RegistryOptions, type SnapshotContext, type StandardSchemaV1, type Unsubscribe, 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 };
+export { AGENT_CAPABILITY_ERROR_CODES, type AgentActionContext, type AgentActionDefinition, type AgentActionDescriptor, type AgentAuthorizationContext, type AgentCapabilityDescriptorUnion, type AgentCapabilityErrorCode, type AgentCapabilityErrorPayload, type AgentComponentDefinition, type AgentComponentDescriptor, type AgentConcurrency, type AgentConsumer, type AgentEffect, type AgentEnvironment, type AgentErrorRetry, type AgentInvocation, type AgentInvocationPolicyContext, type AgentInvocationResult, type AgentObservationDefinition, type AgentObservationDescriptor, type AgentPlane, type AgentPolicy, type AgentPolicyContext, type AgentProcedureBinding, type AgentProcedureBindingRuntimeConfig, type AgentProcedureDescriptor, type AgentProcedureEffect, type AgentProcedureExecutor, type AgentProcedureRefDescriptor, type AgentReadContext, type AgentRegistrationHandle, type AgentRouteInfo, type AgentSchema, AgentSchemaError, type AgentSchemaIssue, AgentSurfaceDefinitionError, type AgentSurfaceDefinitionErrorCode, AgentSurfaceError, type AgentSurfaceEvent, type AgentSurfaceLimits, type AgentSurfaceRegistry, type AgentSurfaceSnapshot, type AgentTool, type AgentToolset, type AgentToolsetOptions, type AuditEvent, type AuditSink, CONFIRMATION_ESCALATION, type ConfirmationController, type ConfirmationEscalation, DEFAULT_LIMITS, type DiscoveryDecision, type InvokeOptions, type JsonSchema, type JsonValue, MAX_ID_LENGTH, MAX_WIRE_NAME_LENGTH, type ParsedCapabilityId, type PendingConfirmation, type PreconditionFailure, type ProcedureCallInfo, type RegistrationCandidate, type RegistryOptions, type SnapshotContext, type StandardSchemaV1, type Unsubscribe, type WireNameAssignment, type WireNameEntry, action, assignWireNames, 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, stableDescriptionOf, tenantBoundary, validateComponentDefinition, validateJsonSchemaDocument, validateValueAgainstSchema };

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
@@ -2520,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}.`));
@@ -2625,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,
@@ -2703,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(),
@@ -2994,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";
@@ -3016,11 +3085,13 @@ function createAgentToolset(registry, options) {
     );
   }
   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;
@@ -3063,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(
@@ -3090,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) {
@@ -3100,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)
         );
       }
     }
@@ -3116,25 +3197,45 @@ 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.",
         inputSchema: {
           type: "object",
-          properties: { scope: { type: "array", items: { type: "string" } } },
+          properties: {
+            scope: {
+              type: "array",
+              items: { type: "string" },
+              // No enum: valid tokens are live component types, and inlining
+              // them would make this tool block churn on every mount —
+              // the churn AS-META-005 and D28 exist to prevent.
+              description: 'Component-type prefixes to narrow the result, e.g. ["devices.table"], taken from `components[].type` of an earlier call \u2014 omit on the first. Narrows only: prefixes outside this host\'s configured scope match nothing and come back in `scopeRejected`.'
+            }
+          },
           additionalProperties: false
         },
         async execute(input) {
@@ -3145,7 +3246,14 @@ function createAgentToolset(registry, options) {
             ...effective.scope ? { scope: effective.scope } : {},
             ...options.budget ? { budget: options.budget } : {}
           });
-          const projected = effective.empty ? { ...snapshot, components: [], procedures: [] } : snapshot;
+          const projected = {
+            ...snapshot,
+            // A disjoint request is snapshotted unscoped, so any `truncated`
+            // count belongs to a surface this payload does not contain. Keeping
+            // it would claim a budget dropped what scope did.
+            ...effective.empty ? { components: [], procedures: [], truncated: void 0 } : {},
+            ...effective.rejected.length > 0 ? { scopeRejected: { prefixes: effective.rejected } } : {}
+          };
           return {
             status: "ok",
             invocationId: `inv_${randomBase62(12)}`,
@@ -3161,8 +3269,14 @@ function createAgentToolset(registry, options) {
         inputSchema: {
           type: "object",
           properties: {
-            capabilityId: { type: "string" },
-            instanceId: { type: "string" }
+            capabilityId: {
+              type: "string",
+              description: "Observation id, verbatim from `observations[].capabilityId` in a discover result."
+            },
+            instanceId: {
+              type: "string",
+              description: "Only when several components share a type: `components[].instanceId` picks one."
+            }
           },
           required: ["capabilityId"],
           additionalProperties: false
@@ -3187,15 +3301,31 @@ 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: {
-            capabilityId: { type: "string" },
-            instanceId: { type: "string" },
-            input: {},
-            invocationId: { type: "string" },
-            confirmationId: { type: "string" }
+            capabilityId: {
+              type: "string",
+              description: "Action `capabilityId` or `procedureId`, verbatim from a discover result."
+            },
+            instanceId: {
+              type: "string",
+              description: "Only when several components share a type: `components[].instanceId` picks one."
+            },
+            input: { description: "Arguments matching that capability's `inputSchema`." },
+            invocationId: {
+              type: "string",
+              description: "Reuse a previous call's id to retry without executing twice; required when resuming after CONFIRMATION_REQUIRED."
+            },
+            confirmationId: {
+              type: "string",
+              description: "The id returned with CONFIRMATION_REQUIRED, sent back after the user approves."
+            },
+            surfaceVersion: {
+              type: "string",
+              description: "The `surfaceVersion` you planned against. Send it for destructive or externally-visible calls: a surface that moved underneath the plan then fails instead of executing. Omitted, the call binds to what is live now."
+            }
           },
           required: ["capabilityId"],
           additionalProperties: false
@@ -3209,7 +3339,7 @@ function createAgentToolset(registry, options) {
               capabilityId: req.capabilityId,
               ...registrationId !== void 0 ? { registrationId } : {},
               ...req.instanceId !== void 0 ? { instanceId: req.instanceId } : {},
-              surfaceVersion: snapshot.surfaceVersion,
+              surfaceVersion: req.surfaceVersion ?? snapshot.surfaceVersion,
               kind: "action"
             },
             req.input,
@@ -3222,6 +3352,7 @@ function createAgentToolset(registry, options) {
         }
       }
     ];
+    return verbs.map((verb) => ({ ...verb, state: { available: true } }));
   }
   function computeTools() {
     if (mode === "meta") {
@@ -3230,13 +3361,15 @@ 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) => {
@@ -3260,6 +3393,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 () => {
@@ -3278,17 +3416,25 @@ 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 };
+    return hasFloor ? { scope: floor, empty: false, rejected: [] } : { empty: false, rejected: [] };
   }
-  if (!hasFloor) return { scope: requested, empty: false };
+  if (!hasFloor) return { scope: requested, empty: false, rejected: [] };
   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);
+  const rejected = [];
+  for (const r of requested) {
+    let admitted = false;
+    for (const f of floor) {
+      if (r === f || r.startsWith(`${f}.`)) {
+        out.add(r);
+        admitted = true;
+      } else if (f.startsWith(`${r}.`)) {
+        out.add(f);
+        admitted = true;
+      }
     }
+    if (!admitted && !rejected.includes(r)) rejected.push(r);
   }
-  return out.size > 0 ? { scope: [...out], empty: false } : { empty: true };
+  return out.size > 0 ? { scope: [...out], empty: false, rejected } : { empty: true, rejected };
 }
 function findRegistrationId(snapshot, capabilityId, instanceId) {
   const matches = [];
@@ -3315,6 +3461,7 @@ export {
   MAX_ID_LENGTH,
   MAX_WIRE_NAME_LENGTH,
   action,
+  assignWireNames,
   audit,
   authenticated,
   composeInvokeChain,
@@ -3343,6 +3490,7 @@ export {
   parseCapabilityId,
   rateLimit,
   requireConfirmation,
+  stableDescriptionOf,
   tenantBoundary,
   validateComponentDefinition,
   validateJsonSchemaDocument,