@remnic/core 9.69.32 → 9.69.34

package/src/activity/timeline/analysis-provider.ts

@@ -0,0 +1,140 @@
+/**
+ * Provider-neutral completion adapter for timeline analysis (issue #2050).
+ *
+ * Routes the analysis prompt through the existing LLM contracts — the local
+ * client (`provider: "local"`) or the gateway fallback client pinned to the
+ * ONE explicitly configured remote provider/model. An invalid or missing
+ * explicit provider surfaces as a typed failure; there is no chain fallback,
+ * so a bad config can never silently answer from a different provider.
+ *
+ * Structural seams (not concrete classes) so hosts and tests inject fakes.
+ * Never logs prompt or response content.
+ */
+import type { AnalysisFailureKind } from "./analysis-failure.js";
+import type { TimelineAnalysisComplete } from "./analysis.js";
+
+/** Structural slice of LocalLlmClient.chatCompletion (local seam). */
+export interface TimelineAnalysisLocalLlm {
+  chatCompletion(
+    messages: Array<{ role: "system" | "user"; content: string }>,
+    options: {
+      temperature?: number;
+      maxTokens?: number;
+      responseFormat?: { type: string };
+      signal?: AbortSignal;
+      operation?: string;
+      redactProviderErrors?: boolean;
+      model?: string;
+    },
+  ): Promise<{ content: string } | null>;
+}
+
+/** Structural slice of FallbackLlmClient.chatCompletion (remote seam). */
+export interface TimelineAnalysisRemoteLlm {
+  chatCompletion(
+    messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+    options: {
+      temperature?: number;
+      maxTokens?: number;
+      signal?: AbortSignal;
+      modelChain?: { primary?: string; fallbacks?: string[] };
+      includeDefaultModelFallback?: boolean;
+      redactProviderErrors?: boolean;
+    },
+  ): Promise<{ content: string } | null>;
+}
+
+/** Marker base for provider errors the analysis run classifies by kind. */
+export class TimelineAnalysisProviderError extends Error {
+  override readonly name = "TimelineAnalysisProviderError";
+  constructor(
+    readonly kind: AnalysisFailureKind,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The provider id that routes to the local LLM client. */
+export const TIMELINE_ANALYSIS_LOCAL_PROVIDER_ID = "local";
+
+const RATE_LIMIT_MESSAGE = /rate limit|too many requests/i;
+
+/**
+ * Map a thrown provider error onto the typed failure kinds. Name- and
+ * status-based only: the message is matched, never logged, so provider error
+ * text cannot become a log line.
+ */
+export function classifyAnalysisProviderError(error: unknown): AnalysisFailureKind {
+  if (error instanceof TimelineAnalysisProviderError) return error.kind;
+  if (error instanceof Error) {
+    if (error.name === "AbortError" || ("code" in error && error.code === "ABORT_ERR")) {
+      return "aborted";
+    }
+    if (error.name === "TimeoutError") return "timeout";
+    const status = "status" in error ? error.status : "statusCode" in error ? error.statusCode : undefined;
+    if (status === 429 || RATE_LIMIT_MESSAGE.test(error.message)) return "rate_limited";
+  }
+  return "provider_unavailable";
+}
+
+/**
+ * Build the `complete` function `analyzeTimelineCards` calls, from the local
+ * and remote client seams. Selection is by the explicit provider id carried
+ * on each call: `"local"` uses the local client; anything else is a remote
+ * provider id pinned as the single-model chain (no default-chain fallback is
+ * ever appended).
+ */
+export function timelineAnalysisCompleteFromClients(input: {
+  localLlm: TimelineAnalysisLocalLlm | null;
+  remoteLlm: TimelineAnalysisRemoteLlm | null;
+}): TimelineAnalysisComplete {
+  const { localLlm, remoteLlm } = input;
+  return async ({ prompt, provider, model, signal }) => {
+    const messages = [{ role: "user" as const, content: prompt }];
+    if (provider === TIMELINE_ANALYSIS_LOCAL_PROVIDER_ID) {
+      if (!localLlm) {
+        throw new TimelineAnalysisProviderError(
+          "provider_unavailable",
+          "timeline analysis local provider is not configured",
+        );
+      }
+      const result = await localLlm.chatCompletion(messages, {
+        temperature: 0,
+        maxTokens: 2048,
+        signal,
+        operation: "timeline-analysis",
+        redactProviderErrors: true,
+        model,
+      });
+      if (result === null) {
+        throw new TimelineAnalysisProviderError(
+          "provider_unavailable",
+          "timeline analysis local provider returned no completion",
+        );
+      }
+      return result.content;
+    }
+    if (!remoteLlm) {
+      throw new TimelineAnalysisProviderError(
+        "provider_unavailable",
+        "timeline analysis remote provider is not configured",
+      );
+    }
+    const result = await remoteLlm.chatCompletion(messages, {
+      temperature: 0,
+      maxTokens: 2048,
+      signal,
+      modelChain: { primary: `${provider}/${model}` },
+      includeDefaultModelFallback: false,
+      redactProviderErrors: true,
+    });
+    if (result === null) {
+      throw new TimelineAnalysisProviderError(
+        "provider_unavailable",
+        `timeline analysis provider "${provider}" is not configured`,
+      );
+    }
+    return result.content;
+  };
+}

package/src/activity/timeline/analysis-run.test.ts

@@ -0,0 +1,419 @@
+/**
+ * Provider-contract and surface tests for timeline-card analysis (issue #2050).
+ *
+ * Every acceptance path runs against synthetic observations through the
+ * local/remote client seams — no network, no real provider. Prompt and
+ * response content are captured by the fakes and asserted locally.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runTimelineCardAnalysis } from "./analysis-run.js";
+import {
+  classifyAnalysisProviderError,
+  timelineAnalysisCompleteFromClients,
+  TimelineAnalysisProviderError,
+} from "./analysis-provider.js";
+import type { TimelineAnalysisLocalLlm, TimelineAnalysisRemoteLlm } from "./analysis-provider.js";
+import type { ActivityTimelineAnalysisConfig } from "../types.js";
+import type { TimelineCard, TimelineObservation } from "./types.js";
+
+const DATE = "2026-08-17";
+const TZ = "UTC";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "main.ts — editor",
+    summary: "Code editor on ws-a",
+    categoryId: "development",
+    confidence: 0.8,
+    dayKey: DATE,
+    timezone: TZ,
+    machine: "ws-a",
+    evidenceIds: [1],
+    evidenceRange: {
+      firstKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1",
+      lastKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1",
+    },
+    ...overrides,
+  };
+}
+
+function observation(overrides: Partial<TimelineObservation> = {}): TimelineObservation {
+  return {
+    id: 1,
+    machine: "ws-a",
+    capturedAtUtc: "2026-08-17T10:00:00.000Z",
+    app: "editor",
+    windowTitle: "main.ts — editor",
+    contentHash: "hash-1",
+    ...overrides,
+  };
+}
+
+function sampleCards(): TimelineCard[] {
+  return [card({ id: "card-1", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T10:15:00.000Z" })];
+}
+
+const ENABLED: ActivityTimelineAnalysisConfig = { enabled: true, provider: "openai", model: "gpt-test" };
+
+interface RecordedCall {
+  messages: Array<{ role: string; content: string }>;
+  options: Record<string, unknown>;
+}
+
+function fakeLocal(handler: (call: RecordedCall) => Promise<{ content: string } | null>) {
+  const calls: RecordedCall[] = [];
+  const localLlm: TimelineAnalysisLocalLlm = {
+    chatCompletion: async (messages, options) => {
+      const call = { messages, options: options as unknown as Record<string, unknown> };
+      calls.push(call);
+      return handler(call);
+    },
+  };
+  return { localLlm, calls };
+}
+
+function fakeRemote(handler: (call: RecordedCall) => Promise<{ content: string } | null>) {
+  const calls: RecordedCall[] = [];
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (messages, options) => {
+      const call = { messages, options: options as unknown as Record<string, unknown> };
+      calls.push(call);
+      return handler(call);
+    },
+  };
+  return { remoteLlm, calls };
+}
+
+test("disabled config makes zero provider calls and produces zero analysis artifacts", async () => {
+  const cards = sampleCards();
+  const local = fakeLocal(async () => ({ content: '{"ops":[]}' }));
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { enabled: false },
+    deps: { localLlm: local.localLlm, remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "disabled");
+  assert.equal(result.cards, cards);
+  assert.equal(local.calls.length + remote.calls.length, 0);
+  assert.equal(result.failure, undefined);
+  assert.equal(result.metadata, undefined);
+});
+
+test("remote provider is pinned to the single configured model with no chain fallback", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  assert.equal(remote.calls.length, 1);
+  assert.deepEqual(remote.calls[0]?.options.modelChain, { primary: "openai/gpt-test" });
+  assert.equal(remote.calls[0]?.options.includeDefaultModelFallback, false);
+  assert.deepEqual(result.metadata, {
+    provider: "openai",
+    model: "gpt-test",
+    promptVersion: "1",
+    observationCount: 1,
+  });
+});
+
+test("local provider routes to the local client seam", async () => {
+  const local = fakeLocal(async () => ({ content: '{"ops":[]}' }));
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: { ...ENABLED, provider: "local", model: "qwen3.8-27b" },
+    deps: { localLlm: local.localLlm, remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  assert.equal(local.calls.length, 1);
+  assert.equal(remote.calls.length, 0);
+  assert.equal(local.calls[0]?.options.operation, "timeline-analysis");
+  assert.equal(local.calls[0]?.options.model, "qwen3.8-27b");
+  assert.equal(result.metadata?.provider, "local");
+  assert.equal(result.metadata?.model, "qwen3.8-27b");
+});
+
+test("prompt carries evidence-only chronology and strict-output instructions with only safe fields", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation({ browserUrl: "https://example.test/repo" })],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  const prompt = remote.calls[0]?.messages[0]?.content ?? "";
+  for (const phrase of [
+    "Use only supplied evidence",
+    "Preserve chronology",
+    "Do not invent people, places, or tasks",
+    "Avoid productivity or emotional claims",
+    "Return strict JSON",
+  ]) {
+    assert.ok(prompt.includes(phrase), `prompt must instruct: ${phrase}`);
+  }
+  // The prompt is "<instructions>\n<payload JSON>"; the payload is line 2.
+  const payload = JSON.parse(prompt.slice(prompt.indexOf("\n") + 1));
+  assert.deepEqual(Object.keys(payload.observations[0]).sort(), [
+    "app",
+    "browserUrl",
+    "capturedAtUtc",
+    "contentHash",
+    "id",
+    "machine",
+    "windowTitle",
+  ]);
+  // No raw capture channels exist on the observation payload: the type carries
+  // none, and the wire shape proves nothing extra was smuggled in.
+  assert.equal(JSON.stringify(payload).includes("textSource"), false);
+});
+
+test("observations outside the day window are never sent", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [
+      observation({ id: 1 }),
+      observation({ id: 2, capturedAtUtc: "2026-08-16T23:59:59.999Z", contentHash: "hash-2" }),
+    ],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  const prompt = remote.calls[0]?.messages[0]?.content ?? "";
+  const payload = JSON.parse(prompt.slice(prompt.indexOf("\n") + 1));
+  assert.equal(payload.observations.length, 1);
+  assert.equal(result.metadata?.observationCount, 1);
+});
+
+test("an impossible date or timezone throws before any provider contact", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  await assert.rejects(
+    () =>
+      runTimelineCardAnalysis({
+        date: "2026-02-30",
+        timezone: TZ,
+        cards: sampleCards(),
+        observations: [observation()],
+        config: ENABLED,
+        deps: { remoteLlm: remote.remoteLlm },
+      }),
+    RangeError,
+  );
+  await assert.rejects(
+    () =>
+      runTimelineCardAnalysis({
+        date: DATE,
+        timezone: "Not/AZone",
+        cards: sampleCards(),
+        observations: [observation()],
+        config: ENABLED,
+        deps: { remoteLlm: remote.remoteLlm },
+      }),
+    RangeError,
+  );
+  assert.equal(remote.calls.length, 0);
+});
+
+test("missing provider seam returns a typed provider_unavailable failure and unchanged cards", async () => {
+  const cards = sampleCards();
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { ...ENABLED, provider: "local" },
+    deps: { localLlm: null, remoteLlm: null },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.cards, cards);
+  assert.deepEqual(result.failure, { kind: "provider_unavailable", retryable: true, preservesDeterministic: true });
+});
+
+test("unconfigured remote provider returns null and never falls back to another provider", async () => {
+  const remote = fakeRemote(async () => null);
+  const cards = sampleCards();
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { ...ENABLED, provider: "no-such-provider" },
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.cards, cards);
+  assert.equal(result.failure?.kind, "provider_unavailable");
+  assert.equal(remote.calls.length, 1);
+  assert.deepEqual(remote.calls[0]?.options.modelChain, { primary: "no-such-provider/gpt-test" });
+});
+
+for (const [name, error, kind] of [
+  ["timeout", Object.assign(new Error("timeline analysis timed out"), { name: "TimeoutError" }), "timeout"],
+  ["abort", Object.assign(new Error("aborted"), { name: "AbortError" }), "aborted"],
+  ["rate limit status", Object.assign(new Error("HTTP 429"), { status: 429 }), "rate_limited"],
+  ["generic provider crash", new Error("socket hang up"), "provider_unavailable"],
+] as const) {
+  test(`${name} returns the typed failure kind and leaves cards byte-identical`, async () => {
+    const cards = sampleCards();
+    const remote = fakeRemote(async () => {
+      throw error;
+    });
+    const result = await runTimelineCardAnalysis({
+      date: DATE,
+      timezone: TZ,
+      cards,
+      observations: [observation()],
+      config: ENABLED,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(result.status, "provider_failed");
+    assert.equal(result.cards, cards);
+    assert.equal(result.failure?.kind, kind);
+    assert.equal(result.failure?.preservesDeterministic, true);
+  });
+}
+
+for (const [name, body, kind] of [
+  ["empty response body", "", "partial_output"],
+  ["malformed JSON", "the model rambled, no json here", "malformed_json"],
+  ["json without ops", '{"summary":"no ops key"}', "invalid_schema"],
+  ["ops with an invalid entry", '{"ops":[{"cardId":"card-1"}]}', "invalid_schema"],
+] as const) {
+  test(`${name} is typed ${kind} and leaves cards unchanged`, async () => {
+    const cards = sampleCards();
+    const remote = fakeRemote(async () => ({ content: body }));
+    const result = await runTimelineCardAnalysis({
+      date: DATE,
+      timezone: TZ,
+      cards,
+      observations: [observation()],
+      config: ENABLED,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(result.status, "invalid_output");
+    assert.equal(result.cards, cards);
+    assert.equal(result.failure?.kind, kind);
+  });
+}
+
+test("a valid op updates only allowed fields and preserves manual edits and evidence", async () => {
+  const locked = card({
+    id: "locked",
+    startUtc: "2026-08-17T11:00:00.000Z",
+    endUtc: "2026-08-17T11:15:00.000Z",
+    manualEdit: { editedAtUtc: "2026-08-17T12:00:00.000Z", title: "kept" },
+  });
+  const open = card({ id: "open", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T10:15:00.000Z" });
+  const remote = fakeRemote(
+    async () =>
+      ({
+        content: JSON.stringify({
+          ops: [
+            {
+              cardId: "open",
+              title: "Refined title",
+              summary: "Editor work bound to the supplied window",
+              categoryId: "development",
+              confidence: 0.9,
+              uncertainty: "Title inferred from window title only",
+              evidenceRange: { firstKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1", lastKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1" },
+            },
+          ],
+        }),
+      }) as { content: string },
+  );
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: [locked, open],
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  const updated = result.cards.find((entry) => entry.id === "open");
+  const untouched = result.cards.find((entry) => entry.id === "locked");
+  assert.equal(updated?.title, "Refined title");
+  assert.equal(updated?.confidence, 0.9);
+  assert.deepEqual(updated?.evidenceRange, open.evidenceRange);
+  assert.deepEqual(updated?.evidenceIds, [1]);
+  assert.equal(untouched?.title, "main.ts — editor");
+  assert.ok(untouched?.manualEdit);
+});
+
+test("empty input returns invalid_output with zero provider calls", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const cards: TimelineCard[] = [];
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "invalid_output");
+  assert.equal(result.cards, cards);
+  assert.equal(remote.calls.length, 0);
+});
+
+test("provider error classification is name/status based and total", () => {
+  assert.equal(classifyAnalysisProviderError(new TimelineAnalysisProviderError("rate_limited", "x")), "rate_limited");
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("HTTP 429"), { status: 429 })),
+    "rate_limited",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(new Error("Rate limit exceeded, retry later")),
+    "rate_limited",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("x"), { name: "AbortError" })),
+    "aborted",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("x"), { name: "TimeoutError" })),
+    "timeout",
+  );
+  assert.equal(classifyAnalysisProviderError(new Error("socket hang up")), "provider_unavailable");
+  assert.equal(classifyAnalysisProviderError("not an error"), "provider_unavailable");
+});
+
+test("adapter pins the call-time provider verbatim with no chain fallback", async () => {
+  const seen: string[] = [];
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (_messages, options) => {
+      seen.push(options.modelChain?.primary ?? "");
+      assert.equal(options.includeDefaultModelFallback, false);
+      return { content: '{"ops":[]}' };
+    },
+  };
+  const complete = timelineAnalysisCompleteFromClients({ localLlm: null, remoteLlm });
+  await complete({
+    prompt: "p",
+    provider: "anthropic",
+    model: "claude-4_1",
+    signal: new AbortController().signal,
+  });
+  assert.deepEqual(seen, ["anthropic/claude-4_1"]);
+});

package/src/activity/timeline/analysis-run.ts

@@ -0,0 +1,106 @@
+/**
+ * Config-driven surface for evidence-bound timeline-card analysis (issue #2050).
+ *
+ * Composes the parsed `activity.timeline.analysis` config with the local/remote
+ * provider seams and `analyzeTimelineCards`. The AI gate is independent of
+ * activity capture, timeline derivation, and memory creation: disabled means
+ * zero provider calls and zero analysis artifacts. Every failure leaves the
+ * deterministic cards byte-identical and returns a typed status.
+ */
+import { activityDayWindow } from "../digest.js";
+import type { ActivityTimelineAnalysisConfig } from "../types.js";
+import { analyzeTimelineCards, type TimelineAnalysisStatus } from "./analysis.js";
+import type { AnalysisFailure } from "./analysis-failure.js";
+import {
+  timelineAnalysisCompleteFromClients,
+  type TimelineAnalysisLocalLlm,
+  type TimelineAnalysisRemoteLlm,
+} from "./analysis-provider.js";
+import { buildAnalysisRunMetadata, type AnalysisRunMetadata } from "./analysis-metadata.js";
+import type { TimelineCard, TimelineCategory, TimelineCorrection, TimelineObservation } from "./types.js";
+
+export interface TimelineAnalysisRunInput {
+  /** Local calendar day being analyzed (YYYY-MM-DD). */
+  date: string;
+  /** IANA timezone the day is bucketed in. */
+  timezone: string;
+  /** Deterministic cards for the day (the bytes that must survive failure). */
+  cards: readonly TimelineCard[];
+  /** Day observations — the only evidence the provider may see. */
+  observations: readonly TimelineObservation[];
+  categories?: readonly TimelineCategory[];
+  /** Prior accepted manual corrections, surfaced to the prompt as edits. */
+  corrections?: readonly TimelineCorrection[];
+  config: ActivityTimelineAnalysisConfig;
+  deps: {
+    localLlm?: TimelineAnalysisLocalLlm | null;
+    remoteLlm?: TimelineAnalysisRemoteLlm | null;
+  };
+  signal?: AbortSignal;
+}
+
+export interface TimelineAnalysisRunResult {
+  status: TimelineAnalysisStatus;
+  /** Same card objects as the input on any non-ok status. */
+  cards: TimelineCard[];
+  failure?: AnalysisFailure;
+  /** Provider/model/prompt-version provenance; identifiers only, never content. */
+  metadata?: AnalysisRunMetadata;
+}
+
+/**
+ * Run the optional analysis for one day. Observations are confined to the
+ * DST-aware day window before anything is sent, so a mis-scoped caller cannot
+ * widen the evidence the provider sees.
+ */
+export async function runTimelineCardAnalysis(
+  input: TimelineAnalysisRunInput,
+): Promise<TimelineAnalysisRunResult> {
+  // Throws RangeError on an impossible date or invalid timezone before any
+  // provider contact — the window bounds the whole run.
+  const { startUtc, endUtc } = activityDayWindow(input.date, input.timezone);
+  if (!input.config.enabled) {
+    return { status: "disabled", cards: input.cards as TimelineCard[] };
+  }
+  const start = Date.parse(startUtc);
+  const end = Date.parse(endUtc);
+  const observations = input.observations.filter((observation) => {
+    const captured = Date.parse(observation.capturedAtUtc);
+    return Number.isFinite(captured) && captured >= start && captured < end;
+  });
+  const result = await analyzeTimelineCards({
+    enabled: true,
+    cards: input.cards,
+    observations,
+    provider: input.config.provider,
+    model: input.config.model,
+    complete: timelineAnalysisCompleteFromClients({
+      localLlm: input.deps.localLlm ?? null,
+      remoteLlm: input.deps.remoteLlm ?? null,
+    }),
+    ...(input.config.timeoutMs === undefined ? {} : { timeoutMs: input.config.timeoutMs }),
+    date: input.date,
+    timezone: input.timezone,
+    ...(input.categories === undefined ? {} : { categories: input.categories }),
+    ...(input.config.preferences === undefined ? {} : { preferences: input.config.preferences }),
+    ...(input.corrections === undefined ? {} : { priorEdits: input.corrections }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+  if (result.status !== "ok") {
+    return {
+      status: result.status,
+      cards: result.cards,
+      ...(result.failure === undefined ? {} : { failure: result.failure }),
+    };
+  }
+  return {
+    status: "ok",
+    cards: result.cards,
+    metadata: buildAnalysisRunMetadata({
+      provider: result.provider ?? "unknown",
+      model: result.model ?? "unknown",
+      promptVersion: String(result.promptVersion ?? "v0"),
+      observationCount: observations.length,
+    }),
+  };
+}