@versatly/workgraph 1.1.0 → 1.3.0

package/dist/cli.js

@@ -11,9 +11,10 @@ import {
   onboard_exports,
   search_qmd_adapter_exports,
   skill_exports,
+  swarm_exports,
   trigger_exports,
   workspace_exports
-} from "./chunk-TOFSHG5S.js";
+} from "./chunk-NGRQ6T4O.js";
 import {
   autonomy_exports,
   dispatch_exports,
@@ -29,7 +30,7 @@ import {
   thread_audit_exports,
   thread_exports,
   trigger_engine_exports
-} from "./chunk-OTSECVE5.js";
+} from "./chunk-BJVBE7F4.js";
 
 // src/cli.ts
 import fs from "fs";
@@ -1898,6 +1899,85 @@ addWorkspaceOption(
     readOnly: !!opts.readOnly
   });
 });
+var swarmCmd = program.command("swarm").description("Decompose goals into tasks and orchestrate agent swarms");
+addWorkspaceOption(
+  swarmCmd.command("deploy <planFile>").description("Deploy a swarm plan (JSON) into the workspace as threads").option("-a, --actor <name>", "Actor name", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+).action(
+  (planFile, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const planPath = path.resolve(planFile);
+      const planData = JSON.parse(fs.readFileSync(planPath, "utf-8"));
+      return swarm_exports.deployPlan(workspacePath, planData, opts.actor);
+    },
+    (result) => [
+      `Swarm deployed: ${result.spaceSlug}`,
+      `Threads: ${result.threadPaths.length}`,
+      `Status: ${result.status}`
+    ]
+  )
+);
+addWorkspaceOption(
+  swarmCmd.command("status <spaceSlug>").description("Show swarm progress").option("--json", "Emit structured JSON output")
+).action(
+  (spaceSlug, opts) => runCommand(
+    opts,
+    () => swarm_exports.getSwarmStatus(resolveWorkspacePath(opts), spaceSlug),
+    (result) => [
+      `Swarm: ${result.deployment.spaceSlug} [${result.deployment.status}]`,
+      `Progress: ${result.done}/${result.total} (${result.percentComplete}%)`,
+      `Claimed: ${result.claimed} | Open: ${result.open} | Blocked: ${result.blocked}`,
+      `Ready to claim: ${result.readyToClaim}`
+    ]
+  )
+);
+addWorkspaceOption(
+  swarmCmd.command("claim <spaceSlug>").description("Claim the next available task in a swarm").option("-a, --actor <name>", "Worker agent name", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+).action(
+  (spaceSlug, opts) => runCommand(
+    opts,
+    () => {
+      const result = swarm_exports.workerClaim(resolveWorkspacePath(opts), spaceSlug, opts.actor);
+      if (!result) return { claimed: false, message: "No tasks available" };
+      return { claimed: true, path: result.path, title: result.fields.title };
+    },
+    (result) => result.claimed ? [`Claimed: ${result.path} \u2014 ${result.title}`] : ["No tasks available to claim"]
+  )
+);
+addWorkspaceOption(
+  swarmCmd.command("complete <threadPath>").description("Mark a swarm task as done with result").option("-a, --actor <name>", "Worker agent name", DEFAULT_ACTOR).requiredOption("--result <text>", "Result text (or @file to read from file)").option("--json", "Emit structured JSON output")
+).action(
+  (threadPath, opts) => runCommand(
+    opts,
+    () => {
+      let resultText = opts.result;
+      if (resultText.startsWith("@")) {
+        resultText = fs.readFileSync(resultText.slice(1), "utf-8");
+      }
+      return swarm_exports.workerComplete(resolveWorkspacePath(opts), threadPath, opts.actor, resultText);
+    },
+    (result) => [`Completed: ${result.path}`]
+  )
+);
+addWorkspaceOption(
+  swarmCmd.command("synthesize <spaceSlug>").description("Merge all completed task results into a single document").option("-o, --output <file>", "Output file path").option("--json", "Emit structured JSON output")
+).action(
+  (spaceSlug, opts) => runCommand(
+    opts,
+    () => {
+      const result = swarm_exports.synthesize(resolveWorkspacePath(opts), spaceSlug);
+      if (opts.output) {
+        fs.writeFileSync(path.resolve(opts.output), result.markdown);
+      }
+      return result;
+    },
+    (result) => [
+      `Synthesized: ${result.completedCount}/${result.totalCount} tasks`,
+      opts.output ? `Written to: ${opts.output}` : result.markdown
+    ]
+  )
+);
 await program.parseAsync();
 function addWorkspaceOption(command) {
   return command.option("-w, --workspace <path>", "Workgraph workspace path").option("--vault <path>", "Alias for --workspace").option("--shared-vault <path>", "Shared vault path (e.g. mounted via Tailscale)").option("--dry-run", "Execute against a temporary workspace copy and discard changes");

package/dist/index.d.ts

@@ -614,11 +614,11 @@ interface WriteSkillOptions {
     version?: string;
     status?: 'draft' | 'proposed' | 'active' | 'deprecated' | 'archived';
     distribution?: string;
-    tailscalePath?: string;
     reviewers?: string[];
     tags?: string[];
     dependsOn?: string[];
     expectedUpdatedAt?: string;
+    tailscalePath?: string;
 }
 interface ProposeSkillOptions {
     proposalThread?: string;
@@ -1448,6 +1448,144 @@ declare function parseCronExpression(expression: string): CronSchedule;
 declare function matchesCronSchedule(schedule: CronSchedule, date: Date): boolean;
 declare function nextCronMatch(scheduleOrExpression: CronSchedule | string, after: Date, maxSearchMinutes?: number): Date | null;
 
+/**
+ * WorkGraph Swarm — Decompose goals into hundreds of tasks,
+ * spawn agent containers to claim and complete them, merge results.
+ *
+ * Architecture:
+ *   1. Planner: Takes a goal → decomposes into N threads with dependencies
+ *   2. Orchestrator: Spawns containers, each runs a worker that claims threads
+ *   3. Worker: Claims a thread, does work, writes result, marks done
+ *   4. Synthesizer: Watches for completion, merges results
+ */
+
+interface SwarmGoal {
+    title: string;
+    description: string;
+    outputFormat?: 'markdown' | 'json' | 'code';
+    maxTasks?: number;
+    maxConcurrent?: number;
+    tags?: string[];
+}
+interface SwarmTask {
+    title: string;
+    description: string;
+    priority: 'critical' | 'high' | 'medium' | 'low';
+    dependsOn?: string[];
+    estimatedMinutes?: number;
+    outputType?: string;
+    tags?: string[];
+}
+interface SwarmPlan {
+    goal: SwarmGoal;
+    tasks: SwarmTask[];
+    phases: SwarmPhase[];
+    createdAt: string;
+    estimatedTotalMinutes: number;
+}
+interface SwarmPhase {
+    name: string;
+    description: string;
+    taskIndices: number[];
+    parallel: boolean;
+}
+interface SwarmDeployment {
+    planPath: string;
+    workspacePath: string;
+    threadPaths: string[];
+    spaceSlug: string;
+    createdAt: string;
+    status: 'deployed' | 'running' | 'completing' | 'done' | 'failed';
+}
+interface SwarmStatus {
+    deployment: SwarmDeployment;
+    total: number;
+    claimed: number;
+    done: number;
+    blocked: number;
+    open: number;
+    readyToClaim: number;
+    percentComplete: number;
+    threads: Array<{
+        path: string;
+        title: string;
+        status: string;
+        owner?: string;
+        priority: string;
+    }>;
+}
+/**
+ * Generate a swarm plan from a goal description.
+ * This creates the plan structure — call deployPlan() to create actual threads.
+ *
+ * In production, pipe goal through an LLM for decomposition.
+ * This function provides the structured output format the LLM should produce.
+ */
+declare function createPlanTemplate(goal: SwarmGoal): SwarmPlan;
+/**
+ * Validate a swarm plan for internal consistency.
+ */
+declare function validatePlan(plan: SwarmPlan): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Deploy a swarm plan into a WorkGraph workspace.
+ * Creates a space for the swarm and threads for each task.
+ * Dependencies are encoded as wiki-links in thread bodies.
+ */
+declare function deployPlan(workspacePath: string, plan: SwarmPlan, actor: string): SwarmDeployment;
+/**
+ * Get the current status of a swarm deployment.
+ */
+declare function getSwarmStatus(workspacePath: string, spaceSlug: string): SwarmStatus;
+/**
+ * Worker claims the next available task in a swarm.
+ * Returns the thread to work on, or null if nothing available.
+ */
+declare function workerClaim(workspacePath: string, spaceSlug: string, agent: string): PrimitiveInstance | null;
+/**
+ * Worker completes a task, writing result to the thread body.
+ */
+declare function workerComplete(workspacePath: string, threadPath: string, agent: string, result: string): PrimitiveInstance;
+/**
+ * Worker loop: claim → work → complete → repeat until no tasks left.
+ * The workFn receives the thread and returns the result string.
+ */
+declare function workerLoop(workspacePath: string, spaceSlug: string, agent: string, workFn: (thread: PrimitiveInstance) => Promise<string>, options?: {
+    maxTasks?: number;
+    delayMs?: number;
+}): Promise<{
+    completed: number;
+    errors: number;
+}>;
+/**
+ * Collect all completed task results from a swarm into a single document.
+ */
+declare function synthesize(workspacePath: string, spaceSlug: string): {
+    markdown: string;
+    completedCount: number;
+    totalCount: number;
+};
+
+type swarm_SwarmDeployment = SwarmDeployment;
+type swarm_SwarmGoal = SwarmGoal;
+type swarm_SwarmPhase = SwarmPhase;
+type swarm_SwarmPlan = SwarmPlan;
+type swarm_SwarmStatus = SwarmStatus;
+type swarm_SwarmTask = SwarmTask;
+declare const swarm_createPlanTemplate: typeof createPlanTemplate;
+declare const swarm_deployPlan: typeof deployPlan;
+declare const swarm_getSwarmStatus: typeof getSwarmStatus;
+declare const swarm_synthesize: typeof synthesize;
+declare const swarm_validatePlan: typeof validatePlan;
+declare const swarm_workerClaim: typeof workerClaim;
+declare const swarm_workerComplete: typeof workerComplete;
+declare const swarm_workerLoop: typeof workerLoop;
+declare namespace swarm {
+  export { type swarm_SwarmDeployment as SwarmDeployment, type swarm_SwarmGoal as SwarmGoal, type swarm_SwarmPhase as SwarmPhase, type swarm_SwarmPlan as SwarmPlan, type swarm_SwarmStatus as SwarmStatus, type swarm_SwarmTask as SwarmTask, swarm_createPlanTemplate as createPlanTemplate, swarm_deployPlan as deployPlan, swarm_getSwarmStatus as getSwarmStatus, swarm_synthesize as synthesize, swarm_validatePlan as validatePlan, swarm_workerClaim as workerClaim, swarm_workerComplete as workerComplete, swarm_workerLoop as workerLoop };
+}
+
 type DoctorSeverity = 'warning' | 'error';
 interface DoctorIssue {
     code: string;
@@ -1780,4 +1918,4 @@ declare class CursorCloudAdapter implements DispatchAdapter {
     execute(input: DispatchAdapterExecutionInput): Promise<DispatchAdapterExecutionResult>;
 }
 
-export { type CronField, type CronSchedule, CursorCloudAdapter, type DispatchAdapter, type DispatchAdapterCreateInput, type DispatchAdapterExecutionInput, type DispatchAdapterExecutionResult, type DispatchAdapterLogEntry, type DispatchAdapterRunStatus, type DispatchRun, type FieldDefinition, type InstallSkillIntegrationOptions, type InstallSkillIntegrationResult, type LedgerChainState, type LedgerEntry, type LedgerIndex, type LedgerOp, type PolicyParty, type PolicyRegistry, type PrimitiveInstance, type PrimitiveQueryFilters, type PrimitiveTypeDefinition, type Registry, type RunStatus, type SkillIntegrationProvider, THREAD_STATUS_TRANSITIONS, type ThreadStatus, type WorkgraphBrief, type WorkgraphLensDescriptor, type WorkgraphLensId, type WorkgraphLensItem, type WorkgraphLensOptions, type WorkgraphLensResult, type WorkgraphLensSection, type WorkgraphMaterializeLensOptions, type WorkgraphMaterializedLensResult, type WorkgraphStatusSnapshot, type WorkgraphWorkspaceConfig, agent, autonomy, autonomyDaemon, bases, board, claimLease, clawdapus, commandCenter, index as diagnostics, dispatch, fetchSkillMarkdownFromUrl, gate, graph, installSkillIntegration, integration, ledger, lens, matchesCronSchedule, nextCronMatch, onboard, orientation, parseCronExpression, policy, query, registry, searchQmdAdapter, skill, store, thread, threadAudit, trigger, triggerEngine, workspace };
+export { type CronField, type CronSchedule, CursorCloudAdapter, type DispatchAdapter, type DispatchAdapterCreateInput, type DispatchAdapterExecutionInput, type DispatchAdapterExecutionResult, type DispatchAdapterLogEntry, type DispatchAdapterRunStatus, type DispatchRun, type FieldDefinition, type InstallSkillIntegrationOptions, type InstallSkillIntegrationResult, type LedgerChainState, type LedgerEntry, type LedgerIndex, type LedgerOp, type PolicyParty, type PolicyRegistry, type PrimitiveInstance, type PrimitiveQueryFilters, type PrimitiveTypeDefinition, type Registry, type RunStatus, type SkillIntegrationProvider, THREAD_STATUS_TRANSITIONS, type ThreadStatus, type WorkgraphBrief, type WorkgraphLensDescriptor, type WorkgraphLensId, type WorkgraphLensItem, type WorkgraphLensOptions, type WorkgraphLensResult, type WorkgraphLensSection, type WorkgraphMaterializeLensOptions, type WorkgraphMaterializedLensResult, type WorkgraphStatusSnapshot, type WorkgraphWorkspaceConfig, agent, autonomy, autonomyDaemon, bases, board, claimLease, clawdapus, commandCenter, index as diagnostics, dispatch, fetchSkillMarkdownFromUrl, gate, graph, installSkillIntegration, integration, ledger, lens, matchesCronSchedule, nextCronMatch, onboard, orientation, parseCronExpression, policy, query, registry, searchQmdAdapter, skill, store, swarm, thread, threadAudit, trigger, triggerEngine, workspace };

package/dist/index.js

@@ -13,9 +13,10 @@ import {
   onboard_exports,
   search_qmd_adapter_exports,
   skill_exports,
+  swarm_exports,
   trigger_exports,
   workspace_exports
-} from "./chunk-TOFSHG5S.js";
+} from "./chunk-NGRQ6T4O.js";
 import {
   CursorCloudAdapter,
   THREAD_STATUS_TRANSITIONS,
@@ -37,7 +38,7 @@ import {
   thread_audit_exports,
   thread_exports,
   trigger_engine_exports
-} from "./chunk-OTSECVE5.js";
+} from "./chunk-BJVBE7F4.js";
 export {
   CursorCloudAdapter,
   THREAD_STATUS_TRANSITIONS,
@@ -70,6 +71,7 @@ export {
   search_qmd_adapter_exports as searchQmdAdapter,
   skill_exports as skill,
   store_exports as store,
+  swarm_exports as swarm,
   thread_exports as thread,
   thread_audit_exports as threadAudit,
   trigger_exports as trigger,

package/dist/mcp-server.js

@@ -1,7 +1,7 @@
 import {
   createWorkgraphMcpServer,
   startWorkgraphMcpServer
-} from "./chunk-OTSECVE5.js";
+} from "./chunk-BJVBE7F4.js";
 export {
   createWorkgraphMcpServer,
   startWorkgraphMcpServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatly/workgraph",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Agent-first workgraph workspace for multi-agent coordination with dynamic primitives, append-only ledger, and markdown-native storage.",
   "workspaces": [
     "packages/*"