@standardagents/spec 0.41.8 → 0.41.10

package/dist/index.d.ts

@@ -806,11 +806,24 @@ interface UserState {
     env(name: string): Promise<string>;
     /**
      * Broadcast an event to every socket attached to this user's event stream
-     * (`{runtime_prefix}/users/me/stream`). 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`).
+     * (`{runtime_prefix}/users/me/stream`) and to every 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`).
      */
     emit(event: string, data?: unknown): void;
+    /**
+     * 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.
+     */
+    clients(): Promise<UserRoomConnection[]>;
+    /**
+     * Deliver one frame to one room connection. Resolves `false` when no live
+     * socket carries that client id; the frame is then dropped, never queued.
+     * Delivery is at-most-once.
+     */
+    send(clientId: string, frame: unknown): Promise<boolean>;
     /** Registry metadata for the user's threads. */
     listThreads(options?: ListUserThreadsOptions): Promise<{
         threads: UserThreadSummary[];
@@ -896,6 +909,12 @@ interface CredentialGrant {
         tools?: string[];
         endpoints?: string[];
         userEndpoints?: string[];
+        /**
+         * Room definitions by registry key (for example `my_package/room`). When
+         * absent, rooms are matched against `userEndpoints`, so a policy that
+         * names the room there works too.
+         */
+        userRooms?: string[];
         agents?: string[];
     };
     /** Non-secret metadata: account label, scopes, expiry. */
@@ -909,6 +928,77 @@ interface CredentialGrant {
  * with a UserState.
  */
 declare const USER_ENDPOINT_SYMBOL: unique symbol;
+/** One live room connection on the user's hub socket. */
+interface UserRoomConnection {
+    /** The `client_id` the socket presented at connect (trimmed, ≤ 256 chars). */
+    clientId: string;
+    /** The self-declared `client_kind`, when presented. */
+    clientKind: string | null;
+    /** Unix milliseconds when this socket attached. */
+    since: number;
+}
+/**
+ * A frame a room connection sends: `{ type: "room", id, ... }`. `id` is the
+ * client's correlation id for replies made through {@link UserState.send}.
+ * Everything else is the package's own protocol.
+ */
+interface UserRoomFrame {
+    type: 'room';
+    id: string;
+    [key: string]: unknown;
+}
+/** A room connection attaching or detaching. */
+interface UserRoomPresenceEvent {
+    kind: 'attached' | 'detached';
+    connection: UserRoomConnection;
+    /** Unix milliseconds of the observation. */
+    at: number;
+}
+/**
+ * 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.
+ */
+interface UserRoomDefinition {
+    /**
+     * Keys under this prefix are room-owned: the runtime keeps them out of
+     * client-writable value routes and does not raise `user_value_changed`
+     * for them, so the room can write state without hook churn.
+     */
+    valuePrefix?: string;
+    /** Called for every `{ type: "room" }` frame from a verified-attached socket. */
+    onFrame(user: UserState, connection: UserRoomConnection, frame: UserRoomFrame): Promise<void>;
+    /** Called when a room connection attaches or, after a grace period, detaches. */
+    onPresence?(user: UserState, event: UserRoomPresenceEvent): Promise<void>;
+}
+declare const USER_ROOM_SYMBOL: unique symbol;
+interface MarkedUserRoom extends UserRoomDefinition {
+    [USER_ROOM_SYMBOL]: true;
+}
+declare function isUserRoom(value: unknown): value is MarkedUserRoom;
+/**
+ * Define the project's user room. The file lives in the `users/` directory
+ * like an endpoint (packages SHOULD root it in a package-named directory,
+ * for example `users/my_package/room.ts`); it is never HTTP-routed.
+ *
+ * @example
+ * ```typescript
+ * // users/my_package/room.ts
+ * import { defineUserRoom } from '@standardagents/spec';
+ *
+ * export default defineUserRoom({
+ *   valuePrefix: 'my_package.v2.',
+ *   async onFrame(user, connection, frame) {
+ *     if (frame.op === 'ping') await user.send(connection.clientId, { type: 'room', id: frame.id, ok: true });
+ *   },
+ *   async onPresence(user, event) {
+ *     user.emit('my_package.presence', { client: event.connection.clientId, online: event.kind === 'attached' });
+ *   },
+ * });
+ * ```
+ */
+declare function defineUserRoom(definition: UserRoomDefinition): MarkedUserRoom;
 /**
  * Route parameters captured from `[param]` and `[*]` segments of a user
  * endpoint file path.
@@ -6142,4 +6232,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 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 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 ThreadState, 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, type UserClientInfo, type UserEndpointHandler, type UserEndpointRouteParams, type UserHandle, type UserIdentity, type UserState, type UserThreadSummary, type UserValueEntry, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHandler, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, getEndpointAccess, isHandler, isPacked, isThreadEndpoint, isUserEndpoint, 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 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 ThreadState, 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, 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 };

package/dist/index.js

@@ -716,6 +716,13 @@ function defineThreadEndpoint(handler, options) {
 
 // src/users.ts
 var USER_ENDPOINT_SYMBOL = Symbol.for("standardagents.userEndpoint");
+var USER_ROOM_SYMBOL = Symbol.for("standardagents.userRoom");
+function isUserRoom(value) {
+  return typeof value === "object" && value !== null && USER_ROOM_SYMBOL in value && value[USER_ROOM_SYMBOL] === true && typeof value.onFrame === "function";
+}
+function defineUserRoom(definition) {
+  return { ...definition, [USER_ROOM_SYMBOL]: true };
+}
 function isUserEndpoint(value) {
   return typeof value === "function" && USER_ENDPOINT_SYMBOL in value && value[USER_ENDPOINT_SYMBOL] === true;
 }
@@ -795,6 +802,7 @@ export {
   THREAD_ENDPOINT_SYMBOL,
   THREAD_STREAM_REASONING_PARAM,
   USER_ENDPOINT_SYMBOL,
+  USER_ROOM_SYMBOL,
   belongsToPackage,
   defineAgent,
   defineController,
@@ -807,11 +815,13 @@ export {
   defineThreadEndpoint,
   defineTool,
   defineUserEndpoint,
+  defineUserRoom,
   getEndpointAccess,
   isHandler,
   isPacked,
   isThreadEndpoint,
   isUserEndpoint,
+  isUserRoom,
   isVisibleInNamespace,
   mapReasoningLevel,
   providerConst,