@versatly/workgraph 1.0.0 → 1.2.0

package/dist/cli.js

@@ -7,12 +7,14 @@ import {
   command_center_exports,
   diagnostics_exports,
   integration_exports,
+  lens_exports,
   onboard_exports,
   search_qmd_adapter_exports,
   skill_exports,
+  swarm_exports,
   trigger_exports,
   workspace_exports
-} from "./chunk-OJ6KOGB2.js";
+} from "./chunk-MCHTUXG2.js";
 import {
   autonomy_exports,
   dispatch_exports,
@@ -28,7 +30,7 @@ import {
   thread_audit_exports,
   thread_exports,
   trigger_engine_exports
-} from "./chunk-R2MLGBHB.js";
+} from "./chunk-G6B47IBD.js";
 
 // src/cli.ts
 import fs from "fs";
@@ -1053,6 +1055,57 @@ addWorkspaceOption(
     (result) => [`Captured intake: ${result.intake.path}`]
   )
 );
+var lensCmd = program.command("lens").description("Generate deterministic context lenses for situational awareness");
+addWorkspaceOption(
+  lensCmd.command("list").description("List built-in context lenses").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => ({
+      lenses: lens_exports.listContextLenses()
+    }),
+    (result) => result.lenses.map((lens) => `lens://${lens.id} - ${lens.description}`)
+  )
+);
+addWorkspaceOption(
+  lensCmd.command("show <lensId>").description("Generate one context lens snapshot").option("-a, --actor <name>", "Actor identity for actor-scoped lenses", DEFAULT_ACTOR).option("--lookback-hours <hours>", "Lookback window in hours", "24").option("--stale-hours <hours>", "Stale threshold in hours", "24").option("--limit <n>", "Maximum items per section", "10").option("-o, --output <path>", "Write lens markdown to workspace-relative output path").option("--json", "Emit structured JSON output")
+).action(
+  (lensId, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const lensOptions = {
+        actor: opts.actor,
+        lookbackHours: parsePositiveNumberOption(opts.lookbackHours, "lookback-hours"),
+        staleHours: parsePositiveNumberOption(opts.staleHours, "stale-hours"),
+        limit: parsePositiveIntegerOption(opts.limit, "limit")
+      };
+      if (opts.output) {
+        return lens_exports.materializeContextLens(workspacePath, lensId, {
+          ...lensOptions,
+          outputPath: opts.output
+        });
+      }
+      return lens_exports.generateContextLens(workspacePath, lensId, lensOptions);
+    },
+    (result) => {
+      const metricSummary = Object.entries(result.metrics).map(([metric, value]) => `${metric}=${value}`).join(" ");
+      const sectionSummary = result.sections.map((section) => `${section.id}:${section.items.length}`).join(" ");
+      const lines = [
+        `Lens: ${result.lens}`,
+        `Generated: ${result.generatedAt}`,
+        ...result.actor ? [`Actor: ${result.actor}`] : [],
+        `Metrics: ${metricSummary || "none"}`,
+        `Sections: ${sectionSummary || "none"}`
+      ];
+      if (isMaterializedLensResult(result)) {
+        lines.push(`Saved markdown: ${result.outputPath}`);
+        return lines;
+      }
+      return [...lines, "", ...result.markdown.split("\n")];
+    }
+  )
+);
 addWorkspaceOption(
   program.command("query").description("Query primitive instances with multi-field filters").option("--type <type>", "Primitive type").option("--status <status>", "Status value").option("--owner <owner>", "Owner/actor value").option("--tag <tag>", "Tag filter").option("--text <text>", "Full-text contains filter").option("--path-includes <text>", "Path substring filter").option("--updated-after <iso>", "Updated at or after").option("--updated-before <iso>", "Updated at or before").option("--created-after <iso>", "Created at or after").option("--created-before <iso>", "Created at or before").option("--limit <n>", "Result limit").option("--offset <n>", "Result offset").option("--json", "Emit structured JSON output")
 ).action(
@@ -1846,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");
@@ -1952,6 +2084,13 @@ function parsePositiveIntOption(value, name) {
   }
   return parsed;
 }
+function parsePositiveNumberOption(value, optionName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${optionName}. Expected a positive number.`);
+  }
+  return parsed;
+}
 function parseNonNegativeIntOption(value, name) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
   if (!Number.isFinite(parsed) || parsed < 0) {
@@ -1959,6 +2098,16 @@ function parseNonNegativeIntOption(value, name) {
   }
   return parsed;
 }
+function parsePositiveIntegerOption(value, optionName) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${optionName}. Expected a positive integer.`);
+  }
+  return parsed;
+}
+function isMaterializedLensResult(value) {
+  return typeof value.outputPath === "string";
+}
 function normalizeRunStatus(status) {
   const normalized = String(status).toLowerCase();
   if (normalized === "running" || normalized === "succeeded" || normalized === "failed" || normalized === "cancelled") {

package/dist/index.d.ts

@@ -132,6 +132,51 @@ interface WorkgraphBrief {
     nextReadyThreads: PrimitiveInstance[];
     recentActivity: LedgerEntry[];
 }
+type WorkgraphLensId = 'my-work' | 'team-risk' | 'customer-health' | 'exec-brief';
+interface WorkgraphLensDescriptor {
+    id: WorkgraphLensId;
+    description: string;
+}
+interface WorkgraphLensOptions {
+    actor?: string;
+    lookbackHours?: number;
+    staleHours?: number;
+    limit?: number;
+}
+interface WorkgraphLensItem {
+    title: string;
+    path?: string;
+    status?: string;
+    priority?: string;
+    owner?: string;
+    detail?: string;
+    ageHours?: number;
+}
+interface WorkgraphLensSection {
+    id: string;
+    title: string;
+    items: WorkgraphLensItem[];
+}
+interface WorkgraphLensResult {
+    lens: WorkgraphLensId;
+    generatedAt: string;
+    actor?: string;
+    options: {
+        lookbackHours: number;
+        staleHours: number;
+        limit: number;
+    };
+    metrics: Record<string, number>;
+    sections: WorkgraphLensSection[];
+    markdown: string;
+}
+interface WorkgraphMaterializeLensOptions extends WorkgraphLensOptions {
+    outputPath: string;
+}
+interface WorkgraphMaterializedLensResult extends WorkgraphLensResult {
+    outputPath: string;
+    created: boolean;
+}
 interface PolicyParty {
     id: string;
     roles: string[];
@@ -655,6 +700,21 @@ declare namespace orientation {
   export { orientation_brief as brief, orientation_checkpoint as checkpoint, orientation_intake as intake, orientation_statusSnapshot as statusSnapshot };
 }
 
+/**
+ * Deterministic context lenses for fast, runtime-agnostic orientation.
+ */
+
+declare function listContextLenses(): WorkgraphLensDescriptor[];
+declare function generateContextLens(workspacePath: string, lensId: WorkgraphLensId | string, options?: WorkgraphLensOptions): WorkgraphLensResult;
+declare function materializeContextLens(workspacePath: string, lensId: WorkgraphLensId | string, options: WorkgraphMaterializeLensOptions): WorkgraphMaterializedLensResult;
+
+declare const lens_generateContextLens: typeof generateContextLens;
+declare const lens_listContextLenses: typeof listContextLenses;
+declare const lens_materializeContextLens: typeof materializeContextLens;
+declare namespace lens {
+  export { lens_generateContextLens as generateContextLens, lens_listContextLenses as listContextLenses, lens_materializeContextLens as materializeContextLens };
+}
+
 /**
  * Wiki-link graph indexing and graph-intelligence queries.
  */
@@ -1388,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;
@@ -1720,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 WorkgraphStatusSnapshot, type WorkgraphWorkspaceConfig, agent, autonomy, autonomyDaemon, bases, board, claimLease, clawdapus, commandCenter, index as diagnostics, dispatch, fetchSkillMarkdownFromUrl, gate, graph, installSkillIntegration, integration, ledger, 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

@@ -9,12 +9,14 @@ import {
   fetchSkillMarkdownFromUrl,
   installSkillIntegration,
   integration_exports,
+  lens_exports,
   onboard_exports,
   search_qmd_adapter_exports,
   skill_exports,
+  swarm_exports,
   trigger_exports,
   workspace_exports
-} from "./chunk-OJ6KOGB2.js";
+} from "./chunk-MCHTUXG2.js";
 import {
   CursorCloudAdapter,
   THREAD_STATUS_TRANSITIONS,
@@ -36,7 +38,7 @@ import {
   thread_audit_exports,
   thread_exports,
   trigger_engine_exports
-} from "./chunk-R2MLGBHB.js";
+} from "./chunk-G6B47IBD.js";
 export {
   CursorCloudAdapter,
   THREAD_STATUS_TRANSITIONS,
@@ -56,6 +58,7 @@ export {
   installSkillIntegration,
   integration_exports as integration,
   ledger_exports as ledger,
+  lens_exports as lens,
   matchesCronSchedule,
   mcp_server_exports as mcpServer,
   nextCronMatch,
@@ -68,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-R2MLGBHB.js";
+} from "./chunk-G6B47IBD.js";
 export {
   createWorkgraphMcpServer,
   startWorkgraphMcpServer

package/package.json

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