@agent-surface/core 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -699,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;
@@ -807,7 +816,7 @@ interface RegistryOptions {
     route?: () => AgentRouteInfo | undefined;
     limits?: Partial<AgentSurfaceLimits>;
     /**
-     * D28 compatibility flag. `true` (default, for one minor) folds a procedure
+     * D28 compatibility flag. `true` (default through 0.4; flips in 0.5) 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
@@ -889,7 +898,7 @@ interface AgentToolsetOptions {
         maxBytes?: number;
     };
     /**
-     * D28 compatibility flag. `true` (default, for one minor) composes
+     * D28 compatibility flag. `true` (default through 0.4; flips in 0.5) 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

package/dist/index.js

@@ -3226,7 +3226,16 @@ function createAgentToolset(registry, options) {
         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) {
@@ -3237,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)}`,
@@ -3253,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
@@ -3283,12 +3305,27 @@ function createAgentToolset(registry, options) {
         inputSchema: {
           type: "object",
           properties: {
-            capabilityId: { type: "string" },
-            instanceId: { type: "string" },
-            input: {},
-            invocationId: { type: "string" },
-            confirmationId: { type: "string" },
-            surfaceVersion: { 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
@@ -3379,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 = [];