@agent-surface/core 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -749,17 +749,10 @@ 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).
+     * `describe()` output is `contextualNote` and is never folded in here (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.
-     */
+    /** Volatile: this snapshot's contextual `describe()` output, if any. */
     contextualNote?: string;
     /** Agent-facing (reduced) input schema per binding rule 1 (docs/05). */
     inputSchema: JsonSchema;
@@ -783,15 +776,6 @@ 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;
@@ -815,15 +799,6 @@ interface RegistryOptions {
     /** Route descriptor for snapshots (host wires its router here). */
     route?: () => AgentRouteInfo | undefined;
     limits?: Partial<AgentSurfaceLimits>;
-    /**
-     * 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
-     * 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;
 }
@@ -897,23 +872,14 @@ interface AgentToolsetOptions {
         maxComponents?: number;
         maxBytes?: number;
     };
-    /**
-     * 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
-     * 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, 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.
+     * Contains NO live state (D28), so it is safe in a provider tool block with
+     * prompt-prefix caching across steps.
      */
     description: string;
     inputSchema: JsonSchema;
@@ -950,4 +916,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, 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 };
+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, tenantBoundary, validateComponentDefinition, validateJsonSchemaDocument, validateValueAgainstSchema };

package/dist/index.js

@@ -2572,12 +2572,6 @@ 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}.`));
@@ -2692,10 +2686,12 @@ function createSnapshot(internals, ctx) {
         } catch {
         }
       }
-      const description = contextualNote && internals.mergesContextualNote ? `${proc.baseDescription} ${contextualNote}`.trim() : proc.baseDescription;
       procedures.push({
         procedureId: proc.capabilityId,
-        description,
+        // 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 } : {},
@@ -2763,7 +2759,6 @@ function createAgentSurfaceRegistry(options) {
   const internals = {
     environment: environment2,
     limits,
-    mergesContextualNote: options?.snapshotMergesContextualNote ?? true,
     surfaceId: `srf_${randomBase62(22)}`,
     version: 0,
     registrations: /* @__PURE__ */ new Map(),
@@ -3060,11 +3055,6 @@ function describePrefix(plane, effect, confirmation) {
   if (confirmation === "required") parts.push("requires confirmation");
   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,
@@ -3085,7 +3075,6 @@ 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;
@@ -3199,7 +3188,7 @@ function createAgentToolset(registry, options) {
         void 0,
         describePrefix("domain", proc.effect, proc.confirmation),
         // The stable half only: a contextual note travels in `state.note`.
-        stableDescriptionOf(proc),
+        proc.description,
         proc.inputSchema,
         availabilityState(proc),
         needsSuffix ? proc.context?.instanceId ?? proc.registrationId.replace(/[^A-Za-z0-9_-]/g, "") : void 0
@@ -3208,7 +3197,7 @@ function createAgentToolset(registry, options) {
     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}`,
+      description: `${p.prefix} ${p.description}`,
       inputSchema: p.inputSchema,
       state: p.state,
       execute: (input, call) => invokeThroughSurface(p.entry, input, call.toolCallId)
@@ -3490,7 +3479,6 @@ export {
   parseCapabilityId,
   rateLimit,
   requireConfirmation,
-  stableDescriptionOf,
   tenantBoundary,
   validateComponentDefinition,
   validateJsonSchemaDocument,