@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/CoordinationProtocol.d.ts

@@ -0,0 +1,198 @@
+/**
+ * CoordinationProtocol — Work coordination primitives for multi-machine agents.
+ *
+ * Provides higher-level coordination on top of AgentBus:
+ *   1. File avoidance requests ("please avoid file X for 30 min")
+ *   2. Work announcements (broadcast what you're starting/finishing)
+ *   3. Status queries (who is working on what?)
+ *   4. ETA tracking (when will other machine finish with a file?)
+ *   5. Leadership / awake-role management with fencing tokens
+ *
+ * From INTELLIGENT_SYNC_SPEC Sections 7.4, 8, 13.
+ */
+import type { AgentBus } from './AgentBus.js';
+export interface FileAvoidanceRequest {
+    /** Files to avoid. */
+    files: string[];
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Reason for the request. */
+    reason: string;
+    /** Session ID of the requester. */
+    sessionId?: string;
+}
+export interface FileAvoidanceResponse {
+    /** Whether the request was accepted. */
+    accepted: boolean;
+    /** Files that cannot be avoided (already committed to). */
+    conflictingFiles: string[];
+    /** Reason for partial/full rejection. */
+    reason?: string;
+}
+export interface WorkAnnouncement {
+    /** Unique work item ID. */
+    workId: string;
+    /** Type of announcement. */
+    action: 'started' | 'completed' | 'paused' | 'resumed' | 'abandoned';
+    /** Session ID. */
+    sessionId: string;
+    /** Task description. */
+    task: string;
+    /** Files planned or modified. */
+    files: string[];
+    /** Branch name, if applicable. */
+    branch?: string;
+    /** Estimated completion time (ISO). */
+    eta?: string;
+}
+export interface StatusQuery {
+    /** What to query. */
+    queryType: 'active-work' | 'file-owners' | 'machine-status';
+    /** Filter by specific files (for file-owners). */
+    files?: string[];
+}
+export interface StatusResponse {
+    /** Machine ID of the responder. */
+    machineId: string;
+    /** Active work items on this machine. */
+    activeWork: WorkAnnouncement[];
+    /** Machine status. */
+    status: 'active' | 'idle' | 'shutting-down';
+    /** Current session ID. */
+    sessionId?: string;
+}
+export interface LeadershipState {
+    /** Current leader machine ID. */
+    leaderId: string;
+    /** Fencing token (monotonically increasing). */
+    fencingToken: number;
+    /** Role of this machine. */
+    role: 'awake' | 'standby';
+    /** Lease expiration (ISO). */
+    leaseExpiresAt: string;
+    /** When the lease was acquired. */
+    acquiredAt: string;
+}
+export interface AvoidanceEntry {
+    /** Requesting machine. */
+    from: string;
+    /** Files to avoid. */
+    files: string[];
+    /** When the avoidance expires. */
+    expiresAt: number;
+    /** Reason. */
+    reason: string;
+}
+export interface CoordinationProtocolConfig {
+    /** The AgentBus instance for communication. */
+    bus: AgentBus;
+    /** This machine's ID. */
+    machineId: string;
+    /** State directory (.instar). */
+    stateDir: string;
+    /** Lease TTL in ms (default: 15 min). */
+    leaseTtlMs?: number;
+    /** Timeout for status queries in ms (default: 10s). */
+    statusQueryTimeoutMs?: number;
+    /** Callback when a file avoidance request is received. */
+    onAvoidanceRequest?: (req: FileAvoidanceRequest, from: string) => FileAvoidanceResponse;
+    /** Callback when a work announcement is received. */
+    onWorkAnnouncement?: (announcement: WorkAnnouncement, from: string) => void;
+}
+export interface CoordinationEvents {
+    'avoidance-requested': (req: FileAvoidanceRequest, from: string) => void;
+    'avoidance-response': (resp: FileAvoidanceResponse, from: string) => void;
+    'work-announced': (announcement: WorkAnnouncement, from: string) => void;
+    'status-response': (resp: StatusResponse) => void;
+    'leadership-changed': (state: LeadershipState) => void;
+}
+export declare class CoordinationProtocol {
+    private bus;
+    private machineId;
+    private stateDir;
+    private leaseTtlMs;
+    private statusQueryTimeoutMs;
+    private coordDir;
+    private avoidances;
+    private peerWork;
+    private onAvoidanceRequest?;
+    private onWorkAnnouncement?;
+    constructor(config: CoordinationProtocolConfig);
+    /**
+     * Request another machine to avoid specific files for a duration.
+     */
+    requestFileAvoidance(targetMachineId: string, request: FileAvoidanceRequest): Promise<FileAvoidanceResponse | null>;
+    /**
+     * Broadcast a file avoidance request to all machines.
+     */
+    broadcastFileAvoidance(request: FileAvoidanceRequest): Promise<void>;
+    /**
+     * Check if a file is currently under avoidance.
+     */
+    isFileAvoided(filePath: string): AvoidanceEntry | undefined;
+    /**
+     * Get all active avoidances.
+     */
+    getActiveAvoidances(): AvoidanceEntry[];
+    /**
+     * Announce work to all machines.
+     */
+    announceWork(announcement: WorkAnnouncement): Promise<void>;
+    /**
+     * Announce that work has started.
+     */
+    announceWorkStarted(opts: {
+        sessionId: string;
+        task: string;
+        files: string[];
+        branch?: string;
+        eta?: string;
+    }): Promise<string>;
+    /**
+     * Announce that work has completed.
+     */
+    announceWorkCompleted(workId: string, sessionId: string, files: string[]): Promise<void>;
+    /**
+     * Get known work from other machines.
+     */
+    getPeerWork(machineId?: string): WorkAnnouncement[];
+    /**
+     * Query a specific machine's status.
+     */
+    queryStatus(targetMachineId: string): Promise<StatusResponse | null>;
+    /**
+     * Query all machines for file owners.
+     */
+    queryFileOwners(files: string[]): Promise<StatusResponse[]>;
+    /**
+     * Attempt to claim the awake (leader) role.
+     * Returns the new leadership state if successful.
+     */
+    claimLeadership(): LeadershipState | null;
+    /**
+     * Renew the leadership lease (must already be leader).
+     */
+    renewLease(): LeadershipState | null;
+    /**
+     * Relinquish leadership (transition to standby).
+     */
+    relinquishLeadership(): void;
+    /**
+     * Read current leadership state.
+     */
+    getLeadership(): LeadershipState | null;
+    /**
+     * Check if this machine is the current leader.
+     */
+    isLeader(): boolean;
+    /**
+     * Check if the current leader's lease has expired.
+     */
+    isLeaseExpired(): boolean;
+    getMachineId(): string;
+    private registerHandlers;
+    private cleanExpiredAvoidances;
+    private readLeadership;
+    private writeLeadership;
+}
+//# sourceMappingURL=CoordinationProtocol.d.ts.map

package/dist/core/CoordinationProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoordinationProtocol.d.ts","sourceRoot":"","sources":["../../src/core/CoordinationProtocol.ts"],"names":[],"mappings":"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"}

package/dist/core/CoordinationProtocol.js

@@ -0,0 +1,363 @@
+/**
+ * CoordinationProtocol — Work coordination primitives for multi-machine agents.
+ *
+ * Provides higher-level coordination on top of AgentBus:
+ *   1. File avoidance requests ("please avoid file X for 30 min")
+ *   2. Work announcements (broadcast what you're starting/finishing)
+ *   3. Status queries (who is working on what?)
+ *   4. ETA tracking (when will other machine finish with a file?)
+ *   5. Leadership / awake-role management with fencing tokens
+ *
+ * From INTELLIGENT_SYNC_SPEC Sections 7.4, 8, 13.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+const DEFAULT_LEASE_TTL = 15 * 60 * 1000; // 15 minutes
+const DEFAULT_STATUS_TIMEOUT = 10_000;
+const COORDINATION_DIR = 'coordination';
+const LEADERSHIP_FILE = 'leadership.json';
+const AVOIDANCE_FILE = 'avoidances.json';
+// ── CoordinationProtocol ─────────────────────────────────────────────
+export class CoordinationProtocol {
+    bus;
+    machineId;
+    stateDir;
+    leaseTtlMs;
+    statusQueryTimeoutMs;
+    coordDir;
+    avoidances = [];
+    peerWork = new Map();
+    onAvoidanceRequest;
+    onWorkAnnouncement;
+    constructor(config) {
+        this.bus = config.bus;
+        this.machineId = config.machineId;
+        this.stateDir = config.stateDir;
+        this.leaseTtlMs = config.leaseTtlMs ?? DEFAULT_LEASE_TTL;
+        this.statusQueryTimeoutMs = config.statusQueryTimeoutMs ?? DEFAULT_STATUS_TIMEOUT;
+        this.onAvoidanceRequest = config.onAvoidanceRequest;
+        this.onWorkAnnouncement = config.onWorkAnnouncement;
+        this.coordDir = path.join(config.stateDir, 'state', COORDINATION_DIR);
+        if (!fs.existsSync(this.coordDir)) {
+            fs.mkdirSync(this.coordDir, { recursive: true });
+        }
+        // Register message handlers
+        this.registerHandlers();
+    }
+    // ── File Avoidance ──────────────────────────────────────────────────
+    /**
+     * Request another machine to avoid specific files for a duration.
+     */
+    async requestFileAvoidance(targetMachineId, request) {
+        const reply = await this.bus.request({
+            type: 'file-avoidance-request',
+            to: targetMachineId,
+            payload: request,
+            timeoutMs: this.statusQueryTimeoutMs,
+        });
+        return reply?.payload ?? null;
+    }
+    /**
+     * Broadcast a file avoidance request to all machines.
+     */
+    async broadcastFileAvoidance(request) {
+        await this.bus.send({
+            type: 'file-avoidance-request',
+            to: '*',
+            payload: request,
+        });
+    }
+    /**
+     * Check if a file is currently under avoidance.
+     */
+    isFileAvoided(filePath) {
+        this.cleanExpiredAvoidances();
+        return this.avoidances.find(a => a.files.includes(filePath));
+    }
+    /**
+     * Get all active avoidances.
+     */
+    getActiveAvoidances() {
+        this.cleanExpiredAvoidances();
+        return [...this.avoidances];
+    }
+    // ── Work Announcements ──────────────────────────────────────────────
+    /**
+     * Announce work to all machines.
+     */
+    async announceWork(announcement) {
+        await this.bus.send({
+            type: 'work-announcement',
+            to: '*',
+            payload: announcement,
+        });
+    }
+    /**
+     * Announce that work has started.
+     */
+    async announceWorkStarted(opts) {
+        const workId = `work_${crypto.randomBytes(6).toString('hex')}`;
+        await this.announceWork({
+            workId,
+            action: 'started',
+            ...opts,
+        });
+        return workId;
+    }
+    /**
+     * Announce that work has completed.
+     */
+    async announceWorkCompleted(workId, sessionId, files) {
+        await this.announceWork({
+            workId,
+            action: 'completed',
+            sessionId,
+            task: '',
+            files,
+        });
+    }
+    /**
+     * Get known work from other machines.
+     */
+    getPeerWork(machineId) {
+        if (machineId) {
+            return this.peerWork.get(machineId) ?? [];
+        }
+        const all = [];
+        for (const [, work] of this.peerWork) {
+            all.push(...work);
+        }
+        return all;
+    }
+    // ── Status Queries ──────────────────────────────────────────────────
+    /**
+     * Query a specific machine's status.
+     */
+    async queryStatus(targetMachineId) {
+        const reply = await this.bus.request({
+            type: 'status-update',
+            to: targetMachineId,
+            payload: { queryType: 'active-work' },
+            timeoutMs: this.statusQueryTimeoutMs,
+        });
+        return reply?.payload ?? null;
+    }
+    /**
+     * Query all machines for file owners.
+     */
+    async queryFileOwners(files) {
+        // Broadcast the query
+        await this.bus.send({
+            type: 'status-update',
+            to: '*',
+            payload: { queryType: 'file-owners', files },
+        });
+        // Collect responses (imperfect — relies on peer responses arriving before timeout)
+        return new Promise((resolve) => {
+            const responses = [];
+            const timer = setTimeout(() => {
+                this.bus.off('message', handler);
+                resolve(responses);
+            }, this.statusQueryTimeoutMs);
+            const handler = (msg) => {
+                if (msg.type === 'status-update' && msg.from !== this.machineId) {
+                    const payload = msg.payload;
+                    if (payload.machineId) {
+                        responses.push(payload);
+                    }
+                }
+            };
+            this.bus.on('message', handler);
+        });
+    }
+    // ── Leadership ──────────────────────────────────────────────────────
+    /**
+     * Attempt to claim the awake (leader) role.
+     * Returns the new leadership state if successful.
+     */
+    claimLeadership() {
+        const current = this.readLeadership();
+        // Check if current leader's lease is still valid
+        if (current && current.leaderId !== this.machineId) {
+            const expiresAt = new Date(current.leaseExpiresAt).getTime();
+            if (Date.now() < expiresAt) {
+                return null; // Another machine holds a valid lease
+            }
+        }
+        // Claim leadership
+        const newToken = (current?.fencingToken ?? 0) + 1;
+        const now = new Date();
+        const state = {
+            leaderId: this.machineId,
+            fencingToken: newToken,
+            role: 'awake',
+            leaseExpiresAt: new Date(now.getTime() + this.leaseTtlMs).toISOString(),
+            acquiredAt: now.toISOString(),
+        };
+        this.writeLeadership(state);
+        return state;
+    }
+    /**
+     * Renew the leadership lease (must already be leader).
+     */
+    renewLease() {
+        const current = this.readLeadership();
+        if (!current || current.leaderId !== this.machineId) {
+            return null; // Not the leader
+        }
+        const now = new Date();
+        current.leaseExpiresAt = new Date(now.getTime() + this.leaseTtlMs).toISOString();
+        this.writeLeadership(current);
+        return current;
+    }
+    /**
+     * Relinquish leadership (transition to standby).
+     */
+    relinquishLeadership() {
+        const current = this.readLeadership();
+        if (current && current.leaderId === this.machineId) {
+            current.role = 'standby';
+            current.leaseExpiresAt = new Date().toISOString(); // Expire immediately
+            this.writeLeadership(current);
+        }
+    }
+    /**
+     * Read current leadership state.
+     */
+    getLeadership() {
+        return this.readLeadership();
+    }
+    /**
+     * Check if this machine is the current leader.
+     */
+    isLeader() {
+        const current = this.readLeadership();
+        if (!current)
+            return false;
+        if (current.leaderId !== this.machineId)
+            return false;
+        return Date.now() < new Date(current.leaseExpiresAt).getTime();
+    }
+    /**
+     * Check if the current leader's lease has expired.
+     */
+    isLeaseExpired() {
+        const current = this.readLeadership();
+        if (!current)
+            return true;
+        return Date.now() >= new Date(current.leaseExpiresAt).getTime();
+    }
+    // ── Accessors ───────────────────────────────────────────────────────
+    getMachineId() {
+        return this.machineId;
+    }
+    // ── Private: Message Handlers ───────────────────────────────────────
+    registerHandlers() {
+        // Handle file avoidance requests
+        this.bus.onMessage('file-avoidance-request', (msg) => {
+            // Record the avoidance
+            this.avoidances.push({
+                from: msg.from,
+                files: msg.payload.files,
+                expiresAt: Date.now() + msg.payload.durationMs,
+                reason: msg.payload.reason,
+            });
+            // Invoke callback and possibly respond
+            if (this.onAvoidanceRequest) {
+                const response = this.onAvoidanceRequest(msg.payload, msg.from);
+                // Send response if this was a directed request
+                if (msg.to !== '*' && msg.replyTo === undefined) {
+                    this.bus.send({
+                        type: 'file-avoidance-response',
+                        to: msg.from,
+                        payload: response,
+                        replyTo: msg.id,
+                    });
+                }
+            }
+        });
+        // Handle file avoidance responses
+        this.bus.onMessage('file-avoidance-response', (_msg) => {
+            // Handled by request/response pattern in AgentBus
+        });
+        // Handle work announcements
+        this.bus.onMessage('work-announcement', (msg) => {
+            const announcement = msg.payload;
+            const peerList = this.peerWork.get(msg.from) ?? [];
+            if (announcement.action === 'started' || announcement.action === 'resumed') {
+                // Add or update work entry
+                const existingIdx = peerList.findIndex(w => w.workId === announcement.workId);
+                if (existingIdx >= 0) {
+                    peerList[existingIdx] = announcement;
+                }
+                else {
+                    peerList.push(announcement);
+                }
+            }
+            else if (announcement.action === 'completed' || announcement.action === 'abandoned') {
+                // Remove work entry
+                const idx = peerList.findIndex(w => w.workId === announcement.workId);
+                if (idx >= 0)
+                    peerList.splice(idx, 1);
+            }
+            else if (announcement.action === 'paused') {
+                // Update status
+                const existing = peerList.find(w => w.workId === announcement.workId);
+                if (existing)
+                    existing.action = 'paused';
+            }
+            this.peerWork.set(msg.from, peerList);
+            if (this.onWorkAnnouncement) {
+                this.onWorkAnnouncement(announcement, msg.from);
+            }
+        });
+        // Handle status queries
+        this.bus.onMessage('status-update', (msg) => {
+            // Only respond to queries, not responses
+            const payload = msg.payload;
+            if (!payload.queryType)
+                return;
+            const ownWork = this.peerWork.get(this.machineId) ?? [];
+            const response = {
+                machineId: this.machineId,
+                activeWork: ownWork,
+                status: 'active',
+            };
+            // If file-specific query, filter work
+            if (payload.queryType === 'file-owners' && payload.files) {
+                const targetFiles = new Set(payload.files);
+                response.activeWork = ownWork.filter(w => w.files.some(f => targetFiles.has(f)));
+            }
+            this.bus.send({
+                type: 'status-update',
+                to: msg.from,
+                payload: response,
+                replyTo: msg.id,
+            });
+        });
+    }
+    // ── Private: Avoidance Cleanup ──────────────────────────────────────
+    cleanExpiredAvoidances() {
+        const now = Date.now();
+        this.avoidances = this.avoidances.filter(a => a.expiresAt > now);
+    }
+    // ── Private: Leadership State I/O ───────────────────────────────────
+    readLeadership() {
+        const filePath = path.join(this.coordDir, LEADERSHIP_FILE);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            // @silent-fallback-ok — leadership file may not exist yet; null signals no leadership state
+            return null;
+        }
+    }
+    writeLeadership(state) {
+        const filePath = path.join(this.coordDir, LEADERSHIP_FILE);
+        fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n');
+    }
+}
+//# sourceMappingURL=CoordinationProtocol.js.map

package/dist/core/CoordinationProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoordinationProtocol.js","sourceRoot":"","sources":["../../src/core/CoordinationProtocol.ts"],"names":[],"mappings":"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"}

package/dist/core/CustomReviewerLoader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CustomReviewerLoader — Loads custom reviewer specs from disk.
+ *
+ * Reads `.instar/reviewers/*.json` at server startup and validates each
+ * against the expected schema. Invalid files are logged as warnings but
+ * do not break loading of valid specs.
+ *
+ * v1: Only LLM-powered reviewers (with `prompt` field) are supported.
+ * Specs containing a `script` field are rejected.
+ */
+export interface CustomReviewerSpec {
+    name: string;
+    description: string;
+    mode: 'block' | 'warn' | 'observe';
+    prompt: string;
+    contextRequirements: {
+        message: boolean;
+        toolOutput?: boolean;
+        valueDocuments?: boolean;
+        channel?: boolean;
+        customContext?: string;
+    };
+    priority?: 'p0' | 'p1' | 'p2';
+}
+export declare class CustomReviewerLoader {
+    private stateDir;
+    private reviewersDir;
+    constructor(stateDir: string);
+    /**
+     * Load all valid reviewer specs from the reviewers directory.
+     * Invalid files are warned about but do not prevent loading of valid ones.
+     */
+    loadAll(): CustomReviewerSpec[];
+    /**
+     * Load a specific reviewer by name.
+     * Returns null if not found or invalid.
+     */
+    load(name: string): CustomReviewerSpec | null;
+    /**
+     * Validate a parsed JSON object against the CustomReviewerSpec schema.
+     * Returns the validated spec or null if invalid.
+     */
+    private validate;
+}
+//# sourceMappingURL=CustomReviewerLoader.d.ts.map

package/dist/core/CustomReviewerLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomReviewerLoader.d.ts","sourceRoot":"","sources":["../../src/core/CustomReviewerLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE;QACnB,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CAC/B;AAUD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,QAAQ,EAAE,MAAM;IAK5B;;;OAGG;IACH,OAAO,IAAI,kBAAkB,EAAE;IA+B/B;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAgB7C;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAkFjB"}