@harness-gw/sdk 0.5.1 → 0.6.1

package/README.md

@@ -63,7 +63,7 @@ You need a running harness. Hermes is the primary one; see
    docker run --rm \
      -v "$PWD/config.yaml:/run/harness-gw/config.yaml:ro" \
      -v "$PWD/hermes-token:/run/secrets/hermes-token:ro" \
-     ghcr.io/almogbaku/harness-gw:0.5.1 \
+     ghcr.io/almogbaku/harness-gw:0.6.1 \
      config check --config /run/harness-gw/config.yaml
    ```
 
@@ -73,7 +73,7 @@ You need a running harness. Hermes is the primary one; see
    docker run --rm -p 127.0.0.1:4100:4100 \
      -v "$PWD/config.yaml:/run/harness-gw/config.yaml:ro" \
      -v "$PWD/hermes-token:/run/secrets/hermes-token:ro" \
-     ghcr.io/almogbaku/harness-gw:0.5.1 \
+     ghcr.io/almogbaku/harness-gw:0.6.1 \
      serve --config /run/harness-gw/config.yaml
    ```
 

package/dist/chunks/index.js

@@ -208,7 +208,7 @@ var SessionMessagePartSchema = z.discriminatedUnion("type", [
   }),
   z.strictObject({
     type: z.literal("image"),
-    image: z.string().min(1).max(25000000),
+    image: z.string().min(1).max(35000000),
     filename: z.string().min(1).max(4096).optional()
   }),
   z.strictObject({
@@ -727,8 +727,10 @@ var HGW_JSONRPC_ERRORS2 = {
   revisionConflict: -31012,
   temporarilyUnavailable: -31013,
   uncertainMutation: -31014,
-  unsupported: -31015
+  unsupported: -31015,
+  requestTooLarge: -31016
 };
+var HGW_MAX_FRAME_BYTES2 = 1100000;
 var IdentifierSchema2 = z2.string().min(1).max(256).refine((value) => [...value].every((character) => {
   const code = character.charCodeAt(0);
   return code >= 32 && code !== 127;
@@ -1180,4 +1182,4 @@ var MCP_APP_SANDBOX_CSP2 = [
   "frame-ancestors 'self'"
 ].join("; ");
 
-export { SESSION_CATALOG_MAX_WINDOW2, RuntimeAuthStateSchema2, OperationCapabilitySchema2, RuntimeInfoSchema2, AgentAvatarSchema2, AgentCatalogEntrySchema2, AgentCatalogResponseSchema2, AgentUpdateFields2, writesAgentField2, AgentUpdateRequestSchema2, AgentUpdateResponseSchema2, SessionStatusSchema2, SessionPlatformSchema2, SessionSchema2, newestSessionFirst2, SessionCatalogResponseSchema2, StopReason2, ToolKind2, ToolLocationSchema2, DiffOperation2, DiffChangeSchema2, ToolDiffSchema2, SessionMessageErrorStatusSchema2, SessionMessageSchema2, SessionPlanActivityMessageSchema2, SessionHistoryResponseSchema2, SessionCreateRequestSchema2, SessionCreateResponseSchema2, SessionPatchRequestSchema2, TurnStopResponseSchema2, TurnSteerRequestSchema2, TurnSteerResponseSchema2, SlashCommandSchema2, MAX_SLASH_COMMANDS2, INTERACTION_PROTOCOL2, SessionWorkspaceCapabilitiesResponseSchema2, GuestRuntimeCapabilitiesResponseSchema2, SessionModelsResponseSchema2, SessionModelUpdateRequestSchema2, SessionModelUpdateResponseSchema2, SessionContextResponseSchema2, ArtifactDescriptorSchema2, SessionTodosResponseSchema2, SessionActivityResponseSchema2, SessionAttachmentStageRequestSchema2, SessionAttachmentStageResponseSchema2, SessionAudioResponseSchema2, SessionTranscriptionRequestSchema2, SessionTranscriptionResponseSchema2, SessionSpeechRequestSchema2, ErrorResponseSchema2, ACP_PROTOCOL_VERSION2, HGW_API_PREFIX2, HGW_ACP_PATH2, HGW_ACP_AGENTS_PATH2, hgwAcpAgentPath2, HGW_META_KEY2, HGW_EXTENSION_VERSION2, HGW_AUTH_METHOD_INVITE2, HGW_ATTACHMENT_URI_SCHEME2, HGW_ARTIFACT_URI_SCHEME2, HGW_METHODS2, HGW_STOP_REASONS2, HGW_PERMISSION_KIND_SESSION2, HGW_PLAN_ID2, HGW_JSONRPC_ERRORS2, IdentifierSchema2, HgwExtensionsSchema2, HgwClientCapabilitiesMetaSchema2, HgwInitializeMetaSchema2, HgwLoginMetaSchema2, HgwSessionNewMetaSchema2, HgwSessionListMetaSchema2, HgwSessionSearchMetaSchema2, HgwSessionSearchResponseSchema2, HgwSessionInfoMetaSchema2, HgwSessionResumeMetaSchema2, HGW_REPLAY_BEFORE2, HgwReplayBeforeSchema2, HgwHistoryCursorSchema2, HgwHistoryPageResponseMetaSchema2, HgwHistoryPageTagSchema2, HgwSessionResumeResponseMetaSchema2, HgwPromptMetaSchema2, HgwSessionUpdateRequestSchema2, HgwSessionPartRequestSchema2, HgwSteerRequestSchema2, HgwSteerResponseSchema2, HgwFocusRequestSchema2, HgwAgentsListResponseSchema2, HgwAgentUpdateRequestSchema2, HgwAgentUpdateResponseSchema2, HgwTurnMetaSchema2, HgwNoticeMetaSchema2, HgwMessageMetaSchema2, HgwCostSchema2, HGW_SUBAGENT_STATUSES2, HgwSubagentSchema2, HgwStateMetaSchema2, HgwChunkMetaSchema2, HgwToolCallMetaSchema2, HgwPlanMetaSchema2, HgwUsageMetaSchema2, HgwAvailableCommandsMetaSchema2, HgwPermissionMetaSchema2, HgwQuestionOptionSchema2, HgwQuestionSchema2, HgwElicitationMetaSchema2, HgwArtifactDescriptorSchema2, formatArtifactUri2, parseArtifactUri2, HgwComposerPrefillNotificationSchema2, HgwErrorNotificationSchema2, HGW_REQUEST_TEXT_MAX2, HgwActivityNotificationSchema2, PushCategorySchema2, categoryOf2, PushLocaleSchema2, PRESENCE_IDLE_MS2, PRESENCE_HEARTBEAT_MS2, PRESENCE_GRACE_MS2, PRESENCE_CLOSED_GRACE_MS2, COALESCE_WINDOW_MS2, PUSH_TEXT_LIMITS2, PushMessageSchema2, PushCategoriesSchema2, PushSubscriptionJsonSchema2, PushInfoSchema2, PushRegistrationSchema2, PushUnregistrationSchema2, CallToolResultSchema2, ReadResourceResultSchema2, McpUiCspSchema2, isMcpAppCspDomain2, McpUiPermissionsSchema2, McpAppFilesSchema2, McpAppViewSchema2, viewerFileResult2, McpAppToolCallRequestSchema2, McpAppResourceReadRequestSchema2, MCP_APP_SANDBOX_PATH2, MCP_APP_SANDBOX_CSP2 };
+export { SESSION_CATALOG_MAX_WINDOW2, RuntimeAuthStateSchema2, OperationCapabilitySchema2, RuntimeInfoSchema2, AgentAvatarSchema2, AgentCatalogEntrySchema2, AgentCatalogResponseSchema2, AgentUpdateFields2, writesAgentField2, AgentUpdateRequestSchema2, AgentUpdateResponseSchema2, SessionStatusSchema2, SessionPlatformSchema2, SessionSchema2, newestSessionFirst2, SessionCatalogResponseSchema2, StopReason2, ToolKind2, ToolLocationSchema2, DiffOperation2, DiffChangeSchema2, ToolDiffSchema2, SessionMessageErrorStatusSchema2, SessionMessageSchema2, SessionPlanActivityMessageSchema2, SessionHistoryResponseSchema2, SessionCreateRequestSchema2, SessionCreateResponseSchema2, SessionPatchRequestSchema2, TurnStopResponseSchema2, TurnSteerRequestSchema2, TurnSteerResponseSchema2, SlashCommandSchema2, MAX_SLASH_COMMANDS2, INTERACTION_PROTOCOL2, SessionWorkspaceCapabilitiesResponseSchema2, GuestRuntimeCapabilitiesResponseSchema2, SessionModelsResponseSchema2, SessionModelUpdateRequestSchema2, SessionModelUpdateResponseSchema2, SessionContextResponseSchema2, ArtifactDescriptorSchema2, SessionTodosResponseSchema2, SessionActivityResponseSchema2, SessionAttachmentStageRequestSchema2, SessionAttachmentStageResponseSchema2, SessionAudioResponseSchema2, SessionTranscriptionRequestSchema2, SessionTranscriptionResponseSchema2, SessionSpeechRequestSchema2, ErrorResponseSchema2, ACP_PROTOCOL_VERSION2, HGW_API_PREFIX2, HGW_ACP_PATH2, HGW_ACP_AGENTS_PATH2, hgwAcpAgentPath2, HGW_META_KEY2, HGW_EXTENSION_VERSION2, HGW_AUTH_METHOD_INVITE2, HGW_ATTACHMENT_URI_SCHEME2, HGW_ARTIFACT_URI_SCHEME2, HGW_METHODS2, HGW_STOP_REASONS2, HGW_PERMISSION_KIND_SESSION2, HGW_PLAN_ID2, HGW_JSONRPC_ERRORS2, HGW_MAX_FRAME_BYTES2, IdentifierSchema2, HgwExtensionsSchema2, HgwClientCapabilitiesMetaSchema2, HgwInitializeMetaSchema2, HgwLoginMetaSchema2, HgwSessionNewMetaSchema2, HgwSessionListMetaSchema2, HgwSessionSearchMetaSchema2, HgwSessionSearchResponseSchema2, HgwSessionInfoMetaSchema2, HgwSessionResumeMetaSchema2, HGW_REPLAY_BEFORE2, HgwReplayBeforeSchema2, HgwHistoryCursorSchema2, HgwHistoryPageResponseMetaSchema2, HgwHistoryPageTagSchema2, HgwSessionResumeResponseMetaSchema2, HgwPromptMetaSchema2, HgwSessionUpdateRequestSchema2, HgwSessionPartRequestSchema2, HgwSteerRequestSchema2, HgwSteerResponseSchema2, HgwFocusRequestSchema2, HgwAgentsListResponseSchema2, HgwAgentUpdateRequestSchema2, HgwAgentUpdateResponseSchema2, HgwTurnMetaSchema2, HgwNoticeMetaSchema2, HgwMessageMetaSchema2, HgwCostSchema2, HGW_SUBAGENT_STATUSES2, HgwSubagentSchema2, HgwStateMetaSchema2, HgwChunkMetaSchema2, HgwToolCallMetaSchema2, HgwPlanMetaSchema2, HgwUsageMetaSchema2, HgwAvailableCommandsMetaSchema2, HgwPermissionMetaSchema2, HgwQuestionOptionSchema2, HgwQuestionSchema2, HgwElicitationMetaSchema2, HgwArtifactDescriptorSchema2, formatArtifactUri2, parseArtifactUri2, HgwComposerPrefillNotificationSchema2, HgwErrorNotificationSchema2, HGW_REQUEST_TEXT_MAX2, HgwActivityNotificationSchema2, PushCategorySchema2, categoryOf2, PushLocaleSchema2, PRESENCE_IDLE_MS2, PRESENCE_HEARTBEAT_MS2, PRESENCE_GRACE_MS2, PRESENCE_CLOSED_GRACE_MS2, COALESCE_WINDOW_MS2, PUSH_TEXT_LIMITS2, PushMessageSchema2, PushCategoriesSchema2, PushSubscriptionJsonSchema2, PushInfoSchema2, PushRegistrationSchema2, PushUnregistrationSchema2, CallToolResultSchema2, ReadResourceResultSchema2, McpUiCspSchema2, isMcpAppCspDomain2, McpUiPermissionsSchema2, McpAppFilesSchema2, McpAppViewSchema2, viewerFileResult2, McpAppToolCallRequestSchema2, McpAppResourceReadRequestSchema2, MCP_APP_SANDBOX_PATH2, MCP_APP_SANDBOX_CSP2 };

package/dist/client/acp-workspace-client-sessions.d.ts

@@ -1,6 +1,7 @@
 import { type SessionInfo } from "@agentclientprotocol/sdk/experimental/v2";
 import { type HgwSessionInfoMeta } from "../protocol/acp.js";
 import type { SessionMetadata, SessionStatus, TodoItem, WorkspaceActivityEvent } from "./workspace.js";
+import type { Logger } from "../lifecycle/index.js";
 import type { AcpConnection } from "./types.js";
 /**
  * Everything the workspace learns by subscribing to the connection: the Session row
@@ -13,8 +14,10 @@ export type AcpSessionStoreOptions = {
     now?: () => number;
     /** A live turn of a subscribed Session just stopped, however it ended. */
     onTurnFinished?: (sessionId: string) => void;
+    /** Where a listener that throws is told; the others still hear. */
+    logger?: Logger;
 };
-export declare function createAcpSessionStore({ connection, now, onTurnFinished, }: AcpSessionStoreOptions): {
+export declare function createAcpSessionStore({ connection, now, onTurnFinished, logger, }: AcpSessionStoreOptions): {
     subscribe: (sessionId: string, agentId?: string) => () => void;
     dispose(): void;
     /**
@@ -36,6 +39,8 @@ export declare function createAcpSessionStore({ connection, now, onTurnFinished,
         createdAt?: string;
         platform?: import("./workspace.js").SessionPlatform;
     }[];
+    /** Marks Sessions a read has answered for, so a missing one gates no snapshot. */
+    answer(sessionIds: readonly string[]): void;
     /** The provider's title, as a list page or a subscribed Session reports it. */
     setTitle: (sessionId: string, title: string) => Map<string, string>;
     /** The proxy's read state, or the operator's own optimistic ack. */

package/dist/client/index.js

@@ -14,6 +14,7 @@ import {
   HGW_STOP_REASONS2,
   HGW_PERMISSION_KIND_SESSION2,
   HGW_JSONRPC_ERRORS2,
+  HGW_MAX_FRAME_BYTES2,
   HgwInitializeMetaSchema2,
   HgwSessionSearchMetaSchema2,
   HgwSessionSearchResponseSchema2,
@@ -277,6 +278,13 @@ class AgentUpdateError extends Error {
   }
 }
 
+class AcpConnectionClosedError extends Error {
+  constructor(message = "The ACP connection closed", options) {
+    super(message, options);
+    this.name = "AcpConnectionClosedError";
+  }
+}
+
 // client/limits.ts
 var HANDSHAKE_DEADLINE_MS = 1e4;
 var REQUEST_DEADLINE_MS = {
@@ -370,6 +378,21 @@ function loggedStream(stream, logger) {
     })
   };
 }
+var LOGGED_ID_LENGTH = 256;
+function loggedId(row, ...path) {
+  let value = row;
+  for (const key of path)
+    value = typeof value === "object" && value !== null ? value[key] : undefined;
+  return typeof value === "string" && value.length > 0 ? value.slice(0, LOGGED_ID_LENGTH) : undefined;
+}
+function callEach(listeners, logger, event, ...args) {
+  for (const listener of [...listeners])
+    try {
+      listener(...args);
+    } catch (err) {
+      logger.warn({ err }, event);
+    }
+}
 
 // client/connection.ts
 var TRY_AGAIN_LATER = 1013;
@@ -420,9 +443,6 @@ var SESSION_STATES = new Map([
   ["refused", "unavailable"],
   ["gone", "gone"]
 ]);
-function isTimeout(error) {
-  return error instanceof DOMException && error.name === "TimeoutError";
-}
 function agentUpdateError(error) {
   if (codeOf(error) === HGW_JSONRPC_ERRORS2.unsupported)
     return new AgentUpdateError("unsupported", "This runtime cannot store that Agent field");
@@ -466,6 +486,9 @@ function trackedInbound(stream, onReceived) {
     writable: stream.writable
   };
 }
+function closedUnder({ connection }, error) {
+  return connection.signal.aborted && error === connection.signal.reason;
+}
 function observedSocket(Socket, onOpen, onClose) {
   return class extends Socket {
     constructor(...args) {
@@ -637,6 +660,35 @@ function sessionMachine({
     }
   });
 }
+function readEach(entries, schema, skipped) {
+  const kept = [];
+  let unreadable;
+  for (const entry of entries) {
+    const read = schema.safeParse(entry);
+    if (read.success)
+      kept.push(read.data);
+    else {
+      unreadable = read.error;
+      skipped(entry);
+    }
+  }
+  if (entries.length > 0 && kept.length === 0)
+    throw unreadable;
+  return kept;
+}
+var AgentsListEntriesSchema = HgwAgentsListResponseSchema2.extend({
+  agents: z.array(z.unknown()).max(1000)
+});
+var SessionSearchEntriesSchema = HgwSessionSearchResponseSchema2.extend({
+  sessions: z.array(z.unknown())
+});
+var FRAME_ENVELOPE_BYTES = 1024;
+var frameEncoder = new TextEncoder;
+function assertFrameFits(params) {
+  const bytes = frameEncoder.encode(JSON.stringify(params)).byteLength;
+  if (bytes > HGW_MAX_FRAME_BYTES2 - FRAME_ENVELOPE_BYTES)
+    throw new RequestError(HGW_JSONRPC_ERRORS2.requestTooLarge, "Request too large to send");
+}
 function createAcpConnection(options) {
   const {
     clientInfo,
@@ -660,6 +712,7 @@ function createAcpConnection(options) {
   let live;
   let recovering = false;
   let joinable = false;
+  let recovery;
   let invitation;
   let lastFocus;
   let silenceTimer = undefined;
@@ -674,23 +727,13 @@ function createAcpConnection(options) {
     if (status === next)
       return;
     status = next;
-    for (const listener of statusListeners)
-      listener(next);
+    callEach(statusListeners, logger, "acp.listener.failed", next);
   }
   function setOutage(next) {
     if (outage === next)
       return;
     outage = next;
-    for (const listener of outageListeners)
-      listener(next);
-  }
-  function settleOutage() {
-    if (status !== "ready")
-      return;
-    for (const open of sessions.values())
-      if (open.state === "joining")
-        return;
-    setOutage(undefined);
+    callEach(outageListeners, logger, "acp.listener.failed", next);
   }
   function emitPending(request) {
     for (const listener of pendingListeners)
@@ -708,7 +751,9 @@ function createAcpConnection(options) {
       sendLivenessProbeAsync();
     }, LIVENESS_SILENCE_MS);
   }
+  let lastInboundAt = Number.NEGATIVE_INFINITY;
   function onInbound() {
+    lastInboundAt = clock.now();
     armSilenceTimer();
   }
   function sendLivenessProbeAsync() {
@@ -766,14 +811,13 @@ function createAcpConnection(options) {
     if (open.replaying)
       open.replaying.delivered = true;
     for (const { listener } of open.listeners)
-      listener.update?.(params.update, meta);
+      callEach(listener.update ? [listener.update] : [], logger, "acp.listener.failed", params.update, meta);
   }).onRequest(methods2.client.session.requestPermission, ({ params, signal }) => permissionRequest(params, signal)).onRequest(methods2.client.elicitation.create, ({ params, signal }) => elicitationRequest(params, signal));
   for (const [method, parser] of Object.entries(NOTIFICATION_PARSERS))
     app.onNotification(method, parser, ({ params }) => {
       if (method === HGW_METHODS2.notify.error)
         noticeGone(params);
-      for (const listener of notificationListeners.get(method) ?? [])
-        listener(params);
+      callEach(notificationListeners.get(method) ?? [], logger, "acp.listener.failed", params);
     });
   function noticeGone(params) {
     const notice = HgwErrorNotificationSchema2.safeParse(params).data;
@@ -781,48 +825,64 @@ function createAcpConnection(options) {
       return;
     sessions.get(notice.sessionId)?.owner?.actor.send({ type: "gone" });
   }
-  async function readyTransport() {
+  async function liveTransport() {
     start();
     if (inspecting)
       await inspecting;
-    const current = live;
-    if (ended || !current)
-      throw new Error("The ACP connection is not open");
+    if (ended || !live)
+      throw new AcpConnectionClosedError("The ACP connection is not open");
+    return live;
+  }
+  async function readyTransport() {
+    const current = await liveTransport();
     await current.ready;
     return current;
   }
-  async function request(tier, send) {
-    return requestOn(await readyTransport(), tier, send);
+  function recovered() {
+    start();
+    if (ended)
+      return Promise.reject(new AcpConnectionClosedError);
+    if (joinable)
+      return Promise.resolve();
+    recovery ??= Promise.withResolvers();
+    return recovery.promise;
+  }
+  async function request(tier, send, resend) {
+    const sessionId = resend === "read" ? undefined : resend?.sessionId;
+    for (;; ) {
+      if (sessionId !== undefined && sessions.has(sessionId))
+        await joined(sessionId);
+      else if (resend)
+        await recovered();
+      const transport = await liveTransport();
+      try {
+        await transport.ready;
+        return await requestOn(transport, tier, send);
+      } catch (error) {
+        if (!closedUnder(transport, error))
+          throw error;
+        const again = resend === "read" || sessionId !== undefined && sessions.has(sessionId);
+        if (!again)
+          throw new AcpConnectionClosedError(undefined, { cause: error });
+        await transport.connection.closed.catch((err) => logger.warn({ err }, "acp.connection.closed_with_error"));
+      }
+    }
   }
   async function requestOn({ connection }, tier, send, parent) {
     const deadline = new Deadline(REQUEST_DEADLINE_MS[tier], clock, parent);
+    const sentAt = clock.now();
     try {
       return await deadline.run((cancellationSignal) => send(connection.agent, { cancellationSignal }));
     } catch (error) {
       if (deadline.signal.aborted && !parent?.aborted) {
-        if (tier === "probe")
-          connection.close(error);
-        else
+        if (tier !== "probe")
           sendLivenessProbeAsync();
+        else if (lastInboundAt <= sentAt)
+          connection.close(error);
       }
       throw error;
     }
   }
-  async function write(sessionId, tier, send) {
-    for (;; ) {
-      if (sessions.has(sessionId))
-        await joined(sessionId);
-      const transport = await readyTransport();
-      try {
-        return await requestOn(transport, tier, send);
-      } catch (error) {
-        const closedUnder = transport.connection.signal.aborted && !isTimeout(error) && sessions.has(sessionId);
-        if (!closedUnder)
-          throw error;
-        await transport.connection.closed.catch((err) => logger.warn({ err }, "acp.connection.closed_with_error"));
-      }
-    }
-  }
   function notifyAgent(send, sessionId) {
     (async () => {
       if (sessionId !== undefined && sessions.has(sessionId))
@@ -921,7 +981,11 @@ function createAcpConnection(options) {
     }
   }
   async function listAgents() {
-    return HgwAgentsListResponseSchema2.parse(await request("short", (agent, options) => agent.request(HGW_METHODS2.agents.list, undefined, options)));
+    const response = AgentsListEntriesSchema.parse(await request("short", (agent, options) => agent.request(HGW_METHODS2.agents.list, undefined, options), "read"));
+    return {
+      ...response,
+      agents: readEach(response.agents, HgwAgentsListResponseSchema2.shape.agents.element, (entry) => logger.warn({ id: loggedId(entry, "summary", "id") }, "agents.entry_skipped"))
+    };
   }
   function settleOf({ listener }) {
     const settle = listener.replay?.();
@@ -976,8 +1040,7 @@ function createAcpConnection(options) {
     if (next === "joined" || failure !== undefined)
       open.waiters = undefined;
     for (const { listener } of open.listeners)
-      listener.state?.(next);
-    settleOutage();
+      callEach(listener.state ? [listener.state] : [], logger, "acp.listener.failed", next);
   }
   function subscribe(sessionId, listener) {
     if (ended)
@@ -1028,7 +1091,6 @@ function createAcpConnection(options) {
     open.owner?.dispose();
     open.waiters?.reject(notOpen());
     open.waiters = undefined;
-    settleOutage();
     if (open.state === "gone")
       return;
     request("short", (agent, options) => agent.request(HGW_METHODS2.session.part, { sessionId }, options)).catch((err) => {
@@ -1036,18 +1098,20 @@ function createAcpConnection(options) {
     });
   }
   async function resumePage(sessionId, cursor) {
-    await joined(sessionId);
     const open = sessions.get(sessionId);
     if (!open)
       throw notOpen();
-    const updates = [];
-    open.page = updates;
+    let updates = [];
     try {
-      const response = await request("medium", (agent, options) => agent.request(methods2.agent.session.resume, {
-        sessionId,
-        cwd: AGENT_CWD,
-        replayFrom: { type: HGW_REPLAY_BEFORE2, cursor }
-      }, options));
+      const response = await request("medium", (agent, options) => {
+        updates = [];
+        open.page = updates;
+        return agent.request(methods2.agent.session.resume, {
+          sessionId,
+          cwd: AGENT_CWD,
+          replayFrom: { type: HGW_REPLAY_BEFORE2, cursor }
+        }, options);
+      }, { sessionId });
       const { history } = HgwHistoryPageResponseMetaSchema2.parse(hgwMetaOf(response._meta));
       return { updates, history };
     } finally {
@@ -1063,6 +1127,9 @@ function createAcpConnection(options) {
       sendLivenessProbeAsync();
     }
     joinable = true;
+    setOutage(undefined);
+    recovery?.resolve();
+    recovery = undefined;
     const opened = [...sessions.keys()];
     for (const open of sessions.values())
       open.owner?.actor.send({ type: "ready" });
@@ -1102,7 +1169,6 @@ function createAcpConnection(options) {
     closeTransport: () => live?.connection.close(),
     markReady() {
       setStatus("ready");
-      settleOutage();
     },
     lose(next) {
       recovering = true;
@@ -1165,13 +1231,15 @@ function createAcpConnection(options) {
     ended = true;
     setStatus("closed");
     setOutage(undefined);
-    failInitialized?.(new Error("The ACP connection closed"));
+    failInitialized?.(new AcpConnectionClosedError);
     failInitialized = undefined;
     settleInitialized = undefined;
+    recovery?.reject(new AcpConnectionClosedError);
+    recovery = undefined;
     for (const open of sessions.values()) {
       clock.clearTimeout(open.grace);
       open.owner?.dispose();
-      open.waiters?.reject(new Error("The ACP connection closed"));
+      open.waiters?.reject(new AcpConnectionClosedError);
     }
     sessions.clear();
     live?.connection.close();
@@ -1208,16 +1276,22 @@ function createAcpConnection(options) {
       const response = await request("short", (agent, options) => agent.request(methods2.agent.session.list, {
         ...cursor === undefined ? {} : { cursor },
         _meta: { [HGW_META_KEY2]: meta }
-      }, options));
+      }, options), "read");
       return {
         sessions: response.sessions,
         ...response.nextCursor ? { nextCursor: response.nextCursor } : {}
       };
     },
     async searchSessions(meta) {
-      return HgwSessionSearchResponseSchema2.parse(await request("short", (agent, options) => agent.request(HGW_METHODS2.sessions.search, {
-        _meta: { [HGW_META_KEY2]: HgwSessionSearchMetaSchema2.parse(meta) }
-      }, options)));
+      const response = SessionSearchEntriesSchema.parse(await request("short", (agent, options) => agent.request(HGW_METHODS2.sessions.search, {
+        _meta: {
+          [HGW_META_KEY2]: HgwSessionSearchMetaSchema2.parse(meta)
+        }
+      }, options), "read"));
+      return {
+        ...response,
+        sessions: readEach(response.sessions, HgwSessionSearchResponseSchema2.shape.sessions.element, (entry) => logger.warn({ id: loggedId(entry, "sessionId") }, "sessions.result_skipped"))
+      };
     },
     subscribe,
     joined,
@@ -1226,14 +1300,20 @@ function createAcpConnection(options) {
     resumePage,
     history: (sessionId) => sessions.get(sessionId)?.history,
     async prompt(sessionId, blocks, meta) {
-      const response = await write(sessionId, "long", (agent, options) => agent.request(methods2.agent.session.prompt, { sessionId, prompt: blocks, _meta: { [HGW_META_KEY2]: meta } }, options));
+      const params = {
+        sessionId,
+        prompt: blocks,
+        _meta: { [HGW_META_KEY2]: meta }
+      };
+      assertFrameFits(params);
+      const response = await request("long", (agent, options) => agent.request(methods2.agent.session.prompt, params, options), { sessionId });
       return { messageId: response.messageId };
     },
     cancel(sessionId) {
       notifyAgent((agent) => agent.notify(methods2.agent.session.cancel, { sessionId }), sessionId);
     },
     async setConfigOption(sessionId, configId, value) {
-      const response = await write(sessionId, "medium", (agent, options) => agent.request(methods2.agent.session.setConfigOption, { sessionId, configId, type: "id", value }, options));
+      const response = await request("medium", (agent, options) => agent.request(methods2.agent.session.setConfigOption, { sessionId, configId, type: "id", value }, options), { sessionId });
       return response.configOptions;
     },
     async deleteSession(sessionId) {
@@ -1243,7 +1323,8 @@ function createAcpConnection(options) {
       await request("short", (agent, options) => agent.request(HGW_METHODS2.session.update, update, options));
     },
     async steer(steer) {
-      return HgwSteerResponseSchema2.parse(await write(steer.sessionId, "medium", (agent, options) => agent.request(HGW_METHODS2.session.steer, steer, options)));
+      assertFrameFits(steer);
+      return HgwSteerResponseSchema2.parse(await request("medium", (agent, options) => agent.request(HGW_METHODS2.session.steer, steer, options), { sessionId: steer.sessionId }));
     },
     focus(sessionId, presence) {
       const report = {
@@ -1558,7 +1639,8 @@ function sameRow(left, right) {
 function createAcpSessionStore({
   connection,
   now = Date.now,
-  onTurnFinished
+  onTurnFinished,
+  logger = SILENT_LOGGER
 }) {
   const rows = new Map;
   const titles = new Map;
@@ -1577,11 +1659,12 @@ function createAcpSessionStore({
       return row ? [{ ...row }] : [];
     });
   }
+  const answered = new Set;
   function notify(subscription) {
     for (const sessionId of subscription.sessionIds)
-      if (!rows.has(sessionId))
+      if (!rows.has(sessionId) && !answered.has(sessionId))
         return;
-    subscription.listener(rowsFor(subscription.sessionIds));
+    callEach([subscription.listener], logger, "sessions.listener.failed", rowsFor(subscription.sessionIds));
   }
   function publish(sessionId) {
     for (const subscription of subscriptions)
@@ -1623,15 +1706,13 @@ function createAcpSessionStore({
   function setTodos(sessionId, next) {
     todos.set(sessionId, next);
     for (const listener of todoListeners.get(sessionId) ?? [])
-      listener(next.map((todo) => ({ ...todo })));
+      callEach([listener], logger, "sessions.listener.failed", next.map((todo) => ({ ...todo })));
   }
   function emitActivity(event) {
-    for (const listener of activityListeners)
-      listener(event);
+    callEach(activityListeners, logger, "sessions.listener.failed", event);
   }
   function invalidate(sessionId) {
-    for (const listener of invalidationListeners.get(sessionId) ?? [])
-      listener();
+    callEach(invalidationListeners.get(sessionId) ?? [], logger, "sessions.listener.failed");
   }
   function acceptUpdate(sessionId, update, meta) {
     if (SessionUpdate2.isStateUpdate(update)) {
@@ -1726,6 +1807,13 @@ function createAcpSessionStore({
     },
     put,
     rowsFor,
+    answer(sessionIds) {
+      for (const sessionId of sessionIds)
+        answered.add(sessionId);
+      for (const subscription of subscriptions)
+        if (sessionIds.some((id) => subscription.sessionIds.has(id)))
+          notify(subscription);
+    },
     setTitle: (sessionId, title) => titles.set(sessionId, title),
     setUnread: (sessionId, unread) => patch(sessionId, { unread }),
     setPinned: (sessionId, pinned) => patch(sessionId, { pinned }),
@@ -1807,6 +1895,7 @@ function createAcpWorkspaceClient({
 }) {
   const store = createAcpSessionStore({
     connection,
+    logger: clientLog,
     ...now ? { now } : {},
     onTurnFinished: (sessionId) => {
       reportCreatedAgents(sessionId).catch((err) => clientLog.warn({ err }, "agent.report_created_failed"));
@@ -1853,12 +1942,25 @@ function createAcpWorkspaceClient({
     return response;
   }
   function rememberRows(sessions) {
+    const kept = [];
+    let unreadable;
     for (const session of sessions) {
-      const row = rowOf(session);
+      let row;
+      try {
+        row = rowOf(session);
+      } catch (error) {
+        unreadable = error;
+        clientLog.warn({ id: loggedId(session, "sessionId") }, "sessions.row_skipped");
+        continue;
+      }
       remember(row.sessionId, row.info, row.updatedAt);
       if (row.title)
         store.setTitle(row.sessionId, row.title);
+      kept.push(session);
     }
+    if (sessions.length > 0 && kept.length === 0)
+      throw unreadable;
+    return kept;
   }
   const pageReads = new Map;
   let catalogScope;
@@ -1867,10 +1969,7 @@ function createAcpWorkspaceClient({
     const inFlight = pageReads.get(key);
     if (inFlight)
       return inFlight;
-    const read = connection.listSessions(meta, cursor).then((page) => {
-      rememberRows(page.sessions);
-      return page;
-    }).finally(() => pageReads.delete(key));
+    const read = connection.listSessions(meta, cursor).then((page) => ({ ...page, sessions: rememberRows(page.sessions) })).finally(() => pageReads.delete(key));
     pageReads.set(key, read);
     return read;
   }
@@ -1938,16 +2037,16 @@ function createAcpWorkspaceClient({
       let page;
       try {
         page = await listSessions();
-      } catch {
+      } catch (err) {
         if (stale(generation))
           return;
+        clientLog.warn({ err, attempt }, "sessions.relist_retry_failed");
         attempt += 1;
         await backOff(backoffDelay(attempt, RELIST_BACKOFF));
         continue;
       }
       const sessionIds = page.sessions.map(({ sessionId }) => sessionId);
-      for (const listener of catalogListeners)
-        listener(sessionIds);
+      callEach(catalogListeners, clientLog, "sessions.catalog_listener.failed", sessionIds);
       return;
     }
   }
@@ -2048,9 +2147,9 @@ function createAcpWorkspaceClient({
         query,
         ...agentId === undefined ? {} : { agentId }
       });
-      rememberRows(sessions);
-      const titles = new Map(sessions.map(({ sessionId, title }) => [sessionId, title ?? ""]));
-      return store.rowsFor(sessions.map(({ sessionId }) => sessionId)).map(({ sessionId, agentId, updatedAt }) => ({
+      const kept = rememberRows(sessions);
+      const titles = new Map(kept.map(({ sessionId, title }) => [sessionId, title ?? ""]));
+      return store.rowsFor(kept.map(({ sessionId }) => sessionId)).map(({ sessionId, agentId, updatedAt }) => ({
         sessionId,
         agentId,
         title: titles.get(sessionId) ?? "",
@@ -2063,6 +2162,7 @@ function createAcpWorkspaceClient({
     },
     async getSessionMetadata(sessionIds) {
       await readRows(sessionIds);
+      store.answer(sessionIds);
       return store.rowsFor(sessionIds);
     },
     subscribeSessionMetadata: store.subscribeMetadata,
@@ -2613,6 +2713,7 @@ class HgwRemoteClient {
   }
 }
 export {
+  AcpConnectionClosedError,
   AgentUpdateError,
   HgwClientError,
   HgwRemoteClient,

package/dist/client/log.d.ts

@@ -28,4 +28,15 @@ export declare function frameFields(direction: "in" | "out", message: unknown):
 };
 /** `stream` with one `acp.frame` debug line per message, each way. */
 export declare function loggedStream(stream: WireStream, logger: Logger): WireStream;
+/**
+ * The id at `path` in a row not yet checked, bounded for a warning. A warning
+ * about a rejected row names it by this alone, never by its content.
+ */
+export declare function loggedId(row: unknown, ...path: string[]): string | undefined;
+/**
+ * Calls every listener with `args`, each on its own: one that throws is
+ * logged as `event` and costs only itself, never the listeners after it nor
+ * the caller that fanned out to them.
+ */
+export declare function callEach<Args extends readonly unknown[]>(listeners: Iterable<(...args: Args) => void>, logger: Logger, event: string, ...args: Args): void;
 export {};

package/dist/client/types.d.ts

@@ -63,6 +63,13 @@ export type AcpSessionListener = {
     replay?: AcpSessionReplayListener;
     state?: (state: AcpSessionState) => void;
 };
+/**
+ * A read (`listAgents`, `listSessions`, `searchSessions`, `resumePage`) waits
+ * out a reconnect and goes out again on the transport that recovers, and a
+ * write for an opened Session once it has rejoined. Any other call a
+ * transport closes under, and every call once the connection has ended,
+ * rejects as `AcpConnectionClosedError`.
+ */
 export interface AcpConnection {
     readonly status: AcpConnectionStatus;
     /**
@@ -75,7 +82,10 @@ export interface AcpConnection {
     /** Resolves with `InitializeResponse._meta.hgw` once the handshake settles. */
     readonly initialized: Promise<z.infer<typeof HgwInitializeMetaSchema>>;
     subscribeStatus(listener: (status: AcpConnectionStatus) => void): () => void;
-    /** Set from a close until every resumed Session has rejoined. */
+    /**
+     * Set from a close until the transport is ready again. Each Session's
+     * rejoin is its own state (`sessionState`), not the connection's.
+     */
     readonly outage: AcpConnectionOutage | undefined;
     subscribeOutage(listener: (outage: AcpConnectionOutage | undefined) => void): () => void;
     /**

package/dist/client/workspace.d.ts

@@ -17,6 +17,15 @@ export declare class AgentUpdateError extends Error {
     readonly code: "unsupported" | "conflict";
     constructor(code: "unsupported" | "conflict", message: string);
 }
+/**
+ * The ACP connection is gone for a request: it has ended, no transport is open
+ * to send on, or a transport closed under a request it does not send again.
+ * `cause` holds what that transport closed with, which a failed socket leaves
+ * a DOM `Event`. Gateway refusals and timeouts reject as they come.
+ */
+export declare class AcpConnectionClosedError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
 export type SessionStatus = "idle" | "running" | "waiting-for-input" | "failed" | "unknown";
 export type ActivityBase = {
     id: string;

package/dist/protocol/acp.d.ts

@@ -90,7 +90,17 @@ export declare const HGW_JSONRPC_ERRORS: {
     readonly temporarilyUnavailable: -31013;
     readonly uncertainMutation: -31014;
     readonly unsupported: -31015;
+    /**
+     * Params too large for one frame. The client raises it before sending and
+     * the gateway never sends it, so it has no machine name on the wire.
+     */
+    readonly requestTooLarge: -31016;
 };
+/**
+ * The largest inbound WebSocket frame the gateway takes, in bytes. A larger
+ * one closes the socket, and with it every Session on the tab.
+ */
+export declare const HGW_MAX_FRAME_BYTES = 1100000;
 export type HgwJsonRpcErrorCode = (typeof HGW_JSONRPC_ERRORS)[keyof typeof HGW_JSONRPC_ERRORS];
 export declare const IdentifierSchema: z.ZodString;
 export declare const HgwExtensionsSchema: z.ZodObject<{

package/dist/protocol/sdk.js

@@ -65,6 +65,7 @@ import {
   HGW_PERMISSION_KIND_SESSION2,
   HGW_PLAN_ID2,
   HGW_JSONRPC_ERRORS2,
+  HGW_MAX_FRAME_BYTES2,
   IdentifierSchema2,
   HgwExtensionsSchema2,
   HgwClientCapabilitiesMetaSchema2,
@@ -215,6 +216,7 @@ export {
   HGW_AUTH_METHOD_INVITE2 as HGW_AUTH_METHOD_INVITE,
   HGW_EXTENSION_VERSION2 as HGW_EXTENSION_VERSION,
   HGW_JSONRPC_ERRORS2 as HGW_JSONRPC_ERRORS,
+  HGW_MAX_FRAME_BYTES2 as HGW_MAX_FRAME_BYTES,
   HGW_META_KEY2 as HGW_META_KEY,
   HGW_METHODS2 as HGW_METHODS,
   HGW_PERMISSION_KIND_SESSION2 as HGW_PERMISSION_KIND_SESSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-gw/sdk",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "A gateway that puts Hermes, OpenClaw, and OpenCode behind one ACP WebSocket, and the browser client and protocol SDK for it.",
   "license": "Apache-2.0",
   "type": "module",