@standardagents/builder 0.36.3 → 0.37.1

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
-import { e as ThreadEnv, A as Agent, r as ThreadMetadata, t as ToolResult, M as Message, k as ClientToolRequest, l as ClientToolResponse, m as ClientStreamRequest, n as ClientStreamResponse, w as FileRecord, F as FlowState, y as FileStats, G as GrepResult, x as AttachmentRef, J as MessageContent, E as Env, q as ThreadInstance } from './index-DUIfQjBW.js';
-export { f as BuilderThreadEndpointHandler, C as CLIENT_STREAM_CHUNK_BYTES, o as ClientDuplex, p as ClientForwarding, B as Controller, a as ControllerContext, u as FlowResult, D as ImageContentPart, I as ImageMetadata, L as LLMResponse, H as MultimodalContent, R as RequestContext, S as StorageBackend, v as TelemetryEvent, z as TextContentPart, b as ThreadEndpointContext, T as ToolCall, g as callClient, h as callClientStream, c as createThreadEndpointHandler, j as decodeStreamChunk, d as defineController, i as encodeStreamChunk, s as supportsClientForwarding } from './index-DUIfQjBW.js';
+import { i as AuthContext, e as ThreadEnv, v as Agent, x as ThreadMetadata, y as ToolResult, M as Message, n as ClientToolRequest, o as ClientToolResponse, p as ClientStreamRequest, q as ClientStreamResponse, G as FileRecord, F as FlowState, K as FileStats, J as GrepResult, H as AttachmentRef, Q as MessageContent, E as Env, w as ThreadInstance } from './index-DceFbLG9.js';
+export { A as AuthUser, f as BuilderThreadEndpointHandler, C as CLIENT_STREAM_CHUNK_BYTES, t as ClientDuplex, u as ClientForwarding, B as Controller, a as ControllerContext, z as FlowResult, O as ImageContentPart, I as ImageMetadata, L as LLMResponse, P as MultimodalContent, R as RequestContext, S as StorageBackend, D as TelemetryEvent, N as TextContentPart, b as ThreadEndpointContext, T as ToolCall, g as authenticate, j as callClient, k as callClientStream, c as createThreadEndpointHandler, m as decodeStreamChunk, d as defineController, l as encodeStreamChunk, h as requireAdmin, r as requireAuth, s as supportsClientForwarding } from './index-DceFbLG9.js';
 import { CodeExecutionOptions, CodeExecutionResult, SubagentRegistryEntry, InjectMessageInput, QueueMessageInput, CredentialGrant, SkillMetadata, SkillFileInput, ModelDefinition as ModelDefinition$1, ToolArgs, PromptTextPart, PromptEnvPart, VariableDefinition, SubpromptConfig as SubpromptConfig$1, PromptToolConfig as PromptToolConfig$1, SubagentToolConfig as SubagentToolConfig$1, ReasoningConfig, SideConfig as SideConfig$1, LLMProviderInterface, ContentPart, TextPart, ImagePart, FilePart, ThreadState, NamespaceContext, DefinitionLoader } from '@standardagents/spec';
 export { AgentType, DefinitionLoader, GlobalNamespaceContext, HookSignatures, ImageContent, ModelCapabilities, ModelProvider, NamespaceContext, PackageSignature, PackedExports, PackedMeta, PackedMetadata, PackedNamespaceContext, PromptInput, PromptTextPart, ProviderAssistantMessage, ProviderError, ProviderErrorCode, ProviderFactory, ProviderFactoryConfig, ProviderFinishReason, ProviderGeneratedImage, ProviderMessage, ProviderMessageContent, ModelCapabilities as ProviderModelCapabilities, ProviderReasoningDetail, ProviderRequest, ProviderResponse, ProviderStreamChunk, ProviderSystemMessage, ProviderTool, ProviderToolCallPart, ProviderToolMessage, ProviderToolResultContent, ProviderUsage, ProviderUserMessage, ReasoningConfig, StructuredPrompt, TextContent, Tool, ToolArgs, ToolArgsNode, ToolArgsRawShape, ToolContent, belongsToPackage, defineAgent, defineHook, defineModel, definePrompt, defineTool, isPacked, isVisibleInNamespace, mapReasoningLevel } from '@standardagents/spec';
 import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
@@ -94,46 +94,39 @@ declare global {
 }
 
 /**
- * Authentication middleware for protecting API routes
+ * Permissions utility for role-based access control
  *
- * Supports multiple authentication types:
- * - Super admin token (signed with ENCRYPTION_KEY)
- * - User session token (validated against DurableAgentBuilder)
- * - API key (validated against DurableAgentBuilder)
- */
-interface AuthUser {
-    id: string;
-    username: string;
-    /** 'admin' | 'user' | 'api' (API-only: normal API access, no UI, no logs). */
-    role: string;
-    /**
-     * Explicit permission grants (e.g. 'logs'). `null`/absent = legacy row with
-     * no explicit set — see {@link hasPermission} for the fallback rules.
-     */
-    permissions?: string[] | null;
-    platform_user_id?: string | null;
-    email?: string | null;
-    display_name?: string | null;
-    avatar_url?: string | null;
-}
-interface AuthContext {
-    user: AuthUser;
-    authType: 'super_admin' | 'session' | 'api_key';
-}
-/**
- * Authenticate a request using various token types
+ * Current behavior:
+ * - Admin role can do everything (early return true)
+ * - Other roles only get baseline access (own threads)
+ *
+ * The `can()` function checks arbitrary permission strings.
+ * Currently, non-admin users have no explicit permissions,
+ * meaning they rely on ownership checks for access.
  */
-declare function authenticate(request: Request, env: any): Promise<AuthContext | null>;
+
 /**
- * Middleware to require authentication
- * Returns 401 if not authenticated
+ * Check if a user can access a specific thread
+ *
+ * @param auth - The authenticated user context
+ * @param thread - The thread to check access for (must have user_id)
+ * @returns true if the user can access the thread
  */
-declare function requireAuth(request: Request, env: any): Promise<AuthContext | Response>;
+declare function canAccessThread(auth: AuthContext, thread: {
+    user_id: string | null;
+}): boolean;
+
+/** Central API exposure policy shared by the generated Worker router and tests. */
+declare function isHostedInstance(env: Record<string, unknown> | undefined): boolean;
 /**
- * Middleware to require admin role
- * Returns 401 if not authenticated, 403 if not admin
+ * Local-only conveniences are enabled by the request destination, not merely
+ * by the absence of a deployment flag. This makes an incorrectly configured
+ * internet-facing Worker fail closed while preserving localhost and OrbStack.
  */
-declare function requireAdmin(request: Request, env: any): Promise<AuthContext | Response>;
+declare function isTrustedLocalDevelopmentRequest(request: Request, env: Record<string, unknown> | undefined): boolean;
+declare function isPublicApiRoute(routePath: string, request: Request, env: Record<string, unknown> | undefined): boolean;
+/** Instance-global authoring and package-management surfaces are admin-only. */
+declare function isAdminOnlyApiRoute(routePath: string, method?: string): boolean;
 
 type AlarmQueueStatus = "pending" | "processing" | "completed" | "failed" | "agent_canceled" | "user_canceled";
 type EffectCancelSource = "agent" | "user";
@@ -168,6 +161,24 @@ interface EffectRunActionResult {
     replayedId?: string;
 }
 
+interface RuntimeSafetyStatus {
+    state: 'active' | 'quarantined';
+    reason: string | null;
+    source: string | null;
+    trippedAt: number | null;
+    resumedAt: number | null;
+    forensicHold: boolean;
+    lastActionId: string | null;
+    observed: Record<string, number>;
+}
+interface RuntimeQuarantineInput {
+    actionId: string;
+    reason: string;
+    source?: string;
+    forensicHold?: boolean;
+    observed?: Record<string, number>;
+}
+
 interface CodeExecutionBridgeRegistration {
     call(functionId: string, encodedArgs: unknown[]): Promise<unknown>;
 }
@@ -209,6 +220,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
     private pendingClientCalls;
     private clientStreams;
     private alarmQueue;
+    private runtimeSafety;
     private alarmQueueRearmed;
     private currentAbortController;
     private isExecuting;
@@ -644,7 +656,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * "Working" spinner. Used by the FlowEngine's terminal catch and the parked
      * forwarded-call TTL.
      */
-    settleTerminalFailure(errorMessage: string): Promise<void>;
+    settleTerminalFailure(errorMessage: string, threadId?: string): Promise<void>;
     stop(): Promise<Response>;
     /**
      * Continue execution from where it stopped (RPC method)
@@ -1140,6 +1152,18 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * historical accept-anything delivery for old CLIs.
      */
     private sendClientToolRequest;
+    /**
+     * The delivered result of a parked forwarded call, if the client has
+     * already resolved it — lets the approval-park path grace-wait briefly and
+     * return the REAL result inline instead of a "⏳ Awaiting your approval…"
+     * placeholder. Instant auto-accepts (the common case: the client's saved
+     * permission level covers the call) otherwise race the placeholder into
+     * stored history, leaving the model blind to its own tool outcomes.
+     */
+    getDeliveredClientToolResult(toolCallId: string): Promise<{
+        content: string;
+        toolStatus: string | null;
+    } | null>;
     /** Still-pending durable forwarded calls (for re-sending after a reconnect). */
     getPendingClientCalls(): Promise<Array<{
         toolCallId: string;
@@ -1228,6 +1252,17 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * Filters silent messages based on each socket's includeSilent preference
      */
     private broadcastMessage;
+    /**
+     * The FlowEngine's message emit path: broadcast the record, and stamp
+     * message recency when it is the thread's visible terminal assistant reply.
+     *
+     * This is the frame a client's reducer consumes to retire its provisional
+     * draft, so it is the one place where "the user has something new to read"
+     * is known. The stamp deliberately does NOT carry a preview: previews are
+     * row labels and stay keyed to the user's own message, while recency has to
+     * follow the agent's reply.
+     */
+    private emitFlowMessage;
     private broadcastMessageWithSubagentProjection;
     /**
      * Broadcast a content chunk for real-time streaming
@@ -1277,6 +1312,16 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * the alarm chain. All errors are caught and logged.
      */
     alarm(): Promise<void>;
+    /** Persist a reversible emergency stop without scanning or deleting thread data. */
+    emergencyQuarantine(input: RuntimeQuarantineInput): Promise<RuntimeSafetyStatus>;
+    /** Return the low-cost quarantine status used by Brolly and diagnostics. */
+    getRuntimeSafetyStatus(): Promise<RuntimeSafetyStatus>;
+    /** Resume only through an explicit idempotent action; forensic holds need release. */
+    emergencyResume(input: {
+        actionId: string;
+        reason: string;
+        releaseForensicHold?: boolean;
+    }): Promise<RuntimeSafetyStatus>;
     /** Heartbeat: called by LLMRequest on each attempt and streamed chunk. */
     noteExecutionProgress(): void;
     /**
@@ -1344,6 +1389,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
         watchdogStrikes: number;
         watchdogCeilingMs: number;
         stopped: boolean;
+        runtimeSafety: RuntimeSafetyStatus;
         incompleteLogs: Array<{
             id: string;
             model: string | null;
@@ -1873,7 +1919,24 @@ interface ThreadRegistryEntry {
     executing?: boolean;
     /** Short excerpt of the most recent user message, for thread-list rows. */
     last_message_preview?: string | null;
+    /**
+     * Unix seconds of the newest VISIBLE MESSAGE on this thread — the one field
+     * clients key unread indicators on. It moves when a non-empty user (or
+     * operator assistant-role) message arrives, and when a visible terminal
+     * assistant record lands (`isVisibleTerminalAssistantMessage`): terminal
+     * answers, attachment-only replies, and failed rows with visible text — but
+     * never mid-turn tool-calling steps, silent rows, sub-prompt records, or
+     * background execution activity (which move only `last_activity_at`).
+     * Monotonic per thread and never propagated to ancestors.
+     */
+    last_message_at?: number | null;
 }
+/**
+ * Safe registry projection carried by system events. Thread env and arbitrary
+ * properties are intentionally excluded: the stream is an invalidation/list
+ * surface, not a second transport for thread configuration or secrets.
+ */
+type ThreadEventPayload = Pick<ThreadRegistryEntry, 'id' | 'agent_name' | 'origin_agent_name' | 'user_id' | 'tags' | 'parent' | 'terminated' | 'created_at' | 'last_activity_at' | 'executing' | 'last_message_preview' | 'last_message_at'>;
 interface PendingSubagentAttachmentRef {
     path: string;
     name?: string;
@@ -1981,6 +2044,77 @@ interface Provider$1 {
     sdk: string;
     api_key: string;
 }
+/**
+ * Lightweight agent metadata included with real-time thread events.
+ */
+interface ThreadEventAgent {
+    name: string;
+    title: string;
+    type: string;
+    description?: string;
+    icon?: string;
+}
+/**
+ * DurableAgentBuilder - The root Durable Object for AgentBuilder.
+ *
+ * This is a singleton DO that stores:
+ * - Thread registry (maps thread IDs to agent names)
+ * - User authentication data
+ * - Provider credentials (API keys for LLM providers)
+ * - Edit lock state for coordinated edits
+ *
+ * ## Usage
+ *
+ * Users must extend this class to provide virtual module access:
+ *
+ * ```typescript
+ * import { DurableAgentBuilder } from '@standardagents/builder/runtime';
+ * import { models } from 'virtual:@standardagents-models';
+ * import { prompts } from 'virtual:@standardagents-prompts';
+ * import { agents } from 'virtual:@standardagents-agents';
+ *
+ * export class AgentBuilder extends DurableAgentBuilder {
+ *   models() { return models; }
+ *   prompts() { return prompts; }
+ *   agents() { return agents; }
+ * }
+ * ```
+ */
+/**
+ * Event types that can be emitted via WebSocket
+ */
+type AgentBuilderEvent = {
+    type: 'thread_created';
+    thread: ThreadEventPayload & {
+        agent?: ThreadEventAgent;
+    };
+} | {
+    type: 'thread_updated';
+    thread: ThreadEventPayload & {
+        agent?: ThreadEventAgent;
+    };
+} | {
+    type: 'thread_deleted';
+    threadId: string;
+}
+/**
+ * Lightweight activity signal. Kept separate from `thread_updated` because it
+ * fires on every execution start/stop: re-broadcasting the whole registry
+ * entry would decrypt thread env on each transition for data that never
+ * changed.
+ */
+ | {
+    type: 'thread_activity';
+    threadId: string;
+    /** Present only when this event actually wrote the field: a message-only
+     *  recency stamp omits last_activity_at, and `executing` rides only on a
+     *  real transition — clients must leave their current value alone for
+     *  absent fields. */
+    last_activity_at?: number;
+    executing?: boolean;
+    last_message_preview?: string | null;
+    last_message_at?: number | null;
+};
 /** Sort orders supported by `listThreads`. */
 type ThreadListSort = 'activity' | 'created' | 'oldest';
 declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv> extends DurableObject<Env> {
@@ -2131,6 +2265,7 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
     recordThreadActivity(threadId: string, options?: {
         executing?: boolean;
         messagePreview?: string | null;
+        messageAt?: number;
     }): Promise<void>;
     /**
      * Fill in previews for threads that predate preview tracking. Callers read
@@ -2503,9 +2638,11 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
      */
     broadcastThreadUpdated(threadId: string): Promise<void>;
     /**
-     * Broadcast an event to all connected WebSocket clients
+     * Broadcast an event only to its owner or an explicitly all-scoped admin.
      */
     private broadcastEvent;
+    /** Resolve a thread owner without decrypting its env or loading the row. */
+    private getThreadOwnerId;
     /**
      * WebSocket Hibernation API handler for incoming messages
      * Called when a message is received on a hibernated WebSocket
@@ -4126,4 +4263,4 @@ declare function createNamespaceContext(agentDef: {
  */
 declare function isQualifiedName(name: string): boolean;
 
-export { Agent, type AgentBuilderEnv, type AgentDefinition, AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, ClientStreamRequest, ClientStreamResponse, ClientToolRequest, ClientToolResponse, CodeExecutionBridge, DurableAgentBuilder, DurableThread, DurableUserHub, Env, FileRecord, FileStats, FlowState, FlowStateSdk, type FlowStateWithSdk, GrepResult, type HubClientInfo, type ImageContextConfig, type InjectMessageOptions$1 as InjectMessageOptions, type Provider as LLMProviderInterface, Message, MessageContent, type ModelDefinition, NamespaceResolutionError, NamespacedRegistry, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptPart, type PromptToolConfig, type Provider$1 as Provider, type ProviderContentPart, type ProviderFilePart, type ProviderImagePart, ProviderRegistry, type ProviderTextPart, type SessionToolBinding, type SessionToolConfig, type SideConfig, type SubagentToolConfig, type SubpromptConfig, ThreadEnv, ThreadInstance, ThreadMetadata, type ThreadRegistryEntry, ThreadWatchdog, type ThreadWatchdogState, type ToolConfig, ToolResult, type UpdateThreadParams, type User, type WatchdogCheckin, type WatchdogProbeResult, authenticate, buildImageDescription, cat, createNamespaceContext, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateImageDescription, getFileStats, getMessages, getMessagesToSummarize, getShortName, getThumbnail, getUnsummarizedImageAttachments, getVisibleAgentNames, getVisibleModelNames, getVisiblePromptNames, getVisibleToolNames, grep, hasImageAttachments, head, injectMessage, isQualifiedName, linkFile, mkdir, move, optimizeImageContext, parseQualifiedName, qualifyName, queueTool, readFile, readdir, reloadHistory, rename, replaceImagesWithDescriptions, requireAdmin, requireAuth, resolveAgent, resolveHook, resolveModel, resolvePrompt, resolveTool, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };
+export { Agent, type AgentBuilderEnv, type AgentBuilderEvent, type AgentDefinition, AttachmentRef, AuthContext, type BroadcastOptions, ClientStreamRequest, ClientStreamResponse, ClientToolRequest, ClientToolResponse, CodeExecutionBridge, DurableAgentBuilder, DurableThread, DurableUserHub, Env, FileRecord, FileStats, FlowState, FlowStateSdk, type FlowStateWithSdk, GrepResult, type HubClientInfo, type ImageContextConfig, type InjectMessageOptions$1 as InjectMessageOptions, type Provider as LLMProviderInterface, Message, MessageContent, type ModelDefinition, NamespaceResolutionError, NamespacedRegistry, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptPart, type PromptToolConfig, type Provider$1 as Provider, type ProviderContentPart, type ProviderFilePart, type ProviderImagePart, ProviderRegistry, type ProviderTextPart, type SessionToolBinding, type SessionToolConfig, type SideConfig, type SubagentToolConfig, type SubpromptConfig, ThreadEnv, type ThreadEventPayload, ThreadInstance, ThreadMetadata, type ThreadRegistryEntry, ThreadWatchdog, type ThreadWatchdogState, type ToolConfig, ToolResult, type UpdateThreadParams, type User, type WatchdogCheckin, type WatchdogProbeResult, buildImageDescription, canAccessThread, cat, createNamespaceContext, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateImageDescription, getFileStats, getMessages, getMessagesToSummarize, getShortName, getThumbnail, getUnsummarizedImageAttachments, getVisibleAgentNames, getVisibleModelNames, getVisiblePromptNames, getVisibleToolNames, grep, hasImageAttachments, head, injectMessage, isAdminOnlyApiRoute, isHostedInstance, isPublicApiRoute, isQualifiedName, isTrustedLocalDevelopmentRequest, linkFile, mkdir, move, optimizeImageContext, parseQualifiedName, qualifyName, queueTool, readFile, readdir, reloadHistory, rename, replaceImagesWithDescriptions, resolveAgent, resolveHook, resolveModel, resolvePrompt, resolveTool, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };