@cardor/agent-harness-kit 0.17.0 → 1.1.0

package/README.md

@@ -62,8 +62,10 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 - **Health gate** — agents must run `health.sh` and get a green exit before starting or closing any task. You define what "healthy" means.
 - **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.
 - **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.
-- **Zero native dependencies** — uses `node:sqlite` (Node ≥ 22) or `bun:sqlite` (Bun) built-in. No native compilation, no `node-gyp`.
+- **Multi-database support** — SQLite by default (zero native deps, uses `node:sqlite` on Node ≥ 22 or `bun:sqlite` on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
 - **Incremental scaffold** — `ahk init` and `ahk build` never overwrite files you've customized. Agent definitions you've edited are preserved.
+- **Global installation** — `ahk init` can scaffold the harness into your home directory (`~/.claude` or `~/.config/opencode`) to share it across all projects.
+- **Input validation** — CLI prompts validate all inputs (name length, path format, task title, etc.) and retry with the error message instead of silently accepting bad values.
 
 ---
 
@@ -98,7 +100,7 @@ ahk init
 
 ### `ahk init`
 
-Interactive scaffold. Asks for your project name, AI provider, docs path, task adapter, and an optional first task. Creates all harness files in the current directory.
+Interactive scaffold. Asks for your project name, description, AI provider, whether to install globally, docs path, task adapter, and an optional first task. Creates all harness files in the current directory (or home directory if global).
 
 ```bash
 ahk init
@@ -109,6 +111,8 @@ ahk init --name "my-app" --provider claude-code --docs ./docs --tasks local
 
 Run this once per project. Safe to re-run — it will not overwrite files you've customized.
 
+**Global installation** — if you answer yes to "Install globally?", files go to `~/.claude` (Claude Code) or `~/.config/opencode` (OpenCode). This lets you share one harness config across all your projects.
+
 ---
 
 ### `ahk build`
@@ -230,6 +234,26 @@ ahk task done add-auth-flow
 
 ---
 
+### `ahk reset`
+
+Clears harness data interactively. Only SQLite databases are managed by this command — remote Postgres/MySQL databases are intentionally skipped.
+
+```bash
+ahk reset                          # interactive — asks before deleting each item
+ahk reset --force                  # skip all confirmation prompts
+ahk reset --provider claude-code   # also delete agent .md files for this provider
+ahk reset --provider opencode
+```
+
+What it can reset:
+- The SQLite `.db` file (plus WAL and SHM files if present)
+- `.harness/feature_list.json`
+- Agent `.md` files in `.claude/agents/` or `.opencode/agents/`
+
+After a reset, run `ahk init` to scaffold a fresh harness.
+
+---
+
 ### `ahk migrate`
 
 Migrates provider-specific files from one AI provider to another. Useful when switching from Claude Code to OpenCode or vice versa.
@@ -315,10 +339,19 @@ export default defineHarness({
     custom:   [],                 // define extra agents here
   },
 
+  // ── Database ──────────────────────────────────────────────────────────────
+  // SQLite (default — zero native deps, Node 22+ or Bun)
+  database: { type: 'sqlite', path: '.harness/harness.db' },
+
+  // PostgreSQL — uncomment to use instead:
+  // database: { type: 'postgres', connectionString: process.env.DATABASE_URL },
+
+  // MySQL — uncomment to use instead:
+  // database: { type: 'mysql', connectionString: process.env.DATABASE_URL },
+
   storage: {
-    dir:    '.harness',
-    dbPath: '.harness/harness.db',
-    tasks:  { adapter: 'local' },
+    dir:   '.harness',
+    tasks: { adapter: 'local' },  // 'local' | 'jira' | 'linear' | 'mcp'
     sections: {
       toolsUsed:     true,        // log which tools agents used
       filesModified: true,        // log which files were touched
@@ -335,7 +368,7 @@ export default defineHarness({
   },
 
   tools: {
-    mcp:     { enabled: true, port: 3456 },
+    mcp:     { enabled: true, port: 3742 },
     scripts: { enabled: true, outputDir: './.harness/scripts' },
   },
 })
@@ -418,10 +451,14 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | `tasks.get` | `status?` | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked` |
 | `tasks.claim` | `id, agent` | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first |
 | `tasks.update` | `id, status` | Change task status |
+| `tasks.add` | `title, slug?, description?, acceptance?` | Create a new task directly from MCP (agents can queue work on the fly) |
+| `tasks.acceptance.update` | `criterionId` | Mark an acceptance criterion as met. Criterion IDs come from `tasks.get` |
 | `actions.start` | `taskId, agent` | Start a new action, returns `actionId` |
-| `actions.write` | `actionId, sectionType, content` | Record a section: `result \| tools_used \| files_modified \| blockers \| next_steps` |
+| `actions.write` | `actionId, sectionType, content` | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that |
 | `actions.complete` | `actionId, summary` | Close an action with a one-line summary |
 | `actions.get` | `taskId` | Full action history for a task (all agents, all sections) |
+| `actions.record_file` | `actionId, filePath, operation, notes?` | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted` |
+| `actions.record_tool` | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard |
 | `docs.search` | `query` | Search the `docsPath` folder for content matching the query |
 
 ---
@@ -456,11 +493,18 @@ The rule: commit inputs (config, task definitions, agent instructions). Ignore o
 
 ## Runtime compatibility
 
-| Runtime | Support |
-|---------|---------|
-| Node.js ≥ 22 | ✅ uses `node:sqlite` built-in |
-| Bun (any recent) | ✅ uses `bun:sqlite` built-in |
-| Node.js < 22 | ❌ `node:sqlite` not available |
+| Runtime | SQLite | PostgreSQL | MySQL |
+|---------|--------|-----------|-------|
+| Node.js ≥ 22 | ✅ uses `node:sqlite` built-in | ✅ via `postgres` package | ✅ via `mysql2` package |
+| Bun (any recent) | ✅ uses `bun:sqlite` built-in | ✅ via `postgres` package | ✅ via `mysql2` package |
+| Node.js < 22 | ❌ `node:sqlite` not available | ✅ | ✅ |
+
+SQLite requires no additional packages. For PostgreSQL install `postgres`, for MySQL install `mysql2`:
+
+```bash
+npm install postgres    # for PostgreSQL
+npm install mysql2      # for MySQL
+```
 
 ---
 
@@ -475,9 +519,39 @@ npm run build:ui    # build the dashboard SPA (dashboard/ → src/dashboard-dist
 npm run build       # build:ui + tsc + copy-assets
 npm run dev         # watch mode (CLI TypeScript only)
 npm test            # run tests
-npm link            # register ahk globally from local source
 ```
 
+### Testing the local build in another project
+
+Use the helper script to build the package and link it into any local project in one step:
+
+```bash
+# Build + link into a specific project
+./scripts/link-local.sh /path/to/your-other-project
+
+# Build + register globally only (then link manually wherever you need)
+./scripts/link-local.sh
+```
+
+What the script does:
+
+1. Runs `npm run build` (full build including dashboard assets)
+2. Runs `npm link` to register the package globally on your machine
+3. Runs `npm link @cardor/agent-harness-kit` inside the target project
+4. Smoke-tests the `ahk` binary with `--version`
+
+After linking, `npx ahk` inside the target project will use your local build. To unlink when you're done:
+
+```bash
+# Inside the target project
+npm unlink @cardor/agent-harness-kit
+
+# Optionally remove the global registration
+npm uninstall -g @cardor/agent-harness-kit
+```
+
+> **Tip:** If you're iterating quickly, run `npm run build` in this repo after each change — the link picks up the new `dist/` immediately without re-running the script.
+
 To work on the dashboard UI with hot reload:
 
 ```bash
@@ -502,9 +576,16 @@ Types: `feat fix chore refactor docs test perf style build ci revert`
 
 ## Roadmap
 
-- ✅ **`ahk dashboard`** — local web UI with real-time WebSocket updates. Shows tasks, action timelines, file activity, tool usage, and per-agent breakdowns. Run `ahk dashboard` in any initialized project.
-- **Open Telemetry integration** — emit OpenTelemetry spans for all agent actions, file operations, and tool calls. Enables distributed tracing and integration with any OT-compatible observability platform.
-- **Jira task adapter** — pull tasks directly from Jira instead of maintaining `feature_list.json` manually. The `tasks.adapter` config key is already wired for this.
+- ✅ **`ahk dashboard`** — local web UI with real-time WebSocket updates. Shows tasks, action timelines, file activity, tool usage, and per-agent breakdowns.
+- ✅ **`ahk reset`** — interactively clear the SQLite DB, feature list, and agent files to start a project fresh.
+- ✅ **PostgreSQL + MySQL drivers** — remote database support via `postgres` and `mysql2` packages. Configure with `database: { type: 'postgres', connectionString: '...' }`.
+- ✅ **`actions.record_file` + `actions.record_tool`** — dedicated MCP tools for populating the Files and Tools dashboard views.
+- ✅ **`tasks.add` via MCP** — agents can create new tasks on the fly without leaving the conversation.
+- ✅ **Global installation** — `ahk init` can install the harness to your home directory, shared across projects.
+- ✅ **Input validation** — all CLI prompts validate and retry on bad values.
+- **Graphify integration** — connect the harness to Graphify to visualize agent workflows, task dependencies, and action timelines as interactive graphs.
+- **Open Telemetry integration** — emit OpenTelemetry spans for all agent actions, file operations, and tool calls.
+- **Jira task adapter** — pull tasks directly from Jira instead of maintaining `feature_list.json` manually.
 - **Linear task adapter** — same as Jira, for Linear.
 - **GitHub Issues adapter** — same, for GitHub Issues.
 - **Remote MCP adapter** — connect to a hosted MCP server instead of a local SQLite file. Enables shared task state across machines and team members without syncing a DB file.

package/dist/agent-templates/lead.md

@@ -66,7 +66,24 @@ tasks.get('pending')        → pick the task with the lowest id
 
 If `.harness/current.md` is available and MCP is unreachable, read it as fallback.
 
-### 2. Claim the task
+### 2. Find or create a task
+
+**If pending tasks exist:** pick the one with the lowest id.
+
+**If no pending tasks exist:** ask the user what they want to work on. From their reply, infer:
+- `title` — short, action-oriented phrase
+- `description` — goal and context
+- `acceptance` — list of measurable criteria
+
+If any of the above are unclear or missing, ask before proceeding. Then create the task:
+
+```
+tasks.add(title, slug?, description?, acceptance[])
+```
+
+The returned task id is what you pass to `tasks.claim` below.
+
+### 3. Claim the task
 
 ```
 tasks.claim(id)
@@ -74,13 +91,13 @@ tasks.claim(id)
 
 If response is `task_already_claimed` → pick the next pending task. Never steal a claimed task.
 
-### 3. Register your action
+### 4. Register your action
 
 ```
 actions.start(taskId, 'lead')   → save the returned actionId
 ```
 
-### 4. Write a decomposition plan
+### 5. Write a decomposition plan
 
 Think through:
 - What does the explorer need to map?
@@ -95,13 +112,13 @@ actions.write(actionId, 'result', '<your structured plan>')
 
 Format your plan clearly — the other agents will read it via `actions.get(taskId)`.
 
-### 5. Complete your action
+### 6. Complete your action
 
 ```
 actions.complete(actionId, 'Plan defined — delegating to explorer')
 ```
 
-### 6. Delegate in order
+### 7. Delegate in order
 
 Invoke: **Explorer** → **Builder** → **Reviewer**
 
@@ -110,7 +127,7 @@ After each agent completes, read their output:
 actions.get(taskId)   → read the latest completed action and its sections
 ```
 
-### 7. Handle a Reviewer block
+### 8. Handle a Reviewer block
 
 If the reviewer blocks the task:
 1. Read the `blockers` section from the reviewer's action
@@ -118,7 +135,7 @@ If the reviewer blocks the task:
 3. After the builder completes the fix, re-invoke the reviewer
 4. Do NOT mark the task done until the reviewer explicitly approves
 
-### 8. Close the session
+### 9. Close the session
 
 Once the reviewer approves:
 ```

package/dist/{chunk-LQ7SDMK6.js → chunk-X7FOJOZB.js}

@@ -48,9 +48,9 @@ function applyDefaults(config) {
       custom: [],
       ...c.agents
     },
+    database: c.database ?? { type: "sqlite", path: ".harness/harness.db" },
     storage: {
       dir: ".harness",
-      dbPath: ".harness/harness.db",
       tasks: { adapter: "local" },
       sections: {
         toolsUsed: true,
@@ -79,4 +79,4 @@ export {
   loadConfig,
   defineHarness
 };
-//# sourceMappingURL=chunk-LQ7SDMK6.js.map
+//# sourceMappingURL=chunk-X7FOJOZB.js.map

package/dist/chunk-X7FOJOZB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/config.ts"],"sourcesContent":["import { existsSync } from 'node:fs'\nimport { join } from 'node:path'\nimport { createJiti } from 'jiti'\n\nimport type { HarnessConfig } from '@/types'\n\nconst CONFIG_NAMES = [\n  'agent-harness-kit.config.ts',\n  'agent-harness-kit.config',\n  'agent-harness-kit.config.mjs',\n]\n\nexport function findConfigFile(cwd: string): string | null {\n  for (const name of CONFIG_NAMES) {\n    const candidate = join(cwd, name)\n    if (existsSync(candidate)) return candidate\n  }\n  return null\n}\n\nexport async function loadConfig(cwd: string): Promise<HarnessConfig> {\n  const configPath = findConfigFile(cwd)\n  if (!configPath) {\n    throw new Error('No agent-harness-kit.config found. Run: ahk init')\n  }\n\n  const jiti = createJiti(import.meta.url)\n  const mod = await jiti.import(configPath) as { default?: HarnessConfig } | HarnessConfig\n  const config = (mod as { default?: HarnessConfig }).default ?? (mod as HarnessConfig)\n\n  if (!config || typeof config !== 'object') {\n    throw new Error(`agent-harness-kit.config must export a default HarnessConfig object.`)\n  }\n\n  return applyDefaults(config as HarnessConfig)\n}\n\nexport function defineHarness(config: HarnessConfig): HarnessConfig {\n  return config\n}\n\nfunction applyDefaults(config: HarnessConfig): HarnessConfig {\n  const c = config as Partial<HarnessConfig>\n  return {\n    ...config,\n    provider: c.provider ?? 'claude-code',\n    project: {\n      docsPath: './docs',\n      agentsMd: './AGENTS.md',\n      ...c.project,\n    } as HarnessConfig['project'],\n    agents: {\n      lead: { instructionsPath: null },\n      explorer: { instructionsPath: null },\n      builder: { instructionsPath: null },\n      reviewer: { instructionsPath: null },\n      custom: [],\n      ...c.agents,\n    } as HarnessConfig['agents'],\n    database: c.database ?? { type: 'sqlite' as const, path: '.harness/harness.db' },\n    storage: {\n      dir: '.harness',\n      tasks: { adapter: 'local' as const },\n      sections: {\n        toolsUsed: true,\n        filesModified: true,\n        result: true,\n        blockers: true,\n        nextSteps: false,\n      },\n      markdownFallback: { enabled: true, path: '.harness/current.md' },\n      ...c.storage,\n    } as HarnessConfig['storage'],\n    health: {\n      scriptPath: './health.sh',\n      required: true,\n      ...c.health,\n    },\n    tools: {\n      mcp: { enabled: true, port: 3742 },\n      scripts: { enabled: true, outputDir: './.harness/scripts' },\n      ...c.tools,\n    } as HarnessConfig['tools'],\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAC3B,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAI3B,IAAM,eAAe;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AACF;AAEO,SAAS,eAAe,KAA4B;AACzD,aAAW,QAAQ,cAAc;AAC/B,UAAM,YAAY,KAAK,KAAK,IAAI;AAChC,QAAI,WAAW,SAAS,EAAG,QAAO;AAAA,EACpC;AACA,SAAO;AACT;AAEA,eAAsB,WAAW,KAAqC;AACpE,QAAM,aAAa,eAAe,GAAG;AACrC,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AAEA,QAAM,OAAO,WAAW,YAAY,GAAG;AACvC,QAAM,MAAM,MAAM,KAAK,OAAO,UAAU;AACxC,QAAM,SAAU,IAAoC,WAAY;AAEhE,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,UAAM,IAAI,MAAM,sEAAsE;AAAA,EACxF;AAEA,SAAO,cAAc,MAAuB;AAC9C;AAEO,SAAS,cAAc,QAAsC;AAClE,SAAO;AACT;AAEA,SAAS,cAAc,QAAsC;AAC3D,QAAM,IAAI;AACV,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAU,EAAE,YAAY;AAAA,IACxB,SAAS;AAAA,MACP,UAAU;AAAA,MACV,UAAU;AAAA,MACV,GAAG,EAAE;AAAA,IACP;AAAA,IACA,QAAQ;AAAA,MACN,MAAM,EAAE,kBAAkB,KAAK;AAAA,MAC/B,UAAU,EAAE,kBAAkB,KAAK;AAAA,MACnC,SAAS,EAAE,kBAAkB,KAAK;AAAA,MAClC,UAAU,EAAE,kBAAkB,KAAK;AAAA,MACnC,QAAQ,CAAC;AAAA,MACT,GAAG,EAAE;AAAA,IACP;AAAA,IACA,UAAU,EAAE,YAAY,EAAE,MAAM,UAAmB,MAAM,sBAAsB;AAAA,IAC/E,SAAS;AAAA,MACP,KAAK;AAAA,MACL,OAAO,EAAE,SAAS,QAAiB;AAAA,MACnC,UAAU;AAAA,QACR,WAAW;AAAA,QACX,eAAe;AAAA,QACf,QAAQ;AAAA,QACR,UAAU;AAAA,QACV,WAAW;AAAA,MACb;AAAA,MACA,kBAAkB,EAAE,SAAS,MAAM,MAAM,sBAAsB;AAAA,MAC/D,GAAG,EAAE;AAAA,IACP;AAAA,IACA,QAAQ;AAAA,MACN,YAAY;AAAA,MACZ,UAAU;AAAA,MACV,GAAG,EAAE;AAAA,IACP;AAAA,IACA,OAAO;AAAA,MACL,KAAK,EAAE,SAAS,MAAM,MAAM,KAAK;AAAA,MACjC,SAAS,EAAE,SAAS,MAAM,WAAW,qBAAqB;AAAA,MAC1D,GAAG,EAAE;AAAA,IACP;AAAA,EACF;AACF;","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }