nemoris 0.1.0

package/src/runtime/status-aggregator.js

@@ -0,0 +1,330 @@
+import path from "node:path";
+import { ConfigLoader } from "../config/loader.js";
+import { MemoryStore } from "../memory/memory-store.js";
+import { NotificationStore } from "./notification-store.js";
+import { DeliveryStore } from "./delivery-store.js";
+import { PeerRegistry } from "./peer-registry.js";
+import { SchedulerStateStore } from "./scheduler-state.js";
+import { computeNextRun } from "./schedule.js";
+import { ProviderRegistry } from "../providers/registry.js";
+
+function _safeCount(arr) {
+  return Array.isArray(arr) ? arr.length : 0;
+}
+
+function _safeSlice(arr, n) {
+  return Array.isArray(arr) ? arr.slice(0, n) : [];
+}
+
+function resolveEmbeddingsStatus(enabled) {
+  if (enabled === false) return "disabled";
+  if (enabled === true) return "enabled";
+  return "unknown";
+}
+
+function shouldHideJobFromUserStatus(job) {
+  return job?.id === "memory-rollup" && job?.lastStatus === "error";
+}
+
+async function collectAgents(runtime, memoryStore) {
+  const agents = [];
+  for (const [agentId, agent] of Object.entries(runtime.agents || {})) {
+    let memoryHealth;
+    try {
+      const paths = await memoryStore.initAgent(agentId);
+      const sqlite = await memoryStore.ensureSqliteStore(paths);
+      memoryHealth = {
+        totalEntries: sqlite.count(),
+        embeddingHealth: sqlite.getEmbeddingHealth()
+      };
+    } catch {
+      memoryHealth = { totalEntries: 0, embeddingHealth: null, error: "unable_to_read" };
+    }
+
+    agents.push({
+      id: agentId,
+      primaryLane: agent.primaryLane || null,
+      fallbackLane: agent.fallbackLane || null,
+      memoryPolicy: agent.memoryPolicy || null,
+      toolPolicy: agent.toolPolicy || null,
+      deliveryProfile: agent.delivery?.profile || null,
+      memoryHealth
+    });
+  }
+  return agents;
+}
+
+function collectJobs(runtime, schedulerState) {
+  const jobs = [];
+  const jobStates = schedulerState?.jobs || {};
+  for (const [jobId, jobConfig] of Object.entries(runtime.jobs || {})) {
+    const state = jobStates[jobId] || {};
+    let nextDue = null;
+    try {
+      if (jobConfig.trigger) {
+        nextDue = computeNextRun(jobConfig.trigger, new Date()).toISOString();
+      }
+    } catch {
+      // trigger may not be parseable without context
+    }
+
+    jobs.push({
+      id: jobId,
+      trigger: jobConfig.trigger || null,
+      taskType: jobConfig.taskType || null,
+      agentId: jobConfig.agentId || null,
+      lastRunAt: state.lastRunAt || null,
+      lastStatus: state.lastStatus || null,
+      nextDue
+    });
+  }
+  return jobs;
+}
+
+function collectProviders(runtime, providerRegistry) {
+  const providers = [];
+  for (const [providerId, providerConfig] of Object.entries(runtime.providers || {})) {
+    let capabilities;
+    try {
+      const desc = providerRegistry.describe(providerConfig);
+      capabilities = desc.capabilities || null;
+    } catch {
+      capabilities = null;
+    }
+
+    providers.push({
+      id: providerId,
+      adapter: providerConfig.adapter || providerId,
+      baseUrl: providerConfig.baseUrl || null,
+      capabilities
+    });
+  }
+  return providers;
+}
+
+async function collectDelivery(deliveryStore, runtime) {
+  const deliveryConfig = runtime.delivery || {};
+  const profiles = Object.keys(deliveryConfig.profiles || {});
+  let recentFailureCount = 0;
+  let totalRecords = 0;
+
+  try {
+    const index = await deliveryStore.loadIndex();
+    const records = Object.values(index.delivered || {});
+    totalRecords = records.length;
+    recentFailureCount = records.filter(
+      (record) => record.status === "failed" || record.status === "uncertain"
+    ).length;
+  } catch {
+    // delivery store may not exist yet
+  }
+
+  return {
+    profiles,
+    defaultInteractiveProfile: deliveryConfig.defaultInteractiveProfile || null,
+    defaultSchedulerProfile: deliveryConfig.defaultSchedulerProfile || null,
+    standaloneMode: Boolean(
+      process.env.NEMORIS_STANDALONE === "1" ||
+      process.env.NEMORIS_STANDALONE === "true" ||
+      deliveryConfig.standaloneMode
+    ),
+    totalRecords,
+    recentFailureCount
+  };
+}
+
+function collectPeers(runtime) {
+  const peerRegistry = new PeerRegistry(runtime.peers || {});
+  const peers = peerRegistry.list();
+  return peers.map((peer) => ({
+    peerId: peer.peerId,
+    label: peer.label || peer.peerId,
+    agentId: peer.agentId || null,
+    deliveryProfile: peer.deliveryProfile || null,
+    sessionKeys: peer.sessionKeys || [],
+    hasCard: Boolean(peer.card)
+  }));
+}
+
+function collectRuntime(runtime, notifications) {
+  const retention = runtime.runtime?.retention || {};
+  const concurrency = runtime.runtime?.concurrency || {};
+  const retrieval = runtime.runtime?.retrieval || {};
+
+  const followUps = (notifications || []).filter((n) => n.stage === "follow_up");
+  const pendingFollowUps = followUps.filter((n) => n.status === "pending");
+  const handoffs = (notifications || []).filter((n) => n.stage === "handoff");
+  const pendingHandoffs = handoffs.filter(
+    (n) => n.status === "awaiting_choice" || n.handoffState === "pending"
+  );
+
+  return {
+    concurrency: {
+      maxJobsPerTick: concurrency.maxJobsPerTick ?? concurrency.maxConcurrentJobs ?? 2
+    },
+    embeddings: {
+      enabled: runtime.embeddings?.enabled ?? null
+    },
+    retention: {
+      runs: retention.runs || {},
+      notifications: retention.notifications || {},
+      deliveries: retention.deliveries || {}
+    },
+    retrieval: {
+      lexicalWeight: retrieval.lexicalWeight ?? null,
+      embeddingWeight: retrieval.embeddingWeight ?? null,
+      recencyWeight: retrieval.recencyWeight ?? null
+    },
+    followUpStats: {
+      total: followUps.length,
+      pending: pendingFollowUps.length
+    },
+    handoffStats: {
+      total: handoffs.length,
+      pending: pendingHandoffs.length
+    }
+  };
+}
+
+export async function buildRuntimeStatus(options = {}) {
+  const {
+    projectRoot,
+    stateRoot,
+    liveRoot: _liveRoot,
+    // Allow injecting dependencies for testing
+    configLoader,
+    memoryStore,
+    notificationStore,
+    deliveryStore,
+    schedulerStateStore,
+    providerRegistry
+  } = options;
+
+  const loader = configLoader || new ConfigLoader({ rootDir: path.join(projectRoot, "config") });
+  const memory = memoryStore || new MemoryStore({ rootDir: path.join(stateRoot, "memory") });
+  const notifications = notificationStore || new NotificationStore({ rootDir: path.join(stateRoot, "notifications") });
+  const deliveries = deliveryStore || new DeliveryStore({ rootDir: path.join(stateRoot, "deliveries") });
+  const stateStore = schedulerStateStore || new SchedulerStateStore({ rootDir: path.join(stateRoot, "scheduler") });
+  const registry = providerRegistry || new ProviderRegistry();
+
+    let runtime;
+  let configErrors = [];
+  try {
+    runtime = await loader.loadAll();
+  } catch (err) {
+    // Hard validation error or config parse failure — return degraded status
+    configErrors = (err.validationErrors?.map((e) => e.details || e.code) || [err.message || "Unknown config error"]).filter(Boolean);
+    try {
+      runtime = await loader.loadAll({ skipValidation: true });
+    } catch {
+      return {
+        status: "degraded",
+        configErrors,
+      };
+    }
+  }
+
+  const [schedulerState, allNotifications, agents] = await Promise.all([
+    stateStore.load().catch(() => ({ jobs: {} })),
+    notifications.listAll().catch(() => []),
+    collectAgents(runtime, memory)
+  ]);
+
+  const [deliveryStatus, jobs, providers, peers, runtimeStats] = await Promise.all([
+    collectDelivery(deliveries, runtime),
+    Promise.resolve(collectJobs(runtime, schedulerState)),
+    Promise.resolve(collectProviders(runtime, registry)),
+    Promise.resolve(collectPeers(runtime)),
+    Promise.resolve(collectRuntime(runtime, allNotifications))
+  ]);
+
+  return {
+    timestamp: new Date().toISOString(),
+    agents,
+    jobs,
+    providers,
+    delivery: deliveryStatus,
+    peers,
+    runtime: runtimeStats
+  };
+}
+
+export function formatRuntimeStatus(status) {
+  // Early exit for degraded status — avoid shape mismatches with partial config
+  if (status.status === "degraded") {
+    const lines = [
+      "=== Nemoris V2 Runtime Status ===",
+      `Timestamp: ${status.timestamp || new Date().toISOString()}`,
+      "",
+      "⚠  Status: degraded — run `nemoris doctor` for details",
+    ];
+    for (const err of (status.configErrors || [])) {
+      lines.push(`   • ${err}`);
+    }
+    return lines.join("\n");
+  }
+
+  const lines = [];
+  const embeddingsStatus = resolveEmbeddingsStatus(status.runtime?.embeddings?.enabled);
+  const visibleJobs = (status.jobs || []).filter((job) => !shouldHideJobFromUserStatus(job));
+
+  lines.push("=== Nemoris V2 Runtime Status ===");
+  lines.push(`Timestamp: ${status.timestamp}`);
+  if (status.configErrors?.length) {
+    lines.push("");
+    lines.push(`⚠  Config validation: ${status.configErrors.length} issue(s)`);
+    for (const err of status.configErrors) {
+      lines.push(`   • ${err}`);
+    }
+  }
+  lines.push("");
+
+  // Agents
+  lines.push(`--- Agents (${status.agents.length}) ---`);
+  for (const agent of status.agents) {
+    const memEntries = agent.memoryHealth?.totalEntries ?? "?";
+    lines.push(`  ${agent.id}`);
+    lines.push(`    lane: ${agent.primaryLane || "(none)"}  memory entries: ${memEntries}  embeddings: ${embeddingsStatus}`);
+  }
+  lines.push("");
+
+  // Jobs
+  lines.push(`--- Jobs (${visibleJobs.length}) ---`);
+  for (const job of visibleJobs) {
+    const lastRun = job.lastRunAt ? `last: ${job.lastRunAt}` : "last: never";
+    const lastStatus = job.lastStatus ? `status: ${job.lastStatus}` : "status: (none)";
+    const next = job.nextDue ? `next: ${job.nextDue}` : "next: (unknown)";
+    lines.push(`  ${job.id}  [${job.trigger || "?"}]`);
+    lines.push(`    ${lastRun}  ${lastStatus}  ${next}`);
+  }
+  lines.push("");
+
+  // Providers
+  lines.push(`--- Providers (${status.providers.length}) ---`);
+  for (const provider of status.providers) {
+    lines.push(`  ${provider.id} (${provider.adapter})  ${provider.baseUrl || "(no url)"}`);
+  }
+  lines.push("");
+
+  // Delivery
+  lines.push("--- Delivery ---");
+  lines.push(`  profiles: ${status.delivery.profiles.join(", ") || "(none)"}`);
+  lines.push(`  standalone: ${status.delivery.standaloneMode}`);
+  lines.push(`  records: ${status.delivery.totalRecords}  failures: ${status.delivery.recentFailureCount}`);
+  lines.push("");
+
+  // Peers
+  lines.push(`--- Peers (${status.peers.length}) ---`);
+  for (const peer of status.peers) {
+    lines.push(`  ${peer.peerId}  label: ${peer.label}  card: ${peer.hasCard ? "yes" : "no"}`);
+  }
+  lines.push("");
+
+  // Runtime
+  lines.push("--- Runtime ---");
+  lines.push(`  max jobs/tick: ${status.runtime.concurrency.maxJobsPerTick}`);
+  lines.push(`  follow-ups: ${status.runtime.followUpStats.total} total, ${status.runtime.followUpStats.pending} pending`);
+  lines.push(`  handoffs: ${status.runtime.handoffStats.total} total, ${status.runtime.handoffStats.pending} pending`);
+
+  return lines.join("\n");
+}

package/src/runtime/task-contract.js

@@ -0,0 +1,140 @@
+import { ulid } from "./ulid.js";
+
+const VALID_TRANSITIONS = {
+  created: ["accepted", "rejected"],
+  accepted: ["running", "rejected"],
+  running: ["completed", "failed", "cancelled", "timed_out"],
+  timed_out: ["escalated"],
+};
+
+export class TaskContract {
+  constructor(db, envelopeStore) {
+    this.db = db;
+    this.envelopes = envelopeStore;
+    this._ensureSchema();
+  }
+
+  _ensureSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS tasks (
+        task_id           TEXT PRIMARY KEY,
+        envelope_id       TEXT NOT NULL,
+        owner_agent       TEXT NOT NULL,
+        assigned_agent    TEXT NOT NULL,
+        status            TEXT NOT NULL DEFAULT 'created',
+        objective         TEXT NOT NULL,
+        deadline_at       TEXT NOT NULL,
+        result_slot       TEXT,
+        error_slot        TEXT,
+        escalation_chain  TEXT NOT NULL,
+        escalation_index  INTEGER NOT NULL DEFAULT 0,
+        created_at        TEXT NOT NULL,
+        updated_at        TEXT NOT NULL,
+        FOREIGN KEY (envelope_id) REFERENCES envelopes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+      CREATE INDEX IF NOT EXISTS idx_tasks_assigned ON tasks(assigned_agent);
+      CREATE INDEX IF NOT EXISTS idx_tasks_deadline ON tasks(deadline_at);
+    `);
+  }
+
+  createTask({ ownerAgent, assignedAgent, objective, deadlineMinutes, escalationChain = ["assigned", "owner", "operator"] }) {
+    const taskId = ulid();
+    const now = new Date();
+    const deadlineAt = new Date(now.getTime() + deadlineMinutes * 60 * 1000).toISOString();
+    const envelope = this.envelopes.create({
+      sourceAgent: ownerAgent,
+      criticality: "result",
+      payloadType: "task",
+      payload: { objective, assignedAgent, deadlineMinutes },
+    });
+    this.db.prepare(`
+      INSERT INTO tasks (task_id, envelope_id, owner_agent, assigned_agent, status, objective, deadline_at, escalation_chain, escalation_index, created_at, updated_at)
+      VALUES (?, ?, ?, ?, 'created', ?, ?, ?, 0, ?, ?)
+    `).run(taskId, envelope.id, ownerAgent, assignedAgent, objective.slice(0, 500), deadlineAt, JSON.stringify(escalationChain), now.toISOString(), now.toISOString());
+    return this.get(taskId);
+  }
+
+  get(taskId) {
+    return this.db.prepare("SELECT * FROM tasks WHERE task_id = ?").get(taskId) || null;
+  }
+
+  transition(taskId, newStatus, callerAgent, { result, error } = {}) {
+    const task = this.get(taskId);
+    if (!task) throw new Error(`Task ${taskId} not found`);
+    const allowed = VALID_TRANSITIONS[task.status];
+    if (!allowed || !allowed.includes(newStatus)) {
+      throw new Error(`Invalid transition: ${task.status} → ${newStatus}`);
+    }
+    // Permission checks
+    if (newStatus === "cancelled" && callerAgent !== task.owner_agent) {
+      throw new Error("Only owner can cancel a task");
+    }
+    const assignedOnly = ["accepted", "running", "completed", "failed", "rejected"];
+    if (assignedOnly.includes(newStatus) && callerAgent !== task.assigned_agent) {
+      throw new Error(`Only assigned agent can transition to ${newStatus}`);
+    }
+    const now = new Date().toISOString();
+    const updates = { status: newStatus, updated_at: now };
+    if (result !== undefined) {
+      updates.result_slot = typeof result === "string" ? result : JSON.stringify(result);
+      if (updates.result_slot.length > 4000) {
+        updates.result_slot = JSON.stringify({
+          ledger_ref: `overflow-${taskId}`,
+          summary: updates.result_slot.slice(0, 200),
+        });
+      }
+    }
+    if (error !== undefined) {
+      updates.error_slot = typeof error === "string" ? error : JSON.stringify(error);
+    }
+    const setClauses = Object.keys(updates).map((k) => `${k} = ?`).join(", ");
+    const values = [...Object.values(updates), taskId];
+    this.db.prepare(`UPDATE tasks SET ${setClauses} WHERE task_id = ?`).run(...values);
+    return this.get(taskId);
+  }
+
+  listByStatus(status) {
+    return this.db.prepare("SELECT * FROM tasks WHERE status = ? ORDER BY created_at DESC").all(status);
+  }
+
+  listTimedOut() {
+    const now = new Date().toISOString();
+    return this.db.prepare("SELECT * FROM tasks WHERE status = 'running' AND deadline_at < ?").all(now);
+  }
+
+  sweepTimedOutTasks() {
+    const now = new Date().toISOString();
+    const overdue = this.db.prepare("SELECT * FROM tasks WHERE status = 'running' AND deadline_at < ?").all(now);
+    for (const task of overdue) {
+      this.db.prepare("UPDATE tasks SET status = 'timed_out', updated_at = ? WHERE task_id = ?").run(now, task.task_id);
+    }
+    return overdue;
+  }
+
+  advanceEscalation(taskId) {
+    const task = this.get(taskId);
+    if (!task) throw new Error(`Task ${taskId} not found`);
+    if (!["timed_out", "escalated"].includes(task.status)) {
+      throw new Error(`Cannot escalate task in status: ${task.status}`);
+    }
+    const chain = JSON.parse(task.escalation_chain);
+    const newIndex = task.escalation_index + 1;
+    this.db.prepare("UPDATE tasks SET escalation_index = ?, updated_at = ? WHERE task_id = ?")
+      .run(newIndex, new Date().toISOString(), taskId);
+    if (newIndex >= chain.length) {
+      this.db.prepare("UPDATE tasks SET status = 'escalated', updated_at = ? WHERE task_id = ?")
+        .run(new Date().toISOString(), taskId);
+    }
+    return { escalationIndex: newIndex, target: chain[newIndex] || null, exhausted: newIndex >= chain.length };
+  }
+
+  getInbox() {
+    return this.db.prepare(`
+      SELECT * FROM tasks
+      WHERE status IN ('timed_out', 'escalated')
+      AND escalation_index >= json_array_length(escalation_chain)
+      ORDER BY created_at DESC
+    `).all();
+  }
+}

package/src/runtime/task-packet.js

@@ -0,0 +1,107 @@
+import { activeRecall } from "../memory/active-recall.js";
+
+function compactCheckpoint(checkpoint) {
+  if (!checkpoint) return null;
+  return {
+    objective: checkpoint.objective,
+    status: checkpoint.status,
+    nextActions: checkpoint.nextActions || [],
+    blockers: checkpoint.blockers || []
+  };
+}
+
+export async function buildTaskPacket({
+  agentId,
+  objective,
+  memoryStore,
+  backendManager = null,
+  workspaceRoot = null,
+  backendOrder = null,
+  qmdSupplementLimit = 2,
+  retrievalQueries = null,
+  identity = null,
+  interactionContract = null,
+  outputContract = null,
+  reportGuidance = null,
+  allowedTools = [],
+  artifactRefs = [],
+  budget = {},
+  checkpointId = "latest",
+  memoryLimit = 8,
+  retrievalBlend = null,
+  conversationContext = undefined
+}) {
+  const checkpoint = compactCheckpoint(await memoryStore.loadCheckpoint(agentId, checkpointId));
+  let memory;
+  const useActiveRecall = memoryStore?.queryRetrievalCandidates;
+  if (useActiveRecall) {
+    const tokenBudget = budget.maxTokens ? Math.min(2000, Math.floor(budget.maxTokens * 0.08)) : 2000;
+    const recallResult = await activeRecall({
+      inboundMessage: objective,
+      memoryStore,
+      tokenBudget,
+      topicRelevanceFn: null,
+    });
+    const items = [
+      ...recallResult.facts.map((c) => ({ ...c, tier: "fact" })),
+      ...recallResult.asides.map((c) => ({ ...c, tier: "aside" })),
+    ];
+    memory = { items, backends: null, retrieval: null };
+  } else {
+    memory = backendManager
+      ? await backendManager.queryCombined(agentId, objective, {
+          workspaceRoot,
+          backendOrder,
+          qmdSupplementLimit,
+          fileQuery: retrievalQueries?.fileQuery || objective,
+          qmdQuery: retrievalQueries?.qmdQuery || objective,
+          limit: memoryLimit,
+          retrievalBlend
+        })
+      : await memoryStore.query(agentId, objective, { limit: memoryLimit, retrievalBlend });
+  }
+
+  return {
+    agentId,
+    objective,
+    conversationContext: conversationContext || null,
+    budget: {
+      maxTokens: budget.maxTokens ?? 8000,
+      maxRuntimeSeconds: budget.maxRuntimeSeconds ?? 60
+    },
+    layers: {
+      systemRules: [
+        "Transcript is not the system of record.",
+        "Use checkpoint and memory before requesting more history.",
+        "Do not write durable memory without policy approval."
+      ],
+      identity,
+      interactionContract,
+      outputContract,
+      reportGuidance,
+      checkpoint,
+      retrieval: memory.backends || null,
+      retrievalMeta: memory.retrieval || null,
+      retrievalQueries,
+      memory: memory.items.map((item) => ({
+        entryId: item.entryId || null,
+        type: item.type || "memory",
+        category: item.category || "general",
+        title: item.title || "",
+        content: item.content || "",
+        summary: item.summary || "",
+        reason: item.reason || "",
+        score: Number((item.score ?? 0).toFixed(4)),
+        tier: item.tier || null,
+        sourceBackend: item.sourceBackend || "file",
+        candidateSource: item.candidateSource || "indexed",
+        lexicalScore: Number((item.lexicalScore ?? 0).toFixed(4)),
+        embeddingSimilarity: Number((item.embeddingSimilarity ?? 0).toFixed(4)),
+        embeddingFreshness: item.embeddingFreshness || "missing",
+        retrievalSources: item.retrievalSources || ["lexical"]
+      })),
+      tools: allowedTools,
+      artifacts: artifactRefs
+    }
+  };
+}