@hydra-acp/cli 0.1.8 → 0.1.10

package/dist/index.d.ts

@@ -1245,11 +1245,13 @@ interface JsonRpcError {
     data?: unknown;
 }
 type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
-declare const HistoryPolicy: z.ZodEnum<["full", "pending_only", "none"]>;
+declare const HistoryPolicy: z.ZodEnum<["full", "pending_only", "none", "after_message"]>;
 type HistoryPolicy = z.infer<typeof HistoryPolicy>;
 declare const SessionAttachParams: z.ZodObject<{
     sessionId: z.ZodString;
-    historyPolicy: z.ZodDefault<z.ZodEnum<["full", "pending_only", "none"]>>;
+    historyPolicy: z.ZodDefault<z.ZodEnum<["full", "pending_only", "none", "after_message"]>>;
+    afterMessageId: z.ZodOptional<z.ZodString>;
+    clientId: z.ZodOptional<z.ZodString>;
     clientInfo: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         version: z.ZodOptional<z.ZodString>;
@@ -1263,11 +1265,13 @@ declare const SessionAttachParams: z.ZodObject<{
     _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
-    historyPolicy: "full" | "pending_only" | "none";
+    historyPolicy: "full" | "pending_only" | "none" | "after_message";
     clientInfo?: {
         name: string;
         version?: string | undefined;
     } | undefined;
+    afterMessageId?: string | undefined;
+    clientId?: string | undefined;
     _meta?: Record<string, unknown> | undefined;
 }, {
     sessionId: string;
@@ -1275,7 +1279,9 @@ declare const SessionAttachParams: z.ZodObject<{
         name: string;
         version?: string | undefined;
     } | undefined;
-    historyPolicy?: "full" | "pending_only" | "none" | undefined;
+    historyPolicy?: "full" | "pending_only" | "none" | "after_message" | undefined;
+    afterMessageId?: string | undefined;
+    clientId?: string | undefined;
     _meta?: Record<string, unknown> | undefined;
 }>;
 type SessionAttachParams = z.infer<typeof SessionAttachParams>;
@@ -1691,12 +1697,24 @@ declare class Session {
         upstreamSessionId: string;
     }) => void): void;
     get attachedCount(): number;
+    connectedClients(excludeClientId?: string): Array<{
+        clientId: string;
+        name?: string;
+        version?: string;
+    }>;
     get turnStartedAt(): number | undefined;
     getHistorySnapshot(): Promise<CachedNotification[]>;
     onBroadcast(handler: (entry: CachedNotification) => void): () => void;
-    attach(client: AttachedClient, historyPolicy: HistoryPolicy): Promise<CachedNotification[]>;
+    attach(client: AttachedClient, historyPolicy: HistoryPolicy, opts?: {
+        afterMessageId?: string;
+    }): Promise<{
+        entries: CachedNotification[];
+        appliedPolicy: HistoryPolicy;
+    }>;
+    private loadReplay;
     replayPendingPermissions(client: AttachedClient): void;
     detach(clientId: string): void;
+    private broadcastClientDisconnected;
     prompt(clientId: string, params: unknown): Promise<unknown>;
     private broadcastPromptReceived;
     private broadcastTurnComplete;

package/dist/index.js

@@ -854,11 +854,22 @@ var JsonRpcErrorCodes = {
   MethodNotFound: -32601,
   InvalidParams: -32602,
   InternalError: -32603,
+  // -32001…-32003 reserved for RFD #533 attach semantics:
+  //   -32001 Session not found
+  //   -32002 Not authorised to attach
+  //   -32003 Session does not support multi-client attach
+  // We emit -32001 (matching); the other two are reserved for spec
+  // alignment even though we don't currently emit them (we bearer-auth
+  // at WS upgrade time and always support multi-client attach).
   SessionNotFound: -32001,
-  PermissionDenied: -32002,
-  AlreadyAttached: -32003,
+  NotAuthorisedToAttach: -32002,
+  MultiClientNotSupported: -32003,
   AgentNotInstalled: -32005,
-  BundleAlreadyImported: -32010
+  // Hydra-internal codes — outside the RFD's reserved range so they
+  // can't collide with future spec assignments.
+  BundleAlreadyImported: -32010,
+  PermissionDenied: -32011,
+  AlreadyAttached: -32012
 };
 var InitializeParams = z3.object({
   protocolVersion: z3.number().optional(),
@@ -868,7 +879,12 @@ var InitializeParams = z3.object({
     version: z3.string().optional()
   }).optional()
 });
-var HistoryPolicy = z3.enum(["full", "pending_only", "none"]);
+var HistoryPolicy = z3.enum([
+  "full",
+  "pending_only",
+  "none",
+  "after_message"
+]);
 var SessionNewParams = z3.object({
   cwd: z3.string(),
   agentId: z3.string().optional(),
@@ -884,6 +900,18 @@ var SessionResumeHints = z3.object({
 var SessionAttachParams = z3.object({
   sessionId: z3.string(),
   historyPolicy: HistoryPolicy.default("full"),
+  // Required when historyPolicy is "after_message"; ignored otherwise.
+  // The proxy replays history entries strictly after the entry whose
+  // messageId matches this value. If the id isn't found in the buffer,
+  // the response.historyPolicy field surfaces "full" so the caller
+  // knows we fell back. Per RFD #533.
+  afterMessageId: z3.string().optional(),
+  // Caller-assigned opaque id (e.g. a UUID). When provided, the proxy
+  // echoes it in resolvedBy/sentBy and lifecycle events so other
+  // clients can disambiguate multiple instances of the same
+  // clientInfo.name. When omitted, the proxy assigns one and returns
+  // it in the response. Per RFD #533.
+  clientId: z3.string().optional(),
   clientInfo: z3.object({
     name: z3.string(),
     version: z3.string().optional()
@@ -1385,6 +1413,9 @@ function hydraCommandsAsAdvertised() {
 var HYDRA_ID_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 var generateHydraId = customAlphabet(HYDRA_ID_ALPHABET, 16);
 var HYDRA_SESSION_PREFIX = "hydra_session_";
+function generateMessageId() {
+  return `m_${generateHydraId()}`;
+}
 var DEFAULT_HISTORY_MAX_ENTRIES = 1e3;
 var Session = class {
   sessionId;
@@ -1559,6 +1590,30 @@ var Session = class {
   get attachedCount() {
     return this.clients.size;
   }
+  // Roster of currently-attached clients, optionally excluding one
+  // clientId. Used by the daemon to populate connectedClients on the
+  // session/attach response (per RFD #533) — the freshly-attaching
+  // client wants to see who else is on the session but not itself in
+  // the list.
+  connectedClients(excludeClientId) {
+    const out = [];
+    for (const client of this.clients.values()) {
+      if (excludeClientId && client.clientId === excludeClientId) {
+        continue;
+      }
+      const entry = {
+        clientId: client.clientId
+      };
+      if (client.clientInfo?.name) {
+        entry.name = client.clientInfo.name;
+      }
+      if (client.clientInfo?.version) {
+        entry.version = client.clientInfo.version;
+      }
+      out.push(entry);
+    }
+    return out;
+  }
   // Wall-clock when the in-flight agent turn began, or undefined when
   // idle. Tracked in-memory by broadcastPromptReceived/broadcastTurnComplete
   // so the daemon can hand a fresh attacher mid-turn the right elapsed
@@ -1590,10 +1645,12 @@ var Session = class {
     };
   }
   // Register a client and (asynchronously) load the replay slice it
-  // should receive. Validation errors throw synchronously so callers
-  // can rely on either the registration being in effect or having
-  // thrown; the disk-load is the only async work.
-  attach(client, historyPolicy) {
+  // should receive. Returns both the slice to replay and the actual
+  // historyPolicy applied (which may differ from the requested one
+  // when after_message falls back to full). Validation errors throw
+  // synchronously so callers can rely on either the registration being
+  // in effect or having thrown; the disk-load is the only async work.
+  attach(client, historyPolicy, opts = {}) {
     if (this.closed) {
       throw withCode(
         new Error("session is closed"),
@@ -1609,9 +1666,20 @@ var Session = class {
     this.clients.set(client.clientId, client);
     this.updatedAt = Date.now();
     if (historyPolicy === "none" || historyPolicy === "pending_only") {
-      return Promise.resolve([]);
+      return Promise.resolve({ entries: [], appliedPolicy: historyPolicy });
+    }
+    return this.loadReplay(historyPolicy, opts);
+  }
+  async loadReplay(historyPolicy, opts) {
+    const all = await this.getHistorySnapshot();
+    if (historyPolicy === "after_message") {
+      const cutoff = opts.afterMessageId ? findMessageIdIndex(all, opts.afterMessageId) : -1;
+      if (cutoff < 0) {
+        return { entries: all, appliedPolicy: "full" };
+      }
+      return { entries: all.slice(cutoff + 1), appliedPolicy: "after_message" };
     }
-    return this.getHistorySnapshot();
+    return { entries: all, appliedPolicy: "full" };
   }
   // Dispatch in-flight permission requests to a freshly-attached
   // client. Called by the daemon's WS handler *after* it finishes
@@ -1623,8 +1691,39 @@ var Session = class {
     }
   }
   detach(clientId) {
-    if (this.clients.delete(clientId)) {
-      this.updatedAt = Date.now();
+    const leaving = this.clients.get(clientId);
+    if (!leaving) {
+      return;
+    }
+    this.clients.delete(clientId);
+    this.updatedAt = Date.now();
+    this.broadcastClientDisconnected(leaving);
+  }
+  // Notify remaining attached clients that a peer just left, per
+  // RFD #533. Fires for both explicit session/detach and ws-close
+  // teardown (acp-ws calls Session.detach() in both paths). The
+  // notification is broadcast (not recorded) — peer presence is
+  // transient, not part of conversation history.
+  broadcastClientDisconnected(client) {
+    const info = {
+      clientId: client.clientId
+    };
+    if (client.clientInfo?.name) {
+      info.name = client.clientInfo.name;
+    }
+    if (client.clientInfo?.version) {
+      info.version = client.clientInfo.version;
+    }
+    const update = {
+      sessionUpdate: "client_disconnected",
+      client: info,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    for (const peer of this.clients.values()) {
+      void peer.connection.notify("session/update", {
+        sessionId: this.sessionId,
+        update
+      }).catch(() => void 0);
     }
   }
   async prompt(clientId, params) {
@@ -1677,6 +1776,7 @@ var Session = class {
         sessionId: this.sessionId,
         update: {
           sessionUpdate: "prompt_received",
+          messageId: generateMessageId(),
           prompt: promptParams.prompt,
           sentBy
         }
@@ -1702,7 +1802,8 @@ var Session = class {
   broadcastTurnComplete(originatorClientId, response) {
     const stopReason = response && typeof response === "object" && "stopReason" in response && typeof response.stopReason === "string" ? response.stopReason : void 0;
     const update = {
-      sessionUpdate: "turn_complete"
+      sessionUpdate: "turn_complete",
+      messageId: generateMessageId()
     };
     if (stopReason !== void 0) {
       update.stopReason = stopReason;
@@ -2319,10 +2420,11 @@ _(switched from \`${oldAgentId}\` to \`${newAgentId}\`)_
   recordAndBroadcast(method, params, excludeClientId) {
     const rewritten = this.rewriteForClient(params);
     const recordable = !isStateUpdate(method, rewritten);
+    const broadcast = recordable ? ensureMessageIdOnUpdate(method, rewritten) : rewritten;
     if (recordable) {
       const entry = {
         method,
-        params: rewritten,
+        params: broadcast,
         recordedAt: Date.now()
       };
       this.lastRecordedAt = entry.recordedAt;
@@ -2350,7 +2452,7 @@ _(switched from \`${oldAgentId}\` to \`${newAgentId}\`)_
       if (excludeClientId && client.clientId === excludeClientId) {
         continue;
       }
-      void client.connection.notify(method, rewritten).catch(() => void 0);
+      void client.connection.notify(method, broadcast).catch(() => void 0);
     }
   }
   async handlePermissionRequest(params) {
@@ -2362,11 +2464,13 @@ _(switched from \`${oldAgentId}\` to \`${newAgentId}\`)_
       );
     }
     const clientParams = this.rewriteForClient(params);
+    const toolCallId = extractToolCallId(clientParams);
     return new Promise((resolve3, reject) => {
       let settled = false;
       const outbound = [];
       const entry = { addClient: sendTo };
       this.inFlightPermissions.add(entry);
+      const sessionId = this.sessionId;
       const settle = (fn) => {
         if (settled) {
           return;
@@ -2379,22 +2483,25 @@ _(switched from \`${oldAgentId}\` to \`${newAgentId}\`)_
         if (settled) {
           return;
         }
-        const { id, response } = client.connection.requestWithId(
+        const response = client.connection.request(
           "session/request_permission",
           clientParams
         );
-        outbound.push({ client, id });
+        outbound.push({ client });
         void response.then((result) => {
           settle(() => {
+            const update = buildPermissionResolvedUpdate({
+              toolCallId,
+              result,
+              resolver: client
+            });
             for (const o of outbound) {
               if (o.client.clientId === client.clientId) {
                 continue;
               }
-              void o.client.connection.notify("session/permission_resolved", {
-                ...clientParams,
-                requestId: o.id,
-                resolvedBy: client.clientId,
-                result
+              void o.client.connection.notify("session/update", {
+                sessionId,
+                update
               }).catch(() => void 0);
             }
             resolve3(result);
@@ -2507,6 +2614,97 @@ function extractAdvertisedCommands(params) {
   }
   return out;
 }
+function ensureMessageIdOnUpdate(method, params) {
+  if (method !== "session/update" || !params || typeof params !== "object") {
+    return params;
+  }
+  const p = params;
+  if (!p.update || typeof p.update !== "object" || Array.isArray(p.update)) {
+    return params;
+  }
+  const u = p.update;
+  if (typeof u.messageId === "string") {
+    return params;
+  }
+  return {
+    ...params,
+    update: { ...p.update, messageId: generateMessageId() }
+  };
+}
+function findMessageIdIndex(history, target) {
+  for (let i = 0; i < history.length; i++) {
+    const entry = history[i];
+    if (!entry || entry.method !== "session/update") {
+      continue;
+    }
+    const params = entry.params;
+    if (params?.update?.messageId === target) {
+      return i;
+    }
+  }
+  return -1;
+}
+function extractToolCallId(params) {
+  if (!params || typeof params !== "object") {
+    return void 0;
+  }
+  const toolCall = params.toolCall;
+  if (!toolCall || typeof toolCall !== "object") {
+    return void 0;
+  }
+  const id = toolCall.toolCallId;
+  return typeof id === "string" ? id : void 0;
+}
+function buildPermissionResolvedUpdate(args) {
+  const outcome = extractOutcome(args.result);
+  const update = {
+    sessionUpdate: "permission_resolved"
+  };
+  if (args.toolCallId !== void 0) {
+    update.toolCallId = args.toolCallId;
+  }
+  if (outcome) {
+    update.outcome = outcome;
+    if (outcome.kind === "selected" && typeof outcome.optionId === "string") {
+      update.chosenOptionId = outcome.optionId;
+    }
+  }
+  update.resolvedBy = buildResolvedBy(args.resolver);
+  return update;
+}
+function extractOutcome(result) {
+  if (!result || typeof result !== "object") {
+    return void 0;
+  }
+  const raw = result.outcome;
+  if (!raw || typeof raw !== "object") {
+    return void 0;
+  }
+  const kind = raw.kind;
+  if (typeof kind !== "string") {
+    return void 0;
+  }
+  const out = { kind };
+  const optionId = raw.optionId;
+  if (typeof optionId === "string") {
+    out.optionId = optionId;
+  }
+  const reason = raw.reason;
+  if (typeof reason === "string") {
+    out.reason = reason;
+  }
+  return out;
+}
+function buildResolvedBy(client) {
+  const out = { clientId: client.clientId };
+  if (client.clientInfo?.name) {
+    out.name = client.clientInfo.name;
+  }
+  if (client.clientInfo?.version) {
+    out.version = client.clientInfo.version;
+  }
+  return out;
+}
 function extractPromptText(prompt) {
   if (typeof prompt === "string") {
     return prompt;
@@ -4283,7 +4481,7 @@ function registerSessionRoutes(app, manager, defaults) {
     const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
     reply.header(
       "Content-Disposition",
-      `attachment; filename="hydra-${id}-${stamp}.hydra"`
+      `attachment; filename="${id}-${stamp}.hydra"`
     );
     reply.code(200).send(bundle);
   });
@@ -4718,15 +4916,20 @@ function registerAcpWsEndpoint(app, deps) {
         connection,
         session,
         state,
-        params.clientInfo
+        params.clientInfo,
+        params.clientId
+      );
+      const { entries: replay, appliedPolicy } = await session.attach(
+        client,
+        params.historyPolicy,
+        { afterMessageId: params.afterMessageId }
       );
-      const replay = await session.attach(client, params.historyPolicy);
       state.attached.set(session.sessionId, {
         sessionId: session.sessionId,
         clientId: client.clientId
       });
       app.log.info(
-        `session/attach OK sessionId=${session.sessionId} clientId=${client.clientId} attachedCount=${state.attached.size} replayed=${replay.length}`
+        `session/attach OK sessionId=${session.sessionId} clientId=${client.clientId} attachedCount=${state.attached.size} requestedPolicy=${params.historyPolicy} appliedPolicy=${appliedPolicy} replayed=${replay.length}`
       );
       for (const note of replay) {
         await connection.notify(note.method, note.params);
@@ -4734,6 +4937,13 @@ function registerAcpWsEndpoint(app, deps) {
       session.replayPendingPermissions(client);
       return {
         sessionId: session.sessionId,
+        clientId: client.clientId,
+        connectedClients: session.connectedClients(client.clientId),
+        // appliedPolicy surfaces whether after_message fell back to full
+        // (because afterMessageId wasn't found in history) — RFD #533
+        // says the response.historyPolicy should reflect what actually
+        // ran, not what was asked for.
+        historyPolicy: appliedPolicy,
         replayed: replay.length,
         _meta: buildResponseMeta(session)
       };
@@ -4749,7 +4959,7 @@ function registerAcpWsEndpoint(app, deps) {
       const session = deps.manager.get(params.sessionId);
       session?.detach(att.clientId);
       state.attached.delete(params.sessionId);
-      return { detached: true };
+      return { sessionId: params.sessionId, status: "detached" };
     });
     connection.onRequest("session/list", async (raw) => {
       const params = SessionListParams.parse(raw ?? {});
@@ -4822,7 +5032,7 @@ function registerAcpWsEndpoint(app, deps) {
         session = await deps.manager.resurrect(fromDisk);
       }
       const client = bindClientToSession(connection, session, state);
-      const replay = await session.attach(client, "pending_only");
+      const { entries: replay } = await session.attach(client, "pending_only");
       state.attached.set(session.sessionId, {
         sessionId: session.sessionId,
         clientId: client.clientId
@@ -4916,11 +5126,11 @@ function buildInitializeResult() {
     ]
   };
 }
-function bindClientToSession(connection, session, state, clientInfo) {
+function bindClientToSession(connection, session, state, clientInfo, callerClientId) {
   void state;
   void session;
   return {
-    clientId: `cli_${nanoid2(8)}`,
+    clientId: callerClientId ?? `cli_${nanoid2(8)}`,
     connection,
     clientInfo
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydra-acp/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Multi-client ACP session daemon: spawn agents, attach over WSS, multiplex sessions across editors.",
   "license": "MIT",
   "type": "module",