@standardagents/spec 0.41.16 → 0.41.18

package/dist/index.d.ts

@@ -1174,6 +1174,9 @@ interface ThreadUser {
     username: string;
     /** 'admin' | 'user' | 'api' in the reference runtime. */
     role: string;
+    /** Application-defined roles supplied by the identity authority. Opaque strings;
+     * runtimes do not infer permissions or expand wildcards. Missing means no roles. */
+    roles?: string[];
     /** Explicit permission grants (runtime-defined strings), if any. */
     permissions?: string[] | null;
     email?: string | null;
@@ -1462,6 +1465,72 @@ interface ThreadReasoningChunkEvent {
  * server never emits reasoning to that socket.
  */
 declare const THREAD_STREAM_REASONING_PARAM = "reasoning";
+/**
+ * Coarse execution state of a thread.
+ *
+ * - `idle` — no execution is running and the last run did not fail: it ended
+ *   normally (a reply, a stop tool, a stop-on-response, a park for a
+ *   human-backed side, a user abort, a hook block, a step/turn cap) or the
+ *   thread has never run.
+ * - `running` — an execution is in flight.
+ * - `failed` — the last run ended in an error (a step error, a fatal
+ *   execution error, a repeated tool error, a session failure, or an
+ *   execution the runtime lost and could not recover).
+ *
+ * The run state describes execution only, not conversational turn
+ * ownership: a run that ended by handing the turn to a human side is `idle`
+ * with `reason` `awaiting_human` (or the stop code that ended the turn).
+ */
+type ThreadRunState = 'idle' | 'running' | 'failed';
+/**
+ * Authoritative run status of a thread.
+ *
+ * Runtimes persist the status with the thread so it survives restarts, and
+ * MUST NOT leave a thread `running` once its executor is gone: a lost
+ * execution resolves to `failed` (reason `execution_lost`).
+ *
+ * Read it with {@link ThreadState.status}, from `GET /api/threads/:id`
+ * (`status` field), or live from the thread message stream
+ * ({@link ThreadStatusEvent}).
+ */
+interface ThreadStatus {
+    /** Current run state. */
+    state: ThreadRunState;
+    /** When the thread entered this state (microseconds since epoch, like `created_at`). */
+    since: number;
+    /**
+     * The raw stop reason code of the last transition out of `running` — for
+     * example `stop_on_response`, `stop_tool`, `awaiting_human`,
+     * `hook_blocked`, `max_total_steps`, `aborted_by_user`, `step_error`,
+     * `fatal_error`, `execution_lost`. Null while `running` and for a thread
+     * that has never run. Runtimes MAY report codes beyond this list; clients
+     * MUST treat unknown codes as opaque.
+     */
+    reason?: string | null;
+}
+interface ThreadStatusEvent {
+    type: 'thread_status';
+    status: ThreadStatus;
+}
+/** Severity of an application log entry. */
+type ThreadLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * An application log entry recorded with {@link ThreadState.log}.
+ *
+ * Runtimes bound entry sizes and truncate oversized fields with a marker
+ * instead of rejecting the entry: `name` to 120 characters, `message` to
+ * 4 KiB, and the JSON encoding of `data` to 16 KiB.
+ */
+interface ThreadLogEntry {
+    /** Short event name, e.g. `cache.miss` or `sync.completed`. */
+    name: string;
+    /** Human-readable detail. */
+    message?: string;
+    /** Severity. Defaults to `info`. */
+    level?: ThreadLogLevel;
+    /** Structured, JSON-serializable detail. */
+    data?: Record<string, unknown>;
+}
 /**
  * Storage location identifier.
  *
@@ -2588,6 +2657,33 @@ interface ThreadState {
      * @returns Thumbnail data as ArrayBuffer, or null if not available
      */
     getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
+    /**
+     * Read the thread's authoritative run status.
+     *
+     * A method rather than a property: the status changes while the caller
+     * holds the state (a tool runs inside a `running` thread; an endpoint
+     * observes it later), so every call reads the current persisted value.
+     *
+     * Not to be confused with {@link ThreadState.setStatus}, which writes a
+     * free-form label into this thread's entry in its PARENT's subagent
+     * registry and does not affect the run status.
+     */
+    status(): Promise<ThreadStatus>;
+    /**
+     * Record an application log entry on the thread.
+     *
+     * The entry appears alongside the runtime's own execution logs (LLM
+     * requests, tool and handler executions) and is delivered to live log
+     * subscribers. Logging never creates a message, never starts or wakes an
+     * execution, and never throws because an entry is too large (see
+     * {@link ThreadLogEntry} for the size bounds).
+     *
+     * @example
+     * ```typescript
+     * await state.log({ name: 'cache.miss', level: 'debug', data: { key } });
+     * ```
+     */
+    log(entry: ThreadLogEntry): Promise<void>;
     /**
      * Execution-specific state.
      *
@@ -6254,4 +6350,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 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 };
+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 ThreadLogEntry, type ThreadLogLevel, 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, 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 };