@remnic/core 9.18.0 → 9.20.0

package/src/meetings/cli.ts

@@ -0,0 +1,242 @@
+/**
+ * Meetings CLI runner (issue #1900) — one implementation shared by every CLI
+ * host (`remnic meetings ...` and `openclaw engram meetings ...`) so the
+ * surfaces never fork (same rule as the wearables/recall-explain runners).
+ *
+ * Flag validation is strict: value-taking flags require a value, unknown flags
+ * error with the valid list, malformed dates/ids reject loudly, and a missing
+ * record is a caller error — all `MeetingsInputError` → exit code 1 (CLAUDE.md
+ * rules 14 + 51). Backend faults bubble to the host's 500 handler.
+ */
+
+import { isValidTranscriptDate } from "../wearables/day-store.js";
+import type { MeetingsBuilder, MeetingsDayBuildSummary } from "./build.js";
+import { MeetingsInputError } from "./errors.js";
+import { meetingIdDate, type MeetingRecordStore, type MeetingRecordSummary } from "./store.js";
+import type { MeetingsConfig } from "./types.js";
+
+export interface MeetingsCliIo {
+  stdout: { write(chunk: string): unknown };
+  stderr: { write(chunk: string): unknown };
+}
+
+/** Everything the runner drives. Injected so tests wire a store + builder over
+ *  synthetic fixtures with no real filesystem. */
+export interface MeetingsCliDeps {
+  store: MeetingRecordStore;
+  builder: MeetingsBuilder;
+  /**
+   * Meetings config, so list/show honor `meetings.enabled`. The runner reads the
+   * store directly (not through an enabled-aware service), so without this gate a
+   * disabled subsystem would still expose stored records via list/show even
+   * though `build` refuses. Disabled => no exposure (issue #1900).
+   */
+  config: MeetingsConfig;
+}
+
+const USAGE = `Usage: meetings <command> [options]
+
+Commands:
+  list [--date <YYYY-MM-DD>]     List meeting records (all days, or one day)
+  show <meeting-id>              Print a stored meeting record
+  build --date <YYYY-MM-DD>      Detect + fuse + store the day's meetings
+
+Add --json to list/build for machine-readable output.
+`;
+
+const VALUE_FLAGS: Record<string, true> = { "--date": true };
+const BOOLEAN_FLAGS: Record<string, true> = { "--json": true };
+
+interface ParsedFlags {
+  flags: Map<string, string | true>;
+  positional: string[];
+}
+
+function parseFlags(args: string[]): ParsedFlags {
+  const flags = new Map<string, string | true>();
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    if (VALUE_FLAGS[arg] === true) {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new MeetingsInputError(`flag ${arg} requires a value`);
+      }
+      flags.set(arg, value);
+      i++;
+      continue;
+    }
+    if (BOOLEAN_FLAGS[arg] === true) {
+      flags.set(arg, true);
+      continue;
+    }
+    const known = [...Object.keys(VALUE_FLAGS), ...Object.keys(BOOLEAN_FLAGS)].sort().join(", ");
+    throw new MeetingsInputError(`unknown flag ${arg} (valid: ${known})`);
+  }
+  return { flags, positional };
+}
+
+function requireDate(parsed: ParsedFlags): string {
+  const value = parsed.flags.get("--date");
+  if (typeof value !== "string") {
+    throw new MeetingsInputError("--date <YYYY-MM-DD> is required");
+  }
+  if (!isValidTranscriptDate(value)) {
+    throw new MeetingsInputError(`--date must be a real YYYY-MM-DD; got '${value}'`);
+  }
+  return value;
+}
+
+function renderSummaryLine(summary: MeetingRecordSummary): string {
+  const attendees = summary.attendees.length > 0 ? summary.attendees.join(", ") : "(none)";
+  const sources = summary.sources.length > 0 ? summary.sources.join("+") : "(none)";
+  const corroborated =
+    summary.corroboratedBy.length > 0 ? ` corroborated=${summary.corroboratedBy.join("+")}` : "";
+  return (
+    `  ${summary.id}  ${summary.startUtc}–${summary.endUtc}  [${summary.detectionSource}]` +
+    ` sources=${sources}${corroborated} attendees=${attendees} snapshots=${summary.snapshotCount}`
+  );
+}
+
+function renderBuildSummary(summary: MeetingsDayBuildSummary): string {
+  if (!summary.enabled) {
+    return `meetings disabled — set meetings.enabled=true to build (${summary.date})`;
+  }
+  const lines = [
+    `${summary.date}: ${summary.meetings.length} meeting${summary.meetings.length === 1 ? "" : "s"} ` +
+      `(${summary.built} written, ${summary.skipped} unchanged, ${summary.removed.length} removed)`,
+  ];
+  for (const meeting of summary.meetings) {
+    const sources = meeting.sources.length > 0 ? meeting.sources.join("+") : "(none)";
+    lines.push(
+      `  ${meeting.id}  ${meeting.startUtc}–${meeting.endUtc}  [${meeting.detectionSource}]` +
+        ` sources=${sources} snapshots=${meeting.snapshotCount} ${meeting.written ? "written" : "unchanged"}`,
+    );
+  }
+  if (summary.reindexWarning !== undefined) {
+    lines.push(`  warning: ${summary.reindexWarning}`);
+  }
+  if (summary.memoryWarning !== undefined) {
+    lines.push(`  warning: ${summary.memoryWarning}`);
+  }
+  return lines.join("\n");
+}
+
+/** Run a meetings CLI command. Returns a process exit code; all output via `io`. */
+export async function runMeetingsCliCommand(
+  deps: MeetingsCliDeps,
+  args: string[],
+  io: MeetingsCliIo,
+): Promise<number> {
+  const [command, ...rest] = args;
+  try {
+    switch (command) {
+      case undefined:
+      case "help":
+      case "--help": {
+        io.stdout.write(USAGE);
+        return command === undefined ? 1 : 0;
+      }
+      case "list": {
+        const parsed = parseFlags(rest);
+        const json = parsed.flags.has("--json");
+        const dateFlag = parsed.flags.get("--date");
+        // Validate --date regardless of enabled state: a malformed --date is a
+        // caller error on every path, so it must reject before the disabled
+        // list short-circuit returns an empty result.
+        if (typeof dateFlag === "string" && !isValidTranscriptDate(dateFlag)) {
+          throw new MeetingsInputError(`--date must be a real YYYY-MM-DD; got '${dateFlag}'`);
+        }
+        if (!deps.config.enabled) {
+          if (json) {
+            io.stdout.write(typeof dateFlag === "string" ? "[]\n" : "{}\n");
+          } else {
+            io.stdout.write("meetings disabled — set meetings.enabled=true to build\n");
+          }
+          return 0;
+        }
+        if (typeof dateFlag === "string") {
+          const summaries = await deps.store.listMeetingSummaries(dateFlag);
+          if (json) {
+            io.stdout.write(`${JSON.stringify(summaries, null, 2)}\n`);
+            return 0;
+          }
+          if (summaries.length === 0) {
+            io.stdout.write(`No meetings for ${dateFlag}.\n`);
+            return 0;
+          }
+          io.stdout.write(`${dateFlag}:\n`);
+          for (const summary of summaries) io.stdout.write(`${renderSummaryLine(summary)}\n`);
+          return 0;
+        }
+        const dates = await deps.store.listMeetingDates();
+        if (json) {
+          const out: Record<string, MeetingRecordSummary[]> = {};
+          for (const date of dates) out[date] = await deps.store.listMeetingSummaries(date);
+          io.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+          return 0;
+        }
+        if (dates.length === 0) {
+          io.stdout.write("No meetings recorded.\n");
+          return 0;
+        }
+        for (const date of dates) {
+          const summaries = await deps.store.listMeetingSummaries(date);
+          io.stdout.write(`${date}:\n`);
+          for (const summary of summaries) io.stdout.write(`${renderSummaryLine(summary)}\n`);
+        }
+        return 0;
+      }
+      case "show": {
+        const parsed = parseFlags(rest);
+        if (!deps.config.enabled) {
+          io.stdout.write("meetings disabled — set meetings.enabled=true to build\n");
+          return 0;
+        }
+        const id = parsed.positional[0];
+        if (id === undefined) {
+          throw new MeetingsInputError("show requires a meeting id");
+        }
+        const date = meetingIdDate(id);
+        if (date === null) {
+          throw new MeetingsInputError(`invalid meeting id '${id}' — expected mtg-YYYY-MM-DD-<hash>`);
+        }
+        // meetingIdDate matches the id's SHAPE; a syntactically valid but
+        // impossible calendar date (e.g. mtg-2026-13-40-...) must surface as a
+        // clean input error, not a 500 from the store's path validator.
+        if (!isValidTranscriptDate(date)) {
+          throw new MeetingsInputError(`invalid meeting id '${id}' — '${date}' is not a real calendar date`);
+        }
+        const raw = await deps.store.readMeetingRecord(date, id);
+        if (raw === null) {
+          throw new MeetingsInputError(`meeting '${id}' not found`);
+        }
+        io.stdout.write(raw.endsWith("\n") ? raw : `${raw}\n`);
+        return 0;
+      }
+      case "build": {
+        const parsed = parseFlags(rest);
+        const date = requireDate(parsed);
+        const summary = await deps.builder.buildDay(date);
+        if (parsed.flags.has("--json")) {
+          io.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+          return 0;
+        }
+        io.stdout.write(`${renderBuildSummary(summary)}\n`);
+        return 0;
+      }
+      default:
+        throw new MeetingsInputError(`unknown meetings command '${command}'\n\n${USAGE}`);
+    }
+  } catch (err) {
+    if (err instanceof MeetingsInputError) {
+      io.stderr.write(`meetings: ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/meetings/config.test.ts

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { DEFAULT_MEETING_APP_PATTERNS } from "./detect.js";
+import { DEFAULT_MEETINGS_CONFIG, parseMeetingsConfig } from "./config.js";
+
+test("absent config is the disabled default with shipped app patterns", () => {
+  const cfg = parseMeetingsConfig(undefined);
+  assert.equal(cfg.enabled, false);
+  assert.deepEqual(cfg.appPatterns, [...DEFAULT_MEETING_APP_PATTERNS]);
+  assert.equal(cfg.minOverlapMinutes, DEFAULT_MEETINGS_CONFIG.minOverlapMinutes);
+  assert.equal(cfg.maxContextChars, 4000);
+});
+
+test("appPatterns are additive over the shipped defaults and de-duplicated", () => {
+  const cfg = parseMeetingsConfig({ appPatterns: ["Around", "Zoom"] });
+  for (const shipped of DEFAULT_MEETING_APP_PATTERNS) assert.ok(cfg.appPatterns.includes(shipped));
+  assert.ok(cfg.appPatterns.includes("Around"));
+  // "Zoom" is already shipped — no duplicate.
+  assert.equal(cfg.appPatterns.filter((p) => p === "Zoom").length, 1);
+});
+
+test("boolean-like strings coerce for enabled", () => {
+  assert.equal(parseMeetingsConfig({ enabled: "true" }).enabled, true);
+  assert.equal(parseMeetingsConfig({ enabled: "0" }).enabled, false);
+});
+
+test("invalid values reject loudly", () => {
+  assert.throws(() => parseMeetingsConfig({ enabled: "maybe" }), /boolean-like/);
+  assert.throws(() => parseMeetingsConfig({ minOverlapMinutes: -1 }), /between 0 and 1440/);
+  assert.throws(() => parseMeetingsConfig({ audioOnlyMinMinutes: 0 }), /between 1 and 1440/);
+  assert.throws(() => parseMeetingsConfig({ contextDwellSeconds: 1.5 }), /between 0 and 86400/);
+  assert.throws(() => parseMeetingsConfig({ appPatterns: [""] }), /non-empty strings/);
+  assert.throws(() => parseMeetingsConfig({ appPatterns: "Zoom" }), /must be an array/);
+  assert.throws(() => parseMeetingsConfig([]), /must be an object/);
+});
+
+test("numeric knobs coerce CLI string values", () => {
+  const cfg = parseMeetingsConfig({ minOverlapMinutes: "5", contextDwellSeconds: "45" });
+  assert.equal(cfg.minOverlapMinutes, 5);
+  assert.equal(cfg.contextDwellSeconds, 45);
+});
+
+test("summary mode defaults to smart and rejects unknown values", () => {
+  assert.equal(parseMeetingsConfig(undefined).summaryMode, "smart");
+  assert.equal(parseMeetingsConfig({ summaryMode: "off" }).summaryMode, "off");
+  assert.equal(parseMeetingsConfig({ summaryMode: "review" }).summaryMode, "review");
+  assert.throws(() => parseMeetingsConfig({ summaryMode: "loud" }), /off, review, smart/);
+});
+
+test("trust knobs default and reject out-of-range values", () => {
+  const cfg = parseMeetingsConfig(undefined);
+  assert.equal(cfg.sourceTrust, 0.85);
+  assert.equal(cfg.autoApproveTrust, 0.7);
+  assert.equal(cfg.reviewTrust, 0.45);
+  assert.equal(parseMeetingsConfig({ sourceTrust: 0.5 }).sourceTrust, 0.5);
+  assert.throws(() => parseMeetingsConfig({ sourceTrust: 1.5 }), /in \[0, 1\]/);
+  assert.throws(() => parseMeetingsConfig({ reviewTrust: -0.1 }), /in \[0, 1\]/);
+  assert.equal(parseMeetingsConfig({ autoApproveTrust: "0.9" }).autoApproveTrust, 0.9);
+});
+
+test("finding 5 — inverted trust thresholds (autoApprove < review) are rejected", () => {
+  assert.throws(
+    () => parseMeetingsConfig({ autoApproveTrust: 0.4, reviewTrust: 0.6 }),
+    /autoApproveTrust .* must be >= meetings\.reviewTrust/,
+  );
+  // Equal thresholds are allowed (auto-approve band coincides with review bar).
+  assert.equal(parseMeetingsConfig({ autoApproveTrust: 0.5, reviewTrust: 0.5 }).autoApproveTrust, 0.5);
+  // A default reviewTrust (0.45) with a lowered autoApproveTrust below it is
+  // still caught (the override interacts with the default).
+  assert.throws(() => parseMeetingsConfig({ autoApproveTrust: 0.3 }), /must be >= meetings\.reviewTrust/);
+});

package/src/meetings/config.ts

@@ -0,0 +1,183 @@
+/**
+ * Meetings config parsing — strict, loud, and default-safe (issue #1900).
+ *
+ * Mirrors the wearables/procedural blocks in config.ts: shape violations and
+ * unparseable values throw with actionable messages (CLAUDE.md rule 51);
+ * boolean-ish strings coerce via the shared helper (rule 36); every numeric
+ * knob is bounds-checked; the master gate defaults OFF (rule 48) so base
+ * installs see zero behavior change.
+ *
+ * This slice wires only the keys detection + fusion + the record store need.
+ * The memory-generation knobs (summaryMode, sourceTrust, autoApproveTrust,
+ * reviewTrust) land with the trust-pipeline slice.
+ */
+
+import { coerceBool, coerceNumber } from "../connectors/coerce.js";
+import { DEFAULT_MEETING_APP_PATTERNS } from "./detect.js";
+import type { MeetingsConfig, MeetingSummaryMode } from "./types.js";
+
+const DEFAULT_MIN_OVERLAP_MINUTES = 2;
+const DEFAULT_AUDIO_ONLY_MIN_MINUTES = 15;
+const DEFAULT_MERGE_GAP_MINUTES = 2;
+const DEFAULT_CONTEXT_DWELL_SECONDS = 20;
+const DEFAULT_MAX_CONTEXT_CHARS = 4000;
+const DEFAULT_SUMMARY_MODE: MeetingSummaryMode = "smart";
+const DEFAULT_SOURCE_TRUST = 0.85;
+const DEFAULT_AUTO_APPROVE_TRUST = 0.7;
+const DEFAULT_REVIEW_TRUST = 0.45;
+const SUMMARY_MODES: readonly MeetingSummaryMode[] = ["off", "review", "smart"];
+
+export const DEFAULT_MEETINGS_CONFIG: MeetingsConfig = {
+  enabled: false,
+  appPatterns: [...DEFAULT_MEETING_APP_PATTERNS],
+  minOverlapMinutes: DEFAULT_MIN_OVERLAP_MINUTES,
+  audioOnlyMinMinutes: DEFAULT_AUDIO_ONLY_MIN_MINUTES,
+  mergeGapMinutes: DEFAULT_MERGE_GAP_MINUTES,
+  contextDwellSeconds: DEFAULT_CONTEXT_DWELL_SECONDS,
+  maxContextChars: DEFAULT_MAX_CONTEXT_CHARS,
+  summaryMode: DEFAULT_SUMMARY_MODE,
+  sourceTrust: DEFAULT_SOURCE_TRUST,
+  autoApproveTrust: DEFAULT_AUTO_APPROVE_TRUST,
+  reviewTrust: DEFAULT_REVIEW_TRUST,
+};
+
+function parseBool(value: unknown, name: string, fallback: boolean): boolean {
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${name} must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function parseBoundedInt(
+  value: unknown,
+  name: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < min ||
+    coerced > max
+  ) {
+    throw new Error(
+      `${name} must be an integer between ${min} and ${max}; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function parseAppPatterns(value: unknown): string[] {
+  if (value === undefined || value === null) {
+    return [...DEFAULT_MEETING_APP_PATTERNS];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `meetings.appPatterns must be an array of non-empty strings; got ${JSON.stringify(value)}`,
+    );
+  }
+  const patterns: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+      throw new Error(
+        `meetings.appPatterns entries must be non-empty strings; got ${JSON.stringify(entry)}`,
+      );
+    }
+    patterns.push(entry);
+  }
+  // Additive over the shipped defaults so a user extension never silently
+  // drops a built-in meeting app (issue #1900 — appPatterns is additive).
+  const merged = [...DEFAULT_MEETING_APP_PATTERNS, ...patterns];
+  return [...new Set(merged)];
+}
+
+function parseSummaryMode(value: unknown): MeetingSummaryMode {
+  if (value === undefined || value === null) return DEFAULT_SUMMARY_MODE;
+  if (typeof value === "string" && (SUMMARY_MODES as readonly string[]).includes(value)) {
+    return value as MeetingSummaryMode;
+  }
+  throw new Error(
+    `meetings.summaryMode must be one of ${SUMMARY_MODES.join(", ")}; got ${JSON.stringify(value)}`,
+  );
+}
+
+function parseTrust01(value: unknown, name: string, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced) || coerced < 0 || coerced > 1) {
+    throw new Error(`${name} must be a number in [0, 1]; got ${JSON.stringify(value)}`);
+  }
+  return coerced;
+}
+
+/** Parse the `meetings` config block. Absent/`{}` → defaults (subsystem off). */
+export function parseMeetingsConfig(value: unknown): MeetingsConfig {
+  if (value === undefined || value === null) {
+    return { ...DEFAULT_MEETINGS_CONFIG, appPatterns: [...DEFAULT_MEETING_APP_PATTERNS] };
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`meetings must be an object; got ${JSON.stringify(value)}`);
+  }
+  const raw = value as Record<string, unknown>;
+  const config: MeetingsConfig = {
+    enabled: parseBool(raw.enabled, "meetings.enabled", DEFAULT_MEETINGS_CONFIG.enabled),
+    appPatterns: parseAppPatterns(raw.appPatterns),
+    minOverlapMinutes: parseBoundedInt(
+      raw.minOverlapMinutes,
+      "meetings.minOverlapMinutes",
+      DEFAULT_MIN_OVERLAP_MINUTES,
+      0,
+      1440,
+    ),
+    audioOnlyMinMinutes: parseBoundedInt(
+      raw.audioOnlyMinMinutes,
+      "meetings.audioOnlyMinMinutes",
+      DEFAULT_AUDIO_ONLY_MIN_MINUTES,
+      1,
+      1440,
+    ),
+    mergeGapMinutes: parseBoundedInt(
+      raw.mergeGapMinutes,
+      "meetings.mergeGapMinutes",
+      DEFAULT_MERGE_GAP_MINUTES,
+      0,
+      1440,
+    ),
+    contextDwellSeconds: parseBoundedInt(
+      raw.contextDwellSeconds,
+      "meetings.contextDwellSeconds",
+      DEFAULT_CONTEXT_DWELL_SECONDS,
+      0,
+      86_400,
+    ),
+    maxContextChars: parseBoundedInt(
+      raw.maxContextChars,
+      "meetings.maxContextChars",
+      DEFAULT_MAX_CONTEXT_CHARS,
+      0,
+      1_000_000,
+    ),
+    summaryMode: parseSummaryMode(raw.summaryMode),
+    sourceTrust: parseTrust01(raw.sourceTrust, "meetings.sourceTrust", DEFAULT_SOURCE_TRUST),
+    autoApproveTrust: parseTrust01(raw.autoApproveTrust, "meetings.autoApproveTrust", DEFAULT_AUTO_APPROVE_TRUST),
+    reviewTrust: parseTrust01(raw.reviewTrust, "meetings.reviewTrust", DEFAULT_REVIEW_TRUST),
+  };
+  // decideSmart checks the auto-approve band FIRST, so autoApproveTrust below
+  // reviewTrust fails open (a claim under the review bar would auto-activate).
+  // Reject the inversion loudly rather than silently mis-gate meeting facts.
+  if (config.autoApproveTrust < config.reviewTrust) {
+    throw new Error(
+      `meetings.autoApproveTrust (${config.autoApproveTrust}) must be >= meetings.reviewTrust ` +
+        `(${config.reviewTrust}); an inverted gate would auto-approve below the review bar`,
+    );
+  }
+  return config;
+}

package/src/meetings/errors.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown by meeting surfaces for caller-correctable problems: invalid
+ * dates/ids, unknown commands/flags, or a missing record. Transport layers map
+ * this to 400-class responses; anything else is a backend fault (500). Mirrors
+ * `WearablesInputError` so the meetings surfaces follow the same house style.
+ */
+
+export class MeetingsInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MeetingsInputError";
+  }
+}