Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
fix(cli_agent): wire Claude Code login through `claude auth login` (cli-reference)
trohitg7b3dc2f26a42
diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.mdindex 9b69c1e0..5638d998 100644--- a/docs-internal/cli_agent_framework.md+++ b/docs-internal/cli_agent_framework.md@@ -1,250 +1,101 @@-# AI CLI Agent Framework — Claude Code + Codex (v1), Gemini (v2)+# AI CLI Agent Framework-## Context+Multi-instance, multi-provider runtime for AI CLI agents (Claude Code, Codex, Gemini). One workflow node spawns N parallel CLI sessions over a list of tasks, each isolated in its own git worktree, each able to call back into MachinaOs over MCP.-`claude_code_agent` ([server/services/claude_code_service.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/claude_code_service.py)) today is single-instance, single-shot, Claude-only: wraps `asyncio.create_subprocess_exec` with `proc.communicate()`, hardcoded 300s `wait_for`, bypasses the existing `_supervisor` framework, and returns plain text.--**Scope priority — heavy bias toward Claude + Codex.** v1 ships these two only; Gemini is designed-for but deferred to v2. Rationale:--- **Claude Code** = the marquee provider. Full feature surface (sessions, resume, budget, turns, `allowedTools`, `permission-mode`), best stream-json (cost+turns+session_id in `result` event), mature MCP/IDE lockfile integration. Reference implementation for the VSCode pattern.-- **Codex** = the safety-first companion. Sandbox enforcement (`read-only|workspace-write|danger-full-access`) and `--ask-for-approval` make it the right pick for risk-bounded tasks even though it lacks sessions/resume/cost.-- **Gemini** = parity is straightforward but not load-bearing — the abstraction is built to absorb it without refactor in v2.--We need:--1. **Multi-instance** — one workflow node summons N parallel CLI sessions over a list of tasks, each isolated, returning aggregated structured output, cancellable.-2. **Multi-provider abstraction now** — even though only two providers ship in v1, the Protocol/factory/config layer is built upfront so adding Gemini in v2 is a drop-in.-3. **Tool/context injection without custom IPC** — follow VSCode/Cursor exactly: host an MCP server, write a discovery lock file, let CLIs auto-discover MachinaOs tools via the standard MCP protocol. v1 wires this for Claude (where it works today) and writes the lock file for Codex (cheap; Codex CLI doesn't honor it yet but will).-4. **Native CLI auth — no token wrapping** — the CLIs already have working `claude login` / `codex login` flows that store credentials in their own canonical locations (`~/.claude/`, `~/.codex/`, `~/.gemini/`). MachinaOs **does not** copy, encrypt, or relocate those credentials. We only **trigger** the native login flow and **detect** logged-in state. No isolated `~/.claude-machina/` auth dir for the new framework. No `codex_oauth.py` / `gemini_oauth.py` token-management modules.--The fix reuses three existing assets:--- **Supervisor framework** ([_supervisor/base.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/base.py), [process.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/process.py), [util.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/util.py)) — locked idempotent start/stop, `terminate_then_kill(grace=5s)`, recursive `kill_tree`, drain-task cancel, Windows `CTRL_BREAK_EVENT`. Canonical consumer: [whatsapp/_runtime.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/nodes/whatsapp/_runtime.py).-- **Native LLM provider layer** ([llm/protocol.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/protocol.py), [factory.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/factory.py), [providers/](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/providers)) — `@runtime_checkable` Protocol + lazy-import factory + JSON config. Mirror exactly for CLI providers.-- **Credentials registry** ([credential_registry.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/credential_registry.py), [credential_providers.json](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/config/credential_providers.json)) — add `_cli_base` abstract entry + three concrete entries via deep-merge.--## Confirmed design decisions--| Decision | Choice |-|---|---|-| Source branch | `credentials-scaling-v2` (current worktree) |-| Implementation worktree | **NEW** worktree at `D:\startup\projects\machinaos-worktrees\cli-agent-framework` on branch `feat/cli-agent-framework` (off `credentials-scaling-v2`) |-| Scope (v1) | **Claude Code + Codex** (heavy bias). Gemini provider/plugin/oauth/tests deferred to v2. |-| Per-task isolation | git worktree per task (fail batch early if `working_directory` is not a git repo) |-| Concurrency cap | 5 parallel sessions per pool (`asyncio.Semaphore`) |-| Failure mode | Continue-on-error; per-task success/error returned, batch always settles |-| Resumption | Claude: `--session-id`/`--resume`. Codex: N/A. (Gemini v2: `--session-id`/`--resume`) |-| Provider feature gaps | Discriminated-union Pydantic TaskSpec — `ClaudeTaskSpec` / `CodexTaskSpec` (v2 adds `GeminiTaskSpec` to the union) |-| Tool/context injection | **VSCode pattern**: local MCP server + lock file, no custom IPC. v1 active for Claude; v1 writes lock for Codex (cheap, future-proofs); Gemini v2. |-| Node shape | Two plugins in v1: `claude_code_agent` (refactored), `codex_agent` (new). v2 adds `gemini_cli_agent`. |--## Step 0 — bootstrap (first actions after ExitPlanMode)--**0a. Copy plan into the repo as a versioned design doc** so it's reviewable, diffable, and lives alongside the existing `docs-internal/` design docs:--```bash-cp C:/Users/Tgroh/.claude/plans/analyze-the-claude-code-purrfect-sunbeam.md \- D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/docs-internal/cli_agent_framework.md-```--Drop the path-specific Windows-style absolute paths from the in-repo copy if they look out of place; the repo copy is the source of truth from this point forward.--**0b. Create the implementation worktree** off `credentials-scaling-v2`:--```bash-cd D:/startup/projects/machinaos-worktrees/credentials-scaling-v2-git worktree add -b feat/cli-agent-framework \- D:/startup/projects/machinaos-worktrees/cli-agent-framework \- credentials-scaling-v2-cd D:/startup/projects/machinaos-worktrees/cli-agent-framework-```--The new design doc (`docs-internal/cli_agent_framework.md`) is automatically present in the new worktree because `git worktree add` shares the working tree of the parent branch. All subsequent edits below land in the new worktree. The `credentials-scaling-v2` worktree stays clean except for the new design doc.--**0c. (Optional, recommended)** Commit the design doc on `credentials-scaling-v2` before branching, so it's traceable:--```bash-cd D:/startup/projects/machinaos-worktrees/credentials-scaling-v2-git add docs-internal/cli_agent_framework.md-git commit -m "docs: cli agent framework design (claude+codex v1, gemini v2)"-```--## CLI feature surface (raw GitHub source confirmed)--| Feature | Claude | Codex | Gemini |-|---|---|---|---|-| Headless flag | `--print -p` | `codex exec` | `--prompt -p` |-| JSON output | `--output-format json/stream-json` | `--json` (JSONL) | `--output-format json/stream-json` |-| Session ID | `--session-id <UUID>` | n/a | **`--session-id <UUID>`** (`config.ts`) |-| Resume | `--resume <UUID>` | n/a | `--resume latest|<idx>|<UUID>` |-| Model | `--model` | `--model` | `--model` |-| Max turns | `--max-turns <n>` | n/a | n/a |-| Budget | `--max-budget-usd <usd>` | n/a | n/a |-| Allowed tools | `--allowedTools` | n/a | n/a |-| MCP config | `--mcp-config <file>` + IDE lockfile auto-discovery | pre-config only (lockfile not yet honored) | `--mcp-config` + IDE lockfile auto-discovery |-| Sandbox | `--worktree` | `--sandbox read-only|workspace-write|danger-full-access` | `--sandbox` (Docker) |-| Auth env | `CLAUDE_CONFIG_DIR` | `CODEX_API_KEY_ENV_VAR` / `OPENAI_API_KEY_ENV_VAR` / `CODEX_AGENT_IDENTITY_ENV_VAR` | `GEMINI_CLI_HOME` |-| IDE lock env | `CLAUDE_IDE_LOCK` | (n/a v1) | `GEMINI_IDE_LOCK` |-| Cost in JSON | `total_cost_usd` | absent | absent (`stats.duration_ms` only) |-| Exit codes | 0=ok, 1=error | 0=ok, non-0=error | 0=ok, 1=`FatalAuthenticationError`, EPIPE→0 |--## Confirmed JSON event schemas (vendored from source)--**Claude `--output-format stream-json`:**-```-{"type":"system","subtype":"init","session_id":"<UUID>"}-{"type":"assistant","message":{...},"session_id":"<UUID>"}-{"type":"tool_use","tool_name":"...","tool_input":{...}}-{"type":"result","subtype":"success","result":"...","total_cost_usd":0.42,- "duration_ms":18234,"num_turns":7,"session_id":"<UUID>"}-```-Final: `type=="result"`. Carries `total_cost_usd, duration_ms, num_turns, session_id`.--**Gemini** (`packages/cli/src/nonInteractiveCli.ts`):-```typescript-enum JsonStreamEventType {- INIT='init', MESSAGE='message', TOOL_USE='tool_use',- TOOL_RESULT='tool_result', ERROR='error', RESULT='result'-}-// RESULT: { type:'result', timestamp:<ISO8601>, status:'success',-// session_id:<UUID>, stats:{ duration_ms } }-```-Final: `type=="result"`. Carries `session_id` + `stats.duration_ms`. No USD.--**Codex** (`codex-rs/cli/src/main.rs`, Rust + `clap` v4): JS wrapper at `codex-cli/bin/codex.js` is pass-through (`spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" })`). No public stream-json schema; best-effort `type=="complete"` or stream-end fallback. `cost_usd=null` always.+| Provider | Status | Login flow |+|---|---|---|+| Claude Code (`@anthropic-ai/claude-code`) | shipping | Local-install + spawn (`services/claude_oauth.py:initiate_claude_oauth`) |+| OpenAI Codex (`@openai/codex`) | shipping (no login flow yet) | User runs `codex login` manually; UI returns a graceful "not yet wired" error |+| Google Gemini (`@google/gemini-cli`) | v2 stub | factory raises `NotImplementedError` |## Architecture```-ClaudeCodeAgentNode (v1) CodexAgentNode (v1) [GeminiCliAgentNode v2]- │ Params.tasks: list[ClaudeTaskSpec] list[CodexTaskSpec]- ▼-AICliService.run_batch(provider, params, *, node_id, workflow_id, workspace_dir)- │ provider = create_cli_provider(provider_name)- │ "claude" → AnthropicClaudeProvider "codex" → OpenAICodexProvider- │ "gemini" → NotImplementedError("deferred to v2")- │ allocate per-batch bearer token; register in MCP token registry+ClaudeCodeAgentNode (claude_code_agent) CodexAgentNode (codex_agent)+ │ Params.tasks: list[ClaudeTaskSpec] list[CodexTaskSpec]▼-AICliBatchPool(provider, sessions[N], semaphore=5, batch_token)- │ asyncio.gather(return_exceptions=False)+AICliService.run_batch(provider, tasks, *, node_id, workflow_id, workspace_dir)+ │ provider = create_cli_provider(name) ("claude" | "codex" | "gemini"→NotImpl)+ │ allocate per-batch bearer token; register BatchContext in MCP token registry+ │ asyncio.gather under Semaphore(5)│- ├──► AICliSession_0(BaseProcessSupervisor, ClaudeProvider, ClaudeTaskSpec)- │ _pre_spawn(): git worktree add + write ~/.claude/ide/<pid>.lock- │ _do_start(): anyio.open_process + NDJSON consumers- │ env: inherits parent (claude CLI reads its native ~/.claude/)- │ + CLAUDE_IDE_LOCK=<path>- │ + MACHINA_PARENT_RUN_ID=<wf>:<node>:<token8>- │ (Claude CLI auto-discovers MCP, gains mcp__machina__* tools)+ ├──► AICliSession_0 (BaseProcessSupervisor + ClaudeProvider + ClaudeTaskSpec)+ │ _pre_spawn(): git worktree add + write ~/.claude/ide/<pid>.lock+ │ _do_start(): anyio.open_process + NDJSON stdout/stderr consumers+ │ env: CLAUDE_IDE_LOCK + MACHINA_PARENT_RUN_ID│ wait_for_completion(timeout)- │ cleanup(): stop()=terminate_then_kill(5s) + remove lockfile + worktree remove- └──► AICliSession_1(CodexProvider, CodexTaskSpec)- _pre_spawn(): git worktree add (no lockfile env — Codex CLI doesn't honor it yet)- _do_start(): argv has --sandbox + --ask-for-approval- env: inherits parent (codex CLI reads its native ~/.codex/auth.json)- (sandbox enforced by CLI itself)- wait_for_completion(timeout)- cleanup(): stop() + worktree remove+ │ cleanup(): stop()=terminate_then_kill(5s) + rm lockfile + worktree remove│- │ ◄────── CLI calls back via MCP/HTTP- │ POST http://127.0.0.1:<port>/mcp/ide- │ Authorization: Bearer <batch-token>- │ tools: getWorkspaceFiles | getSkills | getCredential | broadcastLog+ └──► AICliSession_N (CodexProvider + CodexTaskSpec)+ (no lockfile yet — Codex CLI doesn't honor it; written when upstream supports it)+ │+ │ ◄──── CLI calls back via MCP/HTTP at /mcp/ide+ │ Authorization: Bearer <batch-token> (per-batch isolation)+ │ tools: getWorkspaceFiles, listSkills, getSkill, getCredential, broadcastLog▼-BatchResult{ tasks: [...], summary: {n_tasks, n_succeeded, n_failed,- total_cost_usd?, wall_clock_ms} }- │ batch_token deregistered in finally+BatchResult { tasks: [SessionResult, ...], n_succeeded, n_failed, total_cost_usd?, wall_clock_ms }+ │ token deregistered in finally▼-existing Temporal heartbeat hook wakes on each broadcast (activities.py:228)-existing tool-result envelope truncates response at 4000 chars (handlers/tools.py:678)+existing Temporal heartbeat fires per WS broadcast (services/temporal/activities.py:228)+existing tool-result envelope truncates response at 4000 chars (services/handlers/tools.py:678)```+Reuses (do not duplicate):++- `services/_supervisor/{base,process,util}.py` — `BaseProcessSupervisor` (locked start/stop, `kill_tree`, `terminate_then_kill(5s)`, drain tasks, Windows `CTRL_BREAK_EVENT`)+- `services/llm/{protocol,factory,config}.py` — Protocol + lazy-import factory + JSON config blueprint+- `services/handlers/tools.py:678` — 4000-char truncation+- `services/status_broadcaster.py` — `update_node_status`, `broadcast_terminal_log`+- `services/skill_loader.py` — `scan_skills` / `load_skill` consumed by MCP `listSkills` / `getSkill`+- `services/auth.py` — `AuthService.get_api_key` consumed by MCP `getCredential`+- `services/credential_registry.py` — deep-merge `extends` for `_cli_base` entry+- `services/claude_oauth.py` — Claude `auth login` / `auth status` / `auth logout` wrappers, project-local npm install at `<repo>/data/claude-machina/npm/`, inherited stdio so the CLI opens the browser itself+- `nodes/stripe/_handlers.py` — pattern reference for marker-token + catalogue broadcast+## Provider abstraction (mirrors `services/llm/`)```python# server/services/cli_agent/protocol.py@runtime_checkableclass AICliProvider(Protocol):- name: str # "claude" | "codex" | "gemini"- package_name: str # npm package- binary_name: str # "claude" | "codex" | "gemini"- ide_lock_env_var: Optional[str] # CLAUDE_IDE_LOCK | GEMINI_IDE_LOCK | None- ide_lockfile_dir: Optional[Path] # ~/.claude/ide | <tmpdir>/gemini/ide- # NOTE: no auth_dir_env_var / isolated_auth_dir. The CLI uses its own- # native auth storage (~/.claude/, ~/.codex/, ~/.gemini/). We do not wrap.+ name: str+ package_name: str+ binary_name: str+ ide_lock_env_var: Optional[str] # CLAUDE_IDE_LOCK | GEMINI_IDE_LOCK | None+ ide_lockfile_dir: Optional[Path] # ~/.claude/ide | <tmpdir>/gemini/idedef binary_path(self) -> Path: ...def headless_argv(self, task, *, defaults) -> list[str]: ...- def login_argv(self) -> list[str]: ...- # Returns the CLI's own native login command, e.g. ["claude", "login"]- # or ["codex", "login"]. Spawned interactively from the Credentials- # Modal. CLI stores its own credentials; we don't intercept.- def auth_status_argv(self) -> Optional[list[str]]: ...- # Optional: a no-op command to verify auth (e.g. ["claude", "--version"]- # combined with a no-op `--print -p ""` invocation). If None, we infer- # from the next session's stderr matcher.- def detect_auth_error(self, stderr: str, exit_code: int) -> bool: ...- # Matcher for "not logged in" stderr patterns:- # Claude: "Please run 'claude login'"- # Codex: HTTP 401 / "OPENAI_API_KEY not set"- # Gemini: exit_code == 1 (FatalAuthenticationError)+ def login_argv(self) -> list[str]: ... # CLI's own login command+ def auth_status_argv(self) -> Optional[list[str]]: ... # cheap probe+ def detect_auth_error(self, stderr, exit_code) -> bool: ...def parse_event(self, line: str) -> Optional[dict]: ...def is_final_event(self, event: dict) -> bool: ...def event_to_session_result(self, events, stderr, exit_code) -> dict: ...- # Returns: { ...shared fields..., "provider_data": {<vendor-specific>} }- # provider_data carries vendor-only metadata (Anthropic reasoning_details,- # Codex call_id, Gemini extra_content) without bloating the shared schema.- # Pattern from Hermes agent/transports/types.py.- def canonical_usage(self, events) -> dict: ...- # Normalize vendor token-counting into {input, output, cache_read,- # cache_write, reasoning, request_count}. Pattern from Hermes- # agent/usage_pricing.py CanonicalUsage. Feeds existing services/pricing.py.+ # Returns: {...shared, "provider_data": {<vendor-specific>}}+ # provider_data carries Anthropic reasoning_details, Codex call_id,+ # Gemini extra_content — pattern from Hermes agent/transports/types.py.+ def canonical_usage(self, events) -> CanonicalUsage: ...+ # Normalises vendor token-counting; feeds services/pricing.py.def supports(self, feature: str) -> bool: ...- # features: max_budget, max_turns, session_id, resume, mcp_runtime, json_cost, ide_lockfile+ # max_budget | max_turns | session_id | resume | mcp_runtime+ # | json_cost | ide_lockfile | sandbox```+Factory:+```python# server/services/cli_agent/factory.py-def create_cli_provider(name: str) -> AICliProvider:- if name == "claude":- from .providers.anthropic_claude import AnthropicClaudeProvider- return AnthropicClaudeProvider()- if name == "codex":- from .providers.openai_codex import OpenAICodexProvider- return OpenAICodexProvider()- if name == "gemini":- from .providers.google_gemini import GoogleGeminiProvider- return GoogleGeminiProvider()- raise ValueError(f"Unknown CLI provider: {name}")-```+SUPPORTED_PROVIDERS = frozenset({"claude", "codex"}) # gemini is v2 stub-```jsonc-// server/config/ai_cli_providers.json-{- "claude": { "package_name":"@anthropic-ai/claude-code", "binary_name":"claude",- "login_argv": ["claude", "login"],- "auth_status_argv": ["claude", "--print", "-p", "ok"],- "ide_lock_env_var":"CLAUDE_IDE_LOCK",- "ide_lockfile_dir":"~/.claude/ide",- "default_model":"claude-sonnet-4-6", "default_max_turns":10,- "default_max_budget_usd":5.0, "default_allowed_tools":"Read,Edit,Bash,Glob,Grep,Write",- "supports":["max_budget","max_turns","session_id","resume","mcp_runtime","json_cost","ide_lockfile"] },- "codex": { "package_name":"@openai/codex", "binary_name":"codex",- "login_argv": ["codex", "login"],- "auth_status_argv": ["codex", "--version"],- "ide_lock_env_var": null, "ide_lockfile_dir": null,- "default_model":"gpt-5.2-codex", "default_sandbox":"workspace-write",- "default_ask_for_approval":"never", "supports":["sandbox"] },- "gemini": { "package_name":"@google/gemini-cli", "binary_name":"gemini",- "login_argv": ["gemini", "auth", "login"],- "auth_status_argv": ["gemini", "--version"],- "ide_lock_env_var":"GEMINI_IDE_LOCK",- "ide_lockfile_dir":"<tmpdir>/gemini/ide",- "default_model":"gemini-2.5-pro",- "supports":["session_id","resume","sandbox","mcp_runtime","ide_lockfile"] }-}+def create_cli_provider(name: str) -> AICliProvider:+ if name == "claude": return AnthropicClaudeProvider()+ if name == "codex": return OpenAICodexProvider()+ if name == "gemini": raise NotImplementedError("gemini deferred to v2")+ raise ValueError(f"Unknown CLI provider: {name!r}")```-## Discriminated-union TaskSpec+## Task specs (discriminated union)```python# server/services/cli_agent/types.py@@ -258,23 +109,22 @@ class BaseAICliTaskSpec(BaseModel):class ClaudeTaskSpec(BaseAICliTaskSpec):provider: Literal["claude"] = "claude"- session_id: Optional[str] = None # start a named session+ session_id: Optional[str] = Noneresume_session_id: Optional[str] = None- max_turns: Optional[int] = Field(None, ge=1)- max_budget_usd: Optional[float] = Field(None, ge=0)+ max_turns: Optional[int] = None+ max_budget_usd: Optional[float] = Noneallowed_tools: Optional[str] = None- permission_mode: Literal["default","acceptEdits","plan","auto"] = "acceptEdits"+ permission_mode: Literal["default", "acceptEdits", "plan", "auto"] = "acceptEdits"class CodexTaskSpec(BaseAICliTaskSpec):provider: Literal["codex"] = "codex"- sandbox: Literal["read-only","workspace-write","danger-full-access"] = "workspace-write"- ask_for_approval: Literal["untrusted","on-request","never"] = "never"+ sandbox: Literal["read-only", "workspace-write", "danger-full-access"] = "workspace-write"+ ask_for_approval: Literal["untrusted", "on-request", "never"] = "never"-# GeminiTaskSpec defined in v1 types.py but plugin/provider stubbed as NotImplementedErrorclass GeminiTaskSpec(BaseAICliTaskSpec):provider: Literal["gemini"] = "gemini"session_id: Optional[str] = None- resume: Optional[str] = None # "latest" | "<idx>" | "<UUID>"+ resume: Optional[str] = Noneyolo: bool = Falsesandbox: bool = False@@ -284,299 +134,111 @@ AICliTaskSpec = Annotated[]```-Each plugin's `Params.tasks` is hard-typed to one variant — the LLM tool schema fast-path at [ai.py:2898](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/ai.py#L2898) gets a clean per-provider schema with no `$defs`.+Each plugin's `Params.tasks` is hard-typed to one variant — the LLM tool-schema fast-path at `services/ai.py:2898` produces a clean per-provider schema (no `$defs`/`$ref`).-**v1 ships `ClaudeTaskSpec` + `CodexTaskSpec` plugins fully wired.** `GeminiTaskSpec` is in the union (and exported) so the type system, factory dispatch keys, and config JSON are ready, but `create_cli_provider("gemini")` raises `NotImplementedError("gemini provider deferred to v2")`.+## Auth model — Stripe-style CLI-managed OAuth-## Auth model — native CLI handles its own tokens+CLI auth is delegated to the CLI's own login flow + a synthetic marker token in MachinaOs's catalogue. Mirrors `nodes/stripe/_handlers.py` (commit `a32f671`).-**Principle**: each CLI ships with a working auth flow. Don't reinvent it. Don't wrap it. Don't relocate the credentials. We only **trigger** the native flow and **detect** the resulting auth state.+**Per-provider WS handler names** (Twitter / Google / Stripe convention — frontend dispatches `{}` payload, handler name encodes provider):-| Concern | What we do | What we don't do |+| Catalogue id | Login handler | Logout handler ||---|---|---|-| Storage | CLI writes to its native location (`~/.claude/`, `~/.codex/`, `~/.gemini/`) | We **don't** copy/encrypt/relocate to `~/.claude-machina/`, our credentials.db, or anywhere else |-| Login trigger | Credentials Modal "Login with Claude/Codex/Gemini" button → WS handler spawns `provider.login_argv()` interactively (PTY or `stdio="inherit"`); user completes browser/device flow; we wait on exit | We **don't** orchestrate OAuth, exchange codes, refresh tokens, or store secrets |-| Status check | `provider.auth_status_argv()` no-op invocation; capture exit code + stderr through `provider.detect_auth_error()` | We **don't** poll `~/.claude/.credentials.json` or parse provider-internal state files |-| Refresh | The CLI handles refresh transparently | We **don't** schedule refresh jobs or manage token TTLs |-| Multi-tenancy | Single user per host (matches every dev who runs `claude`/`codex` locally) | We **don't** support per-MachinaOs-user isolated CLI auth in v1 — out of scope, v2 only if needed |-| Failure recovery | First detected `detect_auth_error()` short-circuits the batch with `error="not_authenticated"` and a hint pointing to the Credentials Modal | We **don't** retry, refresh, or attempt to re-auth mid-batch |--**Implication**: no `claude_oauth.py` / `codex_oauth.py` / `gemini_oauth.py` modules to write or maintain. The existing `claude_oauth.py` (which manages the legacy `~/.claude-machina/` install for `claude_code_service.py`) stays unchanged for back-compat with the legacy single-task path, but the new `cli_agent/` framework does not use it.+| `claude_code` | `claude_code_login` | `claude_code_logout` |+| `codex_cli` | `codex_cli_login` (returns "not yet wired") | `codex_cli_logout` |-**Trade-offs accepted**:-- Anyone running MachinaOs on a host shares the host's CLI auth — same as anyone running `code .` shares VSCode's auth. Acceptable.-- We can't migrate auth between hosts via our credentials system. If users want that, they re-run `claude login` on the new host.-- Multiple parallel sessions hitting the CLI's token at once may race on refresh in rare cases. The CLIs handle this internally; if it shows up, we retry once on `detect_auth_error()` before failing the task.+**Claude flow** (`server/services/cli_agent/_handlers.py:handle_claude_code_login`) uses the documented CLI subcommands from [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference):-## VSCode-style IDE MCP server (v1 core, no custom IPC)+| Subcommand | Purpose |+|---|---|+| `claude auth login` | Opens the browser, writes credentials |+| `claude auth status` | Exits 0 when logged in, 1 otherwise |+| `claude auth logout` | Clears credentials |-VSCode Claude Code extension does, on activation:-1. Start MCP server on `127.0.0.1:<random-port>`-2. Write `~/.claude/ide/<vscode-pid>.lock` = `{"port":..., "authToken":"<32-hex>"}`-3. Spawn `claude` with `--mcp-config <tmp>` + IDE env-4. CLI reads lock, connects via Bearer `<authToken>`, gains `mcp__ide__*` tools+Steps:-Gemini's VSCode companion: same shape, lock at `<tmpdir>/gemini/ide/gemini-ide-server-${PID}-${PORT}.json`.+1. Run `claude auth status`. If it exits 0, write the marker + broadcast and return immediately (idempotent re-click).+2. Otherwise call `services.claude_oauth.initiate_claude_oauth()`:+ - Project-local install of `@anthropic-ai/claude-code` into `<repo>/data/claude-machina/npm/` via `npm install --prefix` (mirrors WhatsApp's `<repo>/node_modules/edgymeow/` layout; skipped if already installed).+ - `asyncio.create_subprocess_exec(claude, "auth", "login", env={..., CLAUDE_CONFIG_DIR=<repo>/data/claude-machina})` with **inherited stdio** — same way the VSCode Claude Code extension delegates to the binary. Anthropic doesn't expose `--print-url` or a programmatic OAuth helper (issue [anthropics/claude-code#7100](https://github.com/anthropics/claude-code/issues/7100), closed "not planned"), so we let the CLI open the user's browser via its own OS-level call. Returns `{success: True, pid}` immediately.+3. Schedule a background task that polls `claude auth status` every 2s up to 600s. On exit-0, write the synthetic `"cli-managed"` marker via `auth_service.store_oauth_tokens("claude_code", ...)` and broadcast `credential_catalogue_updated`. The catalogue's `stored` flag flips and the existing `OAuthConnect.tsx` primitive renders the modal as Connected.-We mirror exactly. **No custom protocol invented.**+**Logout**: runs `claude auth logout`, drops the marker via `auth_service.remove_oauth_tokens()`, and broadcasts.-### MachinaOs MCP tools (mirror existing capabilities)+**Codex login**: not yet wired. The handler returns a graceful error pointing the user at `npm install -g @openai/codex` + `codex login` manual flow. Follow-up: write `services/codex_oauth.py` mirroring `claude_oauth.py` with `HOME=~/.codex-machina` env redirect (Codex has no `CONFIG_DIR` equivalent).-| MCP tool | Maps to | Returns |-|---|---|---|-| `mcp__machina__getWorkspaceFiles` | `LocalShellBackend.glob/read_file` over `workspace_dir` (reuse [filesystem.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/handlers/filesystem.py)) | `{path, content?, mtime, size}` per file. `read=False` mode returns metadata only. |-| `mcp__machina__listSkills` | `SkillLoader.scan_skills()` — returns metadata only for skills connected to the parent agent node (via `BatchContext.connected_skill_names`) | List of `{name, description, allowed_tools, category}` per skill. ~100 tokens each (progressive disclosure pattern). |-| `mcp__machina__getSkill` | `SkillLoader.load_skill(name)` — returns full skill content | `{name, description, instructions, allowed_tools, metadata, scripts: {fname: content}, references: {fname: content}}`. `assets` (binary) excluded by default; available via separate `getSkillAsset` if needed. |-| `mcp__machina__getCredential` | `auth_service.get_api_key()` — gated by per-batch allowlist | `{key, value}` if name is in `BatchContext.allowed_credentials`, else 403. |-| `mcp__machina__broadcastLog` | `broadcaster.broadcast_terminal_log()` — CLI sub-tasks log to Terminal tab | `{success: true}`. Side effect: log appears in MachinaOs Terminal tab tagged with the source CLI session. |+**Frontend**: no changes. The existing `client/src/components/credentials/primitives/OAuthConnect.tsx:42-44` already documents and supports the Stripe-style fieldless-CLI case (`config.fields = []`, `kind: "oauth"`, `stored` flag drives Connected state).-`getDiagnostics` and `executeCode` deferred to v2.+## VSCode-style IDE MCP server-### Skill exposure — concrete SKILL.md schema+Spawned CLI sessions auto-discover MachinaOs over MCP via the lockfile pattern VSCode's Claude Code extension uses. No custom IPC.-Skills live at `server/skills/<folder>/<skill-name>/SKILL.md` with YAML frontmatter + markdown body. Reference: [`server/skills/social_agent/twitter-search-skill/SKILL.md`](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/skills/social_agent/twitter-search-skill/SKILL.md). The `SkillLoader` ([skill_loader.py:19-35](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/skill_loader.py#L19-L35)) parses to:+Lockfile path: `~/.claude/ide/<pid>.lock` (Claude) or `<tmpdir>/gemini/ide/gemini-ide-server-<pid>-<port>.json` (Gemini, v2). Format mirrors VSCode exactly:-```python-@dataclass-class SkillMetadata:- name: str # "twitter-search-skill"- description: str # one-line LLM-visible hook- allowed_tools: list[str] # ["twitter_search"] — informational v1- metadata: dict[str, Any] # {author, version, category, icon, color}- path: Optional[Path]--@dataclass-class Skill:- metadata: SkillMetadata- instructions: str # full markdown body- scripts: dict[str, str] # exec code samples (filename→content)- references: dict[str, str] # extra docs (filename→content)- assets: dict[str, bytes] # binary attachments+```json+{+ "port": 3010,+ "url": "http://127.0.0.1:3010/mcp/ide",+ "authToken": "<32-byte hex>",+ "workspaceFolders": ["<absolute path to per-task git worktree>"],+ "ideName": "machinaos",+ "transport": "http",+ "pid": 12345+}```-**Data source priority** (already implemented in `SkillLoader`):--1. Built-in: `server/skills/<folder>/<skill>/SKILL.md`-2. Project: `.machina/skills/` in CWD-3. User-created: database (UI-edited content takes precedence after first activation)+Bearer-token middleware (`mcp_server.py:_BearerAuthMiddleware`) validates each request against an in-memory per-batch `BatchContext` registry. Tokens registered at `AICliService.run_batch()` entry; unregistered in `finally` so 401s flip immediately when a batch settles.-**`allowed_tools` field is informational in v1** — the CLI agent gets its native tool set (Claude: `Read,Edit,Bash,Glob,Grep,Write` + connected MCP tools; Codex: sandbox-restricted shell). The `allowed_tools` list is included in `listSkills` response so the LLM understands intent ("this skill expects a `twitter_search` tool"), but we don't dynamically register MachinaOs tools as MCP tools per-skill in v1. v2 candidate.+Tools exposed (mirror MachinaOs capabilities; deferred ones marked):-**Progressive disclosure** matches Claude Code's Skill API design: `listSkills` is cheap (metadata only), `getSkill` is on-demand. CLI agent prompt should be guided to call `listSkills` first, then `getSkill(name)` only for relevant ones — keeps token budget tight.--**`BatchContext.connected_skill_names`** is populated at `run_batch()` entry by reusing [`_collect_agent_connections()`](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/nodes/agent/_inline.py) — same logic the existing `aiAgent` uses to find skills connected to its `input-skill` handle. So the CLI agent sees exactly the skills the user wired into the parent `claude_code_agent` / `codex_agent` node.--### Per-batch token isolation--- One token per `AICliBatchPool` (`secrets.token_hex(32)`)-- Lives in memory only; registered in `_active_tokens: dict[str, BatchContext]`-- Lock files (mode 0600 on POSIX) deleted in `cleanup()`-- MCP middleware validates `Authorization: Bearer <token>` → 401 if unknown/expired-- Each tool call resolves its `BatchContext` from the bearer token to scope `workspace_dir`, `node_id`, `allowed_credentials`--## Files to change / create+| Tool | Maps to | Returns |+|---|---|---|+| `mcp__machina__getWorkspaceFiles` | `Path.rglob` over `workspace_dir` | `{files: [{path, size, mtime, content?}]}` |+| `mcp__machina__listSkills` | `SkillLoader.scan_skills()` filtered to `BatchContext.connected_skill_names` | `{skills: [{name, description, allowed_tools, category}]}` (~100 tokens each) |+| `mcp__machina__getSkill` | `SkillLoader.load_skill(name)` | `{name, instructions, allowed_tools, scripts, references}` |+| `mcp__machina__getCredential` | `auth_service.get_api_key(name)`, gated by `BatchContext.allowed_credentials` | `{name, value}` or 403 |+| `mcp__machina__broadcastLog` | `broadcaster.broadcast_terminal_log()` | `{success}` |-All marked **v1** unless explicitly noted **v2 (deferred)**.+Lifespan: `main.py` enters `mcp_app.router.lifespan_context()` so `StreamableHTTPSessionManager`'s task group is alive (Starlette doesn't auto-propagate `app.mount()` lifespans). Stale-PID lockfile sweep on startup (mirrors VSCode's behaviour).-| File | Change | LoC |-|---|---|---|-| `server/services/cli_agent/__init__.py` | **Create (v1)**. Re-exports: `create_cli_provider`, `AICliService`, `AICliBatchPool`, `AICliSession`, task-spec classes (incl. `GeminiTaskSpec` for type completeness). | ~25 |-| `server/services/cli_agent/protocol.py` | **Create (v1)**. `AICliProvider` Protocol. Mirrors [llm/protocol.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/protocol.py). | ~90 |-| `server/services/cli_agent/types.py` | **Create (v1)**. `BaseAICliTaskSpec`, `ClaudeTaskSpec`, `CodexTaskSpec`, `GeminiTaskSpec` (Pydantic schema only — no runtime impl), `AICliTaskSpec` discriminated union, `SessionResult`, `BatchResult`. | ~140 |-| `server/services/cli_agent/config.py` | **Create (v1)**. Loads `ai_cli_providers.json` (all three entries present; gemini surfaces a `available=False` flag). Mirrors [llm/config.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/config.py). | ~60 |-| `server/services/cli_agent/factory.py` | **Create (v1)**. `create_cli_provider(name)` lazy factory; `name=="gemini"` raises `NotImplementedError("gemini provider deferred to v2")`. Mirrors [llm/factory.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/factory.py). | ~55 |-| `server/services/cli_agent/providers/anthropic_claude.py` | **Create (v1, primary)**. argv: `claude --print -p ... --output-format stream-json --include-partial-messages [--session-id|--resume] --model --max-turns --max-budget-usd --allowedTools --permission-mode --append-system-prompt`. **Auth: native** — no `CLAUDE_CONFIG_DIR` injection; CLI reads `~/.claude/`. Final = `result` event. **All Protocol features wired** — sessions, resume, budget, turns, allowed_tools, permission_mode, MCP lockfile, cost. **Binary resolution chain** (Composio pattern): (1) `shutil.which("claude")`, (2) `npx --yes @anthropic-ai/claude-code` shim. `login_argv = ["claude", "login"]`. `detect_auth_error` matches `"Please run 'claude login'"`. `canonical_usage()` extracts `{input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens}` from `result.usage`. `provider_data` Dict carries `reasoning_details` if present. Reference implementation. | ~200 |-| `server/services/cli_agent/providers/openai_codex.py` | **Create (v1)**. argv: `codex exec --json --model --sandbox --ask-for-approval <prompt>`. **Auth: native** — Codex reads its own `~/.codex/auth.json` after the user runs `codex login`. We don't set `OPENAI_API_KEY`. No session/resume/budget/turns. Final = `type=="complete"` or stream-end. `cost_usd=None`. Lockfile written but Codex CLI doesn't read it yet — no-op until upstream support lands. **Sandbox is the marquee feature**, exposed prominently in `CodexTaskSpec`. **Binary resolution chain**: (1) `shutil.which("codex")`, (2) `npx --yes @openai/codex` shim. `login_argv = ["codex", "login"]`. `detect_auth_error` matches HTTP 401 patterns + `"OPENAI_API_KEY not set"`. `canonical_usage()` returns zeros (Codex doesn't expose token counts in `--json`); `provider_data` Dict carries `call_id` and `response_item_id` per Codex schema. | ~170 |-| `server/services/cli_agent/providers/google_gemini.py` | **v2 (deferred)**. argv: `gemini --prompt <p> --output-format stream-json --model [--session-id] [--resume] [--yolo] [--sandbox]`. Auth `GEMINI_CLI_HOME=~/.gemini-machina`. Final = `type=="result"`. Stub left as `# TODO v2` placeholder so the factory raises a clean `NotImplementedError("gemini provider deferred to v2")`. | 0 v1 (~160 v2) |-| `server/services/cli_agent/session.py` | **Create (v1)**. `AICliSession(BaseProcessSupervisor)`. `pipe_streams=True`, `terminate_grace_seconds=5.0`, `graceful_shutdown=(sys.platform=="win32")`. `_pre_spawn`: git worktree add + write IDE lockfile. Override `_do_start` to wire NDJSON consumers + IDE env var + inject `MACHINA_PARENT_RUN_ID=<workflow_id>:<node_id>:<token_short>` (Composio pattern). **Heartbeat stale-detection**: track `(events_count, last_tool_use)` tuple per second; if frozen >60s, log warning + dump `{argv, env_keys, last_20_events, stderr_tail}` to `~/.claude-machina/logs/session-stale-<task_id>.log` (Hermes pattern). On `wait_for_completion` `TimeoutError`, dump same diagnostic to `session-timeout-<task_id>.log` before `stop()`. `cleanup`: stop + remove lockfile + worktree remove. NOT registered in global registry. | ~360 |-| `server/services/cli_agent/lockfile.py` | **Create**. `write_ide_lockfile(pid, port, token, workspace_dir, ide_name) -> Path`, `remove_ide_lockfile(path)`. Path varies per provider (Claude: `~/.claude-machina/ide/<pid>.lock`; Gemini: `<tmpdir>/gemini/ide/gemini-ide-server-<pid>-<port>.json`). 0600 on POSIX. Stale-PID sweep on startup. | ~100 |-| `server/services/cli_agent/mcp_server.py` | **Create (v1)**. FastAPI sub-app at `/mcp/ide` using official `mcp` Python SDK's `StreamableHTTPSessionManager`. Bearer-token middleware → `_active_tokens` registry. Exposes **5 tools**: `getWorkspaceFiles`, `listSkills`, `getSkill`, `getCredential`, `broadcastLog`. Each tool dereferences its `BatchContext` (set on `run_batch` entry via `_collect_agent_connections()`) to scope `workspace_dir`, `node_id`, `connected_skill_names`, and `allowed_credentials`. Skills exposed via the existing `SkillLoader` (progressive disclosure: `listSkills` returns metadata only, `getSkill` returns full markdown + scripts + references). | ~240 |-| `server/services/cli_agent/pool.py` | **Create**. `AICliBatchPool` — owns N sessions, gathers under `Semaphore(5)`. `cancel()` calls `cleanup()` on every session. Aggregates `BatchResult`. | ~120 |-| `server/services/cli_agent/service.py` | **Create**. `AICliService.run_batch(provider, params, *, node_id, workflow_id, workspace_dir, broadcaster)`. Allocates batch token, registers `BatchContext`, instantiates pool, runs, deregisters in finally. `cancel_workflow(wf)`, `cancel_node(node_id)`. | ~160 |-| `server/services/claude_code_service.py` | **Modify** to thin shim. Builds one `ClaudeTaskSpec`, calls `AICliService.run_batch("claude", ...)`. Drops 300s `wait_for`. Keeps legacy return shape. | ~50 (was ~140) |-| `server/services/cli_agent/login.py` | **Create (v1)**. Generic `run_native_login(provider) -> dict` helper. Spawns `provider.login_argv()` with stdio inherited (the CLI handles its own browser/device flow). Returns `{success, exit_code, stderr_tail}`. Used by `cli_login_<provider>` WS handlers. ~50 lines. **Replaces** the would-be `codex_oauth.py` / `gemini_oauth.py` / new `claude_oauth.py`. | ~50 |-| `server/services/cli_agent/auth_status.py` | **Create (v1)**. Generic `check_auth(provider) -> {logged_in: bool, hint: str}` helper. Runs `provider.auth_status_argv()` and feeds output to `provider.detect_auth_error()`. Used by Credentials Modal status row. ~40 lines. | ~40 |-| ~~`server/services/codex_oauth.py`~~ | **Removed from scope** — Codex CLI handles its own auth via `~/.codex/auth.json`; we don't wrap it. | 0 |-| ~~`server/services/gemini_oauth.py`~~ | **Removed from scope** (v2 also). Gemini CLI handles its own auth via `~/.gemini/`; v2 will use the same generic `run_native_login` helper, no per-provider OAuth module. | 0 |-| `server/services/claude_oauth.py` | **No change**. Legacy module used by the legacy `claude_code_service.py` shim. The new framework does not call it. Eventually deletable when the legacy shim goes. | 0 |-| `server/main.py` | **Modify**. Mount MCP sub-app: `app.mount("/mcp/ide", get_mcp_app())` in `lifespan`. Add startup stale-lockfile sweep call. | ~8 |-| `server/nodes/agent/claude_code_agent.py` | **Modify**. `Params.tasks: list[ClaudeTaskSpec]`. `execute_op`: verify git repo, build tasks (with legacy-`prompt` fallback to single-task), call `run_batch("claude", ...)`, emit `phase=batch_started`/`batch_complete`. | ~140 |-| `server/nodes/agent/codex_agent.py` | **Create (v1)**. `CodexAgentNode` with `Params.tasks: list[CodexTaskSpec]`. Visual: orange/black icon, group `("agent","ai")`. Sandbox dropdown surfaced as primary param. | ~130 |-| `server/nodes/agent/gemini_cli_agent.py` | **v2 (deferred)**. `GeminiCliAgentNode` with `Params.tasks: list[GeminiTaskSpec]`. Visual: blue/yellow icon. | 0 v1 (~120 v2) |-| `server/nodes/visuals.json` | **Modify (v1)**. Add `codexAgent` icon+color. (v2: add `geminiCliAgent`.) | ~5 |-| `server/config/credential_providers.json` | **Modify (v1)**. Add `_cli_base` abstract entry (`kind: "native_cli"`, no token storage — just a status hook + login button) + two concretes (`claude_code`, `codex_cli`) extending it. (v2 adds `gemini_cli`.) | ~50 |-| `server/routers/websocket.py` | **Modify (v1)**. Add **generic** `cli_login` and `cli_auth_status` handlers (one pair total, dispatched by `provider` field) that delegate to `cli_agent/login.py` and `cli_agent/auth_status.py`. **Replaces** what would have been per-provider `codex_oauth_login` / `claude_oauth_login` etc. | ~40 |-| `server/services/workflow.py` | **Modify**. `stop_execution` → `get_ai_cli_service().cancel_workflow(workflow_id)` alongside existing process cancel. | ~10 |-| `server/services/_supervisor/*` | **No change**. Used as-is. | 0 |-| `server/services/temporal/activities.py` | **No change**. Heartbeats already fire per WS broadcast. | 0 |-| `server/pyproject.toml` | **Modify**. Add `mcp>=1.0` to deps (pinned). | ~2 |-| `server/tests/services/test_cli_agent_providers.py` | **Create (v1)**. Claude + Codex: `headless_argv` shape, `parse_event` schema fidelity (vendored NDJSON), `event_to_session_result` reconstruction. Heaviest coverage on Claude (full feature set). | ~250 |-| `server/tests/services/test_cli_agent_session.py` | **Create (v1)**. Generic session: 3-task parallel happy path with mocked `anyio.open_process`; cancel mid-batch; worktree cleanup on exception; lockfile written/removed. | ~280 |-| `server/tests/services/test_cli_agent_mcp.py` | **Create (v1)**. MCP server: bearer-token auth (valid/invalid/expired), per-tool scoping, lock file format matches VSCode convention, cleanup of stale PIDs. Uses `mcp` SDK test client. | ~220 |-| `server/tests/nodes/test_claude_code_agent.py` | **Create/modify (v1)**. Single-task back-compat + 3-task parallel via Claude. Heavy coverage: sessions, resume, budget, turns, allowed_tools, permission_mode, MCP tool callback. | ~220 |-| `server/tests/nodes/test_codex_agent.py` | **Create (v1)**. 3-task parallel happy path; assert no `--max-budget-usd` / `--max-turns` / `--session-id` in argv; sandbox `read-only`/`workspace-write`/`danger-full-access` flags propagate; `--ask-for-approval` honored. | ~160 |-| `server/tests/nodes/test_gemini_cli_agent.py` | **v2 (deferred)**. 3-task parallel; `--session-id` roundtrip; `--resume latest`; yolo flag. | 0 v1 (~150 v2) |-| `client/src/components/AIAgentNode.tsx` | **No change**. Renders the three new agent kinds via `useNodeSpec(type)`; the array-of-rows `tasks` editor is auto-generated from JSON Schema. | 0 |--**Net code delta (v1)**: ~2200 lines added, ~90 removed (-240 from dropping `codex_oauth.py` + per-provider OAuth WS handlers; +90 for generic `login.py` / `auth_status.py` helpers). Two plugins (Claude refactor + Codex new), two providers, MCP server (VSCode-pattern), session/pool/service, generic native-auth shim. Supervisor framework reused as-is. New runtime dep: `mcp>=1.0`.--**v1 → v2 follow-up (Gemini, ~430 LoC)**:-- `providers/google_gemini.py` (replace stub) — ~160-- `nodes/agent/gemini_cli_agent.py` — ~120-- `tests/nodes/test_gemini_cli_agent.py` — ~150-- Update `factory.py` (drop `NotImplementedError`)-- Add `geminiCliAgent` to `visuals.json` and `gemini_cli` entry in `credential_providers.json`-- (No `gemini_oauth.py`. No new WS handlers — generic `cli_login`/`cli_auth_status` already cover it.)--## AICliSession sketch+## Files (current state)-```python-# server/services/cli_agent/session.py (abridged)-class AICliSession(BaseProcessSupervisor):- pipe_streams = True- terminate_grace_seconds = 5.0- graceful_shutdown = (sys.platform == "win32")-- def __init__(self, *, provider, task, repo_root, workspace_dir,- node_id, workflow_id, broadcaster, defaults,- mcp_port, batch_token):- super().__init__()- self._provider = provider- self._task = task- self._task_id = task.task_id or f"t_{uuid.uuid4().hex[:8]}"- self._worktree_dir = workspace_dir / node_id / f"wt_{self._task_id}"- self._branch = task.branch or f"machina/{self._task_id}"- self._broadcaster = broadcaster- self._defaults = defaults- self._mcp_port = mcp_port- self._batch_token = batch_token- self._lockfile_path: Optional[Path] = None- self._events, self._stderr = [], []- self._exit_code: Optional[int] = None- self._repo_root, self._node_id, self._workflow_id = repo_root, node_id, workflow_id-- @property- def label(self): return f"AICliSession_{self._provider.name}_{self._task_id}"-- def binary_path(self): return self._provider.binary_path()- def argv(self): return self._provider.headless_argv(self._task, defaults=self._defaults)- def cwd(self): return self._worktree_dir-- def env(self):- # Inherit parent env so the CLI finds its own auth in ~/.claude/, ~/.codex/, ~/.gemini/- # We do NOT inject CLAUDE_CONFIG_DIR / GEMINI_CLI_HOME — the CLI uses its native location.- e = {**os.environ, "PYTHONUNBUFFERED": "1"}- if self._lockfile_path and self._provider.ide_lock_env_var:- e[self._provider.ide_lock_env_var] = str(self._lockfile_path)- # Composio pattern: parent-run-ID propagation for MCP correlation- e["MACHINA_PARENT_RUN_ID"] = (- f"{self._workflow_id}:{self._node_id}:{self._batch_token[:8]}"- )- return e-- async def _pre_spawn(self):- # 1. git worktree- self._worktree_dir.parent.mkdir(parents=True, exist_ok=True)- result = await anyio.run_process(- ["git", "-C", str(self._repo_root), "worktree", "add",- str(self._worktree_dir), "-b", self._branch], check=False)- if result.returncode != 0:- raise RuntimeError(f"git worktree add failed: {result.stderr.decode()}")-- # 2. VSCode-style IDE lock file (CLI auto-discovers MachinaOs MCP)- if self._provider.supports("ide_lockfile"):- from .lockfile import write_ide_lockfile- self._lockfile_path = write_ide_lockfile(- pid=os.getpid(), port=self._mcp_port,- token=self._batch_token,- workspace_dir=self._worktree_dir,- ide_name=self._provider.name,- )-- async def _do_start(self):- binary = self.binary_path()- if not binary.exists():- raise FileNotFoundError(f"{self.label} binary not found at {binary}")- await self._pre_spawn()- kwargs = {"cwd": str(self.cwd()), "env": self.env(),- "stdout": subprocess.PIPE, "stderr": subprocess.PIPE}- if sys.platform == "win32" and self.graceful_shutdown:- kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP- self._proc = await anyio.open_process(self.argv(), **kwargs)- self._drain_tasks = [- asyncio.create_task(self._consume_stdout(self._proc.stdout)),- asyncio.create_task(self._consume_stderr(self._proc.stderr)),- ]-- async def _consume_stdout(self, stream):- async for raw in stream:- text = raw.decode("utf-8", errors="replace").strip()- if not text: continue- event = self._provider.parse_event(text)- if event is None: continue- self._events.append(event)- await self._on_event(event)-- async def _on_event(self, event):- if self._provider.is_final_event(event):- await self._broadcaster.update_node_status(self._node_id, "executing", {- "phase":"ai_cli_subtask", "task_id":self._task_id,- "provider":self._provider.name, "status":"succeeded",- **{k: event.get(k) for k in- ("total_cost_usd","duration_ms","num_turns","session_id")- if event.get(k) is not None},- })- else:- msg = event.get("message") or event.get("text") or json.dumps(event)- await self._broadcaster.broadcast_terminal_log(- {"source":f"{self._provider.name}:{self._task_id}",- "level":"info", "message":msg[:500]})-- async def _consume_stderr(self, stream):- async for raw in stream:- text = raw.decode("utf-8", errors="replace").rstrip()- if not text: continue- self._stderr.append(text)- await self._broadcaster.broadcast_terminal_log(- {"source":f"{self._provider.name}:{self._task_id}",- "level":"error", "message":text})-- async def wait_for_completion(self, timeout: int) -> dict:- try:- await asyncio.wait_for(self._proc.wait(), timeout=timeout)- self._exit_code = self._proc.returncode- except asyncio.TimeoutError:- await self.stop()- return self._build_result(success=False, error=f"timeout after {timeout}s")- return self._build_result(success=(self._exit_code == 0))-- async def cleanup(self):- await self.stop()- if self._lockfile_path:- from .lockfile import remove_ide_lockfile- remove_ide_lockfile(self._lockfile_path)- await anyio.run_process(- ["git", "-C", str(self._repo_root), "worktree", "remove", "--force",- str(self._worktree_dir)], check=False)-- def _build_result(self, *, success, error=None):- base = self._provider.event_to_session_result(- self._events, "\n".join(self._stderr), self._exit_code or -1)- base.update({"task_id":self._task_id, "branch":self._branch,- "worktree_path":str(self._worktree_dir),- "success": success and base.get("success", True),- "error": error or base.get("error")})- return base-```+| File | Purpose |+|---|---|+| `server/services/cli_agent/__init__.py` | Public re-exports + self-registers WS handlers via `services.ws_handler_registry` (telegram-style plugin-folder pattern). |+| `server/services/cli_agent/protocol.py` | `AICliProvider` Protocol + `CanonicalUsage` / `SessionResult` / `BatchResult` dataclasses. |+| `server/services/cli_agent/types.py` | Pydantic discriminated-union task specs + `BatchResultModel` for serialisation. |+| `server/services/cli_agent/config.py` | Loads `server/config/ai_cli_providers.json` (binary, package, defaults, supports flags per provider). |+| `server/services/cli_agent/factory.py` | `create_cli_provider(name)` lazy-import factory. |+| `server/services/cli_agent/lockfile.py` | VSCode-style IDE lockfile read/write/sweep. |+| `server/services/cli_agent/mcp_server.py` | FastMCP sub-app at `/mcp/ide` with bearer-token middleware + 5 tools. |+| `server/services/cli_agent/session.py` | `AICliSession(BaseProcessSupervisor)` per task — heart of framework. |+| `server/services/cli_agent/service.py` | `AICliService.run_batch()` — `asyncio.gather` under `Semaphore(5)` (no separate pool class), cancel hooks. |+| `server/services/cli_agent/_handlers.py` | Per-provider login/logout WS handlers (`claude_code_*`, `codex_cli_*`). |+| `server/services/cli_agent/providers/anthropic_claude.py` | Reference Claude provider — full feature surface. |+| `server/services/cli_agent/providers/openai_codex.py` | Codex provider — sandbox-first. |+| `server/services/cli_agent/providers/google_gemini.py` | v2 stub. |+| `server/config/ai_cli_providers.json` | Per-provider config (binary names, npm packages, login/auth_status argvs, lockfile dirs, supports flags). |+| `server/nodes/agent/claude_code_agent.py` | Refactored — `Params.tasks: list[ClaudeTaskSpec]` + legacy single-prompt fallback. |+| `server/nodes/agent/codex_agent.py` | New plugin — `Params.tasks: list[CodexTaskSpec]` + sandbox-focused defaults. |+| `server/nodes/visuals.json` | `claude_code_agent` + `codex_agent` icon/color entries. |+| `server/config/credential_providers.json` | `_cli_base` abstract + `claude_code` + `codex_cli` entries. |+| `server/services/claude_code_service.py` | Slimmed to a back-compat shim that builds one `ClaudeTaskSpec` and calls `AICliService.run_batch("claude", ...)`. Kept for legacy callers; eventually deletable. |+| `server/services/claude_oauth.py` | Unchanged. The new framework's Claude login handler reuses this directly. |+| `server/services/workflow.py` | `cancel_deployment` also calls `get_ai_cli_service().cancel_workflow(workflow_id)`. |+| `server/main.py` | Mounts `/mcp/ide` sub-app, composes its lifespan, runs stale-lockfile sweep on startup. Side-effect imports `services.cli_agent` so its WS handlers self-register. |+| `server/routers/websocket.py` | No CLI handlers inline — discovered via `services.ws_handler_registry.get_ws_handlers()`. |## Output contract```json{"tasks": [{- "task_id": "t_<8hex>", "session_id": "<UUID|null>",+ "task_id": "t_<8hex>",+ "session_id": "<UUID|null>","provider": "claude|codex|gemini",- "prompt": "...", "branch": "machina/t_<8hex>",+ "prompt": "...",+ "branch": "machina/t_<8hex>","worktree_path": "<abs path, removed after batch>","response": "<truncated to 4000 chars>","cost_usd": 0.42,@@ -589,7 +251,7 @@ class AICliSession(BaseProcessSupervisor):"reasoning_tokens": 0, "request_count": 7},"provider_data": {- "reasoning_details": "...", // Anthropic only+ "reasoning_details": "...", // Claude only"call_id": "...", // Codex only"extra_content": [...] // Gemini only (v2)},@@ -598,155 +260,67 @@ class AICliSession(BaseProcessSupervisor):"summary": {"n_tasks": 3, "n_succeeded": 2, "n_failed": 1,"total_cost_usd": 1.23,- "wall_clock_ms": 19002,- "budget_remaining_usd": 18.77+ "wall_clock_ms": 19002},"provider": "claude|codex|gemini",- "timestamp": "2026-05-02T12:00:00Z"+ "timestamp": "2026-05-04T12:00:00Z"}```-`canonical_usage` normalizes vendor token-counting (Hermes pattern). `provider_data` carries vendor-only metadata that doesn't fit the shared schema.-`cost_usd`/`num_turns` = `null` for codex/gemini. `summary.total_cost_usd`/`budget_remaining_usd` = `null` if any task is non-Claude.++`cost_usd` is the provider's reported value when available (Claude). For Codex (no native USD), `service.py:_derive_cost` falls back to `services.pricing.PricingService.calculate_cost()` from `canonical_usage` — single source of truth for LLM cost across MachinaOs. `summary.total_cost_usd` is `null` if any task didn't surface cost.## Status broadcast events| Phase | When | Payload ||---|---|---|-| `batch_started` | run_batch entry | `{provider, n_tasks, max_parallel, isolation:"worktree"}` |-| `ai_cli_subtask` | per-task partial | `{task_id, provider, status:"running", message, cost_usd?, num_turns?}` |+| `batch_started` | `run_batch` entry | `{provider, n_tasks, max_parallel, isolation:"worktree"}` |+| `ai_cli_subtask` | per-task partial (NDJSON event) | `{task_id, provider, status:"running", message, cost_usd?, num_turns?}` || `ai_cli_subtask` | per-task final | `{task_id, provider, status:"succeeded"|"failed", cost_usd?, duration_ms, num_turns?, error?}` || `batch_complete` | aggregator finish | `{provider, n_succeeded, n_failed, total_cost_usd?, wall_clock_ms}` |-Plus `broadcast_terminal_log(source=f"{provider}:{task_id}", level)` on every NDJSON line.--## Error handling--- **Per-task failure** → `_run_one` catches → `SessionResult(success=False, error=...)`. Batch continues.-- **Per-task timeout** → `asyncio.TimeoutError` → `session.stop()` (terminate_then_kill 5s) → `error="timeout after Ns"`.-- **Auth missing** → `provider.detect_auth_error()` on first session's stderr/exit_code. First detection short-circuits remaining tasks: `error="not_authenticated"` with hint `"Open Credentials Modal and click 'Login with <Provider>'"`. The CLI handles re-auth itself via its own `<provider> login` flow; we don't.-- **CLI not installed** → `binary_path()` `FileNotFoundError` from [process.py:74-75](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/process.py#L74-L75) → pool catches → `error="cli_not_installed"` with hint pointing at credentials modal.-- **Not a git repo** → early `git rev-parse --git-dir` check in plugin's `execute_op` → `BatchResult(error="working_directory_not_git_repo")` before pool construction.-- **Worktree creation fails** → `_pre_spawn` raises → that task only fails; siblings continue.-- **Budget exhaustion (Claude)** → track `running_total_cost`; refuse to acquire semaphore for pending tasks once exceeded; in-flight tasks have CLI's own `--max-budget-usd` cap.-- **Cancellation** → `WorkflowService.stop_execution` → `service.cancel_workflow(wf)` → `pool.cancel()` → per-session `cleanup()` → `BaseSupervisor.stop()` → `terminate_then_kill` → `git worktree remove --force` + lockfile delete.-- **MCP 401** → CLI calls our MCP with bad/expired token → 401 → CLI sees tool error → continues with built-ins.-- **Lockfile leak on hard crash** → startup sweep deletes `~/.claude-machina/ide/*.lock` whose PID is no longer alive (mirrors VSCode behavior).--## Reused (DO NOT duplicate)--- [_supervisor/base.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/base.py) — `BaseSupervisor` lock + lifecycle-- [_supervisor/process.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/process.py) — `BaseProcessSupervisor` (override `_do_start`)-- [_supervisor/util.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/util.py) — `kill_tree`, `terminate_then_kill`-- [whatsapp/_runtime.py:26-116](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/nodes/whatsapp/_runtime.py#L26-L116) — reference subclass shape-- ~~[claude_oauth.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/claude_oauth.py)~~ — **NOT used** by the new framework. Legacy module for the legacy `claude_code_service.py` shim only. New framework uses native CLI auth (no wrapping).-- [llm/protocol.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/protocol.py), [factory.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/factory.py), [config.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/llm/config.py) — Protocol+factory+config blueprint-- [credential_registry.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/credential_registry.py) — `extends` deep-merge-- [handlers/tools.py:678](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/handlers/tools.py#L678) — 4000-char truncation-- [status_broadcaster.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/status_broadcaster.py) — `update_node_status`, `broadcast_terminal_log`-- [workflow.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/workflow.py) — `_get_workspace_dir`-- [agent/_inline.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/nodes/agent/_inline.py) — `collect_agent_connections()` for skill prompt-- [ai.py:2898](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/ai.py#L2898) — plugin Params doubles as LLM tool schema-- [skill_loader.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/skill_loader.py) — `SkillLoader.scan_skills()` (metadata, ~100 tokens/skill) reused by `mcp__machina__listSkills`; `SkillLoader.load_skill(name)` (full content with scripts/references) reused by `mcp__machina__getSkill`. Reference SKILL.md: [`server/skills/social_agent/twitter-search-skill/SKILL.md`](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/skills/social_agent/twitter-search-skill/SKILL.md)-- [auth.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/auth.py) — `AuthService.get_api_key()` reused by `mcp__machina__getCredential` (allowlisted)-- [handlers/filesystem.py](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/handlers/filesystem.py) — `LocalShellBackend` reused by `mcp__machina__getWorkspaceFiles`-- VSCode lock file format reference: `~/.claude/ide/<pid>.lock` = `{port, authToken, workspaceFolders, ideName, transport}` — mirrored exactly+Plus `broadcast_terminal_log(source=f"{provider}:{task_id}", level)` on every NDJSON line — surfaced in the Terminal tab.-## Verification+## Plugin contract — adding a new CLI provider-In order:--1. **Worktree**: `git worktree list` shows `cli-agent-framework` on `feat/cli-agent-framework`.-2. **Unit tests (v1)**:- - `uv run pytest tests/services/test_cli_agent_providers.py -v`- - `uv run pytest tests/services/test_cli_agent_session.py -v`- - `uv run pytest tests/services/test_cli_agent_mcp.py -v`- - `uv run pytest tests/nodes/test_claude_code_agent.py tests/nodes/test_codex_agent.py -v`- - Add: `test_factory_gemini_raises_not_implemented` — calling `create_cli_provider("gemini")` raises `NotImplementedError`.-3. **Plugin contract**: `uv run pytest tests/test_plugin_contract.py tests/test_node_spec.py -k "claude or codex"` — clean per-provider schemas, no `$defs`.-4. **Live single-task back-compat (Claude)**: workflow with one `claude_code_agent`, legacy `prompt="say hello"`. Confirm `summary.n_tasks==1`, `summary.total_cost_usd != null`.-5. **Live 3-task parallel (Claude)**: `tasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}]`. Three distinct `claude:<task_id>` Terminal streams interleaved. Three distinct session_ids. Three worktrees created and removed. `summary.wall_clock_ms < sum(duration_ms)`.-6. **Live 3-task parallel (Codex)**: `codex_agent` node. Confirm `summary.total_cost_usd == null`, no `--max-budget-usd` / `--max-turns` / `--session-id` in argv. Verify `--sandbox workspace-write` and `--ask-for-approval never` defaults applied.-7. **Live cancel** (Claude or Codex): start long batch, click Stop. Confirm child processes die within 5s; worktrees removed; lockfiles removed.-8. **Live tool-mode (Claude)**: aiAgent → input-tools → claude_code_agent. Prompt: "use the claude_code tool to refactor utils.py and tests/test_utils.py in parallel." Confirm structured envelope; response truncated at 4000.-9. **Live resumption (Claude)**: capture `tasks[0].session_id`, run again with `tasks=[{resume_session_id:<captured>, prompt:"add error handling"}]`. Confirm context preservation.-10. **Live MCP discovery (Claude)**: with a Claude task running, `cat ~/.claude-machina/ide/<pid>.lock` and confirm format `{port, url, authToken, workspaceFolders, ideName:"machinaos", transport}`. Stream-json shows an `mcp__machina__*` tool invocation. MCP server logs the call with the per-batch token.-10a. **Skill exposure**: connect `twitter-search-skill` to a `claude_code_agent` node, run a task. Confirm CLI invokes `mcp__machina__listSkills` (returns 1 skill with `name="twitter-search-skill"`, `description`, `allowed_tools=["twitter_search"]`). Then CLI invokes `mcp__machina__getSkill("twitter-search-skill")` and receives full instructions markdown + any scripts/references. Connect a second skill (e.g., `python-skill`) and confirm only the connected skills appear in `listSkills` (scoping via `BatchContext.connected_skill_names`).-10b. **Credential allowlist**: configure batch with `allowed_credentials=["openai"]`. CLI calls `mcp__machina__getCredential("openai")` → returns key. CLI calls `mcp__machina__getCredential("anthropic")` → 403.-11. **Live MCP auth rejection**: `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:3010/mcp/ide/...` → 401.-12. **Live MCP cleanup**: lockfiles removed from `~/.claude-machina/ide/` after batch (success and cancel paths).-13. **Stale lockfile sweep**: kill server mid-batch, restart. Confirm leftover lockfile (PID dead) is deleted on startup.-14. **Codex sandbox enforcement**: Codex task with `sandbox:"read-only"` attempting to write a file → CLI rejects → captured in stderr, surfaces as `success=false` with sandbox error.-15. **Heartbeat stale-detection**: mock a session that emits no events for >60s; confirm `~/.claude-machina/logs/session-stale-<task_id>.log` is written with last-events + stderr tail.-16. **Timeout diagnostic dump**: set `timeout_seconds=5` on a long task; on timeout, confirm `session-timeout-<task_id>.log` contains argv, env keys (no secret values), last 20 events, stderr tail.-17. **Binary resolution chain**: temporarily move/rename the system `claude` binary; run a Claude task; confirm fallback to `npx --yes @anthropic-ai/claude-code` succeeds. Restore.-18. **Parent run-ID env**: with a Claude task running, MCP server logs show `MACHINA_PARENT_RUN_ID=<workflow>:<node>:<token8>` correlating each tool call to the batch.-19. **Native auth — login flow**: log out (`rm ~/.claude/.credentials.json` or equivalent). Open Credentials Modal → click "Login with Claude" → confirm `claude login` opens browser/device flow → complete it → confirm Credentials Modal status flips to "Connected" via `cli_auth_status` polling.-20. **Native auth — status check**: with `claude` logged in, `cli_auth_status` returns `{logged_in: true}`. Manually corrupt `~/.claude/.credentials.json` → `cli_auth_status` returns `{logged_in: false, hint: "Run claude login"}`.-21. **Native auth — error short-circuit**: log out, then run a 3-task batch. First task fails fast with `error="not_authenticated"`; remaining 2 tasks short-circuit with the same error (no spawn). Hint message is surfaced in the BatchResult.-22. **Auth env not injected**: `printenv | grep -i 'CLAUDE_CONFIG_DIR\|GEMINI_CLI_HOME'` inside a running task's env (via `mcp__machina__broadcastLog` reflection or `/proc/<pid>/environ` peek) confirms we're **not** setting these vars; CLI uses its native location.-23. **Smoke**: `uv run pytest -x -q` over the full server suite — no regressions from `claude_code_service.py` slimming.--## External orchestrator patterns (Hermes + Composio source review)--Researched against fresh clones at `D:/tmp/hermes-agent` (NousResearch) and `D:/tmp/composio` (ComposioHQ). Findings shaped the v1 design.--### What we copy--| Pattern | Source | Apply to |-|---|---|---|-| **`ProviderTransport` ABC + `provider_data` Dict** for vendor-specific metadata (Anthropic `reasoning_details`, Codex `call_id`/`response_item_id`, Gemini `extra_content`) without polluting the shared schema | Hermes [`agent/transports/base.py`](D:/tmp/hermes-agent/agent/transports/base.py), [`types.py`](D:/tmp/hermes-agent/agent/transports/types.py) | `AICliProvider.event_to_session_result()` returns `{...shared, provider_data: {<vendor-specific>}}`. Our Protocol stays thin; weird per-CLI metadata lives under `provider_data`. |-| **`CanonicalUsage` normalization** across vendor token-counting shapes (Anthropic vs Codex vs OpenAI handle cache tokens differently) | Hermes [`agent/usage_pricing.py`](D:/tmp/hermes-agent/agent/usage_pricing.py) | When `event_to_session_result` builds the result, normalize usage into `{input, output, cache_read, cache_write, reasoning, request_count}` — feed to existing [`services/pricing.py`](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/pricing.py) for cost. |-| **Heartbeat stale-detection** — track `(iteration, current_tool)` tuple; if unchanged for N cycles, log warning + dump diagnostic | Hermes [`tools/delegate_tool.py:1290-1357`](D:/tmp/hermes-agent/tools/delegate_tool.py) | Add to `AICliSession`: track `(events_seen, last_tool_use)` tuple per second; if frozen >60s, dump stderr buffer + last 5 events to `~/.claude-machina/logs/session-stale-<task_id>.log`. |-| **Timeout diagnostic dump** — on hard timeout, write stack/config/last-events to log file (issue ref: hermes #14726) | Hermes [`tools/delegate_tool.py:1437-1442`](D:/tmp/hermes-agent/tools/delegate_tool.py) | `wait_for_completion` `TimeoutError` branch writes `{argv, env_keys, last_20_events, stderr_tail}` to `~/.claude-machina/logs/session-timeout-<task_id>.log` before `stop()`. |-| **Binary resolution chain**: shipped assets → bundled npm pkg → PATH → npx fallback | Composio [`ts/packages/cli/src/services/run-subagent-acp.ts:66-124`](D:/tmp/composio/ts/packages/cli/src/services/run-subagent-acp.ts) | `provider.binary_path()` tries: (1) `<isolated_auth_dir>/npm/node_modules/.bin/<binary>`, (2) `shutil.which(<binary>)`, (3) `npx --yes <package_name>` shim. Mirrors what `claude_oauth.py` already partially does for Claude. |-| **Parent run-ID propagation via env var** for request tracing (lets MCP tool calls correlate to the parent batch) | Composio [`run.cmd.ts:494`](D:/tmp/composio/ts/packages/cli/src/commands/run.cmd.ts) (`COMPOSIO_CLI_PARENT_RUN_ID`) | Inject `MACHINA_PARENT_RUN_ID=<workflow_id>:<node_id>:<batch_token_short>` into every spawned CLI's env. MCP server logs this with each tool call. |-| **JSON-RPC framing pattern** for subprocess RPC (when MCP doesn't fit) | Hermes [`agent/copilot_acp_client.py:418-478`](D:/tmp/hermes-agent/agent/copilot_acp_client.py) | Reference for v2 if we ever wrap a CLI that doesn't speak stream-json. v1 uses stream-json directly (per-CLI native format). |+To add a fourth provider (e.g. Mistral CLI) post-v1:-### What we deliberately don't copy+1. New file `server/services/cli_agent/providers/<vendor>.py` implementing `AICliProvider`.+2. New entry in `server/config/ai_cli_providers.json`.+3. New `<vendor>TaskSpec` in `types.py` + register in the discriminated union.+4. New branch in `factory.create_cli_provider`.+5. New entry in `server/config/credential_providers.json` (`extends: "_cli_base"`).+6. New per-provider WS handlers in `_handlers.py` (login + logout) + entry in `WS_HANDLERS`.+7. New plugin file `server/nodes/agent/<vendor>_agent.py` (mirror `codex_agent.py`).+8. New entry in `server/nodes/visuals.json`.-| Pattern | Source | Why we skip |-|---|---|---|-| **ACP adapter binaries** (`claude-code-acp`, `codex-acp`) — Composio spawns dedicated wrapper binaries that translate the CLI's native protocol into Zed's Agent Client Protocol | Composio [`run-subagent-acp.ts:533`](D:/tmp/composio/ts/packages/cli/src/services/run-subagent-acp.ts) | Adds a translation layer + extra dependency for each CLI. Stream-json is the official Anthropic format and Gemini's documented JSON output — direct invocation is cleaner. ACP is right for editors that need to speak one protocol to N agents; we're the opposite (one app, many CLIs). |-| **Naive `subprocess.Popen` lifecycle** without locks/kill-tree | Hermes [`copilot_acp_client.py:348-354`](D:/tmp/hermes-agent/agent/copilot_acp_client.py) — `terminate; sleep 2; kill` (parent only) | We already have `BaseProcessSupervisor` with locked idempotent start/stop, recursive `kill_tree`, Windows `CTRL_BREAK_EVENT`. Strictly better. |-| **MCP-over-stdio for structured output collection** — Composio runs an MCP server *inside* the child (not the parent) so children write structured output via tool call | Composio [`run-subagent-output-mcp.ts`](D:/tmp/composio/ts/packages/cli/src/services/run-subagent-output-mcp.ts) | Inverts the call direction. Useful for tools that don't have native structured output, but Claude/Codex/Gemini already emit stream-json. Skip. |-| **Task-scoped filesystem tracking** (no real isolation, just bookkeeping) | Hermes [`tools/delegate_tool.py:1403`](D:/tmp/hermes-agent/tools/delegate_tool.py) | Our git-worktree-per-task is process-level isolation enforced by the kernel (different cwd, different file system view). Strictly stronger. |-| **Tool-tag-based capability filtering** (`destructiveHint`, `readOnlyHint`) for risk gating | Composio [`ts/packages/core/src/types/mcp.types.ts`](D:/tmp/composio/ts/packages/core/src/types/mcp.types.ts) | Codex's native `--sandbox read-only|workspace-write|danger-full-access` already does this at the kernel level; tag-based hints are a soft signal that doesn't enforce. We use Codex's sandbox flag directly. |-| **No retry loop** — failed children return error, not retried | Hermes (same pattern) | Aligns with our continue-on-error settle policy. Match. |-| **`max_concurrent_children=3`** | Hermes [`hermes_cli/config.py:934`](D:/tmp/hermes-agent/hermes_cli/config.py) | We use 5; their 3 is also fine. Difference is cosmetic. |+No edits to `routers/websocket.py`, `main.py`, or any existing handler/service. The plugin auto-registers via `BaseNode.__init_subclass__` (Wave 11) + the `services.ws_handler_registry` self-registration in `cli_agent/__init__.py`.-### Explicit non-finding+## Verification-Neither Hermes nor Composio writes a VSCode-style IDE lockfile (`~/.claude/ide/<pid>.lock` shape). Our v1 lockfile-discovery design is original among open-source orchestrators we surveyed and matches what the **VSCode Claude Code extension itself** does — i.e., we're cloning the upstream IDE pattern, not Hermes/Composio's pattern.+Unit tests (in `server/tests/services/cli_agent/`):-## v2 follow-up — Gemini activation+- `test_providers.py` — Claude + Codex argv shapes, parse_event fidelity (vendored NDJSON), event_to_session_result reconstruction, auth-error detection, `supports()` flags. Factory raises `NotImplementedError` for `gemini`.+- `test_mcp_server.py` — bearer-token registry register/lookup/unregister, 401 on missing/malformed/unknown/expired tokens, lockfile shape matches VSCode convention, stale-PID sweep.+- `test_service.py` — `not_git_repo` abort path, resolver contract (explicit `repo_root` doesn't fall back to cwd), cancel-when-idle, singleton.-After v1 ships and stabilizes, Gemini activation is a small, mechanical PR:+Plugin contract: `tests/test_plugin_contract.py` + `tests/test_node_spec.py` — clean per-provider Params schemas, no `$defs`/`$ref` in the fast-path.-1. Replace `providers/google_gemini.py` stub with full implementation (argv builder for `--prompt`/`--session-id`/`--resume`/`--yolo`/`--sandbox`; `parse_event` keyed on the `JsonStreamEventType` enum from `nonInteractiveCli.ts`; `is_final_event` = `type=="result"`; `event_to_session_result` extracts `session_id` + `stats.duration_ms`, sets `cost_usd=None`; `login_argv = ["gemini", "auth", "login"]`; `detect_auth_error` matches exit code 1 / `FatalAuthenticationError`).-2. Drop the `NotImplementedError` branch in `factory.py`.-3. Create `server/nodes/agent/gemini_cli_agent.py` with `Params.tasks: list[GeminiTaskSpec]`.-4. Add `geminiCliAgent` to `server/nodes/visuals.json`.-5. Add `gemini_cli` entry to `server/config/credential_providers.json` (extending `_cli_base`).-6. (No new WS handlers — generic `cli_login`/`cli_auth_status` already dispatch by provider field.)-7. Create `server/tests/nodes/test_gemini_cli_agent.py` (mirrors `test_codex_agent.py` shape; adds session/resume tests).-8. Vendored NDJSON fixture from the JS source for parser tests.+Live verification (needs a real Claude install + auth):-No changes to `protocol.py`, `types.py`, `session.py`, `pool.py`, `service.py`, `mcp_server.py`, `lockfile.py`, `login.py`, or `auth_status.py` — the v1 abstraction absorbs Gemini cleanly. **No `gemini_oauth.py` ever** — Gemini CLI handles its own auth via `~/.gemini/`.+1. Empty `<repo>/data/claude-machina/`. Open Credentials Modal → click "Login with Claude Code CLI". Confirm the npm install runs (visible in backend logs), `<repo>/data/claude-machina/npm/node_modules/.bin/claude[.cmd]` appears, browser opens for Anthropic OAuth. Modal flips Connected within ~2s of CLI exit (background `claude auth status` poll detects success).+2. Refresh the page. Modal stays Connected (`auth_service.get_oauth_tokens("claude_code")` still returns the marker; idempotent re-click also stays Connected).+3. Click Disconnect. Modal flips Disconnected (`claude auth logout` clears CLI creds + marker dropped).+4. Add a `claude_code_agent` node, set `tasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}]`, run. Three distinct `claude:<task_id>` Terminal streams interleaved. Three distinct session_ids. Three worktrees created and removed. `summary.wall_clock_ms < sum(duration_ms)` (proves parallelism).+5. With a Claude task running, `cat ~/.claude/ide/<pid>.lock` and confirm format. Stream-json shows an `mcp__machina__*` tool invocation.+6. `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:3010/mcp/ide/...` → 401.## Risks / open considerations-- **`drain_stream` not used** — we override `_do_start`; drain task list replaced wholesale; `stop()` still cancels them via `self._drain_tasks` ([process.py:119-120](D:/startup/projects/machinaos-worktrees/credentials-scaling-v2/server/services/_supervisor/process.py#L119-L120)).-- **`--include-partial-messages`** assumes recent Claude CLI; detect via `claude --help | grep partial` once at module init, downgrade to plain `stream-json` if absent.-- **Codex auth** — Codex reads `~/.codex/auth.json` after `codex login`. We **don't** set `OPENAI_API_KEY` ourselves; the CLI handles its own auth. If the user prefers env-based auth (e.g., `CODEX_API_KEY_ENV_VAR`), they can set it in their shell — we inherit env via `os.environ`.-- **Gemini cost** — token stats only, no USD. v1 reports `cost_usd=null`; follow-up could compute via `services/pricing.py`.-- **Concurrent OAuth refresh** at sem=5 — the CLIs handle their own refresh internally. If a race causes a transient auth error, our session retries once on `detect_auth_error()` before failing. Acceptable for v1.-- **Native CLI auth = single user per host** — anyone with shell access on the host has access to the host's CLI auth, same as VSCode/`code .`. v1 doesn't isolate per-MachinaOs-user. If multi-tenant deployment becomes a need, v2 can introduce optional per-user `HOME` redirects (the old `~/.claude-machina/` pattern) gated by a config flag.-- **Discriminator + LLM tool schema** — Pydantic generates `oneOf`+`discriminator` JSON Schema, handled by most LLMs. Per-plugin `Params.tasks` is hard-typed to one variant so the fast-path schema stays clean.-- **Worktree leak on hard crash** — covered by startup sweep (mirrors VSCode lock-file behavior).-- **Three OAuth modules duplicate ~60% of `claude_oauth.py`** — defer factoring; wait for the third concrete to validate the abstraction.-- **Codex/Gemini final-event detection** is best-effort by event-type name; tests pin to vendored NDJSON streams to catch CLI schema drift.-- **MCP SDK is pre-1.0-stable** — pin a known-good version in `pyproject.toml`. Isolate the surface in `mcp_server.py` so an SDK breaking change touches one file.-- **Codex MCP discovery incomplete** — Codex CLI doesn't yet auto-read VSCode-style lockfiles. v1 still writes them (cheap); when Codex lands support, no code change needed.-- **Heavy bias toward Claude** — Claude provider is the reference implementation for the Protocol; if a Protocol method ever needs a feature only Claude has, prefer adding it to the Protocol with sensible defaults for other providers rather than designing for the lowest common denominator.-- **Gemini deferred but designed-for** — `GeminiTaskSpec` ships in `types.py` and the discriminator union in v1 so the JSON Schema fast-path doesn't need re-deriving when v2 lands. The factory raises `NotImplementedError` for gemini; tests assert this contract.-- **MCP multi-tenancy** — multiple parallel batches must not see each other's tokens or workspace. Per-batch token registry keyed by bearer token; missing/expired → 401. Tested.+- **Codex login not yet wired.** v1 returns a graceful error directing the user to `npm install -g @openai/codex` + `codex login`. Follow-up: `services/codex_oauth.py` mirroring `claude_oauth.py` with `HOME=~/.codex-machina` env redirect (Codex has no `CONFIG_DIR` env; `HOME` redirect is risky on Windows, so Windows may need a different strategy or accept user-global Codex auth).+- **Gemini deferred.** `factory.create_cli_provider("gemini")` raises `NotImplementedError`. v2 work: implement `providers/google_gemini.py`, drop the factory branch, add `nodes/agent/gemini_cli_agent.py`. ~430 LoC. No abstraction changes needed.+- **`--include-partial-messages`** assumes a recent Claude CLI; older versions fall back gracefully via the parser's `parse_event` returning `None` for unknown shapes.+- **Browser-prompt phrasing** can change between Claude CLI versions; `b"yes\nyes\n"` might land on the wrong question. Defensible because that's exactly what `claude_oauth.py` has been doing in production.+- **Marker token written without verifying CLI is actually functional** — we trust `claude auth status`'s exit code. If Anthropic invalidates the token server-side and the CLI hasn't re-checked, the modal still shows Connected until the next session attempt's `detect_auth_error` catches it.+- **MCP SDK is pre-1.0-stable.** Pinned at `mcp>=1.0.0`. The surface is isolated in `mcp_server.py` so an SDK breaking change touches one file.+- **Concurrent install safety.** `claude_oauth.py:_get_claude_cmd` doesn't currently use a lock — two simultaneous login clicks within 2s could race the npm install. Low-risk in practice (modal debounces clicks); a follow-up could add an `asyncio.Lock`.+- **Worktree leak on hard crash.** Out-of-scope cleanup pass; document.diff --git a/server/config/credential_providers.json b/server/config/credential_providers.jsonindex c4e3e76c..6ffac207 100644--- a/server/config/credential_providers.json+++ b/server/config/credential_providers.json@@ -162,11 +162,8 @@"category": "ai","category_label": "AI Providers","kind": "oauth",- "_kind_doc": "Stripe-style CLI-managed auth: MachinaOs spawns `<provider> login`, the CLI manages its own credentials (~/.claude/, ~/.codex/, ~/.gemini/), and we write a synthetic marker OAuth token on success so the catalogue's `stored` flag flips. OAuthConnect.tsx renders empty fields because `fields=[]` (see OAuthConnect.tsx:42 — the documented Stripe-style fieldless-CLI case).",- "fields": [],- "ws": {- "login": "cli_login"- }+ "_kind_doc": "Stripe-style CLI-managed auth: MachinaOs spawns `<provider> login` from a per-provider WS handler; the CLI manages its own local-isolated credentials (~/.claude-machina/, future ~/.codex-machina/), and we write a synthetic marker OAuth token on success so the catalogue's `stored` flag flips. OAuthConnect.tsx renders empty fields because `fields=[]` (see OAuthConnect.tsx:42 — the documented Stripe-style fieldless-CLI case). Each child sets its own `ws.login`/`ws.logout` so the handler name encodes the provider (Twitter / Google / Stripe convention — frontend dispatches `{}` payload).",+ "fields": []},"claude_code": {@@ -175,7 +172,10 @@"color": "dracula.cyan","icon_ref": "lobehub:Claude","status_hook": "claude_code",- "ws_provider_arg": "claude"+ "ws": {+ "login": "claude_code_login",+ "logout": "claude_code_logout"+ }},"codex_cli": {@@ -184,7 +184,10 @@"color": "dracula.orange","icon_ref": "lobehub:OpenAI","status_hook": "codex_cli",- "ws_provider_arg": "codex"+ "ws": {+ "login": "codex_cli_login",+ "logout": "codex_cli_logout"+ }},"whatsapp_personal": {diff --git a/server/routers/websocket.py b/server/routers/websocket.pyindex 17f11d67..08e90d06 100644--- a/server/routers/websocket.py+++ b/server/routers/websocket.py@@ -1386,9 +1386,10 @@ async def handle_claude_oauth_login(data: Dict[str, Any], websocket: WebSocket)@ws_handler()async def handle_claude_oauth_status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- """Check Claude OAuth credentials status."""- from services.claude_oauth import get_claude_credentials- return get_claude_credentials()+ """Check Claude OAuth credentials status via ``claude auth status``."""+ from services.claude_oauth import claude_auth_status+ has_token = await claude_auth_status()+ return {"success": True, "has_token": has_token}# NOTE: `cli_login` / `cli_auth_status` handlers are owned bydiff --git a/server/services/claude_oauth.py b/server/services/claude_oauth.pyindex 7f3ba11b..2801ac18 100644--- a/server/services/claude_oauth.py+++ b/server/services/claude_oauth.py@@ -1,138 +1,154 @@-"""Claude OAuth Service - Isolated login that doesn't affect user's main session."""-+"""Claude OAuth — project-local install + plain ``claude login`` spawn.++The Claude Code CLI lives at ``<repo>/data/claude-machina/npm/`` (on-demand+``npm install`` on first use, mirroring the WhatsApp project-local layout)+and ``CLAUDE_CONFIG_DIR`` points at ``<repo>/data/claude-machina/`` so the+credentials file lands inside the project tree, isolated from the user's+own ``~/.claude/`` session.++Login uses the documented subcommand from+https://code.claude.com/docs/en/cli-reference: ``claude auth login`` opens+the browser, ``claude auth logout`` signs out, ``claude auth status``+exits 0 when logged in / 1 otherwise. We spawn ``auth login`` with+inherited stdio so the CLI opens the browser itself (same as the VSCode+Claude Code extension; Anthropic does not expose a programmatic OAuth+helper or a ``--print-url`` flag — see issue+anthropics/claude-code#7100). The background poller in+``services/cli_agent/_handlers.py`` invokes ``claude auth status`` to+flip the catalogue marker on success.+"""++from __future__ import annotations++import asyncioimport jsonimport osimport shutilimport subprocessimport sysfrom pathlib import Path-from typing import Dict, Any+from typing import Any, Dictfrom core.logging import get_loggerlogger = get_logger(__name__)-# Isolated directories for MachinaOs-MACHINA_CLAUDE_DIR = Path.home() / ".claude-machina"+# server/services/claude_oauth.py -> parents[2] is the repo root.+_PROJECT_ROOT = Path(__file__).resolve().parents[2]++MACHINA_CLAUDE_DIR = (_PROJECT_ROOT / "data" / "claude-machina").resolve()MACHINA_NPM_DIR = MACHINA_CLAUDE_DIR / "npm"+CLAUDE_CREDENTIALS_PATH = MACHINA_CLAUDE_DIR / ".credentials.json"def _get_claude_cmd() -> str:- """Get path to isolated claude CLI, installing if needed."""+ """Return path to the project-local claude CLI, installing on miss."""if sys.platform == "win32":- claude_path = MACHINA_NPM_DIR / "claude.cmd"+ bin_path = MACHINA_NPM_DIR / "node_modules" / ".bin" / "claude.cmd"else:- claude_path = MACHINA_NPM_DIR / "bin" / "claude"+ bin_path = MACHINA_NPM_DIR / "node_modules" / ".bin" / "claude"- if claude_path.exists():- return str(claude_path)+ if bin_path.exists():+ return str(bin_path)- # Install claude-code in isolated location- logger.info("Installing Claude Code CLI in isolated environment...")+ logger.info("Installing Claude Code CLI in project-local environment...")MACHINA_NPM_DIR.mkdir(parents=True, exist_ok=True)npm_cmd = shutil.which("npm")if not npm_cmd:- raise FileNotFoundError("npm not found")+ raise FileNotFoundError("npm not found on PATH")result = subprocess.run([npm_cmd, "install", "@anthropic-ai/claude-code", "--prefix", str(MACHINA_NPM_DIR)],capture_output=True,text=True,)-if result.returncode != 0:logger.error(f"npm install failed: {result.stderr}")raise RuntimeError(f"Failed to install claude-code: {result.stderr}")- # Find the installed binary- if sys.platform == "win32":- claude_path = MACHINA_NPM_DIR / "node_modules" / ".bin" / "claude.cmd"- else:- claude_path = MACHINA_NPM_DIR / "node_modules" / ".bin" / "claude"+ if not bin_path.exists():+ raise FileNotFoundError(f"Claude CLI not found at {bin_path} after install")- if not claude_path.exists():- raise FileNotFoundError(f"Claude CLI not found at {claude_path} after install")+ logger.info(f"Claude Code CLI installed at: {bin_path}")+ return str(bin_path)- logger.info(f"Claude Code CLI installed at: {claude_path}")- return str(claude_path)++def _claude_env() -> Dict[str, str]:+ env = os.environ.copy()+ env["CLAUDE_CONFIG_DIR"] = str(MACHINA_CLAUDE_DIR)+ return envasync def initiate_claude_oauth() -> Dict[str, Any]:- """Run claude login in isolated environment with auto-filled prompts."""+ """Spawn ``claude auth login`` and let the CLI open the browser."""try:- MACHINA_CLAUDE_DIR.mkdir(exist_ok=True)-- # Get or install claude CLI+ MACHINA_CLAUDE_DIR.mkdir(parents=True, exist_ok=True)claude_cmd = _get_claude_cmd()- env = os.environ.copy()- env["CLAUDE_CONFIG_DIR"] = str(MACHINA_CLAUDE_DIR)-- # Run claude login with stdin to auto-fill prompts- # Claude login asks: 1) "Do you agree?" (yes) 2) "Open browser?" (yes)- if sys.platform == "win32":- # Windows: pipe inputs and let it open browser- process = subprocess.Popen(- [claude_cmd, "login"],- env=env,- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- creationflags=subprocess.CREATE_NO_WINDOW,- )- # Send "yes" responses for the prompts- try:- process.stdin.write(b"yes\nyes\n")- process.stdin.flush()- except Exception:- pass- else:- # Unix: pipe inputs- process = subprocess.Popen(- [claude_cmd, "login"],- env=env,- stdin=subprocess.PIPE,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- )- try:- process.stdin.write(b"yes\nyes\n")- process.stdin.flush()- except Exception:- pass-- logger.info(f"Claude OAuth login started with PID {process.pid}")+ proc = await asyncio.create_subprocess_exec(+ claude_cmd,+ "auth",+ "login",+ env=_claude_env(),+ )+ logger.info(f"Claude OAuth login started with PID {proc.pid}")return {"success": True,- "message": "OAuth login started. Browser should open for authentication.",+ "pid": proc.pid,"config_dir": str(MACHINA_CLAUDE_DIR),- "pid": process.pid,+ "message": "Claude is opening your browser to authenticate.",}except FileNotFoundError as e:logger.error(f"CLI not found: {e}")return {"success": False, "error": str(e)}except Exception as e:- logger.error(f"Failed to start Claude OAuth: {e}")+ logger.exception(f"Failed to start Claude OAuth: {e}")return {"success": False, "error": str(e)}-def get_claude_credentials() -> Dict[str, Any]:- """Read credentials from isolated config."""+async def claude_auth_status() -> bool:+ """Return True iff ``claude auth status`` exits 0 (logged in)."""try:- creds_path = MACHINA_CLAUDE_DIR / ".credentials.json"- if not creds_path.exists():- return {"success": False, "has_token": False}+ claude_cmd = _get_claude_cmd()+ except (FileNotFoundError, RuntimeError):+ return False- with open(creds_path) as f:- creds = json.load(f)+ try:+ proc = await asyncio.create_subprocess_exec(+ claude_cmd,+ "auth",+ "status",+ env=_claude_env(),+ stdin=subprocess.DEVNULL,+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ )+ return await proc.wait() == 0+ except Exception as e:+ logger.warning(f"claude auth status check failed: {e}")+ return False- return {- "success": True,- "has_token": bool(creds.get("accessToken")),- "access_token": creds.get("accessToken"),- "expires_at": creds.get("expiresAt"),- }++async def claude_auth_logout() -> bool:+ """Run ``claude auth logout``. Returns True on exit 0."""+ try:+ claude_cmd = _get_claude_cmd()+ except (FileNotFoundError, RuntimeError):+ return False++ try:+ proc = await asyncio.create_subprocess_exec(+ claude_cmd,+ "auth",+ "logout",+ env=_claude_env(),+ stdin=subprocess.DEVNULL,+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ )+ return await proc.wait() == 0except Exception as e:- return {"success": False, "error": str(e)}+ logger.warning(f"claude auth logout failed: {e}")+ return Falsediff --git a/server/services/cli_agent/__init__.py b/server/services/cli_agent/__init__.pyindex f10d1430..3439f69e 100644--- a/server/services/cli_agent/__init__.py+++ b/server/services/cli_agent/__init__.py@@ -5,15 +5,15 @@ each isolated in its own git worktree, with a shared MCP server hostingMachinaOs tools (``mcp__machina__*``) discovered via VSCode-stylelockfile.-Self-registers two WebSocket handlers (``cli_login`` /-``cli_auth_status``) into ``services.ws_handler_registry`` on import,-mirroring the telegram / whatsapp plugin folder pattern. The router-does not need to know about us by name.+Self-registers per-provider WebSocket handlers+(``claude_code_login``, ``claude_code_logout``, ``codex_cli_login``,+``codex_cli_logout``) into ``services.ws_handler_registry`` on import,+mirroring the telegram / whatsapp / stripe plugin folder pattern. The+router does not need to know about us by name."""from __future__ import annotations-from services.cli_agent.cli_auth import run_native_loginfrom services.cli_agent.factory import (ALL_PROVIDERS,SUPPORTED_PROVIDERS,@@ -67,6 +67,4 @@ __all__ = ["BatchSummary","BatchResultModel","session_result_to_model",- # Native auth helpers (also used by the router for Credentials Modal)- "run_native_login",]diff --git a/server/services/cli_agent/_handlers.py b/server/services/cli_agent/_handlers.pyindex 01dc5393..c55c9da1 100644--- a/server/services/cli_agent/_handlers.py+++ b/server/services/cli_agent/_handlers.py@@ -1,35 +1,43 @@-"""WebSocket handlers for the CLI agent framework.+"""Per-provider WebSocket handlers for CLI-managed OAuth.Self-registered into ``services.ws_handler_registry`` from-``services/cli_agent/__init__.py``. The router does not import this-module directly — it discovers handlers via the registry at dispatch-time, mirroring the telegram / whatsapp / stripe plugin pattern.--Adopted from `nodes/stripe/_handlers.py` (CLI-managed OAuth pattern):-- - On successful ``<provider> login``, write a synthetic ``"cli-managed"``- marker OAuth token via ``auth_service.store_oauth_tokens()``. The- catalogue handler's ``stored`` check (keyed off- ``status_hook``) flips ``true`` automatically — the existing- ``OAuthConnect.tsx`` primitive renders the modal as Connected.- - Broadcast ``credential_catalogue_updated`` so the frontend- invalidates its catalogue cache and re-fetches reactively.- - No ``cli_auth_status`` handler — redundant once ``stored`` drives- the modal.--Logout: drop the marker token + broadcast.--The actual subprocess spawning lives in ``cli_auth.run_native_login``.+``services/cli_agent/__init__.py``.++Naming convention matches Twitter / Google / Stripe — each provider gets+its own message type (``claude_code_login`` / ``claude_code_logout`` /+``codex_cli_login`` / ``codex_cli_logout``). The frontend dispatches with+an empty payload (see ``OAuthConnect.tsx`` ->+``useCredentialPanel.oauthLogin`` -> ``sendRequest(config.ws!.login, {})``);+the handler name encodes which provider to spawn.++Claude flow uses the documented CLI subcommands from+https://code.claude.com/docs/en/cli-reference:++- ``claude auth login`` — opens the browser, writes credentials.+- ``claude auth status`` — exits 0 when logged in, 1 otherwise.+- ``claude auth logout`` — clears credentials.++We delegate to ``services.claude_oauth`` for the spawn + status checks.+After ``auth login`` returns the spawned PID, a background task polls+``claude auth status`` until it reports success, then writes the synthetic+``"cli-managed"`` marker via ``auth_service.store_oauth_tokens()`` and+broadcasts ``credential_catalogue_updated`` (Stripe pattern, see+``nodes/stripe/_handlers.py``).++Codex login is not yet wired (no ``codex_oauth.py`` yet); the handler+returns a graceful "not yet supported" error pointing the user at the+manual flow. Logout works for both providers — drops the catalogue marker."""from __future__ import annotations+import asyncio+import timefrom typing import Any, Awaitable, Callable, Dictfrom fastapi import WebSocketfrom core.logging import get_logger-from services.cli_agent.cli_auth import run_native_loginlogger = get_logger(__name__)@@ -40,19 +48,17 @@ logger = get_logger(__name__)# handler._MARKER_TOKEN = "cli-managed"-# Maps `cli_login.provider` field values to the credential-catalogue-# provider keys that `auth_service` indexes its OAuth tokens under.-# Aligns with the `status_hook` field in `credential_providers.json`.-_PROVIDER_TO_CATALOGUE_KEY: Dict[str, str] = {- "claude": "claude_code",- "codex": "codex_cli",- "gemini": "gemini_cli",-}+# How long the background finaliser polls for `claude auth status` before+# giving up (the user may simply close the browser tab).+_LOGIN_TIMEOUT_SECONDS = 600.0+_LOGIN_POLL_INTERVAL = 2.0++# ---------------------------------------------------------------------------+# Marker-token + catalogue broadcast (Stripe pattern)+# ---------------------------------------------------------------------------async def _mark_logged_in(catalogue_key: str) -> None:- """Write the marker token via `auth_service.store_oauth_tokens()` —- same plumbing Google / Twitter / Stripe use after their OAuth flow."""from core.container import containerawait container.auth_service().store_oauth_tokens(provider=catalogue_key,@@ -67,81 +73,132 @@ async def _mark_logged_out(catalogue_key: str) -> None:async def _broadcast_catalogue_updated() -> None:- """Generic catalogue-invalidation broadcast — same event the Stripe /- Google / Twitter handlers fire. Frontend listens in- ``WebSocketContext`` (``case 'credential_catalogue_updated'``) and- re-fetches the catalogue."""from services.status_broadcaster import get_status_broadcasterawait get_status_broadcaster().broadcast({"type": "credential_catalogue_updated"})-async def handle_cli_login(- data: Dict[str, Any],- websocket: WebSocket, # noqa: ARG001 — registry signature-) -> Dict[str, Any]:- """Trigger the CLI's native login flow.+# ---------------------------------------------------------------------------+# Claude — `claude auth login` / `auth status` / `auth logout`+# ---------------------------------------------------------------------------- Payload: ``{provider: "claude" | "codex" | "gemini"}``.+async def _wait_until_logged_in(timeout_seconds: float) -> bool:+ """Poll ``claude auth status`` until it reports success or we time out."""+ from services.claude_oauth import claude_auth_status- On success: write the marker token via ``auth_service`` (so the- catalogue's ``stored`` flag flips) and broadcast- ``credential_catalogue_updated`` so the modal refreshes reactively.+ deadline = time.monotonic() + timeout_seconds+ while time.monotonic() < deadline:+ if await claude_auth_status():+ return True+ await asyncio.sleep(_LOGIN_POLL_INTERVAL)+ return False- The CLI itself stores its real credentials in ``~/.claude/``,- ``~/.codex/``, ``~/.gemini/`` — we never touch them.- """- provider = (data.get("provider") or "").strip().lower()- if not provider:- return {"success": False, "error": "missing 'provider' field"}- result = await run_native_login(provider)+async def _finalize_claude_login() -> None:+ try:+ ok = await _wait_until_logged_in(_LOGIN_TIMEOUT_SECONDS)+ if ok:+ await _mark_logged_in("claude_code")+ await _broadcast_catalogue_updated()+ logger.info("[claude_code_login] marker written + broadcast fired")+ else:+ logger.warning(+ "[claude_code_login] timed out after %.0fs waiting for "+ "`claude auth status` to report success — modal stays Disconnected",+ _LOGIN_TIMEOUT_SECONDS,+ )+ except asyncio.CancelledError:+ raise+ except Exception as exc: # pragma: no cover — defensive+ logger.exception("[claude_code_login] finalize failed: %s", exc)+++async def handle_claude_code_login(+ data: Dict[str, Any], # noqa: ARG001 — frontend sends {}+ websocket: WebSocket, # noqa: ARG001 — registry signature+) -> Dict[str, Any]:+ """Spawn ``claude auth login``; let the CLI open the user's browser."""+ from services.claude_oauth import claude_auth_status, initiate_claude_oauth++ if await claude_auth_status():+ try:+ await _mark_logged_in("claude_code")+ await _broadcast_catalogue_updated()+ except Exception as exc:+ logger.warning("[claude_code_login] mark/broadcast failed: %s", exc)+ return {+ "success": True,+ "already_logged_in": True,+ "message": "Already authenticated; refreshed status.",+ }++ result = await initiate_claude_oauth()if result.get("success"):- catalogue_key = _PROVIDER_TO_CATALOGUE_KEY.get(provider)- if catalogue_key:- try:- await _mark_logged_in(catalogue_key)- await _broadcast_catalogue_updated()- except Exception as exc:- # Login itself succeeded; failing to mark/broadcast is a- # cosmetic/UI issue, not a user-visible login failure.- logger.warning(- "[cli_login:%s] mark/broadcast failed: %s", provider, exc,- )+ asyncio.create_task(+ _finalize_claude_login(), name="claude_code_login_finalize",+ )return result-async def handle_cli_logout(- data: Dict[str, Any],- websocket: WebSocket, # noqa: ARG001 — registry signature+async def handle_claude_code_logout(+ data: Dict[str, Any], # noqa: ARG001+ websocket: WebSocket, # noqa: ARG001) -> Dict[str, Any]:- """Drop the marker token + broadcast catalogue update.+ """Run ``claude auth logout``, drop the catalogue marker, broadcast."""+ from services.claude_oauth import claude_auth_logout++ try:+ await claude_auth_logout()+ await _mark_logged_out("claude_code")+ await _broadcast_catalogue_updated()+ except Exception as exc:+ logger.warning("[claude_code_logout] failed: %s", exc)+ return {"success": False, "error": str(exc)}+ return {"success": True}- The actual CLI auth lives in the CLI's own ~/. config — the user- can run ``<provider> logout`` themselves to drop it. We just clear- our catalogue marker so the modal flips back to Disconnected.- """- provider = (data.get("provider") or "").strip().lower()- if not provider:- return {"success": False, "error": "missing 'provider' field"}- catalogue_key = _PROVIDER_TO_CATALOGUE_KEY.get(provider)- if not catalogue_key:- return {"success": False, "error": f"unknown provider {provider!r}"}+# ---------------------------------------------------------------------------+# Codex — login flow not yet wired; logout works for marker cleanup+# ---------------------------------------------------------------------------+async def handle_codex_cli_login(+ data: Dict[str, Any], # noqa: ARG001+ websocket: WebSocket, # noqa: ARG001+) -> Dict[str, Any]:+ return {+ "success": False,+ "error": (+ "Codex login is not yet wired in MachinaOs. "+ "Install with `npm install -g @openai/codex` and run "+ "`codex login` in your terminal — then click Login again "+ "to mark connected."+ ),+ }+++async def handle_codex_cli_logout(+ data: Dict[str, Any], # noqa: ARG001+ websocket: WebSocket, # noqa: ARG001+) -> Dict[str, Any]:try:- await _mark_logged_out(catalogue_key)+ await _mark_logged_out("codex_cli")await _broadcast_catalogue_updated()except Exception as exc:- logger.warning("[cli_logout:%s] mark/broadcast failed: %s", provider, exc)+ logger.warning("[codex_cli_logout] failed: %s", exc)return {"success": False, "error": str(exc)}return {"success": True}+# ---------------------------------------------------------------------------# Registry payload — `services/cli_agent/__init__.py` registers these-# into `services.ws_handler_registry` on package import.+# into `services.ws_handler_registry` on package import. Names match+# `credential_providers.json:ws.login/logout`.+# ---------------------------------------------------------------------------+WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]WS_HANDLERS: Dict[str, WSHandler] = {- "cli_login": handle_cli_login,- "cli_logout": handle_cli_logout,+ "claude_code_login": handle_claude_code_login,+ "claude_code_logout": handle_claude_code_logout,+ "codex_cli_login": handle_codex_cli_login,+ "codex_cli_logout": handle_codex_cli_logout,}diff --git a/server/services/cli_agent/cli_auth.py b/server/services/cli_agent/cli_auth.pydeleted file mode 100644index bae04c74..00000000--- a/server/services/cli_agent/cli_auth.py+++ /dev/null@@ -1,149 +0,0 @@-"""Native CLI login spawner.--Replaces what would have been per-provider OAuth modules-(``codex_oauth.py``, ``gemini_oauth.py``). Each CLI ships a working-``<provider> login`` flow that handles the browser/device flow and-stores credentials in its native location (``~/.claude/``,-``~/.codex/``, ``~/.gemini/``). MachinaOs only triggers the flow.--After ``run_native_login()`` succeeds, ``_handlers.py`` writes a-synthetic marker OAuth token via ``auth_service.store_oauth_tokens()``-(Stripe-style — see ``nodes/stripe/_handlers.py``). The catalogue's-generic ``stored`` check then flips ``true`` and the existing-``OAuthConnect.tsx`` primitive renders the modal as Connected — no-per-provider status hook needed.--There's no ``check_auth`` here: the marker-token + catalogue-broadcast-pattern makes a separate status probe redundant. If you actually want to-verify the CLI is functional (vs just "we marked you as logged in"), the-first session attempt's stderr matcher (``provider.detect_auth_error``)-catches it.-"""--from __future__ import annotations--import asyncio-import shutil-from typing import Any, Dict, List, Optional, Tuple--from core.logging import get_logger--from services.cli_agent.factory import create_cli_provider-from services.cli_agent.protocol import AICliProvider--logger = get_logger(__name__)---# ----------------------------------------------------------------------------# Argv resolution (shared between login + the providers' own binary_path)-# -----------------------------------------------------------------------------def _resolve_argv(- provider: AICliProvider,- argv: List[str],-) -> Tuple[Optional[List[str]], Optional[str]]:- """Resolve ``argv[0]`` to an absolute path or an npx shim.-- Returns ``(resolved_argv, error)``. Either field is None.-- NB: For npm-distributed CLIs (Claude / Codex / Gemini), the Stripe- GitHub-release auto-installer pattern doesn't apply — there are no- standalone binaries on GitHub releases. We fall back to ``npx`` which- auto-fetches the npm package on first use, mirroring what- ``provider.binary_path()`` already does in the providers themselves.- """- if not argv:- return None, "empty argv"- resolved = shutil.which(argv[0])- if resolved:- return [resolved] + argv[1:], None- npx = shutil.which("npx")- if npx and provider.package_name:- return [npx, "--yes", provider.package_name] + argv[1:], None- return None, (- f"Command not found: {argv[0]!r}. Install with "- f"`npm install -g {provider.package_name}` or ensure 'npx' is on PATH."- )---def _build_provider(provider_name: str) -> Tuple[Optional[AICliProvider], Optional[Dict[str, Any]]]:- """Construct a provider, mapping factory errors to result dicts."""- try:- return create_cli_provider(provider_name), None- except NotImplementedError as exc:- return None, {"success": False, "exit_code": None, "stderr_tail": "", "error": str(exc)}- except ValueError as exc:- return None, {"success": False, "exit_code": None, "stderr_tail": "", "error": str(exc)}---# ----------------------------------------------------------------------------# Login-# -----------------------------------------------------------------------------async def run_native_login(- provider_name: str,- *,- timeout_seconds: float = 300.0,- inherit_stdio: bool = True,-) -> Dict[str, Any]:- """Spawn the CLI's own ``<provider> login`` command.-- With ``inherit_stdio=True`` (default) the user completes the OAuth /- device-code flow directly in their terminal — we capture nothing.- """- provider, err = _build_provider(provider_name)- if err is not None:- return err- assert provider is not None-- argv, resolve_err = _resolve_argv(provider, list(provider.login_argv()))- if argv is None:- return {- "success": False, "exit_code": None, "stderr_tail": "",- "error": resolve_err,- }-- logger.info("[cli_login:%s] spawning %s", provider_name, argv)-- if inherit_stdio:- proc = await asyncio.create_subprocess_exec(*argv)- try:- exit_code = await asyncio.wait_for(proc.wait(), timeout=timeout_seconds)- except asyncio.TimeoutError:- proc.kill()- return {- "success": False, "exit_code": None, "stderr_tail": "",- "error": f"login timed out after {timeout_seconds:.0f}s",- }- return {- "success": exit_code == 0,- "exit_code": exit_code,- "stderr_tail": "",- "error": None if exit_code == 0 else f"login exited with code {exit_code}",- }-- proc = await asyncio.create_subprocess_exec(- *argv,- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- )- try:- _, stderr = await asyncio.wait_for(- proc.communicate(), timeout=timeout_seconds,- )- except asyncio.TimeoutError:- proc.kill()- return {- "success": False, "exit_code": None, "stderr_tail": "",- "error": f"login timed out after {timeout_seconds:.0f}s",- }- stderr_text = stderr.decode("utf-8", errors="replace")- return {- "success": proc.returncode == 0,- "exit_code": proc.returncode,- "stderr_tail": stderr_text[-2000:],- "error": (- None if proc.returncode == 0- else f"login exited with code {proc.returncode}"- ),- }