feat(sdk): add idempotency-key delegation to RemoteAgentClient

KI-002: prevent duplicate delegation execution when a remote agent
container restarts mid-delegation. Remote agent clients now compute a
SHA-256 key from task_text + current wall-clock minute and POST it as
idempotency_key to /workspaces/:id/delegate.

The platform deduplicates requests sharing the same key within the
minute window. Callers can also pass an explicit idempotency_key to
override the auto-computed value.

New:
- make_idempotency_key(task_text) → str
- RemoteAgentClient.delegate(task, target_id, idempotency_key=None, timeout=300.0)
- 8 new unit tests covering headers, errors, explicit key override, and
  make_idempotency_key invariants

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

molecule_agent/client.py

@@ -57,6 +57,35 @@ _RETRY_BASE_DELAY = 1.0              # seconds — first delay
 _RETRY_MAX_DELAY = 30.0              # seconds — cap
 _RETRY_JITTER_FRAC = 0.25            # ±25% jitter around base delay
 
+# KI-002 — idempotency key granularity: round to the current minute so
+# that concurrent restarts within the same 60-second window produce the
+# same key, while distinct tasks or distinct minutes produce distinct keys.
+_IDEMPOTENCY_ROUND_SECONDS = 60
+
+
+def make_idempotency_key(task_text: str) -> str:
+    """Compute a deterministic idempotency key for a delegation task.
+
+    Combines the task text with the current wall-clock minute to produce
+    a SHA-256 hex digest. Rounding to minute-level means two container
+    restarts within the same minute that send the same task string will
+    share the same key, preventing the platform from processing a duplicate
+    delegation. A different minute (or a different task string) yields a
+    different key.
+
+    Args:
+        task_text: The task description string being delegated.
+
+    Returns:
+        A 64-character hex string (SHA-256 digest).
+    """
+    # Round current time down to the nearest minute — same-task restarts
+    # within this minute share a key; after the minute rolls over the key
+    # changes so a genuinely new task is always treated as new.
+    now = int(time.time()) // _IDEMPOTENCY_ROUND_SECONDS * _IDEMPOTENCY_ROUND_SECONDS
+    payload = f"{task_text}:{now}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
 
 def _safe_extract_tar(tf: tarfile.TarFile, dest: Path) -> None:
     """Extract a tarfile, refusing entries that would escape `dest`
@@ -658,6 +687,58 @@ class RemoteAgentClient:
         resp.raise_for_status()
         return resp.json()
 
+    # ------------------------------------------------------------------
+    # Delegation — KI-002 idempotency guard
+    # ------------------------------------------------------------------
+
+    def delegate(
+        self,
+        task: str,
+        target_id: str,
+        idempotency_key: str | None = None,
+        timeout: float = 300.0,
+    ) -> dict[str, Any]:
+        """Delegate a task to a peer workspace via the platform proxy.
+
+        KI-002: To prevent duplicate execution when a container restarts mid-
+        delegation, an idempotency key is computed from ``task + current
+        minute`` and sent as ``idempotency_key`` in the request body. The
+        platform deduplicates requests sharing the same key within the
+        minute window. Pass an explicit ``idempotency_key`` to override the
+        auto-computed value (useful for callers that manage their own key
+        scheme).
+
+        Args:
+            task: Human-readable task description sent to the target.
+            target_id: Workspace ID of the peer to delegate to.
+            idempotency_key: Optional override for the idempotency key. If
+                omitted, one is auto-generated from the task text + current
+                wall-clock minute.
+            timeout: Request timeout in seconds. Default 300 s.
+
+        Returns:
+            The platform's JSON response dict.
+
+        Raises:
+            ``requests.HTTPError`` on non-2xx responses.
+        """
+        key = idempotency_key if idempotency_key else make_idempotency_key(task)
+        resp = self._session.post(
+            f"{self.platform_url}/workspaces/{target_id}/delegate",
+            headers={
+                **self._auth_headers(),
+                "X-Workspace-ID": self.workspace_id,
+                "Content-Type": "application/json",
+            },
+            json={
+                "task": task,
+                "idempotency_key": key,
+            },
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
     # ------------------------------------------------------------------
     # Plugin install (Phase 30.3)
     # ------------------------------------------------------------------
@@ -877,6 +958,39 @@ __all__ = [
     "DEFAULT_HEARTBEAT_INTERVAL",
     "DEFAULT_STATE_POLL_INTERVAL",
     "DEFAULT_URL_CACHE_TTL",
-    "compute_plugin_sha256",
-    "verify_plugin_sha256",
+# Retry-on-429 defaults for idempotent GET calls.
+# Matches the behaviour of the TypeScript MCP server's platformGet().
+DEFAULT_GET_MAX_RETRIES = 3          # retry up to 3 times on 429
+_RETRY_BASE_DELAY = 1.0              # seconds — first delay
+_RETRY_MAX_DELAY = 30.0              # seconds — cap
+_RETRY_JITTER_FRAC = 0.25            # ±25% jitter around base delay
+
+# KI-002 — idempotency key granularity: round to the current minute so
+# that concurrent restarts within the same 60-second window produce the
+# same key, while distinct tasks or distinct minutes produce distinct keys.
+_IDEMPOTENCY_ROUND_SECONDS = 60
+
+
+def make_idempotency_key(task_text: str) -> str:
+    """Compute a deterministic idempotency key for a delegation task.
+
+    Combines the task text with the current wall-clock minute to produce
+    a SHA-256 hex digest. Rounding to minute-level means two container
+    restarts within the same minute that send the same task string will
+    share the same key, preventing the platform from processing a duplicate
+    delegation. A different minute (or a different task string) yields a
+    different key.
+
+    Args:
+        task_text: The task description string being delegated.
+
+    Returns:
+        A 64-character hex string (SHA-256 digest).
+    """
+    # Round current time down to the nearest minute — same-task restarts
+    # within this minute share a key; after the minute rolls over the key
+    # changes so a genuinely new task is always treated as new.
+    now = int(time.time()) // _IDEMPOTENCY_ROUND_SECONDS * _IDEMPOTENCY_ROUND_SECONDS
+    payload = f"{task_text}:{now}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
 ]

tests/test_remote_agent.py

@@ -703,6 +703,114 @@ def test_install_plugin_404_raises_with_useful_url(client: RemoteAgentClient):
         client.install_plugin("missing")
 
 
+# ---------------------------------------------------------------------------
+# KI-002 — delegation with idempotency key
+# ---------------------------------------------------------------------------
+
+import hashlib
+
+from molecule_agent.client import make_idempotency_key
+
+
+def test_delegate_posts_task_and_idempotency_key(client: RemoteAgentClient):
+    """delegate() sends task + auto-generated idempotency_key to /delegate."""
+    client.save_token("tok")
+    client._session.post.return_value = FakeResponse(200, {"status": "ok"})
+
+    result = client.delegate(task="index the docs", target_id="peer-ws")
+
+    assert result["status"] == "ok"
+    url = client._session.post.call_args[0][0]
+    assert url == "http://platform.test/workspaces/peer-ws/delegate"
+    body = client._session.post.call_args[1]["json"]
+    assert body["task"] == "index the docs"
+    assert body["idempotency_key"] is not None
+    assert len(body["idempotency_key"]) == 64  # SHA-256 hex
+
+
+def test_delegate_sends_explicit_idempotency_key(client: RemoteAgentClient):
+    """Passing an explicit idempotency_key overrides auto-generation."""
+    client.save_token("tok")
+    client._session.post.return_value = FakeResponse(200, {})
+
+    client.delegate(task="build", target_id="peer-ws", idempotency_key="my-key-abc")
+
+    body = client._session.post.call_args[1]["json"]
+    assert body["idempotency_key"] == "my-key-abc"
+
+
+def test_delegate_sends_bearer_and_workspace_headers(client: RemoteAgentClient):
+    client.save_token("secret-tok")
+    client._session.post.return_value = FakeResponse(200, {})
+
+    client.delegate(task="do work", target_id="ws-x")
+
+    kwargs = client._session.post.call_args[1]
+    assert kwargs["headers"]["Authorization"] == "Bearer secret-tok"
+    assert kwargs["headers"]["X-Workspace-ID"] == "ws-abc-123"
+
+
+def test_delegate_raises_on_http_error(client: RemoteAgentClient):
+    client.save_token("tok")
+    client._session.post.return_value = FakeResponse(500, {"error": "boom"})
+    with pytest.raises(Exception):
+        client.delegate(task="test", target_id="peer-ws")
+
+
+def test_delegate_default_timeout_is_300(client: RemoteAgentClient):
+    client.save_token("tok")
+    client._session.post.return_value = FakeResponse(200, {})
+
+    client.delegate(task="x", target_id="y")
+
+    assert client._session.post.call_args[1]["timeout"] == 300.0
+
+
+def test_delegate_allows_custom_timeout(client: RemoteAgentClient):
+    client.save_token("tok")
+    client._session.post.return_value = FakeResponse(200, {})
+
+    client.delegate(task="x", target_id="y", timeout=60.0)
+
+    assert client._session.post.call_args[1]["timeout"] == 60.0
+
+
+# ---------------------------------------------------------------------------
+# make_idempotency_key()
+# ---------------------------------------------------------------------------
+
+
+def test_make_idempotency_key_returns_64_char_hex():
+    key = make_idempotency_key("do the thing")
+    assert len(key) == 64
+    assert all(c in "0123456789abcdef" for c in key)
+
+
+def test_make_idempotency_key_same_text_same_minute_gives_same_key():
+    """Two calls with identical text within the same minute must be equal."""
+    key1 = make_idempotency_key("do the thing")
+    key2 = make_idempotency_key("do the thing")
+    assert key1 == key2
+
+
+def test_make_idempotency_key_different_text_gives_different_key():
+    key1 = make_idempotency_key("do the thing")
+    key2 = make_idempotency_key("do another thing")
+    assert key1 != key2
+
+
+def test_make_idempotency_key_deterministic():
+    """The key for a given (text, minute) pair is always the same."""
+    # Pick a fixed epoch and verify the hash is stable
+    import time
+    # We can't easily mock time.time inside make_idempotency_key without
+    # monkeypatching, but we can verify that two calls on the same text
+    # always agree — this already captures that the function is deterministic.
+    a = make_idempotency_key("same task")
+    b = make_idempotency_key("same task")
+    assert a == b
+
+
 # ---------------------------------------------------------------------------
 # _safe_extract_tar
 # ---------------------------------------------------------------------------