nemoris 0.1.0 → 0.1.2

package/src/runtime/interaction-contract.js

@@ -1,347 +1,347 @@
-import { parseContractOutput } from "./output-contract-validator.js";
-
-function dedupe(items) {
-  return [...new Set((items || []).map((item) => String(item).trim()).filter(Boolean))];
-}
-
-function normalizeSectionKey(value) {
-  return String(value || "")
-    .toLowerCase()
-    .replace(/[\s-]+/g, "_")
-    .trim();
-}
-
-function normalizeText(value) {
-  return String(value || "").replace(/\s+/g, " ").trim();
-}
-
-function trimValue(value, limit = 220) {
-  const text = normalizeText(value);
-  if (text.length <= limit) return text;
-  return `${text.slice(0, limit - 3)}...`;
-}
-
-function normalizeNextActions(nextActions = []) {
-  return (nextActions || [])
-    .map((item) => {
-      if (typeof item === "string") return normalizeText(item);
-      if (item && typeof item === "object") {
-        const action = normalizeText(item.action || "");
-        const details = normalizeText(item.details || item.summary || "");
-        return [action, details].filter(Boolean).join(": ");
-      }
-      return normalizeText(item);
-    })
-    .filter(Boolean);
-}
-
-export function normalizeInteractionContract(contract = null) {
-  const raw = contract || {};
-  const progressAfterSeconds = raw.progressAfterSeconds ?? 90;
-  const handoff = raw.handoff || {};
-  const yieldConfig = raw.yield || {};
-
-  return {
-    ackMode: raw.ackMode || "immediate",
-    ackText: raw.ackText || null,
-    progressMode: raw.progressMode || "long_running",
-    progressAfterSeconds,
-    maxSilenceSeconds: raw.maxSilenceSeconds ?? Math.max(progressAfterSeconds * 2, 180),
-    notifyOnDone: raw.notifyOnDone ?? true,
-    notifyOnError: raw.notifyOnError ?? true,
-    requiresPingback: raw.requiresPingback ?? true,
-    pingbackTarget: raw.pingbackTarget || "same_thread",
-    completionSignal: raw.completionSignal || "done",
-    failureSignal: raw.failureSignal || "error",
-    handoffFormat: raw.handoffFormat || "structured_handoff",
-    completionSections: dedupe(raw.completionSections || ["status", "next_actions"]),
-    includeNextActions: raw.includeNextActions ?? true,
-    handoff: {
-      enabled: handoff.enabled ?? false,
-      signal: handoff.signal || raw.handoffSignal || "peer_handoff",
-      target: handoff.target || raw.handoffTarget || null,
-      deliveryProfile: handoff.deliveryProfile || raw.handoffDeliveryProfile || null,
-      capabilityQuery: handoff.capabilityQuery || raw.handoffCapabilityQuery || null,
-      preferredTaskClasses: dedupe(handoff.preferredTaskClasses || raw.handoffPreferredTaskClasses || []),
-      trustLevel: handoff.trustLevel || raw.handoffTrustLevel || null,
-      maxSuggestions: handoff.maxSuggestions ?? raw.handoffMaxSuggestions ?? 3,
-      messagePrefix: handoff.messagePrefix || raw.handoffMessagePrefix || null
-    },
-    yield: {
-      enabled: yieldConfig.enabled ?? raw.yieldEnabled ?? false,
-      signal: yieldConfig.signal || raw.yieldSignal || "follow_up",
-      targetSurface: yieldConfig.targetSurface || raw.yieldTargetSurface || "operator_review",
-      followUpObjective: yieldConfig.followUpObjective || raw.followUpObjective || null
-    }
-  };
-}
-
-export function resolveInteractionContract(agentContract = null, jobContract = null) {
-  return normalizeInteractionContract({
-    ...(agentContract || {}),
-    ...(jobContract || {})
-  });
-}
-
-export function formatInteractionContract(contract) {
-  if (!contract) return "";
-
-  const lines = [
-    `- ack mode: ${contract.ackMode}`,
-    `- progress mode: ${contract.progressMode}`,
-    `- progress after seconds: ${contract.progressAfterSeconds}`,
-    `- max silence seconds: ${contract.maxSilenceSeconds}`,
-    `- requires pingback: ${contract.requiresPingback}`,
-    `- pingback target: ${contract.pingbackTarget}`,
-    `- notify on done: ${contract.notifyOnDone}`,
-    `- notify on error: ${contract.notifyOnError}`,
-    `- completion signal: ${contract.completionSignal}`,
-    `- handoff format: ${contract.handoffFormat}`
-  ];
-
-  if (contract.completionSections?.length) {
-    lines.push(`- completion sections: ${contract.completionSections.join(", ")}`);
-  }
-  if (contract.handoff?.enabled) {
-    lines.push(`- handoff enabled: yes`);
-    if (contract.handoff.capabilityQuery) lines.push(`- handoff capability query: ${contract.handoff.capabilityQuery}`);
-    if (contract.handoff.preferredTaskClasses?.length) {
-      lines.push(`- handoff preferred tasks: ${contract.handoff.preferredTaskClasses.join(", ")}`);
-    }
-    if (contract.handoff.target) {
-      lines.push(`- handoff target: ${typeof contract.handoff.target === "string" ? contract.handoff.target : JSON.stringify(contract.handoff.target)}`);
-    }
-  }
-  if (contract.yield?.enabled) {
-    lines.push(`- yield enabled: yes`);
-    lines.push(`- yield target surface: ${contract.yield.targetSurface}`);
-  }
-
-  return lines.join("\n");
-}
-
-function outputSectionMap(output, result, contract = null) {
-  const entries = [];
-  if (contract?.requiredSections?.length) {
-    const parsed = parseContractOutput(output, contract);
-    for (const section of contract.requiredSections) {
-      const key = normalizeSectionKey(section);
-      entries.push([key, trimValue(parsed.sections.get(key) || "None")]);
-    }
-  } else if (output && typeof output === "object" && !Array.isArray(output)) {
-    for (const [key, value] of Object.entries(output)) {
-      entries.push([normalizeSectionKey(key), trimValue(value)]);
-    }
-  }
-
-  entries.push(["status", trimValue(result.summary || "Completed.")]);
-  entries.push(["summary", trimValue(result.summary || "Completed.")]);
-  const nextActions = normalizeNextActions(result.nextActions || []);
-  entries.push(["next_actions", nextActions.length ? nextActions.join("; ") : "None"]);
-  entries.push(["next", nextActions.length ? nextActions.join("; ") : "None"]);
-  entries.push(["handoff", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
-  entries.push(["evidence", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
-  entries.push(["changes", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
-  entries.push(["verification", nextActions.length ? nextActions.join("; ") : "No explicit verification captured."]);
-  entries.push(["issues", "None"]);
-
-  return new Map(entries);
-}
-
-function buildCompletionSections(contract, result) {
-  const output = result.output;
-  const map = outputSectionMap(output, result, result.outputContract || null);
-
-  return contract.completionSections.map((section) => ({
-    key: normalizeSectionKey(section),
-    label: String(section)
-      .replace(/_/g, " ")
-      .replace(/\b\w/g, (char) => char.toUpperCase()),
-    value: map.get(normalizeSectionKey(section)) || "None"
-  }));
-}
-
-function renderCompletionMessage(plan, contract, sections) {
-  if (contract.handoffFormat === "concise_status") {
-    const status = sections.find((section) => section.key === "status")?.value || plan.job.id;
-    const next = sections.find((section) => section.key === "next_actions")?.value || "None";
-    return `[${contract.completionSignal}] ${status} | next: ${next}`;
-  }
-
-  if (contract.handoffFormat === "coding_completion") {
-    const lines = [`${contract.completionSignal.toUpperCase()}: ${plan.job.id}`];
-    for (const section of sections) {
-      lines.push(`${section.label}: ${section.value}`);
-    }
-    return lines.join("\n");
-  }
-
-  return [
-    `${contract.completionSignal.toUpperCase()}: ${plan.job.id}`,
-    ...sections.map((section) => `- ${section.label}: ${section.value}`)
-  ].join("\n");
-}
-
-function normalizeHandoffTarget(target, deliveryProfile = null) {
-  if (!target) return null;
-  if (typeof target === "string") {
-    return {
-      mode: "peer_agent",
-      peerId: target,
-      deliveryProfile
-    };
-  }
-  return {
-    ...target,
-    deliveryProfile: target.deliveryProfile || deliveryProfile || null
-  };
-}
-
-function buildHandoffMessage(plan, contract, sections, suggestions = []) {
-  const status = sections.find((section) => section.key === "status")?.value || resultSummaryFallback(plan);
-  const nextActions = sections.find((section) => section.key === "next_actions")?.value || "None";
-  const lines = [];
-
-  if (contract.handoff.messagePrefix) {
-    lines.push(contract.handoff.messagePrefix);
-  }
-  lines.push(`[${contract.handoff.signal}] ${plan.job.id}`);
-  lines.push(`Status: ${status}`);
-  lines.push(`Next Actions: ${nextActions}`);
-
-  if (suggestions.length) {
-    lines.push(`Suggested Peers: ${suggestions.map((item) => item.label).join(", ")}`);
-  }
-
-  return lines.join("\n");
-}
-
-function resultSummaryFallback(plan) {
-  return `${plan.job.id} completed.`;
-}
-
-function buildHandoffPlan(plan, contract, sections, suggestions = []) {
-  if (!contract.handoff?.enabled) return null;
-
-  const target = normalizeHandoffTarget(contract.handoff.target, contract.handoff.deliveryProfile);
-  return {
-    required: true,
-    signal: contract.handoff.signal,
-    target,
-    deliveryProfile: contract.handoff.deliveryProfile || target?.deliveryProfile || null,
-    suggestions: suggestions.slice(0, contract.handoff.maxSuggestions || 3),
-    capabilityQuery: contract.handoff.capabilityQuery || null,
-    preferredTaskClasses: contract.handoff.preferredTaskClasses || [],
-    sections,
-    nextActions: contract.includeNextActions ? sections.find((section) => section.key === "next_actions")?.value?.split("; ").filter(Boolean) || [] : [],
-    message: buildHandoffMessage(plan, contract, sections, suggestions)
-  };
-}
-
-function buildYieldPlan(plan, contract, result, completion, handoff) {
-  if (!contract.yield?.enabled) return null;
-
-  return {
-    required: true,
-    signal: contract.yield.signal,
-    targetSurface: contract.yield.targetSurface || "operator_review",
-    objective:
-      contract.yield.followUpObjective ||
-      `Continue ${plan.job.id} follow-up in a bounded next step without extending the current turn.`,
-    followUp: {
-      sourceJobId: plan.job.id,
-      sourceAgentId: plan.agent?.id || plan.packet?.agentId || null,
-      signal: contract.yield.signal,
-      objective:
-        contract.yield.followUpObjective ||
-        `Continue ${plan.job.id} follow-up in a bounded next step without extending the current turn.`,
-      targetSurface: contract.yield.targetSurface || "operator_review",
-      sections: completion?.sections || [],
-      nextActions: result.nextActions || [],
-      completion: completion?.required
-        ? {
-            signal: completion.signal,
-            target: completion.target,
-            handoffFormat: completion.handoffFormat,
-            sections: completion.sections || [],
-            nextActions: completion.nextActions || [],
-            message: completion.message
-          }
-        : null,
-      handoff: handoff?.required
-        ? {
-            signal: handoff.signal,
-            target: handoff.target || null,
-            deliveryProfile: handoff.deliveryProfile || null,
-            suggestions: handoff.suggestions || [],
-            capabilityQuery: handoff.capabilityQuery || null,
-            preferredTaskClasses: handoff.preferredTaskClasses || [],
-            sections: handoff.sections || [],
-            nextActions: handoff.nextActions || [],
-            message: handoff.message
-          }
-        : null
-    }
-  };
-}
-
-export function buildInteractionPlan(plan, result, error = null, options = {}) {
-  const contract = normalizeInteractionContract(plan.packet.layers.interactionContract);
-  result.outputContract = plan.packet.layers.outputContract || null;
-
-  const ack =
-    contract.ackMode === "silent"
-      ? {
-          required: false,
-          mode: contract.ackMode,
-          target: contract.pingbackTarget,
-          message: null
-        }
-      : {
-          required: true,
-          mode: contract.ackMode,
-          target: contract.pingbackTarget,
-          message:
-            contract.ackText ||
-            `Acknowledged ${plan.job.id}. I will ping back with ${contract.completionSignal} when the run is finished.`
-        };
-
-  const completionSections = buildCompletionSections(contract, result);
-  const handoff = buildHandoffPlan(plan, contract, completionSections, options.handoffSuggestions || []);
-  const completion = {
-    required: contract.notifyOnDone || contract.requiresPingback,
-    signal: contract.completionSignal,
-    target: contract.pingbackTarget,
-    handoffFormat: contract.handoffFormat,
-    sections: completionSections,
-    nextActions: contract.includeNextActions ? result.nextActions || [] : [],
-    message: renderCompletionMessage(plan, contract, completionSections)
-  };
-  const yieldPlan = error ? null : buildYieldPlan(plan, contract, result, completion, handoff);
-
-  return {
-    ack,
-    progress: {
-      enabled: contract.progressMode !== "none",
-      mode: contract.progressMode,
-      afterSeconds: contract.progressAfterSeconds,
-      maxSilenceSeconds: contract.maxSilenceSeconds,
-      target: contract.pingbackTarget,
-      message:
-        contract.progressMode === "none"
-          ? null
-          : `Still working on ${plan.job.id}. Send a progress ping before ${contract.maxSilenceSeconds}s of silence.`
-    },
-    completion,
-    handoff,
-    yield: yieldPlan,
-    error: {
-      required: contract.notifyOnError,
-      signal: contract.failureSignal,
-      target: contract.pingbackTarget,
-      message: error
-        ? `[${contract.failureSignal}] ${plan.job.id}: ${trimValue(error.message || error)}`
-        : null
-    }
-  };
-}
+import { parseContractOutput } from "./output-contract-validator.js";
+
+function dedupe(items) {
+  return [...new Set((items || []).map((item) => String(item).trim()).filter(Boolean))];
+}
+
+function normalizeSectionKey(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[\s-]+/g, "_")
+    .trim();
+}
+
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function trimValue(value, limit = 220) {
+  const text = normalizeText(value);
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 3)}...`;
+}
+
+function normalizeNextActions(nextActions = []) {
+  return (nextActions || [])
+    .map((item) => {
+      if (typeof item === "string") return normalizeText(item);
+      if (item && typeof item === "object") {
+        const action = normalizeText(item.action || "");
+        const details = normalizeText(item.details || item.summary || "");
+        return [action, details].filter(Boolean).join(": ");
+      }
+      return normalizeText(item);
+    })
+    .filter(Boolean);
+}
+
+export function normalizeInteractionContract(contract = null) {
+  const raw = contract || {};
+  const progressAfterSeconds = raw.progressAfterSeconds ?? 90;
+  const handoff = raw.handoff || {};
+  const yieldConfig = raw.yield || {};
+
+  return {
+    ackMode: raw.ackMode || "immediate",
+    ackText: raw.ackText || null,
+    progressMode: raw.progressMode || "long_running",
+    progressAfterSeconds,
+    maxSilenceSeconds: raw.maxSilenceSeconds ?? Math.max(progressAfterSeconds * 2, 180),
+    notifyOnDone: raw.notifyOnDone ?? true,
+    notifyOnError: raw.notifyOnError ?? true,
+    requiresPingback: raw.requiresPingback ?? true,
+    pingbackTarget: raw.pingbackTarget || "same_thread",
+    completionSignal: raw.completionSignal || "done",
+    failureSignal: raw.failureSignal || "error",
+    handoffFormat: raw.handoffFormat || "structured_handoff",
+    completionSections: dedupe(raw.completionSections || ["status", "next_actions"]),
+    includeNextActions: raw.includeNextActions ?? true,
+    handoff: {
+      enabled: handoff.enabled ?? false,
+      signal: handoff.signal || raw.handoffSignal || "peer_handoff",
+      target: handoff.target || raw.handoffTarget || null,
+      deliveryProfile: handoff.deliveryProfile || raw.handoffDeliveryProfile || null,
+      capabilityQuery: handoff.capabilityQuery || raw.handoffCapabilityQuery || null,
+      preferredTaskClasses: dedupe(handoff.preferredTaskClasses || raw.handoffPreferredTaskClasses || []),
+      trustLevel: handoff.trustLevel || raw.handoffTrustLevel || null,
+      maxSuggestions: handoff.maxSuggestions ?? raw.handoffMaxSuggestions ?? 3,
+      messagePrefix: handoff.messagePrefix || raw.handoffMessagePrefix || null
+    },
+    yield: {
+      enabled: yieldConfig.enabled ?? raw.yieldEnabled ?? false,
+      signal: yieldConfig.signal || raw.yieldSignal || "follow_up",
+      targetSurface: yieldConfig.targetSurface || raw.yieldTargetSurface || "operator_review",
+      followUpObjective: yieldConfig.followUpObjective || raw.followUpObjective || null
+    }
+  };
+}
+
+export function resolveInteractionContract(agentContract = null, jobContract = null) {
+  return normalizeInteractionContract({
+    ...(agentContract || {}),
+    ...(jobContract || {})
+  });
+}
+
+export function formatInteractionContract(contract) {
+  if (!contract) return "";
+
+  const lines = [
+    `- ack mode: ${contract.ackMode}`,
+    `- progress mode: ${contract.progressMode}`,
+    `- progress after seconds: ${contract.progressAfterSeconds}`,
+    `- max silence seconds: ${contract.maxSilenceSeconds}`,
+    `- requires pingback: ${contract.requiresPingback}`,
+    `- pingback target: ${contract.pingbackTarget}`,
+    `- notify on done: ${contract.notifyOnDone}`,
+    `- notify on error: ${contract.notifyOnError}`,
+    `- completion signal: ${contract.completionSignal}`,
+    `- handoff format: ${contract.handoffFormat}`
+  ];
+
+  if (contract.completionSections?.length) {
+    lines.push(`- completion sections: ${contract.completionSections.join(", ")}`);
+  }
+  if (contract.handoff?.enabled) {
+    lines.push(`- handoff enabled: yes`);
+    if (contract.handoff.capabilityQuery) lines.push(`- handoff capability query: ${contract.handoff.capabilityQuery}`);
+    if (contract.handoff.preferredTaskClasses?.length) {
+      lines.push(`- handoff preferred tasks: ${contract.handoff.preferredTaskClasses.join(", ")}`);
+    }
+    if (contract.handoff.target) {
+      lines.push(`- handoff target: ${typeof contract.handoff.target === "string" ? contract.handoff.target : JSON.stringify(contract.handoff.target)}`);
+    }
+  }
+  if (contract.yield?.enabled) {
+    lines.push(`- yield enabled: yes`);
+    lines.push(`- yield target surface: ${contract.yield.targetSurface}`);
+  }
+
+  return lines.join("\n");
+}
+
+function outputSectionMap(output, result, contract = null) {
+  const entries = [];
+  if (contract?.requiredSections?.length) {
+    const parsed = parseContractOutput(output, contract);
+    for (const section of contract.requiredSections) {
+      const key = normalizeSectionKey(section);
+      entries.push([key, trimValue(parsed.sections.get(key) || "None")]);
+    }
+  } else if (output && typeof output === "object" && !Array.isArray(output)) {
+    for (const [key, value] of Object.entries(output)) {
+      entries.push([normalizeSectionKey(key), trimValue(value)]);
+    }
+  }
+
+  entries.push(["status", trimValue(result.summary || "Completed.")]);
+  entries.push(["summary", trimValue(result.summary || "Completed.")]);
+  const nextActions = normalizeNextActions(result.nextActions || []);
+  entries.push(["next_actions", nextActions.length ? nextActions.join("; ") : "None"]);
+  entries.push(["next", nextActions.length ? nextActions.join("; ") : "None"]);
+  entries.push(["handoff", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
+  entries.push(["evidence", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
+  entries.push(["changes", trimValue(typeof output === "string" ? output : JSON.stringify(output || result.output || ""))]);
+  entries.push(["verification", nextActions.length ? nextActions.join("; ") : "No explicit verification captured."]);
+  entries.push(["issues", "None"]);
+
+  return new Map(entries);
+}
+
+function buildCompletionSections(contract, result) {
+  const output = result.output;
+  const map = outputSectionMap(output, result, result.outputContract || null);
+
+  return contract.completionSections.map((section) => ({
+    key: normalizeSectionKey(section),
+    label: String(section)
+      .replace(/_/g, " ")
+      .replace(/\b\w/g, (char) => char.toUpperCase()),
+    value: map.get(normalizeSectionKey(section)) || "None"
+  }));
+}
+
+function renderCompletionMessage(plan, contract, sections) {
+  if (contract.handoffFormat === "concise_status") {
+    const status = sections.find((section) => section.key === "status")?.value || plan.job.id;
+    const next = sections.find((section) => section.key === "next_actions")?.value || "None";
+    return `[${contract.completionSignal}] ${status} | next: ${next}`;
+  }
+
+  if (contract.handoffFormat === "coding_completion") {
+    const lines = [`${contract.completionSignal.toUpperCase()}: ${plan.job.id}`];
+    for (const section of sections) {
+      lines.push(`${section.label}: ${section.value}`);
+    }
+    return lines.join("\n");
+  }
+
+  return [
+    `${contract.completionSignal.toUpperCase()}: ${plan.job.id}`,
+    ...sections.map((section) => `- ${section.label}: ${section.value}`)
+  ].join("\n");
+}
+
+function normalizeHandoffTarget(target, deliveryProfile = null) {
+  if (!target) return null;
+  if (typeof target === "string") {
+    return {
+      mode: "peer_agent",
+      peerId: target,
+      deliveryProfile
+    };
+  }
+  return {
+    ...target,
+    deliveryProfile: target.deliveryProfile || deliveryProfile || null
+  };
+}
+
+function buildHandoffMessage(plan, contract, sections, suggestions = []) {
+  const status = sections.find((section) => section.key === "status")?.value || resultSummaryFallback(plan);
+  const nextActions = sections.find((section) => section.key === "next_actions")?.value || "None";
+  const lines = [];
+
+  if (contract.handoff.messagePrefix) {
+    lines.push(contract.handoff.messagePrefix);
+  }
+  lines.push(`[${contract.handoff.signal}] ${plan.job.id}`);
+  lines.push(`Status: ${status}`);
+  lines.push(`Next Actions: ${nextActions}`);
+
+  if (suggestions.length) {
+    lines.push(`Suggested Peers: ${suggestions.map((item) => item.label).join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+function resultSummaryFallback(plan) {
+  return `${plan.job.id} completed.`;
+}
+
+function buildHandoffPlan(plan, contract, sections, suggestions = []) {
+  if (!contract.handoff?.enabled) return null;
+
+  const target = normalizeHandoffTarget(contract.handoff.target, contract.handoff.deliveryProfile);
+  return {
+    required: true,
+    signal: contract.handoff.signal,
+    target,
+    deliveryProfile: contract.handoff.deliveryProfile || target?.deliveryProfile || null,
+    suggestions: suggestions.slice(0, contract.handoff.maxSuggestions || 3),
+    capabilityQuery: contract.handoff.capabilityQuery || null,
+    preferredTaskClasses: contract.handoff.preferredTaskClasses || [],
+    sections,
+    nextActions: contract.includeNextActions ? sections.find((section) => section.key === "next_actions")?.value?.split("; ").filter(Boolean) || [] : [],
+    message: buildHandoffMessage(plan, contract, sections, suggestions)
+  };
+}
+
+function buildYieldPlan(plan, contract, result, completion, handoff) {
+  if (!contract.yield?.enabled) return null;
+
+  return {
+    required: true,
+    signal: contract.yield.signal,
+    targetSurface: contract.yield.targetSurface || "operator_review",
+    objective:
+      contract.yield.followUpObjective ||
+      `Continue ${plan.job.id} follow-up in a bounded next step without extending the current turn.`,
+    followUp: {
+      sourceJobId: plan.job.id,
+      sourceAgentId: plan.agent?.id || plan.packet?.agentId || null,
+      signal: contract.yield.signal,
+      objective:
+        contract.yield.followUpObjective ||
+        `Continue ${plan.job.id} follow-up in a bounded next step without extending the current turn.`,
+      targetSurface: contract.yield.targetSurface || "operator_review",
+      sections: completion?.sections || [],
+      nextActions: result.nextActions || [],
+      completion: completion?.required
+        ? {
+            signal: completion.signal,
+            target: completion.target,
+            handoffFormat: completion.handoffFormat,
+            sections: completion.sections || [],
+            nextActions: completion.nextActions || [],
+            message: completion.message
+          }
+        : null,
+      handoff: handoff?.required
+        ? {
+            signal: handoff.signal,
+            target: handoff.target || null,
+            deliveryProfile: handoff.deliveryProfile || null,
+            suggestions: handoff.suggestions || [],
+            capabilityQuery: handoff.capabilityQuery || null,
+            preferredTaskClasses: handoff.preferredTaskClasses || [],
+            sections: handoff.sections || [],
+            nextActions: handoff.nextActions || [],
+            message: handoff.message
+          }
+        : null
+    }
+  };
+}
+
+export function buildInteractionPlan(plan, result, error = null, options = {}) {
+  const contract = normalizeInteractionContract(plan.packet.layers.interactionContract);
+  result.outputContract = plan.packet.layers.outputContract || null;
+
+  const ack =
+    contract.ackMode === "silent"
+      ? {
+          required: false,
+          mode: contract.ackMode,
+          target: contract.pingbackTarget,
+          message: null
+        }
+      : {
+          required: true,
+          mode: contract.ackMode,
+          target: contract.pingbackTarget,
+          message:
+            contract.ackText ||
+            `Acknowledged ${plan.job.id}. I will ping back with ${contract.completionSignal} when the run is finished.`
+        };
+
+  const completionSections = buildCompletionSections(contract, result);
+  const handoff = buildHandoffPlan(plan, contract, completionSections, options.handoffSuggestions || []);
+  const completion = {
+    required: contract.notifyOnDone || contract.requiresPingback,
+    signal: contract.completionSignal,
+    target: contract.pingbackTarget,
+    handoffFormat: contract.handoffFormat,
+    sections: completionSections,
+    nextActions: contract.includeNextActions ? result.nextActions || [] : [],
+    message: renderCompletionMessage(plan, contract, completionSections)
+  };
+  const yieldPlan = error ? null : buildYieldPlan(plan, contract, result, completion, handoff);
+
+  return {
+    ack,
+    progress: {
+      enabled: contract.progressMode !== "none",
+      mode: contract.progressMode,
+      afterSeconds: contract.progressAfterSeconds,
+      maxSilenceSeconds: contract.maxSilenceSeconds,
+      target: contract.pingbackTarget,
+      message:
+        contract.progressMode === "none"
+          ? null
+          : `Still working on ${plan.job.id}. Send a progress ping before ${contract.maxSilenceSeconds}s of silence.`
+    },
+    completion,
+    handoff,
+    yield: yieldPlan,
+    error: {
+      required: contract.notifyOnError,
+      signal: contract.failureSignal,
+      target: contract.pingbackTarget,
+      message: error
+        ? `[${contract.failureSignal}] ${plan.job.id}: ${trimValue(error.message || error)}`
+        : null
+    }
+  };
+}