@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/worktree.js

@@ -0,0 +1,140 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const git = (args, cwd) => new Promise((resolve) => {
+    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    const cap = (d) => { if (out.length < 4000)
+        out += String(d); };
+    child.stdout.on('data', cap);
+    child.stderr.on('data', cap);
+    child.on('close', (c) => resolve({ code: c ?? 1, out: out.trim() }));
+    child.on('error', (e) => resolve({ code: 1, out: String(e) }));
+});
+/** `BIR-0282` → `agent/bir-0282`. Stable, so re-work on a card returns to the same branch. */
+const branchFor = (card) => `agent/${card.toLowerCase().replace(/[^a-z0-9._-]+/g, '-')}`;
+export async function ensureWorktree(repo, card, onStep, 
+/**
+ * Where work is cut FROM, which is not always the repo's default branch. Some projects have agents
+ * branch from `dev` — the lead owns it, agents take the latest and hand a feature branch back.
+ * Cutting from the default instead would base every card on the wrong history, and the merge
+ * would look like a much bigger change than it is.
+ */
+base) {
+    if (!existsSync(join(repo, '.git')))
+        return null; // not a git repo; work in place
+    const branch = branchFor(card);
+    // Beside the repo, not inside it: a worktree within the working tree confuses status, ignore
+    // rules and every tool that walks the directory.
+    const path = join(repo, '..', `.worktrees-${basenameOf(repo)}`, branch.replace(/\//g, '-'));
+    if (existsSync(path)) {
+        onStep(`reusing worktree ${branch}`);
+        return { path, branch, created: false };
+    }
+    // Branch from the default branch as the REMOTE has it, so an agent does not inherit whatever
+    // half-finished state a local checkout happens to be in. A repo with no remote is a normal
+    // case though — a scratch project, a fresh init — so fall back to the local branch rather
+    // than giving up on isolation entirely, which is the part that matters.
+    const fallback = await defaultBranch(repo);
+    const from = base ?? fallback;
+    await git(['fetch', '--quiet', 'origin', from], repo);
+    const exists = async (ref) => (await git(['rev-parse', '--verify', ref], repo)).code === 0;
+    let start = (await exists(`origin/${from}`)) ? `origin/${from}` : (await exists(from)) ? from : '';
+    if (!start) {
+        // A declared base that does not exist is a configuration mistake, and it used to be absorbed
+        // silently: the branch fell through to HEAD, meaning whatever this checkout happened to be
+        // sitting on — someone else's half-finished branch as easily as anything. The card then looked
+        // normal and its diff was against the wrong history. Say it, and fall back to the repo's own
+        // default rather than to an accident.
+        onStep(`base "${from}" is not on origin or local — falling back to ${fallback}`);
+        start = (await exists(`origin/${fallback}`)) ? `origin/${fallback}` : (await exists(fallback)) ? fallback : 'HEAD';
+    }
+    const made = await git(['worktree', 'add', '-B', branch, path, start], repo);
+    if (made.code !== 0) {
+        onStep(`could not make a worktree: ${made.out.split('\n').slice(-1)[0]}`);
+        return null;
+    }
+    // Make `origin` fetch-only IN THIS WORKTREE.
+    //
+    // Up to here, "do not publish from the shell" was a PreToolUse hook reading command text, and
+    // it says itself that nothing reading strings can be airtight: `git -C`, an alias, a line
+    // inside a script. What made that a real hole rather than a theoretical one is the machine —
+    // Xcode ships a system gitconfig with `credential.helper = osxkeychain`, and `gh` is logged in
+    // with `repo` and `workflow` scope, so any push that got past the regex would quietly find a
+    // working credential and succeed.
+    //
+    // A dead pushurl closes it without reading anything: `git push`, `git push origin`, `git push
+    // -f origin main` all fail immediately in this worktree, however they are spelled and whatever
+    // wrapper they are spelled inside. Fetch is untouched, so the agent can still stay current
+    // with the base branch, which is work it legitimately does. And push_branch is unaffected
+    // because it never pushes to `origin`: it builds a one-shot authenticated URL of its own.
+    //
+    // This is not the fence either — branch protection on the remote is. It is the difference
+    // between a door that is asked not to be opened and one with no handle on this side.
+    const pushBlocked = await git(['config', '--local', 'remote.origin.pushurl', 'no-push/publish-with-the-push_branch-tool'], path);
+    if (pushBlocked.code !== 0) {
+        // Said out loud rather than swallowed: the hook still refuses shell pushes, but this
+        // worktree is one layer thinner than the others and that is worth knowing.
+        onStep(`could not make origin fetch-only here — shell pushes are blocked by the guard only`);
+    }
+    onStep(`worktree ${branch} from ${start}`);
+    return { path, branch, created: true, from: start };
+}
+async function defaultBranch(repo) {
+    const head = await git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], repo);
+    if (head.code === 0 && head.out)
+        return head.out.replace(/^origin\//, '');
+    for (const guess of ['main', 'master', 'dev']) {
+        if ((await git(['rev-parse', '--verify', `origin/${guess}`], repo)).code === 0)
+            return guess;
+    }
+    return 'main';
+}
+const basenameOf = (p) => p.replace(/\/+$/, '').split('/').pop() || 'repo';
+/** Told to the agent so it knows where it is and what it is on. */
+export function worktreeBrief(tree) {
+    if (!tree)
+        return '';
+    return (`\n\nYou are working in ${tree.path} on branch ${tree.branch}` +
+        `${tree.from ? `, branched from ${tree.from}` : ''} — a checkout of your own. Commit here as ` +
+        `you go, then publish with push_branch. Do not touch any other checkout on this machine: ` +
+        `someone may be using it.`);
+}
+/**
+ * Remove a card's worktree once the card is finished with.
+ *
+ * Worktrees accumulate: one repository here had fourteen, most of them long-done cards, each a
+ * full checkout on disk. But a worktree is also the ONLY copy of anything an agent has committed
+ * and not published, so this refuses far more readily than it deletes.
+ *
+ * It removes only when there is nothing to lose: no uncommitted changes, no untracked files, and
+ * no commit that is not already on the remote. Anything else is left exactly where it is, and the
+ * reason is returned so a person can be told rather than left to find an orphan later.
+ */
+export async function releaseWorktree(repo, card, onStep) {
+    const branch = branchFor(card);
+    const path = join(repo, '..', `.worktrees-${basenameOf(repo)}`, branch.replace(/\//g, '-'));
+    if (!existsSync(path))
+        return { removed: false, why: 'there was no worktree' };
+    const dirty = await git(['status', '--porcelain'], path);
+    if (dirty.code !== 0)
+        return { removed: false, why: `could not read its status (${dirty.out.split('\n')[0]})` };
+    if (dirty.out.trim())
+        return { removed: false, why: 'it has uncommitted changes' };
+    // Commits that exist here and nowhere else. `--remotes` covers a branch pushed under any name,
+    // so a published branch counts as safe however push_branch named it.
+    const unpushed = await git(['log', '--oneline', '--not', '--remotes'], path);
+    if (unpushed.code === 0 && unpushed.out.trim()) {
+        const n = unpushed.out.trim().split('\n').length;
+        return { removed: false, why: `it has ${n} commit${n === 1 ? '' : 's'} that are not on the remote` };
+    }
+    const gone = await git(['worktree', 'remove', '--force', path], repo);
+    if (gone.code !== 0)
+        return { removed: false, why: `git would not remove it (${gone.out.split('\n')[0]})` };
+    // The branch too — it pointed at the same published commits, and leaving hundreds of agent/*
+    // branches behind makes a real branch list unreadable.
+    await git(['branch', '-D', branch], repo);
+    onStep(`released worktree ${branch}`);
+    return { removed: true, why: 'nothing was left on it' };
+}
+//# sourceMappingURL=worktree.js.map

package/dist/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@onepointfour-packs/flaredeck-agent",
+  "version": "0.1.0",
+  "description": "Run a FlareDeck agent on your own machine: it picks up cards assigned to it, works each one in a checkout of its own, and reports back on the card.",
+  "type": "module",
+  "bin": {
+    "flaredeck-agent": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "python",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
+    "ink": "^7.1.1",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.3.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.3.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://app.flaredeck.app",
+  "bugs": {
+    "url": "https://app.flaredeck.app"
+  },
+  "author": "Phiresky",
+  "keywords": [
+    "flaredeck",
+    "agent",
+    "kanban",
+    "mcp",
+    "claude",
+    "gemini",
+    "automation",
+    "coding-agent"
+  ]
+}

package/python/sidecar.py

@@ -0,0 +1,178 @@
+"""The Gemini half of the harness.
+
+The harness is TypeScript; the Antigravity SDK is Python with a compiled runtime binary, so this
+runs as a child process and speaks JSON Lines over stdin/stdout. It is deliberately thin: it owns
+no policy and makes no decisions. Every tool call is referred back to Node over localhost, so
+gitGuard, secretGuard and the Jev gate keep ONE implementation rather than being rewritten here
+and drifting from the originals.
+
+  Node → here   {"type":"run","brief":...,"cwd":...,"resume":...,"model":...,"guard_url":...}
+                {"type":"steer","text":...}
+                {"type":"stop"}
+  here → Node   {"type":"event","kind":"text"|"tool"|"todo"|"usage"|"done"|"ready", ...}
+                {"type":"fatal","message":...}
+
+The event names are the harness's own `AgentEvent` union, not Antigravity's, because that union
+was written for its consumers and already has no vendor in it.
+"""
+import asyncio
+import json
+import os
+import sys
+import urllib.request
+
+from contextlib import AsyncExitStack
+
+from google.antigravity import Agent, LocalAgentConfig
+from google.antigravity.hooks import policy, post_tool_call, pre_tool_call_decide
+from google.antigravity.types import HookResult, McpStreamableHttpServer
+
+GUARD_URL = ""
+
+
+def emit(obj: dict) -> None:
+    """One JSON object per line, flushed — Node is reading this as a stream, not a file."""
+    sys.stdout.write(json.dumps(obj) + "\n")
+    sys.stdout.flush()
+
+
+def ask_node(path: str, payload: dict) -> dict:
+    """Put the decision where the policy already lives. A guard that cannot be reached DENIES:
+    an agent that keeps working because its supervisor is unreachable is the failure this
+    harness exists to prevent."""
+    try:
+        req = urllib.request.Request(
+            f"{GUARD_URL}{path}",
+            data=json.dumps(payload).encode(),
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read().decode())
+    except Exception as e:  # noqa: BLE001 - any failure here must be closed, not loud
+        return {"allow": False, "message": f"The harness could not be reached to approve this ({e})."}
+
+
+@pre_tool_call_decide
+async def gate(data):
+    """Antigravity's shell tool is `run_command` and its argument is `CommandLine` — NOT
+    `command`. Reading the wrong key yields an empty string, which every guard would wave
+    through, so the name is asserted rather than assumed."""
+    args = dict(getattr(data, "args", {}) or {})
+    verdict = ask_node("/tool-call", {
+        "name": str(getattr(data, "name", "")),
+        # Which server a tool came from: the harness pre-approves FlareDeck's READ tools the same
+        # way it does for the other engine, and cannot tell them apart without this.
+        "server": str(getattr(data, "server_name", "") or ""),
+        "args": args,
+    })
+    if not verdict.get("allow", False):
+        return HookResult(allow=False, message=verdict.get("message", "Refused by the harness."))
+    modified = verdict.get("modified_args")
+    if modified:
+        return HookResult(allow=True, modified_args=modified)
+    return HookResult(allow=True)
+
+
+@post_tool_call
+async def seen(data):
+    """PostToolCallHook is an InspectHook: it can SEE a result and cannot change it. So this
+    reports a secret that came back rather than redacting it — the harness decides what to do
+    about an engine that cannot redact, and says so out loud rather than pretending."""
+    result = getattr(data, "result", None)
+    if result is not None:
+        ask_node("/tool-result", {"name": str(getattr(data, "name", "")), "result": str(result)[:20000]})
+    return None
+
+
+async def main() -> None:
+    global GUARD_URL
+    first = json.loads(sys.stdin.readline())
+    if first.get("type") != "run":
+        emit({"type": "fatal", "message": f"expected a run message, got {first.get('type')!r}"})
+        return
+    GUARD_URL = first["guard_url"]
+
+    kwargs = {
+        "system_instructions": first.get("system_instructions") or "",
+        "policies": [policy.allow_all()],   # the gate above is the policy; this just defers to it
+        "hooks": [gate, seen],
+        "workspaces": [first["cwd"]],
+    }
+    # FlareDeck, reached over HTTP with the HARNESS's own token — so the model's tools act as the
+    # same account the harness listens as. Two identities for one agent is a thing that has gone
+    # wrong here before and is hard to see once it has.
+    mcp = [
+        McpStreamableHttpServer(name=m["name"], url=m["url"], headers=m.get("headers") or {})
+        for m in (first.get("mcp") or [])
+    ]
+    if mcp:
+        kwargs["mcp_servers"] = mcp
+    if os.environ.get("GOOGLE_GENAI_USE_VERTEXAI"):
+        kwargs.update(vertex=True, project=os.environ["GOOGLE_CLOUD_PROJECT"],
+                      location=os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1"))
+    else:
+        kwargs["api_key"] = os.environ["GEMINI_API_KEY"]
+    if first.get("model"):
+        kwargs["model"] = first["model"]
+    if first.get("resume"):
+        kwargs["conversation_id"] = first["resume"]
+
+    # A conversation lives in the Antigravity runtime, which dies with this process — so a session
+    # id the harness stored before a restart names something that no longer exists, and asking for
+    # it fails the whole card: "Failed to create agent: conversation ... not found". The card is
+    # not lost by that. Its whole thread is on FlareDeck and it is perfectly workable from a fresh
+    # conversation, so an unusable resume is dropped rather than raised.
+    #
+    # Both the construction AND the entering are covered, because the runtime is only reached on
+    # entry — that is where the failure actually surfaces.
+    stack = AsyncExitStack()
+    try:
+        agent = await stack.enter_async_context(Agent(LocalAgentConfig(**kwargs)))
+    except Exception as e:  # noqa: BLE001
+        if not kwargs.get("conversation_id") or "not found" not in str(e).lower():
+            raise
+        gone = str(kwargs.pop("conversation_id"))[:8]
+        await stack.aclose()
+        # Said out loud: an agent that silently forgot a conversation would re-read the card and
+        # quietly redo work it had already reported.
+        emit({"type": "event", "kind": "text",
+              "text": f"The earlier session for this card is gone ({gone}…), so this starts fresh from the card and its comments."})
+        stack = AsyncExitStack()
+        agent = await stack.enter_async_context(Agent(LocalAgentConfig(**kwargs)))
+
+    async with stack:
+        # "connected", not "configured", and it is not a guess: a server that fails to load raises
+        # during Agent construction ("MCP load failed for flaredeck: ..."), so reaching this line
+        # means every server in `mcp` is really attached to THIS session. The harness refuses to
+        # work a card otherwise, and it is right to — the tool names come from the harness's own
+        # discovery a moment earlier, because the SDK gives no way to enumerate a session's tools.
+        emit({"type": "event", "kind": "ready", "tools": first.get("tool_names") or [],
+              "mcp": [{"name": m.name, "status": "connected"} for m in mcp],
+              "apiKeySource": "vertex" if kwargs.get("vertex") else "gemini-api-key",
+              "permissionMode": "harness-gated",
+              "sessionId": str(getattr(agent, "conversation_id", "") or "")})
+        response = await agent.chat(first["brief"])
+        text = await response.text()
+        if text:
+            emit({"type": "event", "kind": "text", "text": text})
+        # The session id only exists AFTER the first turn — conversation_id is None until then —
+        # so the ready event above could never carry it, and the harness, finding no session,
+        # skipped the handover entirely: "no session to write a handover from". That handover is
+        # where an agent writes its notes and closes the card, so the work half ran and the
+        # report half silently never did. Sending ready again with the real id is enough: the
+        # harness stores a session id from any ready that has one.
+        session_id = str(getattr(agent, "conversation_id", "") or "")
+        if session_id:
+            emit({"type": "event", "kind": "ready", "tools": first.get("tool_names") or [],
+                  "mcp": [{"name": m.name, "status": "connected"} for m in mcp],
+                  "apiKeySource": "vertex" if kwargs.get("vertex") else "gemini-api-key",
+                  "permissionMode": "harness-gated", "sessionId": session_id})
+        emit({"type": "event", "kind": "done", "ok": True, "result": text or ""})
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except Exception as e:  # noqa: BLE001
+        emit({"type": "fatal", "message": str(e)})
+        sys.exit(1)