memorix 1.4.6 → 1.5.1

package/src/team/handoff.ts

@@ -1,87 +1,87 @@
-/**
- * Team Handoff — Structured context transfer between agents.
- *
- * Phase 4b: Creates a handoff artifact as a standard observation
- * (canonical path — no new JSON/file persistence).
- *
- * Architectural boundary (B4): The canonical record is an Observation
- * stored via storeObservation(). TeamStore only holds a reference pointer.
- * Handoff artifacts use valueCategory: 'core' so they are immune to
- * retention archival (Phase 1 provenance: core = immune).
- */
-
-import type { TeamStore } from './team-store.js';
-import type { ObservationType } from '../types.js';
-
-// ── Types ──────────────────────────────────────────────────────────
-
-export interface HandoffInput {
-  projectId: string;
-  fromAgentId: string;
-  toAgentId?: string;       // null = anyone can pick up
-  taskId?: string;           // link to specific task
-  summary: string;           // human-readable summary of what was done
-  context: string;           // machine-readable context for the next agent
-  filesModified?: string[];  // files touched during the work
-  concepts?: string[];       // key concepts for search discoverability
-}
-
-export interface HandoffResult {
-  observationId: number;
-  taskId?: string;
-  fromAgentId: string;
-  toAgentId?: string;
-  summary: string;
-}
-
-// ── createHandoffArtifact ──────────────────────────────────────────
-
-/**
- * Create a structured handoff artifact stored as an observation.
- *
- * @param input - Handoff details
- * @param storeObservation - The canonical storeObservation function (injected to avoid circular deps)
- * @param teamStore - For sending notification message to recipient
- */
-export async function createHandoffArtifact(
-  input: HandoffInput,
-  storeObservation: (params: {
-    entityName: string;
-    type: ObservationType;
-    title: string;
-    narrative: string;
-    facts?: string[];
-    filesModified?: string[];
-    concepts?: string[];
-    projectId: string;
-    topicKey?: string;
+/**
+ * Team Handoff — Structured context transfer between agents.
+ *
+ * Phase 4b: Creates a handoff artifact as a standard observation
+ * (canonical path — no new JSON/file persistence).
+ *
+ * Architectural boundary (B4): The canonical record is an Observation
+ * stored via storeObservation(). TeamStore only holds a reference pointer.
+ * Handoff artifacts use valueCategory: 'core' so they are immune to
+ * retention archival (Phase 1 provenance: core = immune).
+ */
+
+import type { TeamStore } from './team-store.js';
+import type { ObservationType } from '../types.js';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface HandoffInput {
+  projectId: string;
+  fromAgentId: string;
+  toAgentId?: string;       // null = anyone can pick up
+  taskId?: string;           // link to specific task
+  summary: string;           // human-readable summary of what was done
+  context: string;           // machine-readable context for the next agent
+  filesModified?: string[];  // files touched during the work
+  concepts?: string[];       // key concepts for search discoverability
+}
+
+export interface HandoffResult {
+  observationId: number;
+  taskId?: string;
+  fromAgentId: string;
+  toAgentId?: string;
+  summary: string;
+}
+
+// ── createHandoffArtifact ──────────────────────────────────────────
+
+/**
+ * Create a structured handoff artifact stored as an observation.
+ *
+ * @param input - Handoff details
+ * @param storeObservation - The canonical storeObservation function (injected to avoid circular deps)
+ * @param teamStore - For sending notification message to recipient
+ */
+export async function createHandoffArtifact(
+  input: HandoffInput,
+  storeObservation: (params: {
+    entityName: string;
+    type: ObservationType;
+    title: string;
+    narrative: string;
+    facts?: string[];
+    filesModified?: string[];
+    concepts?: string[];
+    projectId: string;
+    topicKey?: string;
     sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
     valueCategory?: 'core' | 'contextual' | 'ephemeral';
     visibility?: 'personal' | 'project' | 'team';
     sharedWithAgentIds?: string[];
     createdByAgentId?: string;
-  }) => Promise<{ observation: { id: number }; upserted: boolean }>,
-  teamStore: TeamStore,
-): Promise<HandoffResult> {
-  // Build facts from handoff context
-  const facts: string[] = [
-    `Handoff from agent ${input.fromAgentId}`,
-  ];
-  if (input.toAgentId) facts.push(`Intended recipient: ${input.toAgentId}`);
-  if (input.taskId) facts.push(`Related task: ${input.taskId}`);
-  facts.push(`Context: ${input.context}`);
-
-  // Store as observation — this IS the canonical record
-  const { observation } = await storeObservation({
-    entityName: 'team-handoff',
-    type: 'what-changed',
-    title: `[Handoff] ${input.summary}`,
-    narrative: input.context,
-    facts,
-    filesModified: input.filesModified,
-    concepts: ['handoff', ...(input.concepts ?? [])],
-    projectId: input.projectId,
-    topicKey: input.taskId ? `handoff:${input.taskId}:${input.fromAgentId}` : undefined,
+  }) => Promise<{ observation: { id: number }; upserted: boolean }>,
+  teamStore: TeamStore,
+): Promise<HandoffResult> {
+  // Build facts from handoff context
+  const facts: string[] = [
+    `Handoff from agent ${input.fromAgentId}`,
+  ];
+  if (input.toAgentId) facts.push(`Intended recipient: ${input.toAgentId}`);
+  if (input.taskId) facts.push(`Related task: ${input.taskId}`);
+  facts.push(`Context: ${input.context}`);
+
+  // Store as observation — this IS the canonical record
+  const { observation } = await storeObservation({
+    entityName: 'team-handoff',
+    type: 'what-changed',
+    title: `[Handoff] ${input.summary}`,
+    narrative: input.context,
+    facts,
+    filesModified: input.filesModified,
+    concepts: ['handoff', ...(input.concepts ?? [])],
+    projectId: input.projectId,
+    topicKey: input.taskId ? `handoff:${input.taskId}:${input.fromAgentId}` : undefined,
     sourceDetail: 'explicit',
     valueCategory: 'core',  // immune to retention archival
     // A direct handoff is not a project-wide memo. The sender retains access
@@ -90,85 +90,85 @@ export async function createHandoffArtifact(
     visibility: input.toAgentId ? 'personal' : 'team',
     ...(input.toAgentId ? { sharedWithAgentIds: [input.toAgentId] } : {}),
     createdByAgentId: input.fromAgentId,
-  });
-
-  // Emit handoff:created event (best-effort, process-local only).
-  // Happens AFTER canonical write succeeds — listener errors never affect the handoff.
-  try {
-    teamStore.getEventBus()?.emit('handoff:created', {
-      observationId: observation.id,
-      projectId: input.projectId,
-      fromAgent: input.fromAgentId,
-      toAgent: input.toAgentId,
-      taskId: input.taskId,
-    });
-  } catch {
-    // Best-effort: event emission failure never affects canonical handoff
-  }
-
-  // Send notification message to recipient.
-  // Broadcast handoff uses fanout-on-write (方案 A): instead of one NULL-recipient
-  // shared message, each active agent (excluding sender) gets their own copy.
-  // This prevents Agent A's markRead from consuming Agent B's unread state.
-  try {
-    if (input.toAgentId) {
-      // Role validation: if the handoff is linked to a task with required_role,
-      // verify the recipient's role matches before sending.
-      if (input.taskId) {
-        const task = teamStore.getTask(input.taskId);
-        if (task?.required_role) {
-          const recipient = teamStore.getAgent(input.toAgentId);
-          if (recipient && recipient.role !== task.required_role) {
-            // Log warning but don't block — handoff observation is still created
-            console.error(
-              `[memorix] Handoff role mismatch: task "${input.taskId}" requires role "${task.required_role}" but recipient "${input.toAgentId}" has role "${recipient.role}". Handoff proceeds but claim will be rejected.`
-            );
-          }
-        }
-      }
-      // Targeted handoff — single recipient-specific message
-      teamStore.sendMessage({
-        projectId: input.projectId,
-        senderAgentId: input.fromAgentId,
-        recipientAgentId: input.toAgentId,
-        type: 'handoff',
-        content: `Handoff: ${input.summary}`,
-        payload: {
-          observationId: observation.id,
-          taskId: input.taskId,
-          filesModified: input.filesModified,
-        },
-        taskId: input.taskId,
-      });
-    } else {
-      // Broadcast handoff — fanout to each active agent (excluding sender)
-      const agents = teamStore.listAgents(input.projectId, { status: 'active' });
-      for (const agent of agents) {
-        if (agent.agent_id === input.fromAgentId) continue;
-        teamStore.sendMessage({
-          projectId: input.projectId,
-          senderAgentId: input.fromAgentId,
-          recipientAgentId: agent.agent_id,
-          type: 'handoff',
-          content: `Handoff: ${input.summary}`,
-          payload: {
-            observationId: observation.id,
-            taskId: input.taskId,
-            filesModified: input.filesModified,
-          },
-          taskId: input.taskId,
-        });
-      }
-    }
-  } catch {
-    // Message sending is best-effort — handoff observation is the canonical record
-  }
-
-  return {
-    observationId: observation.id,
-    taskId: input.taskId,
-    fromAgentId: input.fromAgentId,
-    toAgentId: input.toAgentId,
-    summary: input.summary,
-  };
-}
+  });
+
+  // Emit handoff:created event (best-effort, process-local only).
+  // Happens AFTER canonical write succeeds — listener errors never affect the handoff.
+  try {
+    teamStore.getEventBus()?.emit('handoff:created', {
+      observationId: observation.id,
+      projectId: input.projectId,
+      fromAgent: input.fromAgentId,
+      toAgent: input.toAgentId,
+      taskId: input.taskId,
+    });
+  } catch {
+    // Best-effort: event emission failure never affects canonical handoff
+  }
+
+  // Send notification message to recipient.
+  // Broadcast handoff uses fanout-on-write (方案 A): instead of one NULL-recipient
+  // shared message, each active agent (excluding sender) gets their own copy.
+  // This prevents Agent A's markRead from consuming Agent B's unread state.
+  try {
+    if (input.toAgentId) {
+      // Role validation: if the handoff is linked to a task with required_role,
+      // verify the recipient's role matches before sending.
+      if (input.taskId) {
+        const task = teamStore.getTask(input.taskId);
+        if (task?.required_role) {
+          const recipient = teamStore.getAgent(input.toAgentId);
+          if (recipient && recipient.role !== task.required_role) {
+            // Log warning but don't block — handoff observation is still created
+            console.error(
+              `[memorix] Handoff role mismatch: task "${input.taskId}" requires role "${task.required_role}" but recipient "${input.toAgentId}" has role "${recipient.role}". Handoff proceeds but claim will be rejected.`
+            );
+          }
+        }
+      }
+      // Targeted handoff — single recipient-specific message
+      teamStore.sendMessage({
+        projectId: input.projectId,
+        senderAgentId: input.fromAgentId,
+        recipientAgentId: input.toAgentId,
+        type: 'handoff',
+        content: `Handoff: ${input.summary}`,
+        payload: {
+          observationId: observation.id,
+          taskId: input.taskId,
+          filesModified: input.filesModified,
+        },
+        taskId: input.taskId,
+      });
+    } else {
+      // Broadcast handoff — fanout to each active agent (excluding sender)
+      const agents = teamStore.listAgents(input.projectId, { status: 'active' });
+      for (const agent of agents) {
+        if (agent.agent_id === input.fromAgentId) continue;
+        teamStore.sendMessage({
+          projectId: input.projectId,
+          senderAgentId: input.fromAgentId,
+          recipientAgentId: agent.agent_id,
+          type: 'handoff',
+          content: `Handoff: ${input.summary}`,
+          payload: {
+            observationId: observation.id,
+            taskId: input.taskId,
+            filesModified: input.filesModified,
+          },
+          taskId: input.taskId,
+        });
+      }
+    }
+  } catch {
+    // Message sending is best-effort — handoff observation is the canonical record
+  }
+
+  return {
+    observationId: observation.id,
+    taskId: input.taskId,
+    fromAgentId: input.fromAgentId,
+    toAgentId: input.toAgentId,
+    summary: input.summary,
+  };
+}

package/src/team/poll.ts

@@ -1,132 +1,132 @@
-/**
- * Team Poll — Situational awareness for agents.
- *
- * Phase 4b: Provides `computeWatermark` (extracted from server.ts session_start)
- * and `computePoll` (full situational awareness in one call).
- *
- * Architectural boundary (B3): These are cross-process consistency mechanisms.
- * They read from SQLite (canonical truth), never from EventBus.
- */
-
-import type { TeamStore, TeamAgentRow, TeamTaskRow, TeamMessageRow } from './team-store.js';
-
-// ── Types ──────────────────────────────────────────────────────────
-
-export interface WatermarkResult {
-  lastSeenGeneration: number;
-  currentGeneration: number;
-  newObservationCount: number;
-}
-
-export interface PollResult {
-  agent: {
-    agentId: string;
-    status: string;
-    lastHeartbeat: number;
-  } | null;
-  watermark: WatermarkResult;
-  inbox: {
-    unreadCount: number;
-    messages: TeamMessageRow[];
-  };
-  tasks: {
-    myInProgress: TeamTaskRow[];
-    availableToClaim: TeamTaskRow[];
-    recentlyCompleted: TeamTaskRow[];
-    recentlyFailed: TeamTaskRow[];
-  };
-  team: {
-    activeAgents: TeamAgentRow[];
-    totalAgents: number;
-  };
-}
-
-// ── computeWatermark ───────────────────────────────────────────────
-
-/**
- * Compute the watermark for an agent: how many new observations
- * have appeared in this project since the agent's last session.
- *
- * Extracted from server.ts session_start to be shared by poll and session_start.
- *
- * @param lastSeenGeneration - Agent's last_seen_obs_generation from TeamStore
- * @param currentGeneration  - Current global generation from observation store
- * @param projectObservations - Pre-filtered observations for this project
- *                              with writeGeneration > lastSeenGeneration
- */
-export function computeWatermark(
-  lastSeenGeneration: number,
-  currentGeneration: number,
-  newObservationCount: number,
-): WatermarkResult {
-  return {
-    lastSeenGeneration,
-    currentGeneration,
-    newObservationCount,
-  };
-}
-
-// ── computePoll ────────────────────────────────────────────────────
-
-/**
- * Compute full situational awareness for an agent in one call.
- * Reads only from SQLite (TeamStore) — never from EventBus.
- *
- * @param teamStore - The TeamStore instance
- * @param projectId - Current project ID
- * @param agentId   - The requesting agent's ID (null if no agent registered)
- * @param watermark - Pre-computed watermark result
- */
-export function computePoll(
-  teamStore: TeamStore,
-  projectId: string,
-  agentId: string | null,
-  watermark: WatermarkResult,
-): PollResult {
-  // Agent info
-  let agent: PollResult['agent'] = null;
-  if (agentId) {
-    const row = teamStore.getAgent(agentId);
-    if (row) {
-      agent = {
-        agentId: row.agent_id,
-        status: row.status,
-        lastHeartbeat: row.last_heartbeat,
-      };
-    }
-  }
-
-  // Inbox
-  const unreadCount = agentId ? teamStore.getUnreadCount(projectId, agentId) : 0;
-  const messages = agentId ? teamStore.getInbox(projectId, agentId) : [];
-
-  // Tasks
-  const allTasks = teamStore.listTasks(projectId);
-  const myInProgress = agentId
-    ? allTasks.filter(t => t.assignee_agent_id === agentId && t.status === 'in_progress')
-    : [];
-
-  // Available to claim: pending, no assignee, all deps met
-  const pendingTasks = allTasks.filter(t => t.status === 'pending' && !t.assignee_agent_id);
-  const availableToClaim = pendingTasks.filter(t => {
-    const unmet = teamStore.getTaskDeps(t.task_id)
-      .map(depId => teamStore.getTask(depId))
-      .filter(dep => dep && dep.status !== 'completed');
-    return unmet.length === 0;
-  });
-
-  const recentlyCompleted = allTasks.filter(t => t.status === 'completed');
-  const recentlyFailed = allTasks.filter(t => t.status === 'failed');
-
-  // Team
-  const allAgents = teamStore.listAgents(projectId);
-  const activeAgents = allAgents.filter(a => a.status === 'active');
-
-  return {
-    agent,
-    watermark,
-    inbox: { unreadCount, messages },
-    tasks: { myInProgress, availableToClaim, recentlyCompleted, recentlyFailed },
-    team: { activeAgents, totalAgents: allAgents.length },
-  };
-}
+/**
+ * Team Poll — Situational awareness for agents.
+ *
+ * Phase 4b: Provides `computeWatermark` (extracted from server.ts session_start)
+ * and `computePoll` (full situational awareness in one call).
+ *
+ * Architectural boundary (B3): These are cross-process consistency mechanisms.
+ * They read from SQLite (canonical truth), never from EventBus.
+ */
+
+import type { TeamStore, TeamAgentRow, TeamTaskRow, TeamMessageRow } from './team-store.js';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface WatermarkResult {
+  lastSeenGeneration: number;
+  currentGeneration: number;
+  newObservationCount: number;
+}
+
+export interface PollResult {
+  agent: {
+    agentId: string;
+    status: string;
+    lastHeartbeat: number;
+  } | null;
+  watermark: WatermarkResult;
+  inbox: {
+    unreadCount: number;
+    messages: TeamMessageRow[];
+  };
+  tasks: {
+    myInProgress: TeamTaskRow[];
+    availableToClaim: TeamTaskRow[];
+    recentlyCompleted: TeamTaskRow[];
+    recentlyFailed: TeamTaskRow[];
+  };
+  team: {
+    activeAgents: TeamAgentRow[];
+    totalAgents: number;
+  };
+}
+
+// ── computeWatermark ───────────────────────────────────────────────
+
+/**
+ * Compute the watermark for an agent: how many new observations
+ * have appeared in this project since the agent's last session.
+ *
+ * Extracted from server.ts session_start to be shared by poll and session_start.
+ *
+ * @param lastSeenGeneration - Agent's last_seen_obs_generation from TeamStore
+ * @param currentGeneration  - Current global generation from observation store
+ * @param projectObservations - Pre-filtered observations for this project
+ *                              with writeGeneration > lastSeenGeneration
+ */
+export function computeWatermark(
+  lastSeenGeneration: number,
+  currentGeneration: number,
+  newObservationCount: number,
+): WatermarkResult {
+  return {
+    lastSeenGeneration,
+    currentGeneration,
+    newObservationCount,
+  };
+}
+
+// ── computePoll ────────────────────────────────────────────────────
+
+/**
+ * Compute full situational awareness for an agent in one call.
+ * Reads only from SQLite (TeamStore) — never from EventBus.
+ *
+ * @param teamStore - The TeamStore instance
+ * @param projectId - Current project ID
+ * @param agentId   - The requesting agent's ID (null if no agent registered)
+ * @param watermark - Pre-computed watermark result
+ */
+export function computePoll(
+  teamStore: TeamStore,
+  projectId: string,
+  agentId: string | null,
+  watermark: WatermarkResult,
+): PollResult {
+  // Agent info
+  let agent: PollResult['agent'] = null;
+  if (agentId) {
+    const row = teamStore.getAgent(agentId);
+    if (row) {
+      agent = {
+        agentId: row.agent_id,
+        status: row.status,
+        lastHeartbeat: row.last_heartbeat,
+      };
+    }
+  }
+
+  // Inbox
+  const unreadCount = agentId ? teamStore.getUnreadCount(projectId, agentId) : 0;
+  const messages = agentId ? teamStore.getInbox(projectId, agentId) : [];
+
+  // Tasks
+  const allTasks = teamStore.listTasks(projectId);
+  const myInProgress = agentId
+    ? allTasks.filter(t => t.assignee_agent_id === agentId && t.status === 'in_progress')
+    : [];
+
+  // Available to claim: pending, no assignee, all deps met
+  const pendingTasks = allTasks.filter(t => t.status === 'pending' && !t.assignee_agent_id);
+  const availableToClaim = pendingTasks.filter(t => {
+    const unmet = teamStore.getTaskDeps(t.task_id)
+      .map(depId => teamStore.getTask(depId))
+      .filter(dep => dep && dep.status !== 'completed');
+    return unmet.length === 0;
+  });
+
+  const recentlyCompleted = allTasks.filter(t => t.status === 'completed');
+  const recentlyFailed = allTasks.filter(t => t.status === 'failed');
+
+  // Team
+  const allAgents = teamStore.listAgents(projectId);
+  const activeAgents = allAgents.filter(a => a.status === 'active');
+
+  return {
+    agent,
+    watermark,
+    inbox: { unreadCount, messages },
+    tasks: { myInProgress, availableToClaim, recentlyCompleted, recentlyFailed },
+    team: { activeAgents, totalAgents: allAgents.length },
+  };
+}

package/src/timeout.ts

@@ -21,3 +21,70 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, label: string):
     );
   });
 }
+
+/**
+ * Run an operation with a deadline and an AbortSignal for cancellable work.
+ * Callers should pass the signal to fetch/embedding/LLM APIs they own.
+ */
+export function withTimeoutSignal<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  label: string,
+  parentSignal?: AbortSignal,
+): Promise<T> {
+  const controller = new AbortController();
+  const signal = parentSignal
+    ? AbortSignal.any([parentSignal, controller.signal])
+    : controller.signal;
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      if (timer !== undefined) clearTimeout(timer);
+      parentSignal?.removeEventListener('abort', onParentAbort);
+    };
+    const onParentAbort = () => {
+      if (settled || timedOut) return;
+      settled = true;
+      cleanup();
+      reject(parentSignal?.reason ?? new Error(`${label} aborted`));
+    };
+    parentSignal?.addEventListener('abort', onParentAbort, { once: true });
+
+    timer = setTimeout(() => {
+      if (settled) return;
+      timedOut = true;
+      controller.abort(new Error(`${label} timed out after ${ms}ms`));
+      settled = true;
+      cleanup();
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+
+    let pending: Promise<T>;
+    try {
+      pending = operation(signal);
+    } catch (error) {
+      settled = true;
+      cleanup();
+      reject(error);
+      return;
+    }
+
+    pending.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(timedOut ? new Error(`${label} timed out after ${ms}ms`) : error);
+      },
+    );
+  });
+}