@loompad/cli 0.1.0 → 1.1.2

package/dist/core/team-hub.d.ts

@@ -0,0 +1,514 @@
+/**
+ * Loom Teams — the hub protocol, and an in-memory hub that is its reference.
+ *
+ * The Team Hub is the thin coordination plane between members' daemons
+ * (docs/teams-architecture.md). Three implementations speak `HubClient`:
+ *
+ *   - MemoryHub (here): in-process, authoritative for the rules. Tests and the
+ *     local hub server both run it, so the rules are written once.
+ *   - HttpHubClient (src/hub/client.ts): talks to `loom hub` — a self-hosted
+ *     hub with no Supabase (D1), and the way two daemons meet in tests.
+ *   - Supabase (supabase/migrations/0002_teams.sql): the hosted hub, the same
+ *     rules as row-level security and SQL functions.
+ *
+ * Phase 1 ("see each other"): teams, members, devices, invites, key envelopes,
+ * shared repos, presence heartbeats and a durable feed. What the hub stores is
+ * plain metadata plus sealed content it cannot read (D2).
+ */
+import type { Sealed } from "./team-crypto.js";
+import { type LeaseScope } from "./team-leases.js";
+export type TeamRole = "owner" | "member" | "viewer";
+export interface HubUser {
+    id: string;
+    github: string;
+    name: string;
+}
+export interface Team {
+    id: string;
+    name: string;
+    createdAt: number;
+    /** Current team-key version; bumped by rotation (D6). */
+    keyVersion: number;
+}
+export interface HubDevice {
+    id: string;
+    userId: string;
+    label: string;
+    sealPub: string;
+    signPub: string;
+    createdAt: number;
+}
+export interface MemberView {
+    user: HubUser;
+    role: TeamRole;
+    joinedAt: number;
+    devices: HubDevice[];
+}
+/** One live session on one member's machine (D24: intent, not transcripts). */
+export interface PresenceIn {
+    deviceId: string;
+    repo: string;
+    runId?: string;
+    taskId?: string;
+    agent: string;
+    kind: string;
+    branch?: string;
+    touches: string[];
+    state: "idle" | "planning" | "running" | "reviewing" | "waiting_human" | "ci";
+    since: number;
+    /** Goal title, task title, intent line — sealed to the team. */
+    sealed?: Sealed;
+    sig?: string;
+}
+export interface Presence extends PresenceIn {
+    teamId: string;
+    userId: string;
+    github: string;
+    ts: number;
+}
+/** A goal's claim on part of a repo (Phase 2, D28–D36). */
+export interface Lease extends LeaseScope {
+    id: string;
+    teamId: string;
+    userId: string;
+    github: string;
+    deviceId: string;
+    repo: string;
+    runId: string;
+    taskId: string;
+    /** active while the task runs; landing after it finishes, until the goal's PR merges (D36). */
+    state: "active" | "landing";
+    /** Goal/task titles, sealed to the team (D2). */
+    sealed?: Sealed;
+    since: number;
+    ts: number;
+    /** Computed on read: no renewal within LEASE_TTL_MS (the owner's laptop is asleep — D12). */
+    stale?: boolean;
+}
+export interface LeaseClaim extends LeaseScope {
+    deviceId: string;
+    repo: string;
+    runId: string;
+    taskId: string;
+    /** The team policy's hard zones, as the claimer's reviewed loom.team.json says (D37). */
+    hardZones: string[];
+    sealed?: Sealed;
+}
+export interface ClaimResult {
+    /** Null when refused (a hard zone is held — D31). */
+    lease: Lease | null;
+    /** Everyone else's live leases this one overlaps, with the colliding paths (D29: advisory). */
+    overlaps: Array<{
+        lease: Lease;
+        paths: string[];
+    }>;
+    blockedBy?: {
+        lease: Lease;
+        zone: string;
+    };
+}
+/**
+ * A memory shared with the team (Phase 3, D40–D51). The hub holds its content
+ * sealed; `hmac` (HMAC of the normalized text under the team key) lets it
+ * merge exact duplicates as confirmations without reading them (D41).
+ */
+export interface TeamMemory {
+    id: string;
+    teamId: string;
+    repo: string;
+    authorId: string;
+    author: string;
+    hmac: string;
+    sealed: Sealed;
+    /** live → in briefings; superseded → resolved against (D47); forgotten → its author withdrew it. */
+    state: "live" | "superseded" | "forgotten";
+    /** A correction points at what it corrects (D40). */
+    supersedes?: string;
+    supersededBy?: string;
+    resolvedBy?: string;
+    resolvedReason?: string;
+    /** Members whose agents learned exactly this — the author first (D41). */
+    confirmedBy: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface TeamMemoryIn {
+    id: string;
+    repo: string;
+    hmac: string;
+    sealed: Sealed;
+    deviceId: string;
+    supersedes?: string;
+}
+export type FeedType = "crew_request" | "crew_request_answered" | "member_joined" | "member_left" | "key_rotated" | "repo_shared" | "goal_started" | "goal_finished" | "plan_written" | "pr_opened" | "pr_merged" | "pr_closed" | "check_failed" | "check_passed" | "review_requested" | "review_submitted" | "lease_released" | "overlap_decided" | "drift" | "zone_waiting" | "conflict_predicted" | "memory_resolved" | "canon_proposed" | "goal_landed" | "goal_needs_someone" | "goal_adopted" | "goal_returned" | "check_flaky" | "goal_moved" | "deploy_started" | "deploy_succeeded" | "deploy_failed" | "land_queued" | "land_turn";
+export interface FeedIn {
+    repo?: string;
+    type: FeedType;
+    /** Plain metadata: ids, numbers, states, branch names, paths. */
+    meta: Record<string, unknown>;
+    /** Titles and free text, sealed to the team. */
+    sealed?: Sealed;
+    deviceId?: string;
+    sig?: string;
+    /** Idempotency: the same key twice appends once (GitHub events get polled repeatedly). */
+    dedupeKey?: string;
+}
+export interface FeedEvent extends FeedIn {
+    id: number;
+    teamId: string;
+    userId: string | null;
+    github: string | null;
+    ts: number;
+}
+/**
+ * A runner (Phase 5, D67–D71): one member's always-on Loom daemon that takes
+ * goals from the hub. A device of that member, marked runner.
+ */
+export interface Runner {
+    deviceId: string;
+    userId: string;
+    github: string;
+    label: string;
+    /** Agent kinds installed on it. */
+    kinds: string[];
+    /** Takes any member's goals, not just its owner's (D68). */
+    shared: boolean;
+    /** Goals at once. */
+    capacity: number;
+    lastSeen: number;
+}
+export type JobKind = "start" | "continue" | "fix" | "return" | "land";
+export type JobState = "queued" | "claimed" | "done" | "failed" | "cancelled";
+/** Work for a runner (D71). Everything but routing metadata is sealed to the team. */
+export interface Job {
+    id: string;
+    teamId: string;
+    repo: string;
+    kind: JobKind;
+    /** Who asked. */
+    userId: string;
+    github: string;
+    /** A specific runner (device id), or any eligible one. */
+    target?: string;
+    state: JobState;
+    runnerId?: string;
+    runnerGithub?: string;
+    claimedAt?: number;
+    heartbeatAt?: number;
+    /** The goal, the run record, the briefing. */
+    sealed: Sealed;
+    /** The runner's latest snapshot of the goal (status, tasks, landing). */
+    progress?: Sealed;
+    result?: Sealed;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface JobIn {
+    repo: string;
+    kind: JobKind;
+    target?: string;
+    sealed: Sealed;
+    deviceId: string;
+}
+/** A claimed job whose runner went quiet this long is claimable again (D12, D71). */
+export declare const JOB_TTL_MS: number;
+export type HubEvent = {
+    type: "memory";
+    teamId: string;
+    memory: TeamMemory;
+} | {
+    type: "lease";
+    teamId: string;
+    lease: Lease;
+} | {
+    type: "lease_gone";
+    teamId: string;
+    leaseIds: string[];
+    runId: string;
+} | {
+    type: "presence";
+    teamId: string;
+    presence: Presence;
+} | {
+    type: "presence_gone";
+    teamId: string;
+    userId: string;
+    deviceId: string;
+    agent: string;
+    repo: string;
+} | {
+    type: "feed";
+    teamId: string;
+    event: FeedEvent;
+} | {
+    type: "job";
+    teamId: string;
+    job: Job;
+};
+/** Everything a daemon (or phone) can do against a hub, as one signed-in user. */
+export interface HubClient {
+    me(): Promise<HubUser>;
+    createTeam(name: string): Promise<Team>;
+    teams(): Promise<Array<Team & {
+        role: TeamRole;
+    }>>;
+    registerDevice(input: {
+        label: string;
+        sealPub: string;
+        signPub: string;
+    }): Promise<HubDevice>;
+    createInvite(teamId: string, ttlMs?: number): Promise<{
+        invite: string;
+        expiresAt: number;
+    }>;
+    redeemInvite(invite: string): Promise<{
+        team: Team;
+        role: TeamRole;
+    }>;
+    members(teamId: string): Promise<MemberView[]>;
+    removeMember(teamId: string, userId: string): Promise<void>;
+    /** Store a new key version sealed to each device. Owners only; version must be current or next. */
+    putKeyEnvelopes(teamId: string, version: number, envelopes: Array<{
+        deviceId: string;
+        box: string;
+    }>): Promise<void>;
+    keyEnvelopes(teamId: string, deviceId: string): Promise<Array<{
+        version: number;
+        box: string;
+    }>>;
+    shareRepo(teamId: string, repo: string): Promise<void>;
+    repos(teamId: string): Promise<string[]>;
+    heartbeat(teamId: string, p: PresenceIn): Promise<void>;
+    /** Tell teammates a session ended now, rather than waiting for the TTL. */
+    clearPresence(teamId: string, key: {
+        deviceId: string;
+        agent: string;
+        repo: string;
+    }): Promise<void>;
+    presence(teamId: string): Promise<Presence[]>;
+    appendFeed(teamId: string, e: FeedIn): Promise<FeedEvent | null>;
+    feed(teamId: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): Promise<FeedEvent[]>;
+    subscribe(teamId: string, cb: (e: HubEvent) => void): Promise<() => void>;
+    claimLease(teamId: string, c: LeaseClaim): Promise<ClaimResult>;
+    /** Widen a lease to more paths (drift, D33). Same answer shape as a claim; a held hard zone refuses. */
+    extendLease(teamId: string, leaseId: string, scope: LeaseScope, hardZones: string[]): Promise<ClaimResult>;
+    /** Heartbeat for leases: keeps every lease of this device fresh (D12). */
+    renewLeases(teamId: string, deviceId: string): Promise<number>;
+    setRunLeaseState(teamId: string, runId: string, state: "active" | "landing"): Promise<number>;
+    /** The goal merged or was abandoned (D36). Owners release their own; returns how many. */
+    releaseLeases(teamId: string, runId: string, reason: string): Promise<number>;
+    leases(teamId: string, repo?: string): Promise<Lease[]>;
+    /** Share a memory; an exact duplicate (same hmac) becomes a confirmation instead (D41). */
+    publishMemory(teamId: string, m: TeamMemoryIn): Promise<{
+        memory: TeamMemory;
+        merged: boolean;
+    }>;
+    /** The author revises their own memory (D40). */
+    updateTeamMemory(teamId: string, id: string, patch: {
+        hmac: string;
+        sealed: Sealed;
+    }): Promise<TeamMemory>;
+    /** The author withdraws it (made private, or forgotten). */
+    forgetTeamMemory(teamId: string, id: string, reason: string): Promise<void>;
+    /** A human picks the winner of a contradiction or duplicate; the loser is superseded, kept (D47). */
+    resolveMemories(teamId: string, winnerId: string, loserId: string, reason: string): Promise<TeamMemory>;
+    /** Live memories (D50 snapshot); with history, superseded and forgotten ones too. */
+    teamMemories(teamId: string, repo: string, opts?: {
+        history?: boolean;
+    }): Promise<TeamMemory[]>;
+    /** Mark one of your devices a runner (or update it). Visible to every team you're in. */
+    registerRunner(input: {
+        deviceId: string;
+        kinds: string[];
+        shared: boolean;
+        capacity?: number;
+    }): Promise<Runner>;
+    /** Runners that can take this team's goals: members' runners. */
+    runners(teamId: string): Promise<Runner[]>;
+    /** Remove one of your devices (a runner being revoked); rotate the team key after (D74). */
+    revokeDevice(deviceId: string): Promise<void>;
+    createJob(teamId: string, j: JobIn): Promise<Job>;
+    /** The oldest job this runner may take, claimed atomically; null when none. */
+    claimJob(teamId: string, runnerDeviceId: string, instantOnly?: boolean): Promise<Job | null>;
+    /** The claiming runner is alive; optionally with a progress snapshot. */
+    heartbeatJob(teamId: string, jobId: string, runnerDeviceId: string, progress?: Sealed): Promise<Job>;
+    finishJob(teamId: string, jobId: string, runnerDeviceId: string, outcome: {
+        state: "done" | "failed";
+        result?: Sealed;
+        error?: string;
+    }): Promise<Job>;
+    /** Its author withdraws it; a runner holding it stops. */
+    cancelJob(teamId: string, jobId: string): Promise<Job>;
+    jobs(teamId: string, opts?: {
+        active?: boolean;
+    }): Promise<Job[]>;
+    /** The team's webhook secret, created on first ask; `rotate` replaces it. Owners only. */
+    webhookSecret(teamId: string, rotate?: boolean): Promise<{
+        secret: string;
+    }>;
+}
+export declare class HubError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** A heartbeat older than this is a session that stopped (laptop closed, crash). */
+export declare const PRESENCE_TTL_MS = 45000;
+export declare const INVITE_TTL_MS: number;
+/** A short, one-way tag for an invite token: names it in the feed without revealing it. */
+export declare function inviteTag(invite: string): string;
+export declare const FREE_SEATS = 3;
+/** A lease not renewed for this long is stale: its owner's machine is asleep or gone (D12). */
+export declare const LEASE_TTL_MS: number;
+export declare function normalizeRepo(repo: string): string;
+export declare class MemoryHub {
+    private now;
+    private users;
+    private tokens;
+    private teamsById;
+    private memberships;
+    private devices;
+    private invites;
+    private envelopes;
+    private reposByTeam;
+    private presenceByTeam;
+    private feedByTeam;
+    private dedupe;
+    private feedSeq;
+    private leasesByTeam;
+    private memoriesByTeam;
+    private runnersByDevice;
+    private jobsByTeam;
+    private webhookSecrets;
+    private listeners;
+    constructor(now?: () => number);
+    /**
+     * Dev/self-host sign-in: a claimed GitHub login gets a session token.
+     * The hosted hub (Supabase) replaces this with real GitHub OAuth; the local
+     * hub server gates it behind its own admin secret.
+     */
+    signIn(github: string, name?: string): {
+        token: string;
+        user: HubUser;
+    };
+    /** A client bound to one session — the only way to act on the hub. */
+    client(token: string): HubClient;
+    user(id: string): HubUser;
+    role(teamId: string, userId: string): TeamRole | null;
+    requireRole(teamId: string, userId: string, atLeast: TeamRole): TeamRole;
+    team(teamId: string): Team;
+    createTeam(userId: string, name: string): Team;
+    teamsOf(userId: string): Array<Team & {
+        role: TeamRole;
+    }>;
+    registerDevice(userId: string, input: {
+        label: string;
+        sealPub: string;
+        signPub: string;
+    }): HubDevice;
+    device(deviceId: string, userId: string): HubDevice;
+    createInvite(userId: string, teamId: string, ttlMs?: number | null): {
+        invite: string;
+        expiresAt: number;
+    };
+    redeemInvite(userId: string, invite: string): {
+        team: Team;
+        role: TeamRole;
+    };
+    members(userId: string, teamId: string): MemberView[];
+    removeMember(userId: string, teamId: string, target: string): void;
+    private withStale;
+    /**
+     * Everyone's live (non-stale) leases in a repo, except this user's own run.
+     * Matching on the run alone let anyone dodge a rival's lease by reusing its
+     * run id.
+     */
+    private rivals;
+    private judge;
+    claimLease(userId: string, teamId: string, c: LeaseClaim): ClaimResult;
+    private ownLease;
+    extendLease(userId: string, teamId: string, leaseId: string, scope: LeaseScope, hardZones: string[]): ClaimResult;
+    renewLeases(userId: string, teamId: string, deviceId: string): number;
+    setRunLeaseState(userId: string, teamId: string, runId: string, state: "active" | "landing"): number;
+    releaseLeases(userId: string, teamId: string, runId: string, reason: string): number;
+    private mem;
+    publishMemory(userId: string, teamId: string, m: TeamMemoryIn): {
+        memory: TeamMemory;
+        merged: boolean;
+    };
+    private ownMemory;
+    updateTeamMemory(userId: string, teamId: string, id: string, patch: {
+        hmac: string;
+        sealed: Sealed;
+    }): TeamMemory;
+    forgetTeamMemory(userId: string, teamId: string, id: string, reason: string): void;
+    resolveMemories(userId: string, teamId: string, winnerId: string, loserId: string, reason: string): TeamMemory;
+    teamMemories(userId: string, teamId: string, repo: string, opts?: {
+        history?: boolean;
+    }): TeamMemory[];
+    registerRunner(userId: string, input: {
+        deviceId: string;
+        kinds: string[];
+        shared: boolean;
+        capacity?: number;
+    }): Runner;
+    runners(userId: string, teamId: string): Runner[];
+    revokeDevice(userId: string, deviceId: string): void;
+    private jobMap;
+    /** May this runner take this job? Its owner's jobs, or anyone's when shared (D68). */
+    private eligible;
+    createJob(userId: string, teamId: string, j: JobIn): Job;
+    claimJob(userId: string, teamId: string, runnerDeviceId: string, instantOnly?: boolean): Job | null;
+    private heldJob;
+    heartbeatJob(userId: string, teamId: string, jobId: string, runnerDeviceId: string, progress?: Sealed): Job;
+    finishJob(userId: string, teamId: string, jobId: string, runnerDeviceId: string, outcome: {
+        state: "done" | "failed";
+        result?: Sealed;
+        error?: string;
+    }): Job;
+    cancelJob(userId: string, teamId: string, jobId: string): Job;
+    jobs(userId: string, teamId: string, opts?: {
+        active?: boolean;
+    }): Job[];
+    webhookSecret(userId: string, teamId: string, rotate?: boolean): {
+        secret: string;
+    };
+    /** The receiver's side (no session): the secret to verify a delivery against; null for no such team, or none set. */
+    webhookSecretOf(teamId: string): string | null;
+    /**
+     * A verified delivery: its events, for repos this team shares only, appended
+     * as system events (no member). Returns how many were new — the rest were
+     * already in the feed (polled first, or a redelivery).
+     */
+    receiveGithubWebhook(teamId: string, event: string, payload: unknown): number;
+    leases(userId: string, teamId: string, repo?: string): Lease[];
+    putKeyEnvelopes(userId: string, teamId: string, version: number, envs: Array<{
+        deviceId: string;
+        box: string;
+    }>): void;
+    keyEnvelopes(userId: string, teamId: string, deviceId: string): Array<{
+        version: number;
+        box: string;
+    }>;
+    shareRepo(userId: string, teamId: string, repo: string): void;
+    repos(userId: string, teamId: string): string[];
+    private presenceKey;
+    heartbeat(userId: string, teamId: string, p: PresenceIn): void;
+    clearPresence(userId: string, teamId: string, key: {
+        deviceId: string;
+        agent: string;
+        repo: string;
+    }): void;
+    presence(userId: string, teamId: string): Presence[];
+    appendFeed(userId: string, teamId: string, e: FeedIn): FeedEvent | null;
+    appendFeedRaw(teamId: string, userId: string | null, e: FeedIn): FeedEvent | null;
+    feed(userId: string, teamId: string, opts?: {
+        since?: number;
+        limit?: number;
+    }): FeedEvent[];
+    subscribe(userId: string, teamId: string, cb: (e: HubEvent) => void): () => void;
+    private emit;
+}