@netnodeag/kraftwerk 0.81.0 → 0.82.0

package/dist/config.d.ts

@@ -135,6 +135,23 @@ export interface EntitiesConfig {
     root?: string;
 }
 export declare const ENTITY_KINDS: readonly ["contacts", "places", "events"];
+/**
+ * Boards: the work as columns of tasks, one folder per task (task.md, log.md,
+ * files) under a board folder — inside a project (projects/<p>/boards/) or
+ * at the workspace level under the boards root. Part of the workspace and
+ * synced by the workspace git; agents are woken by events on this machine.
+ */
+export interface BoardsConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /** Where the workspace boards live, relative to the project root. Default: kraftwerk-data/boards */
+    root?: string;
+    /** Default columns for boards that name none (slugs or {slug, label, limit, done, review}). Default: draft, todo, progress, review, done. */
+    columns?: unknown;
+}
+export declare const BOARDS_DEFAULT_ROOT = "kraftwerk-data/boards";
+/** Absolute workspace boards root when the feature is on, undefined otherwise. */
+export declare function boardsRootFor(project: ResolvedWorkspace): string | undefined;
 export type EntityKind = (typeof ENTITY_KINDS)[number];
 /** Where a kind's files live when its `root` is not set. */
 export declare const entityDefaultRoot: (kind: EntityKind) => string;
@@ -218,6 +235,8 @@ export interface WorkspaceConfig {
     places?: EntitiesConfig;
     /** Events: dated entries (one-off), one Markdown file each. Absent = off. */
     events?: EntitiesConfig;
+    /** Boards: tasks as folders in columns, per project and workspace-wide. Absent = off. */
+    boards?: BoardsConfig;
     /** The machine's cloud record lists this workspace. Absent = listed; `enabled: false` leaves it out. */
     cloud?: CloudConfig;
 }

package/dist/config.js

@@ -97,6 +97,14 @@ export function projectsRootFor(project) {
     return path.resolve(project.root, p.root ?? PROJECTS_DEFAULT_ROOT);
 }
 export const ENTITY_KINDS = ["contacts", "places", "events"];
+export const BOARDS_DEFAULT_ROOT = "kraftwerk-data/boards";
+/** Absolute workspace boards root when the feature is on, undefined otherwise. */
+export function boardsRootFor(project) {
+    const b = project.config.boards;
+    if (!b || b.enabled === false)
+        return undefined;
+    return path.resolve(project.root, b.root ?? BOARDS_DEFAULT_ROOT);
+}
 /** Where a kind's files live when its `root` is not set. */
 export const entityDefaultRoot = (kind) => `kraftwerk-data/${kind}`;
 /** Absolute root of a kind when its feature is on, undefined otherwise. */
@@ -241,7 +249,7 @@ export async function addWorkspaceId(configPath) {
     await writeFile(configPath, out);
     return id;
 }
-const KNOWN_KEYS = ["id", "name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "contacts", "places", "events", "cloud"];
+const KNOWN_KEYS = ["id", "name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "contacts", "places", "events", "boards", "cloud"];
 /**
  * Keys an older kraftwerk understood and this one ignores, so the files
  * that still carry them keep loading: `public:` and `tunnel:` (the
@@ -313,6 +321,11 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, key, config[key]);
         }
+        else if (key === "boards") {
+            if (config[key] === null)
+                config[key] = {};
+            validateBoards(configPath, config[key]);
+        }
         else if (key === "cloud") {
             if (config[key] === null)
                 config[key] = {};
@@ -418,6 +431,16 @@ function validateGit(configPath, value) {
  * anything outside it — it is what remove/delete operate under, and what
  * the workspace git may stage.
  */
+/** `boards`: the root block plus `columns`, which core/boards.ts reads (a bad list falls back to the defaults there). */
+function validateBoards(configPath, value) {
+    const file = path.basename(configPath);
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${file}: boards must be a mapping (enabled, root, columns)`);
+    const { columns, ...rest } = value;
+    if (columns !== undefined && columns !== null && !Array.isArray(columns))
+        throw new Error(`${file}: boards.columns must be a list of columns`);
+    validateRootBlock(configPath, "boards", rest);
+}
 function validateRootBlock(configPath, block, value) {
     const file = path.basename(configPath);
     if (typeof value !== "object" || value === null || Array.isArray(value)) {

package/dist/core/attention.d.ts

@@ -33,8 +33,8 @@ export interface AttentionOwner {
 export interface AttentionItem {
     /** The request id (live requests) or the notification id (failures). */
     id: string;
-    /** runner: routines without a runner, or naming a retired identity of this machine (see routines.ts). */
-    kind: "approval" | "question" | "failed" | "runner";
+    /** runner: routines without a runner, or naming a retired identity of this machine (see routines.ts); review: a task waits in a review column (boards.ts). */
+    kind: "approval" | "question" | "failed" | "runner" | "review";
     /** What is asked, or what went wrong. */
     title: string;
     /** The session it sits in. */

package/dist/core/attention.js

@@ -1,14 +1,16 @@
 import { listAgents } from "./agents.js";
+import { getBoard, listAllBoards } from "./boards.js";
 import { waitingRequests } from "./chat/sessions.js";
 import { chatHref, listNotifications } from "./notifications.js";
 import { listProjects } from "./projects.js";
 import { runnerFindings } from "./routines.js";
 export async function listAttention() {
-    const [agents, projects, notes, runners] = await Promise.all([
+    const [agents, projects, notes, runners, boards] = await Promise.all([
         listAgents().catch(() => []),
         listProjects().catch(() => ({ projects: [] })),
         listNotifications().catch(() => ({ items: [] })),
         runnerFindings().catch(() => ({ unassigned: [], retired: [] })),
+        listAllBoards().catch(() => []),
     ]);
     const agentOf = (slug) => {
         const a = agents.find((x) => x.slug === slug);
@@ -101,6 +103,24 @@ export async function listAttention() {
             routines: these,
         });
     }
-    const items = [...waiting, ...failed, ...runner].sort((a, b) => a.since.localeCompare(b.since));
+    // Tasks in a review column: the agents are done, a human decides. One item per task, placed in its project (workspace boards: general).
+    const review = [];
+    for (const b of boards) {
+        const detail = await getBoard(b).catch(() => null);
+        if (!detail)
+            continue;
+        const reviewCols = new Set(detail.columns.filter((c) => c.review).map((c) => c.slug));
+        for (const t of detail.items.filter((t) => reviewCols.has(t.status))) {
+            review.push({
+                id: `review:${t.ref}`,
+                kind: "review",
+                title: `${t.number} ${t.title} waits for your review${t.lastLog ? ` — ${t.lastLog}` : ""}`,
+                href: b.project ? `/projects/${b.project}/boards/${b.board}/${t.slug}` : `/boards/${b.board}/${t.slug}`,
+                since: t.updatedAt ?? new Date(0).toISOString(),
+                owner: b.project ? { project: projectOf(b.project) } : { general: true },
+            });
+        }
+    }
+    const items = [...waiting, ...failed, ...runner, ...review].sort((a, b) => a.since.localeCompare(b.since));
     return { items };
 }

package/dist/core/board-wake.d.ts

@@ -0,0 +1,21 @@
+/** A chat on the task page: the agent's task session (scope.task) or a chat tagged with the task (meta.task, "work on this"). */
+export interface TaskSession {
+    id: string;
+    /** The agent slug of a task session; "claude" | "codex" | "pi" for a plain chat tagged with the task. */
+    agent: string;
+    /** The agent's display name and emoji when it is one of the workspace's agents. */
+    name?: string;
+    emoji?: string;
+    title: string;
+    updatedAt: string;
+    busy: boolean;
+    /** The chat's route in the UI (#/agents/<slug>/chat/<id>, #/projects/<p>/chat/<id>, …). */
+    href: string;
+}
+/** The sessions that worked on a task, newest first: what the task page links the log's actors to. */
+export declare function taskSessions(ref: string): Promise<TaskSession[]>;
+/** Consume what was appended since the last run. Serialised: a run that overlaps is queued, never doubled. */
+export declare function consumeTaskEvents(): Promise<number>;
+/** Start consuming the current workspace's task events: on every change signal, on file changes, and every FALLBACK_MS anyway. */
+export declare function startBoardWake(): void;
+export declare function stopBoardWake(): void;

package/dist/core/board-wake.js

@@ -0,0 +1,221 @@
+import { promises as fs, watch } from "node:fs";
+import path from "node:path";
+import { getAgent, listAgents } from "./agents.js";
+import { EVENTS_FILE } from "./boards.js";
+import { onChanged } from "./changes.js";
+import { createChat, listChats, postMessage } from "./chat/sessions.js";
+import { getOutputDir } from "./context.js";
+import { chatHref, dismissKey, pushNotification } from "./notifications.js";
+import { perWorkspace, workspaceOpen } from "./workspace.js";
+/**
+ * Waking agents for their tasks. boards.ts appends a TaskEvent line to
+ * <output>/boards/events.jsonl whenever a task with an agent as assignee
+ * sits in a work column after a change (created there, moved there,
+ * assigned); this module, started by the server for every open workspace,
+ * consumes the file: for each event it opens a session for the agent with
+ * the task as its scope (ChatScope.task → the task block in its context,
+ * unattended like a routine run) and posts why it was woken — or, when the
+ * agent already has a live session for that task, posts into that one.
+ *
+ * The file is read past a remembered offset (<output>/boards/events.offset),
+ * so every line is acted on once; it is rotated when it grows large. Writers
+ * append whole lines (O_APPEND), so a half-written line never appears.
+ */
+const STATE_FILE = "boards/events.offset";
+const ROTATE_OVER = 256 * 1024;
+const FALLBACK_MS = 20_000;
+const consumer = perWorkspace(() => ({
+    timer: null,
+    watcher: null,
+    unsubscribe: null,
+    running: false,
+    again: false,
+}));
+const eventsFile = () => path.join(getOutputDir(), EVENTS_FILE);
+const offsetFile = () => path.join(getOutputDir(), STATE_FILE);
+async function readOffset() {
+    const n = Number(await fs.readFile(offsetFile(), "utf8").catch(() => "0"));
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/** Lines appended since the offset; the new offset. */
+async function readNew() {
+    const file = eventsFile();
+    const st = await fs.stat(file).catch(() => null);
+    if (!st)
+        return { events: [], offset: 0, size: 0 };
+    let offset = await readOffset();
+    if (offset > st.size)
+        offset = 0; // the file was rotated or replaced
+    if (offset === st.size)
+        return { events: [], offset, size: st.size };
+    const fh = await fs.open(file, "r");
+    try {
+        const buf = Buffer.alloc(st.size - offset);
+        await fh.read(buf, 0, buf.length, offset);
+        const text = buf.toString("utf8");
+        const complete = text.lastIndexOf("\n");
+        if (complete < 0)
+            return { events: [], offset, size: st.size };
+        const events = [];
+        for (const line of text.slice(0, complete).split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                /* a broken line is skipped, not retried forever */
+            }
+        }
+        return { events, offset: offset + complete + 1, size: st.size };
+    }
+    finally {
+        await fh.close();
+    }
+}
+/** Keep the file small: once everything is consumed and it is big, start over (a writer racing the rename lands in the new file). */
+async function rotate(offset, size) {
+    if (size < ROTATE_OVER || offset < size)
+        return;
+    await fs.rename(eventsFile(), `${eventsFile()}.old`).catch(() => { });
+    await fs.rm(`${eventsFile()}.old`, { force: true }).catch(() => { });
+    await fs.writeFile(offsetFile(), "0");
+}
+/** The message the agent gets: why it was woken, in one paragraph; the task itself is in its context block. */
+function wakeMessage(ev, resumed) {
+    const who = ev.actor.replace(/^human:/, "");
+    const why = ev.reason === "created"
+        ? `Task ${ev.task} ("${ev.title}") was created for you by ${who}`
+        : ev.reason === "assigned"
+            ? `Task ${ev.task} ("${ev.title}") was handed to you by ${who}`
+            : `Task ${ev.task} ("${ev.title}") was moved to ${ev.status} for you by ${who}`;
+    return (`${why}${ev.message ? `: ${ev.message}` : "."}\n` +
+        (resumed
+            ? `Continue with it: read the task's log for what changed (\`npx kraftwerk tasks show ${ev.task} ${cliFlags(ev)}\`).`
+            : `It is in ${ev.status}. Read the task block in your context (task.md, files, log), move it to the work column when you start, log what you do, and hand it to review when done.`));
+}
+const cliFlags = (ev) => (ev.project ? `--project ${ev.project} --board ${ev.board}` : `--board ${ev.board}`);
+const taskOf = (c) => c.task ?? (c.scope.kind === "agent" ? c.scope.task : undefined);
+/** The sessions that worked on a task, newest first: what the task page links the log's actors to. */
+export async function taskSessions(ref) {
+    const [chats, agents] = await Promise.all([listChats(), listAgents().catch(() => [])]);
+    return chats
+        .filter((c) => taskOf(c) === ref)
+        .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1))
+        .map((c) => {
+        const slug = c.scope.kind === "agent" ? c.scope.slug : c.agent;
+        const def = agents.find((a) => a.slug === slug);
+        return { id: c.id, agent: slug, ...(def ? { name: def.name, emoji: def.emoji } : {}), title: c.title, updatedAt: c.updatedAt, busy: c.busy, href: chatHref(c) };
+    });
+}
+/** One event: post into the agent's live session for this task, or open one. */
+async function wake(ev) {
+    const def = await getAgent(ev.agent);
+    if (!def)
+        throw new Error(`agent "${ev.agent}" not found`);
+    const existing = (await listChats()).find((c) => c.scope.kind === "agent" && c.scope.slug === ev.agent && c.scope.task === ev.ref);
+    // Already on it (a turn is running in its session for this task): the agent reads the log when it looks; no second session.
+    if (existing?.busy)
+        return;
+    const meta = existing ??
+        (await createChat({
+            agent: def.harness,
+            scope: { kind: "agent", slug: ev.agent, task: ev.ref },
+            title: `📋 ${ev.task}`,
+            ...(ev.project ? { project: ev.project } : {}),
+        }));
+    const { error } = await postMessage(meta.id, wakeMessage(ev, !!existing));
+    if (error)
+        throw new Error(error);
+    await dismissKey(`task-wake:${ev.ref}`);
+    await pushNotification({
+        kind: "task_woken",
+        title: `📋 ${ev.task} → ${def.emoji} ${def.name}`,
+        body: ev.message ?? ev.title,
+        href: chatHref(meta),
+        key: `task-woken:${ev.ref}:${ev.agent}`,
+    }).catch(() => { });
+}
+/** Consume what was appended since the last run. Serialised: a run that overlaps is queued, never doubled. */
+export async function consumeTaskEvents() {
+    const c = consumer();
+    if (c.running) {
+        c.again = true;
+        return 0;
+    }
+    c.running = true;
+    let handled = 0;
+    try {
+        const { events, offset, size } = await readNew();
+        if (events.length) {
+            // The offset moves first: an event that keeps failing must not be retried on every tick.
+            await fs.mkdir(path.dirname(offsetFile()), { recursive: true });
+            await fs.writeFile(offsetFile(), String(offset));
+            // The same task for the same agent twice in one batch (assign, then move): the last reason wins.
+            const latest = new Map();
+            for (const ev of events)
+                latest.set(`${ev.ref}:${ev.agent}`, ev);
+            for (const ev of latest.values()) {
+                try {
+                    await wake(ev);
+                    handled++;
+                }
+                catch (err) {
+                    await pushNotification({
+                        kind: "task_wake_failed",
+                        title: `📋 ${ev.task}: ${ev.agent} could not be started`,
+                        body: err.message,
+                        href: ev.project ? `/projects/${ev.project}/boards/${ev.board}/${ev.task}` : `/boards/${ev.board}/${ev.task}`,
+                        key: `task-wake:${ev.ref}`,
+                    }).catch(() => { });
+                }
+            }
+        }
+        await rotate(offset, size);
+    }
+    finally {
+        c.running = false;
+        if (c.again) {
+            c.again = false;
+            void consumeTaskEvents().catch(() => { });
+        }
+    }
+    return handled;
+}
+/** Start consuming the current workspace's task events: on every change signal, on file changes, and every FALLBACK_MS anyway. */
+export function startBoardWake() {
+    const c = consumer();
+    if (c.timer)
+        return;
+    const kick = () => {
+        if (!workspaceOpen())
+            return;
+        void consumeTaskEvents().catch(() => { });
+    };
+    c.timer = setInterval(kick, FALLBACK_MS);
+    c.timer.unref?.();
+    c.unsubscribe = onChanged(kick);
+    const dir = path.dirname(eventsFile());
+    void fs.mkdir(dir, { recursive: true }).then(() => {
+        if (!c.timer || c.watcher)
+            return;
+        try {
+            c.watcher = watch(dir, { persistent: false }, kick);
+            c.watcher.on("error", () => { });
+        }
+        catch {
+            /* no watcher: the interval still runs */
+        }
+    });
+    kick();
+}
+export function stopBoardWake() {
+    const c = consumer();
+    if (c.timer)
+        clearInterval(c.timer);
+    c.timer = null;
+    c.unsubscribe?.();
+    c.unsubscribe = null;
+    c.watcher?.close();
+    c.watcher = null;
+}

package/dist/core/boards.d.ts

@@ -0,0 +1,256 @@
+import { type ResolvedWorkspace } from "../config.js";
+/**
+ * Boards and tasks: the work of a project (or of the whole workspace) as
+ * columns of cards, stored as plain folders so humans, agents and git all
+ * read the same thing. A board holds columns and tasks; a task is a folder
+ * with the markdown that describes it, an append-only log of what happened
+ * to it, and whatever files it needs.
+ *
+ *   projects/<p>/boards/<board>/board.md             # title, columns, default agent + the board's rules (body)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/task.md   # title, status (a column), order, assignee, due, tags, refs + the task (body)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/log.md    # newest first: moves, hand-overs, comments, files (journal format)
+ *   projects/<p>/boards/<board>/tasks/<n>-<slug>/…         # the task's files
+ *   kraftwerk-data/boards/<board>/…                    # workspace boards, same shape (`boards.root`)
+ *
+ * The folder is the registry: a folder with a board.md is a board, a
+ * folder under tasks/ with a task.md is a task. The column is a field of
+ * task.md, not a folder per column, so a move is a one-line diff and the
+ * task's path (links, files) never changes. Task folders are numbered per
+ * board (`50-write-a-press-release`): the number is the short handle in
+ * the CLI, the whole name is the reference token (task:50-write-a-press-release).
+ *
+ * Agents are woken by events, not by polling: whoever writes a task (an API
+ * route, the CLI in another process) appends a line to <output>/boards/events.jsonl
+ * when a task with an agent as assignee sits in a work column, and the server
+ * on this machine consumes the file (board-wake.ts). The output folder is
+ * local, so a clone of the workspace never sees another machine's events.
+ */
+export declare const BOARD_FILE = "board.md";
+export declare const TASK_FILE = "task.md";
+export declare const TASK_LOG = "log.md";
+/** The folder (and the default board's slug) a project's tasks go to when no board is named. */
+export declare const DEFAULT_BOARD = "tasks";
+export interface Column {
+    slug: string;
+    label: string;
+    /** Work-in-progress limit; the UI marks the column when it is exceeded, nothing is refused. */
+    limit?: number;
+    /** Tasks here are finished. */
+    done?: boolean;
+    /** Tasks here wait for a human: they count as attention. */
+    review?: boolean;
+}
+export declare const DEFAULT_COLUMNS: Column[];
+/** Where a board lives: in a project, or at the workspace level. */
+export interface BoardRef {
+    project?: string;
+    board: string;
+}
+export interface BoardDef extends BoardRef {
+    title: string;
+    columns: Column[];
+    /** Tasks entering todo without an assignee get this agent (and wake it). */
+    agent?: string;
+    /** A task in a work column with no log entry for this long shows as stale. Default: 1d. */
+    staleAfter?: string;
+}
+export interface BoardSummary extends BoardDef {
+    /** Absolute folder path. */
+    path: string;
+    updatedAt?: string;
+    /** Set when board.md exists but is unusable; the rest shows defaults. */
+    configError?: string;
+    /** Tasks per column slug (tasks in no known column under ""). */
+    counts: Record<string, number>;
+    tasks: number;
+    /** Tasks in a review column. */
+    review: number;
+}
+export interface BoardDetail extends BoardSummary {
+    /** The body of board.md: what the board is for, the rules agents follow. */
+    notes: string;
+    items: TaskSummary[];
+}
+export interface TaskDef {
+    /** The folder name: <number>-<slug>. */
+    slug: string;
+    number: number;
+    title: string;
+    /** A column slug of the board. */
+    status: string;
+    /** Position inside the column; sparse, renumbered on save. */
+    order: number;
+    /** An agent slug; absent = unassigned. */
+    assignee?: string;
+    due?: string;
+    created: string;
+    tags: string[];
+    /** kind:slug tokens this task refers to. */
+    refs: string[];
+    /** Unknown frontmatter keys, kept as written. */
+    extra?: Record<string, unknown>;
+}
+export interface TaskSummary extends TaskDef {
+    /** The task's reference: <project>/<board>/<slug> or <board>/<slug>. */
+    ref: string;
+    path: string;
+    updatedAt?: string;
+    configError?: string;
+    /** Files in the folder (task.md, log.md and dot files not counted). */
+    files: number;
+    /** The newest log line, without its stamp. */
+    lastLog?: string;
+    /** In a work column with an assignee and nothing logged for staleAfter. */
+    stale?: boolean;
+}
+export interface TaskDetail extends TaskSummary {
+    /** The body of task.md. */
+    notes: string;
+    /** log.md as written. */
+    log: string;
+    /** The task's files, relative to its folder. */
+    fileList: string[];
+    board: string;
+    project?: string;
+}
+export interface BoardsView {
+    enabled: boolean;
+    /** The workspace boards root. */
+    root?: string;
+    boards: BoardSummary[];
+    error?: string;
+}
+/** Every field optional: omitted = untouched. */
+export interface SaveBoardInput {
+    title?: string;
+    columns?: unknown;
+    agent?: string | null;
+    staleAfter?: string | null;
+    notes?: string;
+}
+export interface TaskInput {
+    title?: string;
+    status?: string;
+    order?: number;
+    assignee?: string | null;
+    due?: string | null;
+    tags?: unknown;
+    refs?: unknown;
+    notes?: string;
+}
+/** Who writes (an actor string: human:user, lisa/claude, …) and an optional message for the log. */
+export interface WriteOpts {
+    actor?: string;
+    message?: string;
+}
+export declare function openBoards(): Promise<{
+    project?: ResolvedWorkspace;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Make sure the workspace boards root exists; runs when the feature is switched on. */
+export declare function ensureBoardsRoot(): Promise<void>;
+export declare function safeBoardSlug(slug: string): string;
+/** The folder name of a task: <number>-<slug>. */
+export declare function safeTaskSlug(slug: string): string;
+/** The folder a board lives in: inside its project (projects must be on) or under the workspace root. */
+export declare function boardDir(ref: BoardRef): Promise<string>;
+/** "<project>/<board>" or "<board>". */
+export declare const boardKey: (ref: BoardRef) => string;
+/** "<project>/<board>/<task>" or "<board>/<task>". */
+export declare const taskRef: (ref: BoardRef, task: string) => string;
+/** Parse "<project>/<board>/<task>" or "<board>/<task>" (and the two-or-one-part board forms when `task` is false). */
+export declare function parseTaskRef(text: string): {
+    board: BoardRef;
+    task: string;
+};
+export declare function parseBoardRef(text: string): BoardRef;
+/** "1d", "12h", "90m" -> milliseconds. */
+export declare function parseDuration(text: string): number;
+/** The column `tasks pick` takes from: "todo" when the board has it, else the second column (the first is the inbox), else the only one. */
+export declare const pickColumn: (columns: Column[]) => Column | undefined;
+/** A column's role: work columns — from the pick column on, review and done excepted — are where an assigned agent is expected to act. */
+export declare const isWorkColumn: (c: Column | undefined, columns: Column[]) => boolean;
+export declare const reviewColumn: (columns: Column[]) => Column | undefined;
+/** The boards of a project (its boards/ folder), or the workspace boards when no project is given. */
+export declare function listBoards(project?: string): Promise<BoardsView>;
+/** Every board of the workspace: the workspace ones first, then each project's. */
+export declare function listAllBoards(): Promise<BoardSummary[]>;
+export declare function getBoard(ref: BoardRef): Promise<BoardDetail | null>;
+/** Tasks of a board, optionally narrowed by column, assignee (or "" for unassigned) and tag. */
+export declare function listTasks(ref: BoardRef, filter?: {
+    status?: string;
+    assignee?: string;
+    tag?: string;
+}): Promise<TaskSummary[]>;
+export declare function getTask(ref: BoardRef, idOrNumber: string): Promise<TaskDetail | null>;
+/** Find a task by its reference anywhere: "<project>/<board>/<task>" or "<board>/<task>". */
+export declare function findTask(reference: string): Promise<TaskDetail | null>;
+export declare function createBoard(input: {
+    project?: string;
+    title: string;
+    slug?: string;
+    columns?: unknown;
+    agent?: string;
+    notes?: string;
+}): Promise<BoardDetail>;
+export declare function saveBoard(ref: BoardRef, input: SaveBoardInput): Promise<BoardDetail>;
+/** Move the board folder, tasks and all, to the trash. */
+export declare function deleteBoard(ref: BoardRef): Promise<void>;
+/** The project's default board (`tasks`), created on first use. */
+export declare function ensureDefaultBoard(project?: string): Promise<BoardRef>;
+/** Append a free entry to a task's log: what was done, a comment, a question. */
+export declare function appendTaskLog(ref: BoardRef, idOrNumber: string, entry: string, actor?: string): Promise<TaskDetail>;
+/** What the server acts on: a task with an agent in a work column, after a change of that pair. */
+export interface TaskEvent {
+    at: string;
+    ref: string;
+    project?: string;
+    board: string;
+    task: string;
+    title: string;
+    agent: string;
+    status: string;
+    /** Why the agent is woken, for the message it gets. */
+    reason: "assigned" | "moved" | "created";
+    actor: string;
+    message?: string;
+}
+export declare const EVENTS_FILE = "boards/events.jsonl";
+export declare function createTask(ref: BoardRef, input: TaskInput & {
+    actor?: string;
+    message?: string;
+}): Promise<TaskDetail>;
+/** Merge fields (and the notes when given) into task.md; a status or assignee change is logged and may wake the assignee. */
+export declare function saveTask(ref: BoardRef, idOrNumber: string, input: TaskInput, opts?: WriteOpts): Promise<TaskDetail>;
+/** Put a task into a column (and, with `order`, at a position: the orders of the column are renumbered around it). */
+export declare function moveTask(ref: BoardRef, idOrNumber: string, status: string, opts?: WriteOpts & {
+    order?: number;
+    before?: string;
+}): Promise<TaskDetail>;
+/** Give the task to an agent, or back to the humans (`to` = null: unassigned and into the review column). */
+export declare function assignTask(ref: BoardRef, idOrNumber: string, to: string | null, opts?: WriteOpts): Promise<TaskDetail>;
+/**
+ * An agent takes the next task: the first unassigned (or its own) task in
+ * the pick column, in the column's order (due date as tie-break), becomes
+ * its and moves to the first work column after it. Exclusive: under the
+ * task's lock the file is read again, so two agents never take the same one.
+ */
+export declare function pickTask(ref: BoardRef, agent: string, opts?: {
+    column?: string;
+    actor?: string;
+}): Promise<TaskDetail | null>;
+/** Move the task folder, files and log included, to the trash. */
+export declare function deleteTask(ref: BoardRef, idOrNumber: string): Promise<void>;
+/** Called by the files API after a file was added to or removed from a task folder. */
+export declare function noteTaskFile(reference: string, what: "added" | "removed", file: string, actor?: string): Promise<void>;
+/**
+ * The "## Board: …" blocks of a project chat (or of an agent for the
+ * boards it has tasks on): the board's rules, its columns with counts, the
+ * open tasks, and the CLI. `agent` narrows the task list to that agent's
+ * and the unassigned ones in the pick column.
+ */
+export declare function boardsContext(project: string | undefined, actor: string, agent?: string): Promise<string>;
+/** The block a session gets when it was opened for one task: the task, its files and its whole log. */
+export declare function taskContext(reference: string): Promise<string>;