@standardagents/builder 0.27.12 → 0.28.0

package/dist/{index-DReIS8eP.d.ts → index-BzXyIJPA.d.ts}

@@ -1,7 +1,7 @@
 import { DurableObjectStorage } from '@cloudflare/workers-types';
 import { ZodObject, ZodRawShape } from 'zod';
 import { N as NamespacedRegistry } from './types-Bpe7IANZ.js';
-import { ToolResult as ToolResult$1, VariableDefinition, HookName, HookSignatures, ThreadState, HookMessage, HookToolCall, HookToolResult, ClientToolRequest, ClientToolResponse, CodeExecutionOptions, CodeExecutionResult, InjectMessageInput, QueueMessageInput, SubagentRegistryEntry, ProviderUsagePricing, AgentDefinition, SkillMetadata, SkillFileInput, ControllerContext, Controller, ThreadEndpointHandler } from '@standardagents/spec';
+import { ThreadState, ToolResult as ToolResult$1, VariableDefinition, HookName, HookSignatures, HookMessage, HookToolCall, HookToolResult, CodeExecutionOptions, CodeExecutionResult, InjectMessageInput, QueueMessageInput, SubagentRegistryEntry, ProviderUsagePricing, AgentDefinition, SkillMetadata, SkillFileInput, ControllerContext, Controller, ThreadEndpointHandler } from '@standardagents/spec';
 
 /**
  * Callback function to execute before stream closes
@@ -76,6 +76,132 @@ declare class StreamManager {
     forceClose(): void;
 }
 
+/**
+ * Client-tool forwarding — a BUILDER capability, not a spec surface.
+ *
+ * The Standard Agent Specification has no "client" concept: agents, prompts,
+ * hooks, and tools are defined against spec surfaces only. But tools are
+ * arbitrary code and may call anything — including this builder API, which
+ * forwards an operation over the thread's `bridge` WebSocket to a connected
+ * client (a CLI or machine daemon) for local execution. Products built on
+ * AgentBuilder (e.g. Standard Code) import these types and entry points from
+ * `@standardagents/builder`.
+ */
+/**
+ * A request forwarded from a server-side tool to a connected client (CLI or
+ * machine daemon) for local execution. Used by "forwarded" tools where the
+ * agent loop runs remotely but the actual operation (read a file, run a
+ * command) must happen on the user's own machine.
+ */
+interface ClientToolRequest {
+    /** Logical operation name the client knows how to perform (e.g. `read_file`). */
+    tool: string;
+    /** Arguments for the operation. */
+    args?: Record<string, unknown>;
+    /**
+     * Human-readable description of what this call will do, shown to the user when
+     * the client needs to ask for permission. Presence signals the operation may
+     * carry side effects.
+     */
+    requestPermission?: string;
+    /** Risk level 1 (safe) – 5 (dangerous). Clients slide auto-accept on this. */
+    risk?: number;
+    /** Milliseconds to wait for the client before failing the call. */
+    timeoutMs?: number;
+}
+/**
+ * The result a connected client returns for a {@link ClientToolRequest}.
+ */
+interface ClientToolResponse {
+    /** Whether the client successfully performed the operation. */
+    ok: boolean;
+    /** Text result (e.g. file contents, command output). */
+    result?: string;
+    /** Error message when `ok` is false (including a user denial). */
+    error?: string;
+    /** Optional structured payload the tool can inspect. */
+    data?: unknown;
+}
+/**
+ * A request to open a bidirectional byte stream to the connected client.
+ *
+ * The client interprets `tool` + `meta` (e.g. `tcp_tunnel` with
+ * `{ host, port }` opens a raw TCP socket and shuttles bytes both ways).
+ * Payload bytes are opaque to the transport — for a TLS tunnel the client
+ * only ever relays ciphertext.
+ */
+interface ClientStreamRequest {
+    /** Client stream capability name (e.g. `tcp_tunnel`). */
+    tool: string;
+    /** Opaque per-stream configuration delivered to the client verbatim. */
+    meta?: Record<string, unknown>;
+    /** Milliseconds to wait for the client to accept the stream. */
+    timeoutMs?: number;
+}
+/**
+ * A live bidirectional byte pipe between the thread runtime and the client.
+ *
+ * `readable` carries bytes FROM the client; `writable` carries bytes TO the
+ * client. `close()` tears the stream down on both sides (mapped to the
+ * `stream_abort` frame); `done` settles when the client reports the stream
+ * finished or failed.
+ */
+interface ClientDuplex {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    /** Abort the stream on both sides. */
+    close(error?: string): void;
+    /** Settles when the stream fully ends (either side) or errors. */
+    done: Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+}
+type ClientStreamResponse = {
+    ok: true;
+    duplex: ClientDuplex;
+} | {
+    ok: false;
+    error: string;
+    data?: unknown;
+};
+/**
+ * The builder-only forwarding surface implemented by `ThreadStateImpl`.
+ * The spec `ThreadState` deliberately does not declare these members.
+ */
+interface ClientForwarding {
+    callClient(request: ClientToolRequest): Promise<ClientToolResponse>;
+    callClientStream(request: ClientStreamRequest): Promise<ClientStreamResponse>;
+}
+/** Whether this runtime's ThreadState supports client-tool forwarding. */
+declare function supportsClientForwarding(state: ThreadState): state is ThreadState & ClientForwarding;
+/**
+ * Forward a tool operation to the connected client and await its result.
+ *
+ * Resolves with `{ ok: false, error }` (rather than throwing) when no client
+ * is connected, the request times out, or the user denies permission, so
+ * forwarded tools can surface a normal tool error to the model.
+ *
+ * When the executing client is unreachable, the call parks durably on the
+ * thread and resumes when a client re-attaches (drain-on-attach) — the caller
+ * receives a deferred placeholder result and the turn suspends instead of
+ * failing.
+ */
+declare function callClient(state: ThreadState, request: ClientToolRequest): Promise<ClientToolResponse>;
+/**
+ * Open a bidirectional byte stream to the connected client (e.g. a raw TCP
+ * tunnel for Worker-side TLS termination). Requires a live bridge socket on
+ * this thread — streams never park durably.
+ */
+declare function callClientStream(state: ThreadState, request: ClientStreamRequest): Promise<ClientStreamResponse>;
+/** Maximum raw bytes per `stream_data` frame (base64 expands ~4/3 on the wire;
+ *  Cloudflare caps WebSocket frames at 1 MiB). */
+declare const CLIENT_STREAM_CHUNK_BYTES: number;
+/** Encode a chunk of raw bytes for a `stream_data` frame. */
+declare function encodeStreamChunk(bytes: Uint8Array): string;
+/** Decode a `stream_data` frame payload back into raw bytes. */
+declare function decodeStreamChunk(data: string): Uint8Array;
+
 /**
  * Agent configuration from D1 agents table
  */
@@ -264,6 +390,14 @@ interface ThreadInstance {
     setValue(key: string, value: unknown): Promise<void>;
     emitThreadEvent?(threadId: string, event: string, data: unknown): void | Promise<void>;
     callClientTool?(request: ClientToolRequest): Promise<ClientToolResponse>;
+    openClientStream?(request: ClientStreamRequest): Promise<ClientStreamResponse>;
+    dispatchClientTool?(request: ClientToolRequest, toolCallId: string, side: "a" | "b"): Promise<{
+        dispatched: boolean;
+    }>;
+    hasBridge?(): Promise<boolean>;
+    failPendingMessagesAndBroadcast?(): Promise<number>;
+    settleTerminalFailure?(errorMessage: string): Promise<void>;
+    notifyClientWaiting?(toolCallId: string, threadId: string, userId: string | null): Promise<void>;
     registerCodeExecutionBridge?(runId: string, bridge: {
         call(functionId: string, encodedArgs: unknown[]): Promise<unknown>;
     }): void;
@@ -1230,6 +1364,31 @@ interface ThreadWatchdogRpc {
         }>;
     }>;
 }
+/**
+ * RPC methods exposed by the DurableUserHub per-user companion Durable Object.
+ */
+interface DurableUserHubRpc {
+    hasClient(): Promise<boolean>;
+    requestWake(threadId: string): Promise<{
+        delivered: boolean;
+    }>;
+    getUserValue(userId: string, key: string): Promise<unknown | null>;
+    setUserValue(userId: string, key: string, value: unknown): Promise<void>;
+    listUserValues(userId: string, options?: {
+        prefix?: string | null;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        entries: Array<{
+            key: string;
+            value: unknown;
+            updated_at: number;
+        }>;
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+}
 /**
  * Thread registry entry from DurableAgentBuilder.
  */
@@ -1454,6 +1613,8 @@ interface ThreadEnv {
     AGENT_BUILDER: DurableObjectNamespace<DurableAgentBuilderRpc>;
     /** Optional: deployments generated before 0.26.0 lack this binding. */
     AGENT_BUILDER_WATCHDOG?: DurableObjectNamespace<ThreadWatchdogRpc>;
+    /** Optional: deployments generated before the per-user hub lack this binding. */
+    AGENT_BUILDER_USER_HUB?: DurableObjectNamespace<DurableUserHubRpc>;
     [key: string]: unknown;
 }
 /**
@@ -1535,4 +1696,4 @@ declare function defineController<Env extends ThreadEnv = ThreadEnv>(controller:
  */
 declare function createThreadEndpointHandler<Env extends ThreadEnv = ThreadEnv>(handler: ThreadEndpointHandler): BuilderController<Env>;
 
-export { type Agent as A, type BuilderController as B, type Env as E, type FlowState as F, type GrepResult as G, type ImageMetadata as I, type LLMResponse as L, type Message as M, type RequestContext as R, type StorageBackend as S, type ToolCall as T, type BuilderControllerContext as a, type ThreadEndpointContext as b, createThreadEndpointHandler as c, defineController as d, type ThreadEnv as e, type BuilderThreadEndpointHandler as f, type ThreadInstance as g, type ThreadMetadata as h, type ToolResult as i, type FlowResult as j, type TelemetryEvent as k, type FileRecord as l, type AttachmentRef as m, type FileStats as n, type TextContentPart as o, type ImageContentPart as p, type MultimodalContent as q, type MessageContent as r };
+export { type Agent as A, type BuilderController as B, CLIENT_STREAM_CHUNK_BYTES as C, type ImageContentPart as D, type Env as E, type FlowState as F, type GrepResult as G, type MultimodalContent as H, type ImageMetadata as I, type MessageContent as J, type LLMResponse as L, type Message as M, type RequestContext as R, type StorageBackend as S, type ToolCall as T, type BuilderControllerContext as a, type ThreadEndpointContext as b, createThreadEndpointHandler as c, defineController as d, type ThreadEnv as e, type BuilderThreadEndpointHandler as f, callClient as g, callClientStream as h, encodeStreamChunk as i, decodeStreamChunk as j, type ClientToolRequest as k, type ClientToolResponse as l, type ClientStreamRequest as m, type ClientStreamResponse as n, type ClientDuplex as o, type ClientForwarding as p, type ThreadInstance as q, type ThreadMetadata as r, supportsClientForwarding as s, type ToolResult as t, type FlowResult as u, type TelemetryEvent as v, type FileRecord as w, type AttachmentRef as x, type FileStats as y, type TextContentPart as z };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ModelDefinition, AgentDefinition } from './runtime.js';
-export { AgentBuilderEnv, AuthContext, AuthUser, BroadcastOptions, CodeExecutionBridge, DurableAgentBuilder, DurableThread, FlowStateSdk, FlowStateWithSdk, ImageContextConfig, InjectMessageOptions, LLMProviderInterface, NamespaceResolutionError, PromptContent, PromptDefinition, PromptIncludePart, PromptPart, PromptToolConfig, Provider, ProviderContentPart, ProviderFilePart, ProviderImagePart, ProviderRegistry, ProviderTextPart, SessionToolBinding, SessionToolConfig, SideConfig, SubagentToolConfig, SubpromptConfig, ThreadRegistryEntry, ThreadWatchdog, ThreadWatchdogState, ToolConfig, UpdateThreadParams, User, WatchdogCheckin, 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 } from './runtime.js';
+export { AgentBuilderEnv, AuthContext, AuthUser, BroadcastOptions, CodeExecutionBridge, DurableAgentBuilder, DurableThread, DurableUserHub, FlowStateSdk, FlowStateWithSdk, HubClientInfo, ImageContextConfig, InjectMessageOptions, LLMProviderInterface, NamespaceResolutionError, PromptContent, PromptDefinition, PromptIncludePart, PromptPart, PromptToolConfig, Provider, ProviderContentPart, ProviderFilePart, ProviderImagePart, ProviderRegistry, ProviderTextPart, SessionToolBinding, SessionToolConfig, SideConfig, SubagentToolConfig, SubpromptConfig, ThreadRegistryEntry, ThreadWatchdog, ThreadWatchdogState, ToolConfig, UpdateThreadParams, User, WatchdogCheckin, 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 } from './runtime.js';
 export { AgentPluginOptions, agentbuilder, builder } from './plugin.js';
-export { A as Agent, m as AttachmentRef, f as BuilderThreadEndpointHandler, B as Controller, a as ControllerContext, E as Env, l as FileRecord, n as FileStats, j as FlowResult, F as FlowState, G as GrepResult, p as ImageContentPart, I as ImageMetadata, L as LLMResponse, M as Message, r as MessageContent, q as MultimodalContent, R as RequestContext, S as StorageBackend, k as TelemetryEvent, o as TextContentPart, b as ThreadEndpointContext, e as ThreadEnv, g as ThreadInstance, h as ThreadMetadata, T as ToolCall, i as ToolResult, c as createThreadEndpointHandler, d as defineController } from './index-DReIS8eP.js';
+export { A as Agent, x as AttachmentRef, f as BuilderThreadEndpointHandler, C as CLIENT_STREAM_CHUNK_BYTES, o as ClientDuplex, p as ClientForwarding, m as ClientStreamRequest, n as ClientStreamResponse, k as ClientToolRequest, l as ClientToolResponse, B as Controller, a as ControllerContext, E as Env, w as FileRecord, y as FileStats, u as FlowResult, F as FlowState, G as GrepResult, D as ImageContentPart, I as ImageMetadata, L as LLMResponse, M as Message, J as MessageContent, H as MultimodalContent, R as RequestContext, S as StorageBackend, v as TelemetryEvent, z as TextContentPart, b as ThreadEndpointContext, e as ThreadEnv, q as ThreadInstance, r as ThreadMetadata, T as ToolCall, t as ToolResult, g as callClient, h as callClientStream, c as createThreadEndpointHandler, j as decodeStreamChunk, d as defineController, i as encodeStreamChunk, s as supportsClientForwarding } from './index-BzXyIJPA.js';
 export { AgentType, DefinitionLoader, GlobalNamespaceContext, HookSignatures, ImageContent, ModelCapabilities, ModelProvider, NamespaceContext, PackageSignature, PackedExports, PackedMeta, PackedMetadata, PackedNamespaceContext, PromptInput, PromptTextPart, ProviderAssistantMessage, ProviderConfigSlot, ProviderConfigSlots, ProviderConfigValueSource, ProviderDefinition, ProviderError, ProviderErrorCode, ProviderFactory, ProviderFactoryConfig, ProviderFinishReason, ProviderGeneratedImage, ProviderMessage, ProviderMessageContent, ProviderMethodOverrides, ModelCapabilities as ProviderModelCapabilities, ProviderOverride, ProviderOverrideContext, ProviderReasoningDetail, ProviderRequest, ProviderResponse, ProviderStreamChunk, ProviderSyncOverride, ProviderSystemMessage, ProviderTool, ProviderToolCallPart, ProviderToolMessage, ProviderToolResultContent, ProviderUsage, ProviderUserMessage, ReasoningConfig, StructuredPrompt, TextContent, Tool, ToolArgs, ToolArgsNode, ToolArgsRawShape, ToolContent, belongsToPackage, defineAgent, defineHook, defineModel, definePrompt, defineProvider, defineTool, isPacked, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue } from '@standardagents/spec';
 export { C as ConstituentItem, D as DiscoveredPackage, N as NamespacedRegistry, P as PackingAnalysis, a as PackingOptions, b as PackingResult, c as UnpackOptions, d as UnpackResult } from './types-Bpe7IANZ.js';
 export { D as DiscoveryConfig, P as PackageDiscoveryService, d as discoverPackages } from './discovery-DiMJWisl.js';