@lensmcp/protocol-types 1.25.33 → 1.25.35

package/lib/team-library.d.ts

@@ -0,0 +1,283 @@
+import type { DashTeamKind, DashTeamOutcome } from './team.js';
+/**
+ * The role library and the team as the person shapes it on the Team page (planning/team/02-role-library.md, RL1): the
+ * base roles LensMCP ships and its team templates, the repository's members built on them (`.lensmcp/team/roles/`),
+ * and the person's writes — a member added, edited or removed, a template previewed and applied. Served by
+ * servers/lensmcp-mcp/src/dashboard/team-library.ts; the data comes from `@lensmcp/storage` (library.ts,
+ * team-files.ts, templates.ts).
+ */
+export type DashTeamRoleFamily = 'lead' | 'build' | 'check' | 'support' | 'market';
+export type DashTeamWorktreePolicy = 'own' | 'shared' | 'any';
+/** A LensMCP tool a role works with, and when to reach for it. */
+export interface DashTeamRoleTool {
+    name: string;
+    when: string;
+}
+/** One tagged section of a role's craft: `<instructions id="…" note="…">`. */
+export interface DashTeamRoleSection {
+    tag: string;
+    id: string;
+    note?: string;
+}
+/** A library role in brief — a card. Its tools by name; `GET /api/team/library/role` has each one's when. */
+export interface DashTeamLibraryRole {
+    id: string;
+    title: string;
+    family: DashTeamRoleFamily;
+    /** Moves when what the role tells an agent changes. */
+    version: number;
+    /** Other names that resolve to it — the default it stands behind. */
+    aliases: string[];
+    summary: string;
+    takes: DashTeamKind[];
+    creates: DashTeamKind[] | 'any';
+    wip: number;
+    worktree: DashTeamWorktreePolicy;
+    /** Stack words it fits. */
+    fits: string[];
+    skills: string[];
+    tools: string[];
+    /** The id a member built on it gets in a repository: the default's it stands behind (`reviewer`), else its own. */
+    member: string;
+    /** The default role it stands behind, when it does. */
+    default?: string;
+    sections: DashTeamRoleSection[];
+    /** How long its craft is, in characters. */
+    chars: number;
+    /** `team://library/<id>` — where an agent reads it whole. */
+    uri: string;
+}
+/** `GET /api/team/library/role?id=` — one library role whole (by its id or an alias). */
+export interface DashTeamLibraryRoleWhole extends Omit<DashTeamLibraryRole, 'tools'> {
+    tools: DashTeamRoleTool[];
+    sha: string;
+    /** Its craft, as tagged sections — read-only beside a member's own rules. */
+    instructions: string;
+}
+/** A member a template staffs. */
+export interface DashTeamTemplateMember {
+    /** The library role it builds on. */
+    role: string;
+    /** Its id in the repository: `.lensmcp/team/roles/<member>.md`. */
+    member: string;
+    title: string;
+    agents: number;
+    start?: 'now' | 'later';
+}
+/**
+ * A hand-off of a template's own flow (TeamDesignHandOff without the text it may leave out: its title and description
+ * are its own, else the default flow's for the same step). `role` names a library role.
+ */
+export interface DashTeamTemplateHandOff {
+    on: {
+        kind: DashTeamKind;
+        outcome: DashTeamOutcome;
+        after?: 'build' | 'bug';
+        paths?: string[];
+    };
+    create: {
+        kind: DashTeamKind;
+        role?: string;
+        to?: 'owner';
+        join?: boolean;
+        title?: string;
+        description?: string;
+    };
+}
+export interface DashTeamTemplate {
+    id: string;
+    title: string;
+    summary: string;
+    fits: string[];
+    roles: DashTeamTemplateMember[];
+    flow: 'default' | DashTeamTemplateHandOff[];
+    /** When it fits, and how to adjust it. */
+    about: string;
+}
+/** `GET /api/team/library` — the base roles by family, in brief, and the team templates. */
+export interface DashTeamLibrary {
+    /** Moves when any role or template does. */
+    sha: string;
+    families: Array<{
+        family: DashTeamRoleFamily;
+        title: string;
+        roles: DashTeamLibraryRole[];
+    }>;
+    templates: DashTeamTemplate[];
+}
+/** Where a member's field came from: its file, its library base, the default role's text — tools and skills from both. */
+export type DashTeamFieldSource = 'file' | 'base' | 'default' | 'base+file';
+/** One member of the repository's team, as its files make it. */
+export interface DashTeamMember {
+    id: string;
+    title: string;
+    summary: string;
+    takes: DashTeamKind[];
+    creates: DashTeamKind[] | 'any';
+    wip: number;
+    worktree: DashTeamWorktreePolicy;
+    /** The library role it builds on — or, while the library has no entry behind a default, that default's id. */
+    base?: string;
+    /** The base's title and version, when it is a library role. */
+    baseTitle?: string;
+    baseVersion?: number;
+    /** The paths it changes and others do not. */
+    owns: string[];
+    /** The LensMCP tools it works with — from its base, or added by its file. */
+    tools: Array<DashTeamRoleTool & {
+        from: 'base' | 'file';
+    }>;
+    skills: Array<{
+        name: string;
+        from: 'base' | 'file';
+    }>;
+    /** Wants `wants` agents (none said: no number), has `has` active ones now — `listening` of them waiting for work. */
+    staffing: {
+        wants?: number;
+        start?: 'now' | 'later';
+        has: number;
+        listening: number;
+    };
+    /** The repository's own rules for it, as tagged sections — empty when it has none. */
+    rules: string;
+    /** `default`: no file — LensMCP's default (built on its library role); `file`: the repository's file; `design`: a file an accepted team design wrote. */
+    source: 'default' | 'file' | 'design';
+    /** Its file, when it has one: `.lensmcp/team/roles/<id>.md`. */
+    file?: string;
+    /** One of the seven defaults (removing it switches it off; deleting its file brings the default back). */
+    isDefault: boolean;
+    fields: Record<string, DashTeamFieldSource>;
+    /** Why its file was not read (the default stood in) — empty when it was. */
+    problems: string[];
+}
+/** `GET /api/team/roles` — the team as the checkout's files make it. */
+export interface DashTeamMembers {
+    members: DashTeamMember[];
+    /** Defaults switched off (`off: true`), each with its file. */
+    off: Array<{
+        id: string;
+        file: string;
+    }>;
+    flow: {
+        from: string;
+    };
+    /** Every file that was skipped, and why. */
+    problems: Array<{
+        file: string;
+        problem: string;
+    }>;
+    files: {
+        roles: string;
+        flow: string;
+        project: string;
+    };
+}
+/** One file a write would make: `write` (new — or already exactly so: `same`), `overwrite` (forced), `keep` (left as it is). */
+export interface DashTeamFilePlan {
+    path: string;
+    exists: boolean;
+    action: 'write' | 'overwrite' | 'keep';
+    same?: true;
+}
+/**
+ * `POST /api/team/roles` — a member created or changed: its file written as an overlay on its base (only what differs
+ * from it). Fields left out come from the base; `force` writes over a file that is there.
+ */
+export interface DashTeamMemberEdit {
+    /** One per submit. */
+    requestId: string;
+    /** Its id — when absent, the id a member built on `base` gets (`reviewer` for code-reviewer). */
+    id?: string;
+    /** A library role (id or alias); none for a role of the repository's own (it then needs title, summary and rules). */
+    base?: string;
+    title?: string;
+    summary?: string;
+    owns?: string[];
+    takes?: DashTeamKind[];
+    creates?: DashTeamKind[] | 'any';
+    wip?: number;
+    worktree?: DashTeamWorktreePolicy;
+    agents?: number;
+    start?: 'now' | 'later';
+    /** Tools added to the base's (one the base has, named again, takes this when). */
+    tools?: DashTeamRoleTool[];
+    /** Skills added to the base's. */
+    skills?: string[];
+    /** The repository's own rules for it — tagged sections, or plain lines (wrapped in `<rules id="role.<id>">`). */
+    rules?: string;
+    force?: boolean;
+}
+/** `POST /api/team/roles`'s answer: what happened to the file, and the member as it is now. */
+export interface DashTeamMemberWritten {
+    file: DashTeamFilePlan;
+    written: boolean;
+    problems: string[];
+    member?: DashTeamMember;
+    /** Whether the agents on the team were told to agent_join again (a file that changed, a requestId). */
+    notified?: boolean;
+    /** On a refusal (409): why, in words — the dashboard's fetch reads only this from an error answer. */
+    error?: string;
+}
+/** `POST /api/team/roles/remove` — `{ requestId, id, why? }`: a default switched off, a role of the repository's own deleted. */
+export interface DashTeamMemberRemoved {
+    path: string;
+    action: 'off' | 'deleted';
+    /** Whether the agents on the team were told to agent_join again. */
+    notified?: boolean;
+    /** Why they were not, when they were not. */
+    problems?: string[];
+}
+/** `POST /api/team/roles/on` — `{ requestId, id }`: a switched-off default back on the team. */
+export interface DashTeamMemberOn {
+    path: string;
+    /** Its file deleted (it only switched the role off), or its `off: true` line taken out (the file holds more). */
+    action: 'deleted' | 'changed';
+    /** Whether the agents on the team were told to agent_join again. */
+    notified?: boolean;
+    /** Why they were not, when they were not. */
+    problems?: string[];
+}
+/** `GET /api/team/paths?under=` — the tracked folders (with their file counts) and files directly under a path. */
+export interface DashTeamPaths {
+    under: string;
+    dirs: Array<{
+        path: string;
+        files: number;
+    }>;
+    files: string[];
+    /** More files than the answer carries, or the tracked-file list was cut. */
+    cut?: string;
+    /** Why nothing could be listed (not a Git checkout, git failed). */
+    why?: string;
+}
+/** `POST /api/team/templates/preview` — `{ requestId?, template, force? }`. */
+export interface DashTeamTemplatePreview {
+    template: {
+        id: string;
+        title: string;
+        summary: string;
+    };
+    members: DashTeamTemplateMember[];
+    /** The defaults it switches off. */
+    off: string[];
+    /** What it leaves as it is, and why. */
+    notes: string[];
+    files: DashTeamFilePlan[];
+    problems: string[];
+}
+/** `POST /api/team/templates/apply` — `{ requestId, template, force? }`. */
+export interface DashTeamTemplateApplied {
+    template: {
+        id: string;
+        title: string;
+        summary: string;
+    };
+    members: DashTeamTemplateMember[];
+    off: string[];
+    notes: string[];
+    written: string[];
+    kept: string[];
+    problems: string[];
+    /** The team was told (one broadcast note) — something changed. */
+    notified: boolean;
+}

package/lib/team-library.js

@@ -0,0 +1 @@
+"use strict";export{};

package/lib/team.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The Team page (servers/lensmcp-mcp/src/dashboard/team.ts): the repository's agent team as its coordination store
+ * holds it — the agents in their roles, the tasks they take and hand on, each task's work log — and what the person at
+ * the machine changes there. The shapes are the store's (libs/storage coordination), cut to what the page shows: a
+ * task's whole log comes with the task alone (`/api/team/task`), the board carries its newest lines.
+ */
+/**
+ * What kind of work a task is: it names the role that takes it. `goal`: what a manager breaks into the others' tasks;
+ * `marketing`: telling people about the product (launch posts, release notes, landing and store copy).
+ */
+export declare const DASH_TEAM_KINDS: readonly ["goal", "build", "bug", "review", "test", "docs", "marketing", "research", "chore"];
+export type DashTeamKind = (typeof DASH_TEAM_KINDS)[number];
+export type DashTeamTaskState = 'open' | 'claimed' | 'recovery' | 'completed' | 'cancelled';
+export type DashTeamOutcome = 'done' | 'approved' | 'changes-requested' | 'passed' | 'failed' | 'wontfix';
+/** What a task points at in the lens or the repository. */
+export declare const DASH_TEAM_LINK_KINDS: readonly ["task", "flow", "error", "suggestion", "ai-call", "review", "page", "route", "commit", "branch", "worktree", "file"];
+export interface DashTeamLink {
+    kind: (typeof DASH_TEAM_LINK_KINDS)[number];
+    id: string;
+    label?: string;
+}
+/** One line of a task's work log. `by`: a session id, `user` (the person at the machine) or `lensmcp` (the team flow, the store). */
+export interface DashTeamLogLine {
+    at: number;
+    by: string;
+    kind: 'progress' | 'decision' | 'blocker' | 'handoff' | 'note' | 'state';
+    text: string;
+}
+export interface DashTeamTask {
+    id: string;
+    title: string;
+    /** Whole on `/api/team/task`; its first lines on the board. */
+    description: string;
+    kind?: DashTeamKind;
+    /** The role that may claim it; none: any agent. */
+    role?: string;
+    /** 0 (drop everything) … 3 (when there is time). */
+    priority: number;
+    parentId?: string;
+    blockedBy?: string[];
+    /** Of `blockedBy`, the tasks not completed or cancelled yet — an open task with any is blocked. */
+    blockedOn?: string[];
+    links?: DashTeamLink[];
+    /** The whole log on `/api/team/task`; its newest lines on the board. */
+    log: DashTeamLogLine[];
+    /** Every line it ever had, those no longer kept counted. */
+    logCount: number;
+    state: DashTeamTaskState;
+    outcome?: DashTeamOutcome;
+    /** The session holding it. */
+    owner?: string;
+    /** The session that must take it. */
+    to?: string;
+    /** A session id, `user` — the person's tasks (the Team page, an accepted team design) — or `lensmcp`: the team flow's hand-offs, the operator CLI's. */
+    creator: string;
+    origin: 'agent' | 'lensmcp';
+    worktreeId?: string;
+    ownerWorktreeId?: string;
+    createdAt: number;
+    updatedAt: number;
+    leaseUntil?: number;
+    checkpoint?: string;
+    /** What its owner said changed and how to check it, on completion (cut on the board). */
+    result?: string;
+    evidence?: string[];
+    completedHead?: string | null;
+    paths?: string[];
+    tags?: string[];
+}
+/** A task named in another's chain: its parent, its children, a blocker. */
+export interface DashTeamTaskRef {
+    id: string;
+    title: string;
+    kind?: DashTeamKind;
+    role?: string;
+    state: DashTeamTaskState;
+    outcome?: DashTeamOutcome;
+    owner?: string;
+}
+/** A task under another, and the tasks under it — the hand-off chain is a child of the task it came from. */
+export interface DashTeamTreeNode extends DashTeamTaskRef {
+    children: DashTeamTreeNode[];
+}
+/** One coordination session: an agent on the team (a role), or one outside it (no role). */
+export interface DashTeamSession {
+    id: string;
+    client: string;
+    name?: string;
+    role?: string;
+    /** Who it reports to: `user`, or a session id. */
+    manager?: string;
+    /** Waiting for work (agent_wait). */
+    listening?: boolean;
+    objective?: string;
+    step?: string;
+    /** `stale`: active, but not heard from within its lease. */
+    presence: 'active' | 'stale' | 'closed';
+    worktreeId: string;
+    createdAt: number;
+    lastSeenAt: number;
+    expiresAt: number;
+}
+/** A checkout of the repository, as an agent's lens last saw it. */
+export interface DashTeamWorktree {
+    id: string;
+    root: string;
+    branch: string | null;
+    head: string | null;
+    observedAt: number;
+    /** Files changed in it, then. */
+    changed: number;
+    truncated: boolean;
+    error?: string;
+}
+/** One role: its active agents (and how many wait for work), its tasks by state. */
+export interface DashTeamRole {
+    role: string;
+    title: string;
+    /** One line: what the role is for. */
+    summary: string;
+    /** The kinds of task it takes — a task of one goes to it unless the task names another role. */
+    takes: DashTeamKind[];
+    agents: number;
+    listening: number;
+    /** The most agents it takes at once (its role file's `agents`): agent_join refuses one more. None: no limit. */
+    cap?: number;
+    /** Claimable now (blocked ones not counted). */
+    open: number;
+    claimed: number;
+    blocked: number;
+    recovery: number;
+}
+/** A message to everyone, or a note — the board's newest. */
+export interface DashTeamNote {
+    id: string;
+    seq: number;
+    sender: string;
+    origin: 'agent' | 'lensmcp';
+    to?: string;
+    kind: 'message' | 'note';
+    body: string;
+    createdAt: number;
+}
+/** `GET /api/team/board` — `{ same: true, rev }` when `?rev=` is still current. */
+export interface DashTeamBoard {
+    repoId: string;
+    /** The checkout this dashboard serves. */
+    currentWorktreeId: string;
+    /** Changes when anything on the board does: a task, a session, an agent going quiet. */
+    rev: string;
+    /** The store's event sequence. */
+    revision: number;
+    observedAt: number;
+    sessions: DashTeamSession[];
+    worktrees: DashTeamWorktree[];
+    /** Live tasks first, then finished ones, newest first. */
+    tasks: DashTeamTask[];
+    notes: DashTeamNote[];
+    roles: DashTeamRole[];
+    /** More sessions or tasks than the board carries. */
+    truncated: boolean;
+}
+export type DashTeamBoardAnswer = DashTeamBoard | {
+    same: true;
+    rev: string;
+};
+/** `GET /api/team/task?id=` — the task whole, the chain above it (root first), the tasks under it, its blockers. */
+export interface DashTeamTaskWhole {
+    task: DashTeamTask;
+    ancestors: DashTeamTaskRef[];
+    tree: DashTeamTreeNode[];
+    /** More tasks under it than the answer carries. */
+    treeTruncated?: boolean;
+    blockers: DashTeamTaskRef[];
+}
+/** `POST /api/team/task` — a task from the person at the machine. `requestId`: one per submit; a retry sends it again. */
+export interface DashTeamNewTask {
+    requestId: string;
+    title: string;
+    description: string;
+    kind?: DashTeamKind;
+    role?: string;
+    priority?: number;
+    parentId?: string;
+    to?: string;
+    blockedBy?: string[];
+    links?: DashTeamLink[];
+}
+/** `POST /api/team/task/operate` — the person changes a task; each change is a line in its log, by `user`. */
+export interface DashTeamOperate {
+    requestId: string;
+    taskId: string;
+    priority?: number;
+    /** A session id, or null: anyone in its role. */
+    to?: string | null;
+    role?: string;
+    /** Take a held (or abandoned) task back, with why. */
+    release?: string;
+    /** Cancel it, with why. */
+    cancel?: string;
+    note?: string;
+}
+/** `POST /api/team/message` — to one agent, or to everyone (no `to`). */
+export interface DashTeamMessage {
+    requestId: string;
+    body: string;
+    kind: 'message' | 'note';
+    to?: string;
+}

package/lib/team.js

@@ -0,0 +1 @@
+"use strict";export const DASH_TEAM_KINDS=["goal","build","bug","review","test","docs","marketing","research","chore"],DASH_TEAM_LINK_KINDS=["task","flow","error","suggestion","ai-call","review","page","route","commit","branch","worktree","file"];

package/package.json

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