run-sakthai-agent-v2

sakthai-agent-v2 is a Python CLI (sakthai) — a personal agent with a
persistent SQLite memory exposed four ways: the CLI itself, a tool-using
agent loop (sakthai run), an MCP stdio JSON-RPC server
(sakthai mcp), and a web API (python -m sakthai.web.server). Drive all
of it with .claude/skills/run-sakthai-agent-v2/driver.py, which smoke-tests
the CLI, the zero-cost agent preflight, the web API, and a live MCP roundtrip
in a throwaway home — no API key or network needed.

All paths are relative to the repo root. The package source lives at
personas/sakthai/sakthai/ (see [tool.setuptools.packages.find] in
pyproject.toml), not at a root-level sakthai/ — edit there.

Prerequisites

Python ≥ 3.11 and uv. No system packages beyond that (pure-Python CLI;
SQLite ships with CPython).

python3 --version   # need >= 3.11
uv --version

Setup

One-time, from the repo root:

uv sync --all-extras     # creates .venv with `sakthai` + dev deps

Verify:

uv run sakthai --version   # → sakthai, version 2.0.0

Run (agent path)

Run the driver. It exits non-zero if any surface is broken and prints a
[PASS]/[FAIL] line per check:

uv run python .claude/skills/run-sakthai-agent-v2/driver.py
# → a [PASS] line per check (21 currently), then "OK: all checks passed"

What it drives (all in a throwaway SAKTHAI_HOME):

surface	how it's checked
memory CLI	status, learn, recall, memory stats, tools (exit codes + output)
system & state machine	doctor, cycle status → cycle next (Dream→Hope transition persists), sessions list, skills list (library discovery)
memory snapshots	memory export → memory import into a second fresh home, then recall proves the fact survived the roundtrip
agent loop	run "..." --dry-run --no-mcp — resolves provider/creds/model/tools, no API call; repeated with --with-skills to prove skill injection preflights
web API	spawns python -m sakthai.web.server, asserts GET /api/stages (KPI JSON) and GET /api/ecosystem (integration status JSON)
MCP server	spawns sakthai mcp, pipes JSON-RPC initialize → tools/list → tools/call learn → tools/call recall, asserts the fact round-trips through the live server

Override the binary with SAKTHAI_BIN=/path/to/sakthai.

Drive the MCP server yourself

The server reads newline-delimited JSON-RPC on stdin and replies on stdout,
running until EOF — feed every request, then close stdin:

source .venv/bin/activate
export SAKTHAI_HOME=$(mktemp -d)
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"learn","arguments":{"value":"hi","kind":"note"}}}' \
  | sakthai mcp

Individual CLI commands

source .venv/bin/activate
export SAKTHAI_HOME=$(mktemp -d)            # isolate from your real ~/.sakthai
sakthai learn "prefers dark mode" --kind pref --key ui   # → learned (id=1)
sakthai recall "dark"                                     # → [pref] ui: prefers dark mode
sakthai run "say hi" --dry-run --no-mcp                  # → preflight report, exit 0, no tokens spent

Web API server

.venv/bin/python -m sakthai.web.server &   # listens on 127.0.0.1:3001
curl -s http://127.0.0.1:3001/api/stages     # → KPI/growth JSON (demo stub without live data)
curl -s http://127.0.0.1:3001/api/ecosystem  # → integration status JSON
kill %1

Run (human path)

• sakthai run "<task>" — real agent loop; needs a credential and network and
  spends tokens. Use --dry-run to validate setup for free.

Test

uv run pytest tests/ -q -m "not integration"   # ~1.2k hermetic tests, ~80s

Integration tests (-m integration) hit real Anthropic/Ollama endpoints and
self-skip when no credential/endpoint is set.

Gotchas

• Always scope pytest to tests/. A bare uv run pytest from the repo
  root tries to collect the persona trees (personas/*/agent-self-evolution,
  skill scripts, …) whose dependencies aren't installed — 60 collection
  errors before a single test runs.
• The dashboard CLI command no longer exists (removed in 5de2c25 along
  with sakthai/dashboard/). The JSON surface is now
  python -m sakthai.web.server (/api/stages, /api/ecosystem), which
  serves a demo stub when no live data layer is present. The React UI under
  the repo-root dashboard/ is a separate app; without its built dist the
  server is API-only.
• All runtimes share one SQLite DB ($SAKTHAI_HOME/memory.db, default
  ~/.sakthai). Always set SAKTHAI_HOME to a temp dir when smoke-testing or
  you'll pollute (or lock) your real memory. The driver does this for you.
• The cycle stage is itself a fact. The Dream→Growth state machine
  persists its current stage as a fact (kind=cycle) in the same store, so
  after a single learn, memory stats/export report 2 facts, not 1.
  Don't assert exact fact counts without accounting for it.
• sakthai run without --dry-run costs tokens and needs network. For a
  "does it work" check, --dry-run resolves provider + credentials + model +
  tool count with zero API calls.
• The MCP server runs until stdin EOF. Don't leave stdin open waiting for
  more output; send all requests and close the pipe.
• sakthai is only on PATH inside the venv (uv run … or
  source .venv/bin/activate). The driver invokes sakthai from PATH; if
  it's elsewhere, pass SAKTHAI_BIN=/abs/path/to/sakthai.

Troubleshooting

• sakthai: command not found: use uv run sakthai … or
  source .venv/bin/activate first.
• ModuleNotFoundError: No module named 'sakthai.cli.dashboard': you're
  on a stale checkout/branch where commit 5de2c25 removed the dashboard
  modules but cli/__init__.py still imported them (fixed since). Update, or
  remove the dangling import.
• FileNotFoundError: … sakthai/dashboard/dist from the web server: same
  era — serve() used to chdir into the removed dist unconditionally;
  fixed to skip it when absent.
• sakthai run exits with "Missing credentials …" / AuthError: expected
  with no provider credential. Use --dry-run, or set ANTHROPIC_API_KEY.
• pytest interrupted with dozens of collection errors: you ran it from
  the repo root without scoping. Use uv run pytest tests/ -q.