opencode-engram 0.1.0

package/src/common/upstream-navigator-prompt.ts

@@ -0,0 +1,131 @@
+import type { Event } from "@opencode-ai/sdk";
+
+export const builtInNavigatorPromptBody = `This session was spawned from an upstream conversation. Your task description
+carries intent but not the full discussion that shaped it — requirements,
+constraints, and rejected approaches may exist only in the upstream history.
+
+## Common Patterns
+
+| Scenario | Strategy |
+|----------|----------|
+| Continue prior work | history_browse_turns → history_browse_messages on 2-3 recent turns → history_pull_message if needed |
+| Known topic / "as we discussed X" | history_search(X) → history_pull_message if snippet insufficient |
+| Check what files were changed | history_browse_messages on recent turns → inspect attachments and tool calls |`;
+
+function buildNavigatorSessionIdLine(parentId: string) {
+  return `**Upstream session ID: ${parentId}**`;
+}
+
+export function buildNavigatorPrompt(parentId: string) {
+  return `${buildNavigatorSessionIdLine(parentId)}
+
+${builtInNavigatorPromptBody}`;
+}
+
+const upstreamNavigatorWaitTimeoutMs = 50;
+
+type SessionChildState = {
+  resolved: boolean;
+  parentId: string | undefined;
+  waiters: Array<(parentId: string | undefined) => void>;
+};
+
+type UpstreamNavigatorState = {
+  sessionChildStates: Map<string, SessionChildState>;
+};
+
+function getOrCreateSessionChildState(states: Map<string, SessionChildState>, sessionID: string): SessionChildState {
+  const existing = states.get(sessionID);
+  if (existing) {
+    return existing;
+  }
+
+  const created: SessionChildState = {
+    resolved: false,
+    parentId: undefined,
+    waiters: [],
+  };
+  states.set(sessionID, created);
+  return created;
+}
+
+function resolveSessionChildState(state: SessionChildState, parentId: string | undefined) {
+  if (state.resolved) {
+    return;
+  }
+
+  state.resolved = true;
+  state.parentId = parentId;
+  const waiters = state.waiters.splice(0);
+  for (const waiter of waiters) {
+    waiter(parentId);
+  }
+}
+
+async function waitForSessionChildState(
+  state: SessionChildState,
+  timeoutMs: number,
+): Promise<string | undefined> {
+  if (state.resolved) {
+    return state.parentId;
+  }
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      state.waiters = state.waiters.filter((waiter) => waiter !== resolve);
+      resolve(undefined);
+    }, timeoutMs);
+
+    state.waiters.push((parentId) => {
+      clearTimeout(timer);
+      resolve(parentId);
+    });
+  });
+}
+
+function isSessionCreatedEvent(event: Event): event is Extract<Event, { type: "session.created" }> {
+  return event.type === "session.created";
+}
+
+export function createUpstreamNavigatorState(): UpstreamNavigatorState {
+  return {
+    sessionChildStates: new Map<string, SessionChildState>(),
+  };
+}
+
+export function recordUpstreamNavigatorSession(
+  state: UpstreamNavigatorState,
+  event: Event,
+) {
+  if (!isSessionCreatedEvent(event)) {
+    return;
+  }
+
+  const session = event.properties.info;
+  const sessionState = getOrCreateSessionChildState(state.sessionChildStates, session.id);
+  resolveSessionChildState(sessionState, session.parentID || undefined);
+}
+
+export async function injectUpstreamNavigatorPrompt(
+  state: UpstreamNavigatorState,
+  sessionID: string | undefined,
+  system: string[],
+) {
+  if (!sessionID) {
+    return;
+  }
+
+  const sessionState = getOrCreateSessionChildState(state.sessionChildStates, sessionID);
+  const parentId = await waitForSessionChildState(
+    sessionState,
+    upstreamNavigatorWaitTimeoutMs,
+  );
+  if (!parentId) {
+    return;
+  }
+
+  const prompt = buildNavigatorPrompt(parentId);
+  if (!system.includes(prompt)) {
+    system.push(prompt);
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,33 @@
+/**
+ * core/index.ts - Core Layer Public Exports
+ *
+ * Public API for the core layer. Runtime modules use these exports
+ * to resolve targets and create browse contexts.
+ *
+ * Architectural boundary:
+ * - Interface layer (`src/plugin/index.ts`) defines tool contracts only
+ * - Runtime layer (`src/runtime/runtime.ts`) wires SDK calls to core abstractions
+ * - Core modules provide target and browse primitives
+ * - Serialization layer (`src/domain/serialize.ts`) remains separate
+ */
+
+// Session types, metadata, context, and utilities
+export type {
+  SessionMetadata,
+  SessionTarget,
+  BrowseContext,
+  SdkSessionData,
+} from "./session.ts";
+export {
+  createBrowseContext,
+  normalizeSessionMetadata,
+  toSessionMetadata,
+  createSessionTarget,
+  computeCacheFingerprint,
+} from "./session.ts";
+
+// SDK bridges for session resolution
+export {
+  getParentSessionId,
+  resolveSessionTarget,
+} from "./sdk-bridge.ts";

package/src/core/sdk-bridge.ts

@@ -0,0 +1,73 @@
+/**
+ * sdk-bridge.ts - SDK-backed Session Resolution
+ *
+ * Wires core abstractions to the OpenCode SDK for session reading.
+ * Provides two low-level primitives:
+ * - getParentSessionId: retrieve the parentID from a session
+ * - resolveSessionTarget: load a session by ID and wrap as SessionTarget
+ */
+
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+import { createSessionTarget, type SdkSessionData } from "./session.ts";
+
+type SdkClient = ReturnType<typeof createOpencodeClient>;
+
+function toQuery(directory?: string): { directory: string } | undefined {
+  if (!directory?.trim()) {
+    return undefined;
+  }
+  return { directory };
+}
+
+async function getSessionOrThrow(
+  client: SdkClient,
+  sessionId: string,
+  directory?: string,
+): Promise<SdkSessionData> {
+  const result = await client.session.get({
+    path: { id: sessionId },
+    query: toQuery(directory),
+    throwOnError: false,
+  });
+
+  const status = result.response?.status ?? 0;
+  if (status === 404) {
+    throw new Error(`Session '${sessionId}' not found`);
+  }
+  if (result.error || status >= 400 || !result.data) {
+    throw new Error(
+      `Failed to load session '${sessionId}'. This may be a temporary issue — try again.`,
+    );
+  }
+
+  return result.data;
+}
+
+/**
+ * Get the parentID from a session.
+ *
+ * Returns undefined if the session has no parent.
+ */
+export async function getParentSessionId(
+  client: SdkClient,
+  sessionId: string,
+  directory?: string,
+): Promise<string | undefined> {
+  const session = await getSessionOrThrow(client, sessionId, directory);
+  return session.parentID || undefined;
+}
+
+/**
+ * Resolve a session target by session ID.
+ *
+ * Loads the session data from the SDK and wraps it as a SessionTarget.
+ */
+export async function resolveSessionTarget(
+  client: SdkClient,
+  sessionId: string,
+  directory?: string,
+) {
+  const session = await getSessionOrThrow(client, sessionId, directory);
+  return createSessionTarget(session);
+}

package/src/core/session.ts

@@ -0,0 +1,196 @@
+/**
+ * session.ts - Core Session Models and Utilities
+ *
+ * Unified module for session targeting, metadata normalization, browse context,
+ * and SDK session adapters used by the core layer.
+ *
+ * Key concepts:
+ * - SessionTarget: the resolved target session for reading
+ * - BrowseContext: unified context for all core reading operations
+ * - SessionMetadata: minimal metadata needed for reading
+ * - SdkSessionData: shape of SDK session data for conversion
+ */
+
+// =============================================================================
+// Session Metadata
+// =============================================================================
+
+/**
+ * Minimal metadata needed to read a session's history.
+ * Intentionally minimal to avoid coupling to SDK-specific types.
+ */
+export interface SessionMetadata {
+  id: string;
+  title: string;
+  version: number | undefined;
+  updatedAt: number | undefined;
+  parentId: string | undefined;
+}
+
+// =============================================================================
+// Session Target
+// =============================================================================
+
+/**
+ * A resolved session target for core reading operations.
+ *
+ * All targets are treated uniformly by core operations —
+ * the core layer only sees a session to read from.
+ */
+export interface SessionTarget {
+  session: SessionMetadata;
+}
+
+// =============================================================================
+// Browse Context
+// =============================================================================
+
+/**
+ * Context for a core browsing operation.
+ *
+ * This context is passed to core timeline/read/summary operations.
+ * It contains the resolved target and any operation-specific parameters
+ * needed by the core layer.
+ *
+ * The context intentionally does NOT include:
+ * - Tool-specific argument validation (interface layer responsibility)
+ * - Public output field filtering (serialize layer responsibility)
+ * - SDK client references (passed separately to avoid coupling)
+ */
+export interface BrowseContext {
+  /**
+   * The resolved session target to browse.
+   */
+  target: SessionTarget;
+
+  /**
+   * True when the target session is the caller's own session.
+   *
+   * This is detected once at the runtime boundary and propagated through
+   * all data paths so tool implementations can apply self-session semantics
+   * without adding new parameters.
+   */
+  selfSession: boolean;
+}
+
+/**
+ * Create a browse context from a resolved target.
+ *
+ * @param target Resolved session target
+ * @returns Browse context for core operations
+ */
+export function createBrowseContext(
+  target: SessionTarget,
+  selfSession: boolean = false,
+): BrowseContext {
+  return {
+    target,
+    selfSession,
+  };
+}
+
+// =============================================================================
+// SDK Session Adapter
+// =============================================================================
+
+/**
+ * SDK session data shape.
+ *
+ * Captures the shape of session data returned by the SDK,
+ * allowing conversion to core SessionMetadata.
+ */
+export interface SdkSessionData {
+  id: string;
+  title: string;
+  version?: number | string;
+  time?: {
+    updated?: number | string;
+  };
+  parentID?: string;
+}
+
+// =============================================================================
+// Session Metadata Normalization
+// =============================================================================
+
+/**
+ * Normalize a flexible numeric value from SDK/session layer.
+ */
+function normalizeVersion(value: number | string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = typeof value === "number"
+    ? value
+    : parseInt(String(value), 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/**
+ * Normalize a flexible timestamp value from SDK/session layer.
+ */
+function normalizeUpdatedAt(
+  value: number | string | undefined,
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = typeof value === "number"
+    ? value
+    : Date.parse(String(value));
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+/**
+ * Convert SDK session data to core SessionMetadata.
+ */
+export function normalizeSessionMetadata(session: SdkSessionData): SessionMetadata {
+  return {
+    id: session.id,
+    title: session.title,
+    version: normalizeVersion(session.version),
+    updatedAt: normalizeUpdatedAt(session.time?.updated),
+    parentId: session.parentID,
+  };
+}
+
+// =============================================================================
+// Session Target Factory
+// =============================================================================
+
+/**
+ * Convert SDK session data to core SessionMetadata.
+ */
+export function toSessionMetadata(sdk: SdkSessionData): SessionMetadata {
+  return normalizeSessionMetadata(sdk);
+}
+
+/**
+ * Create a SessionTarget from SDK session data.
+ */
+export function createSessionTarget(
+  sdk: SdkSessionData,
+): SessionTarget {
+  return {
+    session: toSessionMetadata(sdk),
+  };
+}
+
+// =============================================================================
+// Session Fingerprint (for cache invalidation)
+// =============================================================================
+
+/**
+ * Compute a cache fingerprint string from session metadata.
+ * Returns undefined if required metadata is unavailable.
+ */
+export function computeCacheFingerprint(
+  session: SessionMetadata,
+): string | undefined {
+  if (session.version === undefined || session.updatedAt === undefined) {
+    return undefined;
+  }
+  return `${session.version}:${session.updatedAt}`;
+}

package/src/core/turn-index.ts

@@ -0,0 +1,219 @@
+/**
+ * turn-index.ts - Reusable Turn Cache for Upstream History
+ *
+ * This module provides a session-scoped turn cache that:
+ * - Computes turn mappings once per session version
+ * - Invalidates when session metadata changes (version/updated time)
+ * - Falls back to full scan when cache unavailable or stale
+ * - Logs cache hit/rebuild/fallback events
+ */
+
+import type { TurnComputeItem } from "../domain/domain.ts";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Session fingerprint used for cache invalidation.
+ * Combines version and updated time to detect any upstream changes.
+ */
+export interface SessionFingerprint {
+  version: number;
+  updated: number;
+}
+
+/**
+ * Cached turn index entry for a session.
+ */
+interface TurnCacheEntry {
+  fingerprint: SessionFingerprint;
+  turnMap: Map<string, number>;
+  cachedAt: number;
+}
+
+const turnCacheTtlMs = 10 * 60 * 1000;
+const turnCacheMaxEntries = 128;
+
+/**
+ * Logger interface matching the runtime logger shape.
+ */
+export interface TurnCacheLogger {
+  debug: (message: string, extra?: Record<string, unknown>) => void;
+}
+
+/**
+ * Callback type for fetching all messages and computing turn items.
+ */
+export type FetchTurnItems = () => Promise<TurnComputeItem[]>;
+
+/**
+ * Callback type for computing turns from items.
+ * Matches the signature of computeTurns from domain.ts.
+ */
+export type ComputeTurnsFn = (items: TurnComputeItem[]) => Map<string, number>;
+
+// =============================================================================
+// Turn Cache Implementation
+// =============================================================================
+
+/**
+ * In-memory turn cache keyed by session ID.
+ */
+const turnCache = new Map<string, TurnCacheEntry>();
+
+function pruneTurnCache(now = Date.now()) {
+  for (const [sessionId, entry] of turnCache) {
+    if (now - entry.cachedAt > turnCacheTtlMs) {
+      turnCache.delete(sessionId);
+    }
+  }
+
+  while (turnCache.size > turnCacheMaxEntries) {
+    const oldest = turnCache.keys().next().value;
+    if (oldest === undefined) {
+      break;
+    }
+    turnCache.delete(oldest);
+  }
+}
+
+/**
+ * Compare two fingerprints for equality.
+ */
+function fingerprintsMatch(a: SessionFingerprint, b: SessionFingerprint): boolean {
+  return a.version === b.version && a.updated === b.updated;
+}
+
+/**
+ * Build a fingerprint from session metadata.
+ */
+export function buildFingerprint(version: number, updated: number): SessionFingerprint {
+  return { version, updated };
+}
+
+/**
+ * Get cached turn map if valid, otherwise return undefined.
+ *
+ * @param sessionId Session ID to look up
+ * @param fingerprint Current session fingerprint for validation
+ * @returns Cached turn map if valid, undefined if stale/missing
+ */
+export function getTurnCache(
+  sessionId: string,
+  fingerprint: SessionFingerprint,
+): Map<string, number> | undefined {
+  pruneTurnCache();
+  const entry = turnCache.get(sessionId);
+  if (!entry) {
+    return undefined;
+  }
+
+  if (!fingerprintsMatch(entry.fingerprint, fingerprint)) {
+    turnCache.delete(sessionId);
+    return undefined;
+  }
+
+  // Refresh insertion order to keep hot entries in this bounded cache.
+  turnCache.delete(sessionId);
+  turnCache.set(sessionId, entry);
+
+  return entry.turnMap;
+}
+
+/**
+ * Store turn map in cache.
+ *
+ * @param sessionId Session ID to cache for
+ * @param fingerprint Session fingerprint at time of computation
+ * @param turnMap Computed turn map
+ */
+export function setTurnCache(
+  sessionId: string,
+  fingerprint: SessionFingerprint,
+  turnMap: Map<string, number>,
+): void {
+  turnCache.delete(sessionId);
+  turnCache.set(sessionId, {
+    fingerprint,
+    turnMap,
+    cachedAt: Date.now(),
+  });
+  pruneTurnCache();
+}
+
+/**
+ * Clear turn cache for a specific session.
+ */
+export function clearTurnCache(sessionId: string): void {
+  turnCache.delete(sessionId);
+}
+
+// =============================================================================
+// High-Level API
+// =============================================================================
+
+/**
+ * Result of getTurnMapWithCache operation.
+ */
+export interface TurnCacheResult {
+  turnMap: Map<string, number>;
+  source: "hit" | "rebuild" | "fallback";
+}
+
+/**
+ * Get turn map with caching support.
+ *
+ * This is the main entry point for turn cache usage.
+ * It handles:
+ * - Cache hit: return cached turn map immediately
+ * - Cache miss/stale: rebuild from full scan
+ * - Fallback: if fingerprint unavailable, always do full scan
+ *
+ * @param sessionId Session ID for cache key
+ * @param fingerprint Current session fingerprint (undefined triggers fallback)
+ * @param fetchItems Callback to fetch turn items if rebuild needed
+ * @param computeTurnsFn Function to compute turns from items
+ * @param logger Optional logger for cache events
+ * @returns Turn map and source indicator
+ */
+export async function getTurnMapWithCache(
+  sessionId: string,
+  fingerprint: SessionFingerprint | undefined,
+  fetchItems: FetchTurnItems,
+  computeTurnsFn: ComputeTurnsFn,
+  logger?: TurnCacheLogger,
+): Promise<TurnCacheResult> {
+  // Fallback mode: no fingerprint means no caching possible
+  if (fingerprint === undefined) {
+    logger?.debug("turn cache fallback (no fingerprint)", { sessionId });
+    const items = await fetchItems();
+    const turnMap = computeTurnsFn(items);
+    return { turnMap, source: "fallback" };
+  }
+
+  // Try cache hit
+  const cached = getTurnCache(sessionId, fingerprint);
+  if (cached) {
+    logger?.debug("turn cache hit", {
+      sessionId,
+      entries: cached.size,
+    });
+    return { turnMap: cached, source: "hit" };
+  }
+
+  // Cache miss or stale - rebuild
+  logger?.debug("turn cache rebuild", {
+    sessionId,
+    version: fingerprint.version,
+    updated: fingerprint.updated,
+  });
+
+  const items = await fetchItems();
+  const turnMap = computeTurnsFn(items);
+
+  // Store in cache
+  setTurnCache(sessionId, fingerprint, turnMap);
+
+  return { turnMap, source: "rebuild" };
+}