@linkedclaw/consumer-runtime 0.9.2 → 0.10.0

package/dist/index.d.ts

@@ -6,20 +6,34 @@ interface HireParams {
     maxMessages?: number;
     referredBy?: string;
     autoActivate?: boolean;
-    /** Override the default relay URL (defaults to the cloud relay /ws endpoint). */
+    /** Override the default relay URL (only used when ``tryAcp: true``). */
     relayUrl?: string;
     /**
-     * Try /acp (OpenClaw sub-agent bridge) before /ws. Default false — mirrors
-     * `SkillConfig.try_acp = False` on the provider side (upstream commit
-     * 2dbc36c). Native providers register on /ws and are reachable there; only
-     * opt in when the target is an ACP-routed agent (OpenClaw sub-agent). When
-     * opted in, falls back to /ws if /acp connect fails or the recipient is
-     * absent from /acp's connection table.
+     * Try /acp (OpenClaw sub-agent bridge) before /ws. Default false.
+     *
+     * **Default flow (recommended)** — no WS opens at all on the requester side:
+     * `POST /sessions` → `POST /activate`. The cloud drives the
+     * SESSION_CREATE/ACCEPT handshake to the provider on its own (relay's
+     * `deliver_session_create_and_await_accept`, upstream `1f1b363f`). The
+     * /activate call returns 200 once the provider accepts, with timing /
+     * failure surfaced as 503 / 408 / 403 status codes.
+     *
+     * **Opt-in WS path (`tryAcp: true`)** — only needed for OpenClaw
+     * sub-agent / ACP-routed agents. Opens a transient WS to /acp first
+     * (2s connect timeout); falls back to /ws if /acp connect fails or
+     * the recipient is absent from /acp's connection table. When this
+     * path runs, /activate sees the in-memory session as already active
+     * and short-circuits.
      */
     tryAcp?: boolean;
-    /** API key + agent ID for the IDENTIFY frame. */
+    /** API key (Bearer token + WS IDENTIFY token when tryAcp is enabled). */
     apiKey: string;
-    agentId: string;
+    /**
+     * Required only when `tryAcp: true` — the WS IDENTIFY frame validates
+     * `listing.owner_id == user_id` against this string. Default HTTP path
+     * does not need a registered listing — leave undefined.
+     */
+    agentId?: string;
 }
 interface HireResult {
     session: Session;
@@ -37,11 +51,15 @@ declare class RequesterFlows {
         sort?: string;
     }): Promise<Agent[]>;
     /**
-     * Open a session. HTTP create → WS handshake (SESSION_CREATE/ACCEPT) → done.
+     * Open a session.
+     *
+     * Default: pure HTTP — `POST /sessions` then `POST /activate`. Cloud
+     * drives the SESSION_CREATE handshake to the provider server-side. No
+     * WebSocket opens on the requester side; no `agentId` registration
+     * required.
      *
-     * Default transport is /ws — native providers register there
-     * (`SkillConfig.try_acp=False` upstream default). Set `tryAcp: true` to try
-     * /acp first; on opt-in, falls back to /ws when the recipient isn't on /acp.
+     * `tryAcp: true` opts into the legacy WS handshake path for OpenClaw
+     * sub-agent / ACP-routed scenarios — see {@link HireParams.tryAcp}.
      */
     hire(params: HireParams): Promise<HireResult>;
     private attemptHandshake;

package/dist/index.js

@@ -25,11 +25,15 @@ var RequesterFlows = class {
     return this.client.discover({ capability, ...extra });
   }
   /**
-   * Open a session. HTTP create → WS handshake (SESSION_CREATE/ACCEPT) → done.
+   * Open a session.
    *
-   * Default transport is /ws — native providers register there
-   * (`SkillConfig.try_acp=False` upstream default). Set `tryAcp: true` to try
-   * /acp first; on opt-in, falls back to /ws when the recipient isn't on /acp.
+   * Default: pure HTTP — `POST /sessions` then `POST /activate`. Cloud
+   * drives the SESSION_CREATE handshake to the provider server-side. No
+   * WebSocket opens on the requester side; no `agentId` registration
+   * required.
+   *
+   * `tryAcp: true` opts into the legacy WS handshake path for OpenClaw
+   * sub-agent / ACP-routed scenarios — see {@link HireParams.tryAcp}.
    */
   async hire(params) {
     const session = await this.client.createSession({
@@ -39,9 +43,9 @@ var RequesterFlows = class {
       ...params.referredBy !== void 0 ? { referred_by: params.referredBy } : {}
     });
     if (params.autoActivate === false) return { session, activated: false };
-    const relayUrl = params.relayUrl ?? DEFAULT_RELAY_URL;
     try {
       if (params.tryAcp) {
+        const relayUrl = params.relayUrl ?? DEFAULT_RELAY_URL;
         const acpUrl = relayUrl.replace(/\/ws$/, "/acp");
         try {
           await this.attemptHandshake(acpUrl, session.session_id, params, ACP_CONNECT_TIMEOUT_MS);
@@ -49,9 +53,8 @@ var RequesterFlows = class {
           if (!(err instanceof TransportMissError)) throw err;
           await this.attemptHandshake(relayUrl, session.session_id, params, SESSION_ACCEPT_TIMEOUT_MS);
         }
-      } else {
-        await this.attemptHandshake(relayUrl, session.session_id, params, SESSION_ACCEPT_TIMEOUT_MS);
       }
+      await this.client.activateSession(session.session_id);
     } catch (err) {
       await this.client.endSession(session.session_id, {}).catch(() => {
       });
@@ -62,7 +65,14 @@ var RequesterFlows = class {
     }
     return { session, activated: true };
   }
+  // tryAcp:true path only. Default `hire()` no longer calls this — see the
+  // method comment on `hire`. Kept for OpenClaw sub-agent integration.
   async attemptHandshake(url, sessionId, params, connectTimeoutMs) {
+    if (!params.agentId) {
+      throw new Error(
+        "attemptHandshake (tryAcp:true) requires `agentId` in HireParams \u2014 the WS IDENTIFY frame validates listing ownership. Use the default HTTP path (omit tryAcp) if you don't have a registered agent listing."
+      );
+    }
     const ws = new WebSocket(url);
     try {
       await new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedclaw/consumer-runtime",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Runtime helpers (RequesterFlows, ACP) for LinkedClaw consumer agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,7 +23,7 @@
   "dependencies": {
     "ws": "^8.18.0",
     "zod": "^3.23.0",
-    "@linkedclaw/consumer": "^0.9.1",
+    "@linkedclaw/consumer": "^0.9.2",
     "@linkedclaw/provider": "^0.9.1"
   },
   "devDependencies": {