dsh-live-teams 0.1.0

package/lib/tree-snapshot.d.ts

@@ -0,0 +1,28 @@
+//#region src/tree-snapshot.d.ts
+/**
+ * A cheap fingerprint of a workspace tree, for the scope record in `files` mode (B32).
+ *
+ * Pure filesystem work — no git, no shelling out — so the task store can use it without
+ * taking on the git adapter, and so it can be tested against a plain temporary folder.
+ * Size and mtime, not content: the question is whether a file moved while an attempt ran,
+ * and hashing every file of a workspace on every claim is a cost nobody agreed to. Content
+ * digests live in the submission artifact, where they belong.
+ */
+/** Directories that are never a member's work: build output, caches, the team's own state. */
+export declare const SNAPSHOT_EXCLUDED: Set<string>;
+export declare const MAX_SNAPSHOT_FILES = 20000;
+export type TreeSnapshot = Readonly<Record<string, string>>;
+/**
+ * A cheap fingerprint of the whole tree: path → `size:mtime`.
+ *
+ * Size and mtime, not content: the question here is "did this file move while the attempt
+ * ran", and hashing every file of a workspace on every claim would be a cost nobody agreed
+ * to. Content digests live in the submission artifact, where they belong.
+ *
+ * `undefined` means the tree was too large to watch, which is reported as `unchecked` with a
+ * reason rather than as "nothing changed".
+ */
+export declare function snapshotTree(workspacePath: string): Promise<TreeSnapshot | undefined>;
+/** Paths added, changed or removed between two snapshots, sorted for a stable record. */
+export declare function diffSnapshots(before: TreeSnapshot, after: TreeSnapshot): string[];
+//#endregion

package/lib/tree-snapshot.js

@@ -0,0 +1,80 @@
+import * as path$1 from "node:path";
+import * as fsp from "node:fs/promises";
+//#region src/tree-snapshot.ts
+/**
+* A cheap fingerprint of a workspace tree, for the scope record in `files` mode (B32).
+*
+* Pure filesystem work — no git, no shelling out — so the task store can use it without
+* taking on the git adapter, and so it can be tested against a plain temporary folder.
+* Size and mtime, not content: the question is whether a file moved while an attempt ran,
+* and hashing every file of a workspace on every claim is a cost nobody agreed to. Content
+* digests live in the submission artifact, where they belong.
+*/
+/** Directories that are never a member's work: build output, caches, the team's own state. */
+const SNAPSHOT_EXCLUDED = /* @__PURE__ */ new Set([
+	".git",
+	".dsh-live-teams",
+	"node_modules",
+	"dist",
+	"build",
+	"target",
+	".venv",
+	"venv",
+	"__pycache__",
+	".next",
+	".cache",
+	"coverage",
+	".idea",
+	".DS_Store"
+]);
+const MAX_SNAPSHOT_FILES = 2e4;
+/**
+* A cheap fingerprint of the whole tree: path → `size:mtime`.
+*
+* Size and mtime, not content: the question here is "did this file move while the attempt
+* ran", and hashing every file of a workspace on every claim would be a cost nobody agreed
+* to. Content digests live in the submission artifact, where they belong.
+*
+* `undefined` means the tree was too large to watch, which is reported as `unchecked` with a
+* reason rather than as "nothing changed".
+*/
+async function snapshotTree(workspacePath) {
+	const snapshot = {};
+	let count = 0;
+	const walk = async (relative) => {
+		let entries;
+		try {
+			entries = await fsp.readdir(path$1.join(workspacePath, relative), { withFileTypes: true });
+		} catch {
+			return true;
+		}
+		for (const entry of entries) {
+			const next = relative.length === 0 ? entry.name : `${relative}/${entry.name}`;
+			if (entry.isDirectory()) {
+				if (SNAPSHOT_EXCLUDED.has(entry.name)) continue;
+				if (!await walk(next)) return false;
+				continue;
+			}
+			if (!entry.isFile() || SNAPSHOT_EXCLUDED.has(entry.name)) continue;
+			count += 1;
+			if (count > 2e4) return false;
+			try {
+				const stat = await fsp.stat(path$1.join(workspacePath, next));
+				snapshot[next] = `${stat.size}:${Math.round(stat.mtimeMs)}`;
+			} catch {
+				return true;
+			}
+		}
+		return true;
+	};
+	return await walk("") ? snapshot : void 0;
+}
+/** Paths added, changed or removed between two snapshots, sorted for a stable record. */
+function diffSnapshots(before, after) {
+	const changed = /* @__PURE__ */ new Set();
+	for (const [file, stamp] of Object.entries(before)) if (after[file] !== stamp) changed.add(file);
+	for (const file of Object.keys(after)) if (before[file] === void 0) changed.add(file);
+	return [...changed].sort();
+}
+//#endregion
+export { MAX_SNAPSHOT_FILES, SNAPSHOT_EXCLUDED, diffSnapshots, snapshotTree };

package/lib/types/client/TeamView.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import type { MessageKind, TaskStatus, TeamAttemptStatus, TeamSubmissionScope } from './api.js';
+import type { LocaleKey } from './locales.js';
+import './styles.js';
+export type TeamViewContext = {
+    readonly sessions: {
+        open(sessionId: string): void;
+    };
+    readonly t: (key: LocaleKey) => string;
+};
+export type TeamViewProps = {
+    readonly ctx?: TeamViewContext;
+    /** Session the view belongs to; the host serves this Session's workspace team. */
+    readonly sessionId?: string;
+    /** How often the tab re-reads tasks while visible. Exposed so the test can watch it. */
+    readonly pollMs?: number;
+};
+export type TaskFilter = 'active' | 'waiting' | 'archived';
+export declare const attemptStatusKeys: Record<TeamAttemptStatus, LocaleKey>;
+export declare const scopeKeys: Record<TeamSubmissionScope['state'], LocaleKey>;
+export declare const scopeReasonKeys: Record<NonNullable<TeamSubmissionScope['reason']>, LocaleKey>;
+export declare const taskStatusKeys: Record<TaskStatus, LocaleKey>;
+export declare const taskFilterKeys: Record<TaskFilter, LocaleKey>;
+export declare const messageKindKeys: Record<MessageKind, LocaleKey>;
+export declare function TeamView(props: TeamViewProps): React.ReactElement;
+export default TeamView;

package/lib/types/client/TeamView.dom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/client/api.d.ts

@@ -0,0 +1,522 @@
+export type TeamMember = {
+    memberId: string;
+    note?: string;
+    displayName: string;
+    role: string;
+    availability: string;
+    sessionId: string | null;
+    live: boolean;
+    status: 'idle' | 'running' | 'unknown';
+    bindingGeneration: number;
+    contractRevision: number;
+    permittedContacts?: string[];
+};
+export type TeamSnapshot = {
+    teamName?: string;
+    leadMemberId?: string;
+    teamId: string;
+    workspacePath: string;
+    revision: number;
+    members: TeamMember[];
+};
+export type MessageKind = 'message' | 'direction' | 'comment';
+export type TeamInboxMessage = {
+    id: string;
+    from: string;
+    fromName: string;
+    kind: MessageKind;
+    content: string;
+    createdAt: number;
+    delivery: {
+        id: string;
+        state: 'stored' | 'acknowledged';
+        acknowledgedAt?: number;
+    };
+};
+export type TeamInbox = {
+    teamId: string;
+    messages: TeamInboxMessage[];
+};
+/**
+ * One member who is waiting for the human. Small on purpose: the chip that shows
+ * this lives in the Session header of every Session and must not pull the inbox.
+ */
+export type TeamAttentionEntry = {
+    memberId: string;
+    name: string;
+    sessionId: string | null;
+    waiting: number;
+    since: number;
+    kind: MessageKind;
+};
+export type TeamAttention = {
+    teamId: string;
+    attention: TeamAttentionEntry[];
+};
+export type JournalCategory = 'message' | 'delivery' | 'task' | 'review' | 'contact' | 'team' | 'member' | 'other';
+export type TeamJournalEntry = {
+    id: string;
+    kind: string;
+    category: JournalCategory;
+    at: number;
+    actor?: string;
+    actorName?: string;
+    summary: string;
+    refs: {
+        taskId?: string;
+        taskTitle?: string;
+        messageId?: string;
+        round?: number; /** Everything the row knows, resolved for a person: who, to whom, which task, which attempt. */
+        fields?: {
+            label: string;
+            value: string;
+        }[];
+        /** The summary split into plain and emphasised runs: names are names, not words. */
+        summaryParts?: {
+            text: string;
+            strong?: boolean;
+        }[];
+    };
+    detail?: string;
+};
+export type TeamJournal = {
+    teamId: string;
+    entries: TeamJournalEntry[];
+};
+export type SendMessageResult = {
+    messageId: string;
+    recipients: string[];
+    deliveries: Array<{
+        id: string;
+        recipient: string;
+        state: string;
+        failure?: string;
+    }>;
+};
+export type TeamCandidate = {
+    sessionId: string;
+    title: string | null;
+    cwd: string;
+    live: boolean;
+    status: 'idle' | 'running' | 'unknown';
+};
+export type TeamCandidates = {
+    teamId: string;
+    /** Name the listed Sessions are titled with, so `"<member> - <team>"` can be undone. */
+    teamName: string;
+    workspacePath: string;
+    revision: number;
+    candidates: TeamCandidate[];
+};
+export type TeamAdoptionCandidate = {
+    teamId: string;
+    name?: string;
+    memberCount?: number;
+    updatedAt?: number;
+    usable?: boolean;
+    reason?: string;
+};
+export type TeamAdoptionCandidates = {
+    teamId: string;
+    workspacePath: string;
+    candidates: TeamAdoptionCandidate[];
+};
+export type TeamRole = {
+    id: string;
+    name: string;
+    description?: string;
+    aliases: string[];
+    source: 'global' | 'workspace';
+    overridden: boolean;
+};
+export type TeamRoles = {
+    roles: TeamRole[];
+    globalDirectory: string;
+    workspaceDirectory: string;
+    workspaceDirectoryExists: boolean;
+    openAvailable: boolean;
+    globalOpenAvailable: boolean;
+};
+export type TaskStatus = 'draft' | 'ready' | 'claimed' | 'in_progress' | 'waiting' | 'needs_human' | 'completed' | 'failed' | 'cancelled';
+export type TaskRoute = {
+    type: 'report';
+    to: string | 'human';
+} | {
+    type: 'review';
+    reviewer: string;
+} | {
+    type: 'interactive';
+    then: TaskRoute;
+} | {
+    type: 'custom';
+    description: string;
+};
+export type TaskRouteSummary = {
+    type: 'report';
+    to: string | 'human';
+    toName?: string;
+} | {
+    type: 'review';
+    reviewer: string;
+    reviewerName?: string;
+} | {
+    type: 'interactive';
+    then: TaskRouteSummary;
+} | {
+    type: 'custom';
+    description: string;
+};
+export type TeamTask = {
+    id: string;
+    teamId: string;
+    title: string;
+    kind: string;
+    status: TaskStatus;
+    assignee?: string;
+    route?: TaskRoute;
+    humanContact?: 'none' | 'expected' | 'required';
+    activeAttemptId?: string;
+    latestSubmissionId?: string;
+    acceptedSubmissionId?: string;
+    acceptance: string[];
+    /** Checks and declared paths are part of the contract the human edits. */
+    checks?: string[];
+    paths?: string[];
+    roundLimit: number;
+    createdBy: string;
+    createdAt: number;
+    updatedAt: number;
+    revision: number;
+    archivedPath?: string;
+    documentMissing?: boolean;
+};
+export type TaskSummary = {
+    id: string;
+    title: string;
+    status: TaskStatus;
+    assignee?: string;
+    assigneeName?: string;
+    route?: TaskRouteSummary;
+    round?: number;
+    roundLimit?: number;
+    updatedAt: number;
+    archivedPath?: string;
+    documentMissing?: boolean;
+    dependsOn?: string[];
+    blockedBy?: Array<{
+        id: string;
+        title: string;
+        status: TaskStatus;
+    }>;
+    /** Declared write paths, so the contract form can be filled without a second read. */
+    paths?: string[];
+    checks?: string[];
+};
+export type SubmissionArtifact = {
+    type: 'report';
+    bodyRef: string;
+    bodyDigest: string;
+} | {
+    type: 'files';
+    paths: string[];
+    manifestDigest: string;
+};
+export type SubmissionCheck = {
+    command: string;
+    status: 'passed' | 'failed';
+    output?: string;
+};
+export type TeamSubmissionScope = {
+    declared?: string[];
+    changed?: string[];
+    unexpected?: string[];
+    sharedTree?: string[];
+    state: 'clean' | 'violation' | 'shared-tree' | 'unchecked';
+    /** B32: `git` in a work tree, `files` in a folder that is not a repository. */
+    mode?: 'git' | 'files';
+    reason?: 'no-repository' | 'too-many-files' | 'no-snapshot' | 'unreadable';
+};
+export type Submission = {
+    id: string;
+    taskId: string;
+    attemptId: string;
+    attemptGeneration: number;
+    artifact: SubmissionArtifact;
+    summary: string;
+    checks: SubmissionCheck[];
+    scope?: TeamSubmissionScope;
+    createdAt: number;
+    revision: number;
+};
+export type ReviewFinding = {
+    severity: 'low' | 'medium' | 'high' | 'blocker';
+    problem: string;
+    requiredFix: string;
+    artifactLocation?: string;
+};
+export type ReviewRound = {
+    id: string;
+    taskId: string;
+    submissionId: string;
+    reviewerMemberId: string;
+    round: number;
+    verdict: 'pass' | 'needs_revision' | 'escalate';
+    findings: ReviewFinding[];
+    evidence: SubmissionCheck[];
+    createdAt: number;
+    revision: number;
+};
+export type TeamTasks = {
+    teamId: string;
+    tasks: TaskSummary[];
+};
+export type TeamAttemptStatus = 'active' | 'revoking' | 'revoked' | 'completed' | 'failed';
+export type TeamTaskAttempt = {
+    id: string;
+    memberId: string;
+    sessionId: string;
+    generation: number;
+    status: TeamAttemptStatus;
+    startedAt: number;
+    humanIntervenedAt?: number;
+};
+export type TeamTaskDetail = {
+    task: TeamTask;
+    document: string;
+    documentMissing?: true;
+    submissions: Submission[];
+    rounds: ReviewRound[];
+    attempts: TeamTaskAttempt[];
+};
+export type AcceptTaskResult = {
+    task: TeamTask;
+    archivedPath: string;
+};
+export type ReviseTaskResult = {
+    task: TeamTask;
+};
+/** The workspace folder action only exists after override created its folder. */
+export declare function canOpenWorkspaceRoles(roles: Pick<TeamRoles, 'openAvailable' | 'workspaceDirectoryExists'>): boolean;
+export type CreateSessionSuccess = {
+    teamId: string;
+    memberId: string;
+    sessionId: string;
+    revision: number;
+    applied: true;
+    retried: boolean;
+    member: TeamMember;
+};
+export type MutationSuccess = {
+    teamId: string;
+    memberId: string;
+    revision: number;
+    applied: true;
+    retried: boolean;
+    member: TeamMember;
+};
+export type InterruptTurnSuccess = {
+    memberId: string;
+    interrupted: true;
+    status: 'idle' | 'running' | 'unknown';
+};
+export type RemoveMemberSuccess = {
+    teamId: string;
+    memberId: string;
+    revision: number;
+    applied: true;
+    retried: boolean;
+    removed: {
+        memberId: string;
+        displayName: string;
+        role: string;
+        sessionId: string | null;
+    };
+};
+export type MutationConflict = {
+    revision: number;
+    members: TeamMember[];
+};
+export declare class LiveTeamsApiError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly conflict: MutationConflict | null;
+    constructor(status: number, error: string, conflict?: MutationConflict | null);
+}
+export type TeamStateStatus = {
+    enabled: boolean;
+    briefing?: string;
+    openAvailable?: boolean;
+    teamId: string;
+    teamName: string;
+    workspacePath: string;
+    revision?: number;
+    memberCount?: number;
+    compatibility?: {
+        verdict: 'compatible' | 'degraded' | 'incompatible';
+        hostVersion?: string;
+        missing: string[];
+        absent: string[];
+        detail: string;
+    };
+};
+export declare function fetchTeamState(session?: string, signal?: AbortSignal): Promise<TeamStateStatus>;
+export declare function enableTeam(name?: string, session?: string, createNew?: boolean): Promise<TeamStateStatus>;
+export declare function disableTeam(session?: string): Promise<TeamStateStatus>;
+export declare function renameTeam(name: string, expectedRevision: number, session?: string): Promise<TeamStateStatus>;
+export declare function fetchTeamTasks(session?: string, includeArchived?: boolean, signal?: AbortSignal): Promise<TeamTasks>;
+/** One task's dispatch verdict, in the same words the journal uses (B29). */
+export type DispatchTaskVerdict = {
+    taskId: string;
+    title: string;
+    status: string;
+    assignee?: string;
+    decision: 'assign' | 'active' | 'wait' | 'refused';
+    reason: string;
+    detail: string;
+    warning?: string;
+    /** F3: this attempt has been silent long enough to show. Detection only, never an auto-revoke. */
+    stalled?: {
+        at: number;
+        reason: 'unacknowledged' | 'idle';
+        detail: string;
+    };
+};
+export type TeamDispatch = {
+    teamId: string;
+    paused: boolean;
+    coding: 'manual' | 'automatic';
+    pausedBy?: string;
+    pausedReason?: string;
+    counts: Record<'assign' | 'active' | 'wait' | 'refused', number>;
+    tasks: DispatchTaskVerdict[];
+};
+export declare function fetchTeamDispatch(session?: string, signal?: AbortSignal): Promise<TeamDispatch>;
+/** Only the human and the lead may flip this; the server decides which one the caller is. */
+export declare function setTeamDispatch(mode: 'auto' | 'paused', reason?: string, session?: string): Promise<{
+    from: string;
+    to: string;
+}>;
+export declare function fetchTeamTask(taskId: string, session?: string, signal?: AbortSignal): Promise<TeamTaskDetail>;
+export declare function acceptTeamTask(taskId: string, note?: string, session?: string): Promise<AcceptTaskResult>;
+export declare function reviseTeamTask(taskId: string, instructions: string, session?: string): Promise<ReviseTaskResult>;
+export declare function fetchTeamRoles(session?: string, signal?: AbortSignal): Promise<TeamRoles>;
+export declare function openTeamRoles(kind: 'global' | 'workspace', id?: string, session?: string): Promise<string>;
+export declare function overrideTeamRole(id: string, session?: string): Promise<{
+    id: string;
+    path: string;
+}>;
+export declare function fetchTeamAdoptionCandidates(session?: string, signal?: AbortSignal): Promise<TeamAdoptionCandidates>;
+export declare function adoptTeam(teamId: string, replaceEmptyDerived: boolean, session?: string): Promise<TeamStateStatus & {
+    adoptedFrom: string;
+}>;
+export declare function fetchTeamCandidates(session?: string, signal?: AbortSignal): Promise<TeamCandidates>;
+export declare function fetchTeamInbox(session?: string, limit?: number, signal?: AbortSignal): Promise<TeamInbox>;
+/** Who is waiting for the human, one entry per member. Polled by the header chip. */
+export declare function fetchTeamAttention(session?: string, signal?: AbortSignal): Promise<TeamAttention>;
+/**
+ * Clear a whole member's backlog in one request. The chip opens the Session the
+ * human was taken to, so acknowledging 22 rows one by one would be busywork.
+ */
+export declare function acknowledgeTeamMessages(messageIds: readonly string[], session?: string): Promise<{
+    messageIds: string[];
+}>;
+export declare function fetchTeamJournal(session?: string, limit?: number, signal?: AbortSignal): Promise<TeamJournal>;
+export declare function sendTeamMessage(request: {
+    to: string;
+    kind: MessageKind;
+    content: string;
+    threadId?: string;
+}, session?: string): Promise<SendMessageResult>;
+export declare function acknowledgeTeamMessage(messageId: string, session?: string): Promise<{
+    messageId: string;
+    state: 'acknowledged';
+}>;
+export type TeamLead = {
+    leadMemberId?: string;
+    resolvedFrom: 'state' | 'role' | 'none';
+};
+export declare function openTeamBriefing(session?: string): Promise<string>;
+export declare function fetchTeamLead(session?: string): Promise<TeamLead>;
+export declare function setTeamLead(memberId: string, session?: string): Promise<{
+    leadMemberId: string;
+}>;
+export declare function fetchTeamSnapshot(session?: string, signal?: AbortSignal): Promise<TeamSnapshot>;
+export declare function changeMemberRole(memberId: string, role: string, expectedRevision: number, session?: string): Promise<MutationSuccess>;
+export declare function changeMemberAvailability(memberId: string, availability: 'available' | 'paused', expectedRevision: number, session?: string): Promise<MutationSuccess>;
+export declare function changeMemberDisplayName(memberId: string, displayName: string, expectedRevision: number, session?: string): Promise<MutationSuccess>;
+/**
+ * The body's `sessionId` names the Session that JOINS, so the request scope travels
+ * in the query instead. Passing it through `withSession` overwrote the joining
+ * Session with the caller's, and the server refused it as already a member.
+ */
+/**
+ * The human's own control over work (review finding 4): the same operations the lead's tools call.
+ * The panel used to read tasks, accept them and send them back — creating one, changing a contract or
+ * releasing a held attempt meant asking the lead and waiting a model turn.
+ */
+export type TaskControlDraft = {
+    title: string;
+    kind: string;
+    assignee: string;
+    acceptance: string[];
+    paths?: string[];
+    checks?: string[];
+    body?: string;
+    why?: string;
+    route?: {
+        type: string;
+        to?: string;
+        reviewer?: string;
+    };
+    roundLimit?: number;
+};
+export declare function createTeamTask(draft: TaskControlDraft, session?: string): Promise<{
+    task: {
+        id: string;
+        title: string;
+        status: string;
+    };
+}>;
+export declare function updateTeamTask(request: {
+    taskId: string;
+    acceptance?: string[];
+    paths?: string[];
+    checks?: string[];
+    title?: string;
+    assignee?: string;
+    body?: string;
+    expectedRevision?: number;
+}, session?: string): Promise<MutationSuccess>;
+export declare function revokeTeamTask(request: {
+    taskId: string;
+    reason: string;
+}, session?: string): Promise<MutationSuccess>;
+export declare function addTeamMember(request: {
+    sessionId: string;
+    displayName: string;
+    role: string;
+    memberId?: string;
+    expectedRevision: number;
+}, session?: string): Promise<MutationSuccess>;
+export declare function createTeamSessionMember(request: {
+    displayName: string;
+    role: string;
+    expectedRevision: number;
+}, session?: string): Promise<CreateSessionSuccess>;
+export declare function interruptTeamMember(memberId: string, session?: string): Promise<InterruptTurnSuccess>;
+export type ContactGrant = {
+    from: string;
+    to: string;
+    grantedBy: string;
+    at: number;
+};
+export type ContactGrantResult = {
+    grants: ContactGrant[];
+    leadMemberId?: string;
+};
+export declare function grantTeamContact(request: {
+    memberId: string;
+    allow: string;
+    action: 'add' | 'remove';
+}, session?: string): Promise<ContactGrantResult>;
+export declare function removeTeamMember(memberId: string, expectedRevision: number, session?: string): Promise<RemoveMemberSuccess>;

package/lib/types/client/api.test.d.ts

@@ -0,0 +1 @@
+export {};