agent-kanban 1.0.0

package/dist/skills/agent-kanban/SKILL.md

@@ -0,0 +1,116 @@
+# Agent Kanban — Task Management Skill
+
+Use the `agent-kanban` CLI (alias `ak`) to manage tasks on your kanban board.
+
+## Setup
+
+```bash
+npm install -g agent-kanban
+ak config set api-url https://your-instance.pages.dev
+ak config set api-key <your-api-key>
+```
+
+## Workflow
+
+When the daemon assigns you a task, you receive the task ID. Follow this flow:
+
+### 1. View the task
+
+```bash
+ak task list --format json
+```
+
+Find your assigned task and read the details.
+
+### 2. Claim the task
+
+```bash
+ak task claim <task-id> --agent-name <your-name>
+```
+
+This confirms you are starting work and moves the task to "In Progress."
+
+### 3. Do the work
+
+Read the task description, implement the changes, run tests, etc.
+
+### 4. Log progress
+
+```bash
+ak task log <task-id> "Investigating the auth flow..."
+ak task log <task-id> "Root cause: breaking change in v2.3"
+```
+
+### 5. Complete the task
+
+```bash
+ak task complete <task-id> \
+  --result "Fixed JWT claim namespace" \
+  --pr-url "https://github.com/org/repo/pull/42" \
+  --agent-name <your-name>
+```
+
+## Task Lifecycle
+
+```
+Todo ──assign(daemon)──→ Todo (assigned) ──claim(agent)──→ In Progress
+  → In Review (review) → Done (complete)
+  → Cancelled (cancel at any stage)
+  → Todo (release — on crash or timeout)
+```
+
+- **assign**: Daemon locks the task to you. Status stays `todo`, but no other agent can take it.
+- **claim**: You confirm you're starting. Status moves to `in_progress`.
+- **complete**: You're done. Status moves to `done`.
+- **review**: Move to `in_review` for human review before completing.
+
+## Creating Subtasks
+
+When you discover follow-up work, create a task:
+
+```bash
+ak task create \
+  --title "Fix shared-lib JWT claim namespace" \
+  --priority high \
+  --agent-name <your-name>
+```
+
+Log the relationship:
+
+```bash
+ak task log <original-task-id> "Created subtask for shared-lib fix"
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `task create --title <t>` | Create a task (optional: --priority, --labels, --input) |
+| `task list` | List tasks (optional: --status, --label, --format) |
+| `task claim <id>` | Claim an assigned task — start working |
+| `task log <id> <msg>` | Add a progress log entry |
+| `task review <id>` | Move task to In Review |
+| `task complete <id>` | Mark task done (optional: --result, --pr-url) |
+| `task cancel <id>` | Cancel a task |
+| `board list` | List all boards |
+| `board view` | Show the kanban board |
+| `config set <key> <val>` | Set api-url or api-key |
+
+## Smart Defaults
+
+- Output is JSON when piped (not a TTY), text in interactive terminals
+- Use `--format json` to force JSON output
+
+## Error Handling
+
+- **401 Unauthorized**: Check your API key with `ak config get api-key`
+- **409 Conflict**: Task is already claimed or not assigned to you
+- **404 Not Found**: Task ID doesn't exist — check with `task list`
+
+## Best Practices
+
+1. Always claim before working — don't start without claiming
+2. Log progress frequently — humans monitor the board
+3. Create subtasks when you find dependency gaps
+4. Include PR URLs when completing — it closes the loop
+5. Use meaningful agent names for traceability

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export interface UsageWindow {
+    utilization: number;
+    resets_at: string;
+}
+export interface UsageInfo {
+    five_hour?: UsageWindow;
+    seven_day?: UsageWindow;
+    seven_day_sonnet?: UsageWindow;
+    seven_day_opus?: UsageWindow;
+    updated_at: string;
+}

package/dist/types.js

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

package/dist/usage.d.ts

@@ -0,0 +1,2 @@
+import type { UsageInfo } from "./types.js";
+export declare function getUsage(): Promise<UsageInfo | null>;

package/dist/usage.js

@@ -0,0 +1,66 @@
+import { execSync } from "child_process";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir, platform } from "os";
+const CREDENTIALS_PATH = join(homedir(), ".claude", ".credentials.json");
+const USAGE_API = "https://api.anthropic.com/api/oauth/usage";
+const CACHE_TTL_MS = 5 * 60 * 1000;
+let cachedUsage = null;
+let cachedAt = 0;
+let cachedToken = null;
+function parseToken(raw) {
+    const creds = JSON.parse(raw);
+    return creds.claudeAiOauth?.accessToken || null;
+}
+function readOAuthToken() {
+    if (cachedToken)
+        return cachedToken;
+    try {
+        if (platform() === "darwin") {
+            const raw = execSync('security find-generic-password -s "Claude Code-credentials" -w', { stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+            cachedToken = parseToken(raw);
+        }
+        else {
+            cachedToken = parseToken(readFileSync(CREDENTIALS_PATH, "utf-8"));
+        }
+        return cachedToken;
+    }
+    catch {
+        return null;
+    }
+}
+export async function getUsage() {
+    if (cachedUsage && Date.now() - cachedAt < CACHE_TTL_MS) {
+        return cachedUsage;
+    }
+    const token = readOAuthToken();
+    if (!token)
+        return cachedUsage;
+    try {
+        const res = await fetch(USAGE_API, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "anthropic-beta": "oauth-2025-04-20",
+            },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok) {
+            console.error(`[WARN] Usage API returned ${res.status}`);
+            return cachedUsage;
+        }
+        const data = await res.json();
+        cachedUsage = {
+            ...data.five_hour && { five_hour: data.five_hour },
+            ...data.seven_day && { seven_day: data.seven_day },
+            ...data.seven_day_sonnet && { seven_day_sonnet: data.seven_day_sonnet },
+            ...data.seven_day_opus && { seven_day_opus: data.seven_day_opus },
+            updated_at: new Date().toISOString(),
+        };
+        cachedAt = Date.now();
+        return cachedUsage;
+    }
+    catch (err) {
+        console.error(`[WARN] Failed to fetch usage: ${err.message}`);
+        return cachedUsage;
+    }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "agent-kanban",
+  "version": "1.0.0",
+  "description": "CLI for Agent Kanban — agent-first cross-project task board",
+  "type": "module",
+  "bin": {
+    "agent-kanban": "./dist/index.js",
+    "ak": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+"@auth/agent": "^0.3.0",
+    "commander": "^13.0.0",
+    "jose": "^6.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,165 @@
+import { SignJWT } from "jose";
+import { randomUUID } from "crypto";
+import type { UsageInfo } from "./types.js";
+import { getConfigValue } from "./config.js";
+
+export class ApiClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor() {
+    const url = getConfigValue("api-url");
+    const key = getConfigValue("api-key");
+    if (!url) throw new Error("API URL not configured. Run: agent-kanban config set api-url <url>");
+    if (!key) throw new Error("API key not configured. Run: agent-kanban config set api-key <key>");
+    this.baseUrl = url.replace(/\/$/, "");
+    this.apiKey = key;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(10000),
+    });
+
+    const data = await res.json() as T & { error?: { code: string; message: string } };
+
+    if (!res.ok) {
+      const msg = (data as any).error?.message || `HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    return data;
+  }
+
+  // Tasks
+  createTask(input: Record<string, unknown>) { return this.request("POST", "/api/tasks", input); }
+  listTasks(params?: Record<string, string>) {
+    const qs = params ? "?" + new URLSearchParams(params).toString() : "";
+    return this.request("GET", `/api/tasks${qs}`);
+  }
+  getTask(id: string) { return this.request("GET", `/api/tasks/${id}`); }
+  claimTask(id: string, agentName?: string) {
+    return this.request("POST", `/api/tasks/${id}/claim`, agentName ? { agent_id: agentName } : {});
+  }
+  completeTask(id: string, body: Record<string, unknown>) {
+    return this.request("POST", `/api/tasks/${id}/complete`, body);
+  }
+  releaseTask(id: string) {
+    return this.request("POST", `/api/tasks/${id}/release`);
+  }
+  cancelTask(id: string, body: Record<string, unknown> = {}) {
+    return this.request("POST", `/api/tasks/${id}/cancel`, body);
+  }
+  reviewTask(id: string, body: Record<string, unknown> = {}) {
+    return this.request("POST", `/api/tasks/${id}/review`, body);
+  }
+  assignTask(id: string, agentId: string) {
+    return this.request("POST", `/api/tasks/${id}/assign`, { agent_id: agentId });
+  }
+  addLog(taskId: string, detail: string, agentName?: string) {
+    return this.request("POST", `/api/tasks/${taskId}/logs`, { detail, agent_id: agentName });
+  }
+
+  // Machines
+  registerMachine(info: { name: string; os: string; version: string; runtimes: string[] }) {
+    return this.request<{ id: string; name: string }>("POST", "/api/machines", info);
+  }
+  heartbeat(machineId: string, info: { version?: string; runtimes?: string[]; usage_info?: UsageInfo | null }) {
+    return this.request("POST", `/api/machines/${machineId}/heartbeat`, info);
+  }
+
+  // Agents
+  registerAgent(agentId: string, publicKey?: string, runtime?: string, model?: string) {
+    return this.request("POST", "/api/agents", { agent_id: agentId, public_key: publicKey, runtime, model });
+  }
+  listAgents() { return this.request("GET", "/api/agents"); }
+
+  // Boards
+  createBoard(input: { name: string; description?: string }) {
+    return this.request("POST", "/api/boards", input);
+  }
+  listBoards() { return this.request<any[]>("GET", "/api/boards"); }
+  getBoardByName(name: string) { return this.request("GET", `/api/boards?name=${encodeURIComponent(name)}`); }
+  getBoard(boardId: string) { return this.request("GET", `/api/boards/${boardId}`); }
+
+  // Repositories
+  createRepository(input: { name: string; url: string }) {
+    return this.request("POST", "/api/repositories", input);
+  }
+  listRepositories() { return this.request<any[]>("GET", "/api/repositories"); }
+
+  // Agent usage
+  updateAgentUsage(agentId: string, usage: { input_tokens: number; output_tokens: number; cache_read_tokens: number; cache_creation_tokens: number; cost_micro_usd: number }) {
+    return this.request("PATCH", `/api/agents/${agentId}/usage`, usage);
+  }
+
+  // Messages
+  sendMessage(taskId: string, body: { agent_id: string; role: string; content: string }) {
+    return this.request("POST", `/api/tasks/${taskId}/messages`, body);
+  }
+  getMessages(taskId: string, since?: string) {
+    const qs = since ? `?since=${encodeURIComponent(since)}` : "";
+    return this.request<any[]>("GET", `/api/tasks/${taskId}/messages${qs}`);
+  }
+}
+
+export class AgentClient {
+  private baseUrl: string;
+  private agentId: string;
+  private privateKey: CryptoKey;
+
+  constructor(baseUrl: string, agentId: string, privateKey: CryptoKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.agentId = agentId;
+    this.privateKey = privateKey;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const jwt = await new SignJWT({ sub: this.agentId, jti: randomUUID(), aud: this.baseUrl })
+      .setProtectedHeader({ alg: "EdDSA", typ: "agent+jwt" })
+      .setIssuedAt()
+      .setExpirationTime("60s")
+      .sign(this.privateKey);
+
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${jwt}`,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(10000),
+    });
+
+    const data = await res.json() as T & { error?: { code: string; message: string } };
+
+    if (!res.ok) {
+      const msg = (data as any).error?.message || `HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    return data;
+  }
+
+  // Tasks
+  releaseTask(id: string) {
+    return this.request("POST", `/api/tasks/${id}/release`);
+  }
+
+  // Agent usage
+  updateAgentUsage(usage: { input_tokens: number; output_tokens: number; cache_read_tokens: number; cache_creation_tokens: number; cost_micro_usd: number }) {
+    return this.request("PATCH", `/api/agents/${this.agentId}/usage`, usage);
+  }
+
+  // Messages
+  sendMessage(taskId: string, body: { agent_id: string; role: string; content: string }) {
+    return this.request("POST", `/api/tasks/${taskId}/messages`, body);
+  }
+}

package/src/commands/link.ts

@@ -0,0 +1,60 @@
+import { execSync } from "child_process";
+import { basename } from "path";
+import type { Command } from "commander";
+import { ApiClient } from "../client.js";
+import { setLink } from "../links.js";
+
+function getGitRepoRoot(): string {
+  return execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+}
+
+function getGitRemoteUrl(): string | undefined {
+  try {
+    return execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export function registerLinkCommand(program: Command) {
+  program
+    .command("link")
+    .description("Register current repo and map local directory to it")
+    .action(async () => {
+      let repoRoot: string;
+      try {
+        repoRoot = getGitRepoRoot();
+      } catch {
+        console.error("Not a git repository. Run this command from a git repo.");
+        process.exit(1);
+      }
+
+      const remoteUrl = getGitRemoteUrl();
+      if (!remoteUrl) {
+        console.error("No git remote found. Add an origin remote first.");
+        process.exit(1);
+      }
+
+      const client = new ApiClient();
+      let repo: any;
+      try {
+        repo = await client.createRepository({
+          name: basename(repoRoot),
+          url: remoteUrl,
+        });
+        console.log(`Registered repository: ${remoteUrl}`);
+      } catch (err: any) {
+        if (err.message?.includes("UNIQUE")) {
+          // Already exists — find it
+          const repos = await client.listRepositories();
+          repo = repos.find((r: any) => r.url === remoteUrl);
+          console.log(`Repository already registered: ${remoteUrl}`);
+        } else {
+          throw err;
+        }
+      }
+
+      setLink(repo.id, repoRoot);
+      console.log(`Linked repository ${repo.id} → ${repoRoot}`);
+    });
+}

package/src/commands/start.ts

@@ -0,0 +1,56 @@
+import { createInterface } from "readline";
+import type { Command } from "commander";
+import { startDaemon } from "../daemon.js";
+import { setConfigValue, getConfigValue, deleteConfigValue } from "../config.js";
+
+function confirm(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === "y");
+    });
+  });
+}
+
+export function registerStartCommand(program: Command) {
+  program
+    .command("start")
+    .description("Start the Machine daemon — auto-claim and execute tasks")
+    .option("--api-url <url>", "API server URL")
+    .option("--api-key <key>", "Machine API key")
+    .option("--max-concurrent <n>", "Max concurrent agents", "3")
+    .option("--agent-cli <cmd>", "Agent CLI command to spawn", "claude")
+    .option("--poll-interval <ms>", "Poll interval in ms", "10000")
+    .option("--task-timeout <ms>", "Task timeout in ms (0 to disable)", "7200000")
+    .action(async (opts) => {
+      if (opts.apiUrl) setConfigValue("api-url", opts.apiUrl);
+      if (opts.apiKey) {
+        const oldKey = getConfigValue("api-key");
+        if (oldKey && oldKey !== opts.apiKey && getConfigValue("machine-id")) {
+          const machineId = getConfigValue("machine-id");
+          const yes = await confirm(
+            `This machine is already registered (${machineId}) with a different API key.\nSwitch to the new key and re-register? [y/N] `
+          );
+          if (!yes) {
+            console.log("Aborted.");
+            process.exit(0);
+          }
+          deleteConfigValue("machine-id");
+        }
+        setConfigValue("api-key", opts.apiKey);
+      }
+
+      if (!getConfigValue("api-url") || !getConfigValue("api-key")) {
+        console.error("API URL and key required. Pass --api-url and --api-key, or set via: ak config set api-url <url>");
+        process.exit(1);
+      }
+
+      await startDaemon({
+        maxConcurrent: parseInt(opts.maxConcurrent, 10),
+        agentCli: opts.agentCli,
+        pollInterval: parseInt(opts.pollInterval, 10),
+        taskTimeout: parseInt(opts.taskTimeout, 10),
+      });
+    });
+}

package/src/config.ts

@@ -0,0 +1,43 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const CONFIG_DIR = join(homedir(), ".agent-kanban");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+interface Config {
+  "api-url"?: string;
+  "api-key"?: string;
+  "machine-id"?: string;
+}
+
+export function readConfig(): Config {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config: Config): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+
+export function getConfigValue(key: string): string | undefined {
+  return readConfig()[key as keyof Config];
+}
+
+export function setConfigValue(key: string, value: string): void {
+  const config = readConfig();
+  (config as Record<string, string>)[key] = value;
+  writeConfig(config);
+}
+
+export function deleteConfigValue(key: string): void {
+  const config = readConfig();
+  delete (config as Record<string, string>)[key];
+  writeConfig(config);
+}
+
+export const PID_FILE = join(CONFIG_DIR, "daemon.pid");