@onepointfour-packs/flaredeck-agent 0.1.0

package/LICENSE.md

@@ -0,0 +1,14 @@
+# Licence
+
+Copyright © Phiresky. All rights reserved.
+
+This software is provided to let you run an agent against the FlareDeck service. You may
+install and run it, on as many machines as you like, for that purpose.
+
+You may not redistribute it, sell it, or offer it as part of another service, and you may not
+use it to build a competing product. It is published here so that anyone with a FlareDeck
+workspace can install it easily — not as open source.
+
+No warranty of any kind is given, and no liability is accepted for any loss arising from its
+use. An agent runs commands on the machine you put it on; what it does there is yours to
+supervise.

package/README.md

@@ -0,0 +1,102 @@
+# @onepointfour-packs/flaredeck-agent
+
+Runs a FlareDeck agent on your own machine. It watches the board for work assigned to it,
+picks each card up, does it in a checkout of its own, reports back on the card, and asks a
+person when it genuinely needs one.
+
+You need a [FlareDeck](https://app.flaredeck.app) workspace and an agent account in it
+(Users → Add Agent). The agent works as that account: its comments, its branches and its
+pull requests are its own, and you can see everything it did on the card.
+
+## Install
+
+```bash
+npm install -g @anthropic-ai/claude-code @onepointfour-packs/flaredeck-agent
+```
+
+Node 20 or newer. The Claude CLI is what the agent runs on, and it carries its own login — a
+Claude subscription rather than metered API billing, which matters when an agent runs for hours.
+
+## Start
+
+```bash
+cd /path/to/your/repo
+flaredeck-agent login     # once per machine — asks four short questions
+flaredeck-agent           # run it; leave it in tmux or a service
+```
+
+`login` asks which FlareDeck account this machine acts as, authorises GitHub so it can publish
+branches, works out which repositories it may touch, and offers to set an OpenRouter key for the
+command guard. It detects an SSH session and gives you a code to paste instead of opening a
+browser, so a headless box is fine.
+
+## What it does with a card
+
+1. **Works out where the work belongs.** A board can name a repository per component and a
+   branch per environment; the card's own fields then say which repository and which branch.
+   Where a card says nothing, the agent reads it and works it out, and asks a person rather than
+   guessing between several.
+2. **Takes a checkout of its own.** A git worktree per card, on its own branch, cut from the
+   branch that card's environment means. Two agents never share a working tree.
+3. **Does the work and reports on the card.** What it found, what it changed, what it could not
+   do. The account that comments is the account you created.
+4. **Publishes through tools, never the shell.** `push_branch` pushes the branch this card made
+   and nothing else; `open_pull_request` targets the branch the board declared.
+5. **Hands the checkout back** when the card is finished and nothing is left on it.
+
+## Where you point it
+
+Start it **in a repository** and it works that repository. Start it in a **folder of
+repositories** and it works all of them, choosing per card — `login` shows you what it found and
+you tick which ones it may touch. There is no list to maintain: the folder is the declaration.
+
+## What it will not do
+
+These are enforced, not asked for in a prompt:
+
+- **It cannot push from the shell.** `origin` is fetch-only inside each card's worktree, so
+  `git push` fails however it is spelled. Publishing goes through the tools, which can only
+  publish that card's own branch.
+- **It cannot write outside its own checkout.** It may read the neighbouring repositories —
+  that is often how a change is understood — but editing them is refused.
+- **It will not run an irreversible command.** With an OpenRouter key it judges each risky
+  command and refuses what cannot be undone; without one, every risky command stops and asks a
+  person. The guard is never off.
+- **It will not quietly guess.** A card whose repository or branch it cannot establish goes to a
+  person, with what is missing, rather than landing somewhere plausible.
+
+None of this is a substitute for branch protection on your remote. It is the door, not the fence.
+
+## Asking a person
+
+When an agent genuinely needs something only a person has — an access it does not hold, a
+decision about what the product should do, permission for something irreversible — it flags the
+card and the people who can answer are notified, on their phone if they have the app. The ask
+arrives as one short question with the answers as buttons, so it can be answered in a tap.
+
+Before that happens the harness checks whether the agent could have finished the job itself, and
+refuses to interrupt anyone over work it was capable of doing.
+
+## Engines
+
+Claude by default. `flaredeck-agent --agy` runs the same harness on Gemini through Google's
+Antigravity SDK — same tools, same guards, same reporting, so you can compare them on the same
+board. The Python sidecar it needs is installed on first use.
+
+## Commands
+
+| | |
+| --- | --- |
+| `flaredeck-agent` | Run, and keep running |
+| `flaredeck-agent login` | Set this machine up |
+| `flaredeck-agent whoami` | Which account, which repositories, what is switched on |
+| `flaredeck-agent run "<task>"` | One task, right now, without a card |
+| `flaredeck-agent approvals` | Answer what your agents are waiting on |
+| `flaredeck-agent providers` | Keys for the optional small models |
+| `flaredeck-agent secret` | Store a credential the agent may use but never see |
+
+## Where things are kept
+
+`~/.config/flaredeck-agent/` — one file per machine for logins and keys, one per workspace for
+what that agent works on. Nothing is stored in your repository, and no credential is written
+into a config you might copy to another box.

package/dist/agent.d.ts

@@ -0,0 +1,104 @@
+import { query, type HookCallbackMatcher, type HookEvent, type Options } from '@anthropic-ai/claude-agent-sdk';
+import type { Config } from './config.js';
+import { type Decider } from './permissions.js';
+/**
+ * The one place a session is configured.
+ *
+ * Everything still to come — hooks for the supervisor, the event-stream connector, per-role tool
+ * sets, budgets — is another field on the object this builds. Keeping that in a single function
+ * is most of what "a foundation" means here: no second place to remember.
+ */
+/**
+ * What the agent is told about itself before it does anything.
+ *
+ * An agent that has to be ASKED who it is will sometimes not ask. Stating it up front means
+ * identity and workload are facts of the session rather than something the model has to remember
+ * to look up — and `get-outstanding` is named explicitly so the first thing it does is find its
+ * own work rather than wait to be handed some.
+ */
+export declare const AGENT_BRIEF: string;
+/** In-process tool sets, mounted only when the caller has a use for them. */
+export type ToolSet = {
+    server: unknown;
+    toolNames: string[];
+};
+export declare function buildOptions(config: Config, decider: Decider, extra?: Partial<Options>, 
+/** The card's worktree — the only place this turn may write. See sandbox.ts. */
+sandbox?: string, 
+/** Publishing tools, when a job is running. Absent for one-off `run` and `whoami`. */
+git?: ToolSet, 
+/** The harness's own FlareDeck token, handed to the MCP server so the model's tools act as
+ *  the SAME account the harness listens as. */
+token?: string, 
+/** Present only for a LEAD. A worker never receives these tools, so "a worker cannot reach
+ *  across the team" holds because there is nothing to call, not because a prompt asked nicely. */
+team?: ToolSet, 
+/** FlareDeck's tools, served in-process from what the server just listed. */
+flaredeck?: ToolSet, 
+/** Production runs, where this machine names a target. Asking is harmless; running needs a person. */
+runs?: ToolSet, 
+/** Recurring tasks. Asking is harmless: a person's approval is what starts one. */
+schedules?: ToolSet, 
+/** The Jev gate, when this machine has a key for it. See jevguard.ts. */
+guard?: Partial<Record<HookEvent, HookCallbackMatcher[]>>): Options;
+/** process.env minus the one variable that would silently switch us to metered billing. */
+export declare function subscriptionEnv(): Record<string, string | undefined>;
+/**
+ * A tool call the agent made or tried to make. The supervisor will read these; for now they are
+ * what the CLI prints. Deriving them here rather than logging inline keeps the stream one thing
+ * that several consumers can read.
+ */
+export type AgentEvent = {
+    kind: 'ready';
+    tools: string[];
+    mcp: {
+        name: string;
+        status: string;
+    }[];
+    apiKeySource: string;
+    permissionMode: string;
+    /** Needed to resume this session later, so an agent picking a card back up remembers it. */
+    sessionId: string;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool';
+    name: string;
+}
+/** The agent's own plan, as it writes it. What a supervisor reads instead of asking. */
+ | {
+    kind: 'todo';
+    text: string;
+    status?: string;
+    id?: string;
+    created?: boolean;
+}
+/** `contextTokens` is the size of the last request — what the next turn on this session starts from. */
+/** After each model reply: the size of the request that produced it. */
+ | {
+    kind: 'usage';
+    contextTokens: number;
+}
+/** The SDK compacted the context mid-turn. It keeps the session alive by throwing detail away. */
+ | {
+    kind: 'compacted';
+} | {
+    kind: 'done';
+    ok: boolean;
+    result: string;
+    contextTokens?: number;
+}
+/** Raw text a tool returned. Our own servers' output, so it can be parsed rather than read. */
+ | {
+    kind: 'result';
+    text: string;
+};
+/**
+ * Run one task, yielding structured events rather than printing.
+ *
+ * `onStart` hands back the live query. That is what lets someone type at a turn already in
+ * progress — steering it rather than interrupting and starting again, which would throw away
+ * whatever it had worked out so far.
+ */
+export declare function runTask(prompt: string, options: Options, onStart?: (q: ReturnType<typeof query>) => void): AsyncGenerator<AgentEvent>;

package/dist/agent.js

@@ -0,0 +1,329 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { writeAutoModeSettings } from './automode.js';
+import { gitGuard } from './gitguard.js';
+import { secretGuard } from './secretguard.js';
+import { sandboxGuard } from './sandbox.js';
+import { readToolNames } from './permissions.js';
+import { LEAD_BRIEF } from './team.js';
+/**
+ * The one place a session is configured.
+ *
+ * Everything still to come — hooks for the supervisor, the event-stream connector, per-role tool
+ * sets, budgets — is another field on the object this builds. Keeping that in a single function
+ * is most of what "a foundation" means here: no second place to remember.
+ */
+/**
+ * What the agent is told about itself before it does anything.
+ *
+ * An agent that has to be ASKED who it is will sometimes not ask. Stating it up front means
+ * identity and workload are facts of the session rather than something the model has to remember
+ * to look up — and `get-outstanding` is named explicitly so the first thing it does is find its
+ * own work rather than wait to be handed some.
+ */
+export const AGENT_BRIEF = [
+    'You are a FlareDeck agent running unattended on your own machine, with your own FlareDeck',
+    'account. Nobody is watching this terminal.',
+    '',
+    'Two things already tell you what to do, and they win over anything here:',
+    '  · your agent description in FlareDeck — who you are and what you are for',
+    '  · the board\'s agent behaviour rules — how cards move, who picks up from where, who merges',
+    'Read them and follow them. What follows is only how THIS MACHINE works, which FlareDeck',
+    'cannot know.',
+    '',
+    'You work alone. There are no sub-agents to delegate to — do the work yourself, in order.',
+    '',
+    'Before changing anything, work out what THIS task actually needs and check it is there. Some',
+    'cards need nothing; for those, just get on with it. If something you need is missing, do not',
+    'work around it and do not diagnose the code — nothing is running, so anything you conclude',
+    'would be wrong. Say what is missing, call `set-needs-human`, and stop.',
+    '',
+    'Keep your todo list in step with the work. It is what a supervisor reads to see how you are',
+    'getting on, so it should show the real state rather than a plan you have moved past.',
+    '',
+    'If FlareDeck calls start coming back "interrupted before a result was received" or "Stream',
+    'closed", that is this session\'s channel to FlareDeck, not FlareDeck: it will not recover',
+    'within the turn, and no health check will show otherwise. Do not retry or wait for it. Say',
+    'in one line what did not land, and end the turn — the next event starts a session whose',
+    'calls work, and it reads the card before touching anything.',
+    '',
+    'Your session ends when the card is done, and you will be asked for a handover before it does.',
+    'Nothing you remember survives that — only what you write down.',
+    '',
+    'You have no memory on this machine, on purpose: you may be started anywhere, and you must be',
+    'the same agent wherever that is. Your memory is on your FlareDeck account — `remember` writes',
+    'to it and it is read back to you at the start of every session. Progress goes on the card;',
+    'lessons go in memory.',
+].join('\n');
+/**
+ * FlareDeck, plus whichever in-process tool sets are mounted.
+ *
+ * FlareDeck is served from inside this process (see flaredeck-proxy.ts) whenever the caller has
+ * discovered it; the harness is then the MCP client, with a fresh token per call. The direct
+ * http entry remains only for a caller that has a token but did no discovery — it carries a
+ * bearer frozen at session start, which is exactly the weakness the proxy removes.
+ */
+function mcpServers(config, token, mounted, flaredeck) {
+    const servers = {};
+    if (flaredeck) {
+        servers[config.mcpServerName] = flaredeck.server;
+    }
+    else if (token) {
+        servers[config.mcpServerName] = {
+            type: 'http',
+            url: config.mcpUrl,
+            headers: { Authorization: `Bearer ${token}` },
+        };
+    }
+    for (const [name, set] of Object.entries(mounted))
+        if (set)
+            servers[name] = set.server;
+    return servers;
+}
+/** Hook sets into one, keeping every matcher for an event instead of letting the last one win. */
+function mergeHooks(...sets) {
+    const out = {};
+    for (const set of sets) {
+        if (!set)
+            continue;
+        for (const [event, matchers] of Object.entries(set)) {
+            out[event] = [...(out[event] ?? []), ...matchers];
+        }
+    }
+    return out;
+}
+export function buildOptions(config, decider, extra = {}, 
+/** The card's worktree — the only place this turn may write. See sandbox.ts. */
+sandbox, 
+/** Publishing tools, when a job is running. Absent for one-off `run` and `whoami`. */
+git, 
+/** The harness's own FlareDeck token, handed to the MCP server so the model's tools act as
+ *  the SAME account the harness listens as. */
+token, 
+/** Present only for a LEAD. A worker never receives these tools, so "a worker cannot reach
+ *  across the team" holds because there is nothing to call, not because a prompt asked nicely. */
+team, 
+/** FlareDeck's tools, served in-process from what the server just listed. */
+flaredeck, 
+/** Production runs, where this machine names a target. Asking is harmless; running needs a person. */
+runs, 
+/** Recurring tasks. Asking is harmless: a person's approval is what starts one. */
+schedules, 
+/** The Jev gate, when this machine has a key for it. See jevguard.ts. */
+guard) {
+    return {
+        systemPrompt: {
+            type: 'preset',
+            preset: 'claude_code',
+            append: team ? `${AGENT_BRIEF}\n${LEAD_BRIEF}` : AGENT_BRIEF,
+        },
+        cwd: config.repo,
+        // Run on the Claude subscription, never on metered API billing. The SDK prefers
+        // ANTHROPIC_API_KEY whenever it is present, and an agent left running all night on a
+        // per-token key is a bill nobody agreed to — so the key is removed from the environment the
+        // Claude process gets rather than merely warned about. `env` REPLACES the subprocess
+        // environment, so everything else is passed through deliberately.
+        env: subscriptionEnv(),
+        // Isolation. Without this the agent inherits whatever Claude Code is configured with on this
+        // box — on a developer's machine that meant ten other MCP servers and 473 tools, and Flaredeck
+        // itself then timed out competing with them to connect. An agent must behave the same on every
+        // machine, so it loads no ambient settings and gets exactly the servers named below.
+        // 'project' only: the repo's .mcp.json (where login registered Flaredeck, with its stored
+        // credential) and the repo's CLAUDE.md, which an agent working here should follow. User-level
+        // settings are excluded — that is where this box's ten unrelated MCP servers came from, and an
+        // agent has to behave the same on every machine.
+        /**
+         * Trusted agent on its own sandboxed machine: it should get on with the job, not ask about
+         * every file it edits. Auto mode does that — a classifier reviews each action instead of a
+         * human and blocks "anything that escalates beyond your request, targets unrecognized
+         * infrastructure, or appears driven by hostile content Claude read".
+         *
+         * That last clause is why this beats bypassPermissions here. An agent works from card
+         * comments and web pages written by other people, so prompt injection is a live risk rather
+         * than a theoretical one — and the classifier's own request has tool RESULTS stripped, so
+         * hostile text in a comment cannot talk to the classifier directly.
+         *
+         * Deny rules and hooks are still evaluated before the mode, so the hard guardrails hold.
+         */
+        permissionMode: 'auto',
+        // Tell the classifier what this machine is. Without it the judge trusts only the working
+        // directory and the repo's remotes, so routine agent work looks like exfiltration. The file
+        // is written beside the agent's own config, never in the repo — see automode.ts.
+        settings: writeAutoModeSettings(config),
+        settingSources: ['project'],
+        // Filesystem settings are not the only ambient source: claude.ai account connectors
+        // which are fetched from the logged-in account. An agent should not inherit those either.
+        managedSettings: {
+            disableClaudeAiConnectors: true,
+            // Same reason as the tools above: a scheduled cloud run is work nobody on this machine is
+            // watching. Skills are not covered by disallowedTools, so they are turned off here.
+            skillOverrides: { schedule: 'off' },
+        },
+        /**
+         * FlareDeck, authenticated with the harness's OWN token.
+         *
+         * This replaces registering the server with the Claude CLI and authorising it separately.
+         * That needed a second OAuth, and worse it let the two drift: the tools acted as one account
+         * while the harness listened as another, which happened and took a while to spot. One token
+         * for both makes that disagreement impossible rather than merely detected.
+         *
+         * It also removes what that approach dragged in — `claude mcp add`, `claude mcp login`, a
+         * .mcp.json written into the repo, and pre-approving it in the CLI's own config, each of
+         * which broke in its own way first.
+         */
+        mcpServers: mcpServers(config, token, { git, team, runs, schedules }, flaredeck),
+        // Only the servers named above. A repo's own .mcp.json, agent frontmatter or plugin could
+        // declare a server with the same name and shadow the one that carries the token; this makes
+        // that impossible rather than merely unlikely.
+        strictMcpConfig: true,
+        // Reads only. Writes are left off deliberately so they reach the decider — see permissions.ts.
+        allowedTools: [
+            ...readToolNames(config.mcpServerName),
+            ...(git?.toolNames ?? []),
+            // Looking at the team is a read. It cannot change anyone's work, so it does not
+            // need a human's nod every time the lead wants to know who is on what.
+            ...(team?.toolNames ?? []),
+            // Requesting a run changes nothing: the person's Approve inside the call is the gate. Left
+            // to the classifier, "production" plus a script is exactly what it would block or bounce
+            // to the broker — a second approval for the act of asking.
+            ...(runs?.toolNames ?? []),
+            ...(schedules?.toolNames ?? []),
+        ],
+        // Always on, not only while a job runs. A guard that a different entry point can skip is a
+        // guard with a way round it — and `run` was exactly that way round.
+        // Three guards, merged by event rather than one replacing another: gitGuard keeps publishing
+        // in the tools, secretGuard fills in {{secret:NAME}} on the way out and redacts any secret
+        // that comes back, and the optional Jev gate judges whatever could be irreversible.
+        hooks: mergeHooks(gitGuard(() => { }), secretGuard(() => { }), 
+        // Write where your job is, read anywhere. Starting the agent IN its worktree was only
+        // placement — a shell can cd out of it — and with several repositories in one folder there
+        // is somewhere to go.
+        sandboxGuard(() => sandbox ?? null, () => { }), guard),
+        // No sub-agents. One thread that runs a card to completion is far easier to reason about
+        // than several sharing a checkout: no worktrees to juggle, nothing competing for the same
+        // ports and database, and one place to look when something stalls. A bare name here removes
+        // the tool from the model's context entirely, so it never plans around having it.
+        // RemoteTrigger and Workflow are worse than sub-agents here, not better: they start runs on
+        // OTHER machines, where this harness cannot see them, stop them, or notice them stalling.
+        // Asked what it could delegate to, the agent found these itself and offered them — so naming
+        // them is the difference between a rule and a suggestion.
+        // Everything that starts or steers WORK IN ANOTHER PROCESS. Deliberately not FlareDeck's own
+        // send-message or trigger-build: messaging another agent and kicking a CI build are ordinary
+        // product features, not this agent quietly forking itself.
+        disallowedTools: ['Agent', 'Task', 'RemoteTrigger', 'Workflow', 'SendMessage'],
+        canUseTool: async (toolName, input, { signal }) => {
+            const decision = await decider({ toolName, input }, { signal });
+            return decision.allow
+                ? { behavior: 'allow', updatedInput: input }
+                : { behavior: 'deny', message: decision.reason };
+        },
+        ...extra,
+    };
+}
+/** process.env minus the one variable that would silently switch us to metered billing. */
+export function subscriptionEnv() {
+    const { ANTHROPIC_API_KEY: _removed, ...rest } = process.env;
+    return {
+        ...rest,
+        // Flaredeck is the one server that must be up before the first turn: an agent that starts
+        // without it looks healthy and can't touch a card. The default first-turn wait gave up on it
+        // after 5 seconds, so wait properly rather than racing a cold remote server.
+        CLAUDE_CODE_MCP_STARTUP_WAIT_MS: rest['CLAUDE_CODE_MCP_STARTUP_WAIT_MS'] ?? '60000',
+        MCP_TIMEOUT: rest['MCP_TIMEOUT'] ?? '60000',
+        // Current models track multi-step work without writing a list, so the task tools are OFF by
+        // default and nothing appears in the stream. We want them ON: the agent's own todo list is
+        // how a supervisor sees progress without asking, and TaskCreate/TaskUpdate arrive as
+        // tool_use blocks we can read. There is no todos file on disk to read instead.
+        CLAUDE_CODE_ENABLE_TODO_TOOLS: rest['CLAUDE_CODE_ENABLE_TODO_TOOLS'] ?? '1',
+    };
+}
+/**
+ * Run one task, yielding structured events rather than printing.
+ *
+ * `onStart` hands back the live query. That is what lets someone type at a turn already in
+ * progress — steering it rather than interrupting and starting again, which would throw away
+ * whatever it had worked out so far.
+ */
+export async function* runTask(prompt, options, onStart) {
+    const running = query({ prompt, options });
+    onStart?.(running);
+    let lastContext = 0;
+    for await (const message of running) {
+        const m = message;
+        if (m['type'] === 'assistant') {
+            const u = m['message']?.usage ?? {};
+            const n = (u['input_tokens'] ?? 0) + (u['cache_creation_input_tokens'] ?? 0) + (u['cache_read_input_tokens'] ?? 0);
+            if (n > 0) {
+                lastContext = n;
+                yield { kind: 'usage', contextTokens: n };
+            }
+        }
+        if (m['type'] === 'system' && m['subtype'] === 'compact_boundary')
+            yield { kind: 'compacted' };
+        if (m['type'] === 'system' && m['subtype'] === 'init') {
+            yield {
+                kind: 'ready',
+                tools: (m['tools'] ?? []).filter((t) => t.startsWith('mcp__')),
+                mcp: (m['mcp_servers'] ?? []).map((s) => ({ name: s.name, status: s.status })),
+                // 'none' means no API key is in use — i.e. a claude.ai OAuth login. That is what we want.
+                apiKeySource: m['apiKeySource'] ?? 'unknown',
+                // Asked for 'auto', but a session that cannot have it silently starts in Manual instead,
+                // which for an unattended agent means prompting for work nobody will approve. Report what
+                // we actually got rather than what we asked for.
+                permissionMode: m['permissionMode'] ?? 'unknown',
+                sessionId: m['session_id'] ?? '',
+            };
+        }
+        else if (m['type'] === 'assistant') {
+            for (const block of m['message']?.content ?? []) {
+                if (block.type === 'text' && block.text.trim())
+                    yield { kind: 'text', text: block.text };
+                if (block.type === 'tool_use') {
+                    // Read the id defensively: Claude Code repairs close-but-wrong key names before
+                    // executing, but the STREAM carries the model's raw spelling.
+                    const i = block.input ?? {};
+                    if (block.name === 'TaskCreate' || block.name === 'TodoWrite') {
+                        yield {
+                            kind: 'todo',
+                            text: i.subject ?? i.content ?? JSON.stringify(i).slice(0, 120),
+                            created: true,
+                        };
+                        continue;
+                    }
+                    if (block.name === 'TaskUpdate') {
+                        const id = i.taskId ?? i.id ?? i.task_id;
+                        yield {
+                            kind: 'todo',
+                            text: `${id ?? '?'} → ${i.status ?? '?'}`,
+                            status: i.status,
+                            ...(id ? { id: String(id) } : {}),
+                        };
+                        continue;
+                    }
+                    yield { kind: 'tool', name: block.name };
+                }
+            }
+        }
+        else if (m['type'] === 'user') {
+            for (const block of m['message']?.content ?? []) {
+                if (block.type !== 'tool_result')
+                    continue;
+                const c = block.content;
+                const text = typeof c === 'string' ? c : (c ?? []).map((b) => b?.text ?? '').join('');
+                if (text)
+                    yield { kind: 'result', text };
+            }
+        }
+        else if (m['type'] === 'result') {
+            // The result's own usage is the SUM over every request in the turn — a fifteen-request
+            // turn reads as a million tokens. The context the next turn starts from is the size of
+            // the LAST request, which is what its assistant message recorded.
+            yield {
+                kind: 'done',
+                ok: m['subtype'] === 'success',
+                result: m['result'] ?? '',
+                ...(lastContext > 0 ? { contextTokens: lastContext } : {}),
+            };
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/approval.d.ts

@@ -0,0 +1,72 @@
+import type { Flaredeck } from './flaredeck.js';
+import type { Decider } from './permissions.js';
+/**
+ * The wire shape is Claude Code's own permission-relay protocol, deliberately, even though this
+ * harness talks to FlareDeck directly rather than through a channel MCP server.
+ *
+ * A channel would add a second process and a research-preview dependency to get something
+ * `canUseTool` already does better for an unattended agent — the channel relay has no deadline,
+ * so a session with nobody at the terminal waits for an answer forever. Going direct keeps the
+ * timeout.
+ *
+ * But the PAYLOAD costs nothing to share, and sharing it means the FlareDeck side — the approval
+ * record, the Approve/Deny buttons, the mobile widget — is built once against a shape that is
+ * already proven and already spoken by every Claude Code session. If a channel ever becomes the
+ * better transport, only the transport changes.
+ */
+export type PermissionRequest = {
+    /** Five lowercase letters, no `l`. Echoed by the verdict. */
+    request_id: string;
+    tool_name: string;
+    /** What this call does, in words — never the command itself. */
+    description: string;
+    /** The arguments as display text. Redacted and truncated before it leaves here. */
+    input_preview: string;
+};
+export type PermissionVerdict = {
+    request_id: string;
+    behavior: 'allow' | 'deny';
+};
+/** How long a request waits before it is treated as a refusal. */
+export declare const APPROVAL_TIMEOUT_MS: number;
+/**
+ * Verdicts arrive on the event stream, not by polling the card.
+ *
+ * The server queues a `decided` event to the requester the moment anyone answers — lead, phone,
+ * web or inbox — and the stream the harness already holds delivers it. A request waiting here
+ * registers under its id; the stream loop hands the event in; the wait resolves. Nothing is
+ * fetched in between, so an hour-long wait costs nothing and an answer lands within a second.
+ */
+export type Decided = {
+    outcome: 'endorsed' | 'rejected' | 'allow' | 'deny';
+    by: string;
+    note?: string;
+};
+/** Called by the stream loop for every `decided` event. Returns true when a wait took it. */
+export declare function deliverDecision(message: string): boolean;
+/** True while any request is waiting — the stream loop uses it to know a `decided` event is expected. */
+export declare const awaitingDecision: (requestId: string) => boolean;
+export declare const redact: (text: string) => string;
+/**
+ * Turn a permission request into a question on the card.
+ *
+ * In auto mode the classifier has already handled everything routine, so whatever arrives here is
+ * the unusual kind — an explicit `ask` rule, or a tool that needs a person. Rather than refusing
+ * and losing the work, the harness posts it to the card and waits: anyone on the board can answer
+ * from their phone, and the reply arrives as an ordinary comment.
+ *
+ * It cannot hang. The wait ends at the timeout, or when the SDK aborts, and both mean "no".
+ */
+export declare function flaredeckDecider(deck: Flaredeck, card: string, timeoutMs?: number, 
+/** Routing the request carries with it: a lead who must endorse it first, and who may answer. */
+route?: {
+    review_by?: string;
+    approvers?: string[];
+}, 
+/** Called once the request is on the card, with what a local answerer needs to find it. */
+onPosted?: (posted: {
+    request_id: string;
+    comment_id: string;
+}) => void, 
+/** Called when the lead endorses it — the wait continues, now on a person. */
+onReviewed?: (d: Decided) => void): Decider;