speexor 0.1.1 → 0.2.1

package/docs/adr/0002-plugin-architecture.md

@@ -0,0 +1,53 @@
+# ADR-0002: 7-Slot Plugin Architecture with EventBus
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor must support diverse capabilities — agent adapters, runtime backends, workspace management, issue tracking, SCM operations, notifications, and terminal I/O — without coupling these concerns in the core lifecycle. The architecture must allow:
+
+1. New plugins to be added without modifying core code.
+2. Multiple implementations per slot (e.g., tmux and Process for runtime).
+3. Loose communication between plugins and the dashboard.
+4. Graceful degradation when a plugin dependency (e.g., `tmux`, `gh` CLI) is unavailable.
+
+## Decision
+
+### Seven Plugin Slots
+
+We define exactly seven plugin slots, each with a dedicated TypeScript interface:
+
+| Slot       | Interface          | Purpose                              |
+|------------|---------------------|---------------------------------------|
+| agent      | `AgentPlugin`       | Spawn, communicate with, kill agents |
+| runtime    | `RuntimePlugin`     | Create/destroy terminal sessions     |
+| workspace  | `WorkspacePlugin`   | Manage isolated git worktrees        |
+| tracker    | `TrackerPlugin`     | Fetch issues, subscribe to events    |
+| scm        | `SCMPlugin`         | Branch, commit, PR, CI operations    |
+| notifier   | `NotifierPlugin`    | Desktop notifications                |
+| terminal   | `TerminalPlugin`    | Interactive terminal attach/detach   |
+
+### EventBus over Direct Calls
+
+All inter-module communication flows through an EventBus (EventEmitter3 wrapper) rather than direct method calls. This means:
+
+- The dashboard subscribes to lifecycle events without lifecycle knowing about the dashboard.
+- Plugins emit events (e.g., `session:created`, `worktree:created`) without importing other modules.
+- New observers (e.g., logging, metrics) can be added without modifying existing code.
+
+### getFirstPlugin() Resolution
+
+When the lifecycle needs a plugin for a slot, it calls `getFirstPlugin<T>(slot)` which returns the first registered implementation. This allows:
+
+- Multiple implementations per slot (e.g., both TmuxRuntime and ProcessRuntime).
+- Implicit priority ordering by registration order.
+- Graceful fallback: if the primary plugin fails initialization, the next in the list serves.
+
+## Consequences
+
+- **Positive:** Loose coupling; plugins are independently testable; new capabilities slot in without core changes.
+- **Positive:** The `getFirstPlugin()` pattern enables natural fallback (ProcessRuntime when tmux is absent).
+- **Negative:** Event-based flow is harder to trace than direct calls during debugging.
+- **Negative:** Seven slots are a fixed set — adding a new slot requires a core type change and a new interface definition.

package/docs/adr/0003-recursive-task-decomposition.md

@@ -0,0 +1,57 @@
+# ADR-0003: DAG-Based Recursive Task Decomposition with LLM Planner
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor must decompose complex tasks (e.g., "implement feature X across the full stack") into smaller, parallel-executable units that can be distributed across multiple agents. Two core design questions arise:
+
+1. **Representation:** Should the task structure be a flat list, a tree, or a directed acyclic graph (DAG)?
+2. **Planner:** Should the decomposition algorithm be rule-based (deterministic) or LLM-driven (probabilistic)?
+
+The representation must handle dependency ordering (task B depends on task A, task C depends on both) and allow parallel execution of independent sub-tasks. The planner must adapt to arbitrary repo structures and technologies without hardcoded rules.
+
+## Decision
+
+### DAG-Based Task Graph
+
+We represent decomposed tasks as a **directed acyclic graph (DAG)** where:
+
+- Each **Task Node** represents one atomic unit of work.
+- Edges represent **depends-on** relationships (a node cannot execute until all predecessors complete).
+- Nodes with no edges between them are eligible for parallel execution.
+- The graph supports dynamic refinement: a node in progress can be further decomposed into sub-DAGs at runtime.
+
+This choice over a flat list (which cannot express dependencies) or a tree (which cannot express cross-branch dependencies like "both frontend and backend depend on the shared schema change").
+
+### LLM-Based Planner over Algorithmic Decomposition
+
+We use an LLM-based planner (configurable per project, defaulting to `deepseek-reasoner`) to decompose tasks rather than a rule-based algorithm. Rationale:
+
+- **Arbitrary tech stacks:** The planner reads the repo structure and task description, then generates a decomposition customized to the actual codebase — no hardcoded "microservice decomposition" rules needed.
+- **Context-aware granularity:** The LLM decides how fine-grained each sub-task should be based on complexity, rather than a fixed heuristic.
+- **Adaptive refinement:** If the initial decomposition is too coarse, the planner can further decompose a node mid-execution using the same LLM.
+- **Human-readable plans:** The LLM generates natural language descriptions for each node, which feed into the approval UI and decision log.
+
+### Configuration
+
+```yaml
+decomposition:
+  maxTaskGraphDepth: 3      # Max depth of the Task Graph (node depth)
+  maxAgentSpawnDepth: 3     # Max levels of subagent spawning
+  maxNodesPerGraph: 50      # Safety limit on graph size
+  plannerProvider: opencode # Which agent backend to use for planning
+  plannerModel: deepseek-reasoner  # Model for the planner LLM call
+```
+
+The two depth limits (`maxTaskGraphDepth` and `maxAgentSpawnDepth`) are tracked separately — a deep task graph does not force deep agent spawning if the planner assigns shallow agents to deep nodes.
+
+## Consequences
+
+- **Positive:** DAG enables maximum parallelism — independent sub-tasks execute concurrently.
+- **Positive:** LLM planner adapts to any codebase without rule maintenance.
+- **Negative:** LLM planner calls add latency and cost to the decomposition phase.
+- **Negative:** DAG complexity requires a scheduler with dependency resolution (no simple FIFO queue).
+- **Neutral:** The `maxTaskGraphDepth`/`maxAgentSpawnDepth` split prevents confusion between graph depth and agent hierarchy depth (per FR-89).

package/docs/adr/0004-local-first-security.md

@@ -0,0 +1,58 @@
+# ADR-0004: Local-First Security with Two-Layer Defense
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor manages AI agents that write code, execute commands, and interact with git providers. This introduces two distinct security surfaces:
+
+1. **Third-party extensions** (installed via the future Marketplace) that can access the file system, shell, and network.
+2. **Runtime agent actions** — file edits, git operations, PR creation, CI interactions — some of which are irreversible (e.g., force-push to main).
+
+The architecture must ensure that a malicious or buggy extension cannot compromise the host system, and that high-risk agent actions require explicit human approval.
+
+## Decision
+
+### Local-First Architecture
+
+All data, credentials, and execution remain on the user's machine. There is no cloud relay, no telemetry by default, and no remote control plane. This means:
+
+- Secrets are stored in the OS keychain (via `conf` with `encryptionKey`), never in plaintext config files.
+- The dashboard runs on localhost only (`127.0.0.1`) by default.
+- The decision log and session state never leave the `~/.speexor/` directory.
+
+### Two-Layer Defense: Extension Permissions + Action Risk Tiers
+
+These are two independent, complementary layers documented in `SECURITY-DEFAULTS.md`:
+
+**Layer 1 — Extension Permissions (install-time capability gating):**
+
+Defined by `extensions.permissionsMode` in config (`strict` | `permissive`). Each extension declares capabilities (`shell`, `network`, `fileSystem`, `clipboard`) at install time. In `strict` mode, the user must explicitly approve each capability; in `permissive` mode, all declared capabilities are auto-granted. This layer gates what an extension *can ever do* — set once, at install.
+
+Extensions with `shell: none` and `network: none` run in `isolated-vm` (true V8 isolate, no access to Node built-ins). Extensions requiring `fileSystem`/`shell`/`network` run as separate OS processes with minimum privileges and a permission-enforcing proxy layer intercepting `fs`/`net`/`child_process` calls.
+
+`worker_threads` is explicitly **not** used as a security boundary — it is a performance-only primitive for orchestrator-internal CPU-bound work (per FR-85).
+
+**Layer 2 — Action Risk Tiers (runtime action gating):**
+
+Defined by `riskPolicy` in config. Every action an agent or extension takes is classified into a risk tier. Actions in `requireApproval` tiers (e.g., `irreversible-high-stakes`) block until the user approves. Actions in `autoApprove` tiers (e.g., `reversible-low`) execute autonomously. Unknown actions default to `high-stakes` (safe default).
+
+This layer gates what *any* action (from any already-permitted extension or core agent) *does right now* — evaluated every time, separate from the install-time capability grant.
+
+### Sandboxing: isolated-vm over worker_threads
+
+| Mechanism       | Security Boundary | Use Case                         |
+|-----------------|-------------------|----------------------------------|
+| `isolated-vm`   | True V8 isolate   | Extensions with no shell/network |
+| OS process      | OS-level          | Extensions with shell/network    |
+| `worker_threads`| None (same proc)  | Orchestrator-internal CPU work   |
+
+## Consequences
+
+- **Positive:** Two layers provide defense-in-depth — an extension with "write files" capability still cannot force-push to main without risk-tier approval.
+- **Positive:** Local-first ensures no external dependency for security; no cloud outage can leak secrets.
+- **Negative:** `isolated-vm` is a native dependency that complicates cross-platform builds and installs.
+- **Negative:** Two-layer model requires clear documentation (covered by `SECURITY-DEFAULTS.md`).
+- **Neutral:** `worker_threads` reclassification from v4's proposal removes a false sense of security.

package/docs/adr/0005-data-directory-layout.md

@@ -0,0 +1,69 @@
+# ADR-0005: User-Home Data Directory Layout (~/.speexor/)
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor persists several kinds of local state: session data, task graphs, checkpoints, the decision log, extension caches, and secret references. Earlier drafts left the storage location implicit. A formal decision is needed on:
+
+1. **Location:** Should data live in the project directory (`.speexor/`) or the user home directory (`~/.speexor/`)?
+2. **Structure:** How should different data types (SQLite, JSON, binary checkpoints, vault references) be organized?
+3. **Isolation:** How do we prevent state leakage between different projects managed by Speexor?
+
+## Decision
+
+### Location: ~/.speexor/ (User Home)
+
+All persistent state lives under `~/.speexor/` in the user's home directory, not project-local. Each managed project gets a subdirectory keyed by a content-hash of the repository URL combined with a short project ID:
+
+```
+~/.speexor/
+  ├── 1a2b3c4d-my-project/       # Per-project directory (hash-projectId)
+  │   ├── task-graph.sqlite       # Task graph DAG store (SQLite)
+  │   ├── decision-log.sqlite     # Decision Log (SQLite, read-only history)
+  │   ├── checkpoints/            # Session checkpoint snapshots (JSON)
+  │   │   ├── checkpoint-abc.json
+  │   │   └── checkpoint-def.json
+  │   ├── extensions/             # Downloaded/cached extension manifests
+  │   └── vault-refs.json         # References into OS keychain (never secrets)
+  ├── registry-cache/             # Marketplace registry index cache
+  ├── logs/                       # Global orchestrator logs
+  └── lock                        # Process lock file (prevents concurrent instances)
+```
+
+Rationale for `~/.speexor/` over project-local:
+
+- Data survives project directory deletion (user can delete a clone without losing the decision log).
+- Multiple clones of the same repo share a single project directory (hash-based dedup).
+- Cleaner user experience — no hidden directories scattered across the file system.
+- Consistent with established patterns (`.aws/`, `.config/`, `.npm/`, etc.).
+
+### Storage Formats
+
+| Data Type        | Format  | Rationale                                      |
+|------------------|---------|------------------------------------------------|
+| Task graph       | SQLite  | Relational queries on DAG nodes/edges          |
+| Decision log     | SQLite  | Searchable, filterable history                 |
+| Checkpoints      | JSON    | Human-readable, debuggable snapshots           |
+| Extension cache  | JSON    | Simple manifest storage, no query pattern      |
+| Vault refs       | JSON    | Lightweight reference store (values in keychain)|
+| Session state    | JSON    | Synchronous read/write for simplicity          |
+
+### Secrets Management
+
+The `vault-refs.json` file contains only **references** (key names/paths) into the OS keychain. Actual secret values (API tokens, encryption keys) are stored via the OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) and never written to disk in plaintext. The `secretsBackend` config option controls which backend is used.
+
+### Process Lock
+
+A `lock` file at `~/.speexor/lock` prevents multiple Speexor processes from operating on the same data directory simultaneously. The lock is advisory — it contains the PID and is cleaned up on graceful shutdown. Stale locks from crashes are automatically detected and cleared on startup.
+
+## Consequences
+
+- **Positive:** Data persists across project directory deletions; clean separation between projects.
+- **Positive:** Hash-based project IDs prevent collisions and enable deduplication.
+- **Positive:** SQLite for graph and decision log enables efficient queries vs. JSON scanning.
+- **Negative:** User-home directory may not be writable in some locked-down enterprise environments (mitigation: `SPEEXOR_DATA_DIR` env var override).
+- **Negative:** OS keychain dependency adds a setup step for headless/server environments.
+- **Neutral:** Consistent with `speexor migrate-from-konduktor` migration path (FR-84).

package/examples/basic.yaml

@@ -1,61 +1,61 @@
-# Speexor Configuration — Basic Example
-# Agent Orchestrator for multi-AI coding agent orchestration
-#
-# Usage:
-#   1. Save this file as speexor.config.yaml in your project root
-#   2. Run `speexor start` to initialize and open the dashboard
-#   3. Run `speexor agent spawn --task <issue-id>` to spawn an agent
-
-version: "1"
-
-projects:
-  # --- Single project, single agent ---
-  - name: brainclash
-    repository: https://github.com/superdevids/brainclash
-    provider:
-      primary: opencode
-      fallback:
-        - claude-code
-        - aider
-      concurrentLimit: 3
-
-    # Automated reactions to CI and PR events
-    reactions:
-      ci-failed:
-        auto: true
-        action: fix
-        retries: 3
-        escalateAfter: 30
-      changes-requested:
-        auto: true
-        action: fix
-        retries: 2
-        escalateAfter: 60
-      approved-and-green:
-        auto: false
-        action: notify
-        retries: 0
-        escalateAfter: 0
-
-  # --- Second project with different provider ---
-  - name: kata-netizen
-    repository: https://github.com/superdevids/kata-netizen
-    provider:
-      primary: claude-code
-      concurrentLimit: 2
-    reactions:
-      ci-failed:
-        auto: true
-        action: fix
-        retries: 3
-        escalateAfter: 30
-      changes-requested:
-        auto: true
-        action: fix
-        retries: 2
-        escalateAfter: 45
-      approved-and-green:
-        auto: false
-        action: notify
-        retries: 0
-        escalateAfter: 0
+# Speexor Configuration — Basic Example
+# Agent Orchestrator for multi-AI coding agent orchestration
+#
+# Usage:
+#   1. Save this file as speexor.config.yaml in your project root
+#   2. Run `speexor start` to initialize and open the dashboard
+#   3. Run `speexor agent spawn --task <issue-id>` to spawn an agent
+
+version: "1"
+
+projects:
+  # --- Single project, single agent ---
+  - name: brainclash
+    repository: https://github.com/superdevids/brainclash
+    provider:
+      primary: opencode
+      fallback:
+        - claude-code
+        - aider
+      concurrentLimit: 3
+
+    # Automated reactions to CI and PR events
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 60
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0
+
+  # --- Second project with different provider ---
+  - name: kata-netizen
+    repository: https://github.com/superdevids/kata-netizen
+    provider:
+      primary: claude-code
+      concurrentLimit: 2
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 45
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0

package/package.json

@@ -1,102 +1,103 @@
-{
-  "name": "speexor",
-  "version": "0.1.1",
-  "description": "Speexor — Agent Orchestrator for multi-AI coding agent orchestration across repositories",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "speexor": "dist/cli/index.js"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./core": {
-      "import": "./dist/core/index.js",
-      "types": "./dist/core/index.d.ts"
-    },
-    "./cli": {
-      "import": "./dist/cli/index.js",
-      "types": "./dist/cli/index.d.ts"
-    },
-    "./plugins": {
-      "import": "./dist/plugins/index.js",
-      "types": "./dist/plugins/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "schema",
-    "docs",
-    "*.md",
-    "examples",
-    "speexor.config.yaml.example"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
-  },
-  "dependencies": {
-    "commander": "^12.0.0",
-    "chalk": "^5.3.0",
-    "conf": "^12.0.0",
-    "dayjs": "^1.11.0",
-    "debug": "^4.3.0",
-    "eventemitter3": "^5.0.0",
-    "execa": "^9.0.0",
-    "globby": "^14.0.0",
-    "node-emoji": "^2.1.0",
-    "ora": "^8.0.0",
-    "yaml": "^2.5.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@types/debug": "^4.1.0",
-    "@types/node": "^26.0.1",
-    "@vitest/coverage-v8": "^2.1.9",
-    "tsup": "^8.3.0",
-    "typescript": "^5.7.0",
-    "vite": "^8.1.0",
-    "vitest": "^2.1.0"
-  },
-  "keywords": [
-    "orchestrator",
-    "ai-agent",
-    "agent-orchestration",
-    "coding-agent",
-    "claude-code",
-    "opencode",
-    "aider",
-    "codex",
-    "multi-agent",
-    "speexor"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "preferGlobal": true,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/superdevids/speexjs.git",
-    "directory": "packages/speexor"
-  },
-  "bugs": {
-    "url": "https://github.com/superdevids/speexjs/issues"
-  },
-  "homepage": "https://github.com/superdevids/speexjs/tree/main/packages/speexor#readme",
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "speexor",
+  "version": "0.2.1",
+  "description": "Speexor — Agent Orchestrator for multi-AI coding agent orchestration across repositories",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "speexor": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli/index.js",
+      "types": "./dist/cli/index.d.ts"
+    },
+    "./plugins": {
+      "import": "./dist/plugins/index.js",
+      "types": "./dist/plugins/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schema",
+    "docs",
+    "*.md",
+    "examples",
+    "speexor.config.yaml.example"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "conf": "^12.0.0",
+    "dayjs": "^1.11.0",
+    "debug": "^4.3.0",
+    "eventemitter3": "^5.0.0",
+    "execa": "^9.0.0",
+    "globby": "^14.0.0",
+    "node-emoji": "^2.1.0",
+    "ora": "^8.0.0",
+    "sql.js": "^1.14.1",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@types/debug": "^4.1.0",
+    "@types/node": "^26.0.1",
+    "@types/sql.js": "^1.4.11",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vite": "^8.1.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "orchestrator",
+    "ai-agent",
+    "agent-orchestration",
+    "coding-agent",
+    "claude-code",
+    "opencode",
+    "aider",
+    "codex",
+    "multi-agent",
+    "speexor"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdevids/speexor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/superdevids/speexor/issues"
+  },
+  "homepage": "https://github.com/superdevids/speexor#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}