@gaia-minds/assistant-cli 0.1.0 → 0.2.0

package/tools/gaia-assistant.py

@@ -9,11 +9,18 @@ from __future__ import annotations
 
 import argparse
 import base64
+import getpass
+import html
 import json
 import os
+import re
 import shutil
 import subprocess
 import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -23,7 +30,9 @@ SCRIPT_DIR = Path(__file__).resolve().parent
 REPO_ROOT = SCRIPT_DIR.parent
 DEFAULT_HOME = Path(os.environ.get("GAIA_ASSISTANT_HOME", str(Path.home() / ".gaia-assistant"))).expanduser()
 DEFAULT_STATE_DIR = DEFAULT_HOME / "state"
+DEFAULT_DATA_DIR = DEFAULT_HOME / "data"
 DEFAULT_CONFIG_PATH = DEFAULT_HOME / "config.json"
+DEFAULT_SECRET_STORE = DEFAULT_HOME / "secrets.json"
 AGENT_CONFIG_PATH = SCRIPT_DIR / "agent-config.yml"
 AGENT_LOOP_PATH = SCRIPT_DIR / "agent-loop.py"
 DEFAULT_LAUNCHER_HINT = "python3 tools/gaia-assistant.py"
@@ -34,6 +43,30 @@ DEFAULT_CODEX_AUTH_PATH = Path(
 DEFAULT_OPENCLAW_STATE_DIR = Path(
     os.environ.get("OPENCLAW_STATE_DIR", str(Path.home() / ".openclaw"))
 ).expanduser()
+DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5-20250929"
+DEFAULT_OPENAI_MODEL = "gpt-4.1-mini"
+DEFAULT_OPENROUTER_MODEL = "openrouter/auto"
+ONBOARD_PROVIDER_CHOICES = ("openrouter", "openai", "anthropic", "openai-codex")
+PROFILE_VERBOSITY_CHOICES = ("concise", "balanced", "detailed")
+PROFILE_PROVIDER_CHOICES = ("openrouter", "openai", "anthropic", "openai-codex")
+PERMISSION_LEVEL_CHOICES = ("safe", "confirm", "forbidden")
+DEFAULT_SESSION_CONTEXT_TURNS = 20
+DEFAULT_CAPABILITY_LEVELS = {
+    "file_read": "safe",
+    "file_write": "safe",
+    "network_request": "safe",
+    "shell_exec": "confirm",
+    "delete_files": "confirm",
+    "send_email": "forbidden",
+    "external_messaging": "forbidden",
+}
+PROFILE_KEY_MAP = {
+    "name": ("profile", "name"),
+    "timezone": ("profile", "timezone"),
+    "verbosity": ("profile", "verbosity"),
+    "provider": ("profile", "default_provider"),
+    "default_provider": ("profile", "default_provider"),
+}
 
 
 DEFAULT_CONFIG: Dict[str, Any] = {
@@ -41,21 +74,55 @@ DEFAULT_CONFIG: Dict[str, Any] = {
         "mode": "continuous",
         "interval_minutes": 60,
     },
+    "reasoning": {
+        "provider": "anthropic",
+        "model": DEFAULT_ANTHROPIC_MODEL,
+    },
+    "secrets": {
+        "store_path": str(DEFAULT_SECRET_STORE),
+    },
     "auth": {
         "providers": {
             "anthropic": {
-                "subscription_oauth_supported": True,
+                "subscription_oauth_supported": False,
                 "api_key_env": "ANTHROPIC_API_KEY",
             },
             "openai": {
                 "subscription_oauth_supported": True,
                 "api_key_env": "OPENAI_API_KEY",
             },
+            "openai-codex": {
+                "subscription_oauth_supported": True,
+                "api_key_env": "",
+            },
+            "openrouter": {
+                "subscription_oauth_supported": False,
+                "api_key_env": "OPENROUTER_API_KEY",
+            },
         }
     },
     "tracks": {
         "default": "auto",
     },
+    "profile": {
+        "name": "",
+        "timezone": "UTC",
+        "verbosity": "balanced",
+        "default_provider": "anthropic",
+    },
+    "capabilities": {
+        "overrides": {},
+    },
+    "traces": {
+        "dir": str(DEFAULT_HOME / "traces"),
+    },
+    "sessions": {
+        "dir": str(DEFAULT_HOME / "sessions"),
+        "max_context_turns": DEFAULT_SESSION_CONTEXT_TURNS,
+    },
+    "storage": {
+        "dir": str(DEFAULT_DATA_DIR),
+    },
 }
 
 
@@ -94,6 +161,13 @@ def _normalize_config(payload: Dict[str, Any]) -> Dict[str, Any]:
     runtime.setdefault("mode", "continuous")
     runtime.setdefault("interval_minutes", 60)
 
+    reasoning = cfg.setdefault("reasoning", {})
+    reasoning.setdefault("provider", "anthropic")
+    reasoning.setdefault("model", DEFAULT_ANTHROPIC_MODEL)
+
+    secrets = cfg.setdefault("secrets", {})
+    secrets.setdefault("store_path", str(DEFAULT_SECRET_STORE))
+
     auth = cfg.setdefault("auth", {})
     providers = auth.setdefault("providers", {})
     auth.setdefault("store_path", str(DEFAULT_GAIA_AUTH_STORE))
@@ -107,9 +181,724 @@ def _normalize_config(payload: Dict[str, Any]) -> Dict[str, Any]:
 
     tracks = cfg.setdefault("tracks", {})
     tracks.setdefault("default", "auto")
+
+    profile = cfg.setdefault("profile", {})
+    profile.setdefault("name", "")
+    profile.setdefault("timezone", "UTC")
+    profile.setdefault("verbosity", "balanced")
+    profile.setdefault("default_provider", "anthropic")
+
+    verbosity = str(profile.get("verbosity", "")).strip().lower()
+    if verbosity not in PROFILE_VERBOSITY_CHOICES:
+        profile["verbosity"] = "balanced"
+
+    default_provider = str(profile.get("default_provider", "")).strip().lower()
+    if default_provider not in PROFILE_PROVIDER_CHOICES:
+        profile["default_provider"] = "anthropic"
+
+    capabilities = cfg.setdefault("capabilities", {})
+    overrides = capabilities.setdefault("overrides", {})
+    if not isinstance(overrides, dict):
+        capabilities["overrides"] = {}
+
+    traces = cfg.setdefault("traces", {})
+    traces_dir = str(traces.get("dir", "")).strip()
+    if not traces_dir:
+        traces["dir"] = str(DEFAULT_HOME / "traces")
+
+    sessions = cfg.setdefault("sessions", {})
+    sessions_dir = str(sessions.get("dir", "")).strip()
+    if not sessions_dir:
+        sessions["dir"] = str(DEFAULT_HOME / "sessions")
+    max_context = sessions.get("max_context_turns", DEFAULT_SESSION_CONTEXT_TURNS)
+    if not isinstance(max_context, int) or max_context < 2:
+        sessions["max_context_turns"] = DEFAULT_SESSION_CONTEXT_TURNS
+
+    storage = cfg.setdefault("storage", {})
+    storage_dir = str(storage.get("dir", "")).strip()
+    if not storage_dir:
+        storage["dir"] = str(DEFAULT_DATA_DIR)
+
     return cfg
 
 
+def _config_path_for_key(key: str) -> Optional[Tuple[str, str]]:
+    return PROFILE_KEY_MAP.get(key.strip().lower())
+
+
+def _get_nested_value(cfg: Dict[str, Any], path: Tuple[str, str]) -> Any:
+    section, field = path
+    section_value = cfg.get(section, {})
+    if not isinstance(section_value, dict):
+        return None
+    return section_value.get(field)
+
+
+def _set_nested_value(cfg: Dict[str, Any], path: Tuple[str, str], value: Any) -> None:
+    section, field = path
+    section_value = cfg.setdefault(section, {})
+    if not isinstance(section_value, dict):
+        section_value = {}
+        cfg[section] = section_value
+    section_value[field] = value
+
+
+def _normalize_profile_value(key: str, value: str) -> Tuple[Optional[str], Optional[str]]:
+    canonical_key = key.strip().lower()
+    raw = value.strip()
+    if canonical_key == "verbosity":
+        normalized = raw.lower()
+        if normalized not in PROFILE_VERBOSITY_CHOICES:
+            return None, (
+                f"Invalid verbosity '{value}'. "
+                f"Expected one of: {', '.join(PROFILE_VERBOSITY_CHOICES)}."
+            )
+        return normalized, None
+    if canonical_key in ("provider", "default_provider"):
+        normalized = raw.lower()
+        if normalized not in PROFILE_PROVIDER_CHOICES:
+            return None, (
+                f"Invalid provider '{value}'. "
+                f"Expected one of: {', '.join(PROFILE_PROVIDER_CHOICES)}."
+            )
+        return normalized, None
+    if canonical_key == "timezone":
+        if not raw:
+            return None, "timezone cannot be empty."
+        return raw, None
+    if canonical_key == "name":
+        return raw, None
+    return None, f"Unsupported key: {key}"
+
+
+def _resolve_trace_dir(cfg: Dict[str, Any], override_path: Optional[str] = None) -> Path:
+    if override_path:
+        return Path(override_path).expanduser()
+    traces = cfg.get("traces", {})
+    if isinstance(traces, dict):
+        configured = str(traces.get("dir", "")).strip()
+        if configured:
+            return Path(configured).expanduser()
+    return DEFAULT_HOME / "traces"
+
+
+def _append_jsonl(path: Path, payload: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, ensure_ascii=True) + "\n")
+
+
+def _summarize_text(value: Any, max_chars: int = 180) -> str:
+    text = str(value).replace("\n", " ").strip()
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - 3] + "..."
+
+
+def _trace_action_path(trace_dir: Path) -> Path:
+    return trace_dir / "actions.jsonl"
+
+
+def _write_action_trace(
+    trace_dir: Path,
+    action_type: str,
+    input_summary: str,
+    output_summary: str,
+    duration_ms: float,
+    permission_level: str,
+    status: str = "ok",
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    record: Dict[str, Any] = {
+        "id": str(uuid.uuid4()),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "action_type": action_type,
+        "input_summary": _summarize_text(input_summary),
+        "output_summary": _summarize_text(output_summary),
+        "duration_ms": round(max(duration_ms, 0.0), 3),
+        "permission_level": permission_level,
+        "status": status,
+        "schema_version": 1,
+    }
+    if metadata:
+        record["metadata"] = metadata
+    _append_jsonl(_trace_action_path(trace_dir), record)
+    return record
+
+
+def _read_action_traces(trace_dir: Path) -> List[Dict[str, Any]]:
+    path = _trace_action_path(trace_dir)
+    if not path.exists():
+        return []
+    traces: List[Dict[str, Any]] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(payload, dict):
+            traces.append(payload)
+    return traces
+
+
+def _capability_registry(cfg: Dict[str, Any]) -> Dict[str, str]:
+    registry = dict(DEFAULT_CAPABILITY_LEVELS)
+    capabilities = cfg.get("capabilities", {})
+    overrides = {}
+    if isinstance(capabilities, dict):
+        raw_overrides = capabilities.get("overrides", {})
+        if isinstance(raw_overrides, dict):
+            overrides = raw_overrides
+    for capability, level in overrides.items():
+        normalized_level = str(level).strip().lower()
+        if normalized_level in PERMISSION_LEVEL_CHOICES:
+            registry[str(capability).strip()] = normalized_level
+    return registry
+
+
+def _permission_for_capability(cfg: Dict[str, Any], capability: str) -> str:
+    registry = _capability_registry(cfg)
+    return registry.get(capability, "confirm")
+
+
+def _check_capability_permission(
+    cfg: Dict[str, Any],
+    capability: str,
+    user_prompt: Optional[str],
+    non_interactive: bool,
+) -> Tuple[bool, str, str]:
+    level = _permission_for_capability(cfg, capability)
+    if level == "safe":
+        return True, level, "allowed"
+    if level == "forbidden":
+        return False, level, f"blocked by policy for capability '{capability}'"
+
+    prompt = user_prompt or f"Capability '{capability}' requires confirmation. Continue?"
+    allowed = _prompt_yes_no(prompt, default=False, non_interactive=non_interactive)
+    if allowed:
+        return True, level, "allowed after confirmation"
+    return False, level, "user denied confirmation"
+
+
+class ProviderError(RuntimeError):
+    """Raised when the configured reasoning provider call fails."""
+
+
+class ProviderTokenLimitError(ProviderError):
+    """Raised when provider rejects a request due to context/token limits."""
+
+
+def _resolve_session_dir(cfg: Dict[str, Any], override_path: Optional[str] = None) -> Path:
+    if override_path:
+        return Path(override_path).expanduser()
+    sessions = cfg.get("sessions", {})
+    if isinstance(sessions, dict):
+        configured = str(sessions.get("dir", "")).strip()
+        if configured:
+            return Path(configured).expanduser()
+    return DEFAULT_HOME / "sessions"
+
+
+def _resolve_storage_dir(cfg: Dict[str, Any], override_path: Optional[str] = None) -> Path:
+    if override_path:
+        return Path(override_path).expanduser()
+    storage = cfg.get("storage", {})
+    if isinstance(storage, dict):
+        configured = str(storage.get("dir", "")).strip()
+        if configured:
+            return Path(configured).expanduser()
+    return DEFAULT_DATA_DIR
+
+
+def _load_records(path: Path) -> List[Dict[str, Any]]:
+    payload = _load_json(path)
+    if not payload:
+        return []
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        items = payload.get("items", [])
+        if isinstance(items, list):
+            return [item for item in items if isinstance(item, dict)]
+    return []
+
+
+def _save_records(path: Path, items: List[Dict[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(items, indent=2) + "\n", encoding="utf-8")
+
+
+def _notes_path(storage_dir: Path) -> Path:
+    return storage_dir / "notes.json"
+
+
+def _tasks_path(storage_dir: Path) -> Path:
+    return storage_dir / "tasks.json"
+
+
+def _summaries_path(storage_dir: Path) -> Path:
+    return storage_dir / "summaries.json"
+
+
+def _plans_path(storage_dir: Path) -> Path:
+    return storage_dir / "plans.json"
+
+
+def _new_record_id(prefix: str) -> str:
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+    return f"{prefix}{timestamp}-{uuid.uuid4().hex[:6]}"
+
+
+def _create_note_record(text: str, source: str) -> Dict[str, Any]:
+    now = datetime.now(timezone.utc).isoformat()
+    return {
+        "id": _new_record_id("n"),
+        "text": text.strip(),
+        "created_at": now,
+        "updated_at": now,
+        "source": source,
+    }
+
+
+def _create_task_record(text: str, source: str) -> Dict[str, Any]:
+    now = datetime.now(timezone.utc).isoformat()
+    return {
+        "id": _new_record_id("t"),
+        "text": text.strip(),
+        "status": "open",
+        "created_at": now,
+        "updated_at": now,
+        "source": source,
+    }
+
+
+def _parse_since_date(raw: str) -> Optional[datetime]:
+    value = raw.strip()
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _captures_note_intent(user_input: str) -> Optional[Tuple[str, bool]]:
+    text = user_input.strip()
+    lower = text.lower()
+    note_markers = ("capture this as a note", "save as note", "note this")
+    task_markers = ("capture this as a task", "save as task", "add task")
+
+    for marker in note_markers:
+        if lower.startswith(marker):
+            content = text[len(marker) :].lstrip(" :,-")
+            return (content, False)
+    for marker in task_markers:
+        if lower.startswith(marker):
+            content = text[len(marker) :].lstrip(" :,-")
+            return (content, True)
+    return None
+
+
+def _extract_title_and_text(raw_html: str) -> Tuple[str, str]:
+    title = ""
+    title_match = re.search(r"<title[^>]*>(.*?)</title>", raw_html, flags=re.IGNORECASE | re.DOTALL)
+    if title_match:
+        title = html.unescape(re.sub(r"\s+", " ", title_match.group(1)).strip())
+
+    no_script = re.sub(r"<script[^>]*>.*?</script>", " ", raw_html, flags=re.IGNORECASE | re.DOTALL)
+    no_style = re.sub(r"<style[^>]*>.*?</style>", " ", no_script, flags=re.IGNORECASE | re.DOTALL)
+    text_only = re.sub(r"<[^>]+>", " ", no_style)
+    normalized = html.unescape(re.sub(r"\s+", " ", text_only)).strip()
+    return title, normalized
+
+
+def _fetch_url_content(url: str, timeout: int = 15) -> Tuple[str, str]:
+    req = urllib.request.Request(
+        url,
+        headers={"User-Agent": "GaiaAssistant/0.1"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            charset = response.headers.get_content_charset() or "utf-8"
+            raw = response.read().decode(charset, errors="replace")
+    except urllib.error.HTTPError as exc:
+        raise ProviderError(f"HTTP {exc.code} for {url}") from exc
+    except urllib.error.URLError as exc:
+        raise ProviderError(f"Network error for {url}: {exc.reason}") from exc
+    except TimeoutError as exc:
+        raise ProviderError(f"Timeout fetching {url}") from exc
+    return _extract_title_and_text(raw)
+
+
+def _key_points_from_text(text: str, max_points: int = 4) -> List[str]:
+    if not text.strip():
+        return []
+    pieces = re.split(r"(?<=[.!?])\s+", text.strip())
+    points: List[str] = []
+    for piece in pieces:
+        cleaned = piece.strip()
+        if len(cleaned) < 30:
+            continue
+        points.append(_summarize_text(cleaned, max_chars=200))
+        if len(points) >= max_points:
+            break
+    if points:
+        return points
+    return [_summarize_text(text, max_chars=200)]
+
+
+def _estimate_plan_complexity(goal: str) -> str:
+    words = [part for part in goal.strip().split() if part]
+    count = len(words)
+    if count <= 5:
+        return "low"
+    if count <= 12:
+        return "medium"
+    return "high"
+
+
+def _derive_plan_dependencies(goal: str) -> List[str]:
+    normalized = goal.strip().lower()
+    dependencies: List[str] = []
+    if any(token in normalized for token in ("research", "knowledge", "study", "read")):
+        dependencies.append("reference material access")
+    if any(token in normalized for token in ("setup", "install", "deploy", "configure")):
+        dependencies.append("runtime environment access")
+    if any(token in normalized for token in ("team", "collaborate", "stakeholder")):
+        dependencies.append("stakeholder coordination")
+    dependencies.append("time allocation")
+    seen = set()
+    deduped: List[str] = []
+    for item in dependencies:
+        if item in seen:
+            continue
+        seen.add(item)
+        deduped.append(item)
+    return deduped
+
+
+def _generate_plan_steps(goal: str, refinement: str = "") -> List[str]:
+    steps = [
+        f"Clarify the objective and success criteria for '{goal.strip()}'.",
+        "Break the objective into concrete milestones with owners and deadlines.",
+        "Execute the milestones in priority order and capture outputs.",
+        "Review results, identify gaps, and schedule next iteration.",
+    ]
+    refinement_text = refinement.strip()
+    if refinement_text:
+        steps.append(f"Refinement request: {refinement_text}")
+    return steps
+
+def _session_file_path(session_dir: Path, session_id: str) -> Path:
+    return session_dir / f"{session_id}.json"
+
+
+def _load_session(session_dir: Path, session_id: str) -> Optional[Dict[str, Any]]:
+    path = _session_file_path(session_dir, session_id)
+    payload = _load_json(path)
+    if not payload:
+        return None
+    if not isinstance(payload.get("turns"), list):
+        payload["turns"] = []
+    return payload
+
+
+def _save_session(session_dir: Path, session: Dict[str, Any]) -> None:
+    session_dir.mkdir(parents=True, exist_ok=True)
+    _write_json(_session_file_path(session_dir, str(session["id"])), session)
+
+
+def _list_sessions(session_dir: Path) -> List[Dict[str, Any]]:
+    if not session_dir.exists():
+        return []
+    sessions: List[Dict[str, Any]] = []
+    for path in session_dir.glob("*.json"):
+        payload = _load_json(path)
+        if not payload:
+            continue
+        session_id = str(payload.get("id", "")).strip()
+        updated_at = str(payload.get("updated_at", "")).strip()
+        if not session_id:
+            continue
+        sessions.append({"id": session_id, "updated_at": updated_at})
+    sessions.sort(key=lambda item: item.get("updated_at", ""), reverse=True)
+    return sessions
+
+
+def _create_session(provider: str, model: str) -> Dict[str, Any]:
+    session_id = datetime.now(timezone.utc).strftime("s%Y%m%d%H%M%S") + "-" + uuid.uuid4().hex[:6]
+    now = datetime.now(timezone.utc).isoformat()
+    return {
+        "id": session_id,
+        "created_at": now,
+        "updated_at": now,
+        "provider": provider,
+        "model": model,
+        "turns": [],
+    }
+
+
+def _resolve_resume_session_id(session_dir: Path, resume: str) -> Optional[str]:
+    target = str(resume).strip()
+    if not target:
+        return None
+    if target != "last":
+        return target
+    sessions = _list_sessions(session_dir)
+    if not sessions:
+        return None
+    return str(sessions[0]["id"])
+
+
+def _extract_last_user_text(messages: List[Dict[str, str]]) -> str:
+    for msg in reversed(messages):
+        if str(msg.get("role", "")).strip() == "user":
+            return str(msg.get("content", "")).strip()
+    return ""
+
+
+def _mock_provider_response(provider: str, model: str, messages: List[Dict[str, str]]) -> str:
+    prompt = _extract_last_user_text(messages)
+    prompt_summary = _summarize_text(prompt, max_chars=140)
+    return (
+        f"[local-{provider}] {prompt_summary}\n"
+        f"Context messages: {len(messages)} | model: {model}."
+    )
+
+
+def _extract_http_error_details(exc: urllib.error.HTTPError) -> str:
+    try:
+        raw = exc.read().decode("utf-8")
+    except Exception:
+        return str(exc)
+    if not raw:
+        return str(exc)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return raw
+    if isinstance(payload, dict):
+        if isinstance(payload.get("error"), dict):
+            message = payload["error"].get("message")
+            if isinstance(message, str) and message.strip():
+                return message.strip()
+        message = payload.get("message")
+        if isinstance(message, str) and message.strip():
+            return message.strip()
+    return raw
+
+
+def _looks_like_token_limit(text: str) -> bool:
+    normalized = text.strip().lower()
+    markers = (
+        "context length",
+        "too many tokens",
+        "token limit",
+        "maximum context",
+        "context_window_exceeded",
+        "context_length_exceeded",
+    )
+    return any(marker in normalized for marker in markers)
+
+
+def _http_json_request(
+    url: str,
+    headers: Dict[str, str],
+    payload: Dict[str, Any],
+    timeout: int = 30,
+) -> Dict[str, Any]:
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            raw = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        details = _extract_http_error_details(exc)
+        if exc.code in (413, 429) or _looks_like_token_limit(details):
+            raise ProviderTokenLimitError(details) from exc
+        raise ProviderError(f"HTTP {exc.code}: {details}") from exc
+    except urllib.error.URLError as exc:
+        raise ProviderError(f"Network error: {exc.reason}") from exc
+
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ProviderError("Provider returned non-JSON response") from exc
+    if not isinstance(decoded, dict):
+        raise ProviderError("Provider returned invalid payload")
+    return decoded
+
+
+def _call_openai_chat(
+    base_url: str,
+    api_key: str,
+    model: str,
+    messages: List[Dict[str, str]],
+) -> str:
+    payload = {
+        "model": model,
+        "messages": messages,
+        "temperature": 0.2,
+    }
+    response = _http_json_request(
+        url=f"{base_url.rstrip('/')}/chat/completions",
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        payload=payload,
+    )
+    choices = response.get("choices", [])
+    if not isinstance(choices, list) or not choices:
+        raise ProviderError("Provider returned no choices")
+    first = choices[0]
+    if not isinstance(first, dict):
+        raise ProviderError("Provider returned invalid choice")
+    message = first.get("message", {})
+    if not isinstance(message, dict):
+        raise ProviderError("Provider returned invalid message payload")
+    content = message.get("content")
+    if isinstance(content, str) and content.strip():
+        return content.strip()
+    if isinstance(content, list):
+        parts = [part.get("text", "") for part in content if isinstance(part, dict)]
+        merged = "\n".join([p for p in parts if p.strip()]).strip()
+        if merged:
+            return merged
+    raise ProviderError("Provider returned empty response")
+
+
+def _call_anthropic_chat(api_key: str, model: str, messages: List[Dict[str, str]]) -> str:
+    payload = {
+        "model": model,
+        "max_tokens": 700,
+        "messages": messages,
+    }
+    response = _http_json_request(
+        url="https://api.anthropic.com/v1/messages",
+        headers={
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        },
+        payload=payload,
+    )
+    content = response.get("content", [])
+    if not isinstance(content, list):
+        raise ProviderError("Provider returned invalid content")
+    parts: List[str] = []
+    for item in content:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") != "text":
+            continue
+        text = item.get("text")
+        if isinstance(text, str) and text.strip():
+            parts.append(text.strip())
+    if not parts:
+        raise ProviderError("Provider returned empty response")
+    return "\n".join(parts)
+
+
+def _resolve_runtime_provider(cfg: Dict[str, Any]) -> Tuple[str, str]:
+    reasoning = cfg.get("reasoning", {})
+    reasoning = reasoning if isinstance(reasoning, dict) else {}
+    profile = cfg.get("profile", {})
+    profile = profile if isinstance(profile, dict) else {}
+
+    provider = str(reasoning.get("provider", "")).strip().lower()
+    if not provider:
+        provider = str(profile.get("default_provider", "anthropic")).strip().lower()
+    if provider not in PROFILE_PROVIDER_CHOICES:
+        provider = "anthropic"
+
+    model = str(reasoning.get("model", "")).strip()
+    if not model:
+        model = _default_model_for_provider(provider)
+    return provider, model
+
+
+def _resolve_provider_api_key(
+    provider: str,
+    cfg_path: Path,
+    secret_store_override: Optional[str],
+) -> str:
+    env_key = {
+        "anthropic": "ANTHROPIC_API_KEY",
+        "openai": "OPENAI_API_KEY",
+        "openrouter": "OPENROUTER_API_KEY",
+    }.get(provider, "")
+    if not env_key:
+        return ""
+    from_env = os.environ.get(env_key, "").strip()
+    if from_env:
+        return from_env
+    secret_store = _resolve_secret_store(cfg_path, secret_store_override)
+    return _read_secret_api_key(secret_store, env_key)
+
+
+def _reasoning_response(
+    provider: str,
+    model: str,
+    messages: List[Dict[str, str]],
+    cfg_path: Path,
+    secret_store_override: Optional[str],
+) -> str:
+    if provider == "openai-codex":
+        return _mock_provider_response(provider, model, messages)
+
+    api_key = _resolve_provider_api_key(provider, cfg_path, secret_store_override)
+    if not api_key:
+        return _mock_provider_response(provider, model, messages)
+
+    if provider == "openai":
+        base_url = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
+        return _call_openai_chat(base_url=base_url, api_key=api_key, model=model, messages=messages)
+    if provider == "openrouter":
+        return _call_openai_chat(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=api_key,
+            model=model,
+            messages=messages,
+        )
+    if provider == "anthropic":
+        return _call_anthropic_chat(api_key=api_key, model=model, messages=messages)
+    raise ProviderError(f"Unsupported provider: {provider}")
+
+
+def _infer_capability_from_prompt(text: str) -> Tuple[str, Optional[str]]:
+    prompt = text.strip().lower()
+    if not prompt:
+        return "file_read", None
+    if "send email" in prompt or "email " in prompt:
+        return "send_email", "This action sends outbound email. Continue?"
+    if "delete" in prompt and ("file" in prompt or "folder" in prompt):
+        return "delete_files", "This action may delete files. Continue?"
+    if prompt.startswith("run ") or "execute " in prompt:
+        return "shell_exec", "This action executes shell commands. Continue?"
+    if "http://" in prompt or "https://" in prompt:
+        return "network_request", "This action performs a network request. Continue?"
+    return "file_read", None
+
+
+def _build_context_messages(
+    turns: List[Dict[str, Any]],
+    user_prompt: str,
+    max_turns: int,
+) -> List[Dict[str, str]]:
+    bounded = turns[-max_turns:] if max_turns > 0 else turns
+    messages: List[Dict[str, str]] = []
+    for turn in bounded:
+        role = str(turn.get("role", "")).strip()
+        content = str(turn.get("content", "")).strip()
+        if role in ("user", "assistant") and content:
+            messages.append({"role": role, "content": content})
+    messages.append({"role": "user", "content": user_prompt})
+    return messages
 def _ensure_config_exists(cfg_path: Path) -> Dict[str, Any]:
     cfg = _load_json(cfg_path)
     if not cfg:
@@ -122,6 +911,264 @@ def _ensure_config_exists(cfg_path: Path) -> Dict[str, Any]:
     return cfg
 
 
+def _prompt_yes_no(question: str, default: bool = True, non_interactive: bool = False) -> bool:
+    if non_interactive:
+        return default
+    suffix = "[Y/n]" if default else "[y/N]"
+    raw = input(f"{question} {suffix}: ").strip().lower()
+    if not raw:
+        return default
+    return raw in ("y", "yes")
+
+
+def _prompt_choice(
+    question: str,
+    options: List[Tuple[str, str]],
+    default_index: int = 0,
+    non_interactive: bool = False,
+) -> str:
+    if not options:
+        raise ValueError("options list cannot be empty")
+    if default_index < 0 or default_index >= len(options):
+        default_index = 0
+    if non_interactive:
+        return options[default_index][0]
+
+    print(question)
+    for idx, (_, label) in enumerate(options, start=1):
+        marker = " (default)" if idx - 1 == default_index else ""
+        print(f"  {idx}) {label}{marker}")
+
+    while True:
+        raw = input(f"Select [1-{len(options)}] (default {default_index + 1}): ").strip()
+        if not raw:
+            return options[default_index][0]
+        if raw.isdigit():
+            selected = int(raw)
+            if 1 <= selected <= len(options):
+                return options[selected - 1][0]
+        print("Invalid selection. Please enter a valid number.")
+
+
+def _resolve_secret_store(cfg_path: Path, override_path: Optional[str]) -> Path:
+    if override_path:
+        return Path(override_path).expanduser()
+    cfg = _load_json(cfg_path)
+    if cfg:
+        store = cfg.get("secrets", {}).get("store_path")
+        if isinstance(store, str) and store.strip():
+            return Path(store).expanduser()
+    return cfg_path.parent / "secrets.json"
+
+
+def _load_secret_store(path: Path) -> Dict[str, Any]:
+    payload = _load_json(path)
+    if not payload:
+        return {"version": 1, "api_keys": {}}
+    if not isinstance(payload.get("api_keys"), dict):
+        payload["api_keys"] = {}
+    if "version" not in payload:
+        payload["version"] = 1
+    return payload
+
+
+def _save_secret_store(path: Path, payload: Dict[str, Any]) -> None:
+    _write_secret_json(path, payload)
+
+
+def _read_secret_api_key(path: Path, env_var: str) -> str:
+    payload = _load_secret_store(path)
+    api_keys = payload.get("api_keys", {})
+    if not isinstance(api_keys, dict):
+        return ""
+    value = api_keys.get(env_var)
+    if not isinstance(value, str):
+        return ""
+    return value.strip()
+
+
+def _write_secret_api_key(path: Path, env_var: str, value: str) -> None:
+    payload = _load_secret_store(path)
+    api_keys = payload.setdefault("api_keys", {})
+    if not isinstance(api_keys, dict):
+        api_keys = {}
+        payload["api_keys"] = api_keys
+    api_keys[env_var] = value
+    _save_secret_store(path, payload)
+
+
+def _default_model_for_provider(provider: str) -> str:
+    if provider == "openrouter":
+        return DEFAULT_OPENROUTER_MODEL
+    if provider == "openai":
+        return DEFAULT_OPENAI_MODEL
+    return DEFAULT_ANTHROPIC_MODEL
+
+
+def _set_reasoning_config(cfg_path: Path, provider: str, model: Optional[str]) -> None:
+    cfg = _ensure_config_exists(cfg_path)
+    reasoning = cfg.setdefault("reasoning", {})
+    if not isinstance(reasoning, dict):
+        reasoning = {}
+        cfg["reasoning"] = reasoning
+
+    reasoning["provider"] = provider
+    if model and model.strip():
+        reasoning["model"] = model.strip()
+    else:
+        reasoning["model"] = _default_model_for_provider(provider)
+    _write_json(cfg_path, cfg)
+
+
+def _set_secret_store_config(cfg_path: Path, store_path: Path) -> None:
+    cfg = _ensure_config_exists(cfg_path)
+    secrets = cfg.setdefault("secrets", {})
+    if not isinstance(secrets, dict):
+        secrets = {}
+        cfg["secrets"] = secrets
+    secrets["store_path"] = str(store_path)
+    _write_json(cfg_path, cfg)
+
+
+def _is_zero_pricing(value: Any) -> bool:
+    if isinstance(value, (int, float)):
+        return float(value) == 0.0
+    if isinstance(value, str):
+        try:
+            return float(value.strip()) == 0.0
+        except ValueError:
+            return False
+    return False
+
+
+def _fetch_openrouter_free_models(api_key: str) -> List[str]:
+    if not api_key:
+        return []
+    req = urllib.request.Request(
+        "https://openrouter.ai/api/v1/models",
+        headers={"Authorization": f"Bearer {api_key}"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=12) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, TimeoutError):
+        return []
+
+    data = payload.get("data", [])
+    if not isinstance(data, list):
+        return []
+
+    free: List[str] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        model_id = str(item.get("id", "")).strip()
+        if not model_id:
+            continue
+        if ":free" in model_id:
+            free.append(model_id)
+            continue
+        pricing = item.get("pricing", {})
+        if isinstance(pricing, dict):
+            prompt = pricing.get("prompt")
+            completion = pricing.get("completion")
+            if _is_zero_pricing(prompt) and _is_zero_pricing(completion):
+                free.append(model_id)
+    seen = set()
+    uniq = []
+    for model in sorted(free):
+        if model in seen:
+            continue
+        uniq.append(model)
+        seen.add(model)
+    return uniq[:8]
+
+
+def _select_openrouter_model(
+    api_key: str,
+    explicit_model: Optional[str],
+    non_interactive: bool,
+) -> str:
+    if explicit_model and explicit_model.strip():
+        return explicit_model.strip()
+    if non_interactive:
+        return DEFAULT_OPENROUTER_MODEL
+
+    free_models = _fetch_openrouter_free_models(api_key)
+    options: List[Tuple[str, str]] = [("openrouter/auto", "openrouter/auto (recommended)")]
+    for model in free_models:
+        options.append((model, f"{model} (detected free model)"))
+    options.append(("__custom__", "Custom model id"))
+
+    selection = _prompt_choice(
+        "Choose your OpenRouter model:",
+        options,
+        default_index=0,
+        non_interactive=non_interactive,
+    )
+    if selection != "__custom__":
+        return selection
+
+    while True:
+        custom = input("Enter OpenRouter model id (example: provider/model:free): ").strip()
+        if custom:
+            return custom
+        print("Model id cannot be empty.")
+
+
+def _configure_api_key_provider(
+    cfg_path: Path,
+    provider: str,
+    api_key_env: str,
+    model: Optional[str],
+    api_key: Optional[str],
+    secret_store_override: Optional[str],
+    no_prompt: bool,
+    no_store_api_key: bool,
+) -> int:
+    secret_store = _resolve_secret_store(cfg_path, secret_store_override)
+    _set_secret_store_config(cfg_path, secret_store)
+    env_value = os.environ.get(api_key_env, "").strip()
+    secret_value = _read_secret_api_key(secret_store, api_key_env)
+    provided = api_key.strip() if isinstance(api_key, str) else ""
+
+    selected_key = provided or env_value or secret_value
+    if not selected_key and no_prompt:
+        print(
+            f"API key for {provider} is required in non-interactive mode.\n"
+            f"Provide --api-key or set {api_key_env}.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not selected_key:
+        selected_key = getpass.getpass(f"Enter {api_key_env}: ").strip()
+        if not selected_key:
+            print(f"{api_key_env} was empty; onboarding canceled.", file=sys.stderr)
+            return 1
+
+    should_store = not no_store_api_key
+    if not no_prompt and not no_store_api_key:
+        should_store = _prompt_yes_no(
+            f"Store {api_key_env} in local secret store ({secret_store})?",
+            default=True,
+            non_interactive=no_prompt,
+        )
+
+    if should_store:
+        _write_secret_api_key(secret_store, api_key_env, selected_key)
+        print(f"[ok] stored {api_key_env} in local secret store: {secret_store}")
+    else:
+        print(f"[warn] {api_key_env} not stored; keep it exported in your shell.")
+
+    _set_reasoning_config(cfg_path, provider, model)
+    print("[ok] reasoning provider configured")
+    print(f"     provider: {provider}")
+    print(f"     model:    {model or _default_model_for_provider(provider)}")
+    return 0
+
+
 def _resolve_openclaw_auth_store(openclaw_agent: str, override_path: Optional[str]) -> Path:
     if override_path:
         return Path(override_path).expanduser()
@@ -445,14 +1492,6 @@ def cmd_doctor(args: argparse.Namespace) -> int:
         else:
             print(f"[warn] optional command not found: {name}")
 
-    anth = os.environ.get("ANTHROPIC_API_KEY")
-    oai = os.environ.get("OPENAI_API_KEY")
-    if anth or oai:
-        print("[ok] at least one API auth env var is present")
-    else:
-        print("[warn] no API key env vars found (ANTHROPIC_API_KEY / OPENAI_API_KEY)")
-        print("       subscription OAuth profiles may still be used depending on your runtime setup")
-
     cfg = _load_json(cfg_path)
     if not cfg:
         print(f"[warn] launcher config not found yet: {cfg_path}")
@@ -460,10 +1499,34 @@ def cmd_doctor(args: argparse.Namespace) -> int:
         print(f"       run `{launcher} init` or `{launcher} onboard`")
     else:
         cfg = _normalize_config(cfg)
+        reasoning_cfg = cfg.get("reasoning", {})
+        reasoning_provider = ""
+        if isinstance(reasoning_cfg, dict):
+            reasoning_provider = str(reasoning_cfg.get("provider", "")).strip()
+            print(
+                "[ok] reasoning config: "
+                f"{reasoning_cfg.get('provider', '?')}/{reasoning_cfg.get('model', '?')}"
+            )
+
+        secret_store = _resolve_secret_store(cfg_path, None)
+        anth = os.environ.get("ANTHROPIC_API_KEY", "").strip() or _read_secret_api_key(secret_store, "ANTHROPIC_API_KEY")
+        oai = os.environ.get("OPENAI_API_KEY", "").strip() or _read_secret_api_key(secret_store, "OPENAI_API_KEY")
+        openrouter = os.environ.get("OPENROUTER_API_KEY", "").strip() or _read_secret_api_key(
+            secret_store, "OPENROUTER_API_KEY"
+        )
+        if anth or oai or openrouter:
+            print("[ok] at least one API auth credential is available (env or secret store)")
+        else:
+            print("[warn] no API credentials found (env or secret store)")
+            print("       expected: ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY")
+
         active = cfg.get("auth", {}).get("active_profile")
         if not isinstance(active, dict):
-            print("[warn] no linked OAuth profile in launcher config")
-            print(f"       run `{_launcher_hint()} onboard`")
+            if reasoning_provider == "openai-codex":
+                print("[warn] no linked OAuth profile in launcher config")
+                print(f"       run `{_launcher_hint()} onboard --provider openai-codex`")
+            else:
+                print("[info] no linked OAuth profile (not required for API-key providers)")
         else:
             credential, error = _read_linked_credential(active)
             if credential is None:
@@ -510,30 +1573,94 @@ def cmd_onboard(args: argparse.Namespace) -> int:
         print(f"[ok] using existing launcher config: {cfg_path}")
     print(f"[ok] state directory ready: {state_dir}")
     print("")
-    print("Auth flow selected: Gaia native profile store + Codex web OAuth broker")
-    print("This opens a browser/device auth flow through Codex CLI.")
-    print("Tokens are copied into Gaia local auth store (outside this repository).")
-    sys.stdout.flush()
-
-    proceed = "y"
-    if not args.yes:
-        proceed = input("Start web OAuth login now? [Y/n]: ").strip().lower()
-    if proceed in ("n", "no"):
-        print("Skipped OAuth login. Run this later:")
-        print(f"  {_launcher_hint()} auth login --provider openai-codex")
-        return 0
+    provider = (args.provider or "").strip().lower()
+    if not provider:
+        provider = _prompt_choice(
+            "Choose provider to connect:",
+            [
+                ("openrouter", "OpenRouter (API key + model selection)"),
+                ("openai", "OpenAI (API key)"),
+                ("anthropic", "Anthropic (API key)"),
+                ("openai-codex", "OpenAI Codex (OAuth via Codex CLI)"),
+            ],
+            default_index=0,
+            non_interactive=args.yes,
+        )
+
+    if provider not in ONBOARD_PROVIDER_CHOICES:
+        print(f"Unsupported onboarding provider: {provider}", file=sys.stderr)
+        print(f"Supported providers: {', '.join(ONBOARD_PROVIDER_CHOICES)}", file=sys.stderr)
+        return 1
+    print(f"[ok] selected provider: {provider}")
+
+    if provider == "openai-codex":
+        print("OAuth flow selected: OpenAI Codex via Codex CLI")
+        print("This opens browser/device auth and links profile into Gaia local auth store.")
+        should_start = _prompt_yes_no(
+            "Start OpenAI Codex OAuth login now?",
+            default=True,
+            non_interactive=args.yes,
+        )
+        if not should_start:
+            print("Skipped OAuth login. Run this later:")
+            print(f"  {_launcher_hint()} auth login --provider openai-codex")
+            return 0
+        login_args = argparse.Namespace(
+            config=str(cfg_path),
+            provider="openai-codex",
+            source="codex-cli",
+            codex_auth_path=args.codex_auth_path,
+            gaia_auth_store=args.gaia_auth_store,
+            openclaw_agent="main",
+            openclaw_auth_store=None,
+            no_prompt=True,
+            profile_id=None,
+        )
+        return cmd_auth_login(login_args)
 
-    login_args = argparse.Namespace(
-        config=str(cfg_path),
-        provider="openai-codex",
-        source="codex-cli",
-        codex_auth_path=args.codex_auth_path,
-        gaia_auth_store=args.gaia_auth_store,
-        openclaw_agent="main",
-        openclaw_auth_store=None,
-        no_prompt=True,
+    api_key_env_by_provider = {
+        "openrouter": "OPENROUTER_API_KEY",
+        "openai": "OPENAI_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+    }
+    api_key_env = api_key_env_by_provider.get(provider, "")
+    if not api_key_env:
+        print(f"Provider is not configured for API-key onboarding: {provider}", file=sys.stderr)
+        return 1
+
+    provider_model: Optional[str] = args.model
+    if provider == "openrouter":
+        seed_key = (
+            (args.api_key.strip() if isinstance(args.api_key, str) else "")
+            or os.environ.get(api_key_env, "").strip()
+            or _read_secret_api_key(_resolve_secret_store(cfg_path, args.secret_store), api_key_env)
+        )
+        provider_model = _select_openrouter_model(
+            api_key=seed_key,
+            explicit_model=args.model,
+            non_interactive=args.yes,
+        )
+    elif not provider_model or not provider_model.strip():
+        provider_model = _default_model_for_provider(provider)
+
+    rc = _configure_api_key_provider(
+        cfg_path=cfg_path,
+        provider=provider,
+        api_key_env=api_key_env,
+        model=provider_model,
+        api_key=args.api_key,
+        secret_store_override=args.secret_store,
+        no_prompt=args.yes,
+        no_store_api_key=args.no_store_api_key,
     )
-    return cmd_auth_login(login_args)
+    if rc != 0:
+        return rc
+
+    print("")
+    print("Onboarding complete.")
+    print(f"Next: {_launcher_hint()} doctor")
+    print(f"Then: {_launcher_hint()} run --mode single --dry-run")
+    return 0
 
 
 def cmd_auth_login(args: argparse.Namespace) -> int:
@@ -695,7 +1822,14 @@ def cmd_auth_status(args: argparse.Namespace) -> int:
     cfg = _normalize_config(cfg)
     active = cfg.get("auth", {}).get("active_profile")
     if not isinstance(active, dict):
+        reasoning_cfg = cfg.get("reasoning", {})
+        reasoning_provider = ""
+        if isinstance(reasoning_cfg, dict):
+            reasoning_provider = str(reasoning_cfg.get("provider", "")).strip()
         print("No linked auth profile in launcher config.")
+        if reasoning_provider in ("openrouter", "openai", "anthropic"):
+            print("This is expected when using API-key providers.")
+            return 0
         print(f"Run: {_launcher_hint()} auth login --provider openai-codex")
         return 1
 
@@ -729,8 +1863,1028 @@ def cmd_auth_status(args: argparse.Namespace) -> int:
     return 0
 
 
+def _print_chat_help() -> None:
+    print("Chat commands:")
+    print("  /help      Show this help")
+    print("  /session   Show current session id")
+    print("  /exit      Exit chat")
+
+
+def cmd_chat(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    session_dir = _resolve_session_dir(cfg, args.session_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+
+    provider, model = _resolve_runtime_provider(cfg)
+    sessions_cfg = cfg.get("sessions", {})
+    sessions_cfg = sessions_cfg if isinstance(sessions_cfg, dict) else {}
+    configured_max_turns = sessions_cfg.get("max_context_turns", DEFAULT_SESSION_CONTEXT_TURNS)
+    max_turns = args.max_context_turns if args.max_context_turns else configured_max_turns
+    if not isinstance(max_turns, int) or max_turns < 2:
+        max_turns = DEFAULT_SESSION_CONTEXT_TURNS
+
+    session: Optional[Dict[str, Any]] = None
+    if args.resume:
+        target_session_id = _resolve_resume_session_id(session_dir, str(args.resume))
+        if not target_session_id:
+            print("No session available to resume.", file=sys.stderr)
+            return 1
+        session = _load_session(session_dir, target_session_id)
+        if session is None:
+            print(f"Session not found: {target_session_id}", file=sys.stderr)
+            return 1
+        print(f"Resumed session: {target_session_id}")
+    else:
+        session = _create_session(provider=provider, model=model)
+        _save_session(session_dir, session)
+        print(f"Started session: {session['id']}")
+
+    assert session is not None
+    print(f"Provider: {provider} | Model: {model}")
+    print("Type /help for commands.")
+
+    while True:
+        try:
+            raw = input("you> ")
+        except EOFError:
+            print("")
+            break
+        except KeyboardInterrupt:
+            print("")
+            break
+
+        user_input = raw.strip()
+        if not user_input:
+            continue
+        if user_input in ("/exit", "exit", "quit"):
+            break
+        if user_input in ("/help", "help"):
+            _print_chat_help()
+            continue
+        if user_input == "/session":
+            print(session["id"])
+            continue
+
+        capture_intent = _captures_note_intent(user_input)
+        if capture_intent is not None:
+            captured_text, as_task = capture_intent
+            if not captured_text:
+                guidance = "Provide text after the capture command, for example: capture this as a note: draft agenda"
+                print(f"gaia> {guidance}")
+                continue
+
+            turn_start = time.perf_counter()
+            allowed, permission_level = _enforce_capability(
+                cfg=cfg,
+                capability="file_write",
+                input_summary=user_input,
+                trace_dir=trace_dir,
+                non_interactive=False,
+            )
+            if not allowed:
+                blocked_reply = "Action blocked by capability policy."
+                print(f"gaia> {blocked_reply}")
+                timestamp = datetime.now(timezone.utc).isoformat()
+                session["turns"].append({"role": "user", "content": user_input, "timestamp": timestamp})
+                session["turns"].append({"role": "assistant", "content": blocked_reply, "timestamp": timestamp})
+                session["updated_at"] = timestamp
+                _save_session(session_dir, session)
+                _write_action_trace(
+                    trace_dir=trace_dir,
+                    action_type="chat_turn",
+                    input_summary=user_input,
+                    output_summary=blocked_reply,
+                    duration_ms=(time.perf_counter() - turn_start) * 1000,
+                    permission_level=permission_level,
+                    status="blocked",
+                    metadata={"session_id": session["id"], "provider": provider, "model": model},
+                )
+                continue
+
+            if as_task:
+                items = _load_records(_tasks_path(storage_dir))
+                record = _create_task_record(captured_text, source="chat")
+                items.append(record)
+                _save_records(_tasks_path(storage_dir), items)
+                reply = f"Captured task {record['id']}"
+                action_type = "task_capture"
+            else:
+                items = _load_records(_notes_path(storage_dir))
+                record = _create_note_record(captured_text, source="chat")
+                items.append(record)
+                _save_records(_notes_path(storage_dir), items)
+                reply = f"Captured note {record['id']}"
+                action_type = "note_capture"
+
+            print(f"gaia> {reply}")
+            timestamp = datetime.now(timezone.utc).isoformat()
+            session["turns"].append({"role": "user", "content": user_input, "timestamp": timestamp})
+            session["turns"].append({"role": "assistant", "content": reply, "timestamp": timestamp})
+            session["updated_at"] = timestamp
+            _save_session(session_dir, session)
+            _write_action_trace(
+                trace_dir=trace_dir,
+                action_type=action_type,
+                input_summary=user_input,
+                output_summary=reply,
+                duration_ms=(time.perf_counter() - turn_start) * 1000,
+                permission_level=permission_level,
+                metadata={"session_id": session["id"], "source": "chat"},
+            )
+            continue
+
+        capability, confirm_prompt = _infer_capability_from_prompt(user_input)
+        turn_start = time.perf_counter()
+        allowed, permission_level = _enforce_capability(
+            cfg=cfg,
+            capability=capability,
+            input_summary=user_input,
+            trace_dir=trace_dir,
+            non_interactive=False,
+            prompt=confirm_prompt,
+        )
+        if not allowed:
+            blocked_reply = "Action blocked by capability policy."
+            print(f"gaia> {blocked_reply}")
+            timestamp = datetime.now(timezone.utc).isoformat()
+            session["turns"].append({"role": "user", "content": user_input, "timestamp": timestamp})
+            session["turns"].append({"role": "assistant", "content": blocked_reply, "timestamp": timestamp})
+            session["updated_at"] = timestamp
+            _save_session(session_dir, session)
+            _write_action_trace(
+                trace_dir=trace_dir,
+                action_type="chat_turn",
+                input_summary=user_input,
+                output_summary=blocked_reply,
+                duration_ms=(time.perf_counter() - turn_start) * 1000,
+                permission_level=permission_level,
+                status="blocked",
+                metadata={"session_id": session["id"], "provider": provider, "model": model},
+            )
+            continue
+
+        messages = _build_context_messages(session["turns"], user_input, max_turns=max_turns)
+        status = "ok"
+        try:
+            assistant_reply = _reasoning_response(
+                provider=provider,
+                model=model,
+                messages=messages,
+                cfg_path=cfg_path,
+                secret_store_override=args.secret_store,
+            )
+        except ProviderTokenLimitError:
+            compact_turns = session["turns"][-max(4, max_turns // 2) :]
+            compact_messages = _build_context_messages(
+                compact_turns,
+                user_input,
+                max_turns=max(4, max_turns // 2),
+            )
+            try:
+                assistant_reply = _reasoning_response(
+                    provider=provider,
+                    model=model,
+                    messages=compact_messages,
+                    cfg_path=cfg_path,
+                    secret_store_override=args.secret_store,
+                )
+                status = "ok"
+            except ProviderError as exc:
+                assistant_reply = f"[provider-error] {exc}"
+                status = "error"
+        except ProviderError as exc:
+            assistant_reply = f"[provider-error] {exc}"
+            status = "error"
+
+        print(f"gaia> {assistant_reply}")
+        timestamp = datetime.now(timezone.utc).isoformat()
+        session["turns"].append({"role": "user", "content": user_input, "timestamp": timestamp})
+        session["turns"].append({"role": "assistant", "content": assistant_reply, "timestamp": timestamp})
+        session["updated_at"] = timestamp
+        _save_session(session_dir, session)
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="chat_turn",
+            input_summary=user_input,
+            output_summary=assistant_reply,
+            duration_ms=(time.perf_counter() - turn_start) * 1000,
+            permission_level=permission_level,
+            status=status,
+            metadata={
+                "session_id": session["id"],
+                "provider": provider,
+                "model": model,
+                "context_messages": len(messages),
+            },
+        )
+
+    _save_session(session_dir, session)
+    print(f"Session saved: {session['id']}")
+    return 0
+
+
+def cmd_config_get(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg)
+    start = time.perf_counter()
+    key = str(args.key).strip().lower()
+    path = _config_path_for_key(key)
+    if path is None:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="config_get",
+            input_summary=f"key={key}",
+            output_summary="unsupported key",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+            status="error",
+        )
+        print(
+            "Unsupported key. Supported keys: "
+            + ", ".join(sorted(PROFILE_KEY_MAP.keys())),
+            file=sys.stderr,
+        )
+        return 1
+
+    value = _get_nested_value(cfg, path)
+    if value is None:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="config_get",
+            input_summary=f"key={key}",
+            output_summary="empty value",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+        )
+        print("", end="")
+        return 0
+    if isinstance(value, (dict, list)):
+        print(json.dumps(value, indent=2))
+    else:
+        print(value)
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="config_get",
+        input_summary=f"key={key}",
+        output_summary=f"value={_summarize_text(value)}",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level="safe",
+    )
+    return 0
+
+
+def cmd_config_set(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg)
+    start = time.perf_counter()
+    key = str(args.key).strip().lower()
+    path = _config_path_for_key(key)
+    if path is None:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="config_set",
+            input_summary=f"key={key}",
+            output_summary="unsupported key",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+            status="error",
+        )
+        print(
+            "Unsupported key. Supported keys: "
+            + ", ".join(sorted(PROFILE_KEY_MAP.keys())),
+            file=sys.stderr,
+        )
+        return 1
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_write",
+        input_summary=f"config set {key}",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="config_set",
+            input_summary=f"key={key}",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    normalized, error = _normalize_profile_value(key, str(args.value))
+    if error:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="config_set",
+            input_summary=f"key={key}",
+            output_summary=error,
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="error",
+        )
+        print(error, file=sys.stderr)
+        return 1
+    assert normalized is not None
+    _set_nested_value(cfg, path, normalized)
+
+    if key in ("provider", "default_provider"):
+        reasoning = cfg.setdefault("reasoning", {})
+        if not isinstance(reasoning, dict):
+            reasoning = {}
+            cfg["reasoning"] = reasoning
+        reasoning["provider"] = normalized
+        reasoning["model"] = _default_model_for_provider(normalized)
+
+    _write_json(cfg_path, _normalize_config(cfg))
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="config_set",
+        input_summary=f"key={key}",
+        output_summary=f"set to {normalized}",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    print(f"{path[0]}.{path[1]}={normalized}")
+    return 0
+
+
+def _log_permission_decision(
+    trace_dir: Path,
+    capability: str,
+    input_summary: str,
+    allowed: bool,
+    permission_level: str,
+    reason: str,
+    duration_ms: float,
+) -> None:
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="permission_decision",
+        input_summary=f"{capability}: {input_summary}",
+        output_summary=reason,
+        duration_ms=duration_ms,
+        permission_level=permission_level,
+        status="ok" if allowed else "blocked",
+        metadata={"capability": capability, "allowed": allowed},
+    )
+
+
+def _enforce_capability(
+    cfg: Dict[str, Any],
+    capability: str,
+    input_summary: str,
+    trace_dir: Path,
+    non_interactive: bool = False,
+    prompt: Optional[str] = None,
+) -> Tuple[bool, str]:
+    start = time.perf_counter()
+    allowed, level, reason = _check_capability_permission(
+        cfg=cfg,
+        capability=capability,
+        user_prompt=prompt,
+        non_interactive=non_interactive,
+    )
+    duration_ms = (time.perf_counter() - start) * 1000
+    _log_permission_decision(
+        trace_dir=trace_dir,
+        capability=capability,
+        input_summary=input_summary,
+        allowed=allowed,
+        permission_level=level,
+        reason=reason,
+        duration_ms=duration_ms,
+    )
+    return allowed, level
+
+
+def cmd_capability_list(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_read",
+        input_summary="capability list",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="capability_list",
+            input_summary="capability list",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    registry = _capability_registry(cfg)
+    for capability in sorted(registry):
+        print(f"{capability} {registry[capability]}")
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="capability_list",
+        input_summary="capability list",
+        output_summary=f"{len(registry)} capabilities",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    return 0
+
+
+def cmd_capability_set(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg)
+    start = time.perf_counter()
+    capability = str(args.capability).strip()
+    if not capability:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="capability_set",
+            input_summary="capability empty",
+            output_summary="capability cannot be empty",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+            status="error",
+        )
+        print("capability cannot be empty", file=sys.stderr)
+        return 1
+
+    level = str(args.level).strip().lower()
+    if level not in PERMISSION_LEVEL_CHOICES:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="capability_set",
+            input_summary=f"{capability}={level}",
+            output_summary="invalid level",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+            status="error",
+        )
+        print(
+            f"Invalid level '{args.level}'. "
+            f"Expected one of: {', '.join(PERMISSION_LEVEL_CHOICES)}.",
+            file=sys.stderr,
+        )
+        return 1
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_write",
+        input_summary=f"capability set {capability}",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="capability_set",
+            input_summary=f"{capability}={level}",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    capabilities = cfg.setdefault("capabilities", {})
+    if not isinstance(capabilities, dict):
+        capabilities = {}
+        cfg["capabilities"] = capabilities
+    overrides = capabilities.setdefault("overrides", {})
+    if not isinstance(overrides, dict):
+        overrides = {}
+        capabilities["overrides"] = overrides
+    overrides[capability] = level
+    _write_json(cfg_path, _normalize_config(cfg))
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="capability_set",
+        input_summary=f"{capability}={level}",
+        output_summary="override updated",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    print(f"capabilities.overrides.{capability}={level}")
+    return 0
+
+
+def cmd_traces(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    traces = _read_action_traces(trace_dir)
+    if args.type:
+        wanted = str(args.type).strip()
+        traces = [item for item in traces if str(item.get("action_type", "")).strip() == wanted]
+
+    if args.last and args.last > 0:
+        traces = traces[-args.last :]
+
+    if not traces:
+        print(f"No traces found in {trace_dir}")
+        return 0
+
+    for item in traces:
+        ts = str(item.get("timestamp", "?")).strip()
+        action_type = str(item.get("action_type", "?")).strip()
+        level = str(item.get("permission_level", "?")).strip()
+        status = str(item.get("status", "?")).strip()
+        summary = _summarize_text(item.get("output_summary", ""), max_chars=100)
+        print(f"{ts} | {action_type:<20} | {level:<9} | {status:<7} | {summary}")
+    return 0
+
+
+def cmd_note(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    start = time.perf_counter()
+    text = str(args.text).strip()
+    if not text:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="note_capture",
+            input_summary="empty input",
+            output_summary="text cannot be empty",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level="safe",
+            status="error",
+        )
+        print("note text cannot be empty", file=sys.stderr)
+        return 1
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_write",
+        input_summary=f"note capture: {text}",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="note_capture",
+            input_summary=text,
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    if args.task:
+        path = _tasks_path(storage_dir)
+        items = _load_records(path)
+        record = _create_task_record(text, source="cli")
+        items.append(record)
+        _save_records(path, items)
+        action_type = "task_capture"
+        print(f"{record['id']} open {record['text']}")
+    else:
+        path = _notes_path(storage_dir)
+        items = _load_records(path)
+        record = _create_note_record(text, source="cli")
+        items.append(record)
+        _save_records(path, items)
+        action_type = "note_capture"
+        print(f"{record['id']} {record['text']}")
+
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type=action_type,
+        input_summary=text,
+        output_summary=f"saved {record['id']}",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+        metadata={"source": "cli"},
+    )
+    return 0
+
+
+def cmd_tasks(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_read",
+        input_summary="list tasks",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="tasks_list",
+            input_summary="tasks list",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    tasks = _load_records(_tasks_path(storage_dir))
+    status = str(args.status).strip().lower()
+    if status not in ("open", "done", "all"):
+        status = "open"
+
+    if status != "all":
+        tasks = [item for item in tasks if str(item.get("status", "open")).strip().lower() == status]
+
+    query = str(args.q or "").strip().lower()
+    if query:
+        tasks = [item for item in tasks if query in str(item.get("text", "")).lower()]
+
+    since_dt = None
+    if args.since:
+        since_dt = _parse_since_date(str(args.since))
+        if since_dt is None:
+            _write_action_trace(
+                trace_dir=trace_dir,
+                action_type="tasks_list",
+                input_summary=f"since={args.since}",
+                output_summary="invalid --since date",
+                duration_ms=(time.perf_counter() - start) * 1000,
+                permission_level=permission_level,
+                status="error",
+            )
+            print("Invalid --since value. Use YYYY-MM-DD.", file=sys.stderr)
+            return 1
+        tasks = [
+            item
+            for item in tasks
+            if str(item.get("created_at", ""))[:10] >= since_dt.date().isoformat()
+        ]
+
+    tasks.sort(key=lambda item: str(item.get("created_at", "")))
+    if not tasks:
+        print("No tasks found.")
+    else:
+        for task in tasks:
+            task_id = str(task.get("id", "?"))
+            task_status = str(task.get("status", "open"))
+            created = str(task.get("created_at", "?"))
+            text = str(task.get("text", ""))
+            print(f"{task_id} {task_status:<4} {created} {text}")
+
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="tasks_list",
+        input_summary=f"status={status} query={query}",
+        output_summary=f"{len(tasks)} tasks",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    return 0
+
+
+def cmd_summarize(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="network_request",
+        input_summary="summarize urls",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="summarize_url",
+            input_summary=" ".join(args.urls),
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    summaries = _load_records(_summaries_path(storage_dir))
+    failed = 0
+    for raw_url in args.urls:
+        url = str(raw_url).strip()
+        if not url:
+            continue
+
+        item_start = time.perf_counter()
+        try:
+            title, body_text = _fetch_url_content(url)
+            points = _key_points_from_text(body_text)
+        except ProviderError as exc:
+            failed += 1
+            message = f"[warn] {exc}"
+            print(message, file=sys.stderr)
+            _write_action_trace(
+                trace_dir=trace_dir,
+                action_type="summarize_url",
+                input_summary=url,
+                output_summary=message,
+                duration_ms=(time.perf_counter() - item_start) * 1000,
+                permission_level=permission_level,
+                status="error",
+            )
+            continue
+
+        record = {
+            "id": _new_record_id("s"),
+            "url": url,
+            "title": title or "Untitled",
+            "key_points": points,
+            "date_summarized": datetime.now(timezone.utc).isoformat(),
+            "source": "cli",
+        }
+        summaries.append(record)
+        print(f"- {record['title']}")
+        print(f"  URL: {url}")
+        print(f"  Date: {record['date_summarized']}")
+        for point in points:
+            print(f"  * {point}")
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="summarize_url",
+            input_summary=url,
+            output_summary=f"saved summary {record['id']}",
+            duration_ms=(time.perf_counter() - item_start) * 1000,
+            permission_level=permission_level,
+            metadata={"summary_id": record["id"]},
+        )
+
+    _save_records(_summaries_path(storage_dir), summaries)
+    if failed and failed == len(args.urls):
+        return 1
+    return 0
+
+
+def cmd_summaries(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_read",
+        input_summary="list summaries",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="summaries_list",
+            input_summary="summaries list",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    summaries = _load_records(_summaries_path(storage_dir))
+    summaries.sort(key=lambda item: str(item.get("date_summarized", "")), reverse=True)
+    if args.last and args.last > 0:
+        summaries = summaries[: args.last]
+
+    if not summaries:
+        print("No summaries found.")
+    else:
+        for item in summaries:
+            summary_id = str(item.get("id", "?"))
+            title = str(item.get("title", "Untitled"))
+            url = str(item.get("url", ""))
+            date_summarized = str(item.get("date_summarized", ""))
+            print(f"{summary_id} {date_summarized} {title} ({url})")
+
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="summaries_list",
+        input_summary=f"last={args.last}",
+        output_summary=f"{len(summaries)} summaries",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    return 0
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    plans_path = _plans_path(storage_dir)
+    plans = _load_records(plans_path)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_write",
+        input_summary="plan create/update",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="plan_create",
+            input_summary="plan command",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    if args.edit:
+        plan_id = str(args.edit).strip()
+        if not plan_id:
+            print("--edit requires a plan id.", file=sys.stderr)
+            return 1
+        target = None
+        for item in plans:
+            if str(item.get("id", "")).strip() == plan_id:
+                target = item
+                break
+        if target is None:
+            print(f"Plan not found: {plan_id}", file=sys.stderr)
+            return 1
+
+        refinement = str(args.update or "").strip()
+        if not refinement:
+            if not sys.stdin.isatty():
+                print("Provide --update in non-interactive mode.", file=sys.stderr)
+                return 1
+            refinement = input("Refinement request: ").strip()
+        if not refinement:
+            print("Refinement text cannot be empty.", file=sys.stderr)
+            return 1
+
+        steps = _generate_plan_steps(str(target.get("objective", "")), refinement=refinement)
+        target["steps"] = steps
+        target["dependencies"] = _derive_plan_dependencies(str(target.get("objective", "")))
+        target["estimated_complexity"] = _estimate_plan_complexity(str(target.get("objective", "")))
+        revisions = target.setdefault("revisions", [])
+        if not isinstance(revisions, list):
+            revisions = []
+            target["revisions"] = revisions
+        revisions.append(
+            {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "refinement": refinement,
+            }
+        )
+        target["updated_at"] = datetime.now(timezone.utc).isoformat()
+        _save_records(plans_path, plans)
+        print(f"Updated plan {plan_id}")
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="plan_update",
+            input_summary=f"plan_id={plan_id}",
+            output_summary="plan updated",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            metadata={"plan_id": plan_id},
+        )
+        return 0
+
+    goal = str(args.goal or "").strip()
+    if not goal:
+        print("Goal is required. Example: gaia plan \"Set up a personal knowledge base\".", file=sys.stderr)
+        return 1
+
+    plan_id = _new_record_id("p")
+    now = datetime.now(timezone.utc).isoformat()
+    plan_record = {
+        "id": plan_id,
+        "objective": goal,
+        "steps": _generate_plan_steps(goal),
+        "estimated_complexity": _estimate_plan_complexity(goal),
+        "dependencies": _derive_plan_dependencies(goal),
+        "created_at": now,
+        "updated_at": now,
+        "revisions": [{"timestamp": now, "refinement": "initial"}],
+        "source": "cli",
+    }
+    plans.append(plan_record)
+    _save_records(plans_path, plans)
+    print(f"Plan {plan_id}")
+    print(f"Objective: {plan_record['objective']}")
+    print(f"Complexity: {plan_record['estimated_complexity']}")
+    print("Dependencies:")
+    for dependency in plan_record["dependencies"]:
+        print(f"- {dependency}")
+    print("Steps:")
+    for idx, step in enumerate(plan_record["steps"], start=1):
+        print(f"{idx}. {step}")
+
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="plan_create",
+        input_summary=goal,
+        output_summary=f"created {plan_id}",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+        metadata={"plan_id": plan_id},
+    )
+    return 0
+
+
+def cmd_plans(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config).expanduser()
+    cfg = _ensure_config_exists(cfg_path)
+    trace_dir = _resolve_trace_dir(cfg, args.trace_dir)
+    storage_dir = _resolve_storage_dir(cfg, args.storage_dir)
+    storage_dir.mkdir(parents=True, exist_ok=True)
+    start = time.perf_counter()
+
+    allowed, permission_level = _enforce_capability(
+        cfg=cfg,
+        capability="file_read",
+        input_summary="list plans",
+        trace_dir=trace_dir,
+        non_interactive=False,
+    )
+    if not allowed:
+        _write_action_trace(
+            trace_dir=trace_dir,
+            action_type="plans_list",
+            input_summary="plans list",
+            output_summary="blocked by permission policy",
+            duration_ms=(time.perf_counter() - start) * 1000,
+            permission_level=permission_level,
+            status="blocked",
+        )
+        print("Action blocked by capability policy.", file=sys.stderr)
+        return 1
+
+    plans = _load_records(_plans_path(storage_dir))
+    plans.sort(key=lambda item: str(item.get("updated_at", "")), reverse=True)
+    if args.last and args.last > 0:
+        plans = plans[: args.last]
+
+    if not plans:
+        print("No plans found.")
+    else:
+        for plan in plans:
+            plan_id = str(plan.get("id", "?"))
+            objective = _summarize_text(plan.get("objective", ""), max_chars=100)
+            complexity = str(plan.get("estimated_complexity", "?"))
+            updated_at = str(plan.get("updated_at", ""))
+            print(f"{plan_id} {complexity:<6} {updated_at} {objective}")
+
+    _write_action_trace(
+        trace_dir=trace_dir,
+        action_type="plans_list",
+        input_summary=f"last={args.last}",
+        output_summary=f"{len(plans)} plans",
+        duration_ms=(time.perf_counter() - start) * 1000,
+        permission_level=permission_level,
+    )
+    return 0
+
+
 def cmd_run(args: argparse.Namespace) -> int:
     cfg_path = Path(args.config).expanduser()
+    state_dir = Path(args.state_dir).expanduser()
     try:
         cfg = _ensure_config_exists(cfg_path)
     except PermissionError:
@@ -740,6 +2894,15 @@ def cmd_run(args: argparse.Namespace) -> int:
             file=sys.stderr,
         )
         return 1
+    try:
+        state_dir.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        print(
+            "Cannot create runtime state directory due to permissions. "
+            "Set GAIA_ASSISTANT_HOME or pass --state-dir to a writable path.",
+            file=sys.stderr,
+        )
+        return 1
 
     cmd = [
         "python3",
@@ -755,8 +2918,37 @@ def cmd_run(args: argparse.Namespace) -> int:
         cmd.append("--verbose")
 
     env = os.environ.copy()
+    secret_store = _resolve_secret_store(cfg_path, args.secret_store)
+    loaded_from_secret: List[str] = []
+    for env_var in ("ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY"):
+        if env.get(env_var, "").strip():
+            continue
+        stored = _read_secret_api_key(secret_store, env_var)
+        if stored:
+            env[env_var] = stored
+            loaded_from_secret.append(env_var)
+
+    reasoning_cfg = cfg.get("reasoning", {})
+    reasoning_cfg = reasoning_cfg if isinstance(reasoning_cfg, dict) else {}
+    profile_cfg = cfg.get("profile", {})
+    profile_cfg = profile_cfg if isinstance(profile_cfg, dict) else {}
+    profile_provider = str(profile_cfg.get("default_provider", "")).strip()
+    configured_provider = str(reasoning_cfg.get("provider", "")).strip()
+    configured_model = str(reasoning_cfg.get("model", "")).strip()
+    effective_provider = str(args.reasoning_provider or configured_provider or profile_provider).strip()
+    effective_model = str(args.reasoning_model or configured_model).strip()
+
     if args.track != "auto":
         env["GAIA_ACTIVE_TRACK_OVERRIDE"] = args.track
+    if effective_provider:
+        env["GAIA_REASONING_PROVIDER"] = effective_provider
+    if effective_model:
+        env["GAIA_REASONING_MODEL"] = effective_model
+    env["GAIA_AGENT_MEMORY_DIR"] = str(state_dir)
+    env["GAIA_ASSISTANT_VERBOSITY"] = str(profile_cfg.get("verbosity", "balanced")).strip() or "balanced"
+    profile_tz = str(profile_cfg.get("timezone", "UTC")).strip()
+    if profile_tz:
+        env["TZ"] = profile_tz
 
     runtime_cfg = cfg.get("runtime", {})
     if args.mode == "continuous" and "interval_minutes" in runtime_cfg:
@@ -765,6 +2957,21 @@ def cmd_run(args: argparse.Namespace) -> int:
         print(f"Running Gaia assistant in {args.mode} mode")
     if args.track != "auto":
         print(f"Track override: {args.track}")
+    if args.reasoning_provider:
+        print(f"Reasoning provider override: {args.reasoning_provider}")
+    elif effective_provider:
+        print(f"Reasoning provider: {effective_provider} (from launcher config)")
+    if args.reasoning_model:
+        print(f"Reasoning model override: {args.reasoning_model}")
+    elif effective_model:
+        print(f"Reasoning model: {effective_model} (from launcher config)")
+    profile_name = str(profile_cfg.get("name", "")).strip()
+    if profile_name:
+        print(f"Profile name: {profile_name}")
+    print(f"Profile verbosity: {env['GAIA_ASSISTANT_VERBOSITY']}")
+    print(f"Profile timezone: {profile_tz or 'UTC'}")
+    if loaded_from_secret:
+        print(f"Loaded API credentials from secret store: {', '.join(loaded_from_secret)}")
 
     active_profile = cfg.get("auth", {}).get("active_profile")
     if isinstance(active_profile, dict):
@@ -790,7 +2997,7 @@ def build_parser() -> argparse.ArgumentParser:
     init.add_argument("--force", action="store_true", help="Overwrite config if it exists")
     init.set_defaults(func=cmd_init)
 
-    onboard = sub.add_parser("onboard", help="Guided onboarding with Gaia-native OAuth linking")
+    onboard = sub.add_parser("onboard", help="Guided provider onboarding (OAuth or API key)")
     onboard.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
     onboard.add_argument("--state-dir", default=str(DEFAULT_STATE_DIR), help="Local state directory")
     onboard.add_argument(
@@ -803,6 +3010,32 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Path to Codex auth.json (optional override)",
     )
+    onboard.add_argument(
+        "--provider",
+        choices=list(ONBOARD_PROVIDER_CHOICES),
+        default=None,
+        help="Provider to onboard (interactive if omitted)",
+    )
+    onboard.add_argument(
+        "--api-key",
+        default=None,
+        help="API key for API-key providers (openrouter/openai/anthropic)",
+    )
+    onboard.add_argument(
+        "--model",
+        default=None,
+        help="Reasoning model to set during onboarding",
+    )
+    onboard.add_argument(
+        "--secret-store",
+        default=None,
+        help="Path to local secrets.json store (optional override)",
+    )
+    onboard.add_argument(
+        "--no-store-api-key",
+        action="store_true",
+        help="Do not store API key in local secret store",
+    )
     onboard.add_argument("--yes", action="store_true", help="Skip onboarding confirmations")
     onboard.set_defaults(func=cmd_onboard)
 
@@ -810,6 +3043,97 @@ def build_parser() -> argparse.ArgumentParser:
     doctor.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
     doctor.set_defaults(func=cmd_doctor)
 
+    config = sub.add_parser("config", help="Read or write local assistant preferences")
+    config_sub = config.add_subparsers(dest="config_command", required=True)
+
+    config_set = config_sub.add_parser("set", help="Set a preference value")
+    config_set.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    config_set.add_argument("key", choices=sorted(PROFILE_KEY_MAP.keys()), help="Preference key")
+    config_set.add_argument("value", help="Preference value")
+    config_set.set_defaults(func=cmd_config_set)
+
+    config_get = config_sub.add_parser("get", help="Get a preference value")
+    config_get.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    config_get.add_argument("key", choices=sorted(PROFILE_KEY_MAP.keys()), help="Preference key")
+    config_get.set_defaults(func=cmd_config_get)
+
+    capability = sub.add_parser("capability", help="Inspect or override capability permissions")
+    capability_sub = capability.add_subparsers(dest="capability_command", required=True)
+
+    capability_list = capability_sub.add_parser("list", help="List effective capability levels")
+    capability_list.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    capability_list.set_defaults(func=cmd_capability_list)
+
+    capability_set = capability_sub.add_parser("set", help="Set local capability override")
+    capability_set.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    capability_set.add_argument("capability", help="Capability name (for example: shell_exec)")
+    capability_set.add_argument("level", choices=list(PERMISSION_LEVEL_CHOICES), help="Permission level")
+    capability_set.set_defaults(func=cmd_capability_set)
+
+    traces = sub.add_parser("traces", help="Show structured action traces")
+    traces.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    traces.add_argument("--trace-dir", default=None, help="Trace directory override")
+    traces.add_argument("--last", type=int, default=20, help="Number of recent trace entries to show")
+    traces.add_argument("--type", default=None, help="Filter by action type")
+    traces.set_defaults(func=cmd_traces)
+
+    chat = sub.add_parser("chat", help="Start an interactive Gaia chat session")
+    chat.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    chat.add_argument("--secret-store", default=None, help="Path to local secrets.json store (optional override)")
+    chat.add_argument("--session-dir", default=None, help="Session directory override")
+    chat.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    chat.add_argument("--trace-dir", default=None, help="Trace directory override")
+    chat.add_argument("--resume", default=None, help="Session id or 'last'")
+    chat.add_argument("--max-context-turns", type=int, default=None, help="Override max context turns")
+    chat.set_defaults(func=cmd_chat)
+
+    note = sub.add_parser("note", help="Capture a note or task")
+    note.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    note.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    note.add_argument("--trace-dir", default=None, help="Trace directory override")
+    note.add_argument("--task", action="store_true", help="Store as task instead of note")
+    note.add_argument("text", help="Note/task text")
+    note.set_defaults(func=cmd_note)
+
+    tasks = sub.add_parser("tasks", help="List saved tasks")
+    tasks.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    tasks.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    tasks.add_argument("--trace-dir", default=None, help="Trace directory override")
+    tasks.add_argument("--q", default=None, help="Filter tasks by keyword")
+    tasks.add_argument("--since", default=None, help="Filter tasks created since YYYY-MM-DD")
+    tasks.add_argument("--status", choices=["open", "done", "all"], default="open", help="Filter by task status")
+    tasks.set_defaults(func=cmd_tasks)
+
+    summarize = sub.add_parser("summarize", help="Fetch and summarize one or more URLs")
+    summarize.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    summarize.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    summarize.add_argument("--trace-dir", default=None, help="Trace directory override")
+    summarize.add_argument("urls", nargs="+", help="One or more URLs to summarize")
+    summarize.set_defaults(func=cmd_summarize)
+
+    summaries = sub.add_parser("summaries", help="List saved URL summaries")
+    summaries.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    summaries.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    summaries.add_argument("--trace-dir", default=None, help="Trace directory override")
+    summaries.add_argument("--last", type=int, default=20, help="Number of entries to show")
+    summaries.set_defaults(func=cmd_summaries)
+
+    plan = sub.add_parser("plan", help="Generate or refine an actionable plan from a goal")
+    plan.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    plan.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    plan.add_argument("--trace-dir", default=None, help="Trace directory override")
+    plan.add_argument("--edit", default=None, help="Existing plan id to refine")
+    plan.add_argument("--update", default=None, help="Refinement instructions for --edit")
+    plan.add_argument("goal", nargs="?", help="Goal description")
+    plan.set_defaults(func=cmd_plan)
+
+    plans = sub.add_parser("plans", help="List saved plans")
+    plans.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Config JSON path")
+    plans.add_argument("--storage-dir", default=None, help="Data storage directory override")
+    plans.add_argument("--trace-dir", default=None, help="Trace directory override")
+    plans.add_argument("--last", type=int, default=20, help="Number of entries to show")
+    plans.set_defaults(func=cmd_plans)
+
     auth = sub.add_parser("auth", help="Manage OAuth profile linkage for Gaia assistant")
     auth_sub = auth.add_subparsers(dest="auth_command", required=True)
 
@@ -876,8 +3200,25 @@ def build_parser() -> argparse.ArgumentParser:
 
     run = sub.add_parser("run", help="Run Gaia assistant loop")
     run.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Launcher config JSON path")
+    run.add_argument("--state-dir", default=str(DEFAULT_STATE_DIR), help="Local state directory for memory files")
+    run.add_argument(
+        "--secret-store",
+        default=None,
+        help="Path to local secrets.json store (optional override)",
+    )
     run.add_argument("--mode", choices=["single", "continuous"], default="single")
     run.add_argument("--track", choices=["auto", "assistant", "framework"], default="auto")
+    run.add_argument(
+        "--reasoning-provider",
+        choices=["anthropic", "openai", "openrouter"],
+        default=None,
+        help="Override reasoning provider for this run",
+    )
+    run.add_argument(
+        "--reasoning-model",
+        default=None,
+        help="Override reasoning model for this run",
+    )
     run.add_argument("--dry-run", action="store_true", help="Plan only, do not execute actions")
     run.add_argument("--verbose", action="store_true", help="Verbose logs")
     run.set_defaults(func=cmd_run)