@lensmcp/protocol-types 1.25.39 → 1.25.41

package/lib/team-design.d.ts

@@ -90,7 +90,12 @@ export interface TeamDesignHandOff {
         description: string;
     };
 }
-/** Keep the flow the repository has, or replace it. */
+/**
+ * Keep the flow the repository has, or tune LensMCP's (planning/team/08 TH-D2): a design keeps every default step —
+ * build → test → review, a fix → review, changes back to whoever did the work, one QA run per goal, docs after QA — and
+ * `handOffs` are only what it ADDS to them (a path-triggered specialist review, an announcement when a goal is done).
+ * Accepted, they are written as `flow.json` `{ "extends": "default", "handOffs": [...] }`, so later defaults reach it.
+ */
 export type TeamDesignFlow = {
     keep: true;
     why?: string;
@@ -194,6 +199,44 @@ export interface DashTeamDesignAccept {
     /** Overwrite files the repository already has (they are listed to the person first). */
     force: boolean;
 }
+/**
+ * Roles left taking the same work once a design is accepted as chosen (planning/team/08 S4): a default role the accept
+ * keeps as it is — `builder`, `bug-fixer` — takes kinds the design's own roles take, on paths they own (a role that owns
+ * nothing takes them anywhere). A task of those kinds with no role goes to whichever owns most of its paths, else the
+ * first: the default competes with the roles meant to replace it. `canOff`: the page may offer to switch it off — never
+ * for a role whose flow step LensMCP keeps (tester, reviewer, qa, docs).
+ */
+export interface DashTeamDesignOverlap {
+    /** The default role kept as it is. */
+    role: string;
+    /** The kinds it takes that the others take too. */
+    kinds: DashTeamKind[];
+    /** The roles of the design (or the repository) taking them on overlapping paths. */
+    with: string[];
+    canOff: boolean;
+    /** Its tasks still open, claimed or in recovery on the board — to re-route before it is switched off (at most 20). */
+    open: Array<{
+        id: string;
+        title: string;
+        kind?: DashTeamKind;
+        state: string;
+    }>;
+    /** Its open tasks past the ones listed. */
+    moreOpen?: number;
+    /** In words, for the person. */
+    text: string;
+}
+/** `POST /api/team/design/preview`: the files accepting would write, what it would not and why, and the roles it would leave overlapping. */
+export interface DashTeamDesignPreview {
+    files: Array<{
+        path: string;
+        exists: boolean;
+        action: 'write' | 'overwrite' | 'keep';
+        same?: true;
+    }>;
+    problems: string[];
+    overlaps?: DashTeamDesignOverlap[];
+}
 /** What accepting wrote, and what it kept because a file was already there and `force` was not given. */
 export interface DashTeamDesignAccepted {
     written: string[];
@@ -225,4 +268,36 @@ export interface DashTeamDesignState {
     /** Newest first, at most 20, without their designs. */
     runs: DashTeamDesignRun[];
     fits?: DashTeamDesignFit;
+    /**
+     * The team the repository runs now: its own (`.lensmcp/team/` — team-init, the Roles tab, an accepted design, by hand)
+     * or only LensMCP's defaults; how many roles, and how many of them name their own model, effort, paths, rules or cap.
+     * A repository with its own team is offered a design, never asked for one.
+     */
+    team?: {
+        own: boolean;
+        roles: number;
+        tuned: number;
+    };
+    /**
+     * What a design started now may spend and research (planning/team/08 TH-D1): Settings › Features «Team design
+     * ceiling» ($50 unless set), and the tool calls that buys — its own, apart from the click and agent allowances.
+     */
+    ceiling?: {
+        usd: number;
+        toolCalls: number;
+        source: 'workspace' | 'default';
+        /**
+         * The day's design allowance (Settings › Features «Team designs per day», $100 unless set; UTC): what today's
+         * designs spent, what is left — a design started now runs on the smaller of its ceiling and what is left, with the
+         * tool calls that buys (`runUsd`, `runToolCalls`).
+         */
+        day?: {
+            usd: number;
+            spent: number;
+            left: number;
+            source: 'workspace' | 'default';
+        };
+        runUsd?: number;
+        runToolCalls?: number;
+    };
 }

package/lib/team.d.ts

@@ -77,6 +77,21 @@ export interface DashTeamTask {
     };
     /** What its holder's tool calls did in its newest claim, as the hooks saw them (the drawer). */
     work?: DashTeamTaskWork;
+    /** The paths its holder reserved to edit (agent_task_reserve) — held while it is claimed. */
+    reserved?: string[];
+    /** A goal's word for the roles that work under it (agent_goal_team, the drawer). */
+    team?: DashTeamGoalRole[];
+    /** The open blocking question (`q-…`) it waits for (agent_ask): no one claims it until it is answered. */
+    waitingOn?: string;
+}
+/** A goal's word for one role: its rules for this goal (after the role's own), what its agents launch with, the paths it reviews too. */
+export interface DashTeamGoalRole {
+    role: string;
+    rules: string;
+    model?: string;
+    effort?: string;
+    client?: 'codex' | 'claude';
+    reviews?: string[];
 }
 /** One claim's work, from its holder's hooks: the files edited, commits, the checks and the whole suites run, workspace actions. */
 export interface DashTeamTaskWork {
@@ -96,7 +111,7 @@ export interface DashTeamTaskWork {
  * change completed with no commit or no check, a QA pass naming no run, a claim with no line in ten minutes, a holder
  * whose process ended. Hints, never verdicts.
  */
-export type DashTeamConductKind = 'checker-edited' | 'whole-suite' | 'outside-paths' | 'no-commit' | 'unchecked' | 'qa-unrun' | 'quiet-claim' | 'host-gone';
+export type DashTeamConductKind = 'checker-edited' | 'whole-suite' | 'outside-paths' | 'no-commit' | 'unchecked' | 'qa-unrun' | 'quiet-claim' | 'host-gone' | 'edited-reserved';
 export interface DashTeamFlag {
     kind: DashTeamConductKind;
     severity: 'info' | 'warn';
@@ -246,6 +261,18 @@ export interface DashTeamBoard {
     flags?: DashTeamFlag[];
     /** More sessions or tasks than the board carries. */
     truncated: boolean;
+    /**
+     * Set on a worktree's board: its tasks (and their flags, and the roles' task counts) are that worktree's only — the
+     * ones it is to do, claimed or completed there, or made there. Absent on the main checkout's board, which holds every
+     * worktree's tasks. The agents, worktrees and notes are the whole team's either way.
+     */
+    scope?: DashTeamBoardScope;
+}
+export interface DashTeamBoardScope {
+    worktreeId: string;
+    /** The worktree's branch and folder, when it has reported them. */
+    branch?: string;
+    root?: string;
 }
 export type DashTeamBoardAnswer = DashTeamBoard | {
     same: true;
@@ -259,6 +286,8 @@ export interface DashTeamTaskWhole {
     /** More tasks under it than the answer carries. */
     treeTruncated?: boolean;
     blockers: DashTeamTaskRef[];
+    /** Its agents' questions, oldest first (planning/team/09) — absent when it has none. */
+    questions?: DashTeamQuestion[];
 }
 /** `POST /api/team/task` — a task from the person at the machine. `requestId`: one per submit; a retry sends it again. */
 export interface DashTeamNewTask {
@@ -630,3 +659,308 @@ export interface DashTeamLaunchesAnswer {
     running: number;
     launches: DashTeamLaunch[];
 }
+/** `progress.json` beside an archive while it is written, and after: what the writer is doing, or how it ended. */
+export interface DashTeamArchiveProgress {
+    state: 'writing' | 'done' | 'failed';
+    startedAt: number;
+    /** What it is on now (`events`, `AI calls`…), or the last step it reached. */
+    step: string;
+    finishedAt?: number;
+    /** Why it failed. */
+    error?: string;
+    /** The writer's process: a `writing` archive whose process is gone failed. */
+    pid: number;
+    goalId?: string;
+}
+/**
+ * `summary.json` — inside the zip and beside it: a small, stable record to compare goals without unzipping them.
+ * Versioned: a field changes meaning only with a new `schema`.
+ */
+export interface DashTeamArchiveSummary {
+    schema: 1;
+    /** The workspace's key: the archive's folder is under it. */
+    workspace: string;
+    goal: {
+        id: string;
+        title: string;
+        kind?: string;
+        state: string;
+        outcome?: string;
+        createdAt: number;
+        completedAt?: number;
+    };
+    /** The events' window: from 5 minutes before the goal was created to a minute after it completed (or was archived). */
+    window: {
+        from: number;
+        to: number;
+    };
+    /** The checkout the goal worked in: its worktree's instance name, else `main`. */
+    checkout: {
+        name: string;
+        branch?: string;
+        root?: string;
+        worktree: boolean;
+    };
+    tasks: {
+        total: number;
+        byKind: Record<string, number>;
+        byOutcome: Record<string, number>;
+        byState: Record<string, number>;
+    };
+    /** Agents with a session, and spawned agents that never joined. */
+    agents: {
+        joined: number;
+        unjoined: number;
+    };
+    durations: {
+        elapsedMs: number;
+        goalOpenMs: number;
+        heldMs: number;
+        idleMs: number;
+        waitMedianMs?: number;
+        waitMaxMs?: number;
+    };
+    performance: {
+        verdict: 'pass' | 'fail' | 'unmeasured';
+        events: number;
+        breaches: number;
+        breachesByKind: Record<string, number>;
+        waived: number;
+        routes: number;
+        statements: number;
+        pages: number;
+        limits: Record<string, number>;
+    };
+    /** Each QA run's measured verdict (the QA gate's `performance`), and its outcome. */
+    qaRuns: Array<{
+        taskId: string;
+        title: string;
+        state: string;
+        outcome?: string;
+        verdict?: 'pass' | 'fail' | 'unmeasured';
+        breaches?: number;
+        checkout?: string;
+    }>;
+    events: {
+        /** Where they were read: the event history, the worktree's bus files (no row in the history), or nowhere. */
+        source: 'history' | 'bus-files' | 'none';
+        written: number;
+        bytes: number;
+        parts: number;
+        /** Read in the window, whether written or not (past the cut they still feed the performance and flows). */
+        read: number;
+        cut: boolean;
+        note?: string;
+    };
+    flows: {
+        count: number;
+        cut: boolean;
+    };
+    aiCalls: {
+        count: number;
+        bytes: number;
+        cut: boolean;
+    };
+    testRuns: {
+        count: number;
+        passed: number;
+        failed: number;
+        other: number;
+        byAction: Record<string, number>;
+    };
+    lensmcp: string;
+    writtenAt: number;
+}
+/** `GET|POST /api/team/archive?id=` and `team_archive` — a task's archive: where it is, how far, what it holds. */
+export interface DashTeamArchive {
+    taskId: string;
+    /** `~/.lensmcp/team-archive/<workspace>/<goal-slug>-<id8>/` */
+    folder: string;
+    /** The zip in it, once written. */
+    zip: string;
+    /** `none`: never written here. */
+    state: 'none' | 'writing' | 'done' | 'failed';
+    /** A POST (or `team_archive` without `check`) started this one. */
+    started?: boolean;
+    progress?: DashTeamArchiveProgress;
+    /** Once done. */
+    summary?: DashTeamArchiveSummary;
+    /** The zip's size, once done. */
+    bytes?: number;
+    next?: string;
+}
+/** A team health check's verdict: within its expected range, worth a look, against how the team must work, or not measurable here. */
+export type DashTeamHealthStatus = 'ok' | 'warn' | 'bad' | 'n/a';
+/** One task or agent a check names — what to open. */
+export interface DashTeamHealthExample {
+    text: string;
+    taskId?: string;
+    sessionId?: string;
+}
+/**
+ * One measure of how the team works against how it must (planning/team/08-team-health-and-grounded-design.md), with
+ * the range it is held to — a hint to look, never a verdict on an agent.
+ */
+export interface DashTeamHealthCheck {
+    /** `flow.rework`, `roles.switches`, `proof.fast-reviews`… */
+    id: string;
+    group: 'flow' | 'roles' | 'proof' | 'agents';
+    title: string;
+    status: DashTeamHealthStatus;
+    /** The measure: a count, or the part of `of`. */
+    value: number;
+    of?: number;
+    /** What it should be, in words: «none», «at most 3 per change», «under 10 % of reviews». */
+    expected: string;
+    /** What was measured and what it means, in one or two sentences. */
+    detail: string;
+    /** At most five, worst first. */
+    examples: DashTeamHealthExample[];
+}
+/** How one role worked in the window — what the design reads as «how we work». */
+export interface DashTeamHealthRole {
+    role: string;
+    /** The sessions that held the role in the window, by client (claude, codex, mcp…). */
+    agents: Record<string, number>;
+    /** Its agents within their lease now. */
+    live: number;
+    claimed: number;
+    completed: number;
+    /** The median minutes from claim to completion of its tasks. */
+    medianMinutes?: number;
+    /** Work sent back to its owner: a failed test, a changes-requested review. */
+    reworked: number;
+    /** Its tasks open, claimed or in recovery now. */
+    open: number;
+}
+/** One kind of task in the window. */
+export interface DashTeamHealthKind {
+    kind: string;
+    created: number;
+    /** Of `created`, the ones LensMCP made from the flow. */
+    handOffs: number;
+    completed: number;
+    cancelled: number;
+    open: number;
+    outcomes: Record<string, number>;
+}
+/**
+ * `GET /api/team/health`, `team_health`, `lensmcp agent health` — how the team works, measured from its store: the
+ * window's tasks (a worktree's own, as its board's; the main checkout's all), its agents, their joins and messages.
+ */
+export interface DashTeamHealth {
+    window: {
+        from: number;
+        to: number;
+    };
+    scope?: DashTeamBoardScope;
+    /** The worst check's. */
+    status: DashTeamHealthStatus;
+    totals: {
+        tasks: number;
+        handOffs: number;
+        /** Builds and bug fixes completed. */
+        changes: number;
+        goals: number;
+        sessions: number;
+        /** Sessions that claimed, logged, created or wrote anything. */
+        actingSessions: number;
+        messages: number;
+    };
+    checks: DashTeamHealthCheck[];
+    roles: DashTeamHealthRole[];
+    kinds: DashTeamHealthKind[];
+    /** The flow's steps the checks were held to: `build→test`, `test→review`, `review→qa`… */
+    flow: string[];
+    /** More tasks in the window than one report reads. */
+    truncated?: {
+        tasks?: number;
+        joins?: number;
+        messages?: number;
+    };
+    observedAt: number;
+}
+/**
+ * Where an agent's question is (planning/team/09): with its manager, with the person (escalated, or no manager to take
+ * it), answered, or withdrawn (by its asker, or with its task).
+ */
+export type DashTeamQuestionState = 'manager' | 'person' | 'answered' | 'withdrawn';
+export interface DashTeamQuestionOption {
+    label: string;
+    detail?: string;
+}
+/** Who answered: the manager it went to, the person (Team › Inbox, the CLI), or the person's delegate — their inbox session. */
+export interface DashTeamQuestionAnswer {
+    text: string;
+    /** The option picked, 1-based. */
+    option?: number;
+    /** A session id, or `user` for the person and their delegate. */
+    by: string;
+    byName?: string;
+    as: 'manager' | 'person' | 'delegate';
+    at: number;
+}
+/**
+ * One agent's question (agent_ask, the store's `CoordinationQuestion`): its asker, the task and goal it is about, the
+ * choices it gives with its own pick, what it found — and where it is now.
+ */
+export interface DashTeamQuestion {
+    /** `q-` and 12 hex characters — unique across the machine's repositories. */
+    id: string;
+    /** The asker's session id. */
+    asker: string;
+    askerName?: string;
+    askerRole?: string;
+    /** The checkout it was asked in. */
+    worktreeId: string;
+    taskId?: string;
+    taskTitle?: string;
+    goalId?: string;
+    question: string;
+    /** 2–4 choices, or none. */
+    options?: DashTeamQuestionOption[];
+    /** The asker's pick: the number (1…) of one of `options`. */
+    recommended?: number;
+    /** What the asker found and tried. */
+    context?: string;
+    links?: DashTeamLink[];
+    /** Its task waits for the answer. */
+    blocking: boolean;
+    state: DashTeamQuestionState;
+    /** The manager it is with, while `manager`. */
+    to?: string;
+    toName?: string;
+    /** Why it went to the person — `by` its manager, or `lensmcp` (no manager to take it, its manager gone or silent). */
+    escalation?: {
+        at: number;
+        by: string;
+        why: string;
+    };
+    answer?: DashTeamQuestionAnswer;
+    withdrawn?: {
+        at: number;
+        why: string;
+    };
+    createdAt: number;
+    updatedAt: number;
+}
+/** `GET /api/team/questions[?state=open|answered|all&all=1&limit=]` — newest first, scoped as the checkout's board. */
+export interface DashTeamQuestionsAnswer {
+    questions: DashTeamQuestion[];
+    /** The open questions in scope, whatever `state` asked: with the person, with a manager. */
+    counts: {
+        person: number;
+        manager: number;
+    };
+    /** Set on a worktree's page, unless `all=1`: its own questions only. */
+    scope?: DashTeamBoardScope;
+    observedAt: number;
+}
+/** `POST /api/team/questions/<id>/answer` — the person answers: an option, their own words, or both. Answered: `{ question }`. */
+export interface DashTeamAnswerQuestion {
+    answer?: string;
+    /** 1-based, of the question's options. */
+    option?: number;
+    /** One per submit; a retry sends it again. */
+    requestId?: string;
+}

package/lib/workspace-actions.d.ts

@@ -65,10 +65,17 @@ export interface WorkspaceActionStep {
         omittedData?: number;
         branch?: string;
     };
+    /** `env`: a restart of a worktree instance's service — which instance variables its new tree was given, read again
+     *  from the instance's files: a print of them all, the print before, and the names that changed. Never a value. */
     service?: {
         name: string;
         state: string;
         ready: boolean;
+        env?: {
+            fingerprint: string;
+            fromFingerprint: string;
+            changed: string[];
+        };
     };
     evidence: {
         log: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/protocol-types",
-  "version": "1.25.39",
+  "version": "1.25.41",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",