@remnic/core 1.1.12 → 1.1.14

package/src/legacy-hook-compat.ts

@@ -0,0 +1,45 @@
+import { compareVersions, type VersionTriple } from "./version-utils.js";
+
+const FIRST_PUBLISHED_RUNTIME_WITHOUT_AGENT_HEARTBEAT = [2026, 1, 29] as const;
+const OPENCLAW_VERSION_PREFIX = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/;
+
+type ParsedOpenClawVersion = {
+  triple: VersionTriple;
+  prerelease: boolean;
+};
+
+function parseOpenClawVersion(
+  value: string | undefined,
+): ParsedOpenClawVersion | null {
+  if (typeof value !== "string") return null;
+  const match = value.trim().match(OPENCLAW_VERSION_PREFIX);
+  if (!match) return null;
+  return {
+    triple: [
+      Number.parseInt(match[1], 10),
+      Number.parseInt(match[2], 10),
+      Number.parseInt(match[3], 10),
+    ],
+    prerelease: typeof match[4] === "string" && match[4].length > 0,
+  };
+}
+
+function parseOpenClawVersionTriple(
+  value: string | undefined,
+): VersionTriple | null {
+  return parseOpenClawVersion(value)?.triple ?? null;
+}
+
+export function shouldRegisterTypedAgentHeartbeat(
+  runtimeVersion: string | undefined,
+): boolean {
+  const parsed = parseOpenClawVersion(runtimeVersion);
+  if (!parsed) return false;
+  const comparison = compareVersions(
+    parsed.triple,
+    FIRST_PUBLISHED_RUNTIME_WITHOUT_AGENT_HEARTBEAT,
+  );
+  if (comparison < 0) return true;
+  if (comparison > 0) return false;
+  return parsed.prerelease;
+}

package/src/lifecycle.ts

@@ -0,0 +1,289 @@
+import type {
+  LifecycleState,
+  MemoryCategory,
+  MemoryFile,
+  MemoryFrontmatter,
+  VerificationState,
+} from "./types.js";
+
+export interface LifecyclePolicy {
+  promoteHeatThreshold: number;
+  staleDecayThreshold: number;
+  archiveDecayThreshold: number;
+  protectedCategories: MemoryCategory[];
+}
+
+export interface LifecycleSignals {
+  /**
+   * Optional relevance feedback in [-1, 1]. Negative values increase decay.
+   * Positive values raise heat.
+   */
+  feedbackScore?: number;
+  /**
+   * Optional bounded prior derived from memory-action outcomes in [-1, 1].
+   * This is intentionally low-impact to avoid circular amplification.
+   */
+  actionPriorScore?: number;
+  /**
+   * Optional causal impact score from CMC chain analysis in [0, 0.3].
+   * Computed as 0.1 * incomingEdges + 0.15 * outgoingEdges, clamped.
+   * Weight in heat/decay is intentionally low (0.05) to avoid circular amplification.
+   */
+  causalImpactScore?: number;
+}
+
+export interface LifecycleDecision {
+  currentState: LifecycleState;
+  nextState: LifecycleState;
+  heatScore: number;
+  decayScore: number;
+  changed: boolean;
+  reason: string;
+}
+
+export interface LifecycleValueInputs {
+  confidence: number;
+  access: number;
+  recency: number;
+  importance: number;
+  feedback: number;
+  disputedPenalty: number;
+}
+
+const DEFAULT_POLICY: LifecyclePolicy = {
+  promoteHeatThreshold: 0.55,
+  staleDecayThreshold: 0.65,
+  archiveDecayThreshold: 0.85,
+  protectedCategories: ["decision", "principle", "commitment", "preference", "procedure"],
+};
+
+export function clamp01(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+export function clampLifecycleThreshold(value: number): number {
+  return clamp01(value);
+}
+
+function parseIsoMs(value?: string): number | null {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+export function daysSince(value: string | undefined, nowMs: number): number {
+  const ts = parseIsoMs(value);
+  if (ts === null) return 365;
+  return Math.max(0, (nowMs - ts) / 86_400_000);
+}
+
+function confidenceTierWeight(frontmatter: MemoryFrontmatter): number {
+  switch (frontmatter.confidenceTier) {
+    case "explicit":
+      return 1;
+    case "implied":
+      return 0.8;
+    case "inferred":
+      return 0.6;
+    case "speculative":
+      return 0.35;
+    default:
+      return clamp01(frontmatter.confidence ?? 0.5);
+  }
+}
+
+function accessWeight(accessCount: number | undefined): number {
+  const raw = accessCount ?? 0;
+  if (raw <= 0) return 0;
+  return clamp01(Math.log1p(raw) / Math.log1p(20));
+}
+
+function recencyWeight(frontmatter: MemoryFrontmatter, nowMs: number): number {
+  const lastTouch = frontmatter.lastAccessed ?? frontmatter.updated ?? frontmatter.created;
+  const ageDays = daysSince(lastTouch, nowMs);
+  return clamp01(1 - ageDays / 90);
+}
+
+function feedbackWeight(signals?: LifecycleSignals): number {
+  const raw = (signals?.feedbackScore ?? 0) + (signals?.actionPriorScore ?? 0);
+  return clamp01((raw + 1) / 2);
+}
+
+function boundedFeedbackScore(signals?: LifecycleSignals): number {
+  const raw = (signals?.feedbackScore ?? 0) + (signals?.actionPriorScore ?? 0);
+  if (!Number.isFinite(raw)) return 0;
+  if (raw < -1) return -1;
+  if (raw > 1) return 1;
+  return raw;
+}
+
+function isProtectedMemory(
+  frontmatter: MemoryFrontmatter,
+  policy: LifecyclePolicy,
+): boolean {
+  return frontmatter.policyClass === "protected" || policy.protectedCategories.includes(frontmatter.category);
+}
+
+export function resolveLifecycleState(frontmatter: MemoryFrontmatter): LifecycleState {
+  if (frontmatter.status === "archived") return "archived";
+  return frontmatter.lifecycleState ?? "candidate";
+}
+
+export function computeHeat(
+  memory: Pick<MemoryFile, "frontmatter">,
+  now: Date,
+  signals?: LifecycleSignals,
+): number {
+  const frontmatter = memory.frontmatter;
+  if (frontmatter.status === "archived") return 0;
+
+  const inputs = computeLifecycleValueInputs(memory, now, signals);
+  const causalBoost = clamp01(signals?.causalImpactScore ?? 0) * 0.05;
+  const score = (inputs.confidence * 0.25)
+    + (inputs.access * 0.3)
+    + (inputs.recency * 0.2)
+    + (inputs.importance * 0.15)
+    + (inputs.feedback * 0.1)
+    + causalBoost
+    - inputs.disputedPenalty;
+  return clamp01(score);
+}
+
+export function computeLifecycleValueInputs(
+  memory: Pick<MemoryFile, "frontmatter">,
+  now: Date,
+  signals?: LifecycleSignals,
+): LifecycleValueInputs {
+  const frontmatter = memory.frontmatter;
+  const nowMs = now.getTime();
+  return {
+    confidence: confidenceTierWeight(frontmatter),
+    access: accessWeight(frontmatter.accessCount),
+    recency: recencyWeight(frontmatter, nowMs),
+    importance: clamp01(frontmatter.importance?.score ?? 0.5),
+    feedback: feedbackWeight(signals),
+    disputedPenalty: frontmatter.verificationState === "disputed" ? 0.2 : 0,
+  };
+}
+
+export function computeDecay(
+  memory: Pick<MemoryFile, "frontmatter">,
+  now: Date,
+  signals?: LifecycleSignals,
+): number {
+  const frontmatter = memory.frontmatter;
+  if (frontmatter.status === "archived") return 1;
+
+  const nowMs = now.getTime();
+  const ageDays = daysSince(frontmatter.updated ?? frontmatter.created, nowMs);
+  const staleAccessDays = daysSince(frontmatter.lastAccessed, nowMs);
+  const ageRisk = clamp01(ageDays / 180);
+  const staleAccessRisk = clamp01(staleAccessDays / 120);
+  const confidenceRisk = 1 - confidenceTierWeight(frontmatter);
+  const feedbackRisk = clamp01((boundedFeedbackScore(signals) * -1 + 1) / 2);
+  const heat = computeHeat(memory, now, signals);
+
+  const score = (ageRisk * 0.3)
+    + (staleAccessRisk * 0.25)
+    + (confidenceRisk * 0.2)
+    + (feedbackRisk * 0.1)
+    + ((1 - heat) * 0.15);
+
+  return clamp01(score);
+}
+
+function toTerminalDisputedState(
+  currentState: LifecycleState,
+): LifecycleState {
+  if (currentState === "archived") return "archived";
+  return "stale";
+}
+
+function isActiveEligible(verificationState?: VerificationState): boolean {
+  return verificationState === "user_confirmed" || verificationState === "system_inferred";
+}
+
+export function decideLifecycleTransition(
+  memory: Pick<MemoryFile, "frontmatter">,
+  policy: Partial<LifecyclePolicy>,
+  now: Date,
+  signals?: LifecycleSignals,
+): LifecycleDecision {
+  const mergedPolicy: LifecyclePolicy = { ...DEFAULT_POLICY, ...policy };
+  const frontmatter = memory.frontmatter;
+  const currentState = resolveLifecycleState(frontmatter);
+  const heatScore = computeHeat(memory, now, signals);
+  const decayScore = computeDecay(memory, now, signals);
+  const protectedMemory = isProtectedMemory(frontmatter, mergedPolicy);
+
+  if (currentState === "archived") {
+    return {
+      currentState,
+      nextState: "archived",
+      heatScore,
+      decayScore,
+      changed: false,
+      reason: "archived_is_terminal",
+    };
+  }
+
+  if (frontmatter.verificationState === "disputed") {
+    const nextState = toTerminalDisputedState(currentState);
+    return {
+      currentState,
+      nextState,
+      heatScore,
+      decayScore,
+      changed: nextState !== currentState,
+      reason: "disputed_memories_do_not_promote_to_active",
+    };
+  }
+
+  if (decayScore >= mergedPolicy.archiveDecayThreshold && !protectedMemory) {
+    return {
+      currentState,
+      nextState: "archived",
+      heatScore,
+      decayScore,
+      changed: true,
+      reason: "decay_exceeded_archive_threshold",
+    };
+  }
+
+  if (decayScore >= mergedPolicy.staleDecayThreshold) {
+    return {
+      currentState,
+      nextState: "stale",
+      heatScore,
+      decayScore,
+      changed: currentState !== "stale",
+      reason: "decay_exceeded_stale_threshold",
+    };
+  }
+
+  if (heatScore >= mergedPolicy.promoteHeatThreshold) {
+    const nextState = isActiveEligible(frontmatter.verificationState)
+      ? "active"
+      : "validated";
+    return {
+      currentState,
+      nextState,
+      heatScore,
+      decayScore,
+      changed: currentState !== nextState,
+      reason: "heat_exceeded_promote_threshold",
+    };
+  }
+
+  return {
+    currentState,
+    nextState: currentState,
+    heatScore,
+    decayScore,
+    changed: false,
+    reason: "no_transition",
+  };
+}

package/src/live-connectors-runner.ts

@@ -0,0 +1,385 @@
+import {
+  runConnectorPollOnce,
+  type ConnectorRunResult,
+} from "./connectors-cli.js";
+import {
+  createGitHubConnector,
+  createGmailConnector,
+  createGoogleDriveConnector,
+  createNotionConnector,
+  GITHUB_CONNECTOR_ID,
+  GITHUB_DEFAULT_POLL_INTERVAL_MS,
+  GMAIL_CONNECTOR_ID,
+  GMAIL_DEFAULT_POLL_INTERVAL_MS,
+  GOOGLE_DRIVE_CONNECTOR_ID,
+  GOOGLE_DRIVE_DEFAULT_POLL_INTERVAL_MS,
+  NOTION_CONNECTOR_ID,
+  NOTION_DEFAULT_POLL_INTERVAL_MS,
+  readConnectorState,
+  writeConnectorState,
+  validateGitHubConfig,
+  validateGmailConfig,
+  validateGoogleDriveConfig,
+  validateNotionConfig,
+  type ConnectorConfig,
+  type ConnectorCursor,
+  type ConnectorDocument,
+  type ConnectorState,
+  type LiveConnector,
+} from "./connectors/live/index.js";
+import type { LiveConnectorsConfig } from "./types.js";
+
+export type LiveConnectorSkipReason =
+  | "disabled"
+  | "not_due"
+  | "invalid_config"
+  | "state_read_error"
+  | "connector_error";
+
+export interface LiveConnectorRunItem {
+  id: string;
+  displayName: string;
+  enabled: boolean;
+  ran: boolean;
+  skippedReason?: LiveConnectorSkipReason;
+  docsImported: number;
+  error?: string;
+  stateWriteError?: string;
+  lastSyncAt: string | null;
+  nextDueAt: string | null;
+}
+
+export interface LiveConnectorsRunSummary {
+  ranAt: string;
+  force: boolean;
+  totalDocsImported: number;
+  ranCount: number;
+  skippedCount: number;
+  errorCount: number;
+  results: LiveConnectorRunItem[];
+}
+
+export interface LiveConnectorDefinition {
+  id: string;
+  displayName: string;
+  enabled: boolean;
+  pollIntervalMs: number;
+  rawConfig: unknown;
+  createConnector: () => LiveConnector;
+  validateConfig: (raw: unknown) => ConnectorConfig;
+}
+
+type LiveConnectorsNow = Date | (() => Date);
+
+export function builtInLiveConnectorDefinitions(
+  config: LiveConnectorsConfig,
+): LiveConnectorDefinition[] {
+  return [
+    {
+      id: GOOGLE_DRIVE_CONNECTOR_ID,
+      displayName: "Google Drive",
+      enabled: config.googleDrive.enabled,
+      pollIntervalMs:
+        config.googleDrive.pollIntervalMs ?? GOOGLE_DRIVE_DEFAULT_POLL_INTERVAL_MS,
+      rawConfig: config.googleDrive,
+      createConnector: createGoogleDriveConnector,
+      validateConfig: (raw) =>
+        validateGoogleDriveConfig(raw) as unknown as ConnectorConfig,
+    },
+    {
+      id: NOTION_CONNECTOR_ID,
+      displayName: "Notion",
+      enabled: config.notion.enabled,
+      pollIntervalMs: config.notion.pollIntervalMs ?? NOTION_DEFAULT_POLL_INTERVAL_MS,
+      rawConfig: config.notion,
+      createConnector: createNotionConnector,
+      validateConfig: (raw) =>
+        validateNotionConfig(raw) as unknown as ConnectorConfig,
+    },
+    {
+      id: GMAIL_CONNECTOR_ID,
+      displayName: "Gmail",
+      enabled: config.gmail.enabled,
+      pollIntervalMs: config.gmail.pollIntervalMs ?? GMAIL_DEFAULT_POLL_INTERVAL_MS,
+      rawConfig: config.gmail,
+      createConnector: createGmailConnector,
+      validateConfig: (raw) => validateGmailConfig(raw) as unknown as ConnectorConfig,
+    },
+    {
+      id: GITHUB_CONNECTOR_ID,
+      displayName: "GitHub",
+      enabled: config.github.enabled,
+      pollIntervalMs:
+        config.github.pollIntervalMs ?? GITHUB_DEFAULT_POLL_INTERVAL_MS,
+      rawConfig: config.github,
+      createConnector: createGitHubConnector,
+      validateConfig: (raw) => validateGitHubConfig(raw) as unknown as ConnectorConfig,
+    },
+  ];
+}
+
+export function hasEnabledLiveConnector(config: LiveConnectorsConfig): boolean {
+  return (
+    config.googleDrive.enabled ||
+    config.notion.enabled ||
+    config.gmail.enabled ||
+    config.github.enabled
+  );
+}
+
+export async function runLiveConnectorsOnce(options: {
+  memoryDir: string;
+  connectors: LiveConnectorsConfig;
+  ingestDocuments: (docs: ConnectorDocument[]) => Promise<void>;
+  force?: boolean;
+  now?: LiveConnectorsNow;
+  abortSignal?: AbortSignal;
+  definitions?: LiveConnectorDefinition[];
+}): Promise<LiveConnectorsRunSummary> {
+  const ranAt = resolveNow(options.now);
+  const force = options.force === true;
+  const definitions =
+    options.definitions ?? builtInLiveConnectorDefinitions(options.connectors);
+  const results: LiveConnectorRunItem[] = [];
+
+  for (const definition of definitions) {
+    const checkAt = resolveNow(options.now);
+    if (!definition.enabled) {
+      results.push(skipResult(definition, null, "disabled"));
+      continue;
+    }
+    let state: ConnectorState | null;
+    try {
+      state = await readConnectorState(options.memoryDir, definition.id);
+    } catch (err) {
+      results.push({
+        id: definition.id,
+        displayName: definition.displayName,
+        enabled: true,
+        ran: false,
+        skippedReason: "state_read_error",
+        docsImported: 0,
+        error: err instanceof Error ? err.message : String(err),
+        lastSyncAt: null,
+        nextDueAt: null,
+      });
+      continue;
+    }
+    if (!force && !isConnectorDue(state, definition.pollIntervalMs, checkAt)) {
+      results.push(skipResult(definition, state, "not_due"));
+      continue;
+    }
+
+    let validatedConfig: ConnectorConfig;
+    try {
+      validatedConfig = definition.validateConfig(definition.rawConfig);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      let stateWriteError: string | undefined;
+      let writtenErrorState: ConnectorState | undefined;
+      const errorAt = resolveNow(options.now);
+      try {
+        writtenErrorState = await writeConnectorErrorState({
+          memoryDir: options.memoryDir,
+          connectorId: definition.id,
+          state,
+          error: message,
+          now: errorAt,
+        });
+      } catch (writeErr) {
+        stateWriteError =
+          writeErr instanceof Error ? writeErr.message : String(writeErr);
+      }
+      const reportedState = writtenErrorState ?? state;
+      results.push({
+        id: definition.id,
+        displayName: definition.displayName,
+        enabled: true,
+        ran: false,
+        skippedReason: "invalid_config",
+        docsImported: 0,
+        error: message,
+        ...(stateWriteError !== undefined ? { stateWriteError } : {}),
+        lastSyncAt: reportedState?.lastSyncAt ?? null,
+        nextDueAt: nextDueAt(reportedState, definition.pollIntervalMs),
+      });
+      continue;
+    }
+
+    let runResult: ConnectorRunResult;
+    let lastStateWrittenAt: Date | undefined;
+    try {
+      const connector = definition.createConnector();
+      runResult = await runConnectorPollOnce({
+        connectorId: definition.id,
+        priorState: state,
+        syncFn: (cursor: ConnectorCursor | null) =>
+          connector.syncIncremental({
+            cursor,
+            config: validatedConfig,
+            abortSignal: options.abortSignal,
+          }),
+        ingestFn: options.ingestDocuments,
+        writeCursorFn: (writeState) => {
+          const writeAt = resolveNow(options.now);
+          return writeConnectorState(options.memoryDir, definition.id, {
+            id: definition.id,
+            cursor: writeState.cursor,
+            lastSyncAt: writeAt.toISOString(),
+            lastSyncStatus: writeState.lastSyncStatus,
+            ...(writeState.lastSyncError !== undefined
+              ? { lastSyncError: writeState.lastSyncError }
+              : {}),
+            totalDocsImported: writeState.totalDocsImported,
+          }).then(() => {
+            lastStateWrittenAt = writeAt;
+          });
+        },
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      let stateWriteError: string | undefined;
+      let writtenErrorState: ConnectorState | undefined;
+      const errorAt = resolveNow(options.now);
+      try {
+        writtenErrorState = await writeConnectorErrorState({
+          memoryDir: options.memoryDir,
+          connectorId: definition.id,
+          state,
+          error: message,
+          now: errorAt,
+        });
+      } catch (writeErr) {
+        stateWriteError =
+          writeErr instanceof Error ? writeErr.message : String(writeErr);
+      }
+      const reportedState = writtenErrorState ?? state;
+      results.push({
+        id: definition.id,
+        displayName: definition.displayName,
+        enabled: true,
+        ran: false,
+        skippedReason: "connector_error",
+        docsImported: 0,
+        error: message,
+        ...(stateWriteError !== undefined ? { stateWriteError } : {}),
+        lastSyncAt: reportedState?.lastSyncAt ?? null,
+        nextDueAt: nextDueAt(reportedState, definition.pollIntervalMs),
+      });
+      continue;
+    }
+    results.push(
+      runItemFromResult(
+        definition,
+        runResult,
+        state,
+        lastStateWrittenAt ?? resolveNow(options.now),
+      ),
+    );
+  }
+
+  return {
+    ranAt: ranAt.toISOString(),
+    force,
+    totalDocsImported: results.reduce((sum, item) => sum + item.docsImported, 0),
+    ranCount: results.filter((item) => item.ran).length,
+    skippedCount: results.filter((item) => !item.ran).length,
+    errorCount: results.filter(
+      (item) => item.error !== undefined || item.stateWriteError !== undefined,
+    ).length,
+    results,
+  };
+}
+
+function resolveNow(now: LiveConnectorsNow | undefined): Date {
+  return typeof now === "function" ? now() : now ?? new Date();
+}
+
+function isConnectorDue(
+  state: ConnectorState | null,
+  pollIntervalMs: number,
+  now: Date,
+): boolean {
+  if (state?.lastSyncAt === null || state?.lastSyncAt === undefined) return true;
+  const lastMs = Date.parse(state.lastSyncAt);
+  if (!Number.isFinite(lastMs)) return true;
+  return now.getTime() - lastMs >= Math.max(1, Math.floor(pollIntervalMs));
+}
+
+function nextDueAt(
+  state: ConnectorState | null,
+  pollIntervalMs: number,
+): string | null {
+  if (state?.lastSyncAt === null || state?.lastSyncAt === undefined) return null;
+  const lastMs = Date.parse(state.lastSyncAt);
+  if (!Number.isFinite(lastMs)) return null;
+  return new Date(lastMs + Math.max(1, Math.floor(pollIntervalMs))).toISOString();
+}
+
+function skipResult(
+  definition: LiveConnectorDefinition,
+  state: ConnectorState | null,
+  skippedReason: LiveConnectorSkipReason,
+): LiveConnectorRunItem {
+  return {
+    id: definition.id,
+    displayName: definition.displayName,
+    enabled: definition.enabled,
+    ran: false,
+    skippedReason,
+    docsImported: 0,
+    lastSyncAt: state?.lastSyncAt ?? null,
+    nextDueAt:
+      skippedReason === "not_due"
+        ? nextDueAt(state, definition.pollIntervalMs)
+        : null,
+  };
+}
+
+function runItemFromResult(
+  definition: LiveConnectorDefinition,
+  result: ConnectorRunResult,
+  priorState: ConnectorState | null,
+  now: Date,
+): LiveConnectorRunItem {
+  const stateWriteFailed = result.stateWriteError !== undefined;
+  const reportedLastSyncAt = stateWriteFailed
+    ? priorState?.lastSyncAt ?? null
+    : now.toISOString();
+  const reportedNextDueAt = stateWriteFailed
+    ? nextDueAt(priorState, definition.pollIntervalMs)
+    : new Date(
+        now.getTime() + Math.max(1, Math.floor(definition.pollIntervalMs)),
+      ).toISOString();
+
+  return {
+    id: definition.id,
+    displayName: definition.displayName,
+    enabled: definition.enabled,
+    ran: true,
+    docsImported: result.docsImported,
+    ...(result.error !== undefined ? { error: result.error } : {}),
+    ...(result.stateWriteError !== undefined
+      ? { stateWriteError: result.stateWriteError }
+      : {}),
+    lastSyncAt: reportedLastSyncAt,
+    nextDueAt: reportedNextDueAt,
+  };
+}
+
+async function writeConnectorErrorState(options: {
+  memoryDir: string;
+  connectorId: string;
+  state: ConnectorState | null;
+  error: string;
+  now: Date;
+}): Promise<ConnectorState> {
+  return writeConnectorState(options.memoryDir, options.connectorId, {
+    id: options.connectorId,
+    cursor: options.state?.cursor ?? null,
+    lastSyncAt: options.now.toISOString(),
+    lastSyncStatus: "error",
+    lastSyncError: options.error,
+    totalDocsImported: options.state?.totalDocsImported ?? 0,
+  });
+}