@agent-surface/core 0.1.0 → 0.3.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

@@ -17,6 +17,35 @@ interface AgentRouteInfo {
     path: string;
     params?: Record<string, string>;
 }
+/**
+ * Concurrency group for an action or procedure reference (D25). Not
+ * model-visible: it is runtime behavior, not planning information.
+ *
+ * - `instance` (default) — every action on the registration shares one FIFO
+ *   queue. Safest: two actions on the same component can never interleave.
+ * - `capability` — one queue per capability, so a slow export does not block
+ *   closing a drawer.
+ * - `key` — one queue per author-chosen key, for actions that contend over
+ *   the same resource across capabilities.
+ * - `parallel` — bounded parallelism; `max` is required and must be ≥ 1.
+ *
+ * `queueDepth` overrides `limits.actionQueueDepth` for this group only.
+ */
+type AgentConcurrency = {
+    mode: "instance";
+    queueDepth?: number;
+} | {
+    mode: "capability";
+    queueDepth?: number;
+} | {
+    mode: "key";
+    key: string;
+    queueDepth?: number;
+} | {
+    mode: "parallel";
+    max: number;
+    queueDepth?: number;
+};
 interface AgentSurfaceLimits {
     maxComponentDescription: number;
     maxCapabilityDescription: number;
@@ -107,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;
 
@@ -423,6 +480,9 @@ interface AgentActionDefinition<TIn extends JsonValue, TOut extends JsonValue |
     policies?: AgentPolicy[];
     meta?: Record<string, JsonValue>;
     timeoutMs?: number;
+    /** Concurrency group (D25). Default `{mode:"instance"}` — serialize with
+     *  every other action on this component instance. */
+    concurrency?: AgentConcurrency;
 }
 /** Identity helpers that fix generics for record-literal authoring. */
 declare function observation<TOut extends JsonValue>(def: AgentObservationDefinition<TOut>): AgentObservationDefinition<TOut>;
@@ -468,6 +528,10 @@ interface AgentProcedureBindingRuntimeConfig {
     /** Contextual description appended to the manifest description. */
     describe?: () => string;
     meta?: Record<string, JsonValue>;
+    /** Concurrency group (D25). Default: one group per procedure identity per
+     *  referencing registration — conservative, and it never couples a domain
+     *  call to unrelated view actions. */
+    concurrency?: AgentConcurrency;
 }
 interface AgentProcedureBinding<TIn extends object = object, TOut = unknown> {
     readonly kind: "procedure-binding";
@@ -674,7 +738,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;
@@ -697,6 +774,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;
@@ -720,6 +806,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;
 }
@@ -755,7 +850,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" →
@@ -771,19 +871,67 @@ interface AgentToolsetOptions {
      * its transport-timeout story, docs/09 §confirmation-topology).
      */
     confirmations?: "wait" | "two-phase";
+    /**
+     * Component-type prefixes this consumer may discover. D27: this is a
+     * **floor** — in "meta" mode a model-supplied `scope` can only narrow it
+     * further, never widen it. Not an authority boundary: `invoke` does not
+     * check scope in either mode (docs/09 §scope-is-discovery-only).
+     */
     scope?: string[];
+    /**
+     * [Experimental] Snapshot truncation budget for `surface_discover`.
+     * "meta" mode only — there the `truncated` marker rides in the payload the
+     * model reads. In "direct" mode a budget would silently drop tools with no
+     * signal to anyone, so it is rejected rather than half-honored.
+     */
+    budget?: {
+        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;
@@ -793,4 +941,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 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 };