@standardagents/spec 0.42.3 → 0.43.0

package/dist/index.d.ts

@@ -1494,7 +1494,8 @@ interface UserState {
     instanceEnv?(name: string): Promise<string | undefined>;
     /**
      * Broadcast an event to every socket attached to this user's event stream
-     * (`{runtime_prefix}/users/me/stream`) and to every room socket. Delivery
+     * (`{runtime_prefix}/users/me/stream`) and to every admitted, identified room
+     * socket. Delivery
      * is at-most-once and live-only: the stream carries no history and no
      * acknowledgements. Packages SHOULD namespace event names
      * (`my_package.thing_changed`).
@@ -1503,7 +1504,8 @@ interface UserState {
     /**
      * The user's live room connections (`{runtime_prefix}/users/me/hub`
      * sockets that presented a `client_id`), newest attachment last. One entry
-     * per client id: a reconnecting client supersedes its older socket.
+     * per client id: admission of a reconnecting client supersedes its older socket.
+     * Pending explicit-admission attachments are excluded.
      */
     clients(): Promise<UserRoomConnection[]>;
     /**
@@ -1512,6 +1514,8 @@ interface UserState {
      * Delivery is at-most-once.
      */
     send(clientId: string, frame: unknown): Promise<boolean>;
+    /** Optional attachment-addressed replies, admission and close for user rooms. */
+    roomAttachments?: UserRoomAttachments;
     /** Registry metadata for the user's threads. */
     listThreads(options?: ListUserThreadsOptions): Promise<{
         threads: UserThreadSummary[];
@@ -1622,8 +1626,33 @@ interface UserRoomConnection {
     clientId: string;
     /** The self-declared `client_kind`, when presented. */
     clientKind: string | null;
-    /** Unix milliseconds when this socket attached. */
+    /** Unix milliseconds when this socket attached; not a unique socket identity. */
     since: number;
+    /** Opaque identity of this physical attachment; never reused on reconnect. */
+    attachmentId?: string;
+}
+/**
+ * Optional room admission capability. Operations address a physical attachment
+ * in this user's room and run within the caller's per-user serialized execution.
+ * Available during serialized room/endpoint handlers, not observational hooks.
+ * A client id or timestamp is never a substitute for an attachment id.
+ */
+interface UserRoomAttachments {
+    /** Reply to exactly this live attachment, even before admission. No buffering. */
+    send(attachmentId: string, frame: unknown): Promise<boolean>;
+    /**
+     * Admit a live attachment after the room verifies its application proof.
+     * Atomically supersedes the admitted socket with the same client id, never
+     * other pending sockets. Repeating admission is harmless. Returns false if
+     * the attachment has detached or was superseded; it can never be resurrected.
+     */
+    admit(attachmentId: string): Promise<boolean>;
+    /**
+     * Close exactly this live attachment and report its detach. Returns false for
+     * unknown, detached, superseded or foreign attachments. Defaults to 1000/"";
+     * code must be 1000 or 3000–4999; reason is at most 123 UTF-8 bytes.
+     */
+    close(attachmentId: string, code?: number, reason?: string): Promise<boolean>;
 }
 /**
  * A frame a room connection sends: `{ type: "room", id, ... }`. `id` is the
@@ -1646,9 +1675,23 @@ interface UserRoomPresenceEvent {
  * A packaged user room: the handler for room frames on the user's hub
  * socket. Frames and presence events execute in the user scope under the
  * same per-user serialization as user endpoints, so a presence write cannot
- * race a mutation. At most one room definition is active per project.
+ * race a mutation. Multiple room definitions fail room upgrades and delivery
+ * closed; other user surfaces remain available.
  */
 interface UserRoomDefinition {
+    /**
+     * Automatic admission is the default. In explicit mode a newly attached
+     * socket cannot replace an admitted socket or receive send/emit/wake traffic
+     * until the room calls roomAttachments.admit after verifying its proof.
+     * clients() lists admitted sockets only. onFrame still receives pending
+     * frames so the room can implement a challenge protocol; use attachment-
+     * addressed replies for these frames. Runtimes supporting this option MUST
+     * provide roomAttachments and attachmentId; consumers MUST fail closed when
+     * either is absent. Restored legacy attachments require admission too.
+     * Explicit-mode presence reports each physical attach/detach immediately,
+     * including pending and superseded attachments, without reconnect grace.
+     */
+    admission?: 'automatic' | 'explicit';
     /**
      * The user endpoint this room fronts, by policy name (for example
      * `standard/account`). Room executions then run as that endpoint for
@@ -1662,9 +1705,9 @@ interface UserRoomDefinition {
      * for them, so the room can write state without hook churn.
      */
     valuePrefix?: string;
-    /** Called for every `{ type: "room" }` frame from a verified-attached socket. */
+    /** Called for every room frame from a live socket, including pending admission. */
     onFrame(user: UserState, connection: UserRoomConnection, frame: UserRoomFrame): Promise<void>;
-    /** Called when a room connection attaches or, after a grace period, detaches. */
+    /** Physical presence in explicit mode; client presence with grace in automatic mode. */
     onPresence?(user: UserState, event: UserRoomPresenceEvent): Promise<void>;
 }
 declare const USER_ROOM_SYMBOL: unique symbol;
@@ -6408,4 +6451,4 @@ declare function validateAgentDefinition(def: unknown): DefinitionIssue[];
  */
 declare const SPEC_VERSION = "0.2.0";
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type CodeExecution, type CodeExecutionError, type CodeExecutionLog, type CodeExecutionOptions, type CodeExecutionResult, type CodeExecutionStatus, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type CreateFetch, type CredentialGrant, DEFINITION_ISSUE_CODES, type DecideOptions, type DecisionAnswer, type DecisionAnswers, type DecisionBooleanAnswer, type DecisionChoiceAnswer, type DecisionContext, type DecisionJson, type DecisionProviderFactory, type DecisionProviderInterface, type DecisionQuestion, type DecisionQuestions, type DecisionRequest, type DecisionResult, type DecisionScoreAnswer, type DefineHandlerOptions, type DefineToolOptions, type DefinitionIssue, type DefinitionIssueCode, type DefinitionLoader, ENDPOINT_ACCESS_SYMBOL, type Effect, type EffectDefinition, type EmptyUsesState, type EndpointAccess, type EndpointOptions, type EnvValueType, type ErrorOrigin, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, HANDLER_SYMBOL, type HandlerDefinition, type HandlerSide, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookExecutionContext, type HookExecutionSource, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type HumanSide, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type ListUserThreadsOptions, type ListUserValuesOptions, type MarkedThreadEndpoint, type MarkedUserEndpoint, type MarkedUserRoom, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type ParentHookRequirement, type ParentHookStage, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptSide, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderErrorOptions, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, RESERVED_RELATIONSHIP_NAMES, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, SPEC_VERSION, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentRelationship, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointAuth, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadHookName, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadRunState, type ThreadState, type ThreadStatus, type ThreadStatusEvent, type ThreadUser, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, USER_ENDPOINT_SYMBOL, USER_ROOM_SYMBOL, type UserClientInfo, type UserEndpointHandler, type UserEndpointRouteParams, type UserHandle, type UserIdentity, type UserRoomConnection, type UserRoomDefinition, type UserRoomFrame, type UserRoomPresenceEvent, type UserState, type UserThreadSummary, type UserValueEntry, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, decide, defineAgent, defineController, defineEffect, defineHandler, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, defineUserRoom, getEndpointAccess, isHandler, isPacked, isThreadEndpoint, isUserEndpoint, isUserRoom, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateAgentDefinition, validateToolName };
+export { type AgentDefinition, type AgentType, type AttachmentRef, type CodeExecution, type CodeExecutionError, type CodeExecutionLog, type CodeExecutionOptions, type CodeExecutionResult, type CodeExecutionStatus, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type CreateFetch, type CredentialGrant, DEFINITION_ISSUE_CODES, type DecideOptions, type DecisionAnswer, type DecisionAnswers, type DecisionBooleanAnswer, type DecisionChoiceAnswer, type DecisionContext, type DecisionJson, type DecisionProviderFactory, type DecisionProviderInterface, type DecisionQuestion, type DecisionQuestions, type DecisionRequest, type DecisionResult, type DecisionScoreAnswer, type DefineHandlerOptions, type DefineToolOptions, type DefinitionIssue, type DefinitionIssueCode, type DefinitionLoader, ENDPOINT_ACCESS_SYMBOL, type Effect, type EffectDefinition, type EmptyUsesState, type EndpointAccess, type EndpointOptions, type EnvValueType, type ErrorOrigin, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, HANDLER_SYMBOL, type HandlerDefinition, type HandlerSide, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookExecutionContext, type HookExecutionSource, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type HumanSide, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type ListUserThreadsOptions, type ListUserValuesOptions, type MarkedThreadEndpoint, type MarkedUserEndpoint, type MarkedUserRoom, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type ParentHookRequirement, type ParentHookStage, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptSide, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderErrorOptions, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, RESERVED_RELATIONSHIP_NAMES, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, SPEC_VERSION, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentRelationship, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointAuth, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadHookName, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadRunState, type ThreadState, type ThreadStatus, type ThreadStatusEvent, type ThreadUser, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, USER_ENDPOINT_SYMBOL, USER_ROOM_SYMBOL, type UserClientInfo, type UserEndpointHandler, type UserEndpointRouteParams, type UserHandle, type UserIdentity, type UserRoomAttachments, type UserRoomConnection, type UserRoomDefinition, type UserRoomFrame, type UserRoomPresenceEvent, type UserState, type UserThreadSummary, type UserValueEntry, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, decide, defineAgent, defineController, defineEffect, defineHandler, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, defineUserRoom, getEndpointAccess, isHandler, isPacked, isThreadEndpoint, isUserEndpoint, isUserRoom, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateAgentDefinition, validateToolName };