@standardagents/builder 0.25.6 → 0.26.0

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
-import { e as ThreadEnv, A as Agent, h as ThreadMetadata, i as ToolResult, M as Message, l as FileRecord, F as FlowState, n as FileStats, G as GrepResult, m as AttachmentRef, r as MessageContent, E as Env, g as ThreadInstance } from './index-CX9Ti98s.js';
-export { f as BuilderThreadEndpointHandler, B as Controller, a as ControllerContext, j as FlowResult, p as ImageContentPart, I as ImageMetadata, L as LLMResponse, q as MultimodalContent, R as RequestContext, S as StorageBackend, k as TelemetryEvent, o as TextContentPart, b as ThreadEndpointContext, T as ToolCall, c as createThreadEndpointHandler, d as defineController } from './index-CX9Ti98s.js';
+import { e as ThreadEnv, A as Agent, h as ThreadMetadata, i as ToolResult, M as Message, l as FileRecord, F as FlowState, n as FileStats, G as GrepResult, m as AttachmentRef, r as MessageContent, E as Env, g as ThreadInstance } from './index-DJ7B8CTp.js';
+export { f as BuilderThreadEndpointHandler, B as Controller, a as ControllerContext, j as FlowResult, p as ImageContentPart, I as ImageMetadata, L as LLMResponse, q as MultimodalContent, R as RequestContext, S as StorageBackend, k as TelemetryEvent, o as TextContentPart, b as ThreadEndpointContext, T as ToolCall, c as createThreadEndpointHandler, d as defineController } from './index-DJ7B8CTp.js';
 import { CodeExecutionOptions, CodeExecutionResult, SubagentRegistryEntry, InjectMessageInput, QueueMessageInput, ClientToolRequest, ClientToolResponse, 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, 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';
@@ -173,6 +173,31 @@ interface CodeExecutionBridgeRegistration {
 }
 
 type ThreadEndpointCodeOptions = Pick<CodeExecutionOptions, "language" | "filename" | "execute" | "modules" | "memoryLimitBytes">;
+/**
+ * Result of one watchdog assessment (see performWatchdogAssessment). Returned
+ * to whichever delivery invoked it — the internal alarm check, the
+ * ThreadWatchdog companion probe, or the diagnostics revive endpoint — so the
+ * caller can schedule/record without re-deriving thread state.
+ */
+interface WatchdogProbeResult {
+    /** What the thread looked like, after any recovery action taken. */
+    verdict: "healthy" | "observing" | "recovered" | "parked" | "idle";
+    /** The recovery action performed (all actions are already done on return). */
+    action: "none" | "finalized_resumed" | "finalized_parked" | "finalized_deferred" | "aborted_takeover_resumed";
+    executing: boolean;
+    incompleteLogs: number;
+    queuedMessages: number;
+    /** Milliseconds since the last execution heartbeat; null when unknown/∞. */
+    silenceMs: number | null;
+    ceilingMs: number;
+    strikes: number;
+    /**
+     * True when a live-but-wedged executor was taken over: the zombie turn may
+     * still own this DO's alarm invocation, so the caller should force a
+     * restart (ThreadWatchdog calls forceRestart()) to free the alarm chain.
+     */
+    requestRestart: boolean;
+}
 declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableObject<Env> {
     private migratedToVersion;
     private logSockets;
@@ -607,7 +632,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * @param includeSilent Include silent messages (UI-only messages)
      * @param maxDepth Maximum depth to include (default: 0 for top-level only)
      */
-    getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC", includeSilent?: boolean, maxDepth?: number): Promise<{
+    getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC" | "asc" | "desc", includeSilent?: boolean, maxDepth?: number): Promise<{
         messages: {
             id: string;
             role: string;
@@ -1087,15 +1112,82 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
     alarm(): Promise<void>;
     /** Heartbeat: called by LLMRequest on each attempt and streamed chunk. */
     noteExecutionProgress(): void;
+    /**
+     * The per-thread companion watchdog DO (ThreadWatchdog), derived from the
+     * thread id. It exists because this thread's OWN alarm cannot fire while a
+     * queue-dispatched turn runs inside alarm() — the companion delivers the
+     * same check via RPC, which interleaves at await points even mid-turn.
+     * Returns null on deployments whose generated config predates the binding.
+     */
+    private watchdogCompanion;
     /** Arm the standing watchdog for an execution start. One pending row max. */
     private armExecutionWatchdog;
     /** Disarm on clean execution end. Completed check rows are noise, not history. */
     private disarmExecutionWatchdog;
     /**
-     * The standing check. Evaluates the thread's state AT FIRE TIME — it knows
-     * nothing about whichever request was in flight when it was armed.
+     * The standing check, alarm-queue delivery. Evaluates the thread's state AT
+     * FIRE TIME — it knows nothing about whichever request was in flight when it
+     * was armed. NOTE this delivery path cannot fire while a queue-dispatched
+     * turn runs (the turn owns this DO's single alarm invocation); the
+     * ThreadWatchdog companion delivers the same assessment via watchdogProbe()
+     * in exactly that window.
      */
     private watchdogCheck;
+    /**
+     * RPC delivery of the standing check — called by the ThreadWatchdog
+     * companion (and the diagnostics revive endpoint). Runs in a fresh request
+     * context, so it interleaves with a running turn at await points and its
+     * own awaits/timers are alive even when a wedged turn's context is frozen.
+     * Does NOT touch the internal watchdogCheck alarm rows — those belong to
+     * the alarm delivery path.
+     */
+    watchdogProbe(threadId: string): Promise<WatchdogProbeResult>;
+    /**
+     * Reset this Durable Object instance on request. Used by the watchdog
+     * companion after a wedged-executor takeover: the zombie turn may still own
+     * this DO's single alarm invocation, which would block the just-enqueued
+     * recovery alarm forever. Aborting guarantees a fresh instance whose alarm
+     * chain re-arms from persisted queue state on first wake.
+     */
+    forceRestart(reason: string): Promise<void>;
+    /**
+     * Execution-health snapshot for the diagnostics endpoint and `agents diag`.
+     * Exposes the state the 2026-07-08 post-mortem could not see from outside:
+     * the alarm queue (was a turn item pending/processing/failed? was the
+     * watchdog row gone?), the volatile execution flags, and open request logs.
+     * Read-only; safe to call at any time.
+     */
+    getDiagnostics(): Promise<{
+        executing: boolean;
+        lastProgressAt: number | null;
+        silenceMs: number | null;
+        watchdogStrikes: number;
+        watchdogCeilingMs: number;
+        stopped: boolean;
+        incompleteLogs: Array<{
+            id: string;
+            model: string | null;
+            provider: string | null;
+            created_at: number;
+        }>;
+        alarmQueue: Array<{
+            id: string;
+            method: string;
+            status: string;
+            scheduled_at: number;
+            created_at: number;
+            attempts: number;
+            error: string | null;
+        }>;
+        messageQueueCount: number;
+        contextUsage: Record<string, unknown> | null;
+    }>;
+    /**
+     * The shared watchdog decision core. Both deliveries (alarm + companion
+     * probe) evaluate and ACT through this method; the caller only decides what
+     * to do with its own scheduling based on the verdict.
+     */
+    private performWatchdogAssessment;
     /** Mark logs the dead executor abandoned, and tell connected clients. */
     private finalizeLostExecutionLogs;
     /**
@@ -2102,6 +2194,92 @@ declare class CodeExecutionBridge extends WorkerEntrypoint<ThreadEnv, CodeExecut
     call(threadId: string, runId: string, functionId: string, encodedArgs: unknown[]): Promise<unknown>;
 }
 
+/**
+ * ThreadWatchdog — a per-thread companion Durable Object whose only job is to
+ * deliver liveness checks INTO a DurableThread on a schedule the thread cannot
+ * starve.
+ *
+ * Why this exists (2026-07-08 incident, api.standardcode.ai): every normal
+ * turn is dispatched through the thread's own AlarmQueue and runs INSIDE its
+ * alarm() handler. Cloudflare serializes alarm invocations per object and the
+ * queue only re-arms the storage alarm after the current item finishes — so
+ * while a turn runs, the thread's own standing `watchdogCheck` alarm rows are
+ * inert. When a provider request wedged (zero bytes for 18+ minutes, in-flight
+ * stall-guard timers frozen with the turn's context), nothing could fire: the
+ * thread sat "working" forever, and the user's UI polling kept the instance
+ * resident, which is exactly what prevented fresh-instance wake recovery.
+ * A manual RPC delivery of the same check recovered the thread in one call —
+ * the LOGIC was sound, the DELIVERY was starved. This object is that delivery.
+ *
+ * Design rules:
+ * - The alarm handler stays tiny: one probe RPC + reschedule. It must never
+ *   run long work, so it can never starve itself the way thread turns do.
+ * - Reschedule-first: the next alarm is set before the probe runs, so a crash
+ *   mid-probe never kills the chain.
+ * - Parent-child lifecycle is explicit (Cloudflare has no cascade): the
+ *   companion is created lazily by the thread's execution start (`arm`),
+ *   stands itself down when the thread probes clean, and is destroyed by
+ *   `DurableThread.deleteThread()`/`terminateThread()`. Standing down keeps
+ *   the check-in history (the UI reads it) but drops the alarm — a DO with no
+ *   alarm and no traffic hibernates at zero cost.
+ * - Probe timeouts are counted, not fatal: a thread DO whose input gate is
+ *   permanently blocked cannot be revived at the application layer, so after
+ *   MAX_UNREACHABLE consecutive timeouts the companion logs loudly and stands
+ *   down instead of ticking forever.
+ */
+/** One recorded check-in, newest first in storage. */
+interface WatchdogCheckin {
+    at: number;
+    /** Thread verdict, or 'unreachable' when the probe itself failed/timed out. */
+    verdict: "healthy" | "observing" | "recovered" | "parked" | "idle" | "unreachable";
+    /** What the probe did, for the UI's determination column. */
+    action: string;
+    executing: boolean | null;
+    incompleteLogs: number | null;
+    silenceMs: number | null;
+    probeMs: number;
+    error?: string;
+}
+interface ThreadWatchdogState {
+    armed: boolean;
+    threadId: string | null;
+    armedAt: number | null;
+    history: WatchdogCheckin[];
+}
+interface ThreadWatchdogEnv {
+    AGENT_BUILDER_THREAD: {
+        idFromName(name: string): unknown;
+        get(id: unknown): unknown;
+    };
+    [key: string]: unknown;
+}
+declare class ThreadWatchdog extends DurableObject<ThreadWatchdogEnv> {
+    /**
+     * Arm (or re-arm) the standing check for a thread execution. Idempotent —
+     * called at every execution start. Resets the unreachable counter because a
+     * fresh arm proves the thread is answering RPCs right now.
+     */
+    arm(threadId: string): Promise<void>;
+    /**
+     * Hint that the thread believes its execution ended cleanly. The companion
+     * does NOT trust this (a bogus "clean end" was one of the incident's failure
+     * modes) — it just moves the next check close so a genuinely clean thread
+     * stands down in seconds instead of a full cadence.
+     */
+    disarmHint(): Promise<void>;
+    /** Diagnostics view for the thread inspector UI and the diag CLI. */
+    getState(): Promise<ThreadWatchdogState>;
+    /**
+     * Explicit cascade from the parent thread (delete/terminate). Cloudflare
+     * has no automatic parent-child cleanup — this IS the cleanup.
+     */
+    destroy(): Promise<void>;
+    alarm(): Promise<void>;
+    private getThreadStub;
+    private probeThread;
+    private recordCheckin;
+}
+
 /**
  * Model definition module for AgentBuilder.
  *
@@ -3538,4 +3716,4 @@ declare function createNamespaceContext(agentDef: {
  */
 declare function isQualifiedName(name: string): boolean;
 
-export { Agent, type AgentBuilderEnv, type AgentDefinition, AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, CodeExecutionBridge, DurableAgentBuilder, DurableThread, Env, FileRecord, FileStats, FlowState, FlowStateSdk, type FlowStateWithSdk, GrepResult, 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, type ToolConfig, ToolResult, type UpdateThreadParams, type User, 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 AgentDefinition, AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, CodeExecutionBridge, DurableAgentBuilder, DurableThread, Env, FileRecord, FileStats, FlowState, FlowStateSdk, type FlowStateWithSdk, GrepResult, 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 };