@adhdev/daemon-core 0.9.66 → 0.9.68

package/src/index.ts

@@ -81,6 +81,26 @@ export type {
   ExtensionProviderState,
 } from './shared-types.js';
 
+// ── Repo Mesh Types (cross-package) ──
+export type {
+  RepoMesh,
+  RepoMeshNode,
+  RepoMeshNodeHealth,
+  RepoMeshPolicy,
+  RepoMeshNodePolicy,
+  RepoMeshNodeCapabilities,
+  DetectedCommand,
+  ProjectContextSnapshot,
+  ProjectContextSource,
+  RepoMeshCoordinatorConfig,
+  LocalMeshConfig,
+  LocalMeshEntry,
+  LocalMeshNodeEntry,
+  RepoMeshStatus,
+  RepoMeshNodeStatus,
+} from './repo-mesh-types.js';
+export { DEFAULT_MESH_POLICY } from './repo-mesh-types.js';
+
 // ── Git Surface ──
 export * from './git/index.js';
 
@@ -111,6 +131,19 @@ export type { RecentActivityEntry } from './config/recent-activity.js';
 export { getSavedProviderSessions, upsertSavedProviderSession } from './config/saved-sessions.js';
 export type { SavedProviderSessionEntry } from './config/saved-sessions.js';
 
+// ── Mesh Config ──
+export {
+  listMeshes, getMesh, getMeshByRepo, createMesh, updateMesh, deleteMesh,
+  addNode, removeNode, updateNode, normalizeRepoIdentity,
+} from './config/mesh-config.js';
+export type { CreateMeshOptions, UpdateMeshOptions, AddNodeOptions } from './config/mesh-config.js';
+
+// ── Mesh Coordinator ──
+export { buildCoordinatorSystemPrompt } from './mesh/coordinator-prompt.js';
+export type { CoordinatorPromptContext } from './mesh/coordinator-prompt.js';
+export { syncMeshes } from './mesh/mesh-sync.js';
+export type { MeshSyncTransport, MeshSyncResult, RemoteMeshRecord } from './mesh/mesh-sync.js';
+
 // ── State Store ──
 export { loadState, saveState, resetState } from './config/state-store.js';
 export type { DaemonState } from './config/state-store.js';

package/src/mesh/coordinator-prompt.ts

@@ -0,0 +1,156 @@
+/**
+ * Coordinator Prompt — System prompt template for mesh coordinator sessions
+ *
+ * When an MCP server starts in mesh mode, this prompt is injected into the
+ * coordinator agent's context so it understands:
+ *   1. What the mesh is (repo, nodes, policy)
+ *   2. What tools are available
+ *   3. How to orchestrate work across nodes
+ *
+ * The prompt is generated dynamically from the current mesh state.
+ */
+
+import type {
+    LocalMeshEntry,
+    RepoMeshPolicy,
+    RepoMeshStatus,
+    RepoMeshNodeStatus,
+} from '../repo-mesh-types.js';
+
+// ─── Prompt Builder ─────────────────────────────
+
+export interface CoordinatorPromptContext {
+    mesh: LocalMeshEntry;
+    status?: RepoMeshStatus;
+    userInstruction?: string;
+}
+
+export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string {
+    const { mesh, status, userInstruction } = ctx;
+    const sections: string[] = [];
+
+    // ── Identity ──
+    sections.push(`You are a **Repo Mesh Coordinator** — a technical team lead who orchestrates work across multiple agent sessions on a shared Git repository.
+
+Your mesh: **${mesh.name}**
+Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`${mesh.defaultBranch}\`` : ''}`);
+
+    // ── Nodes ──
+    if (status?.nodes?.length) {
+        sections.push(buildNodeStatusSection(status.nodes));
+    } else if (mesh.nodes.length) {
+        sections.push(buildNodeConfigSection(mesh));
+    } else {
+        sections.push('## Nodes\nNo nodes configured yet. Ask the user to add nodes with `adhdev mesh add-node`.');
+    }
+
+    // ── Policy ──
+    sections.push(buildPolicySection(mesh.policy));
+
+    // ── Tools ──
+    sections.push(TOOLS_SECTION);
+
+    // ── Workflow ──
+    sections.push(WORKFLOW_SECTION);
+
+    // ── Rules ──
+    sections.push(RULES_SECTION);
+
+    // ── User instruction ──
+    if (userInstruction) {
+        sections.push(`## Additional Context\n${userInstruction}`);
+    }
+
+    if (mesh.coordinator.systemPromptSuffix) {
+        sections.push(mesh.coordinator.systemPromptSuffix);
+    }
+
+    return sections.join('\n\n');
+}
+
+// ─── Section Builders ───────────────────────────
+
+function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
+    const lines = ['## Current Node Status', ''];
+    for (const n of nodes) {
+        const healthIcon = n.health === 'online' ? '🟢' :
+            n.health === 'dirty' ? '🟡' :
+            n.health === 'offline' ? '⚫' : '🔴';
+        const sessions = n.activeSessions.length > 0
+            ? `sessions: ${n.activeSessions.join(', ')}`
+            : 'no active sessions';
+        const branch = n.git?.branch ? `branch: \`${n.git.branch}\`` : '';
+        lines.push(`- ${healthIcon} **${n.machineLabel}** (${n.nodeId})`);
+        lines.push(`  workspace: \`${n.workspace}\` | ${branch} | ${sessions}`);
+        if (n.error) lines.push(`  ⚠️ ${n.error}`);
+    }
+    return lines.join('\n');
+}
+
+function buildNodeConfigSection(mesh: LocalMeshEntry): string {
+    const lines = ['## Configured Nodes', ''];
+    for (const n of mesh.nodes) {
+        const labels: string[] = [];
+        if (n.isLocalWorktree) labels.push('worktree');
+        if (n.policy.readOnly) labels.push('read-only');
+        const suffix = labels.length ? ` [${labels.join(', ')}]` : '';
+        lines.push(`- **${n.workspace}** (${n.id})${suffix}`);
+    }
+    lines.push('', '_Use `mesh_status` to probe live health before delegating work._');
+    return lines.join('\n');
+}
+
+function buildPolicySection(policy: RepoMeshPolicy): string {
+    const rules: string[] = [];
+    if (policy.requirePreTaskCheckpoint) rules.push('- Create a git checkpoint **before** starting each task');
+    if (policy.requirePostTaskCheckpoint) rules.push('- Create a git checkpoint **after** each task completes');
+    if (policy.requireApprovalForPush) rules.push('- **Ask for user approval** before pushing to remote');
+    if (policy.requireApprovalForDestructiveGit) rules.push('- **Ask for user approval** before destructive git operations (force push, reset, etc.)');
+
+    const dirtyBehavior = {
+        block: '- **Do not** send tasks to nodes with dirty workspaces',
+        warn: '- Warn the user if a node has uncommitted changes before sending a task',
+        checkpoint_then_continue: '- Auto-checkpoint dirty nodes before sending tasks',
+    }[policy.dirtyWorkspaceBehavior] || '';
+    if (dirtyBehavior) rules.push(dirtyBehavior);
+
+    rules.push(`- Maximum **${policy.maxParallelTasks}** tasks running in parallel`);
+
+    return `## Policy\n${rules.join('\n')}`;
+}
+
+const TOOLS_SECTION = `## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`mesh_status\` | Check all nodes' health, git state, and active sessions |
+| \`mesh_list_nodes\` | List nodes with workspace paths |
+| \`mesh_launch_session\` | Start a new agent session on a node |
+| \`mesh_send_task\` | Send a task (natural language) to a running agent |
+| \`mesh_read_chat\` | Read an agent's recent messages to check progress |
+| \`mesh_git_status\` | Check git status on a specific node |
+| \`mesh_checkpoint\` | Create a git checkpoint on a node |
+| \`mesh_approve\` | Approve/reject a pending agent action |`;
+
+const WORKFLOW_SECTION = `## Orchestration Workflow
+
+1. **Assess** — Call \`mesh_status\` to see which nodes are healthy and available.
+2. **Plan** — Decompose the user's request into independent tasks for parallel execution, or sequential tasks when dependencies exist.
+3. **Delegate** — For each task:
+   a. Pick the best node (consider: health, dirty state, current workload).
+   b. If no session exists, call \`mesh_launch_session\` to start one.
+   c. Call \`mesh_send_task\` with a clear, self-contained natural-language instruction.
+4. **Monitor** — Periodically call \`mesh_read_chat\` to check progress. Handle approvals via \`mesh_approve\`.
+5. **Verify** — When a task reports completion, call \`mesh_git_status\` to verify changes were made.
+6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
+7. **Report** — Summarize what was done, what changed, and any issues.`;
+
+const RULES_SECTION = `## Rules
+
+- **Be conversational.** Delegate work the way a tech lead would — clear, specific instructions in natural language.
+- **Don't inspect code.** Trust the agent's output. Verify via git diff/status, not by reading source files.
+- **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed.
+- **Handle failures gracefully.** If a task fails, read the chat to understand why, then retry or reassign.
+- **Keep the user informed.** Report progress after each delegation round.
+- **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
+- **Never fabricate tool results.** Always call the actual tool; never pretend you did.`;

package/src/mesh/mesh-sync.ts

@@ -0,0 +1,109 @@
+/**
+ * Mesh Sync — Sync local mesh config to/from cloud D1
+ *
+ * When cloud is available, this module pushes local mesh config
+ * to the server and pulls remote meshes that were created from
+ * other machines. The local ~/.adhdev/meshes.json remains the
+ * canonical source; cloud is a persistence/relay layer.
+ *
+ * This is called lazily (not on daemon startup) — only when the
+ * user explicitly opens the mesh page or runs `adhdev mesh sync`.
+ */
+
+import { listMeshes, getMesh, createMesh, deleteMesh, addNode, removeNode } from '../config/mesh-config.js';
+import type { LocalMeshEntry, LocalMeshNodeEntry } from '../repo-mesh-types.js';
+
+export interface MeshSyncTransport {
+    /** GET /api/v1/repo-meshes */
+    listRemoteMeshes(): Promise<{ meshes: RemoteMeshRecord[] }>;
+    /** POST /api/v1/repo-meshes */
+    createRemoteMesh(data: {
+        name: string;
+        repo_identity: string;
+        repo_remote_url?: string;
+        default_branch?: string;
+        policy?: string;
+    }): Promise<{ mesh: RemoteMeshRecord }>;
+    /** DELETE /api/v1/repo-meshes/:id */
+    deleteRemoteMesh(meshId: string): Promise<void>;
+}
+
+export interface RemoteMeshRecord {
+    id: string;
+    name: string;
+    repo_identity: string;
+    repo_remote_url: string | null;
+    default_branch: string | null;
+    policy: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+
+export interface MeshSyncResult {
+    pushed: number;
+    pulled: number;
+    deleted: number;
+    errors: string[];
+}
+
+/**
+ * Push local meshes to cloud (upsert by repo_identity).
+ * Pull remote meshes that don't exist locally.
+ */
+export async function syncMeshes(transport: MeshSyncTransport): Promise<MeshSyncResult> {
+    const result: MeshSyncResult = { pushed: 0, pulled: 0, deleted: 0, errors: [] };
+
+    let remoteMeshes: RemoteMeshRecord[];
+    try {
+        const res = await transport.listRemoteMeshes();
+        remoteMeshes = res.meshes;
+    } catch (e: any) {
+        result.errors.push(`Failed to list remote meshes: ${e.message}`);
+        return result;
+    }
+
+    const localMeshes = listMeshes();
+    const remoteByIdentity = new Map(remoteMeshes.map(m => [m.repo_identity, m]));
+    const localByIdentity = new Map(localMeshes.map(m => [m.repoIdentity, m]));
+
+    // Push: local meshes not in cloud
+    for (const local of localMeshes) {
+        if (!remoteByIdentity.has(local.repoIdentity)) {
+            try {
+                await transport.createRemoteMesh({
+                    name: local.name,
+                    repo_identity: local.repoIdentity,
+                    repo_remote_url: local.repoRemoteUrl,
+                    default_branch: local.defaultBranch,
+                    policy: JSON.stringify(local.policy),
+                });
+                result.pushed++;
+            } catch (e: any) {
+                result.errors.push(`Push failed for "${local.name}": ${e.message}`);
+            }
+        }
+    }
+
+    // Pull: remote meshes not in local
+    for (const remote of remoteMeshes) {
+        if (!localByIdentity.has(remote.repo_identity)) {
+            try {
+                let policy;
+                try { policy = JSON.parse(remote.policy); } catch { policy = undefined; }
+                createMesh({
+                    name: remote.name,
+                    repoIdentity: remote.repo_identity,
+                    repoRemoteUrl: remote.repo_remote_url || undefined,
+                    defaultBranch: remote.default_branch || undefined,
+                    policy,
+                });
+                result.pulled++;
+            } catch (e: any) {
+                result.errors.push(`Pull failed for "${remote.name}": ${e.message}`);
+            }
+        }
+    }
+
+    return result;
+}

package/src/repo-mesh-types.ts

@@ -0,0 +1,212 @@
+/**
+ * Repo Mesh Types — Cross-package type definitions for repo-scoped orchestration
+ *
+ * A Repo Mesh is a repo-scoped execution environment that groups
+ * machines/workspaces around one Git repository identity. A coordinator
+ * agent delegates work to mesh nodes via natural conversation.
+ *
+ * These types are OSS-level and usable without cloud infrastructure.
+ * Import via: import type { ... } from '@adhdev/daemon-core/repo-mesh-types'
+ *
+ * IMPORTANT: This file must remain runtime-free (types only).
+ */
+
+import type { GitRepoStatus, GitCompactSummary } from './git/git-types.js';
+
+// ─── Core Mesh Types ────────────────────────────
+
+export interface RepoMesh {
+    id: string;
+    name: string;
+    repoIdentity: string;
+    repoRemoteUrl?: string;
+    defaultBranch?: string;
+    policy: RepoMeshPolicy;
+    coordinator: RepoMeshCoordinatorConfig;
+    projectContext: ProjectContextSnapshot;
+    nodes: RepoMeshNode[];
+    status: 'active' | 'archived' | 'deleted';
+}
+
+export interface RepoMeshNode {
+    id: string;
+    daemonId: string;
+    machineId?: string;
+    machineLabel: string;
+    workspace: string;
+    repoRoot?: string;
+    git?: GitCompactSummary;
+    providers: string[];
+    detectedCapabilities: RepoMeshNodeCapabilities;
+    userOverrides: Partial<RepoMeshNodeCapabilities>;
+    effectiveCapabilities: RepoMeshNodeCapabilities;
+    policy: RepoMeshNodePolicy;
+    health: RepoMeshNodeHealth;
+    status: 'enabled' | 'disabled' | 'removed';
+}
+
+export type RepoMeshNodeHealth =
+    | 'online'
+    | 'offline'
+    | 'degraded'
+    | 'dirty'
+    | 'wrong_branch'
+    | 'unknown';
+
+// ─── Policy Types ───────────────────────────────
+
+export interface RepoMeshPolicy {
+    requirePreTaskCheckpoint: boolean;
+    requirePostTaskCheckpoint: boolean;
+    requireApprovalForPush: boolean;
+    requireApprovalForDestructiveGit: boolean;
+    dirtyWorkspaceBehavior: 'block' | 'warn' | 'checkpoint_then_continue';
+    maxParallelTasks: number;
+    allowedProviders?: string[];
+}
+
+export interface RepoMeshNodePolicy {
+    readOnly?: boolean;
+    canPush?: boolean;
+    maxConcurrentSessions?: number;
+}
+
+export const DEFAULT_MESH_POLICY: RepoMeshPolicy = {
+    requirePreTaskCheckpoint: false,
+    requirePostTaskCheckpoint: true,
+    requireApprovalForPush: true,
+    requireApprovalForDestructiveGit: true,
+    dirtyWorkspaceBehavior: 'warn',
+    maxParallelTasks: 2,
+};
+
+// ─── Capabilities ───────────────────────────────
+
+export interface RepoMeshNodeCapabilities {
+    platform?: string;
+    packageManagers?: string[];
+    detectedCommands?: DetectedCommand[];
+    canRunLongJobs?: boolean;
+    canRunDocker?: boolean;
+    canRunBrowserE2E?: boolean;
+    canAccessSecrets?: boolean;
+    canPush?: boolean;
+    readOnly?: boolean;
+    userLabels?: string[];
+}
+
+export interface DetectedCommand {
+    command: string;
+    sourcePath: string;
+    confidence: 'high' | 'medium' | 'low';
+    requiresApproval?: boolean;
+}
+
+// ─── Project Context ────────────────────────────
+
+export interface ProjectContextSnapshot {
+    version: number;
+    generatedAt: string;
+    sources: ProjectContextSource[];
+    repo: {
+        identity: string;
+        remoteUrl?: string;
+        defaultBranch?: string;
+        currentBranches: string[];
+    };
+    layout: {
+        packageManager?: string;
+        workspaceFiles: string[];
+        packageRoots: string[];
+        likelyEntryPoints: string[];
+    };
+    commands: {
+        build?: DetectedCommand[];
+        test?: DetectedCommand[];
+        typecheck?: DetectedCommand[];
+        lint?: DetectedCommand[];
+        e2e?: DetectedCommand[];
+    };
+    instructions: {
+        files: string[];
+        summary: string;
+    };
+    conventions: {
+        pathHints: string[];
+        validationNotes: string[];
+        riskyAreas: string[];
+    };
+}
+
+export interface ProjectContextSource {
+    kind: 'daemon_status' | 'git' | 'project_file' | 'instruction_file' | 'user_override' | 'probe_error';
+    nodeId?: string;
+    path?: string;
+    observedAt: string;
+    confidence: 'high' | 'medium' | 'low';
+}
+
+// ─── Coordinator Config ─────────────────────────
+
+export interface RepoMeshCoordinatorConfig {
+    /** Provider to use for coordinator session (e.g. 'claude-cli', 'cursor') */
+    providerType?: string;
+    /** Preferred node to run coordinator on (null = auto) */
+    preferredNodeId?: string;
+    /** Additional system prompt context for coordinator */
+    systemPromptSuffix?: string;
+}
+
+// ─── Local Mesh Config (OSS standalone) ─────────
+
+/**
+ * Local mesh configuration stored in ~/.adhdev/meshes.json
+ * Used by OSS standalone mode without cloud infrastructure.
+ */
+export interface LocalMeshConfig {
+    meshes: LocalMeshEntry[];
+}
+
+export interface LocalMeshEntry {
+    id: string;
+    name: string;
+    repoIdentity: string;
+    repoRemoteUrl?: string;
+    defaultBranch?: string;
+    policy: RepoMeshPolicy;
+    coordinator: RepoMeshCoordinatorConfig;
+    nodes: LocalMeshNodeEntry[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface LocalMeshNodeEntry {
+    id: string;
+    workspace: string;
+    repoRoot?: string;
+    userOverrides: Partial<RepoMeshNodeCapabilities>;
+    policy: RepoMeshNodePolicy;
+    /** For single-machine mesh: same daemon, different worktree */
+    isLocalWorktree?: boolean;
+}
+
+// ─── Mesh Status (runtime, not persisted) ───────
+
+export interface RepoMeshStatus {
+    meshId: string;
+    meshName: string;
+    repoIdentity: string;
+    refreshedAt: string;
+    nodes: RepoMeshNodeStatus[];
+}
+
+export interface RepoMeshNodeStatus {
+    nodeId: string;
+    machineLabel: string;
+    workspace: string;
+    health: RepoMeshNodeHealth;
+    git?: GitRepoStatus;
+    providers: string[];
+    activeSessions: string[];
+    error?: string;
+}