feat: ai session attach — live WebSocket streaming + interactive chat

[maximelb]

Summary

Three related additions to the ai CLI, on top of cli-v2. Together they cover the two distinct session models the ai-sessions backend exposes — org-owned automation and user-owned interactive — plus the WebSocket attach that streams both.

1. limacharlie ai session attach — live session streaming + interactive chat

• New subcommand that opens a WebSocket to ai.limacharlie.io and streams session messages in real time with colour-coded pretty-printing (--raw for JSON).
• --interactive / -i turns the terminal into a chat: stdin lines are sent as prompt messages; tool_approval_request and ask_user_question messages are surfaced as live prompts; /interrupt and /quit built in.
• --read-only connects to the org-scoped /v1/ws/org/sessions/{id} endpoint. When the owner endpoint returns 403 (the caller isn't the session owner), the CLI transparently falls back to read-only with a notice.
• WS URL path uses the /v1/ws/... form — the only prefix the GCP load balancer routes to the interaction-proxy. The legacy /v1/sessions/{id}/ws form registered on the proxy service isn't reachable through the LB and returns 404.
• New limacharlie.sdk.ai_session.SessionAttachment async helper wrapping the full WebSocket protocol (see ai-sessions/api/WEBSOCKET_PROTOCOL.md): prompt, interrupt, tool_approval_response, ask_user_question_response, heartbeat.
• AI.attach_session(session_id, read_only=...) factory on the SDK.
• Adds websockets>=13.0 to runtime dependencies.

Important: sessions created by ai start-session (below) are org-owned (OwnerOID set, OwnerUID empty, SessionType=API). The backend exposes those only through the read-only org-scoped WS endpoint, so ai session attach --interactive against an org-started session will always auto-fall back to read-only. Use ai chat (below) to get a real interactive session.

2. limacharlie ai start-session + ai session {list,get,terminate,history} — org-owned sessions

ai start-session runs an ai_agent hive record as a template; every field on the server's ProfileContent schema can be overridden for a single run:

• --model, --max-turns, --max-budget-usd, --task-budget-tokens, --ttl-seconds, --one-shot/--no-one-shot, --permission-mode, --allowed-tools, --denied-tools, --plugin (repeatable).
• --env KEY=VALUE (repeatable) — merged with the template's environment; override wins on key collisions.
• --anthropic-key, --lc-api-key, --lc-uid — credential overrides that accept literal values or hive://secret/<name> refs.

Scalars and lists REPLACE the template value when passed. Environment MERGES. Omitted flags leave the template untouched. Override values starting with hive://secret/ are resolved before sending so secrets never appear in argv.

The ai session group manages org-owned sessions through their lifecycle: list, get, terminate, history, attach.

Examples:
```
limacharlie ai start-session --definition my-agent
--model claude-sonnet-4-6 --max-budget-usd 2.50
limacharlie ai start-session --definition my-agent
--env SLACK_WEBHOOK=hive://secret/slack-webhook
limacharlie ai start-session --definition my-agent
--allowed-tools Read,Grep --denied-tools Bash,Write --no-one-shot
```

3. limacharlie ai chat + ai chats {list,get,terminate,history} + ai auth claude — user-owned interactive sessions

ai start-session creates org-owned sessions (read-only over the WS by design). ai chat creates user-owned sessions billed against the caller's registered Claude credential, opens the owner WS endpoint, and hands the terminal off to the interactive attach loop — the setup the existing --interactive flag was always describing.

ai chats is the user-scoped counterpart to ai session: same subcommand shape (list, get, terminate, history), but it routes to /v1/sessions/* (user-owned, keyed by the caller's UID) instead of /v1/org/sessions/*. Sessions of one kind are not visible from the other group's commands; they live in distinct ownership models on the backend.

New credential-management surface (one-time setup before ai chat works):

• ai auth claude status — returns has_credentials, credential_type (oauth_token / apikey), created_at.
• ai auth claude login — full browser OAuth flow: calls /v1/auth/claude/start, polls /v1/auth/claude/url for the URL, prompts the user for the returned code, posts it to /v1/auth/claude/code.
• ai auth claude set-key --key <VALUE> (or --key-from-stdin) — stores a raw Anthropic API key; hive://secret/<name> is resolved before sending.
• ai auth claude logout — DELETE /v1/auth/claude.

ai chat flow:

1. Calls claude_auth_status; if has_credentials=false, exits non-zero with a pointer to auth claude login / set-key. No silent fallback.
2. Calls POST /v1/register (idempotent).
3. POST /v1/sessions with any supplied overrides (--model, --max-turns, --max-budget-usd, --task-budget-tokens, --permission-mode, --allowed-tools, --denied-tools, --plugin, --name, --idempotent-key).
4. Attaches via the owner WS endpoint in interactive mode. If a PROMPT argument is given it's sent as the opening prompt; further turns come from the interactive stdin loop. Stdin is not consumed as the opening prompt — supply that via the argument so multi-line piping doesn't get glued into one message.

Examples:
```
limacharlie ai auth claude login
limacharlie ai chat "what sensors pinged in the last hour?"
limacharlie ai chat --model claude-sonnet-4-6 --max-budget-usd 0.50
limacharlie ai chats list --status running
limacharlie ai chats terminate --id
```

The existing ai session attach still works for either kind of session — use it to rejoin an existing session or view an org-owned one live in read-only mode.

Cross-linked PRs

• documentation (CLI reference page): docs(ai-sessions): document the new ai CLI surface (org + user sessions, attach, chat, auth claude) documentation#189
• lc-ai (READMEs): docs: explain running ai_agent Hive records from the CLI lc-ai#82

Protocol references

• WebSocket auth / endpoints / message types: ai-sessions/internal/proxy/handler.go:111-397 and ai-sessions/api/WEBSOCKET_PROTOCOL.md. GCP LB URL map: ai-sessions/terraform/modules/load-balancer/main.tf:137-190 — /v1/ws/* routes to the interaction-proxy.
• Org-session shape: ai-sessions/pkg/api/types.go (SessionRequest / ProfileContent).
• User-session shape: ai-sessions/internal/sessionmanager/models.go (CreateSessionRequest). Routes: handler.go:36-43.
• Claude credential management handlers: ai-sessions/internal/claudeauth/handler.go.
• Auth middleware: ai-sessions/internal/common/jwt.go — accepts Authorization: Bearer <jwt> and Sec-WebSocket-Protocol: access_token, <jwt>; the CLI uses the header form via Client.get_jwt().

Test plan

• pytest tests/unit/ — 3075 passed, 5 pre-existing platform/docstring skips. 39 in tests/unit/test_ai_session_attach.py plus 73 in the extended tests/unit/test_sdk_ai_sessions.py (org SDK + user SDK + auth + chat + chats CLI groups).
• Manual (white-sands, prod): ai start-session override propagation verified on-wire (model/max_turns/max_budget_set in session init); max_budget_usd=0.10 cap triggered precisely at $0.10530.
• Manual (white-sands, prod): ai session attach connects via /v1/ws/sessions/{id}; pretty + --raw | jq both work; owner endpoint 403 → transparent read-only fallback notice emitted.
• Manual (prod): ai auth claude status returns the live credential state.
• Manual (white-sands, prod): ai chat "What is the capital of France?" against a registered user — assistant replied "Paris" in interactive mode (no read-only fallback).
• Manual (white-sands, prod): re-attach via ai session attach --interactive to the same session and send a follow-up — assistant replied "56" to "What is 7 times 8?".
• Manual (white-sands, prod): ai chats list / ai chats get --id <id> show user-owned sessions invisible to ai session list.
• Manual: ai auth claude login against a fresh user — walk through browser flow, confirm credential stored.
• Manual: ai auth claude set-key --key-from-stdin with a raw Anthropic key.