@onepointfour-packs/flaredeck-agent 0.1.0

package/dist/sandbox.js

@@ -0,0 +1,110 @@
+import { resolve } from 'node:path';
+/**
+ * Keep a card's changes inside that card's checkout.
+ *
+ * The harness makes a worktree per card and starts the agent in it, and for a long time that was
+ * the whole story — which is placement, not confinement. A shell can `cd` out of it, `git -C` past
+ * it, or edit by absolute path, and an agent with four repositories in one folder has somewhere to
+ * go. One did: given a card with no worktree it read production out of a worktree belonging to
+ * somebody else. Nothing was harmed because that card only read, and that is luck rather than
+ * design.
+ *
+ * So: WRITE where your job is, READ wherever you like. Reading the neighbouring repositories is
+ * how an agent understands how a change fits; writing to them is how two agents end up in each
+ * other's work. The split is deliberate and the refusal says which half it is.
+ *
+ * Like gitGuard, this reads strings and is therefore not airtight — a write buried in a script it
+ * will not catch. It is the closed front door. The fence is the dead `origin` pushurl, which no
+ * amount of spelling gets past, and branch protection on the remote.
+ */
+/** Writing verbs. `git add` is included: staging outside your job is the first half of committing there. */
+const GIT_WRITES = /\b(commit|add|rm|mv|restore|checkout|switch|reset|revert|stash|clean|apply|am|cherry-pick|rebase|merge|tag|branch|worktree|config)\b/;
+/** Shell commands that change files. Deliberately short: the point is the obvious ones, said clearly. */
+const FILE_WRITES = /(^|[\s;&|(])(rm|mv|cp|touch|mkdir|rmdir|chmod|chown|ln|truncate|tee|dd|sed\s+-i|install)\b/;
+/** `>` and `>>`, but not `2>&1`, `>&2` or a comparison inside a test. */
+const REDIRECTS = /(^|[^\d&<>])>>?\s*[^&\s|]/;
+/** An absolute path mentioned anywhere in the line, so a write by full path is seen. */
+const ABSOLUTE_PATHS = /(^|[\s"'=:])(\/[^\s"':;|&)]+)/g;
+const inside = (path, root) => {
+    const p = resolve(path);
+    const r = resolve(root);
+    return p === r || p.startsWith(`${r}/`);
+};
+/** `git -C <path>` / `--git-dir=<path>`: the repo a git command acts on, when it is not the cwd. */
+function gitTarget(command) {
+    const c = /(?:^|\s)git\s[^\n;&|]*?(?:-C\s+|--git-dir[= ]|--work-tree[= ])(["']?)([^\s"']+)\1/.exec(command);
+    return c?.[2] ?? null;
+}
+/**
+ * True when this command looks like it writes somewhere outside `root`.
+ *
+ * Reads are never refused, so the question is only ever asked of a line that changes something.
+ */
+export function writesOutside(command, root) {
+    const isGit = /(^|[\s;&|(])git\b/.test(command);
+    const target = gitTarget(command);
+    if (isGit && target && GIT_WRITES.test(command) && !inside(target, root)) {
+        return `\`git -C ${target}\` would change a checkout that is not this card's.`;
+    }
+    // A `cd` out of the worktree followed by anything that writes.
+    const cd = /(?:^|[\s;&|(])cd\s+(["']?)([^\s"';&|]+)\1/.exec(command);
+    if (cd?.[2]?.startsWith('/') && !inside(cd[2], root)) {
+        if ((isGit && GIT_WRITES.test(command)) || FILE_WRITES.test(command) || REDIRECTS.test(command)) {
+            return `This changes files under ${cd[2]}, which is outside this card's checkout.`;
+        }
+    }
+    if (!FILE_WRITES.test(command) && !REDIRECTS.test(command))
+        return null;
+    for (const m of command.matchAll(ABSOLUTE_PATHS)) {
+        const path = m[2];
+        // /tmp, /dev and the like are scratch, not somebody's work.
+        if (/^\/(tmp|var\/folders|dev|proc|sys|private\/tmp)(\/|$)/.test(path))
+            continue;
+        if (!inside(path, root))
+            return `This writes to ${path}, which is outside this card's checkout.`;
+    }
+    return null;
+}
+/**
+ * `job()` returns the directory this card owns, or null when there is no job — in which case
+ * nothing is enforced here, because a turn with no checkout has a different rule (it is told it
+ * may change nothing at all) and the publishing tools already refuse it.
+ */
+export function sandboxGuard(job, onNote) {
+    const refusal = (why, root) => `${why}\n\n` +
+        `Your checkout for this card is ${root} — commit there, and publish with push_branch. ` +
+        `You may READ anything on this machine, including the other repositories, and that is often ` +
+        `how a change is understood. Changing them is what this refuses: they are other cards' work, ` +
+        `and another agent may be in them right now. If the change genuinely belongs in another ` +
+        `repository, say so on the card rather than making it.`;
+    const check = async (input) => {
+        const root = job();
+        if (!root)
+            return { continue: true };
+        const tool = String(input?.tool_name ?? '');
+        if (tool === 'Bash') {
+            const why = writesOutside(String(input?.tool_input?.command ?? ''), root);
+            if (!why)
+                return { continue: true };
+            onNote(`blocked a write outside the worktree: ${why}`);
+            return { decision: 'block', reason: refusal(why, root) };
+        }
+        // Edit / Write / NotebookEdit all name the file they change.
+        const path = String(input?.tool_input?.file_path ?? input?.tool_input?.notebook_path ?? '');
+        if (!path || inside(path, root))
+            return { continue: true };
+        if (/^\/(tmp|var\/folders|private\/tmp)(\/|$)/.test(path))
+            return { continue: true };
+        onNote(`blocked an edit outside the worktree: ${path}`);
+        return { decision: 'block', reason: refusal(`${path} is outside this card's checkout.`, root) };
+    };
+    return {
+        PreToolUse: [
+            { matcher: 'Bash', hooks: [check] },
+            { matcher: 'Edit', hooks: [check] },
+            { matcher: 'Write', hooks: [check] },
+            { matcher: 'NotebookEdit', hooks: [check] },
+        ],
+    };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

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

package/dist/schedules.d.ts

@@ -0,0 +1,11 @@
+import type { Flaredeck } from './flaredeck.js';
+/**
+ * Recurring tasks, held by FlareDeck rather than by this machine.
+ *
+ * An agent asks for one here; FlareDeck files the request as an approval on a card and the
+ * schedule only goes live when a person approves it. From then on FlareDeck wakes the named agent
+ * at each time — on whichever machine that agent is running — with the prompt it was given. A run
+ * more than its late window past the due time is skipped, not delayed.
+ */
+export declare const SCHEDULE_TOOL_NAMES: string[];
+export declare function scheduleTools(deck: Flaredeck | null, currentCard: () => string | null): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/schedules.js

@@ -0,0 +1,85 @@
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+/**
+ * Recurring tasks, held by FlareDeck rather than by this machine.
+ *
+ * An agent asks for one here; FlareDeck files the request as an approval on a card and the
+ * schedule only goes live when a person approves it. From then on FlareDeck wakes the named agent
+ * at each time — on whichever machine that agent is running — with the prompt it was given. A run
+ * more than its late window past the due time is skipped, not delayed.
+ */
+export const SCHEDULE_TOOL_NAMES = [
+    'mcp__schedules__create_schedule',
+    'mcp__schedules__list_schedules',
+    'mcp__schedules__delete_schedule',
+];
+const say = (text, isError = false) => ({ content: [{ type: 'text', text }], isError });
+export function scheduleTools(deck, currentCard) {
+    const need = () => say('This harness has no FlareDeck client of its own, so it cannot manage schedules.', true);
+    return createSdkMcpServer({
+        name: 'schedules',
+        version: '1.0.0',
+        tools: [
+            tool('create_schedule', 'Ask FlareDeck to wake an agent on a recurring schedule, for example 7am on weekdays. This does ' +
+                'NOT start it: the request is posted on a card as an approval, and a person must approve it ' +
+                'before the first run. Returns at once; do not wait for the answer. The prompt is what the agent ' +
+                'is told at each run, with no memory of earlier runs, so it must be self-contained. A run that ' +
+                'is more than max_late_minutes late is skipped, not delayed. Runs must be at least 15 minutes apart.', {
+                name: z.string().describe('A short label, e.g. "Daily summary to Darren".'),
+                cron: z.string().describe('Standard 5-field cron in the given timezone, e.g. "0 7 * * 1-5" for 07:00 Monday to Friday.'),
+                timezone: z.string().describe('IANA zone, e.g. "Africa/Johannesburg". Always state it; cron means nothing without one.'),
+                prompt: z.string().describe('Exactly what the agent should do at each run, written so it needs no other context.'),
+                card: z.string().optional().describe('The card code (e.g. KD-1234) to post the approval request on. Defaults to the card you are working.'),
+                agent: z.string().optional().describe('Email or user id of the agent to wake. Defaults to you.'),
+                max_late_minutes: z.number().optional().describe('How late a run may start before it is skipped. Default 60.'),
+            }, async ({ name, cron, timezone, prompt, card, agent, max_late_minutes }) => {
+                if (!deck)
+                    return need();
+                const where = card ?? currentCard();
+                if (!where)
+                    return say('Say which card to post the approval request on (the card parameter): there is no card in front of you.', true);
+                try {
+                    const s = await deck.createSchedule({
+                        name, cron, timezone, prompt, card: where,
+                        ...(agent ? { agent } : {}),
+                        ...(max_late_minutes ? { max_late_minutes } : {}),
+                    });
+                    return say(s.state === 'active'
+                        ? `Schedule ${s.id} is live. Next run ${s.next_run_at}.`
+                        : `Schedule ${s.id} is waiting for a person to approve it on ${where}. Nothing runs until they do. ` +
+                            'You will not be told the answer; list_schedules shows its state.');
+                }
+                catch (e) {
+                    return say(`Could not register the schedule: ${e instanceof Error ? e.message : String(e)}`, true);
+                }
+            }),
+            tool('list_schedules', 'The recurring schedules in this workspace: state (pending approval, active, denied), cron, timezone, ' +
+                'next and last run, and the agent each one wakes.', {}, async () => {
+                if (!deck)
+                    return need();
+                try {
+                    const all = await deck.schedules();
+                    if (!all.length)
+                        return say('No schedules.');
+                    return say(all.map((s) => `${s.id} · ${s.name} · ${s.state} · ${s.cron} (${s.timezone}) → ${s.agent_name ?? s.agent_uid}` +
+                        `${s.next_run_at ? ` · next ${s.next_run_at}` : ''}${s.last_run_at ? ` · last ${s.last_run_at}` : ''}`).join('\n'));
+                }
+                catch (e) {
+                    return say(`Could not read the schedules: ${e instanceof Error ? e.message : String(e)}`, true);
+                }
+            }),
+            tool('delete_schedule', 'Stop and remove a schedule you registered.', { id: z.string().describe('The schedule id from list_schedules.') }, async ({ id }) => {
+                if (!deck)
+                    return need();
+                try {
+                    await deck.deleteSchedule(id);
+                    return say(`Removed ${id}.`);
+                }
+                catch (e) {
+                    return say(`Could not remove it: ${e instanceof Error ? e.message : String(e)}`, true);
+                }
+            }),
+        ],
+    });
+}
+//# sourceMappingURL=schedules.js.map

package/dist/schedules.js.map

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

package/dist/secretguard.d.ts

@@ -0,0 +1,4 @@
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+/** Replace every known secret value in any text with [REDACTED]. */
+export declare function scrub(text: string, values?: Record<string, string>): string;
+export declare function secretGuard(log: (text: string) => void): Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/secretguard.js

@@ -0,0 +1,115 @@
+import { secretValues } from './secrets.js';
+/**
+ * How the agent uses a credential it is never allowed to read.
+ *
+ * Two halves, and the second is the one that matters.
+ *
+ * IN: the model writes `{{secret:STRIPE_KEY}}` and the PreToolUse hook replaces it with the real
+ * value as the call goes out. The transcript — which is written to disk in plain text and resent
+ * with every subsequent request — keeps only the placeholder.
+ *
+ * OUT: substitution alone is not enough and it is easy to stop there. `curl -v` echoes its own
+ * Authorization header; a failing command prints the URL it was given; an env dump prints
+ * everything. So every tool result is scrubbed of every known secret value before the model sees
+ * it. That also covers the accident nobody planned: an agent that stumbles into printing a key
+ * gets `[REDACTED]`, not a leak.
+ *
+ * A value is only ever in the executed command and in this process. It is never in the model's
+ * context, so it is never in the session file, and never in what goes back to the API.
+ */
+const PLACEHOLDER = /\{\{\s*secret:([A-Z][A-Z0-9_]{1,63})\s*\}\}/g;
+/** Short values would match everywhere and turn ordinary output into confetti. */
+const MIN_SCRUBBABLE = 8;
+/** Replace every known secret value in any text with [REDACTED]. */
+export function scrub(text, values = secretValues()) {
+    let out = text;
+    for (const [name, value] of Object.entries(values)) {
+        if (!value || value.length < MIN_SCRUBBABLE)
+            continue;
+        if (!out.includes(value))
+            continue;
+        out = out.split(value).join(`[REDACTED:${name}]`);
+    }
+    return out;
+}
+/** Walk a tool result of unknown shape, scrubbing every string in it. */
+function scrubDeep(value, values) {
+    if (typeof value === 'string')
+        return scrub(value, values);
+    if (Array.isArray(value))
+        return value.map((v) => scrubDeep(v, values));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubDeep(v, values)]));
+    }
+    return value;
+}
+export function secretGuard(log) {
+    return {
+        PreToolUse: [
+            {
+                matcher: 'Bash',
+                hooks: [
+                    async (input) => {
+                        const command = String(input?.tool_input?.command ?? '');
+                        PLACEHOLDER.lastIndex = 0;
+                        if (!PLACEHOLDER.test(command))
+                            return { continue: true };
+                        const values = secretValues();
+                        const missing = [];
+                        const used = [];
+                        PLACEHOLDER.lastIndex = 0;
+                        const filled = command.replace(PLACEHOLDER, (_m, name) => {
+                            const value = values[name];
+                            if (value === undefined) {
+                                missing.push(name);
+                                return _m;
+                            }
+                            used.push(name);
+                            return value;
+                        });
+                        if (missing.length) {
+                            return {
+                                decision: 'block',
+                                reason: `There is no secret called ${missing.join(', ')} on this machine.\n\n` +
+                                    `Available: ${Object.keys(values).sort().join(', ') || '(none)'}. ` +
+                                    `A person adds one with \`flaredeck-agent secret add ${missing[0]}\` — you cannot add it yourself, ` +
+                                    `and you will never see its value. Say on the card which credential you need and what for.`,
+                            };
+                        }
+                        log(`filled in ${used.join(', ')} — the value is not in this conversation`);
+                        return {
+                            continue: true,
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                updatedInput: { ...input.tool_input, command: filled },
+                            },
+                        };
+                    },
+                ],
+            },
+        ],
+        PostToolUse: [
+            {
+                // Every tool, not just Bash: a secret can come back from a file read or an MCP call too.
+                matcher: '*',
+                hooks: [
+                    async (input) => {
+                        const values = secretValues();
+                        if (!Object.keys(values).length)
+                            return { continue: true };
+                        const before = JSON.stringify(input?.tool_response ?? '');
+                        const after = scrubDeep(input?.tool_response, values);
+                        if (JSON.stringify(after) === before)
+                            return { continue: true };
+                        log('a secret came back in a tool result — redacted before the model saw it');
+                        return {
+                            continue: true,
+                            hookSpecificOutput: { hookEventName: 'PostToolUse', updatedToolOutput: after },
+                        };
+                    },
+                ],
+            },
+        ],
+    };
+}
+//# sourceMappingURL=secretguard.js.map

package/dist/secretguard.js.map

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

package/dist/secrets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Credentials the agent may USE but must never SEE.
+ *
+ * A key pasted into the pane is in the session transcript, on disk in plain text, and in every
+ * API request that follows for as long as that session lives. There is no taking it back. So a
+ * secret is put here by a person, in a separate process, and the agent is given only its NAME:
+ * it writes `{{secret:STRIPE_KEY}}` and the harness substitutes the value as the command runs
+ * (see secretguard.ts), then scrubs the value back out of whatever the command printed.
+ *
+ * Stored as plain text with 0600 permissions, which is exactly the posture of the two credential
+ * files already beside it — `providers.json` holds the OpenRouter key and `me.json` holds OAuth
+ * tokens. The file keeps secrets out of the TRANSCRIPT, which is the leak that cannot be undone;
+ * it does not pretend to defend a machine someone already has an account on. Moving all three to
+ * the OS keychain is a worthwhile follow-up, and it is one change for all of them, not this file
+ * diverging on its own.
+ */
+export type SecretStore = Record<string, string>;
+/** A name the agent can type in a placeholder without ambiguity, and that reads as a constant. */
+export declare const VALID_NAME: RegExp;
+/** Names only. This is what the agent is allowed to know. */
+export declare function secretNames(): string[];
+/** The values, for the harness's own substitution and scrubbing. Never returned to the model. */
+export declare function secretValues(): SecretStore;
+export declare function setSecret(name: string, value: string): void;
+export declare function removeSecret(name: string): boolean;
+/** Where they live, for telling a person where to look. */
+export declare const secretsPath: () => string;

package/dist/secrets.js

@@ -0,0 +1,51 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const file = () => join(process.env['XDG_CONFIG_HOME'] || join(homedir(), '.config'), 'flaredeck-agent', 'secrets.json');
+/** A name the agent can type in a placeholder without ambiguity, and that reads as a constant. */
+export const VALID_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+function load() {
+    try {
+        if (!existsSync(file()))
+            return {};
+        const raw = JSON.parse(readFileSync(file(), 'utf8'));
+        return Object.fromEntries(Object.entries(raw).filter(([k, v]) => VALID_NAME.test(k) && typeof v === 'string'));
+    }
+    catch {
+        return {};
+    }
+}
+function save(store) {
+    const path = file();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+    // writeFileSync's mode only applies when it CREATES the file: an existing one keeps whatever
+    // permissions it had, so a file that was once world-readable would stay that way silently.
+    chmodSync(path, 0o600);
+}
+/** Names only. This is what the agent is allowed to know. */
+export function secretNames() {
+    return Object.keys(load()).sort();
+}
+/** The values, for the harness's own substitution and scrubbing. Never returned to the model. */
+export function secretValues() {
+    return load();
+}
+export function setSecret(name, value) {
+    if (!VALID_NAME.test(name))
+        throw new Error(`"${name}" is not a usable name — use CAPITALS, digits and underscores, e.g. STRIPE_KEY`);
+    if (!value.trim())
+        throw new Error('That value is empty.');
+    save({ ...load(), [name]: value });
+}
+export function removeSecret(name) {
+    const store = load();
+    if (!(name in store))
+        return false;
+    delete store[name];
+    save(store);
+    return true;
+}
+/** Where they live, for telling a person where to look. */
+export const secretsPath = file;
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqB1C,MAAM,IAAI,GAAG,GAAW,EAAE,CACxB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,iBAAiB,EAAE,cAAc,CAAC,CAAC;AAExG,kGAAkG;AAClG,MAAM,CAAC,MAAM,UAAU,GAAG,wBAAwB,CAAC;AAEnD,SAAS,IAAI;IACX,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAgB,CAAC;QACpE,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC,CACpF,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,IAAI,CAAC,KAAkB;IAC9B,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;IACpB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5E,6FAA6F;IAC7F,2FAA2F;IAC3F,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,WAAW;IACzB,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,gFAAgF,CAAC,CAAC;IACtI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC3D,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC;IACrB,IAAI,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,CAAC,CAAC;IACZ,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC"}

package/dist/serve.d.ts

@@ -0,0 +1,17 @@
+import { type Config } from './config.js';
+import type { Flaredeck } from './flaredeck.js';
+import type { Decider } from './permissions.js';
+export type Serve = {
+    config: Config;
+    /** Returns a currently-valid bearer; refreshed on use, since the daemon outlives any token. */
+    auth: () => Promise<string>;
+    baseUrl: string;
+    decider: Decider;
+    deck?: Flaredeck;
+    /** A PERSON's client, when someone has done `login --me` here: what answers a run from the pane. */
+    me?: Flaredeck;
+    say: (text: string) => void;
+    /** Who this machine is, for the header. */
+    agent?: string;
+};
+export declare function serve(opts: Serve): Promise<void>;