refactor(sessions): add sessions.resolve + label helper (#570)

src/gateway/server-methods/sessions.ts

@@ -24,6 +24,7 @@ import {
   validateSessionsListParams,
   validateSessionsPatchParams,
   validateSessionsResetParams,
+  validateSessionsResolveParams,
 } from "../protocol/index.js";
 import {
   archiveFileOnDisk,
@@ -60,6 +61,122 @@ export const sessionsHandlers: GatewayRequestHandlers = {
     });
     respond(true, result, undefined);
   },
+  "sessions.resolve": ({ params, respond }) => {
+    if (!validateSessionsResolveParams(params)) {
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          `invalid sessions.resolve params: ${formatValidationErrors(validateSessionsResolveParams.errors)}`,
+        ),
+      );
+      return;
+    }
+    const p = params as import("../protocol/index.js").SessionsResolveParams;
+    const cfg = loadConfig();
+
+    const key = typeof p.key === "string" ? p.key.trim() : "";
+    const label = typeof p.label === "string" ? p.label.trim() : "";
+    const hasKey = key.length > 0;
+    const hasLabel = label.length > 0;
+    if (hasKey && hasLabel) {
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          "Provide either key or label (not both)",
+        ),
+      );
+      return;
+    }
+    if (!hasKey && !hasLabel) {
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          "Either key or label is required",
+        ),
+      );
+      return;
+    }
+
+    if (hasKey) {
+      if (!key) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, "key required"),
+        );
+        return;
+      }
+      const target = resolveGatewaySessionStoreTarget({ cfg, key });
+      const store = loadSessionStore(target.storePath);
+      const existingKey = target.storeKeys.find(
+        (candidate) => store[candidate],
+      );
+      if (!existingKey) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, `No session found: ${key}`),
+        );
+        return;
+      }
+      respond(true, { ok: true, key: target.canonicalKey }, undefined);
+      return;
+    }
+
+    if (!label) {
+      respond(
+        false,
+        undefined,
+        errorShape(ErrorCodes.INVALID_REQUEST, "label required"),
+      );
+      return;
+    }
+
+    const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
+    const list = listSessionsFromStore({
+      cfg,
+      storePath,
+      store,
+      opts: {
+        includeGlobal: p.includeGlobal === true,
+        includeUnknown: p.includeUnknown === true,
+        label,
+        agentId: p.agentId,
+        spawnedBy: p.spawnedBy,
+        limit: 2,
+      },
+    });
+    if (list.sessions.length === 0) {
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          `No session found with label: ${label}`,
+        ),
+      );
+      return;
+    }
+    if (list.sessions.length > 1) {
+      const keys = list.sessions.map((s) => s.key).join(", ");
+      respond(
+        false,
+        undefined,
+        errorShape(
+          ErrorCodes.INVALID_REQUEST,
+          `Multiple sessions found with label: ${label} (${keys})`,
+        ),
+      );
+      return;
+    }
+    respond(true, { ok: true, key: list.sessions[0]?.key }, undefined);
+  },
   "sessions.patch": async ({ params, respond, context }) => {
     if (!validateSessionsPatchParams(params)) {
       respond(