agenthub-multiagent-mcp 1.52.0 → 1.53.0

package/dist/tools/sessionControl.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session steering + takeover MCP tools (add-multiplayer-sessions).
+ *
+ * §4.7 `session_steer` (+ the `session_steers` read that makes its
+ * pending → applied lifecycle observable) and §5.9 `session_claim` /
+ * `session_release`.
+ *
+ * These front the same server endpoints the dashboard uses. Every failure the
+ * server can legitimately return — the session cannot accept injection, someone
+ * else already holds the claim, the feature is switched off — is surfaced as a
+ * structured, non-throwing refusal so the caller can tell them apart. A steer
+ * that was refused must never read as a steer that was accepted.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ApiClient, SessionControlResult } from "../client.js";
+/** Tool names handled by this module. */
+export declare const SESSION_CONTROL_TOOLS: readonly ["session_steer", "session_steers", "session_claim", "session_release"];
+export type SessionControlToolName = (typeof SESSION_CONTROL_TOOLS)[number];
+/** True when `name` is one of this module's tools. */
+export declare function isSessionControlTool(name: string): name is SessionControlToolName;
+export declare function registerSessionControlTools(): Tool[];
+/** Structured refusal returned to the model instead of a thrown error. */
+export interface SessionControlFailure {
+    ok: false;
+    error: string;
+    status: number;
+    message: string;
+    /** Why a session cannot be steered (server-supplied). */
+    reason?: string;
+    /** Who currently holds the claim (server-supplied). */
+    holder?: string;
+}
+/**
+ * Turn a failed session-control call into a refusal the model can act on.
+ *
+ * Each known code gets its own sentence because they demand different
+ * responses: a disabled feature is not a permission problem, a lost claim race
+ * is not an outage, and a non-injectable session will never accept a retry.
+ * Unknown codes still carry the HTTP status so a bare 405 or an HTML proxy page
+ * is diagnosable rather than mysterious.
+ */
+export declare function describeSessionControlFailure(tool: string, sessionId: string, result: Extract<SessionControlResult, {
+    ok: false;
+}>): SessionControlFailure;
+/**
+ * Handle a session steer/control tool call.
+ *
+ * Returns a plain object; transport/permission/feature-gate failures come back
+ * as `{ok:false,...}` rather than exceptions so the model sees the distinction
+ * between "refused" and "crashed".
+ */
+export declare function handleSessionControlToolCall(name: SessionControlToolName, args: Record<string, unknown>, client: ApiClient): Promise<unknown>;
+//# sourceMappingURL=sessionControl.d.ts.map

package/dist/tools/sessionControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionControl.d.ts","sourceRoot":"","sources":["../../src/tools/sessionControl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpE,yCAAyC;AACzC,eAAO,MAAM,qBAAqB,kFAKxB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,sBAAsB,CAEjF;AAKD,wBAAgB,2BAA2B,IAAI,IAAI,EAAE,CAiFpD;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,CAAC,oBAAoB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,GACnD,qBAAqB,CAwDvB;AAED;;;;;;GAMG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,sBAAsB,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,OAAO,CAAC,CAuFlB"}

package/dist/tools/sessionControl.js

@@ -0,0 +1,265 @@
+/**
+ * Session steering + takeover MCP tools (add-multiplayer-sessions).
+ *
+ * §4.7 `session_steer` (+ the `session_steers` read that makes its
+ * pending → applied lifecycle observable) and §5.9 `session_claim` /
+ * `session_release`.
+ *
+ * These front the same server endpoints the dashboard uses. Every failure the
+ * server can legitimately return — the session cannot accept injection, someone
+ * else already holds the claim, the feature is switched off — is surfaced as a
+ * structured, non-throwing refusal so the caller can tell them apart. A steer
+ * that was refused must never read as a steer that was accepted.
+ */
+/** Tool names handled by this module. */
+export const SESSION_CONTROL_TOOLS = [
+    "session_steer",
+    "session_steers",
+    "session_claim",
+    "session_release",
+];
+/** True when `name` is one of this module's tools. */
+export function isSessionControlTool(name) {
+    return SESSION_CONTROL_TOOLS.includes(name);
+}
+const SESSION_ID_DESCRIPTION = "Session UUID or display number `s-YYYYMMDD-NNN` (e.g. s-20260725-001). Both forms are accepted.";
+export function registerSessionControlTools() {
+    return [
+        {
+            name: "session_steer",
+            description: "Send a human instruction into a live agent session (add-multiplayer-sessions §4). " +
+                "STEERING IS ASYNCHRONOUS: a successful call QUEUES the instruction and returns status " +
+                "`pending`. The session has not read or obeyed it yet — it flips to `applied` only when the " +
+                "session consumes it as its next turn. Never report a pending steer as done; use " +
+                "`session_steers` to see whether it was applied. " +
+                "Failure modes are distinct and are returned as `{ok:false, error, status}` rather than thrown: " +
+                "`session_not_injectable` (409) means this session physically cannot be steered — one-shot " +
+                "`claude -p` shifts have no channel to inject into — and the server's `reason` explains which; " +
+                "`session_steer_disabled` (503) means the steering feature is switched off on this server, which " +
+                "is not a permission problem and not something a retry fixes. " +
+                "Use `session_claim` first if you need the agent to stop taking its own turns.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: SESSION_ID_DESCRIPTION },
+                    text: {
+                        type: "string",
+                        description: "The instruction to inject, written as a direct instruction to the session " +
+                            "(e.g. 'stop refactoring and fix the failing test first').",
+                    },
+                },
+                required: ["session_id", "text"],
+            },
+        },
+        {
+            name: "session_steers",
+            description: "List the steers recorded against a session and their status (`pending` = queued, not yet seen " +
+                "by the session; `applied` = consumed as a turn). Read-only. Use this to confirm whether a " +
+                "`session_steer` actually took effect instead of assuming it did.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: SESSION_ID_DESCRIPTION },
+                },
+                required: ["session_id"],
+            },
+        },
+        {
+            name: "session_claim",
+            description: "Take over a live session (add-multiplayer-sessions §5). On success the agent stops consuming " +
+                "new turns and the session becomes `human_driven`; your instructions become its turns. " +
+                "A CLAIM IS A LEASE, NOT A LOCK: it carries an `expires_at` and is released automatically when " +
+                "it expires, so a holder that walks away cannot strand the session. This tool does NOT renew the " +
+                "lease and there is no MCP renewal — plan to finish and call `session_release` before " +
+                "`expires_at`, or expect control to revert to the agent at that time. Long human takeovers " +
+                "belong in the dashboard, which renews on a timer. " +
+                "The claim is atomic: if someone already holds it you get `{ok:false, error:'session_already_claimed'}` " +
+                "(409) naming the current `holder` — that is a normal race outcome, not a bug. " +
+                "Because a claim only takes effect after the agent's in-flight turn completes, the session may " +
+                "report `draining` before it reports `human_driven`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: SESSION_ID_DESCRIPTION },
+                },
+                required: ["session_id"],
+            },
+        },
+        {
+            name: "session_release",
+            description: "Hand a claimed session back to its agent (add-multiplayer-sessions §5). The session returns to " +
+                "`agent_driven` and the agent resumes consuming queued turns. Call this as soon as you are done " +
+                "with a takeover — do not rely on the lease expiring.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: SESSION_ID_DESCRIPTION },
+                },
+                required: ["session_id"],
+            },
+        },
+    ];
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${key} is required`);
+    }
+    return value;
+}
+function str(data, key) {
+    const value = data[key];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Turn a failed session-control call into a refusal the model can act on.
+ *
+ * Each known code gets its own sentence because they demand different
+ * responses: a disabled feature is not a permission problem, a lost claim race
+ * is not an outage, and a non-injectable session will never accept a retry.
+ * Unknown codes still carry the HTTP status so a bare 405 or an HTML proxy page
+ * is diagnosable rather than mysterious.
+ */
+export function describeSessionControlFailure(tool, sessionId, result) {
+    const { status, error, holder, reason } = result;
+    const serverMessage = result.message;
+    let message;
+    switch (error) {
+        case "session_not_injectable":
+            message =
+                `REFUSED: session ${sessionId} cannot accept a steer` +
+                    (reason ? ` — ${reason}` : serverMessage ? ` — ${serverMessage}` : "") +
+                    `. Nothing was queued and the session was never told anything. Sessions that ` +
+                    `cannot accept injection (one-shot \`claude -p\` shifts have no transport to ` +
+                    `inject into) will not accept a retry either.`;
+            break;
+        case "session_already_claimed":
+            message =
+                `REFUSED: session ${sessionId} is already claimed by ${holder || "another user"}` +
+                    `. You do not have control. Wait for them to release it (or for their lease ` +
+                    `to expire) before claiming again.`;
+            break;
+        case "session_steer_disabled":
+        case "session_streaming_disabled":
+        case "session_control_disabled":
+            message =
+                `UNAVAILABLE: this AgentHub server has the session ${error === "session_steer_disabled" ? "steering" : "multiplayer session"} feature switched off (${error}, HTTP ${status}). This is a server ` +
+                    `configuration state, not a permission denial and not a missing session — ` +
+                    `an operator must enable it. Do not retry.`;
+            break;
+        case "session_not_found":
+            message = `Session ${sessionId} was not found (HTTP ${status}). Check the id or display number.`;
+            break;
+        default:
+            if (status === 401 || status === 403) {
+                message =
+                    `DENIED: not permitted to ${tool.replace("session_", "")} session ${sessionId} ` +
+                        `(${error}, HTTP ${status})${serverMessage ? `: ${serverMessage}` : ""}.`;
+            }
+            else if (status === 404) {
+                message = `Session ${sessionId} was not found (HTTP ${status}).`;
+            }
+            else {
+                message =
+                    serverMessage ||
+                        result.detail ||
+                        `${tool} failed: ${error} (HTTP ${status}).`;
+            }
+    }
+    return {
+        ok: false,
+        error,
+        status,
+        message,
+        ...(reason ? { reason } : {}),
+        ...(holder ? { holder } : {}),
+    };
+}
+/**
+ * Handle a session steer/control tool call.
+ *
+ * Returns a plain object; transport/permission/feature-gate failures come back
+ * as `{ok:false,...}` rather than exceptions so the model sees the distinction
+ * between "refused" and "crashed".
+ */
+export async function handleSessionControlToolCall(name, args, client) {
+    const sessionId = requireString(args, "session_id");
+    switch (name) {
+        case "session_steer": {
+            const text = requireString(args, "text");
+            const result = await client.steerSession(sessionId, text);
+            if (!result.ok)
+                return describeSessionControlFailure(name, sessionId, result);
+            // The server answers 202 Accepted with status "pending". Report exactly
+            // that: the instruction is queued, the session has not acted on it.
+            const status = str(result.data, "status") || "pending";
+            const steerId = str(result.data, "steer_id") || "";
+            return {
+                ok: true,
+                session_id: sessionId,
+                steer_id: steerId,
+                status,
+                applied: status === "applied",
+                message: `Steer queued for session ${sessionId}${steerId ? ` (steer ${steerId})` : ""} — ` +
+                    `status ${status}. ` +
+                    (status === "applied"
+                        ? "The session has consumed it."
+                        : "The session has NOT seen it yet; it applies when the session takes its next turn. " +
+                            "Call session_steers to check whether it flipped to applied."),
+            };
+        }
+        case "session_steers": {
+            const result = await client.listSessionSteers(sessionId);
+            if (!result.ok)
+                return describeSessionControlFailure(name, sessionId, result);
+            const raw = result.data.steers;
+            const steers = Array.isArray(raw) ? raw : [];
+            const pending = steers.filter((s) => s?.status === "pending").length;
+            return {
+                ok: true,
+                session_id: sessionId,
+                count: steers.length,
+                pending_count: pending,
+                steers,
+                message: `${steers.length} steer(s) on session ${sessionId}; ${pending} still pending (not yet seen by the session).`,
+            };
+        }
+        case "session_claim": {
+            const result = await client.claimSession(sessionId);
+            if (!result.ok)
+                return describeSessionControlFailure(name, sessionId, result);
+            const state = str(result.data, "state") || "human_driven";
+            const holder = str(result.data, "holder") || "";
+            const expiresAt = str(result.data, "expires_at") || "";
+            return {
+                ok: true,
+                session_id: sessionId,
+                state,
+                holder,
+                expires_at: expiresAt,
+                message: `Claimed session ${sessionId}${holder ? ` as ${holder}` : ""} — state ${state}. ` +
+                    (state === "draining"
+                        ? "The agent is finishing its in-flight turn; the claim takes effect once it does. "
+                        : "") +
+                    (expiresAt
+                        ? `This is a LEASE and it expires at ${expiresAt}; it is not renewed by this tool, so ` +
+                            `control reverts to the agent then unless you release it first. `
+                        : `This is a LEASE and expires without renewal; this tool does not renew it. `) +
+                    `Call session_release when you are done.`,
+            };
+        }
+        case "session_release": {
+            const result = await client.releaseSession(sessionId);
+            if (!result.ok)
+                return describeSessionControlFailure(name, sessionId, result);
+            const state = str(result.data, "state") || "agent_driven";
+            return {
+                ok: true,
+                session_id: sessionId,
+                state,
+                message: `Released session ${sessionId} — state ${state}. The agent resumes consuming its queued turns.`,
+            };
+        }
+    }
+}
+//# sourceMappingURL=sessionControl.js.map

package/dist/tools/sessionControl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionControl.js","sourceRoot":"","sources":["../../src/tools/sessionControl.ts"],"names":[],"mappings":"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"}

package/dist/tools/sessionControl.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit tests for the session steering + takeover MCP tools.
+ * add-multiplayer-sessions §4.7 (`session_steer`) and §5.9
+ * (`session_claim`, `session_release`).
+ *
+ * Two layers are exercised:
+ *  - the tool handlers, against a mocked ApiClient, for result/refusal shaping;
+ *  - the real ApiClient with global `fetch` stubbed, for the wire contract
+ *    (paths, body, id passthrough) and the non-JSON-error-body regression
+ *    guarded by fix-mcp-nonjson-error-handling.
+ * No live server is required by either.
+ */
+export {};
+//# sourceMappingURL=sessionControl.test.d.ts.map

package/dist/tools/sessionControl.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionControl.test.d.ts","sourceRoot":"","sources":["../../src/tools/sessionControl.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/tools/sessionControl.test.js

@@ -0,0 +1,298 @@
+/**
+ * Unit tests for the session steering + takeover MCP tools.
+ * add-multiplayer-sessions §4.7 (`session_steer`) and §5.9
+ * (`session_claim`, `session_release`).
+ *
+ * Two layers are exercised:
+ *  - the tool handlers, against a mocked ApiClient, for result/refusal shaping;
+ *  - the real ApiClient with global `fetch` stubbed, for the wire contract
+ *    (paths, body, id passthrough) and the non-JSON-error-body regression
+ *    guarded by fix-mcp-nonjson-error-handling.
+ * No live server is required by either.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { registerSessionControlTools, handleSessionControlToolCall, isSessionControlTool, } from "./sessionControl.js";
+import { ApiClient } from "../client.js";
+const SESSION_UUID = "3f1c0c2e-1a4b-4a5f-9f01-2f3b4c5d6e7f";
+const SESSION_DISPLAY = "s-20260725-001";
+function buildMockClient(overrides = {}) {
+    return {
+        steerSession: vi.fn(),
+        listSessionSteers: vi.fn(),
+        claimSession: vi.fn(),
+        releaseSession: vi.fn(),
+        ...overrides,
+    };
+}
+function ok(data, status = 200) {
+    return { ok: true, status, data };
+}
+// ─── registration ──────────────────────────────────────────────────────────
+describe("session control tool registration", () => {
+    it("registers session_steer, session_steers, session_claim and session_release", () => {
+        const names = registerSessionControlTools().map((t) => t.name);
+        expect(names).toEqual([
+            "session_steer",
+            "session_steers",
+            "session_claim",
+            "session_release",
+        ]);
+    });
+    it("requires session_id on every tool and text on session_steer", () => {
+        const tools = Object.fromEntries(registerSessionControlTools().map((t) => [t.name, t]));
+        for (const name of ["session_steer", "session_steers", "session_claim", "session_release"]) {
+            const schema = tools[name].inputSchema;
+            expect(schema.required).toContain("session_id");
+        }
+        expect(tools.session_steer.inputSchema.required).toContain("text");
+    });
+    it("tells the reader that steering is asynchronous and that a claim is an expiring lease", () => {
+        const tools = Object.fromEntries(registerSessionControlTools().map((t) => [t.name, t]));
+        expect(tools.session_steer.description).toMatch(/ASYNCHRONOUS/);
+        expect(tools.session_steer.description).toMatch(/pending/);
+        expect(tools.session_claim.description).toMatch(/LEASE/);
+        expect(tools.session_claim.description).toMatch(/expires/i);
+        expect(tools.session_claim.description).toMatch(/does NOT renew/);
+    });
+    it("claims only its own tool names", () => {
+        expect(isSessionControlTool("session_steer")).toBe(true);
+        expect(isSessionControlTool("session_claim")).toBe(true);
+        expect(isSessionControlTool("session_get")).toBe(false);
+    });
+});
+// ─── session_steer ─────────────────────────────────────────────────────────
+describe("session_steer", () => {
+    it("reports a queued steer as pending, not as applied", async () => {
+        const client = buildMockClient({
+            steerSession: vi
+                .fn()
+                .mockResolvedValue(ok({ steer_id: "st-1", status: "pending" }, 202)),
+        });
+        const result = (await handleSessionControlToolCall("session_steer", { session_id: SESSION_UUID, text: "stop and fix the failing test" }, client));
+        expect(result.ok).toBe(true);
+        expect(result.status).toBe("pending");
+        expect(result.applied).toBe(false);
+        expect(result.steer_id).toBe("st-1");
+        expect(String(result.message)).toMatch(/has NOT seen it yet/);
+        expect(client.steerSession).toHaveBeenCalledWith(SESSION_UUID, "stop and fix the failing test");
+    });
+    it("surfaces 409 session_not_injectable as a refusal carrying the server reason", async () => {
+        const client = buildMockClient({
+            steerSession: vi.fn().mockResolvedValue({
+                ok: false,
+                status: 409,
+                error: "session_not_injectable",
+                reason: "one-shot -p shift has no injection transport",
+            }),
+        });
+        const result = (await handleSessionControlToolCall("session_steer", { session_id: SESSION_DISPLAY, text: "switch branches" }, client));
+        expect(result.ok).toBe(false);
+        expect(result.error).toBe("session_not_injectable");
+        expect(result.status).toBe(409);
+        expect(result.reason).toBe("one-shot -p shift has no injection transport");
+        expect(String(result.message)).toMatch(/REFUSED/);
+        expect(String(result.message)).toMatch(/one-shot -p shift has no injection transport/);
+        // A refusal must not read as an accepted steer.
+        expect(result).not.toHaveProperty("steer_id");
+        expect(result).not.toHaveProperty("applied");
+        expect(String(result.message)).not.toMatch(/Steer queued/);
+        expect(String(result.message)).toMatch(/Nothing was queued/);
+    });
+    it("reports 503 session_steer_disabled as the feature being off, not a permission or not-found error", async () => {
+        const client = buildMockClient({
+            steerSession: vi.fn().mockResolvedValue({
+                ok: false,
+                status: 503,
+                error: "session_steer_disabled",
+            }),
+        });
+        const result = (await handleSessionControlToolCall("session_steer", { session_id: SESSION_UUID, text: "hello" }, client));
+        expect(result.ok).toBe(false);
+        expect(result.error).toBe("session_steer_disabled");
+        expect(result.status).toBe(503);
+        const message = String(result.message);
+        expect(message).toMatch(/UNAVAILABLE/);
+        expect(message).toMatch(/switched off/);
+        expect(message).not.toMatch(/DENIED|not permitted|not found/i);
+    });
+    it("distinguishes a permission denial from the feature being off", async () => {
+        const client = buildMockClient({
+            steerSession: vi.fn().mockResolvedValue({
+                ok: false,
+                status: 403,
+                error: "forbidden",
+                message: "you do not own this session",
+            }),
+        });
+        const result = (await handleSessionControlToolCall("session_steer", { session_id: SESSION_UUID, text: "hello" }, client));
+        const message = String(result.message);
+        expect(message).toMatch(/DENIED/);
+        expect(message).not.toMatch(/switched off/);
+    });
+    it("rejects a missing or blank instruction before calling the server", async () => {
+        const client = buildMockClient();
+        await expect(handleSessionControlToolCall("session_steer", { session_id: SESSION_UUID }, client)).rejects.toThrow(/text is required/);
+        await expect(handleSessionControlToolCall("session_steer", { text: "x" }, client)).rejects.toThrow(/session_id is required/);
+        expect(client.steerSession).not.toHaveBeenCalled();
+    });
+});
+// ─── session_steers ────────────────────────────────────────────────────────
+describe("session_steers", () => {
+    it("counts pending steers so an applied steer is distinguishable", async () => {
+        const client = buildMockClient({
+            listSessionSteers: vi.fn().mockResolvedValue(ok({
+                steers: [
+                    { id: "st-1", text: "a", status: "applied", created_by: "u1" },
+                    { id: "st-2", text: "b", status: "pending", created_by: "u1" },
+                ],
+            })),
+        });
+        const result = (await handleSessionControlToolCall("session_steers", { session_id: SESSION_DISPLAY }, client));
+        expect(result.ok).toBe(true);
+        expect(result.count).toBe(2);
+        expect(result.pending_count).toBe(1);
+    });
+});
+// ─── session_claim ─────────────────────────────────────────────────────────
+describe("session_claim", () => {
+    it("returns the lease expiry and says plainly that the tool does not renew it", async () => {
+        const client = buildMockClient({
+            claimSession: vi.fn().mockResolvedValue(ok({
+                state: "human_driven",
+                holder: "user-sumit",
+                expires_at: "2026-07-25T12:00:00Z",
+            })),
+        });
+        const result = (await handleSessionControlToolCall("session_claim", { session_id: SESSION_UUID }, client));
+        expect(result.ok).toBe(true);
+        expect(result.state).toBe("human_driven");
+        expect(result.holder).toBe("user-sumit");
+        expect(result.expires_at).toBe("2026-07-25T12:00:00Z");
+        const message = String(result.message);
+        expect(message).toMatch(/LEASE/);
+        expect(message).toMatch(/2026-07-25T12:00:00Z/);
+        expect(message).toMatch(/not renewed by this tool/);
+    });
+    it("names the holder when the claim is lost with 409 session_already_claimed", async () => {
+        const client = buildMockClient({
+            claimSession: vi.fn().mockResolvedValue({
+                ok: false,
+                status: 409,
+                error: "session_already_claimed",
+                holder: "user-ankita",
+            }),
+        });
+        const result = (await handleSessionControlToolCall("session_claim", { session_id: SESSION_UUID }, client));
+        expect(result.ok).toBe(false);
+        expect(result.error).toBe("session_already_claimed");
+        expect(result.holder).toBe("user-ankita");
+        expect(String(result.message)).toMatch(/user-ankita/);
+        expect(String(result.message)).toMatch(/REFUSED/);
+    });
+    it("reports a draining claim as not yet in effect", async () => {
+        const client = buildMockClient({
+            claimSession: vi
+                .fn()
+                .mockResolvedValue(ok({ state: "draining", holder: "u", expires_at: "2026-07-25T12:00:00Z" })),
+        });
+        const result = (await handleSessionControlToolCall("session_claim", { session_id: SESSION_UUID }, client));
+        expect(result.state).toBe("draining");
+        expect(String(result.message)).toMatch(/in-flight turn/);
+    });
+});
+// ─── session_release ───────────────────────────────────────────────────────
+describe("session_release", () => {
+    it("reports the session back under agent control", async () => {
+        const client = buildMockClient({
+            releaseSession: vi.fn().mockResolvedValue(ok({ state: "agent_driven" })),
+        });
+        const result = (await handleSessionControlToolCall("session_release", { session_id: SESSION_DISPLAY }, client));
+        expect(result.ok).toBe(true);
+        expect(result.state).toBe("agent_driven");
+        expect(client.releaseSession).toHaveBeenCalledWith(SESSION_DISPLAY);
+    });
+});
+// ─── wire contract (real ApiClient, stubbed fetch) ─────────────────────────
+describe("ApiClient session control wire contract", () => {
+    let fetchMock;
+    function respond(body, status, contentType = "application/json") {
+        return new Response(body, { status, headers: { "Content-Type": contentType } });
+    }
+    beforeEach(() => {
+        fetchMock = vi.fn();
+        vi.stubGlobal("fetch", fetchMock);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("POSTs the steer body the server contract specifies", async () => {
+        fetchMock.mockResolvedValue(respond(JSON.stringify({ steer_id: "st-1", status: "pending" }), 202));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        const result = await client.steerSession(SESSION_UUID, "do the thing");
+        expect(result.ok).toBe(true);
+        const [url, init] = fetchMock.mock.calls[0];
+        expect(url).toBe(`https://agenthub.example.com/api/sessions/${SESSION_UUID}/steer`);
+        expect(init.method).toBe("POST");
+        expect(JSON.parse(init.body)).toEqual({
+            text: "do the thing",
+            message_type: "steer",
+        });
+    });
+    it("passes a display-number session id through unchanged", async () => {
+        fetchMock.mockResolvedValue(respond(JSON.stringify({ state: "human_driven" }), 200));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        await client.claimSession(SESSION_DISPLAY);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toBe(`https://agenthub.example.com/api/sessions/${SESSION_DISPLAY}/claim`);
+        expect(url).toContain(SESSION_DISPLAY);
+    });
+    it("passes a UUID session id through unchanged", async () => {
+        fetchMock.mockResolvedValue(respond(JSON.stringify({ state: "agent_driven" }), 200));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        await client.releaseSession(SESSION_UUID);
+        const [url] = fetchMock.mock.calls[0];
+        expect(url).toBe(`https://agenthub.example.com/api/sessions/${SESSION_UUID}/release`);
+    });
+    it("keeps the HTTP status when the error body is empty (chi's bare 405)", async () => {
+        fetchMock.mockResolvedValue(new Response("", { status: 405 }));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        const result = await client.steerSession(SESSION_UUID, "x");
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.status).toBe(405);
+        expect(result.error).toBe("http_405");
+        expect(String(result.detail)).toMatch(/405/);
+        expect(String(result.detail)).toMatch(/empty response body/);
+    });
+    it("keeps the HTTP status when the error body is HTML, not a JSON parse error", async () => {
+        fetchMock.mockResolvedValue(respond("<html><body>502 Bad Gateway</body></html>", 502, "text/html"));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        const result = await client.claimSession(SESSION_DISPLAY);
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            return;
+        expect(result.status).toBe(502);
+        expect(String(result.detail)).toMatch(/502/);
+        expect(String(result.detail)).toMatch(/Bad Gateway/);
+    });
+    it("surfaces a non-JSON failure through the tool with the status in the message", async () => {
+        fetchMock.mockResolvedValue(new Response("", { status: 405 }));
+        const client = new ApiClient("https://agenthub.example.com", "k");
+        const result = (await handleSessionControlToolCall("session_steer", { session_id: SESSION_UUID, text: "x" }, client));
+        expect(result.ok).toBe(false);
+        expect(String(result.message)).toMatch(/405/);
+    });
+    it("sends auth headers on session control calls", async () => {
+        fetchMock.mockResolvedValue(respond(JSON.stringify({ steers: [] }), 200));
+        const client = new ApiClient("https://agenthub.example.com", "org-key");
+        client.setConnectToken("ct-xyz");
+        await client.listSessionSteers(SESSION_UUID);
+        const [, init] = fetchMock.mock.calls[0];
+        const headers = init.headers;
+        expect(headers["X-API-Key"]).toBe("org-key");
+        expect(headers["X-Connect-Token"]).toBe("ct-xyz");
+        expect(headers["X-MCP-Version"]).toBeTruthy();
+    });
+});
+//# sourceMappingURL=sessionControl.test.js.map