@loompad/cli 0.1.0 → 1.1.2

package/dist/core/crew.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Agent Teams, Phase 1 — a crew for one person, working one goal at a time
+ * (docs/proposals/agent-teams.md).
+ *
+ * A crew is a named set of teammates — roster agents with a role (lead,
+ * builder, reviewer, tester, researcher) and a charter. A goal runs the
+ * "Ship" play in its own worktree, on its own branch, one turn at a time:
+ *
+ *   Lead plans cards → (you approve) → for each card in order:
+ *     a builder builds it → Loom commits → the reviewer reviews the diff
+ *     (changes go back to the same builder, same session) → the tester runs
+ *     the tests (a failure goes back to the builder) → the card is done.
+ *   Then the Lead writes the summary, and the branch is yours to apply.
+ *
+ * Everything a teammate does lands in its own thread; the crew's channel gets
+ * the plan, the hand-offs, the reviews and anything a teammate posts. You
+ * talk to the crew in that channel. Teammates speak the protocol in
+ * core/crew-protocol.ts. Parallel builders, per-teammate native sessions and
+ * crews across people are later phases (§11).
+ */
+import type { TeamPolicy } from "./team-policy.js";
+import type { OrchestraCoordinator, TaskHold, OrchestraRun } from "./orchestra.js";
+import { type ContinuityEngine } from "./continuity/engine.js";
+import type { Adapter, AgentConfig, ChatInfo, EventKind, LoomEvent } from "../types.js";
+import { type BoardTask } from "./registry.js";
+import { type CrewMemoryKind, type CrewRole } from "./crew-protocol.js";
+export interface CrewTeammate {
+    /** Unique within the crew ("lead", "builder-1"). */
+    id: string;
+    /** A roster agent id. Several teammates may share one; each gets its own session. */
+    agent: string;
+    role: CrewRole;
+    charter?: string;
+}
+export interface CrewConfig {
+    id: string;
+    name: string;
+    teammates: CrewTeammate[];
+    /** The Lead's plan waits for your OK before anyone builds (default on). */
+    planApproval?: boolean;
+    /** How many times a card may go back to its builder from review or test (default 2). */
+    maxRounds?: number;
+    /** What the tester runs, when you'd rather say than have it look. */
+    testCommand?: string;
+    /** Minutes a teammate may go silent before its turn is interrupted and retried once (default 8). */
+    stallMinutes?: number;
+    play?: "ship" | "fanout" | "race";
+    maxParallel?: number;
+    budgetUsd?: number;
+}
+export type CardStage = "planned" | "building" | "review" | "testing" | "ready" | "done" | "failed";
+export interface CrewCard {
+    /** The board task id. */
+    id: string;
+    title: string;
+    detail?: string;
+    touches?: string[];
+    role: CrewRole;
+    assignee?: string;
+    blockedBy: string[];
+    stage: CardStage;
+    /** Teammate building it. */
+    builder?: string;
+    /** Times it went back to the builder. */
+    rounds: number;
+    /** What the builder is told next (review notes, test failures, your messages). */
+    feedback: string[];
+    commits: string[];
+    workspace?: {
+        dir: string;
+        branch: string;
+        base: string;
+        integrated?: boolean;
+    };
+    hold?: {
+        reason: string;
+        with: string[];
+    };
+    overlap?: string;
+    teamHold?: TaskHold;
+    summary?: string;
+    error?: string;
+}
+export type GoalStatus = "planning" | "awaiting_approval" | "running" | "waiting_human" | "waiting_team" | "paused" | "completed" | "failed" | "stopped" | "interrupted";
+export interface CrewGoal {
+    sourceRequestId?: string;
+    requestTarget?: string;
+    play?: "ship" | "fanout" | "race";
+    selected?: string;
+    recovery?: string;
+    pr?: {
+        url: string;
+        at: number;
+    };
+    deliveryError?: string;
+    budgetUsd?: number;
+    teamWait?: string;
+    pauseRequested?: boolean;
+    pauseReason?: string;
+    resumeStatus?: GoalStatus;
+    id: string;
+    text: string;
+    status: GoalStatus;
+    /** Branch and worktree the goal is built in, cut from `base`. */
+    branch: string;
+    dir: string;
+    base: string;
+    baseBranch: string;
+    cards: CrewCard[];
+    /** What is happening right now (a card's stage, or the plan). */
+    current?: {
+        teammate: string;
+        card?: string;
+        step: string;
+    };
+    question?: {
+        teammate: string;
+        text: string;
+        step: "plan" | "card";
+    };
+    summary?: string;
+    error?: string;
+    /** Plan turns that came back without a plan. */
+    rounds?: number;
+    costUsd: number;
+    spendBySeat?: Record<string, number>;
+    startedAt: number;
+    finishedAt?: number;
+    applied?: {
+        into: string;
+        at: number;
+    };
+}
+export interface CrewState {
+    id: string;
+    channel: string;
+    threads: Record<string, string>;
+    goal?: CrewGoal;
+    history: Array<{
+        id: string;
+        text: string;
+        status: GoalStatus;
+        summary?: string;
+        finishedAt?: number;
+        branch: string;
+    }>;
+    /** Messages for a teammate's next turn (from you, or posted by another teammate). */
+    notes: Record<string, string[]>;
+    /** Durable native bindings, keyed by seat rather than roster agent. */
+    sessions?: Record<string, {
+        bindingId: string;
+        epoch: number;
+        nativeSessionId: string | null;
+    }>;
+    inbox?: Array<{
+        id: string;
+        from: string;
+        to: string;
+        text: string;
+        expiresAt: number;
+        status: "queued" | "running" | "waiting_human" | "delivered" | "failed";
+        result?: string;
+        error?: string;
+    }>;
+}
+export interface CrewView extends CrewConfig {
+    state: CrewState;
+    busy: boolean;
+    active: Array<{
+        teammate: string;
+        card?: string;
+        step: string;
+        since: number;
+    }>;
+    spentToday: number;
+}
+export interface CrewHost {
+    projectId: string;
+    projectName: string;
+    projectDir: string;
+    crews(): CrewConfig[];
+    saveCrews(crews: CrewConfig[]): void;
+    roster(): AgentConfig[];
+    makeAgent(cfg: AgentConfig, dir: string): Adapter;
+    append(e: {
+        kind: EventKind;
+        agentId?: string;
+        chat?: string;
+        payload: Record<string, unknown>;
+    }): LoomEvent;
+    createChat(title: string, opts?: {
+        agentId?: string;
+    }): ChatInfo;
+    chatExists(id: string): boolean;
+    briefingFor(query: string, agentId: string, crewId?: string): string | Promise<string>;
+    native?(): ContinuityEngine | null;
+    nativeOptions?(cfg: AgentConfig): Record<string, unknown>;
+    nativeHealth?(id: string): Promise<{
+        available: boolean;
+        error?: string;
+    }>;
+    coordinator?(): OrchestraCoordinator | null;
+    policy?(): TeamPolicy | null;
+    spentToday?(crew?: string): number;
+    gitDelivery?(): string;
+    gate(agentId: string): void;
+    observe(event: LoomEvent): void;
+    stream?(f: {
+        agentId: string;
+        chat: string;
+        text: string;
+        reasoning?: boolean;
+    }): void;
+    createTask(input: {
+        title: string;
+        column?: string;
+        agent?: string;
+        blockedBy?: string[];
+    }): BoardTask;
+    updateTask(id: string, patch: Record<string, unknown>): BoardTask | null;
+    /** Save a memory a teammate asked the crew to keep (scope: this crew, until a human promotes it). */
+    remember?(m: {
+        crewId: string;
+        kind: CrewMemoryKind;
+        text: string;
+        agentId: string;
+        eventId: number;
+    }): void;
+    /** The GitHub login running this daemon, when on a team (commit trailers). */
+    member?(): string | null;
+    /** Tests: how long silence counts as a stall, in ms (else the crew's stallMinutes, else 8 min). */
+    stallMs?: number;
+    /** How long a crew's test command may run (default 10 min). */
+    testTimeoutMs?: number;
+}
+export declare const CREW_TEMPLATES: string[];
+/** Fill a template's roles from the roster; the reviewer avoids the builders' vendor when it can. */
+export declare function teammatesFromTemplate(template: string, roster: AgentConfig[]): CrewTeammate[];
+export declare class CrewEngine {
+    private readonly host;
+    private states;
+    /** Live adapters for the active goal: `${crew}/${teammate}`. */
+    private agents;
+    private agentOptions;
+    /** Teammates blocked on a structured question: key → the request, its question ids, the thread. */
+    private waiting;
+    /** A teammate's live instance by its id (`crew-<crew>-<seat>.<agent>`), for answering its questions. */
+    liveAgent(instanceId: string): Adapter | undefined;
+    private running;
+    private turnText;
+    private turnError;
+    private turnQuestion;
+    private activeTurns;
+    /** When each live teammate last showed a sign of life (any event or streamed text). */
+    private lastActivity;
+    private gitChain;
+    private closed;
+    private loops;
+    private stopping;
+    private seatTurns;
+    private testControllers;
+    private teamRechecks;
+    private deliveries;
+    constructor(host: CrewHost);
+    /** The agents a teammate can be. */
+    roster(): AgentConfig[];
+    list(): CrewView[];
+    get(id: string): CrewView;
+    create(input: {
+        name?: string;
+        template?: string;
+        teammates?: CrewTeammate[];
+        planApproval?: boolean;
+        testCommand?: string;
+        play?: CrewConfig["play"];
+        maxParallel?: number;
+        budgetUsd?: number;
+    }): CrewView;
+    update(id: string, patch: {
+        name?: string;
+        teammates?: CrewTeammate[];
+        planApproval?: boolean;
+        testCommand?: string | null;
+        stallMinutes?: number | null;
+        play?: CrewConfig["play"];
+        maxParallel?: number;
+        budgetUsd?: number | null;
+    }): CrewView;
+    remove(id: string): Promise<void>;
+    private validate;
+    /** Give the crew a goal. It plans in the channel and (by default) waits for your OK. */
+    goal(id: string, text: string, play?: CrewConfig["play"], request?: {
+        id: string;
+        to: string;
+    }): Promise<CrewGoal>;
+    /**
+     * You, in the channel. With no goal on, it becomes the goal; while the crew
+     * waits on a question it's the answer; otherwise it's a note for the
+     * teammate you name (or the Lead) on its next turn.
+     */
+    say(id: string, text: string, to?: string): Promise<{
+        routed: "goal" | "answer" | "note" | "replan";
+        to?: string;
+    }>;
+    /** OK the Lead's plan: building starts. */
+    approve(id: string): CrewGoal;
+    /** Stop: the current turn is interrupted, and the goal ends where it is (its branch stays). */
+    stop(id: string): Promise<CrewGoal>;
+    /** Carry on an interrupted (or stopped) goal from the step it was on. */
+    resume(id: string): CrewGoal;
+    /** Merge a finished goal's branch into the branch you're on. */
+    apply(id: string): Promise<{
+        merged: string;
+        into: string;
+    }>;
+    shutdown(): Promise<void>;
+    private drive;
+    private loop;
+    private plan;
+    private validPlay;
+    receiveRequest(id: string, request: {
+        id: string;
+        from: string;
+        to: string;
+        text: string;
+        expiresAt: number;
+    }): Promise<{
+        delivery: string;
+    }>;
+    private deliverRequest;
+    private planApproval;
+    coordination(id: string): OrchestraRun | undefined;
+    coordinationRuns(): OrchestraRun[];
+    addTeamNote(runId: string, text: string): boolean;
+    private admit;
+    holdForTeam(runId: string, cardId: string, hold: TaskHold): Promise<void>;
+    private waitForTeam;
+    decideOverlap(id: string, cardId: string, decision: string, touches?: string[]): CrewGoal;
+    pause(id: string): CrewGoal;
+    raiseBudget(id: string, amount: number): CrewGoal;
+    private validParallel;
+    private validBudget;
+    /** A bounded wave owns its declared file scopes through review and test. */
+    private parallel;
+    private cardWorkspace;
+    private integrateCard;
+    pick(id: string, choice: string): Promise<CrewGoal>;
+    private addCards;
+    /** One card through build → review → test. */
+    private work;
+    private giveUp;
+    private wrapUp;
+    private finish;
+    deliver(id: string): Promise<{
+        url: string;
+    }>;
+    private deliverOnce;
+    /**
+     * Send one teammate one prompt in the goal's worktree and wait for the turn.
+     * Its role, charter, crewmates, protocol and any notes ride in the briefing.
+     * Null when the goal stopped meanwhile.
+     */
+    private turn;
+    private runTurn;
+    private wire;
+    private briefing;
+    /** A teammate's `remember`: said in the channel, kept in the crew's memory that every teammate's briefing reads. */
+    private remember;
+    private post;
+    private phase;
+    private commit;
+    /** What a card changed: its first commit's parent to the worktree's tip. */
+    private cardDiff;
+    /** A goal's whole change against where it started. */
+    goalDiff(id: string): Promise<string>;
+    private builderFor;
+    private lead;
+    private reviewer;
+    private tester;
+    /** Is there a test step: a test command Loom runs, or a tester teammate? */
+    private tests;
+    private thread;
+    private config;
+    private state;
+    private archive;
+    private dropWorktree;
+    private stopAgents;
+    private assertNativeIdle;
+    /** Explicitly start a fresh native epoch for one stopped teammate. */
+    refresh(id: string, teammate: string): Promise<CrewView>;
+    private serial;
+    private stateFile;
+    private load;
+    private save;
+}