cellcog 2.3.0__tar.gz → 2.4.0__tar.gz

{cellcog-2.3.0 → cellcog-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cellcog
-Version: 2.3.0
+Version: 2.4.0
 Summary: Python SDK for CellCog - Any-to-Any AI for agents. Fire-and-forget pattern with WebSocket notifications.
 Project-URL: Homepage, https://cellcog.ai
 Project-URL: Documentation, https://cellcog.ai/developer/docs
@@ -78,11 +78,13 @@ result = client.create_chat(
 
 ## How It Works
 
-**Two delivery modes:**
+**Three delivery modes:**
 
 - **Wait for Completion (default)** — Blocks until CellCog finishes and returns the full result. Works with any agent — OpenClaw, Claude Code, Cursor, or any Python environment.
 
-- **Fire-and-Forget (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
+- **Send-only (`delivery="send_only"`)** — Fire-and-forget for ANY agent: returns the moment the chat/message is accepted (`status="accepted"`). Poll `get_status()` and fetch results with `wait_for_completion()`/`get_history()`. Use this when orchestrating several chats in parallel — the blocking default would hang on each chat's whole run. Works on `create_chat()` AND `send_message()`.
+
+- **Notify on Completion (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
 
 All methods return the same unified shape:
 
@@ -90,15 +92,23 @@ All methods return the same unified shape:
 {
     "chat_id": str,
     "is_operating": bool,
-    "status": str,         # "completed" | "tracking" | "timeout" | "operating"
+    "status": str,         # "completed" | "tracking" | "accepted" | "operating"
     "message": str,        # Always print this in full
 }
 ```
 
+A wait that gives up returns `status="operating"` with `timed_out=True` — the chat is still
+running server-side; resume with `wait_for_completion()`.
+
 ## Configuration
 
 ```bash
 export CELLCOG_API_KEY="sk_..."
+
+# Optional: where SDK state lives (tracked chats, downloads, daemon files).
+# Default ~/.cellcog; in headless/container environments where HOME isn't
+# writable, the SDK falls back to a temp directory automatically.
+export CELLCOG_STATE_DIR="/path/to/state"
 ```
 
 **Get your API key:**
@@ -148,13 +158,48 @@ result = client.create_chat(
     prompt="...",
     task_label="...",
     chat_mode="agent",
+    chat_tier="max",                        # "flash" | "core" | "max" — omit for the SDK default
+    delivery="send_only",                   # fire-and-forget; default blocks until done
     project_id="...",                       # CellCog project for document context
     agent_role_id="...",                    # Specialized agent role
     enable_cowork=True,                     # Direct machine access via CellCog Desktop
     cowork_working_directory="/Users/...",  # Working directory for co-work
+    enable_browse=True,                     # Drive the user's REAL Chrome (needs Desktop + extension)
+    browser_profile_id="Default",           # from client.get_browser_status()
+    enable_tools=True,                      # the user's connected SaaS tools
+    tools_selection=["gmail", "notion"],    # toolkit slugs (omit for ALL); from client.list_toolkits()
 )
 ```
 
+## Browse & Tools
+
+CellCog chats can drive the user's **real Chrome** (Browse) and call their **connected
+SaaS tools** (Gmail, Notion, Slack, ... — Tools). Discover what's available, then enable
+at chat creation:
+
+```python
+# Browse: discover Chrome profiles, then enable with one
+status = client.get_browser_status()
+profile = status["active_profile"]          # or let the user pick from available_profiles
+result = client.create_chat(
+    prompt="Log into the dashboard and screenshot the weekly report",
+    enable_browse=True,
+    browser_profile_id=profile["profileDir"],
+)
+
+# Tools: discover connected toolkits, then enable a selection (omit for ALL)
+toolkits = client.list_toolkits(connected_only=True)
+result = client.create_chat(
+    prompt="Summarize this week's unread emails",
+    enable_tools=True,
+    tools_selection=["gmail"],              # toolkit slugs
+)
+```
+
+Notes: Browse requires CellCog Desktop + the Chrome extension on the user's machine and
+auto-enables co-work server-side. `tools_selection` takes TOOLKIT slugs (the granularity
+users pick in the product UI); `list_toolkit_tools(slug)` shows what a toolkit unlocks.
+
 ## File Handling
 
 ```python
@@ -180,9 +225,15 @@ a tier for the DEPTH (omit `chat_tier` for the mode's default).
 
 | Mode | Best For | Tiers |
 |------|----------|-------|
-| `"agent"` | Most tasks — building, research, images, audio, documents, coding/co-work | `flash` · `core` · `max` (default) |
+| `"agent"` | Most tasks — assets, documents, production pipelines, coding/co-work | `flash` (SDK default) · `core` · `max` |
 | `"creative"` | Design, brand, frontend craft — taste-first work | `core` (default) · `max` |
-| `"team"` | Deep multi-angled research & analysis (multi-agent) | `flash` · `core` (default) · `max` |
+| `"team"` | Deep research ONLY — multi-source synthesis, citations (multi-agent) | `flash` · `core` (default) · `max` |
+
+**Tier guidance for agent mode:** omit `chat_tier` and the SDK sends `"flash"` — right for
+simple asset generation and light tasks. **Coding / co-work needs `"max"`** (applied
+automatically when `enable_cowork=True`). Heavy multi-step production (video, data
+analysis, financial models, legal drafting) → pass `chat_tier="max"` explicitly. Quality
+disappointing on flash? Re-run with `chat_tier="max"`. Use `"team"` only for deep research.
 
 Legacy mode names (`"agent core"`, `"agent team"`, `"agent team max"`) keep working
 forever — the server normalizes them to their historical operating points.

{cellcog-2.3.0 → cellcog-2.4.0}/README.md

@@ -46,11 +46,13 @@ result = client.create_chat(
 
 ## How It Works
 
-**Two delivery modes:**
+**Three delivery modes:**
 
 - **Wait for Completion (default)** — Blocks until CellCog finishes and returns the full result. Works with any agent — OpenClaw, Claude Code, Cursor, or any Python environment.
 
-- **Fire-and-Forget (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
+- **Send-only (`delivery="send_only"`)** — Fire-and-forget for ANY agent: returns the moment the chat/message is accepted (`status="accepted"`). Poll `get_status()` and fetch results with `wait_for_completion()`/`get_history()`. Use this when orchestrating several chats in parallel — the blocking default would hang on each chat's whole run. Works on `create_chat()` AND `send_message()`.
+
+- **Notify on Completion (OpenClaw)** — Returns immediately. A background daemon monitors via WebSocket and delivers results to your OpenClaw session when done. Requires `sessions_send` on OpenClaw Gateway.
 
 All methods return the same unified shape:
 
@@ -58,15 +60,23 @@ All methods return the same unified shape:
 {
     "chat_id": str,
     "is_operating": bool,
-    "status": str,         # "completed" | "tracking" | "timeout" | "operating"
+    "status": str,         # "completed" | "tracking" | "accepted" | "operating"
     "message": str,        # Always print this in full
 }
 ```
 
+A wait that gives up returns `status="operating"` with `timed_out=True` — the chat is still
+running server-side; resume with `wait_for_completion()`.
+
 ## Configuration
 
 ```bash
 export CELLCOG_API_KEY="sk_..."
+
+# Optional: where SDK state lives (tracked chats, downloads, daemon files).
+# Default ~/.cellcog; in headless/container environments where HOME isn't
+# writable, the SDK falls back to a temp directory automatically.
+export CELLCOG_STATE_DIR="/path/to/state"
 ```
 
 **Get your API key:**
@@ -116,13 +126,48 @@ result = client.create_chat(
     prompt="...",
     task_label="...",
     chat_mode="agent",
+    chat_tier="max",                        # "flash" | "core" | "max" — omit for the SDK default
+    delivery="send_only",                   # fire-and-forget; default blocks until done
     project_id="...",                       # CellCog project for document context
     agent_role_id="...",                    # Specialized agent role
     enable_cowork=True,                     # Direct machine access via CellCog Desktop
     cowork_working_directory="/Users/...",  # Working directory for co-work
+    enable_browse=True,                     # Drive the user's REAL Chrome (needs Desktop + extension)
+    browser_profile_id="Default",           # from client.get_browser_status()
+    enable_tools=True,                      # the user's connected SaaS tools
+    tools_selection=["gmail", "notion"],    # toolkit slugs (omit for ALL); from client.list_toolkits()
 )
 ```
 
+## Browse & Tools
+
+CellCog chats can drive the user's **real Chrome** (Browse) and call their **connected
+SaaS tools** (Gmail, Notion, Slack, ... — Tools). Discover what's available, then enable
+at chat creation:
+
+```python
+# Browse: discover Chrome profiles, then enable with one
+status = client.get_browser_status()
+profile = status["active_profile"]          # or let the user pick from available_profiles
+result = client.create_chat(
+    prompt="Log into the dashboard and screenshot the weekly report",
+    enable_browse=True,
+    browser_profile_id=profile["profileDir"],
+)
+
+# Tools: discover connected toolkits, then enable a selection (omit for ALL)
+toolkits = client.list_toolkits(connected_only=True)
+result = client.create_chat(
+    prompt="Summarize this week's unread emails",
+    enable_tools=True,
+    tools_selection=["gmail"],              # toolkit slugs
+)
+```
+
+Notes: Browse requires CellCog Desktop + the Chrome extension on the user's machine and
+auto-enables co-work server-side. `tools_selection` takes TOOLKIT slugs (the granularity
+users pick in the product UI); `list_toolkit_tools(slug)` shows what a toolkit unlocks.
+
 ## File Handling
 
 ```python
@@ -148,9 +193,15 @@ a tier for the DEPTH (omit `chat_tier` for the mode's default).
 
 | Mode | Best For | Tiers |
 |------|----------|-------|
-| `"agent"` | Most tasks — building, research, images, audio, documents, coding/co-work | `flash` · `core` · `max` (default) |
+| `"agent"` | Most tasks — assets, documents, production pipelines, coding/co-work | `flash` (SDK default) · `core` · `max` |
 | `"creative"` | Design, brand, frontend craft — taste-first work | `core` (default) · `max` |
-| `"team"` | Deep multi-angled research & analysis (multi-agent) | `flash` · `core` (default) · `max` |
+| `"team"` | Deep research ONLY — multi-source synthesis, citations (multi-agent) | `flash` · `core` (default) · `max` |
+
+**Tier guidance for agent mode:** omit `chat_tier` and the SDK sends `"flash"` — right for
+simple asset generation and light tasks. **Coding / co-work needs `"max"`** (applied
+automatically when `enable_cowork=True`). Heavy multi-step production (video, data
+analysis, financial models, legal drafting) → pass `chat_tier="max"` explicitly. Quality
+disappointing on flash? Re-run with `chat_tier="max"`. Use `"team"` only for deep research.
 
 Legacy mode names (`"agent core"`, `"agent team"`, `"agent team max"`) keep working
 forever — the server normalizes them to their historical operating points.

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/__init__.py

@@ -48,7 +48,7 @@ from .exceptions import (
     SDKUpgradeRequiredError,
 )
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"
 __all__ = [
     "CellCogClient",
     "CellCogError",

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/chat.py

@@ -19,6 +19,7 @@ from .exceptions import (
     PaymentRequiredError,
 )
 from .files import FileProcessor
+from .state_paths import state_path
 
 # ── Mode × Tier resolution (Mode × Tier redesign, 2026-08) ──────────────────
 # Friendly SDK names -> API chat_mode values. The server accepts BOTH current
@@ -80,7 +81,7 @@ class ChatManager:
     def __init__(self, config: Config, file_processor: FileProcessor):
         self.config = config
         self.files = file_processor
-        self._chats_dir = Path("~/.cellcog/chats").expanduser()
+        self._chats_dir = state_path("chats")
 
     def create(
         self,
@@ -91,6 +92,10 @@ class ChatManager:
         hc_enabled: bool = False,
         hc_working_directory: Optional[str] = None,
         chat_tier: Optional[str] = None,
+        browser_enabled: bool = False,
+        browser_profile_id: Optional[str] = None,
+        personal_tools_enabled: bool = False,
+        personal_tools_selection: Optional[list] = None,
     ) -> dict:
         """
         Create a new CellCog chat (without streaming).
@@ -107,6 +112,13 @@ class ChatManager:
             agent_role_id: Optional agent role ID within the project. Requires project_id.
             hc_enabled: Enable Human Computer (co-work) for this chat
             hc_working_directory: Working directory on user's machine for HC commands
+            browser_enabled: Enable Browse (the user's real Chrome). Server-side this
+                auto-enables co-work (Browse rides the Desktop connection).
+            browser_profile_id: Chrome profile dir (from the browser-status endpoint's
+                available_profiles[].profileDir). None -> "Default".
+            personal_tools_enabled: Enable the user's connected SaaS tools for this chat
+            personal_tools_selection: Toolkit slugs to restrict the chat to (e.g.
+                ["gmail", "notion"]). None -> ALL connected tools.
 
         Returns:
             {
@@ -133,6 +145,13 @@ class ChatManager:
             data["hc_enabled"] = True
         if hc_working_directory:
             data["hc_working_directory"] = hc_working_directory
+        if browser_enabled:
+            data["browser_enabled"] = True
+            data["browser_profile_id"] = browser_profile_id or "Default"
+        if personal_tools_enabled:
+            data["personal_tools_enabled"] = True
+            if personal_tools_selection is not None:
+                data["personal_tools_selection"] = [str(s).strip().lower() for s in personal_tools_selection]
 
         resp = self._request("POST", "/cellcog/chat/new", data)
 
@@ -192,6 +211,9 @@ class ChatManager:
             "name": resp["name"],
             "is_operating": resp["operating"],
             "error_type": error_type,
+            # Most recent agent progress one-liner (server: ChatMeta.latest_status_update,
+            # CEL-1300 item 6). None until the agent posts its first update of a run.
+            "latest_update": resp.get("latest_status_update"),
         }
 
     def get_history(self, chat_id: str, session_id: str) -> dict:

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/client.py

@@ -22,11 +22,12 @@ from typing import Optional
 import requests as _requests
 
 from .auth import AuthManager
-from .chat import ChatManager
+from .chat import ChatManager, resolve_chat_mode
 from .config import Config
 from .exceptions import APIError, GatewayConfigError
 from .files import FileProcessor
 from .message_processor import MessageProcessor
+from .state_paths import state_dir, state_path
 from .daemon.state import TrackedChat, Listener, StateManager
 
 
@@ -140,7 +141,7 @@ class CellCogClient:
         self._state = StateManager()
         
         # Daemon management
-        self._daemon_pid_file = Path("~/.cellcog/daemon.pid").expanduser()
+        self._daemon_pid_file = state_path("daemon.pid")
 
         # Sessions send pre-flight check cache
         # Maps gateway_url -> (is_available: bool, checked_at: float)
@@ -280,13 +281,20 @@ class CellCogClient:
         enable_cowork: bool = False,
         cowork_working_directory: Optional[str] = None,
         chat_tier: Optional[str] = None,
+        enable_browse: bool = False,
+        browser_profile_id: Optional[str] = None,
+        enable_tools: bool = False,
+        tools_selection: Optional[list] = None,
     ) -> dict:
         """
         Create a CellCog chat.
 
-        Two delivery modes:
+        Three delivery modes:
         - "wait_for_completion" (default): Blocks until done. Returns full results.
           Works with ANY agent (OpenClaw, Cursor, Claude Code, etc.).
+        - "send_only": Fire-and-forget. Returns immediately with status="accepted";
+          no daemon needed. Poll get_status()/wait_for_completion() yourself.
+          Best for orchestrating several chats in parallel.
         - "notify_on_completion": Returns immediately. Daemon delivers results
           to your OpenClaw session via sessions_send. Requires notify_session_key.
 
@@ -296,8 +304,10 @@ class CellCogClient:
                 e.g., "agent:main:main"). If provided without explicit delivery param,
                 automatically uses notify_on_completion for backward compatibility.
             task_label: Human-readable label (appears in notification)
-            delivery: "wait_for_completion" (default, universal) or
-                "notify_on_completion" (OpenClaw only, fire-and-forget)
+            delivery: "wait_for_completion" (default, universal, blocking),
+                "send_only" (fire-and-forget: returns once the chat is accepted;
+                poll with get_status/wait_for_completion), or
+                "notify_on_completion" (OpenClaw sessions_send delivery)
             timeout: Max seconds to wait (wait_for_completion mode only, default 1800)
             gateway_url: OpenClaw Gateway URL (notify_on_completion only)
             project_id: Optional CellCog project ID for document context
@@ -305,9 +315,21 @@ class CellCogClient:
             chat_mode: "agent", "creative", or "team". Legacy names — "agent core",
                 "agent team", "agent team max" — keep working forever.
             chat_tier: "flash" | "core" | "max" — depth/spend within the mode.
-                None -> the mode's default tier. "creative" has no "flash" tier.
+                None in agent mode -> SDK default: "flash" (or "max" when
+                enable_cowork=True — coding needs depth). Other modes: the
+                server applies the mode's default. "creative" has no "flash" tier.
             enable_cowork: Enable co-work on user's PC
             cowork_working_directory: Working directory for co-work commands
+            enable_browse: Enable Browse — the agent drives the user's REAL Chrome
+                (requires CellCog Desktop + the Chrome extension). Auto-enables
+                co-work server-side. Discover profiles via get_browser_status().
+            browser_profile_id: Chrome profile to browse with — a profileDir from
+                get_browser_status()["available_profiles"]. None -> "Default".
+            enable_tools: Enable the user's connected SaaS tools (Gmail, Notion, ...)
+                for this chat. Discover toolkits via list_toolkits().
+            tools_selection: Restrict the chat to these toolkit slugs (e.g.
+                ["gmail", "notion"]). None -> ALL connected tools. no_auth built-in
+                toolkits work regardless of this selection.
 
         Returns:
             All modes return: {"chat_id": str, "is_operating": bool, "status": str, "message": str}
@@ -347,10 +369,11 @@ class CellCogClient:
         if notify_session_key and delivery == "wait_for_completion":
             delivery = "notify_on_completion"
 
-        if delivery not in ("notify_on_completion", "wait_for_completion"):
+        if delivery not in ("notify_on_completion", "wait_for_completion", "send_only"):
             raise ValueError(
                 f"Invalid delivery mode: '{delivery}'. "
-                "Use 'notify_on_completion' (OpenClaw) or 'wait_for_completion' (universal)."
+                "Use 'wait_for_completion' (universal, blocking), 'send_only' "
+                "(fire-and-forget, poll later), or 'notify_on_completion' (OpenClaw)."
             )
 
         if delivery == "notify_on_completion" and not notify_session_key:
@@ -370,6 +393,49 @@ class CellCogClient:
         if delivery == "notify_on_completion":
             self._require_sessions_send(gateway_url)
 
+        # ── Tools selection validation (toolkit slugs only) ──
+        if tools_selection is not None:
+            if not enable_tools:
+                raise ValueError("tools_selection requires enable_tools=True")
+            if not isinstance(tools_selection, (list, tuple)) or not all(
+                isinstance(s, str) and s.strip() for s in tools_selection
+            ):
+                raise ValueError(
+                    "tools_selection must be a list of toolkit slugs (strings), e.g. "
+                    "['gmail', 'notion'] — discover slugs via client.list_toolkits()."
+                )
+
+        # ── Browse pre-flight: fail fast BEFORE creating (and billing) a chat whose
+        # browser commands could never run. Best-effort — a status-fetch error never blocks.
+        if enable_browse:
+            try:
+                _bstatus = self.get_browser_status()
+            except Exception:
+                _bstatus = None
+            if _bstatus is not None:
+                _profiles = _bstatus.get("available_profiles") or []
+                if not any(p.get("hasExtension") for p in _profiles):
+                    raise ValueError(
+                        "enable_browse=True but no Chrome profile has the CellCog extension "
+                        "(or CellCog Desktop is not connected). The user must connect Desktop "
+                        "and install the extension first — check client.get_browser_status()."
+                    )
+                if browser_profile_id and not any(
+                    p.get("profileDir") == browser_profile_id for p in _profiles
+                ):
+                    _known = ", ".join(sorted(str(p.get("profileDir")) for p in _profiles))
+                    raise ValueError(
+                        f"browser_profile_id {browser_profile_id!r} not found in the user's "
+                        f"Chrome. Known profiles: {_known}. Pick a profileDir from "
+                        "client.get_browser_status()['available_profiles']."
+                    )
+
+        # ── SDK tier default (Mode × Tier rollout, 2026-08): when no chat_tier is
+        # given in agent mode, default to the LOWEST tier — "flash" — except co-work
+        # (coding on a real machine), which needs "max". Explicit chat_tier always wins.
+        if chat_tier is None and resolve_chat_mode(chat_mode) == "human_in_the_loop":
+            chat_tier = "max" if enable_cowork else "flash"
+
         # ── Create the chat via API ──
         api_result = self._chat.create(
             prompt, project_id, chat_mode,
@@ -377,10 +443,28 @@ class CellCogClient:
             agent_role_id=agent_role_id,
             hc_enabled=enable_cowork,
             hc_working_directory=cowork_working_directory,
+            browser_enabled=enable_browse,
+            browser_profile_id=browser_profile_id,
+            personal_tools_enabled=enable_tools,
+            personal_tools_selection=list(tools_selection) if tools_selection is not None else None,
         )
         chat_id = api_result["chat_id"]
         task_label = task_label or f"chat-{chat_id[:8]}"
 
+        # ── send_only: fire-and-forget — no tracking, no daemon, return at once ──
+        if delivery == "send_only":
+            return {
+                "chat_id": chat_id,
+                "is_operating": True,
+                "status": "accepted",
+                "message": (
+                    f"Chat {chat_id} accepted and running on CellCog (fire-and-forget).\n"
+                    f'Poll progress:    client.get_status("{chat_id}")\n'
+                    f'Block until done: client.wait_for_completion("{chat_id}", timeout=1800)\n'
+                    f'Fetch results:    client.get_history("{chat_id}")'
+                ),
+            }
+
         # ── Local setup: tracking + daemon + delivery ──
         # Wrapped in try-except so chat_id is always returned even if local
         # setup fails. The chat was already created server-side and billed —
@@ -448,6 +532,10 @@ class CellCogClient:
 
         Same delivery modes as create_chat:
         - "wait_for_completion" (default): Blocks until done. Returns full results.
+        - "send_only": Fire-and-forget. Returns immediately after the message is
+          accepted; poll get_status()/wait_for_completion() yourself. Use this when
+          relaying messages to several chats — the blocking default would hang on
+          each chat's entire run.
         - "notify_on_completion": Returns immediately. Daemon delivers later.
 
         Args:
@@ -455,7 +543,8 @@ class CellCogClient:
             message: Your message (supports SHOW_FILE tags for file uploads)
             notify_session_key: OpenClaw session key (required for notify_on_completion)
             task_label: Label for notification (default: "continue-{chat_id[:8]}")
-            delivery: "wait_for_completion" or "notify_on_completion"
+            delivery: "wait_for_completion" (blocking, default), "send_only"
+                (fire-and-forget), or "notify_on_completion" (OpenClaw)
             timeout: Max seconds to wait (wait_for_completion only, default 1800)
             gateway_url: OpenClaw Gateway URL (notify_on_completion only)
 
@@ -468,10 +557,11 @@ class CellCogClient:
         if notify_session_key and delivery == "wait_for_completion":
             delivery = "notify_on_completion"
 
-        if delivery not in ("notify_on_completion", "wait_for_completion"):
+        if delivery not in ("notify_on_completion", "wait_for_completion", "send_only"):
             raise ValueError(
                 f"Invalid delivery mode: '{delivery}'. "
-                "Use 'notify_on_completion' (OpenClaw) or 'wait_for_completion' (universal)."
+                "Use 'wait_for_completion' (universal, blocking), 'send_only' "
+                "(fire-and-forget, poll later), or 'notify_on_completion' (OpenClaw)."
             )
 
         if delivery == "notify_on_completion" and not notify_session_key:
@@ -494,6 +584,19 @@ class CellCogClient:
         # ── Send message via API ──
         api_result = self._chat.send_message(chat_id, message)
 
+        # ── send_only: fire-and-forget — message delivered, return at once ──
+        if delivery == "send_only":
+            return {
+                "chat_id": chat_id,
+                "is_operating": True,
+                "status": "accepted",
+                "message": (
+                    f"Message delivered to chat {chat_id}; CellCog is working (fire-and-forget).\n"
+                    f'Poll progress:    client.get_status("{chat_id}")\n'
+                    f'Block until done: client.wait_for_completion("{chat_id}", timeout=1800)'
+                ),
+            }
+
         # ── Local setup (same protection as create_chat) ──
         try:
             tracking_info = self._track_chat(
@@ -630,11 +733,80 @@ class CellCogClient:
                 "status": "processing" | "ready" | "error",
                 "name": str,
                 "is_operating": bool,
-                "error_type": str | None
+                "error_type": str | None,
+                "latest_update": str | None  # most recent agent progress one-liner
             }
         """
         return self._chat.get_status(chat_id)
 
+    # ==================== Capability Discovery (Browse & Tools) ====================
+
+    def get_browser_status(self) -> dict:
+        """
+        Browse availability on the user's machine — use this to populate a
+        profile picker before create_chat(enable_browse=True).
+
+        Returns:
+            {
+                "extension_installed": bool,   # CellCog Chrome extension present?
+                "chrome_running": bool,        # Chrome connected to Desktop?
+                "active_profile": dict | None, # sensible default profile
+                "available_profiles": [        # one per Chrome profile
+                    {"profileDir": str,        # -> pass as browser_profile_id
+                     "profileName": str,
+                     "hostedDomain": str | None,
+                     "hasExtension": bool,     # extension installed in this profile
+                     "connected": bool},       # currently connected via Desktop
+                    ...
+                ],
+                "agent_tab_count": int,
+            }
+        """
+        self.config.require_configured()
+        return self._chat._request("GET", "/cellcog/human-computer/browser/status")
+
+    def list_toolkits(self, connected_only: bool = False, search: Optional[str] = None) -> list:
+        """
+        The SaaS toolkit catalog with the user's connection state — use this to
+        populate a tool picker before create_chat(enable_tools=True).
+
+        Args:
+            connected_only: Only toolkits the user has actually connected —
+                the set that matters for tools_selection.
+            search: Optional name filter (server-side, case-insensitive).
+
+        Returns:
+            List of toolkit dicts; each has "slug" (-> pass in tools_selection),
+            "name", and "connection" (dict when connected, None otherwise).
+        """
+        self.config.require_configured()
+        from urllib.parse import quote
+
+        items, offset, limit = [], 0, 200
+        while True:
+            path = f"/cellcog/personal-tools/toolkits?limit={limit}&offset={offset}"
+            if search:
+                path += f"&search={quote(search)}"
+            resp = self._chat._request("GET", path)
+            page = resp.get("items", [])
+            items.extend(page)
+            total = resp.get("total", len(items))
+            offset += limit
+            if len(items) >= total or not page or offset > 5000:
+                break
+        if connected_only:
+            items = [t for t in items if t.get("connection")]
+        return items
+
+    def list_toolkit_tools(self, toolkit_slug: str) -> list:
+        """
+        The individual tools (action slugs) a toolkit carries — for showing users
+        what enabling a toolkit unlocks. (tools_selection itself takes TOOLKIT
+        slugs, not tool slugs.)
+        """
+        self.config.require_configured()
+        return self._chat._request("GET", f"/cellcog/personal-tools/toolkits/{toolkit_slug}/tools")
+
     # ==================== Chat Tracking Recovery ====================
 
     def restart_chat_tracking(self) -> dict:
@@ -670,7 +842,7 @@ class CellCogClient:
         self._kill_daemon_if_running()
         
         # Count tracking files to report
-        tracked_dir = Path("~/.cellcog/tracked_chats").expanduser()
+        tracked_dir = state_path("tracked_chats")
         tracked_count = sum(1 for _ in tracked_dir.glob("*.json")) if tracked_dir.exists() else 0
         
         if tracked_count == 0:
@@ -698,7 +870,7 @@ class CellCogClient:
             return {
                 "status": "failed",
                 "tracked_chats": tracked_count,
-                "message": "Failed to start daemon. Check ~/.cellcog/daemon.log"
+                "message": f"Failed to start daemon. Check {state_path('daemon.log')}"
             }
 
     # ==================== Synchronous Wait ====================
@@ -721,7 +893,8 @@ class CellCogClient:
 
             On completion: status="completed", message contains full response with
             file paths, credits used, and next steps.
-            On timeout: status="timeout", message contains progress updates and
+            On timeout: status="operating" with timed_out=True (the chat is STILL
+            running server-side); message contains progress updates and
             retry guidance.
 
         Examples:
@@ -1021,7 +1194,7 @@ class CellCogClient:
 
         # Read interim updates file written by daemon
         try:
-            updates_file = Path("~/.cellcog/chats").expanduser() / chat_id / ".interim_updates.json"
+            updates_file = state_path("chats") / chat_id / ".interim_updates.json"
             if updates_file.exists():
                 raw = json.loads(updates_file.read_text())
                 now = time.time()
@@ -1059,10 +1232,14 @@ class CellCogClient:
             f"Chat ID: {chat_id}",
         ])
 
+        # The chat is STILL RUNNING server-side. status="timeout" historically read
+        # as failure and misfired callers' retry logic (CEL-1300); status now reflects
+        # the chat's real state, and timed_out=True carries "the SDK stopped waiting".
         return {
             "chat_id": chat_id,
             "is_operating": True,
-            "status": "timeout",
+            "status": "operating",
+            "timed_out": True,
             "message": "\n".join(lines),
         }
 
@@ -1555,9 +1732,15 @@ class CellCogClient:
 
     # ==================== Daemon Management ====================
 
+    # Process-wide warn-once / give-up flags (class-level by design): a stale
+    # heartbeat or an unstartable daemon would otherwise print on EVERY SDK call
+    # in headless environments (CEL-1300 item 7).
+    _heartbeat_warned = False
+    _daemon_start_failures = 0
+
     def _has_tracked_chats(self) -> bool:
         """Check if there are any tracked chats on disk."""
-        tracked_dir = Path("~/.cellcog/tracked_chats").expanduser()
+        tracked_dir = state_path("tracked_chats")
         if not tracked_dir.exists():
             return False
         return any(tracked_dir.glob("*.json"))
@@ -1580,11 +1763,14 @@ class CellCogClient:
         except (ValueError, ProcessLookupError, PermissionError):
             pass
         finally:
-            # Clean up PID file
-            try:
-                self._daemon_pid_file.unlink(missing_ok=True)
-            except Exception:
-                pass
+            # Clean up PID + daemon health files. Leaving a stale heartbeat behind
+            # made every subsequent SDK call re-warn "heartbeat stale" and re-kill
+            # forever with the same age (CEL-1300 item 7).
+            for stale in (self._daemon_pid_file, state_path("daemon.heartbeat"), state_path("daemon.version")):
+                try:
+                    stale.unlink(missing_ok=True)
+                except Exception:
+                    pass
         
         return True
 
@@ -1616,7 +1802,18 @@ class CellCogClient:
                     return self._start_daemon()
                 return True
             
-            return self._start_daemon()
+            if CellCogClient._daemon_start_failures >= 2:
+                return False  # daemon can't start in this environment — poll-only mode
+            started = self._start_daemon()
+            if not started:
+                CellCogClient._daemon_start_failures += 1
+                if CellCogClient._daemon_start_failures == 2:
+                    print(
+                        "Note: CellCog daemon could not be started twice; continuing in "
+                        "poll-only mode (create/status/history/wait still work via HTTP).",
+                        file=sys.stderr,
+                    )
+            return started
         finally:
             self._daemon_check_in_progress = False
     
@@ -1631,7 +1828,7 @@ class CellCogClient:
         Returns:
             True if daemon should be restarted with current SDK
         """
-        version_file = Path("~/.cellcog/daemon.version").expanduser()
+        version_file = state_path("daemon.version")
         if not version_file.exists():
             return True  # No version file = old daemon pre-dating this feature
         try:
@@ -1660,17 +1857,20 @@ class CellCogClient:
         
         # Heartbeat check: daemon writes timestamp every 30s.
         # If stale (>120s), daemon is frozen (e.g., stuck after sleep).
-        heartbeat_file = Path("~/.cellcog/daemon.heartbeat").expanduser()
+        heartbeat_file = state_path("daemon.heartbeat")
         if heartbeat_file.exists():
             try:
                 heartbeat_time = float(heartbeat_file.read_text().strip())
                 age = time.time() - heartbeat_time
                 if age > 120:
-                    print(
-                        f"Warning: Daemon heartbeat stale ({age:.0f}s old). "
-                        f"Killing and restarting...",
-                        file=sys.stderr
-                    )
+                    if not CellCogClient._heartbeat_warned:
+                        print(
+                            f"Warning: Daemon heartbeat stale ({age:.0f}s old). "
+                            f"Killing and restarting... (further daemon-health "
+                            f"warnings suppressed for this process)",
+                            file=sys.stderr
+                        )
+                        CellCogClient._heartbeat_warned = True
                     self._kill_daemon_if_running()
                     return False
             except (ValueError, IOError):
@@ -1697,6 +1897,9 @@ class CellCogClient:
                 self.config.api_key,
                 self.config.api_base_url
             ]
+            # Pin the daemon to the SAME state dir the client resolved (matters when
+            # the client fell back to a tmp/override dir — both sides must agree).
+            daemon_env = {**os.environ, "CELLCOG_STATE_DIR": str(state_dir())}
             
             # Start detached process
             if sys.platform == "win32":
@@ -1706,6 +1909,7 @@ class CellCogClient:
                     creationflags=subprocess.CREATE_NEW_PROCESS_GROUP,
                     stdout=subprocess.DEVNULL,
                     stderr=subprocess.DEVNULL,
+                    env=daemon_env,
                 )
             else:
                 # Unix: start new session
@@ -1714,6 +1918,7 @@ class CellCogClient:
                     start_new_session=True,
                     stdout=subprocess.DEVNULL,
                     stderr=subprocess.DEVNULL,
+                    env=daemon_env,
                 )
             
             # Wait briefly for daemon to start
@@ -1850,7 +2055,7 @@ class CellCogClient:
             tracking_file.unlink(missing_ok=True)
 
         # Remove seen indices (no longer relevant)
-        seen_dir = Path("~/.cellcog/chats/{}/{}".format(chat_id, ".seen_indices")).expanduser()
+        seen_dir = state_path("chats", chat_id, ".seen_indices")
         if seen_dir.exists():
             shutil.rmtree(seen_dir, ignore_errors=True)
 

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/daemon/main.py

@@ -27,6 +27,7 @@ import requests
 
 from .delivery import deliver_to_all_listeners, get_gateway_auth, send_to_session
 from .state import Listener, StateManager, TrackedChat
+from ..state_paths import state_path
 
 log = logging.getLogger(__name__)
 
@@ -114,7 +115,7 @@ class CellCogDaemon:
 
         # Resilience: heartbeat file for client-side daemon health checks
         self.heartbeat_task: Optional[asyncio.Task] = None
-        self._heartbeat_file = Path("~/.cellcog/daemon.heartbeat").expanduser()
+        self._heartbeat_file = state_path("daemon.heartbeat")
         self._heartbeat_interval = 30  # seconds
 
         # Resilience: max tracking age before forced re-verify (24 hours)
@@ -1335,7 +1336,7 @@ def run_daemon():
     If no arguments provided, loads from ~/.openclaw/cellcog.json
     """
     # Setup logging
-    log_file = Path("~/.cellcog/daemon.log").expanduser()
+    log_file = state_path("daemon.log")
     log_file.parent.mkdir(parents=True, exist_ok=True)
 
     logging.basicConfig(
@@ -1378,7 +1379,7 @@ def run_daemon():
         loop.add_signal_handler(sig, signal_handler)
 
     # Write PID file
-    pid_file = Path("~/.cellcog/daemon.pid").expanduser()
+    pid_file = state_path("daemon.pid")
     pid_file.parent.mkdir(parents=True, exist_ok=True)
     pid_file.write_text(str(os.getpid()))
     log.info(f"Daemon PID: {os.getpid()}")
@@ -1386,7 +1387,7 @@ def run_daemon():
     # Write version file for client-side stale daemon detection
     from .. import __version__
 
-    version_file = Path("~/.cellcog/daemon.version").expanduser()
+    version_file = state_path("daemon.version")
     version_file.write_text(__version__)
     log.info(f"Daemon version: {__version__}")
 

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/daemon/state.py

@@ -11,6 +11,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from ..state_paths import state_dir
+
 
 @dataclass
 class Listener:
@@ -134,7 +136,7 @@ class StateManager:
         Args:
             base_dir: Base directory for state files. Defaults to ~/.cellcog
         """
-        self.base_dir = base_dir or Path("~/.cellcog").expanduser()
+        self.base_dir = base_dir or state_dir()
         self.tracked_dir = self.base_dir / "tracked_chats"
         self.chats_dir = self.base_dir / "chats"
         

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/docs/api_reference.md

@@ -7,30 +7,49 @@ from cellcog import CellCogClient
 client = CellCogClient(agent_provider="openclaw")
 ```
 
+`agent_provider` (required) identifies the agent framework calling CellCog — lowercase
+letters/numbers/hyphens. Common values: `"openclaw"`, `"cursor"`, `"claude-code"`,
+`"codex"`, `"aider"`, `"windsurf"`, `"script"` (standalone scripts), `"cellcog"`
+(CellCog's own agents orchestrating sub-chats).
+
+**State directory:** all SDK state (tracked chats, downloads, daemon files) lives under
+`~/.cellcog` by default. Set `CELLCOG_STATE_DIR` to override. In headless/container
+environments where the home directory isn't writable (e.g. `HOME=/`), the SDK falls back
+to a temp directory automatically instead of crashing.
+
 ---
 
 ## Chat Operations
 
 ### create_chat()
 
-Create a new CellCog task. Two delivery modes:
+Create a new CellCog task. Three delivery modes:
 - `wait_for_completion` (default): Blocks until done. Works with any agent.
+- `send_only`: Fire-and-forget. Returns the moment the chat is accepted (`status="accepted"`);
+  poll `get_status()` / `wait_for_completion()` yourself. Best for orchestrating several chats.
 - `notify_on_completion`: Returns immediately. OpenClaw only.
 
 ```python
 result = client.create_chat(
     prompt: str,                          # Task description (required)
     task_label: str = "",                 # Human-readable label
-    delivery: str = "wait_for_completion",# "wait_for_completion" or "notify_on_completion"
+    delivery: str = "wait_for_completion",# "wait_for_completion" | "send_only" | "notify_on_completion"
     timeout: int = 1800,                  # Max wait seconds (wait mode only)
     notify_session_key: str = None,       # OpenClaw session key (notify mode only)
     gateway_url: str = None,              # OpenClaw Gateway URL (notify mode only)
     chat_mode: str = "agent",             # "agent", "creative", "team" (legacy names still work)
-    chat_tier: str = None,                # "flash" | "core" | "max" (None = mode default; creative has no flash)
+    chat_tier: str = None,                # "flash" | "core" | "max". Agent mode + None -> SDK default:
+                                          #   "flash" ("max" when enable_cowork=True — coding needs depth).
+                                          #   Other modes + None -> server default. Creative has no flash.
     project_id: str = None,               # Project context (see project-management-cellcog)
     agent_role_id: str = None,            # Specialized role (requires project_id)
     enable_cowork: bool = False,          # Direct machine access (see pair-programming-cellcog)
     cowork_working_directory: str = None, # Working dir for co-work
+    enable_browse: bool = False,          # Drive the user's REAL Chrome (needs Desktop + extension;
+                                          #   auto-enables co-work server-side)
+    browser_profile_id: str = None,       # profileDir from get_browser_status() (None = "Default")
+    enable_tools: bool = False,           # The user's connected SaaS tools (Gmail, Notion, ...)
+    tools_selection: list = None,         # Toolkit slugs to restrict to (None = ALL connected tools)
 )
 ```
 
@@ -39,10 +58,13 @@ result = client.create_chat(
 {
     "chat_id": str,        # CellCog chat ID
     "is_operating": bool,  # True = still working, False = done
-    "status": str,         # "completed" | "tracking" | "timeout"
+    "status": str,         # "completed" | "tracking" | "accepted" | "operating"
     "message": str,        # THE printable message — always print in full
 }
 ```
+A wait that gives up returns `status="operating"` with `timed_out=True` — the chat is
+STILL running server-side; resume with `wait_for_completion()`. `"timeout"` is no longer
+returned (it read as failure and misfired retry logic).
 
 **Raises:**
 - `PaymentRequiredError` (402) — insufficient credits
@@ -54,12 +76,16 @@ result = client.create_chat(
 
 Continue an existing conversation. Same delivery modes as `create_chat()`.
 
+⚠️ The default BLOCKS until the chat's entire next run completes. When relaying messages
+to several chats, pass `delivery="send_only"` — otherwise the first send hangs your
+script for that chat's whole run.
+
 ```python
 result = client.send_message(
     chat_id: str,                         # Existing chat (required)
     message: str,                         # Follow-up message (required)
     task_label: str = None,               # Label for this message
-    delivery: str = "wait_for_completion",# "wait_for_completion" or "notify_on_completion"
+    delivery: str = "wait_for_completion",# "wait_for_completion" | "send_only" | "notify_on_completion"
     timeout: int = 1800,                  # Max wait seconds (wait mode only)
     notify_session_key: str = None,       # OpenClaw session key (notify mode only)
     gateway_url: str = None,              # OpenClaw Gateway URL (notify mode only)
@@ -81,7 +107,7 @@ completion = client.wait_for_completion(
 
 **Returns:** Same `{chat_id, is_operating, status, message}` shape.
 - `status: "completed"` — chat finished, `message` contains full results
-- `status: "timeout"` — still working, `message` contains progress
+- `status: "operating"` + `timed_out: True` — still working server-side, `message` contains progress; resume with another `wait_for_completion()`
 
 ### get_history()
 
@@ -104,7 +130,50 @@ Quick status check (no message content).
 status = client.get_status(chat_id: str)
 ```
 
-**Returns:** `{"is_operating": bool, "status": str, "name": str, ...}`
+**Returns:** `{"is_operating": bool, "status": str, "name": str, "latest_update": str | None, ...}`
+
+`latest_update` carries the agent's most recent progress one-liner — poll it for live
+orchestration dashboards. `None` until the agent posts its first update of a run.
+
+### get_browser_status()
+
+Browse availability on the user's machine — populate a profile picker from this.
+
+```python
+status = client.get_browser_status()
+# {
+#   "extension_installed": bool,
+#   "chrome_running": bool,
+#   "active_profile": {...} | None,
+#   "available_profiles": [
+#     {"profileDir": "Default", "profileName": "Nitish", "hostedDomain": None,
+#      "hasExtension": True, "connected": True}, ...
+#   ],
+#   "agent_tab_count": int,
+# }
+```
+
+Pass a profile's `profileDir` as `browser_profile_id` in `create_chat(enable_browse=True)`.
+
+### list_toolkits()
+
+The SaaS toolkit catalog with the user's connection state — populate a tool picker from this.
+
+```python
+toolkits = client.list_toolkits(connected_only=True)   # only what the user connected
+# [{"slug": "gmail", "name": "Gmail", "connection": {...}, ...}, ...]
+```
+
+Pass toolkit `slug` values as `tools_selection` in `create_chat(enable_tools=True)`.
+
+### list_toolkit_tools()
+
+The individual tools a toolkit carries (for showing what enabling it unlocks).
+`tools_selection` itself takes TOOLKIT slugs, not tool slugs.
+
+```python
+tools = client.list_toolkit_tools("gmail")
+```
 
 ### delete_chat()
 

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/files.py

@@ -14,6 +14,7 @@ import requests
 
 from .config import Config
 from .exceptions import FileDownloadError, FileUploadError
+from .state_paths import state_path
 
 
 class FileProcessor:
@@ -36,7 +37,7 @@ class FileProcessor:
 
     def __init__(self, config: Config):
         self.config = config
-        self.default_download_dir = Path("~/.cellcog/chats").expanduser()
+        self.default_download_dir = state_path("chats")
 
     def transform_outgoing(self, message: str) -> tuple[str, list]:
         """

{cellcog-2.3.0 → cellcog-2.4.0}/cellcog/message_processor.py

@@ -16,6 +16,7 @@ from .message_formatter import (
     format_messages_for_delivery,
     session_key_to_filename,
 )
+from .state_paths import state_path
 
 if TYPE_CHECKING:
     from .config import Config
@@ -63,7 +64,7 @@ class MessageProcessor:
         """
         self.config = config
         self.files = file_processor
-        self.chats_dir = Path("~/.cellcog/chats").expanduser()
+        self.chats_dir = state_path("chats")
     
     def process_for_delivery(
         self,

cellcog-2.4.0/cellcog/state_paths.py

@@ -0,0 +1,83 @@
+"""
+CellCog SDK state-directory resolution (CEL-1300 item 1).
+
+All SDK state (tracked chats, downloaded files, daemon pid/heartbeat/version/log,
+seen indices) lives under ONE base directory, resolved once per process:
+
+1. $CELLCOG_STATE_DIR — explicit override, always wins.
+2. ~/.cellcog — the default, when the home directory is usable and writable.
+3. $TMPDIR/cellcog-state-{uid} — fallback for headless/container environments
+   where HOME is unset, '/', or not writable (e.g. Docker with HOME=/). A
+   one-line note is printed to stderr the first time the fallback engages,
+   naming CELLCOG_STATE_DIR as the override.
+
+Historically the SDK hardcoded Path("~/.cellcog").expanduser() everywhere, so a
+container with HOME=/ crashed the CellCogClient constructor with a raw
+PermissionError before any API call. Every path helper now routes through
+state_dir()/state_path() — never hardcode ~/.cellcog anywhere else.
+"""
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+_resolved: Optional[Path] = None
+_fallback_noted = False
+
+
+def _is_dir_usable(path: Path) -> bool:
+    """True if `path` exists (or can be created) and is writable."""
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".cellcog_write_probe"
+        probe.touch()
+        probe.unlink(missing_ok=True)
+        return True
+    except Exception:
+        return False
+
+
+def state_dir() -> Path:
+    """Resolve (once per process) and return the SDK state base directory."""
+    global _resolved, _fallback_noted
+    if _resolved is not None:
+        return _resolved
+
+    override = os.environ.get("CELLCOG_STATE_DIR")
+    if override:
+        candidate = Path(override).expanduser()
+        if _is_dir_usable(candidate):
+            _resolved = candidate
+            return _resolved
+        print(
+            f"Warning: CELLCOG_STATE_DIR={override!r} is not writable; "
+            "falling back to default state-dir resolution.",
+            file=sys.stderr,
+        )
+
+    home_candidate = Path("~/.cellcog").expanduser()
+    # Guard the degenerate expansion ('/.cellcog' when HOME is '/' or unset):
+    # even where root could write it, polluting the fs root is never the intent.
+    if str(home_candidate) != "/.cellcog" and _is_dir_usable(home_candidate):
+        _resolved = home_candidate
+        return _resolved
+
+    uid = os.getuid() if hasattr(os, "getuid") else "user"
+    fallback = Path(tempfile.gettempdir()) / f"cellcog-state-{uid}"
+    _is_dir_usable(fallback)  # best-effort create
+    if not _fallback_noted:
+        print(
+            f"Note: using {fallback} for CellCog SDK state (home directory not "
+            "writable). Set CELLCOG_STATE_DIR to choose a persistent location.",
+            file=sys.stderr,
+        )
+        _fallback_noted = True
+    _resolved = fallback
+    return _resolved
+
+
+def state_path(*parts: str) -> Path:
+    """A path under the state dir, e.g. state_path('chats') or state_path('daemon.pid')."""
+    return state_dir().joinpath(*parts)

{cellcog-2.3.0 → cellcog-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cellcog"
-version = "2.3.0"
+version = "2.4.0"
 description = "Python SDK for CellCog - Any-to-Any AI for agents. Fire-and-forget pattern with WebSocket notifications."
 readme = "README.md"
 license = {text = "MIT"}