@loomhelm/multi-task-flow 0.2.6 → 0.2.8

package/toolkit/skills/multi-task-flow/lib/atomic-orchestration.ts

@@ -93,6 +93,15 @@ export type AtomicNode = z.infer<typeof atomicNode>;
 export type AtomicEdge = z.infer<typeof atomicEdge>;
 export type TaskPrBinding = z.infer<typeof taskPrBinding>;
 export type DeliveryUnitExternalFacts = z.infer<typeof deliveryUnitExternalFacts>;
+export type ContributionStartContext = {
+  delivery_unit_kind?: "bootstrap" | "regular";
+  owner_kind?: "main" | "group";
+  execution_owner?: "main" | "delivery_agent" | "task_agent";
+  conversation_policy?: "main_owned" | "delivery_owned" | "task_agent" | "none";
+  active?: boolean;
+  workspace_ready?: boolean;
+  parent_pr_status?: "definitively_absent" | "unknown" | "pending" | "present";
+};
 
 export type DerivedBusinessStatus = "planned" | "ready" | "running" | "blocked" | "completed";
 
@@ -125,10 +134,23 @@ export function deriveBusinessStatus(
   return "planned";
 }
 
-export function validateContributionStart(node: AtomicNode, deliveryUnit: { pr: DeliveryUnitExternalFacts; parent_branch?: string | null }): void {
+export function validateContributionStart(
+  node: AtomicNode,
+  deliveryUnit: { pr: DeliveryUnitExternalFacts; parent_branch?: string | null },
+  context: ContributionStartContext = {},
+): void {
   if (node.kind !== "work" || node.activity_type !== "contribution" || node.state !== "starting") return;
-  if (deliveryUnit.pr.state !== "published" && deliveryUnit.pr.state !== "merged") throw new Error("Contribution work requires a published DeliveryUnit PR before starting");
-  if (!deliveryUnit.parent_branch) throw new Error("Contribution work requires a DeliveryUnit parent branch before starting");
+  const bootstrapException =
+    context.delivery_unit_kind === "bootstrap" &&
+    context.owner_kind === "main" &&
+    context.execution_owner === "main" &&
+    context.conversation_policy === "main_owned" &&
+    context.active === true &&
+    context.workspace_ready === true &&
+    context.parent_pr_status === "definitively_absent" &&
+    deliveryUnit.pr.state === "unpublished";
+  if (!bootstrapException && deliveryUnit.pr.state !== "published" && deliveryUnit.pr.state !== "merged") throw new Error("Contribution work requires a published DeliveryUnit PR before starting");
+  if (!bootstrapException && !deliveryUnit.parent_branch) throw new Error("Contribution work requires a DeliveryUnit parent branch before starting");
 }
 
 export type MilestoneEvaluation =

package/toolkit/skills/multi-task-flow/lib/engine.ts

@@ -195,6 +195,8 @@ function taskPrRef(task: Ledger["tasks"][number]): ExternalRef | null {
 function requireContributionDispatchGate(
   ledger: Ledger,
   owner: Ledger["groups"][number],
+  requireParentPr = true,
+  retryAction: "dispatch-claim" | "task-update" = "dispatch-claim",
 ): void {
   if (legacyLedger(ledger)) return;
   const workspaceAtom = owner.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
@@ -202,23 +204,30 @@ function requireContributionDispatchGate(
   const missing: string[] = [];
   if (owner.lifecycle.workspace_ready !== "passed" || workspaceAtom?.status !== "completed")
     missing.push("workspace_ready");
-  if (owner.lifecycle.pr_created !== "passed" || !deliveryUnitPr(owner) || prAtom?.status !== "completed")
+  const parentPrRequired = requireParentPr || !parentPrDefinitivelyAbsent(ledger, owner);
+  if (parentPrRequired && !parentPrReady(ledger, owner, prAtom))
     missing.push("parent_pr");
   if (missing.length)
     throw new ContractError(
       "DELIVERY_GATE_PENDING",
-      "Contribution task cannot start before the delivery-unit parent PR is created and verified",
+      missing.includes("parent_pr")
+        ? "Contribution task cannot start before the delivery-unit parent PR is created and verified"
+        : "Contribution task cannot start before the delivery-unit workspace is ready",
       4,
       {
         target_type: "group",
         target_id: owner.id,
         missing,
         recovery: [
-          "lifecycle-record workspace_ready",
-          "group-atom-update workspace_ready completed",
-          "publish-pr-claim + publish-pr-resolve for the parent PR",
-          "group-atom-update pr_created completed",
-          "retry dispatch-claim",
+          ...(missing.includes("workspace_ready") ? [
+            "lifecycle-record workspace_ready",
+            "group-atom-update workspace_ready completed",
+          ] : []),
+          ...(missing.includes("parent_pr") ? [
+            "publish-pr-claim + publish-pr-resolve for the parent PR",
+            "group-atom-update pr_created completed",
+            `retry ${retryAction}`,
+          ] : [`retry ${retryAction}`]),
         ],
       },
     );
@@ -409,6 +418,7 @@ function prReceipt(
   prValue: z.infer<typeof externalRef>,
   baseSha?: string,
   headSha?: string,
+  receiptState?: z.infer<typeof providerReceipt>["state"],
 ): boolean {
   const latest = latestPublication(ledger, targetId, "pr_published");
   return (
@@ -419,7 +429,43 @@ function prReceipt(
     latest.receipt.resource_id === prValue.id &&
     stable(latest.receipt.pr) === stable(prValue) &&
     (baseSha === undefined || latest.receipt.base_sha === baseSha) &&
-    (headSha === undefined || latest.receipt.head_sha === headSha)
+    (headSha === undefined || latest.receipt.head_sha === headSha) &&
+    (receiptState === undefined || latest.receipt.state === receiptState)
+  );
+}
+function parentPrReady(
+  ledger: Ledger,
+  owner: Ledger["groups"][number],
+  prAtom = owner.atoms.find((atom) => atom.lifecycle_stage === "pr_created"),
+): boolean {
+  const pr = deliveryUnitPr(owner);
+  const canonicalState = owner.pr && "state" in owner.pr ? owner.pr.state : null;
+  return (
+    owner.lifecycle.pr_created === "passed" &&
+    prAtom?.status === "completed" &&
+    !!pr &&
+    (canonicalState === null || canonicalState === "published") &&
+    prReceipt(ledger, owner.id, pr, undefined, undefined, "open")
+  );
+}
+function parentPrDefinitivelyAbsent(
+  ledger: Ledger,
+  owner: Ledger["groups"][number],
+): boolean {
+  const latest = latestPublication(ledger, owner.id, "pr_published");
+  const publicationPending = ledger.operations.some(
+    (item) =>
+      item.kind === "publish_pr" &&
+      item.target_id === owner.id &&
+      activeOperation(item),
+  );
+  return Boolean(
+    !publicationPending &&
+      latest &&
+      latest.status === "failed" &&
+      latest.receipt?.resource_type === "pr" &&
+      latest.receipt.state === "absent" &&
+      !deliveryUnitPr(owner),
   );
 }
 function requireDevelopmentTarget(
@@ -2837,7 +2883,22 @@ export function execute(
       const occupiedSlot = target.state === "agent_idle";
       if (state === "running" && isContributionKind(target.kind)) {
         const owner = find(ledger.groups, (item) => item.id === target.group_id, "Group");
-        requireContributionDispatchGate(ledger, owner);
+        const bootstrapMainOwnedStart =
+          mainOwned &&
+          owner.delivery_unit_kind === "bootstrap" &&
+          owner.owner_kind === "main";
+        requireCondition(
+          owner.state === "active",
+          "GROUP_NOT_READY",
+          "Task group is not active",
+          4,
+        );
+        requireContributionDispatchGate(
+          ledger,
+          owner,
+          !bootstrapMainOwnedStart,
+          "task-update",
+        );
       }
       if (state === "running" && previousState !== "starting" && !occupiedSlot) {
         requireCondition(
@@ -2935,7 +2996,7 @@ export function execute(
       }
       const eventType =
         state === "running"
-          ? previousState === "starting"
+          ? previousState === "starting" || previousState === "planned"
             ? "task_started"
             : "task_resumed"
           : state === "waiting"

package/toolkit/skills/multi-task-flow/lib/view.ts

@@ -37,14 +37,106 @@ export type PlannedInterval = {
 
 const RELATIVE_EPOCH = Date.parse("2000-01-01T00:00:00.000Z");
 
-function deliveryGateDiagnostics(group: Ledger["groups"][number]): Record<string, string>[] {
-  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+function deliveryUnitPr(group: Ledger["groups"][number]) {
+  if (group.pr && "state" in group.pr) return "pr" in group.pr ? group.pr.pr : null;
+  return group.parent_pr;
+}
+
+function latestParentPrFact(ledger: Ledger, groupId: string) {
+  return ledger.facts
+    .filter((fact) => fact.kind === "pr_published" && fact.subject_id === groupId)
+    .sort((left, right) => left.observed_at.localeCompare(right.observed_at))
+    .at(-1);
+}
+
+function sameExternalRef(left: { provider: string; repository: string; id: string }, right: { provider: string; repository: string; id: string }): boolean {
+  return left.provider === right.provider && left.repository === right.repository && left.id === right.id;
+}
+
+function parentPrReady(ledger: Ledger, group: Ledger["groups"][number]): boolean {
+  const pr = deliveryUnitPr(group);
+  const canonicalState = group.pr && "state" in group.pr ? group.pr.state : null;
   const prAtom = group.atoms.find((atom) => atom.lifecycle_stage === "pr_created");
+  const latest = latestParentPrFact(ledger, group.id);
+  return Boolean(
+    group.lifecycle.pr_created === "passed" &&
+      prAtom?.status === "completed" &&
+      pr &&
+      (canonicalState === null || canonicalState === "published") &&
+      latest?.status === "passed" &&
+      latest.receipt?.resource_type === "pr" &&
+      latest.receipt.resource_id === pr.id &&
+      latest.receipt.pr &&
+      sameExternalRef(latest.receipt.pr, pr) &&
+      latest.receipt.state === "open",
+  );
+}
+
+function parentPrDefinitivelyAbsent(ledger: Ledger, group: Ledger["groups"][number]): boolean {
+  const latest = latestParentPrFact(ledger, group.id);
+  const publicationPending = ledger.operations.some(
+    (operation) =>
+      operation.kind === "publish_pr" &&
+      operation.target_id === group.id &&
+      ["claimed", "unknown"].includes(operation.status),
+  );
+  return Boolean(
+    !publicationPending &&
+      latest &&
+      latest.status === "failed" &&
+      latest.receipt?.resource_type === "pr" &&
+      latest.receipt.state === "absent" &&
+      !deliveryUnitPr(group),
+  );
+}
+
+function allowsBootstrapMainOwnedStart(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+  task?: Ledger["tasks"][number],
+): boolean {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+  return Boolean(
+    task &&
+      group.state === "active" &&
+      group.delivery_unit_kind === "bootstrap" &&
+      group.owner_kind === "main" &&
+      task.execution_owner === "main" &&
+      task.conversation_policy === "main_owned" &&
+      group.lifecycle.workspace_ready === "passed" &&
+      workspaceAtom?.status === "completed" &&
+      parentPrDefinitivelyAbsent(ledger, group),
+  );
+}
+
+function allowsBootstrapGroupStart(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+): boolean {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
+  return Boolean(
+    group.state === "active" &&
+      group.delivery_unit_kind === "bootstrap" &&
+      group.owner_kind === "main" &&
+      group.lifecycle.workspace_ready === "passed" &&
+      workspaceAtom?.status === "completed" &&
+      parentPrDefinitivelyAbsent(ledger, group),
+  );
+}
+
+function deliveryGateDiagnostics(
+  ledger: Ledger,
+  group: Ledger["groups"][number],
+  task?: Ledger["tasks"][number],
+): Record<string, string>[] {
+  const workspaceAtom = group.atoms.find((atom) => atom.lifecycle_stage === "workspace_ready");
   const diagnostics: Record<string, string>[] = [];
+  if (group.state !== "active")
+    diagnostics.push({ code: "DELIVERY_UNIT_NOT_ACTIVE", message: "交付单元尚未进入 active 状态" });
   if (group.lifecycle.workspace_ready !== "passed" || workspaceAtom?.status !== "completed")
     diagnostics.push({ code: "DELIVERY_WORKSPACE_GATE_PENDING", message: "交付单元尚未完成 workspace_ready 原子任务" });
-  const deliveryPr = group.pr && "state" in group.pr ? ("pr" in group.pr ? group.pr.pr : null) : group.parent_pr;
-  if (group.lifecycle.pr_created !== "passed" || !deliveryPr || prAtom?.status !== "completed")
+  const bootstrapGroupException = !task && allowsBootstrapGroupStart(ledger, group);
+  if (!allowsBootstrapMainOwnedStart(ledger, group, task) && !bootstrapGroupException && !parentPrReady(ledger, group))
     diagnostics.push({ code: "DELIVERY_PARENT_PR_GATE_PENDING", message: "父 PR 尚未创建、核验并完成交付原子任务" });
   return diagnostics;
 }
@@ -697,6 +789,10 @@ export function buildView(
             scope: { kind: "task" as const, task_id: node.ref_id ?? node.id, delivery_unit_id: task?.group_id ?? node.group_id ?? "unassigned" },
           };
         });
+  const legacyAtomicNodeIds = new Map<string, string>([
+    ...plan.atoms.map((atom) => [atom.id, atom.task_id] as const),
+    ...plan.group_atoms.map((atom) => [atom.id, atom.group_id] as const),
+  ]);
   const nodeData = plan.nodes.map((node) => ({
     ...node,
     planned_group_id: node.group_id,
@@ -717,7 +813,7 @@ export function buildView(
   const declaredAtomicEdges: AtomicEdge[] = plan.atomic_edges.map((edge) =>
     "from_node_id" in edge
       ? edge
-      : { id: edge.id, from_node_id: edge.from_atom_id, to_node_id: edge.to_atom_id, requires: { kind: "source_terminal_success" as const } },
+      : { id: edge.id, from_node_id: legacyAtomicNodeIds.get(edge.from_atom_id) ?? edge.from_atom_id, to_node_id: legacyAtomicNodeIds.get(edge.to_atom_id) ?? edge.to_atom_id, requires: { kind: "source_terminal_success" as const } },
   );
   const legacyAtomicEdges: AtomicEdge[] = plan.edges
     .filter((edge) => canonicalAtomicNodeIds.has(edge.from_node_id) && canonicalAtomicNodeIds.has(edge.to_node_id))
@@ -803,7 +899,7 @@ export function buildView(
       return {
         ...task,
         ...(() => {
-          const gateDiagnostics = owner && isContributionKind(task.kind) ? deliveryGateDiagnostics(owner) : [];
+          const gateDiagnostics = owner && isContributionKind(task.kind) ? deliveryGateDiagnostics(ledger, owner, task) : [];
           return { gateDiagnostics };
         })(),
         dispatch_diagnostics: [
@@ -811,14 +907,14 @@ export function buildView(
           ...(owner && owner.delivery_unit_kind === "regular" && !owner.agent_thread_id
             ? [{ code: "DELIVERY_AGENT_NOT_BOUND", message: "regular delivery unit 未绑定交付 Agent" }]
             : []),
-          ...((owner && isContributionKind(task.kind)) ? deliveryGateDiagnostics(owner) : []),
+          ...((owner && isContributionKind(task.kind)) ? deliveryGateDiagnostics(ledger, owner, task) : []),
         ],
         dispatch_readiness:
           task.execution_owner === null && task.conversation_policy === null && task.delivery_policy === null
             ? "unknown"
             : taskExecutionPolicyIssues(task).length > 0
               ? "blocked"
-              : owner && isContributionKind(task.kind) && deliveryGateDiagnostics(owner).length > 0
+              : owner && isContributionKind(task.kind) && deliveryGateDiagnostics(ledger, owner, task).length > 0
                 ? "blocked"
               : owner && (owner.delivery_unit_kind === "bootstrap" || !!owner.agent_thread_id)
               ? "ready"
@@ -848,6 +944,10 @@ export function buildView(
   const allTasksDispatchReady = tasks.every(
     (task) => task.dispatch_readiness === "ready",
   );
+  const allDeliveryUnitsDispatchReady = ledger.groups.every((item) =>
+    deliveryGateDiagnostics(ledger, item).length === 0 &&
+    (item.delivery_unit_kind === "bootstrap" || !!item.agent_thread_id),
+  );
   const planSummary = ledger.plans.map((item) => ({
     id: item.id,
     created_at: item.created_at,
@@ -892,7 +992,7 @@ export function buildView(
         activePlan.id !== executionPlan.id ||
         activePlan.lifecycle !== "approved",
       scheduling_eligible: schedulingStatus === "eligible",
-      dispatch_readiness: ledger.groups.every((item) => item.delivery_unit_kind === "bootstrap" || !!item.agent_thread_id) && allTasksDispatchReady ? "ready" : "blocked",
+      dispatch_readiness: allDeliveryUnitsDispatchReady && allTasksDispatchReady ? "ready" : "blocked",
       delivery_agent_readiness: ledger.groups.some((item) => item.delivery_unit_kind === "regular" && !item.agent_thread_id) ? "unbound" : "bound",
       proposal: {
         status: completenessIssues.length === 0 ? "complete" : "blocked",
@@ -923,14 +1023,16 @@ export function buildView(
       ...item,
       derived_status: deriveBusinessStatus(canonicalAtomicNodes, { kind: "delivery_unit", delivery_unit_id: item.id }, milestoneEvaluations),
       ...(() => {
-        const gateDiagnostics = item.delivery_unit_kind === "regular" ? deliveryGateDiagnostics(item) : [];
+        const gateDiagnostics = deliveryGateDiagnostics(ledger, item);
         return { gateDiagnostics };
       })(),
       delivery_agent_readiness: item.delivery_unit_kind === "bootstrap" ? "not_applicable" : item.agent_thread_id ? "bound" : "unbound",
-      dispatch_readiness: item.delivery_unit_kind === "bootstrap" || (!!item.agent_thread_id && deliveryGateDiagnostics(item).length === 0) ? "ready" : "blocked",
+      dispatch_readiness: item.delivery_unit_kind === "bootstrap"
+        ? deliveryGateDiagnostics(ledger, item).length === 0 ? "ready" : "blocked"
+        : !!item.agent_thread_id && deliveryGateDiagnostics(ledger, item).length === 0 ? "ready" : "blocked",
       dispatch_diagnostics: [
         ...(item.delivery_unit_kind === "regular" && !item.agent_thread_id ? [{ code: "DELIVERY_AGENT_NOT_BOUND", message: "regular delivery unit 未绑定交付 Agent" }] : []),
-        ...(item.delivery_unit_kind === "regular" ? deliveryGateDiagnostics(item) : []),
+        ...deliveryGateDiagnostics(ledger, item),
       ],
       ...profileProjection(ledger, "group", item),
       coordinator: coordinatorProjection(ledger, item),
@@ -949,7 +1051,7 @@ export function buildView(
     selected_plan_id: plan.id,
     nodes: canonicalDisplayNodes,
     edges: canonicalDisplayEdges,
-    atomic_edges: plan.atomic_edges,
+    atomic_edges: canonicalAtomicEdges,
     atomic_nodes: canonicalAtomicNodes,
     canonical_atomic_edges: canonicalAtomicEdges,
     planned_intervals: plannedIntervals(plan, ledger.config.max_running_tasks),

package/toolkit/skills/multi-task-flow/scripts/package-client-skills.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env -S bun --no-install
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, relative, resolve, sep } from 'node:path';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
 const root = resolve(import.meta.dirname, '../../..');
 const target = resolve(root, 'clients/typescript/toolkit');
 const manifest = JSON.parse(readFileSync(resolve(root, 'skills/source-manifest.json'), 'utf8'));
@@ -42,36 +42,15 @@ const gitTag = process.env.LOOMHELM_GIT_TAG?.trim() || null;
 if (gitTag !== null && gitTag !== `multi-task-flow-v${buildVersion}`) throw new Error('LOOMHELM_GIT_TAG does not match package version');
 const tarballDigest = process.env.LOOMHELM_TARBALL_DIGEST?.trim() || null;
 if (tarballDigest !== null && !sha256.test(tarballDigest)) throw new Error('LOOMHELM_TARBALL_DIGEST must be a SHA-256 digest');
-type DependencyDeclaration = { name: string; version: string; resourceRoot: string };
-type PreparedDependency = { name: string; version: string; path: string; entry: string };
-const dependencyDeclarations = new Map<string, DependencyDeclaration>();
-function declareDependencies(metadata: { dependencies?: Record<string, string> }, resourceRoot: string): void {
-  for (const [name, version] of Object.entries(metadata.dependencies ?? {})) {
-    const existing = dependencyDeclarations.get(name);
-    if (existing) {
-      if (existing.version !== version) throw new Error(`Conflicting dependency declaration: ${name}`);
-      continue;
-    }
-    dependencyDeclarations.set(name, { name, version, resourceRoot });
-  }
-}
-const skillsPackageMetadata = JSON.parse(readFileSync(resolve(root, 'skills/package.json'), 'utf8')) as { dependencies?: Record<string, string> };
-const flowPackageMetadata = JSON.parse(readFileSync(resolve(root, 'skills/multi-task-flow/package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
-declareDependencies(skillsPackageMetadata, 'skills/node_modules');
-// The viewer's React/ELK dependencies are build-time inputs for the static
-// assets. The portable CLI only needs the runtime Skill dependencies above;
-// shipping the entire frontend dependency tree makes the tarball hundreds of
-// megabytes and slows every `bunx` startup. Keep the package's normal npm
-// dependency declarations for consumers that need the frontend, while bundling
-// only the dependencies executed by Skill scripts.
-if (flowPackageMetadata.dependencies?.zod) {
-  dependencyDeclarations.set('zod', {
-    name: 'zod',
-    version: flowPackageMetadata.dependencies.zod,
-    resourceRoot: 'skills/multi-task-flow/node_modules',
-  });
-}
-const requiredDependencies = [...dependencyDeclarations.values()].sort((left, right) => left.name.localeCompare(right.name));
+type ConsumerDependency = { name: string; version: string; mode: 'consumer-install' };
+const runtimeDependencyNames = ['playwright', 'sharp', 'zod'] as const;
+const declaredDependencies = packageMetadata.dependencies as Record<string, string> | undefined;
+if (!declaredDependencies || JSON.stringify(Object.keys(declaredDependencies).sort()) !== JSON.stringify([...runtimeDependencyNames])) throw new Error('Package production dependencies must be exactly playwright, sharp, and zod');
+const requiredDependencies: ConsumerDependency[] = runtimeDependencyNames.map(name => {
+  const version = declaredDependencies[name];
+  if (typeof version !== 'string' || !version) throw new Error(`Missing runtime dependency declaration: ${name}`);
+  return { name, version, mode: 'consumer-install' };
+});
 // Only this exact disposable resource output is replaced. TS is never emitted.
 if (existsSync(target)) {
   if (lstatSync(target).isSymbolicLink() || realpathSync(target) !== target) throw new Error('Unsafe toolkit output directory');
@@ -109,22 +88,15 @@ function writeGenerated(path: string, contents: Uint8Array): void {
   writeFileSync(output, contents);
   record(path, contents);
 }
-function dependencyMetadata(sourceRoot: string, name: string, expectedVersion: string): { name: string; version: string; entry: string } {
-  const dependencyBase = resolve(root, sourceRoot);
-  const packageRoot = resolve(dependencyBase, name);
-  if (!packageRoot.startsWith(`${dependencyBase}${sep}`)) throw new Error(`Unsafe prepared dependency path: ${name}`);
-  const packageJsonPath = resolve(packageRoot, 'package.json');
-  if (!existsSync(packageJsonPath)) throw new Error(`Prepared dependency missing: ${name}`);
-  const metadata = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { name?: string; version?: string; module?: string; main?: string };
-  if (metadata.name !== name || metadata.version !== expectedVersion) throw new Error(`Prepared dependency version mismatch: ${name}`);
-  const declaredEntry = metadata.module ?? metadata.main ?? 'index.js';
-  const candidates = [declaredEntry, `${declaredEntry}.js`, `${declaredEntry}.mjs`, `${declaredEntry}.cjs`, `${declaredEntry}/index.js`];
-  const entry = candidates.find(candidate => {
-    const sourceEntry = resolve(packageRoot, candidate);
-    return sourceEntry.startsWith(`${packageRoot}${sep}`) && existsSync(sourceEntry) && lstatSync(sourceEntry).isFile() && realpathSync(sourceEntry) === sourceEntry;
-  });
-  if (!entry) throw new Error(`Unsafe prepared dependency entry: ${name}`);
-  return { name, version: expectedVersion, entry: entry.replace(/^\.\//, '') };
+function validateInstalledDependencies(): void {
+  const packageRoot = resolve(root, 'clients/typescript');
+  for (const dependency of requiredDependencies) {
+    const dependencyRoot = resolve(packageRoot, 'node_modules', dependency.name);
+    const dependencyManifest = resolve(dependencyRoot, 'package.json');
+    if (!existsSync(dependencyManifest) || lstatSync(dependencyRoot).isSymbolicLink() || realpathSync(dependencyRoot) !== dependencyRoot) throw new Error(`Consumer dependency is not installed: ${dependency.name}`);
+    const metadata = JSON.parse(readFileSync(dependencyManifest, 'utf8')) as { name?: string; version?: string };
+    if (metadata.name !== dependency.name || metadata.version !== dependency.version) throw new Error(`Consumer dependency version mismatch: ${dependency.name}`);
+  }
 }
 function copyPackageManifest(): void {
   const files = manifest.files.filter(file => !packageOmissionPaths.has(file.path));
@@ -136,109 +108,7 @@ for (const file of [...manifest.files, ...(manifest.additions ?? [])]) if (!pack
 copyPackageManifest();
 copy('skills/catalog.json');
 for (const name of ['index.html','app.js','app.css']) copy(`skills/multi-task-flow/dist/${name}`);
-const copyDependencies = (path: string, dependencyNames?: string[]): boolean => {
-  const sourceRoot = resolve(root, path);
-  if (!existsSync(sourceRoot)) {
-    if (requireDependencies) throw new Error(`Prepared dependency directory missing: ${path}`);
-    return false;
-  }
-  const rootStat = lstatSync(sourceRoot);
-  if (!rootStat.isDirectory() || rootStat.isSymbolicLink() || realpathSync(sourceRoot) !== sourceRoot) throw new Error('Unsafe dependency directory: ' + path);
-  const resolvedRoot = realpathSync(sourceRoot);
-  let preparedFiles = 0;
-  const copyBinLauncher = (child: string, source: string): void => {
-    const resolvedSource = realpathSync(source);
-    const relSource = relative(sourceRoot, resolvedSource);
-    if (relative(resolvedRoot, resolvedSource).startsWith(`..${sep}`) || relative(resolvedRoot, resolvedSource) === '..' || relSource.startsWith(`..${sep}`) || relSource === '..' || !lstatSync(resolvedSource).isFile()) throw new Error('Unsafe dependency launcher: ' + `${path}/${child}`);
-    const outputPath = resolve(target, path, child);
-    const targetPath = resolve(target, path, relSource);
-    const targetRel = relative(dirname(outputPath), targetPath).split(sep).join('/');
-    const launcher = `#!/usr/bin/env bun\nawait import(new URL(${JSON.stringify(targetRel)}, import.meta.url).href);\n`;
-    mkdirSync(dirname(outputPath), { recursive: true });
-    writeFileSync(outputPath, launcher, { mode: 0o755 });
-    record(`${path}/${child}`, Buffer.from(launcher));
-  };
-  const recordPreparedFile = (destination: string, source: string): void => {
-    const resolvedSource = realpathSync(source);
-    const relativeSource = relative(resolvedRoot, resolvedSource);
-    const stat = lstatSync(source);
-    if (relativeSource.startsWith(`..${sep}`) || relativeSource === '..' || !stat.isFile() || stat.isSymbolicLink() || resolvedSource !== source) throw new Error('Unsafe prepared dependency: ' + destination);
-    const output = resolve(target, destination);
-    mkdirSync(dirname(output), { recursive: true });
-    const contents = readFileSync(resolvedSource);
-    cpSync(resolvedSource, output);
-    record(destination, contents);
-    preparedFiles += 1;
-  };
-  const walk = (relativePath: string): void => {
-    for (const entry of readdirSync(resolve(sourceRoot, relativePath), { withFileTypes: true })) {
-      if (entry.name === '.cache') continue;
-      const child = relativePath ? `${relativePath}/${entry.name}` : entry.name;
-      const source = resolve(sourceRoot, child);
-      if (entry.isSymbolicLink()) {
-        if (relativePath !== '.bin' && !relativePath.startsWith(`.bin${sep}`)) throw new Error('Unsafe dependency symlink: ' + `${path}/${child}`);
-        if (productPartitionBuild) recordPreparedFile(`${path}/${child}`, realpathSync(source));
-        else copyBinLauncher(child, source);
-      } else if (entry.isDirectory()) walk(child);
-      else if (productPartitionBuild) recordPreparedFile(`${path}/${child}`, source);
-      else copy(`${path}/${child}`, undefined, true);
-    }
-  };
-  if (!dependencyNames) {
-    walk('');
-    return preparedFiles > 0;
-  }
-  const roots = new Map<string, string>();
-  const queue = dependencyNames.map(name => ({ name, relativePath: name }));
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    if (roots.has(current.relativePath)) continue;
-    const packageJson = resolve(sourceRoot, current.relativePath, 'package.json');
-    if (!existsSync(packageJson)) throw new Error(`Prepared dependency missing: ${current.name}`);
-    roots.set(current.relativePath, current.name);
-    const metadata = JSON.parse(readFileSync(packageJson, 'utf8')) as { dependencies?: Record<string, string>; optionalDependencies?: Record<string, string> };
-    for (const dependencyName of Object.keys(metadata.dependencies ?? {})) {
-      const nested = `${current.relativePath}/node_modules/${dependencyName}`;
-      const root = existsSync(resolve(sourceRoot, nested, 'package.json')) ? nested : dependencyName;
-      if (!roots.has(root)) queue.push({ name: dependencyName, relativePath: root });
-    }
-    for (const dependencyName of Object.keys(metadata.optionalDependencies ?? {})) {
-      const nested = `${current.relativePath}/node_modules/${dependencyName}`;
-      const root = existsSync(resolve(sourceRoot, nested, 'package.json')) ? nested : dependencyName;
-      if (existsSync(resolve(sourceRoot, root, 'package.json')) && !roots.has(root)) queue.push({ name: dependencyName, relativePath: root });
-    }
-  }
-  for (const relativePath of roots.keys()) walk(relativePath);
-  return preparedFiles > 0;
-};
-let preparedDependencies: PreparedDependency[];
-if (productPartitionBuild) {
-  for (const resourceRoot of new Set(requiredDependencies.map(dependency => dependency.resourceRoot))) {
-    copyDependencies(resourceRoot, requiredDependencies.filter(dependency => dependency.resourceRoot === resourceRoot).map(dependency => dependency.name));
-  }
-  preparedDependencies = requiredDependencies.map(dependency => {
-    const metadata = dependencyMetadata(dependency.resourceRoot, dependency.name, dependency.version);
-    const path = `${dependency.resourceRoot}/${dependency.name}`;
-    if (!outputs.has(`${path}/package.json`)) throw new Error(`Prepared dependency was not copied: ${dependency.name}`);
-    return { name: dependency.name, version: dependency.version, path, entry: metadata.entry };
-  });
-} else {
-  // The published package must be runnable from an isolated `bunx` install.
-  // Bun's workspace install may materialize dependency entries as shims that
-  // point outside the package; copying the prepared dependency trees keeps
-  // every runtime import inside the tarball and makes the artifact portable.
-  for (const resourceRoot of new Set(requiredDependencies.map(dependency => dependency.resourceRoot))) {
-    copyDependencies(resourceRoot, requiredDependencies.filter(dependency => dependency.resourceRoot === resourceRoot).map(dependency => dependency.name));
-  }
-  preparedDependencies = requiredDependencies.map(dependency => {
-    const metadata = dependencyMetadata(dependency.resourceRoot, dependency.name, dependency.version);
-    const path = `${dependency.resourceRoot}/${dependency.name}`;
-    if (!outputs.has(`${path}/package.json`)) throw new Error(`Prepared dependency was not copied: ${dependency.name}`);
-    return { name: dependency.name, version: dependency.version, path, entry: metadata.entry };
-  });
-}
-const dependenciesBundled = preparedDependencies.length === requiredDependencies.length && requiredDependencies.length > 0;
-if (requireDependencies && !dependenciesBundled) throw new Error('Prepared dependency closure is incomplete');
+if (requireDependencies) validateInstalledDependencies();
 copyRootFile('AGENTS.md');
 const packageIdentityBase = {
   packageName: packageMetadata.name,
@@ -251,6 +121,7 @@ const packageIdentityBase = {
   contracts: { ledgerContract: packageContracts.ledger, apiVersion: packageContracts.api, frontendContract: packageContracts.frontend, viewerContract: packageContracts.viewer, serviceVersion: packageContracts.service },
   tarballDigest,
   gitTag,
+  canonicalDigestAlgorithm: 'path-byte-v2',
 };
 const generatedPackage = JSON.stringify({ private: true, type: 'module', packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion }, null, 2) + '\n';
 writeFileSync(resolve(target, 'package.json'), generatedPackage);
@@ -258,6 +129,6 @@ writeFileSync(resolve(target, 'package.json'), generatedPackage);
 const finalInventory = [...outputs.values()].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
 const buildId = createHash('sha256').update(JSON.stringify({ ...packageIdentityBase, files: finalInventory })).digest('hex');
 const identity = { ...packageIdentityBase, buildId };
-const artifact = { schemaVersion: 2, packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion, sourceCommit: manifest.commit, sourceSha, mergeSha: packageIdentityBase.mergeSha, candidateSha: sourceSha, dirty, runtime: 'bun@1.4.4', identity, buildId, tarballDigest, gitTag, dependenciesBundled, dependencies: preparedDependencies, omittedResources: packageOmissions, files: finalInventory };
+const artifact = { schemaVersion: 3, packageName: packageMetadata.name, packageVersion: buildVersion, compatibilityLine: packageConfig.compatibilityLine, skillVersion: packageConfig.skillVersion, sourceCommit: manifest.commit, sourceSha, mergeSha: packageIdentityBase.mergeSha, candidateSha: sourceSha, dirty, runtime: 'bun@1.4.4', identity, buildId, tarballDigest, gitTag, canonicalDigestAlgorithm: 'path-byte-v2', dependenciesBundled: false, dependencies: requiredDependencies, omittedResources: packageOmissions, files: finalInventory };
 writeFileSync(resolve(target, 'artifact-manifest.json'), JSON.stringify(artifact, null, 2) + '\n');
-console.log(JSON.stringify({ artifact: target, package: packageMetadata.name, version: buildVersion, compatibilityLine: packageConfig.compatibilityLine, runtime: 'bun@1.4.4', resources: finalInventory.length, dependenciesBundled, source: sourceSha, merge: packageIdentityBase.mergeSha, buildId, dirty }));
+console.log(JSON.stringify({ artifact: target, package: packageMetadata.name, version: buildVersion, compatibilityLine: packageConfig.compatibilityLine, runtime: 'bun@1.4.4', resources: finalInventory.length, dependenciesBundled: false, dependencies: requiredDependencies, source: sourceSha, merge: packageIdentityBase.mergeSha, buildId, dirty }));

package/toolkit/skills/multi-task-flow/scripts/preview-source.ts

@@ -23,6 +23,7 @@ import {
 import { ServiceState } from "../lib/service-state";
 import { servicePaths } from "../lib/service-paths";
 import { ServiceAuth } from "../lib/service-auth";
+import { versionEnvelope } from "../lib/contract";
 import { runDaemon } from "../lib/service-lifecycle";
 import { compatibility, type ReleaseManifest } from "../lib/service-contract";
 import { buildId, digest } from "../lib/service-release";
@@ -112,9 +113,11 @@ files.viewer = digest(readFileSync(import.meta.path));
 const body = {
   schema_version: 1 as const,
   source_sha: source.stdout.toString().trim(),
+  ledger_contract: 3,
   service_version: "source-preview",
   platform:
     `${process.platform}-${process.arch}` as ReleaseManifest["platform"],
+  ...versionEnvelope,
   ...compatibility,
   files,
 };