@agenttower/cli 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @agenttower/cli — `atc`
+
+The Agent Tower CLI. Coordinate multiple coding agents working one repo: claim
+scope before editing, get inline conflict verdicts, and share a decision log.
+
+## Install
+
+```bash
+npm i -g @agenttower/cli
+```
+
+## Configure
+
+Get a **frequency token** from the dashboard (https://app.agenttower.dev → your
+project → Mint token), then:
+
+```bash
+export ATC_TOKEN=atcf_…        # required
+# export ATC_API=…            # optional; defaults to the hosted prod API
+```
+
+## Use
+
+```bash
+atc checkin --task "refactor auth"   # contact the Tower, get your callsign + a brief
+atc brief                            # roster + claims + conflicts touching you + NOTAMs
+atc claim "src/auth/**"              # request scope; exit code 3 if it conflicts
+atc squawk "rewriting User model"    # status + heartbeat
+atc note "auth uses JWT, 15min TTL"  # write to the decision log (--pin to pin)
+atc clear ["src/auth/**"]            # release scope (all, or one glob)
+atc checkout                         # leave; releases your claims
+```
+
+Session state lives in `.atc/` in the worktree (gitignore it). Add `--json` to any
+command for machine-readable output (useful in hooks). See the project docs for the
+full protocol.

package/bin/atc.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Thin launcher → compiled CLI. Build with `npm run build` (tsc → dist/).
+require('../dist/index.js');

package/dist/client.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSession = exports.saveSession = exports.DEFAULT_API = void 0;
+exports.loadConfig = loadConfig;
+exports.workspaceId = workspaceId;
+exports.clearSession = clearSession;
+exports.api = api;
+exports.currentBranch = currentBranch;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+/**
+ * Thin client for the Agent Tower /v1 API + local session state.
+ * Config is env-only (ATC_API / ATC_TOKEN). `.atc/` holds:
+ *   workspace.json  { workspaceId }   — persistent takeover identity (ADR-0003)
+ *   session.json    { callsign, sessionToken, api }  — lease-bound; cleared on checkout
+ * Both live in the worktree and must be gitignored.
+ */
+const ATC_DIR = path.join(process.cwd(), '.atc');
+const WORKSPACE_FILE = path.join(ATC_DIR, 'workspace.json');
+const SESSION_FILE = path.join(ATC_DIR, 'session.json');
+/** Prod Tower API. Override with ATC_API (e.g. the dev stack). */
+exports.DEFAULT_API = 'https://mz7tt5ee71.execute-api.us-east-1.amazonaws.com';
+function loadConfig() {
+    return {
+        api: (process.env.ATC_API || exports.DEFAULT_API).replace(/\/$/, ''),
+        token: process.env.ATC_TOKEN ?? '',
+    };
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(file, data) {
+    fs.mkdirSync(ATC_DIR, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+/** Stable per-checkout workspace id (created once, survives checkout). */
+function workspaceId() {
+    const existing = readJson(WORKSPACE_FILE);
+    if (existing?.workspaceId)
+        return existing.workspaceId;
+    const id = `ws_${(0, node_crypto_1.randomUUID)()}`;
+    writeJson(WORKSPACE_FILE, { workspaceId: id });
+    return id;
+}
+const saveSession = (s) => writeJson(SESSION_FILE, s);
+exports.saveSession = saveSession;
+const loadSession = () => readJson(SESSION_FILE);
+exports.loadSession = loadSession;
+function clearSession() {
+    try {
+        fs.rmSync(SESSION_FILE);
+    }
+    catch {
+        /* already gone */
+    }
+}
+async function api(cfg, bearer, method, apiPath, body) {
+    const res = await fetch(`${cfg.api}${apiPath}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${bearer}`,
+            'content-type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = { error: text };
+    }
+    return { status: res.status, ok: res.ok, body: parsed };
+}
+/** Best-effort current git branch for display. */
+function currentBranch() {
+    try {
+        const head = fs.readFileSync(path.join(process.cwd(), '.git', 'HEAD'), 'utf8').trim();
+        const m = /ref:\s+refs\/heads\/(.+)/.exec(head);
+        return m ? m[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * atc — the Agent Tower CLI. Thin client of the hosted /v1 API.
+ * Config: ATC_API + ATC_TOKEN (frequency token from the dashboard). See
+ * docs/AGENT-INTERFACE.md. Exit codes: 0 ok · 1 usage/error · 2 unexpected · 3 conflict.
+ */
+const client_1 = require("./client");
+const VERSION = '0.1.0';
+const COMMANDS = ['checkin', 'brief', 'squawk', 'claim', 'clear', 'note', 'notes', 'checkout', 'config'];
+function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    const tags = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            const boolFlags = ['pin', 'json'];
+            if (boolFlags.includes(key)) {
+                flags[key] = true;
+            }
+            else if (key === 'tag') {
+                if (next) {
+                    tags.push(next);
+                    i++;
+                }
+            }
+            else if (next && !next.startsWith('--')) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags, tags };
+}
+function out(json, human, data) {
+    process.stdout.write(json ? JSON.stringify(data, null, 2) + '\n' : human + '\n');
+}
+function fail(msg, code = 1) {
+    process.stderr.write(`atc: ${msg}\n`);
+    process.exit(code);
+}
+function requireSession() {
+    const s = (0, client_1.loadSession)();
+    if (!s)
+        fail("not checked in — run 'atc checkin' first");
+    return s;
+}
+function renderConflicts(conflicts) {
+    if (!conflicts || conflicts.length === 0)
+        return '✓ no conflicts';
+    return (`⚠ CONFLICT (${conflicts.length}):\n` +
+        conflicts
+            .map((c) => `  ${c.by} holds ${c.theirGlob} (${c.status}, seen ${c.lastSeen}) vs your ${c.glob}`)
+            .join('\n'));
+}
+function printHelp() {
+    process.stdout.write(`atc ${VERSION} — Agent Tower CLI\n\n` +
+        `Usage: atc <command> [args]\n\n` +
+        `  checkin  [--task "..."] [--as <callsign>] [--cli <name>]\n` +
+        `  brief\n` +
+        `  squawk   "<status>" [--code working|blocked|review|mayday]\n` +
+        `  claim    "<glob>"      (exit 3 if it conflicts)\n` +
+        `  clear    ["<glob>"]    (omit glob to release all)\n` +
+        `  note     "<body>" [--tag <t>]... [--pin] [--supersede <id>]\n` +
+        `  notes    [--tag <t>]   list the decision log\n` +
+        `  checkout\n` +
+        `  config\n\n` +
+        `Env: ATC_API, ATC_TOKEN. Add --json for raw output.\n`);
+}
+async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '--help' || cmd === '-h')
+        return printHelp();
+    if (cmd === '--version' || cmd === '-v')
+        return void process.stdout.write(VERSION + '\n');
+    if (!COMMANDS.includes(cmd))
+        fail(`unknown command '${cmd}'. Run 'atc --help'.`);
+    const { positionals, flags, tags } = parseArgs(rest);
+    const json = flags.json === true;
+    const cfg = (0, client_1.loadConfig)();
+    if (cmd === 'config') {
+        return out(json, `api: ${cfg.api || '(unset)'}\ntoken: ${cfg.token ? '(set)' : '(unset)'}`, {
+            api: cfg.api || null,
+            token: cfg.token ? 'set' : null,
+        });
+    }
+    if (!cfg.api || !cfg.token) {
+        fail('ATC_API and ATC_TOKEN must be set (get a frequency token from the dashboard)');
+    }
+    if (cmd === 'checkin') {
+        const r = await (0, client_1.api)(cfg, cfg.token, 'POST', '/v1/sessions', {
+            workspaceId: (0, client_1.workspaceId)(),
+            callsign: flags.as,
+            cli: flags.cli || process.env.ATC_CLI || 'cli',
+            worktree: process.cwd(),
+            branch: (0, client_1.currentBranch)(),
+            task: flags.task,
+        });
+        if (!r.ok)
+            fail(r.body?.error ?? `checkin failed (${r.status})`, 2);
+        (0, client_1.saveSession)({ callsign: r.body.callsign, sessionToken: r.body.sessionToken, api: cfg.api });
+        const c = r.body.brief?.counts ?? {};
+        return out(json, `checked in as ${r.body.callsign} · ${c.sessions ?? 0} on board, ${c.claims ?? 0} claims, ${c.notams ?? 0} notams`, r.body);
+    }
+    const session = requireSession();
+    const tok = session.sessionToken;
+    switch (cmd) {
+        case 'brief': {
+            const r = await (0, client_1.api)(cfg, tok, 'GET', '/v1/brief');
+            if (!r.ok)
+                fail(r.body?.error ?? `brief failed (${r.status})`, 2);
+            const b = r.body;
+            const human = `roster: ${b.roster.map((x) => `${x.callsign}(${x.status})`).join(', ') || '(none)'}\n` +
+                `claims: ${b.claims.map((x) => `${x.callsign}:${x.glob}`).join(', ') || '(none)'}\n` +
+                renderConflicts(b.conflictsWithMine) +
+                `\nnotams: ${b.notams.length}/${b.counts.notams}`;
+            return out(json, human, b);
+        }
+        case 'squawk': {
+            const r = await (0, client_1.api)(cfg, tok, 'POST', '/v1/squawk', {
+                status: positionals.join(' ') || undefined,
+                code: flags.code,
+            });
+            if (!r.ok)
+                fail(r.body?.error ?? `squawk failed (${r.status})`, 2);
+            return out(json, renderConflicts(r.body.conflictsWithMine), r.body);
+        }
+        case 'claim': {
+            const glob = positionals[0];
+            if (!glob)
+                fail('usage: atc claim "<glob>"');
+            const r = await (0, client_1.api)(cfg, tok, 'POST', '/v1/claims', { glob });
+            if (!r.ok)
+                fail(r.body?.error ?? `claim failed (${r.status})`, 2);
+            const conflicts = r.body.conflicts ?? [];
+            out(json, `claimed ${glob}\n${renderConflicts(conflicts)}`, r.body);
+            if (conflicts.length > 0)
+                process.exit(3);
+            return;
+        }
+        case 'clear': {
+            const r = await (0, client_1.api)(cfg, tok, 'POST', '/v1/clear', { glob: positionals[0] });
+            if (!r.ok)
+                fail(r.body?.error ?? `clear failed (${r.status})`, 2);
+            return out(json, `cleared: ${(r.body.cleared ?? []).join(', ') || '(none)'}`, r.body);
+        }
+        case 'note': {
+            const body = positionals.join(' ');
+            if (!body)
+                fail('usage: atc note "<body>" [--tag t] [--pin] [--supersede <id>]');
+            const supersedes = typeof flags.supersede === 'string' ? flags.supersede : undefined;
+            const r = await (0, client_1.api)(cfg, tok, 'POST', '/v1/notams', { body, tags, pinned: flags.pin === true, supersedes });
+            if (!r.ok)
+                fail(r.body?.error ?? `note failed (${r.status})`, 2);
+            return out(json, `noted (${r.body.id})`, r.body);
+        }
+        case 'notes': {
+            const q = tags[0] ? `?tag=${encodeURIComponent(tags[0])}` : '';
+            const r = await (0, client_1.api)(cfg, tok, 'GET', `/v1/notams${q}`);
+            if (!r.ok)
+                fail(r.body?.error ?? `notes failed (${r.status})`, 2);
+            const human = (r.body.notams ?? [])
+                .map((n) => `${n.pinned ? '📌 ' : ''}[${n.id}] ${n.body}${n.tags?.length ? '  #' + n.tags.join(' #') : ''}`)
+                .join('\n') || '(no notams)';
+            return out(json, human, r.body);
+        }
+        case 'checkout': {
+            const r = await (0, client_1.api)(cfg, tok, 'POST', '/v1/checkout');
+            (0, client_1.clearSession)();
+            if (!r.ok)
+                fail(r.body?.error ?? `checkout failed (${r.status})`, 2);
+            return out(json, 'checked out', r.body);
+        }
+        default:
+            fail(`command '${cmd}' not wired`);
+    }
+}
+main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`atc: ${err?.message ?? err}\n`);
+    process.exit(2);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@agenttower/cli",
+  "version": "0.1.0",
+  "description": "atc — the Agent Tower CLI. Coordinate multiple coding agents on one repo (claims, conflicts, decision log).",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/manateeit/agent-tower.git", "directory": "cli" },
+  "homepage": "https://app.agenttower.dev",
+  "keywords": ["agent-tower", "atc", "coding-agents", "coordination", "cli", "claude", "mcp"],
+  "type": "commonjs",
+  "bin": { "atc": "bin/atc.js" },
+  "files": ["bin", "dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.10",
+    "typescript": "^5.6.2"
+  }
+}