claude-comms 1.0.34 → 1.0.36

package/.agents/AGENTS.md

@@ -43,11 +43,11 @@ Evaluate the Change for a given Assignment/Task against the following criteria:
 
 
 [VALIDATE]
-Run required commands — all must pass without warnings or errors:
-   - `pnpm lint`
-   - `pnpm ts:check`
-   - `pnpm test:all`
-   - `pnpm build`
+Run required commands from `.agents/repo.md` — all must pass without warnings or errors:
+   - lint
+   - typecheck
+   - build
+   - test
 
 [UAT]
 Perform manual QA:
@@ -58,4 +58,4 @@ Perform manual QA:
 
 [/AGENT OPERATING PROCEDURES]
 
-# Repository Guidelines: see `.agents/repo.md`
+# Adhere to the Repository Guidelines: `.agents/repo.md`

package/.agents/repo.md

@@ -1,29 +1,15 @@
 
 # Repository Guidelines
+VALIDATE by Running required commands — all must pass without warnings or errors:
+   - `pnpm lint`
+   - `pnpm ts:check`
+   - `pnpm test:all`
+   - `pnpm build`
 
-## Project Structure & Module Organization
-- `apps/server` hosts the Bun observability API; routes stay in `src/index.ts`, persistence helpers in `src/db.ts`, and regression suites in `src/__tests__`.
-- `apps/client` contains the Vue dashboard; UI modules live in `src/components` and `src/views` with Vitest and Playwright specs under `tests/`.
-- `packages/setup-installer` ships the `claude-comms` NPX CLI; logic resides in `src/`, distributable templates in `templates/`, and Jest suites across `test/unit`, `test/integration`, and `test/e2e`.
-- `.claude/hooks/*` stores Python-powered agents, while `scripts/` provides operational helpers such as `start-system.sh`, `reset-system.sh`, and telemetry generators.
 
-## Build, Test, and Development Commands
-- `./scripts/start-system.sh` boots the Bun API, Vue dashboard, and SQLite broker for an end-to-end stack from the repo root.
-- `cd apps/server && bun install && bun run dev` starts the API with hot reload; use `bun run start` for production parity and `bun run typecheck` before merging.
-- `cd apps/client && bun install && bun run dev` launches the dashboard; `bun run build` compiles the Vite bundle and `bun run preview` smoke-tests it.
-- `cd packages/setup-installer && npm install && npm test` validates the installer; run `npm run lint` or `npm run test:coverage` when altering CLI behavior or templates.
+## Dev server
+`pnpm dev | tee -a dev.log` is already running in the background. check the `dev.log` file. Avoid starting up a new instance as it will bump the port.
+you can access the client on `http://localhost:3000/` using the UAT toolkit
 
-## Coding Style & Naming Conventions
-- Use 2-space indentation, `camelCase` utilities, `PascalCase` components and types, and co-locate shared shapes in `apps/*/src/types.ts`.
-- Keep persistence isolated to `apps/server/src/db.ts`; expose new queries through typed helpers rather than inline SQL inside request handlers.
-- In the dashboard prefer composables in `src/composables`, Tailwind utility classes, and structured logging or toast utilities instead of raw `console.log` calls.
-
-## Testing Guidelines
-- Backend suites live in `apps/server/src/__tests__` with `.test.ts` suffixes; run `bun run test` or `bun run test:coverage` whenever mutating server logic.
-- Dashboard coverage pairs Vitest (`bun run test`) with Playwright smoke tests in `apps/client/tests/playwright`; refresh artifacts in `tests/visual` when UI states change.
-- Installer validation relies on Jest; execute `npm run test:integration` after template edits and `npm run test:e2e` before publishing new packages.
-
-## Commit & Pull Request Guidelines
-- History favors short, imperative subjects (`remove matrix mode`) with selective conventional prefixes (`chore(release): 1.0.23`); follow that tone and omit trailing periods.
-- Reference issues and describe agent-facing impact in PR descriptions; attach dashboard screenshots or installer logs whenever UX or setup flows shift.
-- Before requesting review, ensure `./scripts/test-system.sh` plus relevant package checks pass and call out skipped suites or follow-up tasks in the PR notes.
+## Documentation Protocol
+Guard the doc hierarchy: specs in `docs/project/spec/` remain the source of truth (Businesslogic, data dictionary, data flows, tech guide, industry references); guides in `docs/project/guides/` capture evolving process; phase folders (`docs/project/phases/XX-Name/`) store live work packages and notes. Update whichever doc you rely on as soon as the code diverges.

package/.agents/tools/agent-job/README.md

@@ -0,0 +1,208 @@
+# Agent Job Adapter
+
+Self-contained `uv` Python scripts that turn verbose CLI agent runs (Codex, Gemini CLI) into **file-backed jobs** with stable IDs and cheap status checks.
+
+## Quick Start
+
+```bash
+# Spawn a new job (returns immediately)
+uv run agent_job.py spawn --harness codex -- "your assignment here"
+# Output: Agent running. Check status with: `uv run agent_job.py status <job_id>`
+
+# Check job status
+uv run agent_job.py status <job_id>
+
+# List all jobs
+uv run agent_job.py list
+
+# Monitor jobs with TUI
+uv run agent_monitor.py
+```
+
+## Commands
+
+### `spawn`
+
+Starts a new agent job with the specified harness. Returns immediately after initialization.
+
+```bash
+uv run agent_job.py spawn --harness <gemini|codex> -- "<assignment>"
+```
+
+**Output:**
+```
+Agent running. Check status with: `uv run agent_job.py status 019abd9d-8cb2-7e81-bae9-2a8fe5be04fa`
+```
+
+### `status`
+
+Get current status of a job with computed runtime metrics.
+
+```bash
+uv run agent_job.py status <job_id>
+```
+
+**Running job output:**
+```json
+{
+  "job_id": "019abd9d-8cb2-7e81-bae9-2a8fe5be04fa",
+  "harness": "codex",
+  "pid": 12345,
+  "logs": "/path/to/agent.log",
+  "status": "running",
+  "status_reason": "command_execution",
+  "start_time": "2025-11-25T08:10:06.262Z",
+  "last_event_time": "2025-11-25T08:10:29.337Z",
+  "runtime_sec": 23.1,
+  "idle_sec": 4.0,
+  "operations": 18
+}
+```
+
+**Completed job output:**
+```json
+{
+  "job_id": "019abd9d-8cb2-7e81-bae9-2a8fe5be04fa",
+  "harness": "codex",
+  "pid": 12345,
+  "logs": "/path/to/agent.log",
+  "status": "complete",
+  "status_reason": "completed",
+  "start_time": "2025-11-25T08:10:06.262Z",
+  "last_event_time": "2025-11-25T08:10:29.337Z",
+  "runtime_sec": 23.1,
+  "operations": 18,
+  "end_time": "2025-11-25T08:10:29.340Z",
+  "completion": {
+    "messages": ["Task completed successfully."],
+    "tokens": { "input": 7288, "output": 84, "total": 7372 },
+    "duration_ms": 13845
+  }
+}
+```
+
+### `list`
+
+List all jobs with full status information.
+
+```bash
+uv run agent_job.py list
+```
+
+## Monitor TUI
+
+Real-time terminal UI for monitoring agent jobs, similar to `top`.
+
+```bash
+uv run agent_monitor.py              # Default 2s refresh
+uv run agent_monitor.py --interval 5 # Custom refresh interval
+```
+
+**Features:**
+- Color-coded status indicators:
+  - `●` Yellow = running
+  - `✓` Green = complete
+  - `✗` Red = error
+  - `⏱` Red = timeout
+- Columns: Status, Harness, Job ID, Status Reason, Started, Runtime, Operations
+- Scrollable log viewer
+
+**Keyboard Controls:**
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` or `j/k` | Navigate job list |
+| `Enter` | View job log |
+| `r` | Refresh / reload log |
+| `q` | Quit |
+
+**Log View Controls:**
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` or `j/k` | Scroll line by line |
+| `PgUp/PgDn` | Scroll by page |
+| `Home/End` | Jump to start/end |
+| `r` | Reload log file |
+| `ESC` | Back to job list |
+
+## Job Status
+
+| Status | Description |
+|--------|-------------|
+| `running` | Job is currently executing |
+| `complete` | Job finished successfully |
+| `error` | Job failed (see `status_reason`) |
+| `timeout` | Job killed due to idle timeout |
+
+## Status Reason
+
+The `status_reason` field shows current activity while running:
+
+**Codex:**
+- `initializing` - Job starting up
+- `thinking` - Turn started
+- `reasoning` - Agent reasoning
+- `command_execution` - Running shell command
+- `todo_list` - Managing todos
+- `agent_message` - Generating response
+- `completed` - Finished
+
+**Gemini:**
+- `initializing` - Job starting up
+- `run_shell_command` - Running command
+- `write_file` / `read_file` - File operations
+- `write_todos` - Managing todos
+- `responding` - Generating response
+- `completed` - Finished
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `AGENT_JOBS_ROOT` | `$TMPDIR/agent_jobs/$USER` | Root directory for job files |
+| `IDLE_TIMEOUT_SEC` | `300` | Seconds of inactivity before killing job |
+
+## File Structure
+
+Each job creates a directory under `AGENT_JOBS_ROOT`:
+
+```
+<jobs_root>/<job_id>/
+    status.json    # Current job state (updated on each event)
+    agent.log      # Raw harness output (appended in real-time)
+```
+
+## Supported Harnesses
+
+### Codex
+
+Uses `codex --yolo e "<assignment>" --json`
+
+Events handled:
+- `thread.started` - Extracts job ID (thread_id)
+- `turn.started` - Sets status_reason to "thinking"
+- `item.started/completed` - Updates status_reason with item type
+- `turn.completed` - Extracts token usage
+
+### Gemini CLI
+
+Uses `gemini --yolo -s -m gemini-3-pro-preview --output-format stream-json "<assignment>"`
+
+Events handled:
+- `init` - Extracts session ID as job ID
+- `tool_use` - Updates status_reason with tool name
+- `message` (assistant) - Accumulates response text
+- `result` - Extracts token stats and duration
+
+## Babysitter Pattern
+
+For autonomous monitoring:
+
+1. **Spawn** the job - returns immediately with job ID
+2. **Poll** status periodically
+3. **React** based on status:
+   - `running` - Check `idle_sec`, continue monitoring
+   - `complete` - Read `completion.messages`
+   - `timeout` - Report idle timeout exceeded
+   - `error` - Check `status_reason` and logs