@standardagents/spec 0.41.20 → 0.41.21

package/dist/index.d.ts

@@ -1514,21 +1514,89 @@ interface ThreadStatusEvent {
 }
 /** Severity of an application log entry. */
 type ThreadLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Outcome of the operation an application log entry records.
+ *
+ * - `success` — the operation completed and produced its result.
+ * - `error` — the operation failed; put the reason in `error`.
+ * - `skipped` — the operation was deliberately not performed (a guard,
+ *   cache hit, or policy decided against it).
+ */
+type ThreadLogStatus = 'success' | 'error' | 'skipped';
+/**
+ * The event that caused an application log entry: what woke the code that
+ * wrote it. `kind` is a short category the application chooses (for example
+ * `message`, `webhook`, `schedule`, `tool_call`); `id` identifies the
+ * specific event when one exists; `summary` is a one-line human description.
+ */
+interface ThreadLogTrigger {
+    /** Short category of the triggering event, e.g. `message` or `webhook`. */
+    kind: string;
+    /** Identifier of the triggering event (a message id, delivery id, …). */
+    id?: string;
+    /** One-line human description of the triggering event. */
+    summary?: string;
+}
 /**
  * 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.
+ * Any code with a `ThreadState` (hooks, tools, endpoints, handlers) can record
+ * one. Only `name` is required; a plain event is `{ name, message }`. When the
+ * entry records an operation — a call to another service, a decision, a
+ * background job — fill in the operation fields so a reader can see what was
+ * sent, what came back, how long it took, what it cost, and what caused it:
+ *
+ * ```typescript
+ * await state.log({
+ *   name: 'search.query',
+ *   status: 'success',
+ *   trigger: { kind: 'message', id: messageId, summary: 'User asked for flights' },
+ *   request: { q: 'flights to Lisbon' },
+ *   response: { results: 12 },
+ *   duration_ms: 182,
+ *   cost: 0.0004,
+ * });
+ * ```
+ *
+ * Every field other than `name` is optional, and runtimes ignore fields of the
+ * wrong type rather than rejecting the entry. Runtimes bound entry sizes and
+ * truncate oversized fields with a marker instead of rejecting the entry:
+ * `name` to 120 characters, `message` and `error` to 4 KiB, the JSON
+ * encoding of `data` to 16 KiB, and the JSON encodings of `request` and
+ * `response` to 64 KiB each. A value that cannot be JSON-encoded is replaced
+ * by a marker object; logging never throws because of an entry's content.
  */
 interface ThreadLogEntry {
-    /** Short event name, e.g. `cache.miss` or `sync.completed`. */
+    /** Short event name, e.g. `cache.miss` or `sync.completed`. Required. */
     name: string;
-    /** Human-readable detail. */
+    /** Human-readable detail: one line a person reads first. */
     message?: string;
-    /** Severity. Defaults to `info`. */
+    /**
+     * Severity. Defaults to `error` when `status` is `error`, otherwise `info`.
+     */
     level?: ThreadLogLevel;
-    /** Structured, JSON-serializable detail. */
+    /** Outcome of the recorded operation. Omit for a plain event. */
+    status?: ThreadLogStatus;
+    /**
+     * What was sent, or the input that triggered the work: a request payload,
+     * the arguments of a call, the content of an incoming event. Any
+     * JSON-serializable value; strings are kept as text.
+     */
+    request?: unknown;
+    /**
+     * What came back: the response payload or result of the operation. Any
+     * JSON-serializable value; strings are kept as text.
+     */
+    response?: unknown;
+    /** Failure reason when the operation failed (usually with `status: 'error'`). */
+    error?: string;
+    /** Wall-clock duration of the operation in milliseconds (finite, ≥ 0). */
+    duration_ms?: number;
+    /** Cost of the operation in USD, when it cost money (finite, ≥ 0). */
+    cost?: number;
+    /** The event that caused this entry. */
+    trigger?: ThreadLogTrigger;
+    /** Any other structured, JSON-serializable detail. */
     data?: Record<string, unknown>;
 }
 /**
@@ -2676,11 +2744,24 @@ interface ThreadState {
      * 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).
+     * {@link ThreadLogEntry} for the size bounds). An entry may record a plain
+     * event or a whole operation: its outcome, what triggered it, what was sent,
+     * what came back, its duration and its cost.
      *
      * @example
      * ```typescript
      * await state.log({ name: 'cache.miss', level: 'debug', data: { key } });
+     *
+     * await state.log({
+     *   name: 'reply.skipped',
+     *   status: 'skipped',
+     *   message: 'Nothing new to say',
+     *   trigger: { kind: 'message', id: messageId },
+     *   request: { prompt },
+     *   response: { decision: 'skip' },
+     *   duration_ms: 412,
+     *   cost: 0.0012,
+     * });
      * ```
      */
     log(entry: ThreadLogEntry): Promise<void>;
@@ -6350,4 +6431,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 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 };
+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 ThreadLogStatus, type ThreadLogTrigger, 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 };