twining-mcp 1.3.0

package/dist/engine/coordination.js

@@ -0,0 +1,239 @@
+import { computeLiveness, DEFAULT_LIVENESS_THRESHOLDS, } from "../utils/liveness.js";
+import { normalizeTags } from "../utils/tags.js";
+/** Map liveness state to a numeric score. */
+function livenessToScore(liveness) {
+    switch (liveness) {
+        case "active":
+            return 1.0;
+        case "idle":
+            return 0.5;
+        case "gone":
+            return 0.1;
+    }
+}
+/**
+ * Score an agent against required capabilities and liveness.
+ * Pure function — no side effects, fully testable in isolation.
+ *
+ * Weighting: 70% capability overlap + 30% liveness score.
+ */
+export function scoreAgent(agent, requiredCapabilities, livenessThresholds, now = new Date()) {
+    // Normalize required capabilities for case-insensitive matching
+    const normalizedRequired = normalizeTags(requiredCapabilities);
+    // Find matched capabilities
+    const matched = agent.capabilities.filter((cap) => normalizedRequired.includes(cap));
+    // Compute capability overlap: matched / required, or 0 if no requirements
+    const capability_overlap = normalizedRequired.length > 0 ? matched.length / normalizedRequired.length : 0;
+    // Compute liveness
+    const liveness = computeLiveness(agent.last_active, now, livenessThresholds);
+    const liveness_score = livenessToScore(liveness);
+    // Weighted total: 70% capability + 30% liveness
+    const total_score = capability_overlap * 0.7 + liveness_score * 0.3;
+    return {
+        agent_id: agent.agent_id,
+        capabilities: agent.capabilities,
+        role: agent.role,
+        description: agent.description,
+        liveness,
+        capability_overlap,
+        liveness_score,
+        total_score,
+        matched_capabilities: matched,
+    };
+}
+/** Default timeout durations per urgency level. */
+export const DELEGATION_TIMEOUTS = {
+    high: 300000, // 5 minutes
+    normal: 1800000, // 30 minutes
+    low: 14400000, // 4 hours
+};
+/**
+ * Parse delegation metadata from a blackboard entry's detail field.
+ * Returns null for non-delegation entries or malformed JSON.
+ */
+export function parseDelegationMetadata(entry) {
+    if (!entry.detail)
+        return null;
+    try {
+        const parsed = JSON.parse(entry.detail);
+        if (parsed && parsed.type === "delegation") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a delegation has expired.
+ * Returns true when now >= expires_at (boundary inclusive).
+ */
+export function isDelegationExpired(metadata, now = new Date()) {
+    return now.getTime() >= new Date(metadata.expires_at).getTime();
+}
+export class CoordinationEngine {
+    agentStore;
+    handoffStore;
+    blackboardEngine;
+    decisionStore;
+    blackboardStore;
+    config;
+    constructor(agentStore, handoffStore, blackboardEngine, decisionStore, blackboardStore, config) {
+        this.agentStore = agentStore;
+        this.handoffStore = handoffStore;
+        this.blackboardEngine = blackboardEngine;
+        this.decisionStore = decisionStore;
+        this.blackboardStore = blackboardStore;
+        this.config = config;
+    }
+    /** Discover and rank agents by capability match and liveness. */
+    async discover(input) {
+        const agents = await this.agentStore.getAll();
+        const thresholds = this.config.agents?.liveness ?? DEFAULT_LIVENESS_THRESHOLDS;
+        const now = new Date();
+        // Score each agent
+        let scores = agents.map((agent) => scoreAgent(agent, input.required_capabilities, thresholds, now));
+        // Filter: exclude gone agents if include_gone === false
+        if (input.include_gone === false) {
+            scores = scores.filter((s) => s.liveness !== "gone");
+        }
+        // Filter: exclude agents below min_score threshold
+        if (input.min_score !== undefined) {
+            scores = scores.filter((s) => s.total_score >= input.min_score);
+        }
+        // Sort by total_score descending
+        scores.sort((a, b) => b.total_score - a.total_score);
+        return {
+            agents: scores,
+            total_registered: agents.length,
+        };
+    }
+    /** Post a delegation request to the blackboard. */
+    async postDelegation(input) {
+        const now = new Date();
+        const urgency = input.urgency ?? "normal";
+        // Compute timeout: custom override > config > default constant
+        const urgencyKey = `${urgency}_ms`;
+        const configTimeout = this.config.delegations?.timeouts?.[urgencyKey];
+        const timeoutMs = input.timeout_ms ?? configTimeout ?? DELEGATION_TIMEOUTS[urgency];
+        // Compute expiry
+        const expiresAt = new Date(now.getTime() + timeoutMs).toISOString();
+        // Normalize capabilities
+        const normalizedCapabilities = normalizeTags(input.required_capabilities);
+        // Build delegation metadata
+        const metadata = {
+            type: "delegation",
+            required_capabilities: normalizedCapabilities,
+            urgency,
+            expires_at: expiresAt,
+            timeout_ms: timeoutMs,
+        };
+        // Build tags: user tags + delegation + urgency
+        const tags = [...(input.tags ?? []), "delegation", urgency];
+        // Post to blackboard as a "need" entry
+        const { id, timestamp } = await this.blackboardEngine.post({
+            entry_type: "need",
+            summary: input.summary,
+            detail: JSON.stringify(metadata),
+            tags,
+            scope: input.scope ?? "project",
+            agent_id: input.agent_id ?? "main",
+        });
+        // Get suggested agents via discover (exclude gone agents)
+        const discovery = await this.discover({
+            required_capabilities: input.required_capabilities,
+            include_gone: false,
+        });
+        return {
+            entry_id: id,
+            timestamp,
+            expires_at: expiresAt,
+            suggested_agents: discovery.agents,
+        };
+    }
+    /**
+     * Assemble a context snapshot from active decisions and blackboard
+     * warnings/findings. Used by createHandoff when auto_snapshot is true.
+     */
+    async assembleContextSnapshot(scope) {
+        // 1. Get decision index and filter to active decisions
+        const decisionIndex = await this.decisionStore.getIndex();
+        let activeDecisions = decisionIndex.filter((d) => d.status === "active");
+        // If scope provided, use bidirectional prefix matching
+        if (scope) {
+            activeDecisions = activeDecisions.filter((d) => d.scope.startsWith(scope) || scope.startsWith(d.scope));
+        }
+        // 2. Read blackboard entries for warnings and findings
+        const { entries: bbEntries } = await this.blackboardStore.read({
+            entry_types: ["warning", "finding"],
+            scope,
+        });
+        const warnings = bbEntries.filter((e) => e.entry_type === "warning");
+        const findings = bbEntries.filter((e) => e.entry_type === "finding");
+        // 3. Build context snapshot
+        const decision_ids = activeDecisions.map((d) => d.id);
+        const warning_ids = warnings.map((e) => e.id);
+        const finding_ids = findings.map((e) => e.id);
+        // 4. Build capped summaries
+        const summaries = [];
+        for (const d of activeDecisions.slice(0, 5)) {
+            summaries.push(`Decision: ${d.summary}`);
+        }
+        for (const w of warnings.slice(0, 3)) {
+            summaries.push(`Warning: ${w.summary}`);
+        }
+        for (const f of findings.slice(0, 3)) {
+            summaries.push(`Finding: ${f.summary}`);
+        }
+        return { decision_ids, warning_ids, finding_ids, summaries };
+    }
+    /** Create a handoff record between agents. */
+    async createHandoff(input) {
+        // 1. Determine context_snapshot
+        let context_snapshot;
+        if (input.context_snapshot) {
+            // Manual override
+            context_snapshot = input.context_snapshot;
+        }
+        else if (input.auto_snapshot !== false) {
+            // Auto-assemble (default)
+            context_snapshot = await this.assembleContextSnapshot(input.scope);
+        }
+        else {
+            // Explicitly disabled
+            context_snapshot = {
+                decision_ids: [],
+                warning_ids: [],
+                finding_ids: [],
+                summaries: [],
+            };
+        }
+        // 2. Create via HandoffStore
+        const record = await this.handoffStore.create({
+            source_agent: input.source_agent,
+            target_agent: input.target_agent,
+            scope: input.scope,
+            summary: input.summary,
+            results: input.results,
+            context_snapshot,
+        });
+        // 3. Post status entry to blackboard
+        const statusSummary = `Handoff created: ${input.summary}`.slice(0, 200);
+        const statusDetail = `From ${input.source_agent} to ${input.target_agent ?? "any agent"}. ${input.results.length} result(s).`;
+        await this.blackboardEngine.post({
+            entry_type: "status",
+            summary: statusSummary,
+            detail: statusDetail,
+            tags: ["handoff"],
+            scope: input.scope ?? "project",
+            agent_id: input.source_agent,
+        });
+        return record;
+    }
+    /** Acknowledge receipt of a handoff. */
+    async acknowledgeHandoff(handoffId, agentId) {
+        return this.handoffStore.acknowledge(handoffId, agentId);
+    }
+}
+//# sourceMappingURL=coordination.js.map

package/dist/engine/coordination.js.map

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

package/dist/engine/decisions.d.ts

@@ -0,0 +1,147 @@
+import { DecisionStore } from "../storage/decision-store.js";
+import { BlackboardEngine } from "./blackboard.js";
+import type { DecisionConfidence, DecisionStatus } from "../utils/types.js";
+import type { Embedder } from "../embeddings/embedder.js";
+import type { IndexManager } from "../embeddings/index-manager.js";
+import type { SearchEngine } from "../embeddings/search.js";
+import type { GraphEngine } from "./graph.js";
+/** Entry in a dependency trace chain. */
+export interface TraceEntry {
+    id: string;
+    summary: string;
+    depends_on: string[];
+    dependents: string[];
+    status: string;
+}
+export declare class DecisionEngine {
+    private readonly decisionStore;
+    private readonly blackboardEngine;
+    private readonly embedder;
+    private readonly indexManager;
+    private readonly projectRoot;
+    private readonly searchEngine;
+    private readonly graphEngine;
+    constructor(decisionStore: DecisionStore, blackboardEngine: BlackboardEngine, embedder?: Embedder | null, indexManager?: IndexManager | null, projectRoot?: string | null, searchEngine?: SearchEngine | null, graphEngine?: GraphEngine | null);
+    /**
+     * Sync a decision summary to .planning/STATE.md.
+     * Appends to the "### Decisions" section under "## Accumulated Context".
+     * Never throws — planning sync failure must not prevent decide().
+     * Uses direct fs calls because STATE.md is a GSD planning file, not Twining data.
+     */
+    private syncToPlanning;
+    /** Record a decision with full rationale and conflict detection. */
+    decide(input: {
+        domain: string;
+        scope: string;
+        summary: string;
+        context: string;
+        rationale: string;
+        constraints?: string[];
+        alternatives?: Array<{
+            option: string;
+            pros?: string[];
+            cons?: string[];
+            reason_rejected: string;
+        }>;
+        depends_on?: string[];
+        supersedes?: string;
+        confidence?: "high" | "medium" | "low";
+        reversible?: boolean;
+        affected_files?: string[];
+        affected_symbols?: string[];
+        agent_id?: string;
+        commit_hash?: string;
+    }): Promise<{
+        id: string;
+        timestamp: string;
+        conflicts?: {
+            id: string;
+            summary: string;
+        }[];
+    }>;
+    /** Retrieve decision chain for a scope or file. */
+    why(scope: string): Promise<{
+        decisions: Array<{
+            id: string;
+            summary: string;
+            rationale: string;
+            confidence: string;
+            status: string;
+            timestamp: string;
+            alternatives_count: number;
+            commit_hashes: string[];
+        }>;
+        active_count: number;
+        provisional_count: number;
+    }>;
+    /**
+     * Link a commit hash to an existing decision.
+     * Posts a status entry to the blackboard for traceability.
+     */
+    linkCommit(decisionId: string, commitHash: string, agentId?: string): Promise<{
+        linked: boolean;
+        decision_summary: string;
+    }>;
+    /**
+     * Get decisions linked to a specific commit hash.
+     */
+    getByCommitHash(commitHash: string): Promise<{
+        decisions: Array<{
+            id: string;
+            summary: string;
+            domain: string;
+            scope: string;
+            confidence: string;
+            timestamp: string;
+            commit_hashes: string[];
+        }>;
+    }>;
+    /**
+     * Trace a decision's dependency chain upstream and/or downstream.
+     * Uses BFS with a visited set to prevent infinite loops from circular dependencies.
+     */
+    trace(decisionId: string, direction?: "upstream" | "downstream" | "both"): Promise<{
+        chain: TraceEntry[];
+    }>;
+    /**
+     * Flag a decision for reconsideration.
+     * Sets active decisions to provisional and posts a warning.
+     */
+    reconsider(decisionId: string, newContext: string, agentId?: string): Promise<{
+        flagged: boolean;
+        decision_summary: string;
+    }>;
+    /**
+     * Override a decision with a reason, optionally creating a replacement.
+     */
+    override(decisionId: string, reason: string, newDecision?: string, overriddenBy?: string): Promise<{
+        overridden: boolean;
+        old_summary: string;
+        new_decision_id?: string;
+    }>;
+    /**
+     * Search decisions across all scopes by keyword or semantic similarity.
+     * Supports filtering by domain, status, and confidence.
+     * Never throws — returns empty results on error.
+     */
+    searchDecisions(query: string, filters?: {
+        domain?: string;
+        status?: DecisionStatus;
+        confidence?: DecisionConfidence;
+    }, limit?: number): Promise<{
+        results: Array<{
+            id: string;
+            summary: string;
+            domain: string;
+            scope: string;
+            confidence: string;
+            status: string;
+            timestamp: string;
+            relevance: number;
+            commit_hashes: string[];
+        }>;
+        total_matched: number;
+        fallback_mode: boolean;
+    }>;
+}
+//# sourceMappingURL=decisions.d.ts.map

package/dist/engine/decisions.d.ts.map

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