@standardagents/builder 0.28.1 → 0.29.1

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

@@ -77,15 +77,11 @@ declare class StreamManager {
 }
 
 /**
- * Client-tool forwarding — a BUILDER capability, not a spec surface.
+ * Client-tool forwarding and the legacy client-stream adapter.
  *
- * 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`.
+ * Tool forwarding remains Builder-specific. Live byte streams are exposed to
+ * portable agent code through the optional spec `ThreadState.runtimeStreams`
+ * surface, which this module adapts onto the existing bridge frames.
  */
 /**
  * A request forwarded from a server-side tool to a connected client (CLI or
@@ -125,10 +121,8 @@ interface ClientToolResponse {
 /**
  * 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.
+ * The execution host interprets `tool` + `meta`; both fields and all payload
+ * bytes are opaque to the bridge transport.
  */
 interface ClientStreamRequest {
     /** Client stream capability name (e.g. `tcp_tunnel`). */
@@ -137,6 +131,18 @@ interface ClientStreamRequest {
     meta?: Record<string, unknown>;
     /** Milliseconds to wait for the client to accept the stream. */
     timeoutMs?: number;
+    /**
+     * Builder-internal reconnect hint, never sent to the client: when the
+     * thread's elected execution owner has no live socket, ask this user's hub
+     * to summon the owning machine's daemon to `threadId` and wait for the
+     * bridge to re-attach before failing the open. Without it a transient
+     * disconnect (daemon restart, network blip) surfaces instantly as
+     * "workspace unavailable" mid-turn.
+     */
+    wake?: {
+        threadId: string;
+        userId: string;
+    };
 }
 /**
  * A live bidirectional byte pipe between the thread runtime and the client.
@@ -189,9 +195,10 @@ declare function supportsClientForwarding(state: ThreadState): state is ThreadSt
  */
 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.
+ * Open a bidirectional byte stream through the legacy Builder-only surface.
+ * Requires a live execution-host bridge and never parks durably.
+ *
+ * @deprecated Portable agent code should use `state.runtimeStreams?.open()`.
  */
 declare function callClientStream(state: ThreadState, request: ClientStreamRequest): Promise<ClientStreamResponse>;
 /** Maximum raw bytes per `stream_data` frame (base64 expands ~4/3 on the wire;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ModelDefinition, AgentDefinition } 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, 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 { 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-BNLDsLsL.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';

package/dist/index.js

@@ -56,6 +56,30 @@ function callClient(state, request) {
   return s.callClient(request);
 }
 function callClientStream(state, request) {
+  if (state.runtimeStreams) {
+    return state.runtimeStreams.open({
+      capability: request.tool,
+      metadata: request.meta,
+      timeoutMs: request.timeoutMs
+    }).then(
+      (opened) => opened.ok ? {
+        ok: true,
+        duplex: {
+          readable: opened.stream.readable,
+          writable: opened.stream.writable,
+          close: (reason) => opened.stream.close(reason),
+          done: opened.stream.closed
+        }
+      } : {
+        ok: false,
+        error: opened.error,
+        data: opened.code ? {
+          code: opened.code,
+          noClient: opened.code === "unavailable" ? true : void 0
+        } : void 0
+      }
+    );
+  }
   const s = asForwarding(state);
   if (typeof s.callClientStream !== "function") {
     return Promise.resolve({
@@ -65,6 +89,39 @@ function callClientStream(state, request) {
   }
   return s.callClientStream(request);
 }
+function createRuntimeStreams(openClientStream) {
+  return {
+    async open(request) {
+      const opened = await openClientStream({
+        tool: request.capability,
+        meta: request.metadata,
+        timeoutMs: request.timeoutMs
+      });
+      if (!opened.ok) {
+        const failureData = opened.data;
+        return {
+          ok: false,
+          error: opened.error,
+          code: failureData?.code
+        };
+      }
+      let closed = false;
+      return {
+        ok: true,
+        stream: {
+          readable: opened.duplex.readable,
+          writable: opened.duplex.writable,
+          closed: opened.duplex.done,
+          close: (reason) => {
+            if (closed) return;
+            closed = true;
+            opened.duplex.close(reason);
+          }
+        }
+      };
+    }
+  };
+}
 function encodeStreamChunk(bytes) {
   let binary = "";
   const step = 32768;
@@ -12939,6 +12996,14 @@ var init_ThreadStateImpl = __esm({
         }
         return this.getMetadataArguments();
       }
+      /**
+       * Optional spec byte streams backed by the execution owner's existing
+       * bridge. Streams are live resources: they proxy through ancestors when a
+       * subagent opens one, but they never park or outlive a bridge disconnect.
+       */
+      get runtimeStreams() {
+        return createRuntimeStreams((request) => this.callClientStream(request));
+      }
       getMetadataArguments() {
         const value = this._metadata.properties?.[SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY];
         if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -13515,11 +13580,9 @@ var init_ThreadStateImpl = __esm({
         return local;
       }
       /**
-       * Open a bidirectional byte stream to the connected client (e.g. a raw TCP
-       * tunnel for Worker-side TLS termination). Streams require a LIVE bridge on
-       * this thread and never park — a stream is only meaningful while the client
-       * is attached. Subagents must not call this directly; they proxy whole
-       * requests up to the root thread instead (request-up / stream-down).
+       * Legacy bridge implementation used by `runtimeStreams`. Streams require a
+       * live execution owner and never park. A child thread proxies the complete
+       * request to the nearest bridge-holding ancestor (request-up/stream-down).
        */
       async callClientStream(request) {
         const instance = this._threadInstance;
@@ -13529,7 +13592,9 @@ var init_ThreadStateImpl = __esm({
             error: "This thread runtime cannot open client streams. Client streaming requires the DurableThread bridge."
           };
         }
-        const local = await instance.openClientStream(request);
+        const wakeUserId = this._metadata.user_id ?? null;
+        const withWake = (threadId) => wakeUserId ? { ...request, wake: { threadId, userId: wakeUserId } } : request;
+        const local = await instance.openClientStream(withWake(this._metadata.id));
         if (local.ok || !this.isNoClient(local)) return local;
         const env = this._threadInstance.env;
         if (!env?.AGENT_BUILDER_THREAD) return local;
@@ -13540,12 +13605,16 @@ var init_ThreadStateImpl = __esm({
           try {
             const stub = env.AGENT_BUILDER_THREAD.get(env.AGENT_BUILDER_THREAD.idFromName(parentId));
             if (typeof stub.proxyStreamOpen === "function") {
-              const opened = await stub.proxyStreamOpen(request);
+              const opened = await stub.proxyStreamOpen(withWake(parentId));
               if (opened.ok && opened.id) {
                 return { ok: true, duplex: this.buildProxyDuplex(stub, opened.id) };
               }
               if (opened.error && !opened.noClient) {
-                return { ok: false, error: opened.error };
+                return {
+                  ok: false,
+                  error: opened.error,
+                  data: opened.code ? { code: opened.code } : void 0
+                };
               }
             }
           } catch {
@@ -13564,6 +13633,12 @@ var init_ThreadStateImpl = __esm({
         let settleDone;
         const done = new Promise((r) => settleDone = r);
         let closed = false;
+        let settled = false;
+        const settle = (result) => {
+          if (settled) return;
+          settled = true;
+          settleDone(result);
+        };
         const readable = new ReadableStream({
           async pull(controller) {
             while (!closed) {
@@ -13572,7 +13647,7 @@ var init_ThreadStateImpl = __esm({
                 res = await stub.proxyStreamPull(id);
               } catch (error) {
                 controller.error(error instanceof Error ? error : new Error(String(error)));
-                settleDone({ ok: false, error: "proxy stream pull failed" });
+                settle({ ok: false, error: "proxy stream pull failed" });
                 return;
               }
               for (const chunk of res.chunks) {
@@ -13580,7 +13655,7 @@ var init_ThreadStateImpl = __esm({
               }
               if (res.done) {
                 controller.close();
-                settleDone(res.error ? { ok: false, error: res.error } : { ok: true });
+                settle(res.error ? { ok: false, error: res.error } : { ok: true });
                 return;
               }
               if (res.chunks.length > 0) return;
@@ -13591,6 +13666,7 @@ var init_ThreadStateImpl = __esm({
             closed = true;
             void stub.proxyStreamAbort(id).catch(() => {
             });
+            settle({ ok: false, error: "proxy stream reader canceled" });
           }
         });
         const writable = new WritableStream({
@@ -13605,16 +13681,18 @@ var init_ThreadStateImpl = __esm({
             closed = true;
             void stub.proxyStreamAbort(id).catch(() => {
             });
+            settle({ ok: false, error: "proxy stream writer aborted" });
           }
         });
         return {
           readable,
           writable,
           close: (error) => {
+            if (closed) return;
             closed = true;
             void stub.proxyStreamAbort(id).catch(() => {
             });
-            settleDone(error ? { ok: false, error } : { ok: true });
+            settle(error ? { ok: false, error } : { ok: true });
           },
           done
         };
@@ -28588,23 +28666,51 @@ ${resultContent}${attachmentSummary}`;
     }
     return { side };
   }
-  // ─── Client byte streams (Worker-side TLS tunnels) ─────────────────────────
-  // A stream is a bidirectional byte pipe over the bridge WebSocket: the
-  // client opens a raw TCP socket per the stream's `meta` and shuttles bytes
-  // both ways; the Worker terminates TLS over those bytes (node:tls over the
-  // duplex), so the client only ever relays ciphertext. Streams are bound to a
-  // live socket and never park.
+  // ─── Runtime byte streams ──────────────────────────────────────────────────
+  // The existing bridge frames carry opaque capability metadata and bytes
+  // between the runtime and its execution owner. Streams are live resources:
+  // they are bound to one bridge socket and never park.
   /** Default time to wait for the client to accept a stream open. */
   static CLIENT_STREAM_OPEN_TIMEOUT_MS = 3e4;
+  /** Poll cadence while waiting for a disconnected owner's bridge to return. */
+  static OWNER_REATTACH_POLL_MS = 250;
+  /**
+   * The thread HAS an elected execution owner, but its bridge socket is gone
+   * (daemon restart, network blip, DO handoff). Summon the owning machine
+   * through the per-user hub and wait for a bridge to re-attach instead of
+   * failing the stream open instantly — that instant failure is what ended
+   * Sama One turns with "workspace unavailable" whenever a slow tool/approval
+   * outlived the socket. Threads with NO recorded owner (subagent children)
+   * still fail fast so ancestor walk-up routing stays immediate.
+   */
+  async awaitOwnerBridgeSocket(request) {
+    if (request.wake?.userId) {
+      void this.requestHubWake(request.wake.userId, request.wake.threadId);
+    }
+    const timeoutMs = typeof request.timeoutMs === "number" && request.timeoutMs > 0 ? request.timeoutMs : _DurableThread.CLIENT_STREAM_OPEN_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await new Promise(
+        (resolve2) => setTimeout(resolve2, _DurableThread.OWNER_REATTACH_POLL_MS)
+      );
+      const owner = await this.getExecutionOwner();
+      const socket = this.getOpenBridgeSocket(owner?.client_id ?? null);
+      if (socket) return socket;
+    }
+    return null;
+  }
   /** Open a bidirectional byte stream to the connected owner client. */
   async openClientStream(request) {
     const owner = await this.getExecutionOwner();
-    const socket = this.getOpenBridgeSocket(owner?.client_id ?? null);
+    let socket = this.getOpenBridgeSocket(owner?.client_id ?? null);
+    if (!socket && owner) {
+      socket = await this.awaitOwnerBridgeSocket(request);
+    }
     if (!socket) {
       return {
         ok: false,
         error: "The workspace is not available right now. Try again in a moment.",
-        data: { noClient: true }
+        data: { noClient: true, code: "unavailable" }
       };
     }
     const id = crypto.randomUUID();
@@ -28637,7 +28743,8 @@ ${resultContent}${attachmentSummary}`;
       state.openTimer = setTimeout(() => {
         resolve2({
           ok: false,
-          error: `The client did not accept the ${request.tool} stream within ${Math.round(timeoutMs / 1e3)}s.`
+          error: `The client did not accept the ${request.tool} stream within ${Math.round(timeoutMs / 1e3)}s.`,
+          code: "timeout"
         });
       }, timeoutMs);
       try {
@@ -28652,7 +28759,8 @@ ${resultContent}${attachmentSummary}`;
       } catch (error) {
         resolve2({
           ok: false,
-          error: `Failed to reach the client: ${error instanceof Error ? error.message : String(error)}`
+          error: `Failed to reach the client: ${error instanceof Error ? error.message : String(error)}`,
+          code: "unavailable"
         });
       }
     });
@@ -28665,7 +28773,11 @@ ${resultContent}${attachmentSummary}`;
       this.clientStreams.delete(id);
       state.settled = true;
       settleDone({ ok: false, error: openResult.error });
-      return { ok: false, error: openResult.error ?? "Stream open failed." };
+      return {
+        ok: false,
+        error: openResult.error ?? "Stream open failed.",
+        data: openResult.code ? { code: openResult.code } : void 0
+      };
     }
     const sendChunked = (bytes) => {
       for (let i = 0; i < bytes.length; i += CLIENT_STREAM_CHUNK_BYTES) {
@@ -28709,8 +28821,14 @@ ${resultContent}${attachmentSummary}`;
   async proxyStreamOpen(request) {
     const opened = await this.openClientStream(request);
     if (!opened.ok) {
-      const noClient = !!(opened.data && opened.data.noClient);
-      return { ok: false, error: opened.error, noClient };
+      const failureData = opened.data;
+      const noClient = failureData?.noClient === true;
+      return {
+        ok: false,
+        error: opened.error,
+        noClient,
+        code: failureData?.code
+      };
     }
     const id = crypto.randomUUID();
     const duplex = opened.duplex;
@@ -28781,12 +28899,12 @@ ${resultContent}${attachmentSummary}`;
     }
   }
   /** Settle and remove a client stream exactly once. */
-  settleClientStream(id, result) {
+  settleClientStream(id, result, openCode) {
     const state = this.clientStreams.get(id);
     if (!state) return;
     this.clientStreams.delete(id);
     if (state.openTimer) clearTimeout(state.openTimer);
-    if (state.opened) state.opened({ ok: false, error: result.error ?? "Stream closed." });
+    if (state.opened) state.opened({ ok: false, error: result.error ?? "Stream closed.", code: openCode });
     if (!state.settled) {
       state.settled = true;
       try {
@@ -28830,7 +28948,7 @@ ${resultContent}${attachmentSummary}`;
       }
       case "stream_error": {
         const error = typeof parsed.error === "string" ? parsed.error : "Client stream error.";
-        this.settleClientStream(id, { ok: false, error });
+        this.settleClientStream(id, { ok: false, error }, "refused");
         return;
       }
       case "stream_data": {
@@ -28857,7 +28975,7 @@ ${resultContent}${attachmentSummary}`;
   failClientStreamsForSocket(ws) {
     for (const [id, state] of Array.from(this.clientStreams.entries())) {
       if (state.socket === ws) {
-        this.settleClientStream(id, { ok: false, error: "The client connection was lost." });
+        this.settleClientStream(id, { ok: false, error: "The client connection was lost." }, "unavailable");
       }
     }
   }
@@ -28881,6 +28999,11 @@ ${resultContent}${attachmentSummary}`;
       console.error("[DurableThread] Failed to arm park TTL (non-fatal):", error);
     }
     if (!userId) return;
+    await this.requestHubWake(userId, threadId);
+  }
+  /** Ask the user's hub to summon the owning machine's daemon to a thread.
+   *  Best-effort: wake failure must never fail the caller's own path. */
+  async requestHubWake(userId, threadId) {
     try {
       const namespace = this.env.AGENT_BUILDER_USER_HUB;
       if (!namespace) return;