@standardagents/spec 0.37.8 → 0.38.1

package/dist/index.d.ts

@@ -833,6 +833,10 @@ interface UserHandle extends ThreadUser {
      * scope's serialization guarantee. The runtime MUST NOT require network
      * self-addressing to fulfill this call. Rejects for user-less threads.
      *
+     * The endpoint is always relative to the packaged user-endpoint namespace.
+     * Runtimes reject dot-segment traversal (including encoded/backslash forms)
+     * rather than allowing URL normalization to address another hub route.
+     *
      * @param endpoint - The user endpoint path (e.g. `"standardcode/lease_acquire"`)
      * @param payload - JSON-serializable request body (POSTed to the handler)
      */
@@ -952,16 +956,17 @@ declare function isUserEndpoint(value: unknown): value is MarkedUserEndpoint;
 declare function defineUserEndpoint(handler: UserEndpointHandler): MarkedUserEndpoint;
 
 /**
- * Agent Skills — instance-global skill store types.
+ * Agent Skills — principal-scoped skill store types.
  *
  * Skills follow the Agent Skills standard (https://agentskills.io): a folder
  * whose root SKILL.md opens with YAML frontmatter carrying a required `name`
  * (lowercase kebab, ≤64 chars) and `description` (≤1024 chars), optionally
  * accompanied by scripts, references, and assets.
  *
- * Runtimes store skills server-side as a GLOBAL, instance-wide library:
- * installed once, visible to every thread, nothing persisted on a client
- * machine. Progressive disclosure is the contract — agents see only each
+ * Runtimes store skills server-side and scope visibility to the calling
+ * principal. A runtime may additionally expose administrator-reviewed shared
+ * skills. One principal's private skill MUST NOT be visible to another.
+ * Progressive disclosure is the contract — agents see only each
  * skill's name + description until a skill is judged applicable, at which
  * point they load its SKILL.md body (and, when needed, read or execute its
  * bundled files).
@@ -987,9 +992,9 @@ interface SkillFileInput {
     content: string;
 }
 /**
- * ThreadState surface for the global skill library. All operations hit the
- * instance-wide store — there is no per-thread skill state beyond what a
- * thread chooses to keep in its own key-value store.
+ * ThreadState surface for the calling thread owner's skill library plus any
+ * explicitly shared runtime skills. Owner-scoped names take precedence over a
+ * shared skill with the same name.
  */
 interface SkillsNamespace {
     /** Installed skills (enabled only, unless includeDisabled). */
@@ -1007,11 +1012,16 @@ interface SkillsNamespace {
      * Install (or replace) a skill from its file set. The file set must include
      * a root SKILL.md with valid frontmatter; the skill's identity comes from
      * that frontmatter, never from a caller-supplied name.
+     *
+     * Runtimes MUST authorize mutation and confine it to the calling principal's
+     * scope. Multi-tenant runtimes MUST NOT permit ordinary tenant agent code to
+     * mutate shared skills; an administrative or equivalently trusted principal
+     * is required for shared-library changes.
      */
     install(files: SkillFileInput[]): Promise<SkillMetadata>;
-    /** Enable/disable an installed skill. Returns false when not installed. */
+    /** Enable/disable an installed skill. Requires mutation authorization. */
     setEnabled(name: string, enabled: boolean): Promise<boolean>;
-    /** Uninstall a skill entirely. Returns false when not installed. */
+    /** Uninstall a skill entirely. Requires mutation authorization. */
     remove(name: string): Promise<boolean>;
 }
 
@@ -1961,6 +1971,21 @@ interface ThreadState {
      * @throws If the variable is not defined in any source
      */
     env(propertyName: string): Promise<string>;
+    /**
+     * Resolve an environment value exclusively from the runtime instance.
+     *
+     * Unlike `env()`, this method never considers thread, agent, prompt, or user
+     * values. Use it for security-sensitive instance configuration such as
+     * trusted service endpoints and the credentials sent to those endpoints.
+     *
+     * This capability is optional for backward compatibility with runtimes that
+     * predate instance-scoped environment access. Consumers that require an
+     * instance trust boundary MUST fail closed when the method is unavailable.
+     *
+     * @returns The instance value, or `undefined` when the key is not configured
+     * @throws If the runtime cannot read the instance environment
+     */
+    instanceEnv?(propertyName: string): Promise<string | undefined>;
     /**
      * Resolve the display/redaction type for an environment value.
      *
@@ -2226,7 +2251,8 @@ interface ThreadState {
      *
      * 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,
+     * under the user scope's serialization guarantee (with endpoint paths
+     * confined to that namespace), durable user values,
      * `emit()` on the user event stream, and privileged `fetch()` through
      * credential grants.
      *
@@ -2240,10 +2266,12 @@ interface ThreadState {
      */
     user(): Promise<UserHandle | null>;
     /**
-     * The instance-global Agent Skills library (https://agentskills.io format).
+     * The thread owner's Agent Skills library plus explicitly shared skills
+     * (https://agentskills.io format).
      *
-     * Skills are installed once and visible to every thread; their files live
-     * server-side (never on a client machine). Agents should follow progressive
+     * Private skills are visible only to the owning principal; administrator-
+     * reviewed shared skills may also be visible. Their files live server-side
+     * (never on a client machine). Agents should follow progressive
      * disclosure: browse metadata via `skills.list()`, and load a skill's
      * SKILL.md body with `skills.get()` only when it is applicable to the task.
      *
@@ -5108,6 +5136,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 +5248,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 +5323,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 +5364,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 +5376,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 +5445,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 +5675,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,