@planu/cli 0.15.2

package/dist/tools/orchestrate-agents.js

@@ -0,0 +1,82 @@
+import { readJson, writeJson, projectDataDir } from '../storage/index.js';
+import { routeTask, generateHandoff, detectConflicts, decomposeSpec, } from '../engine/multi-agent/index.js';
+function registryPath(projectId) {
+    return `${projectDataDir(projectId)}/capability-registry.json`;
+}
+async function loadRegistry(projectId) {
+    return readJson(registryPath(projectId), []);
+}
+async function saveRegistry(projectId, registry) {
+    await writeJson(registryPath(projectId), registry);
+}
+function text(content) {
+    return { content: [{ type: 'text', text: JSON.stringify(content, null, 2) }] };
+}
+function err(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export async function handleOrchestrateAgents(args) {
+    const projectId = args.projectId ?? 'global';
+    switch (args.action) {
+        case 'register-agent': {
+            if (!args.agentId) {
+                return err('agentId is required for register-agent. Provide a unique agent identifier.');
+            }
+            const capability = {
+                agentId: args.agentId,
+                role: args.role ?? 'implementer',
+                ecosystems: args.ecosystems ?? [],
+                filePatterns: args.filePatterns ?? [],
+                maxConcurrency: args.maxConcurrency ?? 1,
+                preferredModel: args.preferredModel ?? 'sonnet',
+            };
+            const registry = await loadRegistry(projectId);
+            const idx = registry.findIndex((c) => c.agentId === args.agentId);
+            if (idx >= 0) {
+                registry[idx] = capability;
+            }
+            else {
+                registry.push(capability);
+            }
+            await saveRegistry(projectId, registry);
+            return text({
+                registered: true,
+                agentId: capability.agentId,
+                role: capability.role,
+                preferredModel: capability.preferredModel,
+                totalRegistered: registry.length,
+            });
+        }
+        case 'list-agents': {
+            const registry = await loadRegistry(projectId);
+            return text({ agents: registry, total: registry.length });
+        }
+        case 'route-task': {
+            if (!args.taskDescription) {
+                return err('taskDescription is required for route-task. Describe the task in natural language.');
+            }
+            const registry = await loadRegistry(projectId);
+            const route = routeTask(args.taskDescription, registry);
+            return text(route);
+        }
+        case 'decompose-spec': {
+            const criteria = args.specCriteria ?? [];
+            const agents = args.availableAgents ?? [];
+            const assignments = decomposeSpec(criteria, agents);
+            return text({ assignments, total: assignments.length });
+        }
+        case 'handoff': {
+            if (!args.sessionContext) {
+                return err('sessionContext is required for handoff. Provide fromAgent, toAgent, completedWork, decisions, fileOwnershipMap, and pendingWork.');
+            }
+            const handoff = generateHandoff(args.sessionContext);
+            return text(handoff);
+        }
+        case 'conflict-check': {
+            const plans = args.agentPlans ?? [];
+            const report = detectConflicts(plans);
+            return text(report);
+        }
+    }
+}
+//# sourceMappingURL=orchestrate-agents.js.map

package/dist/tools/orchestrate-agents.js.map

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

package/dist/tools/orchestrate-distribution.d.ts

@@ -0,0 +1,11 @@
+import type { AgentSession, AgentConflict, TaskAssignment, PreCheckResult, DecomposeResult, ToolResult, Spec } from '../types/index.js';
+export declare function buildDistribution(activeSessions: AgentSession[], allSpecs: Spec[]): {
+    assignments: TaskAssignment[];
+    conflicts: AgentConflict[];
+};
+export declare function buildPreCheck(specIds: string[]): Promise<PreCheckResult>;
+export declare function buildDecompose(specId: string, agentCount: number): Promise<DecomposeResult | string>;
+export declare function handleDistribute(activeSessions: AgentSession[], allSpecs: Spec[]): ToolResult;
+export declare function handlePreCheck(specIds: string[]): Promise<ToolResult>;
+export declare function handleDecompose(specId: string, agentCount?: number): Promise<ToolResult>;
+//# sourceMappingURL=orchestrate-distribution.d.ts.map

package/dist/tools/orchestrate-distribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-distribution.d.ts","sourceRoot":"","sources":["../../src/tools/orchestrate-distribution.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EAEd,cAAc,EACd,eAAe,EACf,UAAU,EACV,IAAI,EACL,MAAM,mBAAmB,CAAC;AAqB3B,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,YAAY,EAAE,EAC9B,QAAQ,EAAE,IAAI,EAAE,GACf;IAAE,WAAW,EAAE,cAAc,EAAE,CAAC;IAAC,SAAS,EAAE,aAAa,EAAE,CAAA;CAAE,CAmE/D;AA0CD,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CA4B9E;AAMD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,CA2BnC;AAgBD,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,UAAU,CAmB7F;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAM3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAMzF"}

package/dist/tools/orchestrate-distribution.js

@@ -0,0 +1,210 @@
+// tools/orchestrate-distribution.ts — Distribution, pre-check, decompose logic
+// Extracted from orchestrate.ts to keep each module under line budget.
+import { readdir, readFile } from 'node:fs/promises';
+// ---------------------------------------------------------------------------
+// Action: distribute
+// ---------------------------------------------------------------------------
+const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+function specPriority(spec) {
+    if (spec.risk === 'critical') {
+        return 'critical';
+    }
+    if (spec.risk === 'high' || spec.scope === 'architectural') {
+        return 'high';
+    }
+    if (spec.scope === 'trivial') {
+        return 'low';
+    }
+    return 'medium';
+}
+export function buildDistribution(activeSessions, allSpecs) {
+    const specMap = new Map(allSpecs.map((s) => [s.id, s]));
+    const assignableSpecs = allSpecs.filter((s) => s.status === 'approved' || s.status === 'draft' || s.status === 'implementing');
+    const alreadyAssigned = new Set(activeSessions.flatMap((s) => s.activeSpecs));
+    const assignments = assignableSpecs.map((spec) => {
+        const blockedByUnfinished = spec.dependencies.filter((depId) => {
+            const dep = specMap.get(depId);
+            return dep && dep.status !== 'done';
+        });
+        const isBlocked = blockedByUnfinished.length > 0;
+        const isAssigned = alreadyAssigned.has(spec.id);
+        const assignedSession = activeSessions.find((s) => s.activeSpecs.includes(spec.id));
+        return {
+            specId: spec.id,
+            assignedTo: assignedSession?.sessionId,
+            status: isBlocked ? 'blocked' : isAssigned ? 'in-progress' : 'available',
+            blockedBy: isBlocked ? blockedByUnfinished : undefined,
+            estimatedHours: spec.estimation.devHours,
+            priority: specPriority(spec),
+        };
+    });
+    assignments.sort((a, b) => {
+        if (a.status === 'blocked' && b.status !== 'blocked') {
+            return 1;
+        }
+        if (a.status !== 'blocked' && b.status === 'blocked') {
+            return -1;
+        }
+        return (PRIORITY_ORDER[a.priority] ?? 2) - (PRIORITY_ORDER[b.priority] ?? 2);
+    });
+    // Detect dependency conflicts between agents
+    const conflicts = [];
+    for (const spec of assignableSpecs) {
+        const workingSession = activeSessions.find((s) => s.activeSpecs.includes(spec.id));
+        if (!workingSession) {
+            continue;
+        }
+        for (const depId of spec.dependencies) {
+            const depSession = activeSessions.find((s) => s.activeSpecs.includes(depId));
+            if (!depSession || depSession.sessionId === workingSession.sessionId) {
+                continue;
+            }
+            const alreadyReported = conflicts.some((c) => c.agents.includes(workingSession.sessionId) &&
+                c.agents.includes(depSession.sessionId) &&
+                c.resource === spec.id);
+            if (!alreadyReported) {
+                conflicts.push({
+                    type: 'dependency-conflict',
+                    agents: [workingSession.sessionId, depSession.sessionId],
+                    resource: spec.id,
+                    resolution: `'${spec.id}' depends on '${depId}'. Coordinate between '${workingSession.sessionId}' and '${depSession.sessionId}'.`,
+                    severity: 'warning',
+                });
+            }
+        }
+    }
+    return { assignments, conflicts };
+}
+// ---------------------------------------------------------------------------
+// Action: pre-check (file overlap detection)
+// ---------------------------------------------------------------------------
+/** Attempt to find and read FICHA-TECNICA.md for a specId. */
+async function readFichaTecnica(specId) {
+    try {
+        const specsDir = 'docs/sdd/specs';
+        const entries = await readdir(specsDir);
+        const match = entries.find((e) => e.startsWith(specId));
+        /* v8 ignore next 3 — defensive: spec directory may not exist in all environments */
+        if (!match) {
+            return undefined;
+        }
+        return await readFile(`${specsDir}/${match}/FICHA-TECNICA.md`, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract file paths from a FICHA-TECNICA.md table (first backtick column). */
+function extractFilesFromFicha(content) {
+    const files = [];
+    const lineRegex = /^\s*\|[^|]*`([^`|\n]+)`/gm;
+    let match;
+    while ((match = lineRegex.exec(content)) !== null) {
+        const path = match[1] ?? '';
+        if (path.length > 0 &&
+            (path.startsWith('src/') ||
+                path.startsWith('tests/') ||
+                path.endsWith('.ts') ||
+                path.endsWith('.json'))) {
+            files.push(path);
+        }
+    }
+    return [...new Set(files)];
+}
+export async function buildPreCheck(specIds) {
+    const filesBySpec = new Map();
+    for (const specId of specIds) {
+        const content = await readFichaTecnica(specId);
+        filesBySpec.set(specId, content ? extractFilesFromFicha(content) : []);
+    }
+    // Find files that appear in more than one spec
+    const fileToSpecs = new Map();
+    for (const [specId, files] of filesBySpec) {
+        for (const file of files) {
+            const list = fileToSpecs.get(file) ?? [];
+            list.push(specId);
+            fileToSpecs.set(file, list);
+        }
+    }
+    const overlaps = [...fileToSpecs.entries()]
+        .filter(([, specs]) => specs.length > 1)
+        .map(([file, specs]) => ({ file, specs }));
+    const hasConflicts = overlaps.length > 0;
+    const recommendation = hasConflicts
+        ? `Conflicto detectado: ${overlaps.length} archivo(s) compartidos. Ejecutar secuencialmente o usar 'decompose' para paralelismo intra-spec.`
+        : 'Sin conflictos. Las specs pueden ejecutarse en paralelo.';
+    return { specs: specIds, overlaps, hasConflicts, recommendation };
+}
+// ---------------------------------------------------------------------------
+// Action: decompose (split spec into file-exclusive subtasks)
+// ---------------------------------------------------------------------------
+export async function buildDecompose(specId, agentCount) {
+    const content = await readFichaTecnica(specId);
+    if (!content) {
+        return `No se encontró FICHA-TECNICA.md para '${specId}'. Verifica que el specId es correcto.`;
+    }
+    const allFiles = extractFilesFromFicha(content);
+    if (allFiles.length === 0) {
+        return `No se encontraron archivos en FICHA-TECNICA.md de '${specId}'.`;
+    }
+    const n = Math.min(agentCount, allFiles.length);
+    const subtasks = Array.from({ length: n }, (_, i) => ({ index: i, files: [] }));
+    // Round-robin assignment guarantees exclusive ownership
+    allFiles.forEach((file, i) => {
+        const target = subtasks[i % n];
+        if (target) {
+            target.files.push(file);
+        }
+    });
+    return {
+        specId,
+        subtasks: subtasks.filter((t) => t.files.length > 0),
+        totalFiles: allFiles.length,
+    };
+}
+// ---------------------------------------------------------------------------
+// ToolResult wrappers
+// ---------------------------------------------------------------------------
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function err(msg) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: msg }, null, 2) }],
+        isError: true,
+    };
+}
+export function handleDistribute(activeSessions, allSpecs) {
+    if (activeSessions.length === 0) {
+        const result = {
+            action: 'distribute',
+            distribution: [],
+            message: 'No active agent sessions. Register agents first.',
+        };
+        return ok(result);
+    }
+    const { assignments, conflicts } = buildDistribution(activeSessions, allSpecs);
+    const result = {
+        action: 'distribute',
+        sessions: activeSessions,
+        distribution: assignments,
+        conflicts: conflicts.length > 0 ? conflicts : undefined,
+        message: `${assignments.length} task(s) across ${activeSessions.length} active agent(s)${conflicts.length > 0 ? `, ${conflicts.length} conflict(s) detected` : ''}`,
+    };
+    return ok(result);
+}
+export async function handlePreCheck(specIds) {
+    if (specIds.length === 0) {
+        return err('specIds must have at least one spec ID');
+    }
+    const result = await buildPreCheck(specIds);
+    return ok(result);
+}
+export async function handleDecompose(specId, agentCount = 2) {
+    const result = await buildDecompose(specId, agentCount);
+    if (typeof result === 'string') {
+        return err(result);
+    }
+    return ok(result);
+}
+//# sourceMappingURL=orchestrate-distribution.js.map

package/dist/tools/orchestrate-distribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-distribution.js","sourceRoot":"","sources":["../../src/tools/orchestrate-distribution.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,uEAAuE;AACvE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAYrD,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,cAAc,GAA2B,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AAE3F,SAAS,YAAY,CAAC,IAAU;IAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,KAAK,eAAe,EAAE,CAAC;QAC3D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,cAA8B,EAC9B,QAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CACrC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,KAAK,cAAc,CACtF,CAAC;IAEF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAEtF,MAAM,WAAW,GAAqB,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACjE,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC/B,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC;QACtC,CAAC,CAAC,CAAC;QACH,MAAM,SAAS,GAAG,mBAAmB,CAAC,MAAM,GAAG,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChD,MAAM,eAAe,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACpF,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,UAAU,EAAE,eAAe,EAAE,SAAS;YACtC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW;YACxE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,SAAS;YACtD,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ;YACxC,QAAQ,EAAE,YAAY,CAAC,IAAI,CAAC;SAC7B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACxB,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrD,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;QACD,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,CAAC,CAAC,CAAC;IAEH,6CAA6C;IAC7C,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACnF,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtC,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7E,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,SAAS,KAAK,cAAc,CAAC,SAAS,EAAE,CAAC;gBACrE,SAAS;YACX,CAAC;YACD,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,CACpC,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,SAAS,CAAC;gBAC3C,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC;gBACvC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,EAAE,CACzB,CAAC;YACF,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,SAAS,CAAC,IAAI,CAAC;oBACb,IAAI,EAAE,qBAAqB;oBAC3B,MAAM,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC;oBACxD,QAAQ,EAAE,IAAI,CAAC,EAAE;oBACjB,UAAU,EAAE,IAAI,IAAI,CAAC,EAAE,iBAAiB,KAAK,0BAA0B,cAAc,CAAC,SAAS,UAAU,UAAU,CAAC,SAAS,IAAI;oBACjI,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,6CAA6C;AAC7C,8EAA8E;AAE9E,8DAA8D;AAC9D,KAAK,UAAU,gBAAgB,CAAC,MAAc;IAC5C,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,gBAAgB,CAAC;QAClC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACxD,oFAAoF;QACpF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,QAAQ,CAAC,GAAG,QAAQ,IAAI,KAAK,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAG,2BAA2B,CAAC;IAC9C,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IACE,IAAI,CAAC,MAAM,GAAG,CAAC;YACf,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBACtB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;gBACzB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACpB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EACzB,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAiB;IACnD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEhD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC/C,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,+CAA+C;IAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;IAChD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;QAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAClB,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAE7C,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,MAAM,cAAc,GAAG,YAAY;QACjC,CAAC,CAAC,wBAAwB,QAAQ,CAAC,MAAM,mGAAmG;QAC5I,CAAC,CAAC,0DAA0D,CAAC;IAE/D,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AACpE,CAAC;AAED,8EAA8E;AAC9E,8DAA8D;AAC9D,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,UAAkB;IAElB,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,yCAAyC,MAAM,wCAAwC,CAAC;IACjG,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,sDAAsD,MAAM,IAAI,CAAC;IAC1E,CAAC;IAED,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,EAAc,EAAE,CAAC,CAAC,CAAC;IAE5F,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACpD,UAAU,EAAE,QAAQ,CAAC,MAAM;KAC5B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,SAAS,EAAE,CAAC,IAAa;IACvB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC;AACD,SAAS,GAAG,CAAC,GAAW;IACtB,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,cAA8B,EAAE,QAAgB;IAC/E,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,MAAM,GAAsB;YAChC,MAAM,EAAE,YAAY;YACpB,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,kDAAkD;SAC5D,CAAC;QACF,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,iBAAiB,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAsB;QAChC,MAAM,EAAE,YAAY;QACpB,QAAQ,EAAE,cAAc;QACxB,YAAY,EAAE,WAAW;QACzB,SAAS,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACvD,OAAO,EAAE,GAAG,WAAW,CAAC,MAAM,mBAAmB,cAAc,CAAC,MAAM,mBAAmB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,uBAAuB,CAAC,CAAC,CAAC,EAAE,EAAE;KACpK,CAAC;IACF,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAiB;IACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,wCAAwC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc,EAAE,UAAU,GAAG,CAAC;IAClE,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC"}

package/dist/tools/orchestrate-locking.d.ts

@@ -0,0 +1,35 @@
+import type { LockedResource, OrchestrationState, OrchestrateResult, ToolResult } from '../types/index.js';
+export declare const DEFAULT_LOCK_TTL_MS: number;
+export declare function isLockExpired(lock: LockedResource): boolean;
+export declare function pruneExpiredLocks(state: OrchestrationState): OrchestrationState;
+export declare function handleHeartbeatState(state: OrchestrationState, sessionId: string, lockTtlMinutes?: number): {
+    state: OrchestrationState;
+    result: OrchestrateResult;
+} | {
+    error: string;
+};
+export declare function handleLockState(state: OrchestrationState, sessionId: string, resourcePath?: string, specId?: string, lockTtlMinutes?: number, fileOwnership?: string[]): {
+    state: OrchestrationState;
+    result: OrchestrateResult;
+} | {
+    error: string;
+};
+export declare function handleUnlockState(state: OrchestrationState, sessionId: string, resourcePath?: string, specId?: string): {
+    state: OrchestrationState;
+    result: OrchestrateResult;
+} | {
+    error: string;
+};
+export declare function toHeartbeatResult(sessionId: string | undefined, state: OrchestrationState, lockTtlMinutes?: number): {
+    mutated: OrchestrationState | null;
+    toolResult: ToolResult;
+};
+export declare function toLockResult(sessionId: string | undefined, state: OrchestrationState, resourcePath?: string, specId?: string, lockTtlMinutes?: number, fileOwnership?: string[]): {
+    mutated: OrchestrationState | null;
+    toolResult: ToolResult;
+};
+export declare function toUnlockResult(sessionId: string | undefined, state: OrchestrationState, resourcePath?: string, specId?: string): {
+    mutated: OrchestrationState | null;
+    toolResult: ToolResult;
+};
+//# sourceMappingURL=orchestrate-locking.d.ts.map

package/dist/tools/orchestrate-locking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-locking.d.ts","sourceRoot":"","sources":["../../src/tools/orchestrate-locking.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAMlD,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAK3D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,kBAAkB,CAM/E;AA2BD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAyB9E;AAMD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAuE9E;AAMD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,kBAAkB,EACzB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA6B9E;AAaD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,kBAAkB,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB;IAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAYhE;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,kBAAkB,EACzB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB;IAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAmBhE;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,kBAAkB,EACzB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAYhE"}

package/dist/tools/orchestrate-locking.js

@@ -0,0 +1,202 @@
+export const DEFAULT_LOCK_TTL_MS = 30 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+export function isLockExpired(lock) {
+    if (!lock.expiresAt) {
+        return false;
+    }
+    return new Date(lock.expiresAt) < new Date();
+}
+export function pruneExpiredLocks(state) {
+    const activeLocks = state.locks.filter((l) => !isLockExpired(l));
+    for (const session of state.sessions) {
+        session.lockedResources = session.lockedResources.filter((lr) => !isLockExpired(lr));
+    }
+    return { ...state, locks: activeLocks };
+}
+function lockTtlMs(lockTtlMinutes) {
+    return lockTtlMinutes ? lockTtlMinutes * 60 * 1000 : DEFAULT_LOCK_TTL_MS;
+}
+function resourceType(resourcePath, specId, resourceId) {
+    if (specId && resourceId === specId) {
+        return 'spec';
+    }
+    if (resourcePath?.endsWith('.json') || resourcePath?.includes('config')) {
+        return 'config';
+    }
+    if (resourcePath?.includes('knowledge')) {
+        return 'knowledge';
+    }
+    return 'file';
+}
+// ---------------------------------------------------------------------------
+// Action: heartbeat
+// ---------------------------------------------------------------------------
+export function handleHeartbeatState(state, sessionId, lockTtlMinutes) {
+    const session = state.sessions.find((s) => s.sessionId === sessionId);
+    if (!session) {
+        return { error: `Session '${sessionId}' not found. Register first.` };
+    }
+    const now = new Date().toISOString();
+    session.lastActivity = now;
+    session.status = 'active';
+    // Auto-renew locks held by this session
+    const ttl = lockTtlMs(lockTtlMinutes);
+    for (const lock of state.locks) {
+        if (lock.lockedBy === sessionId) {
+            lock.expiresAt = new Date(Date.now() + ttl).toISOString();
+        }
+    }
+    return {
+        state,
+        result: {
+            action: 'heartbeat',
+            sessionId,
+            message: `Heartbeat received for session '${sessionId}'`,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Action: lock
+// ---------------------------------------------------------------------------
+export function handleLockState(state, sessionId, resourcePath, specId, lockTtlMinutes, fileOwnership) {
+    const resourceId = resourcePath ?? specId;
+    if (!resourceId) {
+        return { error: 'resourcePath or specId is required for lock action' };
+    }
+    const session = state.sessions.find((s) => s.sessionId === sessionId);
+    if (!session) {
+        return { error: `Session '${sessionId}' not found. Register first.` };
+    }
+    const existingLock = state.locks.find((l) => l.resourceId === resourceId && !isLockExpired(l));
+    if (existingLock && existingLock.lockedBy !== sessionId) {
+        return {
+            state,
+            result: {
+                action: 'lock',
+                sessionId,
+                granted: false,
+                message: `Resource '${resourceId}' is already locked by '${existingLock.lockedBy}' until ${existingLock.expiresAt ?? 'indefinitely'}`,
+            },
+        };
+    }
+    const ttl = lockTtlMs(lockTtlMinutes);
+    if (existingLock?.lockedBy === sessionId) {
+        const expiresAt = new Date(Date.now() + ttl).toISOString();
+        existingLock.expiresAt = expiresAt;
+        return {
+            state,
+            result: {
+                action: 'lock',
+                sessionId,
+                granted: true,
+                message: `Lock on '${resourceId}' extended until ${expiresAt}`,
+            },
+        };
+    }
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttl).toISOString();
+    const type = resourceType(resourcePath, specId, resourceId);
+    const lock = {
+        type,
+        resourceId,
+        lockedBy: sessionId,
+        lockedAt: now.toISOString(),
+        reason: `Locked by session '${sessionId}'`,
+        expiresAt,
+    };
+    state.locks.push(lock);
+    session.lockedResources.push(lock);
+    session.lastActivity = now.toISOString();
+    // Update fileOwnership if provided
+    if (fileOwnership?.length) {
+        session.fileOwnership = [...(session.fileOwnership ?? []), ...fileOwnership];
+    }
+    return {
+        state,
+        result: {
+            action: 'lock',
+            sessionId,
+            granted: true,
+            message: `Resource '${resourceId}' locked by '${sessionId}' until ${expiresAt}`,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Action: unlock
+// ---------------------------------------------------------------------------
+export function handleUnlockState(state, sessionId, resourcePath, specId) {
+    const resourceId = resourcePath ?? specId;
+    if (!resourceId) {
+        return { error: 'resourcePath or specId is required for unlock action' };
+    }
+    const lockIdx = state.locks.findIndex((l) => l.resourceId === resourceId && l.lockedBy === sessionId);
+    if (lockIdx === -1) {
+        return { error: `No lock on '${resourceId}' held by '${sessionId}'` };
+    }
+    state.locks.splice(lockIdx, 1);
+    const session = state.sessions.find((s) => s.sessionId === sessionId);
+    if (session) {
+        session.lockedResources = session.lockedResources.filter((lr) => lr.resourceId !== resourceId);
+        session.lastActivity = new Date().toISOString();
+    }
+    return {
+        state,
+        result: {
+            action: 'unlock',
+            sessionId,
+            granted: true,
+            message: `Resource '${resourceId}' unlocked by '${sessionId}'`,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Wrappers that turn errors into ToolResult
+// ---------------------------------------------------------------------------
+function errResult(msg) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: msg }, null, 2) }],
+        isError: true,
+    };
+}
+export function toHeartbeatResult(sessionId, state, lockTtlMinutes) {
+    if (!sessionId) {
+        return { mutated: null, toolResult: errResult('sessionId is required for heartbeat action') };
+    }
+    const out = handleHeartbeatState(state, sessionId, lockTtlMinutes);
+    if ('error' in out) {
+        return { mutated: null, toolResult: errResult(out.error) };
+    }
+    return {
+        mutated: out.state,
+        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+    };
+}
+export function toLockResult(sessionId, state, resourcePath, specId, lockTtlMinutes, fileOwnership) {
+    if (!sessionId) {
+        return { mutated: null, toolResult: errResult('sessionId is required for lock action') };
+    }
+    const out = handleLockState(state, sessionId, resourcePath, specId, lockTtlMinutes, fileOwnership);
+    if ('error' in out) {
+        return { mutated: null, toolResult: errResult(out.error) };
+    }
+    return {
+        mutated: out.state,
+        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+    };
+}
+export function toUnlockResult(sessionId, state, resourcePath, specId) {
+    if (!sessionId) {
+        return { mutated: null, toolResult: errResult('sessionId is required for unlock action') };
+    }
+    const out = handleUnlockState(state, sessionId, resourcePath, specId);
+    if ('error' in out) {
+        return { mutated: null, toolResult: errResult(out.error) };
+    }
+    return {
+        mutated: out.state,
+        toolResult: { content: [{ type: 'text', text: JSON.stringify(out.result, null, 2) }] },
+    };
+}
+//# sourceMappingURL=orchestrate-locking.js.map

package/dist/tools/orchestrate-locking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate-locking.js","sourceRoot":"","sources":["../../src/tools/orchestrate-locking.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAElD,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,UAAU,aAAa,CAAC,IAAoB;IAChD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrC,OAAO,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;AAC1C,CAAC;AAED,SAAS,SAAS,CAAC,cAAuB;IACxC,OAAO,cAAc,CAAC,CAAC,CAAC,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC;AAC3E,CAAC;AAED,SAAS,YAAY,CACnB,YAAqB,EACrB,MAAe,EACf,UAAmB;IAEnB,IAAI,MAAM,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACxC,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,UAAU,oBAAoB,CAClC,KAAyB,EACzB,SAAiB,EACjB,cAAuB;IAEvB,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,YAAY,SAAS,8BAA8B,EAAE,CAAC;IACxE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC;IAC3B,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC;IAE1B,wCAAwC;IACxC,MAAM,GAAG,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM,EAAE;YACN,MAAM,EAAE,WAAW;YACnB,SAAS;YACT,OAAO,EAAE,mCAAmC,SAAS,GAAG;SACzD;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,UAAU,eAAe,CAC7B,KAAyB,EACzB,SAAiB,EACjB,YAAqB,EACrB,MAAe,EACf,cAAuB,EACvB,aAAwB;IAExB,MAAM,UAAU,GAAG,YAAY,IAAI,MAAM,CAAC;IAC1C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,YAAY,SAAS,8BAA8B,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/F,IAAI,YAAY,IAAI,YAAY,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACxD,OAAO;YACL,KAAK;YACL,MAAM,EAAE;gBACN,MAAM,EAAE,MAAM;gBACd,SAAS;gBACT,OAAO,EAAE,KAAK;gBACd,OAAO,EAAE,aAAa,UAAU,2BAA2B,YAAY,CAAC,QAAQ,WAAW,YAAY,CAAC,SAAS,IAAI,cAAc,EAAE;aACtI;SACF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;IACtC,IAAI,YAAY,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3D,YAAY,CAAC,SAAS,GAAG,SAAS,CAAC;QACnC,OAAO;YACL,KAAK;YACL,MAAM,EAAE;gBACN,MAAM,EAAE,MAAM;gBACd,SAAS;gBACT,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,YAAY,UAAU,oBAAoB,SAAS,EAAE;aAC/D;SACF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAE5D,MAAM,IAAI,GAAmB;QAC3B,IAAI;QACJ,UAAU;QACV,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE;QAC3B,MAAM,EAAE,sBAAsB,SAAS,GAAG;QAC1C,SAAS;KACV,CAAC;IAEF,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,YAAY,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAEzC,mCAAmC;IACnC,IAAI,aAAa,EAAE,MAAM,EAAE,CAAC;QAC1B,OAAO,CAAC,aAAa,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM,EAAE;YACN,MAAM,EAAE,MAAM;YACd,SAAS;YACT,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,aAAa,UAAU,gBAAgB,SAAS,WAAW,SAAS,EAAE;SAChF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,iBAAiB,CAC/B,KAAyB,EACzB,SAAiB,EACjB,YAAqB,EACrB,MAAe;IAEf,MAAM,UAAU,GAAG,YAAY,IAAI,MAAM,CAAC;IAC1C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,KAAK,EAAE,sDAAsD,EAAE,CAAC;IAC3E,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CACnC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,CAC/D,CAAC;IACF,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,eAAe,UAAU,cAAc,SAAS,GAAG,EAAE,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACtE,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;QAC/F,OAAO,CAAC,YAAY,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClD,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM,EAAE;YACN,MAAM,EAAE,QAAQ;YAChB,SAAS;YACT,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,aAAa,UAAU,kBAAkB,SAAS,GAAG;SAC/D;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAE9E,SAAS,SAAS,CAAC,GAAW;IAC5B,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAA6B,EAC7B,KAAyB,EACzB,cAAuB;IAEvB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,4CAA4C,CAAC,EAAE,CAAC;IAChG,CAAC;IACD,MAAM,GAAG,GAAG,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IACnE,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,KAAK;QAClB,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;KACvF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,SAA6B,EAC7B,KAAyB,EACzB,YAAqB,EACrB,MAAe,EACf,cAAuB,EACvB,aAAwB;IAExB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,uCAAuC,CAAC,EAAE,CAAC;IAC3F,CAAC;IACD,MAAM,GAAG,GAAG,eAAe,CACzB,KAAK,EACL,SAAS,EACT,YAAY,EACZ,MAAM,EACN,cAAc,EACd,aAAa,CACd,CAAC;IACF,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,KAAK;QAClB,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;KACvF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,SAA6B,EAC7B,KAAyB,EACzB,YAAqB,EACrB,MAAe;IAEf,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,yCAAyC,CAAC,EAAE,CAAC;IAC7F,CAAC;IACD,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACtE,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,KAAK;QAClB,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE;KACvF,CAAC;AACJ,CAAC"}

package/dist/tools/orchestrate.d.ts

@@ -0,0 +1,3 @@
+import type { OrchestrateInput, ToolResult } from '../types/index.js';
+export declare function handleOrchestrate(params: OrchestrateInput): Promise<ToolResult>;
+//# sourceMappingURL=orchestrate.d.ts.map

package/dist/tools/orchestrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../src/tools/orchestrate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkBtE,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAwGrF"}