@starlove/orbit 1.4.0 → 2.0.0

package/lib/core/actors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Who is asking. Orbit has no accounts: a person in the app is the owner, and
+ * an agent says its name (ORBIT_AGENT_NAME, or x-orbit-agent-name over HTTP).
+ * A host with accounts passes its own actors instead.
+ */
+import type { Actor } from "./model.ts";
+/** The person using the app on their own Orbit. */
+export declare function localOwnerActor(): Actor;
+/** An agent that didn't say its name. */
+export declare function localAgentActor(): Actor;
+/** An agent that says its name. */
+export declare function namedAgentActor(name: unknown): Actor;
+/**
+ * The actor a request's headers say: an agent when it says it is one
+ * (`x-orbit-actor-type: agent`) or names itself (`x-orbit-agent-name`), else
+ * the owner.
+ */
+export declare function actorFromHeaders(header: (name: string) => string | undefined): Actor;

package/lib/core/actors.js

@@ -0,0 +1,45 @@
+/**
+ * Who is asking. Orbit has no accounts: a person in the app is the owner, and
+ * an agent says its name (ORBIT_AGENT_NAME, or x-orbit-agent-name over HTTP).
+ * A host with accounts passes its own actors instead.
+ */
+import { asText } from "./text.js";
+const ALL = ["owner", "read", "write", "claim"];
+/** The person using the app on their own Orbit. */
+export function localOwnerActor() {
+    return { id: "local", name: "local", type: "human", role: "owner", permissions: [...ALL], boards: ["*"] };
+}
+/** An agent that didn't say its name. */
+export function localAgentActor() {
+    return { id: "local-agent", name: "agent", type: "agent", role: "owner", permissions: [...ALL], boards: ["*"] };
+}
+function cleanField(value, fallback) {
+    const clean = asText(value).trim().replace(/\s+/g, " ").slice(0, 80);
+    return clean || fallback;
+}
+function idFromName(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || "agent");
+}
+/** An agent that says its name. */
+export function namedAgentActor(name) {
+    const clean = cleanField(name, "agent");
+    return { ...localAgentActor(), id: idFromName(clean), name: clean };
+}
+/**
+ * The actor a request's headers say: an agent when it says it is one
+ * (`x-orbit-actor-type: agent`) or names itself (`x-orbit-agent-name`), else
+ * the owner.
+ */
+export function actorFromHeaders(header) {
+    const type = (header("x-orbit-actor-type") ?? "").trim().toLowerCase();
+    const agentName = header("x-orbit-agent-name") ?? "";
+    if (type !== "agent" && !agentName.trim())
+        return localOwnerActor();
+    const name = cleanField(header("x-orbit-actor-name") || agentName, "agent");
+    const id = cleanField(header("x-orbit-actor-id"), idFromName(name));
+    return { ...localAgentActor(), id, name };
+}

package/lib/core/agent.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The agent flow: an agent takes a card (the next AI Ready one, or one it is
+ * named), reads it with the board's rules, asks when the goal is unclear, and
+ * finishes into Review. Context packs give an agent a card with what is
+ * around it, capped to what it can afford to read.
+ */
+import { boardManual } from "./boards.ts";
+import type { BoardManual } from "./boards.ts";
+import type { CrossCard } from "./cross-board.ts";
+import type { BoardCtx } from "./context.ts";
+import type { Comment, Id, Label, Ticket } from "./model.ts";
+import type { CompactTicket, LanedTicket, TicketView } from "./views.ts";
+import type { BoardReader } from "../store/types.ts";
+/** The comment Orbit writes on every claim. */
+export declare const CLAIM_NOTE = "Agent claimed this ticket and is starting work.";
+export interface Lookup {
+    ticket_id?: unknown;
+    number?: unknown;
+    title?: unknown;
+}
+/** A card by id, number or exact title (any case), on this board, or null. */
+export declare function lookupTicket(r: BoardReader, lookup: Lookup): Promise<Ticket | null>;
+export interface ReadTicket {
+    ticket: {
+        id: Id;
+        number: number;
+        title: string;
+        description: string;
+        state_name: string;
+        type: Ticket["type"];
+        priority: Ticket["priority"];
+        labels: Label[];
+    };
+    board_manual: BoardManual;
+}
+/** A card's title, description, lane and labels, with the board's rules and journal. */
+export declare function readTicket(c: BoardCtx, lookup: Lookup): Promise<ReadTicket>;
+/** A card's comments, oldest first, each with whether it is hidden from agents; an agent never gets a hidden one. */
+export declare function readComments(c: BoardCtx, lookup: Lookup): Promise<{
+    ticket_id: Id;
+    comments: Comment[];
+}>;
+export type ClaimAnswer = {
+    claimed: true;
+    ticket_id: Id;
+    context: ReadTicket;
+} | {
+    claimed: false;
+    reason: "no_schedulable_ticket";
+} | {
+    claimed: false;
+    reason: "blocked";
+    ticket: CompactTicket;
+    blockers: CompactTicket[];
+} | {
+    claimed: false;
+    reason: "already_done";
+    ticket: CompactTicket;
+};
+/**
+ * Takes the next card waiting in AI Ready on this board: highest priority,
+ * then oldest, skipping epics (unless asked) and blocked cards. Moves it to
+ * In Progress with a note.
+ */
+export declare function claimNext(c: BoardCtx, input?: {
+    type?: unknown;
+    include_epics?: unknown;
+}): Promise<ClaimAnswer>;
+/**
+ * Takes one named card. A blocked or done card is refused unless `force`. A
+ * card already In Progress stays where it is; with `becomeHolder` (the
+ * command language's `take`) the caller becomes its holder, noting a takeover.
+ */
+export declare function claimTicket(c: BoardCtx, input: Lookup & {
+    force?: unknown;
+}, options?: {
+    becomeHolder?: boolean;
+}): Promise<ClaimAnswer>;
+/** Pauses for a person: the card goes to Review with the question as a checkpoint comment. */
+export declare function checkpointTicket(c: BoardCtx, input: {
+    ticket_id?: unknown;
+    message?: unknown;
+}): Promise<ContextPack>;
+export interface CompleteInput {
+    ticket_id?: unknown;
+    summary?: unknown;
+    updates?: unknown;
+    pr_url?: unknown;
+    next_state?: unknown;
+    implementation_artifact_path?: unknown;
+    summary_artifact_path?: unknown;
+}
+/** Hands finished work to a person: the card goes to Review (or the lane named) with the summary saved. */
+export declare function completeTicket(c: BoardCtx, input: CompleteInput): Promise<ContextPack>;
+export interface ContextOptions {
+    max_chars_per_field?: unknown;
+    include_parent_full?: unknown;
+    include_related_full?: unknown;
+    comment_limit?: unknown;
+}
+export interface ContextPack {
+    ticket: TicketView & {
+        labels: Label[];
+    };
+    board: {
+        id: Id;
+        slug: string;
+        name: string;
+        default_branch: string;
+    };
+    parent_ticket: unknown;
+    child_tickets: unknown[];
+    relations: unknown[];
+    blockers: LanedTicket[];
+    /** Cards on other boards this card waits on; present only when there are some. */
+    waiting_on?: CrossCard[];
+    related_tickets: unknown[];
+    board_manual?: BoardManual;
+}
+/**
+ * A card with what is around it: its board, epic, sub-cards (with their
+ * labels and blockers), relations, blockers and related cards. `full` adds
+ * the board's rules and journal.
+ */
+export declare function contextPack(c: BoardCtx, ticketId: Id, options?: ContextOptions, full?: boolean): Promise<ContextPack>;
+/** A lean packet for handing one card to an agent: capped text, blockers, the lanes it will move through, recent visible comments. */
+export declare function dispatchPacket(c: BoardCtx, ticketId: Id, options?: ContextOptions): Promise<Record<string, unknown>>;
+export { boardManual };

package/lib/core/agent.js

@@ -0,0 +1,323 @@
+/**
+ * The agent flow: an agent takes a card (the next AI Ready one, or one it is
+ * named), reads it with the board's rules, asks when the goal is unclear, and
+ * finishes into Review. Context packs give an agent a card with what is
+ * around it, capped to what it can afford to read.
+ */
+import { boardManual, manualOf } from "./boards.js";
+import { cardLinkFromInput } from "./card-paths.js";
+import { crossBlockers, crossBlockersFor } from "./cross-board.js";
+import { isAgent } from "./context.js";
+import { OrbitError } from "./errors.js";
+import { record, reindex, touchTicket } from "./history.js";
+import { normalizeTicketType, appendNote, cap, nonNegativeInt, positiveInt, requiredString, asText } from "./text.js";
+import { ticketOn } from "./tickets.js";
+import { Lanes, compactTicket, currentHolder, isHolder, labelsByTicket, laned, relationRows, ticketView, unresolvedBlockers } from "./views.js";
+/** Another board's blocking card, in the short form a claim's answer lists blockers in. */
+function compactCross(card) {
+    return { id: card.id, board_id: card.board_id, board_slug: card.board_slug, number: card.number, title: card.title, type: card.type, state_name: card.state_name, state_role: card.state_role, priority: card.priority };
+}
+/** The comment Orbit writes on every claim. */
+export const CLAIM_NOTE = "Agent claimed this ticket and is starting work.";
+/** A card by id, number or exact title (any case), on this board, or null. */
+export async function lookupTicket(r, lookup) {
+    if (lookup.ticket_id)
+        return r.tickets.get(asText(lookup.ticket_id));
+    if (lookup.number !== undefined && lookup.number !== null && lookup.number !== "") {
+        const n = Number(lookup.number);
+        if (!Number.isInteger(n))
+            throw new OrbitError("invalid_number");
+        return r.tickets.byNumber(n);
+    }
+    if (lookup.title)
+        return r.tickets.byTitle(asText(lookup.title));
+    throw new OrbitError("ticket_id_or_number_or_title_required");
+}
+/** A card's title, description, lane and labels, with the board's rules and journal. */
+export async function readTicket(c, lookup) {
+    return c.data.read(async (r) => {
+        const ticket = await lookupTicket(r, lookup);
+        if (!ticket)
+            throw new OrbitError("ticket_not_found");
+        const [lanes, labels, board, entries] = await Promise.all([Lanes.of(r), labelsByTicket(r, [ticket.id]), r.board.get(), r.entries.list()]);
+        return {
+            ticket: {
+                id: ticket.id,
+                number: ticket.number,
+                title: ticket.title,
+                description: ticket.description,
+                state_name: lanes.nameOf(ticket),
+                type: ticket.type,
+                priority: ticket.priority,
+                labels: labels.get(ticket.id) ?? []
+            },
+            board_manual: manualOf(c, board, entries)
+        };
+    });
+}
+/** A card's comments, oldest first, each with whether it is hidden from agents; an agent never gets a hidden one. */
+export async function readComments(c, lookup) {
+    return c.data.read(async (r) => {
+        const ticket = await lookupTicket(r, lookup);
+        if (!ticket)
+            throw new OrbitError("ticket_not_found");
+        const comments = await r.comments.list(ticket.id);
+        return { ticket_id: ticket.id, comments: isAgent(c.actor) ? comments.filter((comment) => !comment.omitted_for_ai) : comments };
+    });
+}
+async function inProgressLane(lanes) {
+    const lane = lanes.forRole("in_progress", "In Progress");
+    if (!lane)
+        throw new OrbitError("missing_in_progress_state");
+    return Promise.resolve(lane);
+}
+async function noteComment(w, c, ticketId, kind, body, at) {
+    await w.comments.insert({ id: c.ids.next(), ticket_id: ticketId, author: c.actor.name, kind, body, omitted_for_ai: 0, created_at: at });
+}
+/**
+ * Takes the next card waiting in AI Ready on this board: highest priority,
+ * then oldest, skipping epics (unless asked) and blocked cards. Moves it to
+ * In Progress with a note.
+ */
+export async function claimNext(c, input = {}) {
+    const type = input.type ? normalizeTicketType(input.type) : "";
+    const includeEpics = Boolean(input.include_epics);
+    const claimed = await c.data.write(async (w) => {
+        const lanes = await Lanes.of(w);
+        const ready = lanes.list.filter((state) => state.role === "ai_ready" || (state.role === null && state.name === "AI Ready"));
+        const candidates = [];
+        for (const lane of ready)
+            candidates.push(...(await w.tickets.list({ state: lane.id, archived: false })));
+        candidates.sort((a, b) => b.priority - a.priority || a.created_at.localeCompare(b.created_at) || a.number - b.number);
+        // Cards waiting on another board's card: one read per other board, for every candidate at once.
+        const elsewhere = await crossBlockers(c, await w.crossBoardRelations.list());
+        for (const candidate of candidates) {
+            if (type ? candidate.type !== type : !includeEpics && candidate.type === "epic")
+                continue;
+            if ((await unresolvedBlockers(w, candidate.id, lanes)).length || elsewhere.get(candidate.id)?.length)
+                continue;
+            const inProgress = await inProgressLane(lanes);
+            const at = c.clock.now();
+            await w.tickets.update(candidate.id, { state_id: inProgress.id, updated_at: at });
+            await noteComment(w, c, candidate.id, "agent_note", CLAIM_NOTE, at);
+            await record(w, c, "agent_claimed", candidate.id, { agent_id: c.actor.id, from: lanes.nameOf(candidate), to: inProgress.name });
+            await reindex(w, candidate.id);
+            await touchTicket(w, candidate.parent_ticket_id, at);
+            return candidate.id;
+        }
+        return null;
+    });
+    if (!claimed)
+        return { claimed: false, reason: "no_schedulable_ticket" };
+    c.changed(c.board.id);
+    return { claimed: true, ticket_id: claimed, context: await readTicket(c, { ticket_id: claimed }) };
+}
+/**
+ * Takes one named card. A blocked or done card is refused unless `force`. A
+ * card already In Progress stays where it is; with `becomeHolder` (the
+ * command language's `take`) the caller becomes its holder, noting a takeover.
+ */
+export async function claimTicket(c, input, options = {}) {
+    const force = Boolean(input.force);
+    const result = await c.data.write(async (w) => {
+        const ticket = await lookupTicket(w, input);
+        if (!ticket || ticket.archived_at)
+            throw new OrbitError("ticket_not_found");
+        const lanes = await Lanes.of(w);
+        const view = { ...laned(ticket, lanes), board_slug: c.board.slug };
+        const blockers = [...(await unresolvedBlockers(w, ticket.id, lanes)).map(compactTicket), ...(await crossBlockersFor(c, w, ticket.id)).map(compactCross)];
+        if (blockers.length && !force)
+            return { claimed: false, reason: "blocked", ticket: compactTicket(view), blockers };
+        if (lanes.roleOf(ticket) === "done" && !force)
+            return { claimed: false, reason: "already_done", ticket: compactTicket(view) };
+        const inProgress = await inProgressLane(lanes);
+        const at = c.clock.now();
+        if (ticket.state_id !== inProgress.id) {
+            await w.tickets.update(ticket.id, { state_id: inProgress.id, updated_at: at });
+            await noteComment(w, c, ticket.id, "agent_note", CLAIM_NOTE, at);
+            await record(w, c, "agent_claimed", ticket.id, { agent_id: c.actor.id, from: lanes.nameOf(ticket), to: inProgress.name });
+            await reindex(w, ticket.id);
+            await touchTicket(w, ticket.parent_ticket_id, at);
+            return { claimed: true, ticket_id: ticket.id, wrote: true };
+        }
+        if (options.becomeHolder) {
+            const holder = await currentHolder(w, ticket.id);
+            if (!isHolder(holder, c.actor)) {
+                await w.tickets.update(ticket.id, { updated_at: at });
+                if (holder)
+                    await noteComment(w, c, ticket.id, "agent_note", `Took over from @${holder.name}.`, at);
+                await record(w, c, "agent_claimed", ticket.id, { agent_id: c.actor.id, from: lanes.nameOf(ticket), to: inProgress.name, ...(holder ? { took_over_from: holder.name } : {}) });
+                await reindex(w, ticket.id);
+                return { claimed: true, ticket_id: ticket.id, wrote: true };
+            }
+        }
+        return { claimed: true, ticket_id: ticket.id, wrote: false };
+    });
+    if (!result.claimed)
+        return result;
+    if ("wrote" in result && result.wrote)
+        c.changed(c.board.id);
+    return { claimed: true, ticket_id: result.ticket_id, context: await readTicket(c, { ticket_id: result.ticket_id }) };
+}
+/** Pauses for a person: the card goes to Review with the question as a checkpoint comment. */
+export async function checkpointTicket(c, input) {
+    const ticketId = requiredString(input.ticket_id, "ticket_id");
+    await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const lanes = await Lanes.of(w);
+        const review = lanes.forRole("review", "Review");
+        if (!review)
+            throw new OrbitError("missing_review_state");
+        const message = requiredString(input.message, "message");
+        const at = c.clock.now();
+        await w.tickets.update(ticket.id, { state_id: review.id, updated_at: at });
+        await noteComment(w, c, ticket.id, "checkpoint", message, at);
+        await record(w, c, "checkpoint_requested", ticket.id, { from: lanes.nameOf(ticket), state: review.name, to: review.name, actor_type: c.actor.type, actor_id: c.actor.id });
+        await reindex(w, ticket.id);
+        await touchTicket(w, ticket.parent_ticket_id, at);
+    });
+    c.changed(c.board.id);
+    return contextPack(c, ticketId);
+}
+/** Hands finished work to a person: the card goes to Review (or the lane named) with the summary saved. */
+export async function completeTicket(c, input) {
+    const ticketId = requiredString(input.ticket_id, "ticket_id");
+    await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const lanes = await Lanes.of(w);
+        const next = input.next_state ? lanes.byName(asText(input.next_state)) : lanes.forRole("review", "Review");
+        if (!next)
+            throw new OrbitError("missing_next_state");
+        const summary = requiredString(input.summary, "summary");
+        const prUrl = typeof input.pr_url === "string" ? input.pr_url : "";
+        const at = c.clock.now();
+        await noteComment(w, c, ticket.id, "completion", [summary, ...(prUrl ? [`PR: ${prUrl}`] : [])].join("\n\n"), at);
+        const given = input.implementation_artifact_path || input.summary_artifact_path;
+        const artifact = given ? cardLinkFromInput(c, c.board.id, given) : ticket.implementation_artifact_path;
+        await w.tickets.update(ticket.id, {
+            state_id: next.id,
+            implementation_summary: summary,
+            implementation_artifact_path: artifact,
+            implementation_updates: input.updates ? appendNote(ticket.implementation_updates, input.updates) : ticket.implementation_updates,
+            updated_at: at
+        });
+        await record(w, c, "agent_completed", ticket.id, { from: lanes.nameOf(ticket), next_state: next.name, to: next.name, pr_url: prUrl, actor_type: c.actor.type, actor_id: c.actor.id });
+        await reindex(w, ticket.id);
+        await touchTicket(w, ticket.parent_ticket_id, at);
+    });
+    c.changed(c.board.id);
+    return contextPack(c, ticketId);
+}
+const LONG_FIELDS = ["description", "ai_plan", "implementation_summary", "implementation_updates"];
+function capFields(ticket, max) {
+    if (!max)
+        return ticket;
+    const copy = { ...ticket };
+    for (const field of LONG_FIELDS)
+        if (Object.hasOwn(copy, field))
+            copy[field] = cap(copy[field], max);
+    return copy;
+}
+/**
+ * A card with what is around it: its board, epic, sub-cards (with their
+ * labels and blockers), relations, blockers and related cards. `full` adds
+ * the board's rules and journal.
+ */
+export async function contextPack(c, ticketId, options = {}, full = false) {
+    const max = positiveInt(options.max_chars_per_field, 0);
+    const parentFull = Boolean(options.include_parent_full);
+    const relatedFull = Boolean(options.include_related_full);
+    const pack = await c.data.read(async (r) => {
+        const ticket = await ticketOn(r, ticketId);
+        const [lanes, board] = await Promise.all([Lanes.of(r), r.board.get()]);
+        const view = (t) => ticketView(t, lanes, c.board);
+        const relations = await relationRows(r, ticketId, lanes, c.board);
+        const blockers = await unresolvedBlockers(r, ticketId, lanes);
+        const parent = ticket.parent_ticket_id ? await r.tickets.get(ticket.parent_ticket_id) : null;
+        const children = await r.tickets.list({ parent: ticketId, archived: false });
+        const grandchildren = children.length ? await r.tickets.list({ archived: false }) : [];
+        const related = new Map();
+        for (const t of [...relations.map((row) => row.other_ticket), ...children.map(view), ...(parent ? [view(parent)] : [])])
+            if (!related.has(t.id))
+                related.set(t.id, t);
+        const labels = await labelsByTicket(r, [ticketId, ...children.map((t) => t.id), ...(parent ? [parent.id] : []), ...related.keys()]);
+        const labelsOf = (id) => labels.get(id) ?? [];
+        const childRows = [];
+        for (const child of children) {
+            childRows.push({
+                ...capFields({ ...view(child), labels: labelsOf(child.id), blockers: await unresolvedBlockers(r, child.id, lanes) }, max),
+                child_count: grandchildren.filter((t) => t.parent_ticket_id === child.id).length
+            });
+        }
+        const pack = {
+            ticket: capFields({ ...view(ticket), labels: labelsOf(ticketId) }, max),
+            board: { id: board.id, slug: board.slug, name: board.name, default_branch: board.default_branch || "main" },
+            parent_ticket: parent ? (parentFull ? capFields({ ...view(parent), labels: labelsOf(parent.id) }, max) : compactTicket(view(parent))) : null,
+            child_tickets: childRows,
+            relations: relations.map((row) => ({ ...row, other_ticket: relatedFull ? capFields({ ...row.other_ticket, labels: labelsOf(row.other_ticket.id) }, max) : compactTicket(row.other_ticket) })),
+            blockers,
+            related_tickets: [...related.values()].map((t) => (relatedFull ? capFields({ ...t, labels: labelsOf(t.id) }, max) : compactTicket(t)))
+        };
+        const elsewhere = await crossBlockersFor(c, r, ticketId);
+        if (elsewhere.length)
+            pack.waiting_on = elsewhere;
+        if (full)
+            pack.board_manual = manualOf(c, board, await r.entries.list());
+        return pack;
+    });
+    return pack;
+}
+function acceptance(description) {
+    const match = /(?:^|\n)\s*(?:acceptance criteria|acceptance)\s*:?\s*\n([\s\S]*)/i.exec(description);
+    return match?.[1]?.trim() ?? "";
+}
+/** A lean packet for handing one card to an agent: capped text, blockers, the lanes it will move through, recent visible comments. */
+export async function dispatchPacket(c, ticketId, options = {}) {
+    const max = positiveInt(options.max_chars_per_field, 4000);
+    const commentLimit = Math.min(nonNegativeInt(options.comment_limit, 5), 20);
+    return c.data.read(async (r) => {
+        const ticket = await ticketOn(r, ticketId);
+        const [lanes, board, labels, comments] = await Promise.all([Lanes.of(r), r.board.get(), labelsByTicket(r, [ticketId]), r.comments.list(ticketId)]);
+        const parent = ticket.parent_ticket_id ? await r.tickets.get(ticket.parent_ticket_id) : null;
+        const blockers = [...(await unresolvedBlockers(r, ticketId, lanes)).map(compactTicket), ...(await crossBlockersFor(c, r, ticketId)).map(compactCross)];
+        const visible = comments.filter((comment) => !comment.omitted_for_ai);
+        const recent = (commentLimit ? visible.slice(-commentLimit) : [])
+            .map((comment) => ({ id: comment.id, author: comment.author, kind: comment.kind, body: cap(comment.body, max), created_at: comment.created_at }));
+        const id = (role, name) => lanes.forRole(role, name)?.id ?? null;
+        return {
+            board: { id: board.id, slug: board.slug, name: board.name, default_branch: board.default_branch || "main", agent_instructions: cap(board.agent_instructions, max) },
+            ticket: {
+                id: ticket.id,
+                ticket_id: ticket.id,
+                number: ticket.number,
+                title: ticket.title,
+                type: ticket.type,
+                priority: ticket.priority,
+                state_id: ticket.state_id,
+                state_name: lanes.nameOf(ticket),
+                state_role: lanes.roleOf(ticket),
+                description: cap(ticket.description, max),
+                acceptance: cap(acceptance(ticket.description), max),
+                ai_plan: cap(ticket.ai_plan, max),
+                plan_artifact_path: ticket.plan_artifact_path,
+                implementation_summary: cap(ticket.implementation_summary, max),
+                implementation_artifact_path: ticket.implementation_artifact_path,
+                implementation_updates: cap(ticket.implementation_updates, max),
+                labels: (labels.get(ticketId) ?? []).map((label) => label.name)
+            },
+            blockers: { can_start: blockers.length === 0, blockers },
+            parent_ticket: parent ? compactTicket({ ...laned(parent, lanes), board_slug: c.board.slug }) : null,
+            relevant_state_ids: {
+                current: ticket.state_id,
+                current_role: lanes.roleOf(ticket),
+                ai_ready: id("ai_ready", "AI Ready"),
+                in_progress: id("in_progress", "In Progress"),
+                review: id("review", "Review"),
+                done: id("done", "Done"),
+                todo: lanes.byName("Todo")?.id ?? null
+            },
+            recent_comments: recent
+        };
+    });
+}
+export { boardManual };

package/lib/core/boards.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Boards: making one with its lanes, its settings, its journal, its context
+ * for agents, and deleting it.
+ */
+import type { BoardCtx, Ctx } from "./context.ts";
+import type { Board, BoardEntry, Id, RegisteredBoard } from "./model.ts";
+import type { TicketView } from "./views.ts";
+import type { BoardWriter } from "../store/types.ts";
+export interface NewBoardInput {
+    name?: unknown;
+    slug?: unknown;
+    repo_url?: unknown;
+    default_branch?: unknown;
+    ai_enabled?: unknown;
+    /** The lanes to start with, as [name, role] pairs; the usual seven (six without AI) when absent. */
+    states?: unknown;
+}
+/** Makes a board with its lanes, and lists it. Answers the board's own record. */
+export declare function createBoard(c: Ctx, input: NewBoardInput): Promise<Board>;
+/**
+ * Makes sure the lanes the agent flow needs exist: AI Ready right after Todo
+ * (so taking work has a predictable lane), In Progress and Review. Changes
+ * only what isn't so.
+ */
+export declare function ensureAgentLanes(w: BoardWriter, c: Ctx, boardId: Id): Promise<void>;
+export interface BoardUpdate {
+    name?: unknown;
+    repo_url?: unknown;
+    default_branch?: unknown;
+    project_notes?: unknown;
+    agent_instructions?: unknown;
+    ai_enabled?: unknown;
+}
+/** Changes a board's settings; turning AI on adds the agent lanes. */
+export declare function updateBoard(c: BoardCtx, input: BoardUpdate): Promise<Board>;
+export interface BoardManual {
+    board: Omit<Board, "project_notes">;
+    entries: BoardEntry[];
+    /** Where this Orbit runs, for the person's own app; never in an agent's answer. */
+    deployment?: {
+        app_root: string;
+        data_dir: string;
+        data_dir_default: boolean;
+        mcp_server_path: string;
+        db_path: string;
+    };
+}
+/** The board's rules for agents and its journal (newest first; struck entries only when asked). */
+export declare function boardManual(c: BoardCtx, options?: {
+    includeStruck?: boolean;
+}): Promise<BoardManual>;
+export declare function manualOf(c: BoardCtx, board: Board, entries: BoardEntry[], options?: {
+    includeStruck?: boolean;
+}): BoardManual;
+export interface NewEntryInput {
+    type?: unknown;
+    title?: unknown;
+    body?: unknown;
+    ticket_id?: unknown;
+}
+/** A decision or a lesson in the board's journal, optionally about a card. */
+export declare function createEntry(c: BoardCtx, input: NewEntryInput): Promise<BoardEntry>;
+/** Strikes a journal entry, or brings it back. */
+export declare function strikeEntry(c: BoardCtx, entryId: Id, input: {
+    struck?: unknown;
+}): Promise<BoardEntry>;
+/**
+ * Deletes a struck journal entry for good. Only a person may: an agent strikes
+ * an entry, which takes it out of agents' context and leaves the person to
+ * decide. An entry still live is refused, so nothing goes in one step.
+ */
+export declare function deleteEntry(c: BoardCtx, entryId: Id): Promise<{
+    ok: true;
+    deleted_id: Id;
+}>;
+/** A board's archived cards, most recently archived first. */
+export declare function archivedTickets(c: BoardCtx): Promise<TicketView[]>;
+export interface BoardListing {
+    id: Id;
+    slug: string;
+    name: string;
+    repo_url: string;
+    default_branch: string;
+    /** Where the board's data is, for the person's own app; never for an agent. */
+    db_path?: string;
+    last_active_at: string | null;
+}
+/** Every board, by name: a small list without opening any board. */
+export declare function listBoards(c: Ctx): Promise<{
+    boards: BoardListing[];
+}>;
+export interface RemovedBoard {
+    ok: true;
+    deleted_board_id: Id;
+    deleted_board_slug: string;
+    deleted_files: boolean;
+    /** What was deleted, for the person's own app; never for an agent. */
+    artifacts?: {
+        path: string;
+        removed: true;
+    }[];
+}
+/**
+ * Deletes a board once its slug is typed back. A copy is kept first where the
+ * storage can make one. With `delete_files: false` the board leaves the list
+ * and its data stays. Never an agent's, as with a replace: refused before
+ * anything is read, whatever the transport (the JSON API, or a host's
+ * in-process client).
+ */
+export declare function deleteBoard(c: Ctx, board: RegisteredBoard, input: {
+    confirm_slug?: unknown;
+    delete_files?: unknown;
+}): Promise<RemovedBoard>;