nemoris 0.1.0

package/src/runtime/interaction-contract.js

@@ -0,0 +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
+    }
+  };
+}

package/src/runtime/lane-readiness.js

@@ -0,0 +1,226 @@
+function truthy(value) {
+  return value === true;
+}
+
+function hasBlockingInteractionIssues(interaction = null) {
+  if (!interaction) return false;
+  return Boolean(
+    (interaction.deliveryEvidenceRequired && !interaction.deliveryEvidenceHealthy) ||
+    (interaction.yielded && interaction.followUpQueued && !interaction.followUpConsumed) ||
+    interaction.followUpExpired ||
+      interaction.handoffExpired ||
+      interaction.handoffBlocked ||
+      (interaction.handoffRequired && interaction.handoffQueued && !interaction.handoffChosen && !interaction.handoffPendingChoice) ||
+      interaction.deliveryUncertain
+  );
+}
+
+function summarizeFallback(reportFallback = null) {
+  if (!reportFallback) {
+    return {
+      configured: false,
+      ready: true,
+      blockedReasons: []
+    };
+  }
+
+  return {
+    configured: Boolean(reportFallback.jobConfigured),
+    ready: Boolean(!reportFallback.jobConfigured || reportFallback.ready),
+    blockedReasons: reportFallback.blockedReasons || []
+  };
+}
+
+function isStaleError(health) {
+  if (!health.lastError) return false;
+  if (!health.lastSuccessAt) return false;
+  const successMs = new Date(health.lastSuccessAt).getTime();
+  const errorMs = health.lastErrorAt ? new Date(health.lastErrorAt).getTime() : 0;
+  return successMs > errorMs;
+}
+
+function summarizeEmbeddings(embeddingHealth = null) {
+  const health = embeddingHealth?.embeddingHealth || embeddingHealth || null;
+  if (!health) {
+    return {
+      available: false,
+      healthy: false,
+      degraded: true,
+      blockedReasons: ["embedding_health_missing"]
+    };
+  }
+
+  const blockedReasons = [];
+  if (health.disabled) blockedReasons.push("embeddings_disabled");
+  if (health.lastError && !isStaleError(health)) blockedReasons.push("embedding_error");
+  if (health.missingCount > 0 && health.freshCount === 0) blockedReasons.push("embeddings_missing");
+  if (health.failedCount > 0) blockedReasons.push("embedding_failures");
+
+  return {
+    available: !health.disabled,
+    healthy: blockedReasons.length === 0,
+    degraded: blockedReasons.length > 0,
+    blockedReasons,
+    health
+  };
+}
+
+function reconcileEmbeddingsWithRetrieval(embeddings, retrieval) {
+  if (!embeddings) return embeddings;
+  if (!retrieval) return embeddings;
+
+  const retrievalShowsHealthyEmbeddingQuery =
+    retrieval.embeddingQueryMode === "embedding_query" &&
+    Number(retrieval.semanticCount || 0) > 0 &&
+    !retrieval.embeddingError &&
+    Number(retrieval.failedEmbeddingCount || 0) === 0;
+
+  if (!retrievalShowsHealthyEmbeddingQuery) {
+    return embeddings;
+  }
+
+  const blockedReasons = (embeddings.blockedReasons || []).filter((reason) => reason !== "embedding_error");
+  return {
+    ...embeddings,
+    healthy: blockedReasons.length === 0,
+    degraded: blockedReasons.length > 0,
+    blockedReasons
+  };
+}
+
+function buildEffectiveRetrieval(retrieval = null, embeddings = null) {
+  if (!retrieval) return null;
+
+  const effective = { ...retrieval };
+  const embeddingHealth = embeddings?.health || null;
+
+  // Only adopt the embedding health's lastQueryMode when the evaluation's
+  // own retrieval doesn't already show a healthy semantic result.  This
+  // prevents a stale "lexical_fallback" from overwriting a genuinely
+  // healthy "embedding_query" captured during the most recent run.
+  const evalAlreadyHealthy =
+    retrieval.embeddingQueryMode === "embedding_query" &&
+    Number(retrieval.semanticCount || 0) > 0 &&
+    !retrieval.embeddingError;
+
+  if (embeddingHealth?.lastQueryMode && !evalAlreadyHealthy) {
+    effective.embeddingQueryMode = embeddingHealth.lastQueryMode;
+  }
+
+  if (embeddings?.healthy && !embeddings.degraded) {
+    effective.embeddingError = null;
+    effective.failedEmbeddingCount = 0;
+  }
+
+  return effective;
+}
+
+export function buildLaneReadiness({
+  jobId,
+  job = null,
+  evaluation = null,
+  embeddingHealth = null,
+  reportFallback = null,
+  maintenance = null,
+  dependencyHealth = null
+} = {}) {
+  const interaction = evaluation?.interaction || null;
+  const retrieval = evaluation?.retrieval || null;
+  const contractCheck = evaluation?.contractCheck || null;
+  const rubric = evaluation?.rubric || null;
+  const embeddingSummary = summarizeEmbeddings(embeddingHealth);
+  const effectiveRetrieval = buildEffectiveRetrieval(retrieval, embeddingSummary);
+  const embeddings = reconcileEmbeddingsWithRetrieval(embeddingSummary, effectiveRetrieval);
+  const fallback = summarizeFallback(reportFallback);
+
+  const checks = {
+    contractHealthy:
+      contractCheck == null
+        ? true
+        : Number(contractCheck.satisfiedRatio ?? 0) >= 0.99 && (contractCheck.missingFromV2 || []).length === 0,
+    interactionHealthy: !hasBlockingInteractionIssues(interaction),
+    retrievalHealthy:
+      !effectiveRetrieval ||
+      (!effectiveRetrieval.embeddingError &&
+        effectiveRetrieval.embeddingQueryMode !== "lexical_fallback" &&
+        Number(effectiveRetrieval.failedEmbeddingCount || 0) === 0),
+    daemonHealthy:
+      !maintenance ||
+      ((maintenance.handoffs?.expiredCount || 0) === 0 && (maintenance.followUps?.expiredCount || 0) === 0),
+    providerReachable:
+      !dependencyHealth || dependencyHealth.provider?.reachable !== false,
+    deliveryReachable:
+      !dependencyHealth || dependencyHealth.delivery?.reachable !== false,
+    fallbackReady: fallback.ready
+  };
+
+  const blockers = [];
+  if (!checks.contractHealthy) blockers.push("output_contract_not_consistently_satisfied");
+  if (!checks.interactionHealthy) blockers.push("interaction_lifecycle_has_blocking_issues");
+  if (!checks.retrievalHealthy) blockers.push("retrieval_is_degraded_or_falling_back");
+  if (!checks.daemonHealthy) blockers.push("daemon_maintenance_detected_expired_items");
+  if (!checks.providerReachable) blockers.push("provider_unreachable");
+  if (embeddings.degraded) blockers.push(...embeddings.blockedReasons.map((item) => `embeddings:${item}`));
+
+  const warnings = [];
+  if (!checks.deliveryReachable) warnings.push("delivery_not_reachable");
+
+  const suggestions = [];
+  if (!checks.retrievalHealthy) {
+    suggestions.push("Repair embeddings or accept lexical-only mode before treating this lane as daily-driver ready.");
+  }
+  if (!checks.contractHealthy) {
+    suggestions.push("Keep contract adherence at 100% before cutover.");
+  }
+  if (!checks.interactionHealthy) {
+    suggestions.push("Resolve follow-up / handoff lifecycle issues before using this lane unattended.");
+  }
+  if (!checks.providerReachable) {
+    suggestions.push("Check provider health before treating this lane as trustworthy.");
+  }
+  if (!checks.deliveryReachable) {
+    suggestions.push("Delivery transport is not reachable. This does not block pilot readiness but should be resolved before daily-driver cutover.");
+  }
+  if (!checks.fallbackReady && fallback.configured) {
+    suggestions.push("Remote fallback is optional for this lane. Enable and validate it only if you want recovery from local failures.");
+  }
+  if (checks.contractHealthy && checks.interactionHealthy && checks.retrievalHealthy) {
+    suggestions.push("This lane is technically close to cutover; focus next on repeat-run validation and operator trust.");
+  }
+
+  let tier = "not_ready";
+  if (blockers.length === 0 && Number(rubric?.overallScore || 0) >= 0.95) {
+    tier = "ready_for_pilot";
+  } else if (blockers.length <= 2 && Number(rubric?.overallScore || 0) >= 0.85) {
+    tier = "close";
+  }
+
+  return {
+    jobId,
+    taskType: job?.taskType || null,
+    primaryLane: job?.modelLane || null,
+    readinessTier: tier,
+    readyForPilot: tier === "ready_for_pilot",
+    checks,
+    blockers: [...new Set(blockers)],
+    warnings,
+    suggestions,
+    summary: {
+      overallScore: rubric?.overallScore ?? null,
+      contractSatisfiedRatio: contractCheck?.satisfiedRatio ?? null,
+      yielded: truthy(interaction?.yielded),
+      followUpConsumed: truthy(interaction?.followUpConsumed),
+      handoffDelivered: truthy(interaction?.handoffDelivered),
+      embeddingQueryMode: effectiveRetrieval?.embeddingQueryMode || null,
+      semanticCount: effectiveRetrieval?.semanticCount ?? 0,
+      fallbackConfigured: fallback.configured,
+      fallbackReady: fallback.ready
+    },
+    interaction,
+    retrieval: effectiveRetrieval,
+    embeddings,
+    fallback,
+    maintenance,
+    dependencyHealth
+  };
+}