@standardagents/spec 0.37.8 → 0.38.0

package/dist/index.d.ts

@@ -5108,6 +5108,68 @@ declare function defineAgent<N extends string>(options: AgentDefinition<N>): Age
  * @module
  */
 
+/**
+ * The access level of an endpoint.
+ *
+ * - `authenticated` — the runtime MUST authenticate the request before
+ *   invoking the handler, and for thread endpoints MUST additionally enforce
+ *   its thread access policy. Requests that fail authentication or
+ *   authorization MUST be rejected without invoking the handler.
+ * - `public` — the runtime MUST invoke the handler regardless of the
+ *   request's authentication state. The runtime MUST still attempt caller
+ *   resolution: a request presenting credentials the runtime can verify is
+ *   attributed to that caller, and any other request is treated as anonymous
+ *   rather than rejected.
+ *
+ * When no access level is declared, the access level is `authenticated`.
+ */
+type EndpointAccess = 'authenticated' | 'public';
+/**
+ * Symbol used to carry an endpoint's declared access level.
+ *
+ * The declaration is attached to the handler at definition time so that
+ * runtimes can read it before routing the request through their
+ * authentication layer.
+ */
+declare const ENDPOINT_ACCESS_SYMBOL: unique symbol;
+/**
+ * Options accepted when defining an endpoint.
+ */
+interface EndpointOptions {
+    /**
+     * The endpoint's access level. Defaults to `authenticated`.
+     */
+    access?: EndpointAccess;
+}
+/**
+ * Resolve the declared access level of an endpoint handler.
+ *
+ * Returns `authenticated` when the value carries no declaration.
+ */
+declare function getEndpointAccess(value: unknown): EndpointAccess;
+/**
+ * The authentication context supplied to a thread endpoint handler.
+ *
+ * The runtime constructs this context for every invocation:
+ *
+ * - `caller` MUST be the authenticated identity when the request presented
+ *   credentials the runtime verified, and `null` otherwise. For an endpoint
+ *   whose access level is `authenticated`, `caller` is always non-null.
+ * - `threadAccess` MUST be `true` if and only if the runtime's thread access
+ *   policy grants the resolved caller access to the requested thread. It
+ *   MUST be `false` when `caller` is `null`. For an endpoint whose access
+ *   level is `authenticated`, `threadAccess` is always `true`.
+ *
+ * The mechanism by which a runtime authenticates requests is
+ * implementation-defined; this interface defines only the identity contract
+ * observable by endpoint code.
+ */
+interface ThreadEndpointAuth {
+    /** The authenticated caller, or `null` for an anonymous request. */
+    caller: ThreadUser | null;
+    /** Whether the caller satisfies the runtime's access policy for the requested thread. */
+    threadAccess: boolean;
+}
 /**
  * Symbol used to identify thread endpoint handlers.
  *
@@ -5158,6 +5220,15 @@ type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
 interface ControllerContext {
     /** The incoming HTTP request */
     req: Request;
+    /**
+     * The authenticated caller, or `null` for an anonymous request.
+     *
+     * Populated under the same contract as {@link ThreadEndpointAuth.caller}:
+     * non-null whenever the request presented credentials the runtime
+     * verified, and always non-null for a controller whose access level is
+     * `authenticated`.
+     */
+    caller?: ThreadUser | null;
     /** URL path parameters extracted by the router */
     params: Record<string, string>;
     /** Parsed URL object */
@@ -5224,16 +5295,25 @@ type Controller = (context: ControllerContext) => ControllerReturn;
  * Thread endpoint routes are scoped beneath the runtime's thread ID prefix.
  * A request under that prefix that does not match any local or packed thread
  * endpoint route MUST return HTTP 404.
+ *
+ * The fourth argument carries the request's authentication context under the
+ * contract defined by {@link ThreadEndpointAuth}. Handlers that do not
+ * consume it may omit the parameter.
  */
 type ThreadEndpointRouteParams = Record<string, string>;
-type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEndpointRouteParams) => Response | Promise<Response>;
+type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEndpointRouteParams, auth: ThreadEndpointAuth) => Response | Promise<Response>;
 /**
  * Define a standard HTTP controller.
  *
  * Controllers handle HTTP requests and return responses. They have
  * access to the controller context including virtual module registries.
  *
+ * A controller's access level is declared through `options.access` and
+ * defaults to `authenticated`; see {@link EndpointAccess} for the
+ * requirements each level places on the runtime.
+ *
  * @param controller - The controller function
+ * @param options - Endpoint options, including the access level
  * @returns The controller for registration
  *
  * @example
@@ -5256,7 +5336,7 @@ type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEn
  * });
  * ```
  */
-declare function defineController(controller: Controller): Controller;
+declare function defineController(controller: Controller, options?: EndpointOptions): Controller;
 /**
  * Define a thread-specific endpoint.
  *
@@ -5268,7 +5348,14 @@ declare function defineController(controller: Controller): Controller;
  * Runtimes MUST return HTTP 404 for requests beneath the thread endpoint
  * prefix that do not match any local or packed thread endpoint route.
  *
- * @param handler - The handler function receiving request, ThreadState, and route params
+ * A thread endpoint's access level is declared through `options.access` and
+ * defaults to `authenticated`; see {@link EndpointAccess} for the
+ * requirements each level places on the runtime. Handlers receive the
+ * request's authentication context as their fourth argument under the
+ * contract defined by {@link ThreadEndpointAuth}.
+ *
+ * @param handler - The handler function receiving request, ThreadState, route params, and authentication context
+ * @param options - Endpoint options, including the access level
  * @returns A Controller that can be used with the router
  *
  * @example
@@ -5330,8 +5417,24 @@ declare function defineController(controller: Controller): Controller;
  *   return Response.json({ exists: !!file });
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // agents/api/status.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(
+ *   async (req, state, params, auth) => {
+ *     return Response.json({
+ *       threadId: state.threadId,
+ *       authorized: auth.threadAccess,
+ *     });
+ *   },
+ *   { access: 'public' }
+ * );
+ * ```
  */
-declare function defineThreadEndpoint(handler: ThreadEndpointHandler): MarkedThreadEndpoint;
+declare function defineThreadEndpoint(handler: ThreadEndpointHandler, options?: EndpointOptions): MarkedThreadEndpoint;
 
 /**
  * Packing types for Standard Agents.
@@ -5544,4 +5647,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 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 };
+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, ENDPOINT_ACCESS_SYMBOL, type Effect, type EffectDefinition, type EmptyUsesState, type EndpointAccess, type EndpointOptions, 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 ThreadEndpointAuth, 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, getEndpointAccess, isPacked, isThreadEndpoint, isUserEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateToolName };

package/dist/index.js

@@ -355,17 +355,30 @@ function defineAgent(options) {
 var THREAD_STREAM_REASONING_PARAM = "reasoning";
 
 // src/endpoints.ts
+var ENDPOINT_ACCESS_SYMBOL = Symbol.for("standardagents.endpointAccess");
+function getEndpointAccess(value) {
+  if ((typeof value === "function" || typeof value === "object" && value !== null) && value[ENDPOINT_ACCESS_SYMBOL] === "public") {
+    return "public";
+  }
+  return "authenticated";
+}
 var THREAD_ENDPOINT_SYMBOL = Symbol.for("standardagents.threadEndpoint");
 function isThreadEndpoint(controller) {
   return THREAD_ENDPOINT_SYMBOL in controller && controller[THREAD_ENDPOINT_SYMBOL] === true;
 }
-function defineController(controller) {
+function defineController(controller, options) {
+  if (options?.access) {
+    controller[ENDPOINT_ACCESS_SYMBOL] = options.access;
+  }
   return controller;
 }
-function defineThreadEndpoint(handler) {
+function defineThreadEndpoint(handler, options) {
   const markedHandler = handler;
   markedHandler[THREAD_ENDPOINT_SYMBOL] = true;
   markedHandler.__handler = handler;
+  if (options?.access) {
+    markedHandler[ENDPOINT_ACCESS_SYMBOL] = options.access;
+  }
   return markedHandler;
 }
 
@@ -432,6 +445,7 @@ function isVisibleInNamespace(metadata, namespace, isEntryPoint = false) {
   return isOwnPackage || hasPkg && isEntryPoint;
 }
 export {
+  ENDPOINT_ACCESS_SYMBOL,
   ProviderError,
   THREAD_ENDPOINT_SYMBOL,
   THREAD_STREAM_REASONING_PARAM,
@@ -447,6 +461,7 @@ export {
   defineThreadEndpoint,
   defineTool,
   defineUserEndpoint,
+  getEndpointAccess,
   isPacked,
   isThreadEndpoint,
   isUserEndpoint,