@standardagents/spec 0.29.1 → 0.30.0

package/dist/index.d.ts

@@ -699,6 +699,258 @@ declare function defineEffect<State = ThreadState, Args extends ToolArgs = ToolA
  */
 declare function defineEffect<State = ThreadState>(description: string, handler: Effect<State, null>): EffectDefinition<State, null>;
 
+/**
+ * User scope types for Standard Agents.
+ *
+ * A user is a first-class scope owned by a runtime principal: durable values,
+ * packaged HTTP endpoints, an event stream, and credential grants. Threads
+ * reference users; these surfaces are addressable independently of any thread.
+ *
+ * Specification: https://standardagentspec.com/0.1.0/specification/users
+ *
+ * @module
+ */
+
+/**
+ * The identity record of a user — identity fields only, never credentials.
+ *
+ * This is the same record {@link ThreadState.user} resolves for a thread's
+ * owner. A runtime MUST resolve every authenticated request to a stable user
+ * id; a runtime with exactly one principal resolves all requests to a single
+ * constant user id.
+ */
+type UserIdentity = ThreadUser;
+/**
+ * A client attached to the user event stream, as reported to user lifecycle
+ * hooks. `kind` is a client-declared label (for example `"cli"`, `"web"`).
+ */
+interface UserClientInfo {
+    id: string;
+    kind?: string;
+}
+/**
+ * Options for {@link UserState.listValues}.
+ */
+interface ListUserValuesOptions {
+    prefix?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * One durable user value entry.
+ */
+interface UserValueEntry {
+    key: string;
+    value: unknown;
+    /** Last-write timestamp (milliseconds since epoch). */
+    updated_at: number;
+}
+/**
+ * Options for {@link UserState.listThreads}.
+ */
+interface ListUserThreadsOptions {
+    agentId?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Registry metadata for one of a user's threads.
+ */
+interface UserThreadSummary {
+    id: string;
+    agent_id: string;
+    tags: string[];
+    /** Creation timestamp (microseconds since epoch). */
+    created_at: number;
+}
+/**
+ * The user scope surface provided to user endpoints and user lifecycle hooks.
+ *
+ * The runtime serializes user endpoint executions and
+ * {@link UserHandle.call} invocations per user: at most one executes at a
+ * time, and each observes the completed writes of all prior executions for
+ * that user. This is the atomicity guarantee that makes user endpoints the
+ * designated home for quotas, leases, counters, and registries. Value access
+ * outside user endpoints (thread-side reads/writes) is NOT serialized.
+ */
+interface UserState {
+    /** The user this scope belongs to. */
+    userId: string;
+    /** Identity fields (never credentials). */
+    identity(): Promise<UserIdentity>;
+    /** Read a durable user-scoped value. */
+    getValue<T = unknown>(key: string): Promise<T | null>;
+    /** Write a durable user-scoped value (`null`/`undefined` deletes). */
+    setValue(key: string, value: unknown): Promise<void>;
+    /** List durable user-scoped values. */
+    listValues(options?: ListUserValuesOptions): Promise<{
+        entries: UserValueEntry[];
+        total: number;
+    }>;
+    /**
+     * Resolve a user-scoped environment property. Rejects when the property is
+     * not defined for this user.
+     */
+    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`).
+     */
+    emit(event: string, data?: unknown): void;
+    /** Registry metadata for the user's threads. */
+    listThreads(options?: ListUserThreadsOptions): Promise<{
+        threads: UserThreadSummary[];
+        total: number;
+    }>;
+    /**
+     * Privileged fetch through a named credential grant. The runtime injects
+     * the credential per the grant's policy; packaged code never sees the
+     * secret material. Rejects for destinations outside the grant's `origins`
+     * and callers outside its `allow` policy.
+     */
+    fetch(grant: string, input: string | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Raise one of this user's threads at rest — the same materialization
+     * thread endpoints receive (`state.execution` is `null`). Rejects for
+     * threads not belonging to the user. Operations on the resolved state
+     * execute in the thread scope; the user-scope serialization guarantee does
+     * not extend across them. A reentrant user-scope invocation
+     * (`state.user()` → `call()`) made from code reached through `thread()`
+     * within the same user execution MUST fail rather than deadlock.
+     */
+    thread(threadId: string): Promise<ThreadState>;
+}
+/**
+ * The user handle resolved by {@link ThreadState.user} — the identity fields
+ * of {@link UserIdentity} plus scoped capabilities. Additive to the historic
+ * identity-only return value.
+ */
+interface UserHandle extends ThreadUser {
+    /**
+     * Invoke a named user endpoint for the thread's user under the user
+     * scope's serialization guarantee. The runtime MUST NOT require network
+     * self-addressing to fulfill this call. Rejects for user-less threads.
+     *
+     * @param endpoint - The user endpoint path (e.g. `"standardcode/lease_acquire"`)
+     * @param payload - JSON-serializable request body (POSTed to the handler)
+     */
+    call(endpoint: string, payload?: unknown): Promise<Response>;
+    /** Read a durable user value (unserialized convenience access). */
+    getValue<T = unknown>(key: string): Promise<T | null>;
+    /** Write a durable user value (unserialized convenience access). */
+    setValue(key: string, value: unknown): Promise<void>;
+    /** Broadcast on the user event stream. */
+    emit(event: string, data?: unknown): void;
+    /** Privileged fetch through a named credential grant. */
+    fetch(grant: string, input: string | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * A named, user-scoped credential with a declared use policy.
+ *
+ * Secret material is write-only: it is set through runtime credential APIs
+ * and is never readable by packaged code, models, or clients. Only
+ * `metadata` and grant existence are inspectable. Deleting a grant fails
+ * subsequent `fetch` calls with an error distinguishable from a network
+ * failure.
+ */
+interface CredentialGrant {
+    /** Grant name, e.g. `"github"`. */
+    name: string;
+    /** How the credential is applied to requests. */
+    kind: 'bearer' | 'header' | 'query' | 'basic' | 'signing';
+    /** Allowed destinations: exact origins or suffix wildcards (`*.example.com`). */
+    origins: string[];
+    /**
+     * Injection template. `format` may reference `SECRET`, which expands
+     * runtime-side after policy checks (e.g. `{ header: 'Authorization',
+     * format: 'token SECRET' }`).
+     */
+    inject?: {
+        header?: string;
+        format?: string;
+        query?: string;
+    };
+    /**
+     * Which packaged resources may use this grant. An absent `allow` denies
+     * all callers.
+     */
+    allow?: {
+        tools?: string[];
+        endpoints?: string[];
+        userEndpoints?: string[];
+        agents?: string[];
+    };
+    /** Non-secret metadata: account label, scopes, expiry. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Symbol used to identify user endpoint handlers.
+ *
+ * When a handler is created with {@link defineUserEndpoint}, it's marked with
+ * this symbol so the runtime can detect it and execute it in the user scope
+ * with a UserState.
+ */
+declare const USER_ENDPOINT_SYMBOL: unique symbol;
+/**
+ * Route parameters captured from `[param]` and `[*]` segments of a user
+ * endpoint file path.
+ */
+type UserEndpointRouteParams = Record<string, string>;
+/**
+ * User endpoint handler function.
+ *
+ * Receives the HTTP request and the UserState for the addressed user.
+ * `me` routes resolve the authenticated caller; `users/{id}` routes are
+ * served to callers authorized to administer that user.
+ */
+type UserEndpointHandler = (req: Request, user: UserState, params: UserEndpointRouteParams) => Response | Promise<Response>;
+/**
+ * A handler that has been marked as a user endpoint.
+ */
+interface MarkedUserEndpoint {
+    [USER_ENDPOINT_SYMBOL]: true;
+    __handler: UserEndpointHandler;
+    (req: Request, user: UserState, params: UserEndpointRouteParams): Response | Promise<Response>;
+}
+/**
+ * Type guard to check if a value is a marked user endpoint.
+ */
+declare function isUserEndpoint(value: unknown): value is MarkedUserEndpoint;
+/**
+ * Define a user-scoped endpoint.
+ *
+ * User endpoint files live in the project or package `users/` directory and
+ * are file-routed beneath `{runtime_prefix}/users/me/` with the same rules
+ * as thread endpoints (method suffixes, nested directories, `[param]` and
+ * `[*]` segments). Nested directories namespace endpoints; packages SHOULD
+ * root their endpoints in a package-named directory.
+ *
+ * Handlers execute in the user scope under per-user serialization: at most
+ * one user endpoint (or {@link UserHandle.call}) executes at a time for a
+ * given user, and each observes all prior completed writes.
+ *
+ * @example
+ * ```typescript
+ * // users/quota.post.ts → POST {runtime_prefix}/users/me/quota
+ * import { defineUserEndpoint } from '@standardagents/spec';
+ *
+ * export default defineUserEndpoint(async (req, user) => {
+ *   const used = (await user.getValue<number>('quota.used')) ?? 0;
+ *   const limit = Number(await user.getValue('quota.limit')) || 0;
+ *   const { amount } = await req.json() as { amount: number };
+ *   if (used + amount > limit) {
+ *     return Response.json({ ok: false, used, limit }, { status: 429 });
+ *   }
+ *   await user.setValue('quota.used', used + amount);
+ *   user.emit('quota_changed', { used: used + amount, limit });
+ *   return Response.json({ ok: true, used: used + amount, limit });
+ * });
+ * ```
+ */
+declare function defineUserEndpoint(handler: UserEndpointHandler): MarkedUserEndpoint;
+
 /**
  * Agent Skills — instance-global skill store types.
  *
@@ -1943,20 +2195,24 @@ interface ThreadState {
         total: number;
     }>;
     /**
-     * The profile of the user this thread belongs to, or `null` when the thread
-     * has no associated user (e.g. unauthenticated local development).
+     * The user this thread belongs to, or `null` when the thread has no
+     * associated user (e.g. unauthenticated local development).
      *
-     * Lets tools and hooks personalize or gate behavior per user — e.g. an
-     * entitlement hook enforcing a per-user concurrency limit, or a tool
-     * addressing the user by name. Never includes credentials.
+     * Resolves a {@link UserHandle}: the identity fields (never credentials)
+     * plus user-scope capabilities — `call()` into packaged user endpoints
+     * under the user scope's serialization guarantee, durable user values,
+     * `emit()` on the user event stream, and privileged `fetch()` through
+     * credential grants.
      *
      * @example
      * ```typescript
      * const user = await state.user();
      * if (user?.email) await notifyBillingService(user.email);
+     * // Atomic user-scope logic (quotas, leases) goes through call():
+     * await user?.call('standardcode/lease_acquire', { thread_id: state.threadId });
      * ```
      */
-    user(): Promise<ThreadUser | null>;
+    user(): Promise<UserHandle | null>;
     /**
      * The instance-global Agent Skills library (https://agentskills.io format).
      *
@@ -4318,6 +4574,29 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      * @param toolResult - The tool's result (`status` is `'success'` or `'error'`)
      */
     tool_call_done: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<void>;
+    /**
+     * Called when a socket attaches to the user's event stream
+     * (`{runtime_prefix}/users/me/stream`).
+     *
+     * @param user - User scope state
+     * @param client - The attached client's id and self-declared kind
+     */
+    user_client_attached: (user: UserState, client: UserClientInfo) => Promise<void>;
+    /**
+     * Called when a socket detaches from the user's event stream.
+     *
+     * @param user - User scope state
+     * @param client - The detached client's id and self-declared kind
+     */
+    user_client_detached: (user: UserState, client: UserClientInfo) => Promise<void>;
+    /**
+     * Called after a durable user value changes, regardless of the writer
+     * (user endpoint, thread-side handle, or REST).
+     *
+     * @param user - User scope state
+     * @param key - The key that changed
+     */
+    user_value_changed: (user: UserState, key: string) => Promise<void>;
 }
 /**
  * Valid hook names.
@@ -5214,4 +5493,4 @@ interface PackedExports {
     __meta: PackedMeta;
 }
 
-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 DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type EnvValueType, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type MarkedThreadEndpoint, 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 PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, 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, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadEndpointRouteParams, 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, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, 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, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type EnvValueType, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, 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 PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, 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, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadEndpointRouteParams, 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, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, isPacked, isThreadEndpoint, isUserEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateToolName };

package/dist/index.js

@@ -369,6 +369,18 @@ function defineThreadEndpoint(handler) {
   return markedHandler;
 }
 
+// src/users.ts
+var USER_ENDPOINT_SYMBOL = Symbol.for("standardagents.userEndpoint");
+function isUserEndpoint(value) {
+  return typeof value === "function" && USER_ENDPOINT_SYMBOL in value && value[USER_ENDPOINT_SYMBOL] === true;
+}
+function defineUserEndpoint(handler) {
+  const marked = handler;
+  marked[USER_ENDPOINT_SYMBOL] = true;
+  marked.__handler = handler;
+  return marked;
+}
+
 // src/providers.ts
 var ProviderError = class extends Error {
   constructor(message, code, statusCode, retryAfter, options) {
@@ -423,6 +435,7 @@ export {
   ProviderError,
   THREAD_ENDPOINT_SYMBOL,
   THREAD_STREAM_REASONING_PARAM,
+  USER_ENDPOINT_SYMBOL,
   belongsToPackage,
   defineAgent,
   defineController,
@@ -433,8 +446,10 @@ export {
   defineProvider,
   defineThreadEndpoint,
   defineTool,
+  defineUserEndpoint,
   isPacked,
   isThreadEndpoint,
+  isUserEndpoint,
   isVisibleInNamespace,
   mapReasoningLevel,
   providerConst,