@starlove/orbit 1.4.1 → 2.0.0

package/lib/client/types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * One client for every Orbit: `OrbitClient`. `orbit.client(actor)` calls the
+ * core in this process (the CLI, `orbit mcp` on a computer); `createHttpClient`
+ * calls an Orbit over `fetch` (remote agents, the web app, the Suite). Its
+ * methods mirror the JSON API, one route to one method, and each answer is
+ * that route's answer.
+ */
+import type { ClaimAnswer, CompleteInput, ContextOptions, ContextPack, Lookup, ReadTicket } from "../core/agent.ts";
+import type { BoardListing, BoardManual, BoardUpdate, NewBoardInput, NewEntryInput, RemovedBoard } from "../core/boards.ts";
+import type { Bootstrap } from "../core/bootstrap.ts";
+import type { CrossBoardRelationAnswer } from "../core/cross-board.ts";
+import type { AttachmentView, StoredArtifact } from "../core/files.ts";
+import type { AgentSession, Board, BoardChange, BoardEntry, Comment, Id, Relation, State } from "../core/model.ts";
+import type { TicketBlockers, TicketRelations } from "../core/relations.ts";
+import type { SearchAnswer, SearchInput } from "../core/search.ts";
+import type { ImportInput, ImportResult } from "../core/snapshots.ts";
+import type { HistoryEntry, NewTicketInput, TicketUpdate } from "../core/tickets.ts";
+import type { NewVerdictInput, VerdictView } from "../core/verdicts.ts";
+import type { TicketView } from "../core/views.ts";
+/** A command line, as `POST /api/cmd` takes it. */
+export interface CommandInput {
+    /** The line: `view`, `take #12`, `finish #12`. */
+    command?: string;
+    /** The words, already split (a shell's argv), instead of `command`. */
+    argv?: string[];
+    /** Long text: a summary, note, description or question. */
+    text?: string;
+    /** Answer with JSON data instead of text. */
+    json?: boolean;
+    /** Refuse anything that changes the board (the `orbit_read` tool). */
+    readOnly?: boolean;
+    /** How the answer's hints are written: `orbit view` in a shell, `view` elsewhere. */
+    transport?: "cli" | "mcp" | "http";
+}
+/** What a command answers: `ok` false means the line was refused, and `text` says how to put it right. */
+export interface CommandReply {
+    ok: boolean;
+    text: string;
+    /** The board the session has chosen, if any. */
+    board: string | null;
+    kind: "read" | "write";
+    data?: unknown;
+}
+export interface VersionInfo {
+    current: string;
+    deployMode: string;
+    selfUpdate: boolean;
+    repoUrl: string;
+    changesUrl: string;
+    enabled: boolean;
+    latest: string | null;
+    updateAvailable: boolean;
+    error: string | null;
+    checkedAt: string | null;
+}
+/**
+ * What the computer Orbit runs on can do for the app open on it. A host
+ * without one (the browser edition) leaves it out, and its route answers 404.
+ */
+export interface HostServices {
+    version?: (options: {
+        force: boolean;
+    }) => Promise<VersionInfo>;
+    /** Starts a self-update, or null when the operator didn't turn it on (the route answers 404). */
+    selfUpdate?: () => Record<string, unknown> | null;
+    /** Opens a folder picker on this computer; `unsupported` when it has none. */
+    pickFolder?: () => Promise<Record<string, unknown> & {
+        unsupported?: boolean;
+    }>;
+}
+/** The state of a live stream of changes, for a notice when it drops. */
+export type StreamState = "connecting" | "live" | "down";
+export interface ChangesOptions {
+    /** Told each time the stream's state changes. In process, it is live at once and stays so. */
+    onState?: (state: StreamState) => void;
+}
+/**
+ * An image's address for an `<img>`: a route of the server, or an object URL
+ * where the bytes come from no server (the browser edition). Call `release()`
+ * when the image is no longer shown, so an object URL's bytes can go.
+ */
+export interface ImageUrl {
+    url: string;
+    release(): void;
+}
+/** Where to look first for a record named by id (a board's id or slug); a hint naming no board is refused with `board_not_found`. */
+export interface Hint {
+    board?: string | null;
+    board_id?: Id | null;
+}
+export interface OrbitClient {
+    health(): Promise<{
+        ok: true;
+    }>;
+    /** This Orbit's version, and whether a newer one is out (`refresh` checks again now). Refused with `not_found` where the host has no version check. */
+    version(options?: {
+        refresh?: boolean;
+    }): Promise<VersionInfo>;
+    /** Starts updating the computer's Orbit. Refused with `not_found` where self-update is off (always in the browser). */
+    update(): Promise<Record<string, unknown>>;
+    bootstrap(options?: Hint): Promise<Bootstrap>;
+    sessions(options?: {
+        since?: unknown;
+    }): Promise<{
+        since: string;
+        sessions: AgentSession[];
+    }>;
+    command(input: CommandInput): Promise<CommandReply>;
+    search(board: Hint, query: SearchInput): Promise<SearchAnswer>;
+    boards: {
+        list(): Promise<{
+            boards: BoardListing[];
+        }>;
+        create(input: NewBoardInput): Promise<Board>;
+        update(board: string, patch: BoardUpdate): Promise<Board>;
+        remove(board: string, input: {
+            confirm_slug?: unknown;
+            delete_files?: unknown;
+        }): Promise<RemovedBoard>;
+        context(board: string, options?: {
+            include_struck?: boolean;
+        }): Promise<BoardManual>;
+        archive(board: string): Promise<{
+            tickets: TicketView[];
+        }>;
+        export(board: string, options?: {
+            include_attachments?: boolean;
+        }): Promise<Record<string, unknown>>;
+        import(input: ImportInput & Hint): Promise<ImportResult>;
+    };
+    states: {
+        create(board: string, input: {
+            name?: unknown;
+            role?: unknown;
+        }): Promise<State>;
+        update(id: Id, patch: {
+            name?: string;
+            is_default?: boolean;
+            role?: string | null;
+        }, hint?: Hint): Promise<State>;
+        reorder(board: string, input: {
+            state_ids?: unknown;
+        }): Promise<State[]>;
+        remove(id: Id, hint?: Hint): Promise<{
+            ok: true;
+            deleted_state_id: Id;
+        }>;
+    };
+    tickets: {
+        create(input: NewTicketInput & Hint): Promise<TicketView>;
+        lookup(board: Hint, by: {
+            number?: unknown;
+            title?: unknown;
+        }): Promise<ReadTicket>;
+        read(id: Id, hint?: Hint): Promise<ReadTicket>;
+        update(id: Id, patch: TicketUpdate, hint?: Hint): Promise<TicketView>;
+        archive(id: Id, hint?: Hint): Promise<TicketView>;
+        restore(id: Id, hint?: Hint): Promise<TicketView>;
+        remove(id: Id, hint?: Hint): Promise<{
+            ok: true;
+            deleted_id: Id;
+        }>;
+        context(id: Id, options?: ContextOptions, hint?: Hint): Promise<ContextPack>;
+        contextFull(id: Id, options?: ContextOptions, hint?: Hint): Promise<ContextPack>;
+        dispatchPacket(id: Id, options?: ContextOptions, hint?: Hint): Promise<Record<string, unknown>>;
+        history(id: Id, hint?: Hint): Promise<HistoryEntry[]>;
+        relations(id: Id, hint?: Hint): Promise<TicketRelations>;
+        blockers(id: Id, hint?: Hint): Promise<TicketBlockers>;
+    };
+    comments: {
+        list(ticketId: Id, hint?: Hint): Promise<{
+            ticket_id: Id;
+            comments: Comment[];
+        }>;
+        create(ticketId: Id, input: {
+            body?: unknown;
+            author?: unknown;
+            kind?: unknown;
+        }, hint?: Hint): Promise<Comment>;
+        update(ticketId: Id, commentId: Id, patch: {
+            omitted_for_ai?: unknown;
+        }, hint?: Hint): Promise<Comment>;
+    };
+    attachments: {
+        list(ticketId: Id, hint?: Hint): Promise<{
+            attachments: AttachmentView[];
+        }>;
+        create(ticketId: Id, bytes: Uint8Array, meta: {
+            mime_type: string;
+            original_name?: string;
+        }, hint?: Hint): Promise<AttachmentView>;
+        /** Its bytes; a type Orbit won't show comes as `application/octet-stream`, with `download_only` set. */
+        content(ticketId: Id, attachmentId: Id, hint?: Hint): Promise<{
+            bytes: Uint8Array;
+            mime_type: string;
+            download_only: boolean;
+            original_name: string;
+        }>;
+        /** An address to show the image at (see ImageUrl). */
+        url(ticketId: Id, attachmentId: Id, hint?: Hint): Promise<ImageUrl>;
+        remove(ticketId: Id, attachmentId: Id, hint?: Hint): Promise<{
+            ok: true;
+            deleted_id: Id;
+        }>;
+    };
+    artifacts: {
+        read(ticketId: Id, path: string, hint?: Hint): Promise<StoredArtifact & {
+            content: string;
+        }>;
+        write(ticketId: Id, input: {
+            filename?: unknown;
+            path?: unknown;
+            content?: unknown;
+        }, hint?: Hint): Promise<StoredArtifact>;
+    };
+    verdicts: {
+        list(ticketId: Id, options?: {
+            limit?: unknown;
+        }, hint?: Hint): Promise<{
+            review_verdicts: VerdictView[];
+        }>;
+        create(ticketId: Id, input: NewVerdictInput, hint?: Hint): Promise<VerdictView>;
+        get(id: Id, board: Hint): Promise<VerdictView>;
+    };
+    entries: {
+        create(board: string, input: NewEntryInput): Promise<BoardEntry>;
+        update(id: Id, patch: {
+            struck?: unknown;
+        }, hint?: Hint): Promise<BoardEntry>;
+        /** Deletes a struck entry: a person's call (`forbidden` for an agent, `entry_not_struck` for a live one). */
+        remove(id: Id, hint?: Hint): Promise<{
+            ok: true;
+            deleted_id: Id;
+        }>;
+    };
+    relations: {
+        /** With `target_board` naming another board (slug or id), a link across boards, made on the waiting card's board. */
+        create(input: {
+            source_ticket_id?: unknown;
+            target_ticket_id?: unknown;
+            type?: unknown;
+            target_board?: unknown;
+        } & Hint): Promise<Relation | CrossBoardRelationAnswer>;
+        remove(id: Id, hint?: Hint): Promise<{
+            ok: true;
+        }>;
+    };
+    agent: {
+        claimNext(board: Hint, filters?: {
+            type?: unknown;
+            include_epics?: unknown;
+        }): Promise<ClaimAnswer>;
+        claim(input: Lookup & {
+            force?: unknown;
+        } & Hint): Promise<ClaimAnswer>;
+        checkpoint(input: {
+            ticket_id?: unknown;
+            message?: unknown;
+        } & Hint): Promise<ContextPack>;
+        complete(input: CompleteInput & Hint): Promise<ContextPack>;
+    };
+    /**
+     * A board's committed changes, from any writer: watch() in process, the
+     * event stream over HTTP (which reconnects by itself, resuming after the
+     * last change heard). Returns the function that stops.
+     */
+    changes(board: Id, listener: (change: BoardChange) => void, options?: ChangesOptions): () => void;
+}

package/lib/client/types.js

@@ -0,0 +1,8 @@
+/**
+ * One client for every Orbit: `OrbitClient`. `orbit.client(actor)` calls the
+ * core in this process (the CLI, `orbit mcp` on a computer); `createHttpClient`
+ * calls an Orbit over `fetch` (remote agents, the web app, the Suite). Its
+ * methods mirror the JSON API, one route to one method, and each answer is
+ * that route's answer.
+ */
+export {};

package/lib/commands/agent-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Orbit's agent surface: two MCP tools that take a command line (orbit_read,
+ * orbit_write), the server's `instructions`, and the per-instance llms.txt.
+ * All of it is written from the command table (./index.ts), so what agents
+ * are told is what runs.
+ */
+/** The `initialize` instructions. Codex reads the first 512 characters first, so all of it fits there. */
+export declare const ORBIT_COMMAND_INSTRUCTIONS: string;
+export interface ToolDefinition {
+    name: "orbit_read" | "orbit_write";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: "string";
+            description: string;
+        }>;
+        required: string[];
+        additionalProperties: false;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint?: boolean;
+    };
+}
+export declare function commandTools(): ToolDefinition[];
+/** The onboarding text an instance serves at /llms.txt: how to connect, then the grammar. */
+export declare function instanceLlmsTxt({ origin, version }: {
+    origin: string;
+    version: string;
+}): string;

package/lib/commands/agent-tools.js

@@ -0,0 +1,100 @@
+/**
+ * Orbit's agent surface: two MCP tools that take a command line (orbit_read,
+ * orbit_write), the server's `instructions`, and the per-instance llms.txt.
+ * All of it is written from the command table (./index.ts), so what agents
+ * are told is what runs.
+ */
+import { COMMANDS } from "./index.js";
+/** The `initialize` instructions. Codex reads the first 512 characters first, so all of it fits there. */
+export const ORBIT_COMMAND_INSTRUCTIONS = [
+    "Orbit is the user's kanban board: cards (#12) in lanes. Start with orbit_read `view`.",
+    "Loop: orbit_write `take` (next AI Ready card, or `take #12`), do the work, then `finish #12` with a summary in text (it goes to Review).",
+    "Unclear? `ask #12` with what's missing, then stop.",
+    "The board's rules come with each card you take and win over these defaults: work on a branch, commit locally, never push or deploy.",
+    "`help` lists every command."
+].join(" ");
+const isRead = (command) => command.kind === "read";
+/** Short usages for tool descriptions; a command that both reads and writes (boards) appears in each. */
+function usages(kind, skip = []) {
+    return COMMANDS.filter((command) => !skip.includes(command.name))
+        .map((command) => (command.briefs ? command.briefs[kind] : isRead(command) === (kind === "read") ? command.brief : null))
+        .filter((brief) => Boolean(brief))
+        .join("; ");
+}
+export function commandTools() {
+    return [
+        {
+            name: "orbit_read",
+            description: `Read the user's Orbit board (kanban). One command line. Cards are #n, lanes by name. Commands: ${usages("read")}. Add --json for structured output.`,
+            inputSchema: {
+                type: "object",
+                properties: { command: { type: "string", description: "e.g. view, card #12" } },
+                required: ["command"],
+                additionalProperties: false
+            },
+            annotations: { readOnlyHint: true }
+        },
+        {
+            name: "orbit_write",
+            description: "Change the user's Orbit board. One command line; long text (summary, note, description, question) goes in text. " +
+                "Loop: take [#n] -> do the work -> finish #n (text: what changed, how you checked; it goes to Review, never Done unless asked). " +
+                "Goal unclear: ask #n (text: what's missing), then stop. " +
+                `Also: ${usages("write", ["take", "finish", "ask"])}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "e.g. take, move #12 review, finish #12" },
+                    text: { type: "string", description: "summary, note, description or question" }
+                },
+                required: ["command"],
+                additionalProperties: false
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false }
+        }
+    ];
+}
+/** The onboarding text an instance serves at /llms.txt: how to connect, then the grammar. */
+export function instanceLlmsTxt({ origin, version }) {
+    const read = COMMANDS.filter(isRead).map((command) => `  ${command.usage}: ${command.summary}`);
+    const write = COMMANDS.filter((command) => !isRead(command)).map((command) => `  ${command.usage}: ${command.summary}`);
+    return [
+        "# Starscape Orbit",
+        "",
+        `> A kanban board for people and their agents. This instance: ${origin} (Orbit ${version}).`,
+        "",
+        "## Connect an agent",
+        "",
+        "MCP (Claude Code, Codex, Cursor, Goose, Hermes); needs Orbit installed where the agent runs (`npm i -g @starlove/orbit`):",
+        "",
+        "```",
+        `claude mcp add orbit --scope user -e ORBIT_MODE=remote -e ORBIT_API_URL=${origin} -e ORBIT_AGENT_NAME=<your-name> -- orbit mcp`,
+        "```",
+        "",
+        "It gives two tools: orbit_read and orbit_write, each taking one command line (long text in `text`).",
+        "",
+        "A shell works too, with no MCP at all:",
+        "",
+        "```",
+        `export ORBIT_MODE=remote ORBIT_API_URL=${origin} ORBIT_AGENT_NAME=<your-name>`,
+        "orbit view",
+        'orbit take && orbit finish 12 -m "what changed; how you checked"',
+        "```",
+        "",
+        `Or HTTP: POST ${origin}/api/cmd with {"command": "view", "board": "<slug>", "text": "..."}; headers x-orbit-actor-type: agent and x-orbit-agent-name: <your-name>.`,
+        "",
+        "## Commands",
+        "",
+        "Cards are #n (or board#n, or the link orbit:card/<board>/<n>); lanes by name; priorities are words. Add --json for structured output.",
+        "",
+        "Read:",
+        ...read,
+        "",
+        "Write:",
+        ...write,
+        "",
+        "## The loop",
+        "",
+        'take (the next AI Ready card, or take #n) -> do the work -> finish #n with what changed and how you checked it; the card goes to Review. If the goal or "done" is unclear: ask #n with what\'s missing, then stop. The board\'s rules arrive with each card you take and win over your defaults. Never edit Orbit\'s SQLite files.',
+        ""
+    ].join("\n");
+}

package/lib/commands/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The command language: one grammar table (COMMANDS) that the CLI, both MCP
+ * tools (`orbit_read`, `orbit_write`) and `POST /api/cmd` all run, and from
+ * which help, the MCP tool descriptions and `/llms.txt` are written.
+ *
+ * Whether a line reads or writes is decided from its parsed words, before it
+ * runs, so no option can move a write past `orbit_read`'s check.
+ */
+import type { Actor } from "../core/model.ts";
+import type { CommandInput, CommandReply } from "../client/types.ts";
+import type { Args, FlagKind } from "./parse.ts";
+import type { Session, Transport } from "./session.ts";
+import type { Outcome } from "./verbs.ts";
+export { createSession, repoBoardFromRequest } from "./session.ts";
+export type { RepoChoice, RepoSource, Session, Transport } from "./session.ts";
+export { cardLink, parseCardRef, shellSafe, tokenize } from "./parse.ts";
+export { agentLines } from "./verbs.ts";
+export type Kind = "read" | "write";
+export interface Command {
+    name: string;
+    /** Its line in the MCP tools' descriptions; null to leave it out. */
+    brief?: string | null;
+    /** Lines for each tool, when the command both reads and writes. */
+    briefs?: {
+        read: string;
+        write: string;
+    };
+    aliases: string[];
+    /** Read or write, from the parsed words when it depends on them. */
+    kind: Kind | ((positional: string[], session: Session) => Kind);
+    /** How a refusal from orbit_read names the command. */
+    label?: (positional: string[]) => string;
+    /** A refusal from orbit_read that says more than "send it with orbit_write". */
+    readOnlyText?: (positional: string[]) => string | null;
+    usage: string;
+    summary: string;
+    /** Takes long text (-m, the text field). */
+    text?: boolean;
+    flags?: Record<string, FlagKind>;
+    run: (session: Session, args: Args) => Promise<Outcome>;
+}
+export declare const COMMANDS: readonly Command[];
+/** `help` (or `help <command>`) for an actor and transport, without a data folder: it reads no board. */
+export declare function helpText(actor: Actor, transport: Transport, words?: string[]): Promise<{
+    ok: boolean;
+    text: string;
+}>;
+/** A command by name or alias. */
+export declare function commandNamed(word: string): Command | undefined;
+/**
+ * Runs one command line. Never throws for a mistake in the line: that comes
+ * back as ok false with a text that says how to put it right.
+ */
+export declare function runCommand(input: CommandInput & {
+    line?: string;
+}, session: Session): Promise<CommandReply>;