nemoris 0.1.0

package/src/runtime/notifier.js

@@ -0,0 +1,256 @@
+import path from "node:path";
+import { NotificationStore } from "./notification-store.js";
+import { createRuntimeId } from "../utils/ids.js";
+
+function iso() {
+  return new Date().toISOString();
+}
+
+function toTarget(target) {
+  if (!target) return { mode: "same_thread" };
+  if (typeof target === "string") return { mode: target };
+  return target;
+}
+
+function buildDedupeKey(stage, runId, signal) {
+  return `${stage}:${runId}:${signal || "none"}`;
+}
+
+export class InteractionNotifier {
+  constructor({ stateRoot }) {
+    this.store = new NotificationStore({ rootDir: path.join(stateRoot, "notifications") });
+  }
+
+  configureRetention(retention = {}) {
+    this.store.setRetentionPolicy(retention);
+  }
+
+  async queueAck(plan, context = {}) {
+    const contract = plan?.packet?.layers?.interactionContract;
+    if (!contract || contract.ackMode === "silent") return null;
+
+    const notification = {
+      id: createRuntimeId("notification"),
+      timestamp: iso(),
+      jobId: plan.job.id,
+      stage: "ack",
+      status: "queued",
+      dedupeKey: buildDedupeKey("ack", context.runId || plan.job.id, contract.ackMode),
+      deliveryProfile: plan.agent?.deliveryProfile || null,
+      signal: contract.ackMode,
+      target: toTarget(contract.pingbackTarget),
+      message: contract.ackText || `Acknowledged ${plan.job.id}. I will ping back when the run is complete.`,
+      mode: context.mode || null,
+      providerId: context.providerId || null,
+      modelId: context.modelId || null,
+      routingDecision: context.routingDecision || null,
+      maxSilenceSeconds: contract.maxSilenceSeconds ?? null
+    };
+
+    const filePath = await this.store.saveNotification(plan.job.id, notification);
+    return { filePath, ...notification };
+  }
+
+  async queueCompletion(run) {
+    const completion = run?.interaction?.completion;
+    if (!completion?.required) return null;
+
+    const notification = {
+      id: createRuntimeId("notification"),
+      timestamp: iso(),
+      jobId: run.plan.job.id,
+      stage: "completion",
+      status: "ready",
+      dedupeKey: buildDedupeKey("completion", run.id || run.timestamp || run.plan.job.id, completion.signal),
+      deliveryProfile: run.plan.agent?.deliveryProfile || null,
+      signal: completion.signal,
+      target: toTarget(completion.target),
+      message: completion.message,
+      mode: run.mode,
+      providerId: run.providerId,
+      modelId: run.modelId,
+      routingDecision: run.routingDecision,
+      sections: completion.sections || [],
+      nextActions: completion.nextActions || [],
+      sourceRunTimestamp: run.timestamp
+    };
+
+    const filePath = await this.store.saveNotification(run.plan.job.id, notification);
+    return { filePath, ...notification };
+  }
+
+  async queueHandoff(run) {
+    const handoff = run?.interaction?.handoff;
+    if (!handoff?.required) return null;
+
+    const notification = {
+      id: createRuntimeId("notification"),
+      handoffId: createRuntimeId("handoff"),
+      timestamp: iso(),
+      jobId: run.plan.job.id,
+      stage: "handoff",
+      status: handoff.target ? "ready" : "awaiting_choice",
+      handoffState: handoff.target ? "chosen" : "pending",
+      dedupeKey: buildDedupeKey("handoff", run.id || run.timestamp || run.plan.job.id, handoff.signal),
+      deliveryProfile: handoff.deliveryProfile || run.plan.agent?.deliveryProfile || null,
+      signal: handoff.signal,
+      target: handoff.target || null,
+      suggestedPeers: handoff.suggestions || [],
+      capabilityQuery: handoff.capabilityQuery || null,
+      preferredTaskClasses: handoff.preferredTaskClasses || [],
+      message: handoff.message,
+      mode: run.mode,
+      providerId: run.providerId,
+      modelId: run.modelId,
+      routingDecision: run.routingDecision,
+      sections: handoff.sections || [],
+      nextActions: handoff.nextActions || [],
+      sourceRunTimestamp: run.timestamp
+    };
+
+    const filePath = await this.store.saveNotification(run.plan.job.id, notification);
+    return { filePath, ...notification };
+  }
+
+  async queueError({ plan, error, context = {} }) {
+    const contract = plan?.packet?.layers?.interactionContract;
+    if (!contract?.notifyOnError) return null;
+
+    const notification = {
+      id: createRuntimeId("notification"),
+      timestamp: iso(),
+      jobId: plan.job.id,
+      stage: "error",
+      status: "ready",
+      dedupeKey: buildDedupeKey("error", context.runId || context.timestamp || plan.job.id, contract.failureSignal || "error"),
+      deliveryProfile: plan.agent?.deliveryProfile || null,
+      signal: contract.failureSignal || "error",
+      target: toTarget(contract.pingbackTarget),
+      message: `[${contract.failureSignal || "error"}] ${plan.job.id}: ${error.message || String(error)}`,
+      mode: context.mode || null,
+      providerId: context.providerId || null,
+      modelId: context.modelId || null,
+      routingDecision: context.routingDecision || null,
+      sourceRunTimestamp: context.timestamp || null
+    };
+
+    const filePath = await this.store.saveNotification(plan.job.id, notification);
+    return { filePath, ...notification };
+  }
+
+  async queueFollowUp(run) {
+    const yieldPlan = run?.interaction?.yield;
+    if (!yieldPlan?.required) return null;
+
+    const notification = {
+      id: createRuntimeId("notification"),
+      followUpId: createRuntimeId("followup"),
+      timestamp: iso(),
+      jobId: run.plan.job.id,
+      stage: "follow_up",
+      status: "pending",
+      followUpState: "pending",
+      yieldState: "pending",
+      hidden: true,
+      signal: yieldPlan.signal,
+      targetSurface: yieldPlan.targetSurface,
+      objective: yieldPlan.objective,
+      dedupeKey: buildDedupeKey("follow_up", run.id || run.timestamp || run.plan.job.id, yieldPlan.signal),
+      payload: {
+        ...yieldPlan.followUp,
+        sourceRunId: run.id || null,
+        sourceRunTimestamp: run.timestamp
+      },
+      sourceRunId: run.id || null,
+      sourceRunTimestamp: run.timestamp,
+      parentIdempotencyKey: run.idempotencyKey || null
+    };
+
+    const filePath = await this.store.saveNotification(run.plan.job.id, notification);
+    return { filePath, ...notification };
+  }
+
+  async consumeFollowUp(notificationFilePath, options = {}) {
+    const followUp = await this.store.getNotification(notificationFilePath);
+    if (!followUp) {
+      throw new Error(`Follow-up notification not found: ${notificationFilePath}`);
+    }
+    if (followUp.stage !== "follow_up") {
+      throw new Error("Only follow_up notifications can be consumed.");
+    }
+    if (followUp.status !== "pending") {
+      throw new Error("Follow-up has already been consumed or is not pending.");
+    }
+
+    const created = [];
+    const payload = followUp.payload || {};
+    const timestamp = iso();
+
+    if (payload.completion) {
+      const completion = payload.completion;
+      const completionNotification = {
+        id: createRuntimeId("notification"),
+        timestamp,
+        jobId: followUp.jobId,
+        stage: "completion",
+        status: "ready",
+        dedupeKey: `completion:${followUp.followUpId}`,
+        deliveryProfile: options.completionDeliveryProfile || null,
+        signal: completion.signal,
+        target: toTarget(completion.target),
+        message: completion.message,
+        sections: completion.sections || [],
+        nextActions: completion.nextActions || [],
+        sourceRunId: followUp.sourceRunId || null,
+        sourceRunTimestamp: followUp.sourceRunTimestamp || null,
+        sourceFollowUpId: followUp.followUpId,
+        sourceFollowUpFilePath: followUp.filePath
+      };
+      const filePath = await this.store.saveNotification(followUp.jobId, completionNotification);
+      created.push({ filePath, ...completionNotification });
+    }
+
+    if (payload.handoff) {
+      const handoff = payload.handoff;
+      const handoffNotification = {
+        id: createRuntimeId("notification"),
+        handoffId: createRuntimeId("handoff"),
+        timestamp,
+        jobId: followUp.jobId,
+        stage: "handoff",
+        status: handoff.target ? "ready" : "awaiting_choice",
+        handoffState: handoff.target ? "chosen" : "pending",
+        dedupeKey: `handoff:${followUp.followUpId}:${handoff.signal}`,
+        deliveryProfile: handoff.deliveryProfile || null,
+        signal: handoff.signal,
+        target: handoff.target || null,
+        suggestedPeers: handoff.suggestions || [],
+        capabilityQuery: handoff.capabilityQuery || null,
+        preferredTaskClasses: handoff.preferredTaskClasses || [],
+        message: handoff.message,
+        sections: handoff.sections || [],
+        nextActions: handoff.nextActions || [],
+        sourceRunId: followUp.sourceRunId || null,
+        sourceRunTimestamp: followUp.sourceRunTimestamp || null,
+        sourceFollowUpId: followUp.followUpId,
+        sourceFollowUpFilePath: followUp.filePath
+      };
+      const filePath = await this.store.saveNotification(followUp.jobId, handoffNotification);
+      created.push({ filePath, ...handoffNotification });
+    }
+
+    const updated = await this.store.updateNotification(notificationFilePath, {
+      status: "consumed",
+      followUpState: "consumed",
+      yieldState: "consumed",
+      consumedAt: timestamp,
+      generatedNotificationFiles: created.map((item) => item.filePath),
+      generatedStages: created.map((item) => item.stage)
+    });
+
+    return {
+      followUp: updated,
+      created
+    };
+  }
+}

package/src/runtime/orchestrator.js

@@ -0,0 +1,53 @@
+export class Orchestrator {
+  #staticRoutes;
+  #agents;
+  #dynamicRouting;
+  #dynamicRouter;
+
+  constructor({ staticRoutes = {}, agents = {}, dynamicRouting = {}, dynamicRouter = null }) {
+    this.#staticRoutes = staticRoutes;
+    this.#agents = agents;
+    this.#dynamicRouting = dynamicRouting;
+    this.#dynamicRouter = dynamicRouter;
+  }
+
+  async route(jobId) {
+    // 1. Static route lookup
+    const staticTarget = this.#staticRoutes[jobId];
+    if (staticTarget && this.#agents[staticTarget]) {
+      return {
+        agentId: staticTarget,
+        method: "static",
+        reason: `static: ${jobId} → ${staticTarget}`,
+      };
+    }
+
+    // 2. Dynamic route (if enabled)
+    if (this.#dynamicRouting.enabled && this.#dynamicRouter) {
+      try {
+        const agentSummaries = Object.values(this.#agents).map(a => ({
+          id: a.id,
+          primary_lane: a.primary_lane,
+          description: a.description || a.id,
+        }));
+        const result = await this.#dynamicRouter(jobId, agentSummaries);
+        if (result?.agentId && this.#agents[result.agentId]) {
+          return {
+            agentId: result.agentId,
+            method: "dynamic",
+            reason: `dynamic: ${result.reasoning || "LLM routing"}`,
+          };
+        }
+      } catch (_err) {
+        // Dynamic routing failed — fall through to escalation
+      }
+    }
+
+    // 3. Escalation
+    return {
+      agentId: null,
+      method: "escalation",
+      reason: `No route found for job '${jobId}'. Escalating to operator.`,
+    };
+  }
+}

package/src/runtime/orphan-reaper.js

@@ -0,0 +1,41 @@
+const ORPHAN_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * On startup: mark stuck running jobs as failed.
+ * Jobs running for < 5 min are left alone (daemon may have just restarted briefly).
+ * Uses created_at as a proxy for when the job became running.
+ *
+ * @param {import('./scheduler-state.js').SchedulerStateStore} stateStore
+ * @returns {{ job_id: string }[]} reaped job rows
+ */
+export function reapOrphanedJobs(stateStore) {
+  // Ensure columns exist for result and completed_at tracking
+  _addColumnIfMissing(stateStore.db, "interactive_jobs", "result", "TEXT");
+  _addColumnIfMissing(stateStore.db, "interactive_jobs", "completed_at", "TEXT");
+  _addColumnIfMissing(stateStore.db, "interactive_jobs", "started_at", "TEXT");
+
+  const cutoff = new Date(Date.now() - ORPHAN_THRESHOLD_MS).toISOString();
+  const now = new Date().toISOString();
+
+  const reaped = stateStore.db.prepare(`
+    UPDATE interactive_jobs
+    SET status = 'failed',
+        result = json_object('error', 'Daemon restarted before job completed'),
+        completed_at = ?
+    WHERE status = 'running'
+    AND COALESCE(started_at, created_at) < ?
+    RETURNING job_id
+  `).all(now, cutoff);
+
+  if (reaped.length > 0) {
+    console.log(`[startup] reaped ${reaped.length} orphaned job(s)`);
+  }
+  return reaped;
+}
+
+function _addColumnIfMissing(db, table, column, type) {
+  const cols = db.prepare(`pragma table_info(${table})`).all();
+  if (!cols.some((c) => c.name === column)) {
+    db.exec(`alter table ${table} add column ${column} ${type}`);
+  }
+}

package/src/runtime/output-contract-schema.js

@@ -0,0 +1,139 @@
+function titleCase(value) {
+  return String(value || "")
+    .split(/[_\-\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function buildBulletedBriefingOutputSchema(contract) {
+  const properties = {};
+  const required = [];
+
+  if (contract.profile?.requireStatus) {
+    properties.status = {
+      type: "string",
+      description: "One-line overall status."
+    };
+    required.push("status");
+  }
+
+  for (const section of contract.requiredSections || []) {
+    properties[section] = {
+      type: "string",
+      description: `${titleCase(section)} update. Use 'None' if there is no concrete data.`
+    };
+    required.push(section);
+  }
+
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required
+  };
+}
+
+function buildStructuredRollupOutputSchema(contract) {
+  const properties = {};
+  const required = [];
+
+  for (const section of contract.requiredSections || []) {
+    properties[section] = {
+      type: "array",
+      description: `${titleCase(section)} bullets. Use ['None'] if there is no concrete data.`,
+      minItems: contract.profile?.requireSectionItems ? 1 : 0,
+      items: {
+        type: "string"
+      }
+    };
+    required.push(section);
+  }
+
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required
+  };
+}
+
+function buildGenericOutputSchema(contract) {
+  const properties = {};
+  const required = [];
+
+  for (const section of contract.requiredSections || []) {
+    properties[section] = {
+      type: "string",
+      description: `${titleCase(section)} section content.`
+    };
+    required.push(section);
+  }
+
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required
+  };
+}
+
+function buildContractOutputSchema(contract) {
+  if (!contract) {
+    return {
+      type: "string"
+    };
+  }
+
+  if (contract.format === "bulleted_briefing") {
+    return buildBulletedBriefingOutputSchema(contract);
+  }
+
+  if (contract.format === "structured_rollup") {
+    return buildStructuredRollupOutputSchema(contract);
+  }
+
+  return buildGenericOutputSchema(contract);
+}
+
+export function compileOutputContractSchema(contract, options = {}) {
+  if (!contract) return null;
+  const thoughtFirst = options.thoughtFirst ?? false;
+
+  const properties = {};
+  const required = [];
+
+  if (thoughtFirst) {
+    properties.analysis = {
+      type: "string",
+      description: "Compact reasoning about the task before finalizing the structured result."
+    };
+    required.push("analysis");
+  }
+
+  properties.summary = {
+    type: "string",
+    description: "Short summary suitable for a completion pingback."
+  };
+  properties.output = buildContractOutputSchema(contract);
+  properties.nextActions = {
+    type: "array",
+    description: "Concrete next actions after the job result.",
+    items: {
+      type: "string"
+    }
+  };
+  required.push("summary", "output", "nextActions");
+
+  return {
+    name: contract.schemaName || `${String(contract.format || "bounded_output").replace(/[^a-z0-9]+/gi, "_").toLowerCase()}_response`,
+    thoughtFirst,
+    reasoningField: thoughtFirst ? "analysis" : null,
+    schema: {
+      type: "object",
+      additionalProperties: false,
+      properties,
+      required
+    }
+  };
+}