opencode-engram 0.1.0

package/src/domain/types.ts

@@ -0,0 +1,321 @@
+/**
+ * types.ts - Shared domain types and output contracts
+ *
+ * This module defines all domain model types for the upstream history refactor.
+ * It serves as the stable boundary between adapter, domain, and serialize layers.
+ */
+
+// =============================================================================
+// Basic Types
+// =============================================================================
+
+export type MessageRole = "user" | "assistant";
+
+export type ToolStatus = "pending" | "running" | "completed" | "error";
+
+export type ToolOutcome = "completed" | "recovered" | "error" | "running";
+
+export type ReadablePartType = "text" | "reasoning" | "tool";
+
+// =============================================================================
+// Normalized Message (Adapter Output -> Domain Input)
+// =============================================================================
+
+export interface NormalizedMessage {
+  id: string;
+  role: MessageRole;
+  time: number | undefined;
+  summary: boolean;
+}
+
+// =============================================================================
+// Tool Call Summary
+// =============================================================================
+
+/**
+ * Aggregated statistics for a single tool name within a message.
+ */
+export interface ToolCallSummary {
+  tool: string;
+  total: number;
+  errors: number;
+}
+
+// =============================================================================
+// Message Metadata
+// =============================================================================
+
+export interface MessageMetaBase {
+  id: string;
+  role: MessageRole;
+  turn: number;
+  time: number | undefined;
+  notes: string[];
+}
+
+export interface UserMessageMeta extends MessageMetaBase {
+  role: "user";
+  attachments: string[];
+}
+
+export interface AssistantMessageMeta extends MessageMetaBase {
+  role: "assistant";
+  toolCalls: ToolCallSummary[];
+  toolOutcome?: ToolOutcome;
+}
+
+export type AnyMessageMeta = UserMessageMeta | AssistantMessageMeta;
+
+// =============================================================================
+// Section Types (Domain Model)
+// =============================================================================
+
+export interface TextSection {
+  type: "text";
+  partId: string;
+  content: string;
+  truncated: boolean;
+}
+
+export interface ReasoningSection {
+  type: "reasoning";
+  partId: string;
+  content: string;
+  truncated: boolean;
+}
+
+export interface ToolSection {
+  type: "tool";
+  partId: string;
+  tool: string;
+  title: string | null;
+  status: ToolStatus;
+  input?: Record<string, unknown>;
+  content?: string;
+  truncated: boolean;
+}
+
+export interface ImageSection {
+  type: "image";
+  partId: string;
+  mime: string;
+}
+
+export interface FileSection {
+  type: "file";
+  partId: string;
+  path: string;
+  mime: string;
+}
+
+export type Section =
+  | TextSection
+  | ReasoningSection
+  | ToolSection
+  | ImageSection
+  | FileSection;
+
+// =============================================================================
+// Normalized Part (Adapter Output -> Domain Input)
+// =============================================================================
+
+export type NormalizedTextPart = {
+  type: "text";
+  partId: string;
+  messageId: string;
+  text: string;
+  ignored: boolean;
+};
+
+export type NormalizedReasoningPart = {
+  type: "reasoning";
+  partId: string;
+  messageId: string;
+  text: string;
+};
+
+export type NormalizedToolPart = {
+  type: "tool";
+  partId: string;
+  messageId: string;
+  tool: string;
+  title: string | null;
+  status: ToolStatus;
+  input: Record<string, unknown>;
+  content?: string;
+};
+
+export type NormalizedImagePart = {
+  type: "image";
+  partId: string;
+  messageId: string;
+  mime: string;
+};
+
+export type NormalizedFilePart = {
+  type: "file";
+  partId: string;
+  messageId: string;
+  path: string;
+  mime: string;
+};
+
+export type NormalizedPart =
+  | NormalizedTextPart
+  | NormalizedReasoningPart
+  | NormalizedToolPart
+  | NormalizedImagePart
+  | NormalizedFilePart;
+
+// =============================================================================
+// Section Conversion Context
+// =============================================================================
+
+export interface SectionConvertContext {
+  maxTextLength: number;
+  maxReasoningLength: number;
+  maxToolOutputLength: number;
+  maxToolInputLength: number;
+  visibleToolInputs: ReadonlySet<string>;
+  visibleToolOutputs: ReadonlySet<string>;
+}
+
+export interface PreviewFallbackHints {
+  hasCompaction: boolean;
+  hasSubtask: boolean;
+  hasUnsupported: boolean;
+}
+
+// =============================================================================
+// Serialized Output Types (Final JSON Contracts)
+// =============================================================================
+
+export interface BrowseUserItemOutput {
+  role: "user";
+  turn_index: number;
+  message_id: string;
+  preview?: string;
+  attachment?: string[];
+}
+
+export interface BrowseAssistantItemOutput {
+  role: "assistant";
+  turn_index: number;
+  message_id: string;
+  preview?: string;
+  tool?: ToolBlockOutput;
+}
+
+export type BrowseItemOutput =
+  | BrowseUserItemOutput
+  | BrowseAssistantItemOutput;
+
+export interface OverviewUserOutput {
+  message_id: string;
+  preview: string | null;
+  attachment?: string[];
+}
+
+/** Tool activity summary block for assistant outputs. */
+export interface ToolBlockOutput {
+  calls: string[];
+  outcome: ToolOutcome;
+}
+
+export interface OverviewAssistantOutput {
+  total_messages: number;
+  preview: string | null;
+  modified?: string[];
+  tool?: ToolBlockOutput;
+}
+
+/**
+ * Turn summary for overview output.
+ */
+export interface OverviewTurnOutput {
+  turn_index: number;
+  user: OverviewUserOutput | null;
+  assistant: OverviewAssistantOutput | null;
+}
+
+export interface OverviewOutput {
+  turns: OverviewTurnOutput[];
+}
+
+export interface BrowseOutput {
+  before_message_id?: string | null;
+  messages: BrowseItemOutput[];
+  after_message_id?: string | null;
+}
+
+export type SectionOutput =
+  | { type: "text"; part_id?: string; content: string | null }
+  | { type: "reasoning"; part_id?: string; content: string | null }
+    | {
+      type: "tool";
+      part_id?: string;
+      tool: string;
+      status: ToolStatus;
+      input?: Record<string, unknown>;
+      content?: string | null;
+    }
+  | { type: "image"; mime: string }
+  | { type: "file"; path: string; mime: string };
+
+// =============================================================================
+// Search Output Types (Phase 1: Contracts Only)
+// =============================================================================
+
+/**
+ * Searchable part type.
+ *
+ * - "text": user or assistant text content
+ * - "reasoning": assistant reasoning content
+ * - "tool": tool call output content
+ */
+export type SearchPartType = "text" | "reasoning" | "tool";
+
+/**
+ * A single search hit within a message.
+ *
+ * - type: part type that matched
+ * - part_id: identifier for reading full content
+ * - tool_name: present only for tool hits (optional)
+ * - snippets: ordered array of highest-priority text contexts around matches
+ */
+export interface SearchHitOutput {
+  type: SearchPartType;
+  part_id: string;
+  tool_name?: string;
+  snippets: string[];
+}
+
+/**
+ * Search result grouped by message.
+ *
+ * - role: message role
+ * - turn_index: message turn number
+ * - message_id: identifier for reading full message
+ * - hits: array of hits within this message
+ * - remain_hits: omitted when 0; number of omitted low-priority hits
+ */
+export interface SearchMessageOutput {
+  role: MessageRole;
+  turn_index: number;
+  message_id: string;
+  hits: SearchHitOutput[];
+  remain_hits?: number;
+}
+
+/**
+ * Full search response output.
+ *
+ * - messages: results grouped by message (omitted when no message has hits)
+ */
+export type SearchNoHitsOutput = Record<string, never>;
+
+export interface SearchHitsOutput {
+  messages: SearchMessageOutput[];
+}
+
+export type SearchOutput = SearchNoHitsOutput | SearchHitsOutput;

package/src/runtime/charting.ts

@@ -0,0 +1,73 @@
+import type { PluginInput } from "../common/common.ts";
+import type { EngramConfig } from "../common/config.ts";
+import type { BrowseOutput, OverviewOutput } from "../domain/types.ts";
+
+import { createBrowseContext, resolveSessionTarget } from "../core/index.ts";
+import { log } from "./logger.ts";
+import { browseData, loadOverviewState } from "./runtime.ts";
+
+export interface ChartingData {
+  overview: OverviewOutput;
+  latestTurnDetail: BrowseOutput;
+}
+
+// =============================================================================
+// Output Assembly Helpers
+// =============================================================================
+
+function emptyLatestTurnDetail(): BrowseOutput {
+  return {
+    before_message_id: null,
+    messages: [],
+    after_message_id: null,
+  };
+}
+
+// =============================================================================
+// Charting Data Loading
+// =============================================================================
+
+/**
+ * Load the structured data used to assemble the chart block for the current session.
+ */
+export async function loadChartingData(
+  input: PluginInput,
+  sessionID: string,
+  config: EngramConfig,
+): Promise<ChartingData> {
+  const journal = log(input.client, sessionID);
+  const target = await resolveSessionTarget(input.client, sessionID, input.directory);
+  const overviewBrowse = createBrowseContext(target, true);
+  const overviewState = await loadOverviewState(input, overviewBrowse, config, journal);
+  const latestTurn = overviewState.turns.at(-1);
+  const minTurn = latestTurn
+    ? latestTurn.turn - config.context_charting.recent_turns
+    : Number.POSITIVE_INFINITY;
+  const overview: OverviewOutput = {
+    turns: overviewState.turns
+      .filter((turn) => turn.turn >= minTurn)
+      .map((turn) => turn.output),
+  };
+
+  if (!latestTurn) {
+    return {
+      overview,
+      latestTurnDetail: emptyLatestTurnDetail(),
+    };
+  }
+
+  return {
+    overview,
+    latestTurnDetail: await browseData(
+      input,
+      createBrowseContext(target, false),
+      config,
+      journal,
+      {
+        messageID: latestTurn.lastVisibleMessageId,
+        numBefore: config.context_charting.recent_messages,
+        numAfter: 0,
+      },
+    ),
+  };
+}

package/src/runtime/debug.ts

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+
+import { json } from "../common/common.ts";
+import type { ResolvedDebugModeConfig } from "../common/config.ts";
+
+export const transientSearchErrorMessage =
+  "Failed to query messages. Try again or use history_browse_turns to lookup instead.";
+
+export type ToolCallRecord = {
+  tool: string;
+  sessionID: string;
+  messageID: string;
+  targetSessionID?: string;
+  args: Record<string, unknown>;
+  output?: unknown;
+  error?: string;
+  time: string;
+};
+
+/**
+ * Check if tool call logging is enabled.
+ *
+ * Respects `enable` as the highest priority:
+ * - If `enable` is false, logging is disabled regardless of other settings.
+ * - Otherwise, returns the value of `log_tool_calls`.
+ */
+export function isToolCallLoggingEnabled(debug: ResolvedDebugModeConfig): boolean {
+  if (!debug.enable) {
+    return false;
+  }
+  return debug.log_tool_calls;
+}
+
+/**
+ * Check if any debug feature is enabled that requires directory setup.
+ *
+ * This checks if any feature that writes to `.engram/` is active,
+ * respecting `enable` as the highest priority.
+ */
+export function isDebugDirectoryNeeded(debug: ResolvedDebugModeConfig): boolean {
+  if (!debug.enable) {
+    return false;
+  }
+  return debug.log_tool_calls;
+}
+
+export function estimateSerializedTokens(value: unknown): number {
+  const bytes = Buffer.byteLength(json(value), "utf8");
+  return Math.max(1, Math.ceil(bytes / 3));
+}
+
+export function estimateCallDurationMs(startedAt: number): number {
+  return Math.max(0, Math.round(performance.now() - startedAt));
+}
+
+export function getLoggedResponsePayload(record: ToolCallRecord): unknown {
+  if (record.output !== undefined) {
+    return record.output;
+  }
+
+  if (record.error !== undefined) {
+    return { error: record.error };
+  }
+
+  return null;
+}
+
+export function formatDebugTimestamp(date = new Date()) {
+  const year = String(date.getUTCFullYear() % 100).padStart(2, "0");
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  const hour = String(date.getUTCHours()).padStart(2, "0");
+  const minute = String(date.getUTCMinutes()).padStart(2, "0");
+  const second = String(date.getUTCSeconds()).padStart(2, "0");
+  const millisecond = String(date.getUTCMilliseconds()).padStart(3, "0");
+  return `${year}${month}${day}_${hour}${minute}${second}${millisecond}`;
+}
+
+export function debugFileName(tool: string) {
+  return `${formatDebugTimestamp()}-${tool}-${randomUUID().slice(0, 8)}.json`;
+}
+
+export function getToolCallLogDirectory(projectRoot: string, sessionID: string) {
+  return join(projectRoot, ".engram", "log_tool_calls", sessionID);
+}
+
+export async function recordToolCall(
+  record: ToolCallRecord,
+  enabled: boolean,
+  durationMs: number,
+  projectRoot: string,
+) {
+  if (!enabled) return;
+
+  const dir = getToolCallLogDirectory(projectRoot, record.sessionID);
+  const filePath = join(dir, debugFileName(record.tool));
+
+  try {
+    const loggedRecord = {
+      ...record,
+      estimated_tokens: estimateSerializedTokens(getLoggedResponsePayload(record)),
+      duration_ms: durationMs,
+    };
+    await mkdir(dir, { recursive: true });
+    await writeFile(filePath, JSON.stringify(loggedRecord, null, 2), "utf8");
+  } catch {
+    return;
+  }
+}
+
+export async function ensureDebugGitIgnore(projectRoot: string) {
+  const engramDir = join(projectRoot, ".engram");
+  const gitIgnorePath = join(engramDir, ".gitignore");
+  const requiredEntries = ["log_tool_calls", ".gitignore"];
+
+  try {
+    await mkdir(engramDir, { recursive: true });
+
+    let existing = "";
+    try {
+      existing = await readFile(gitIgnorePath, "utf8");
+    } catch (error) {
+      if (
+        !(
+          error &&
+          typeof error === "object" &&
+          "code" in error &&
+          error.code === "ENOENT"
+        )
+      ) {
+        return;
+      }
+    }
+
+    const existingLines = existing
+      .replace(/\r\n/g, "\n")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+    const lineSet = new Set(existingLines);
+    const missing = requiredEntries.filter((entry) => !lineSet.has(entry));
+
+    if (missing.length === 0) {
+      return;
+    }
+
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await appendFile(gitIgnorePath, `${prefix}${missing.join("\n")}\n`, "utf8");
+  } catch {
+    // Ignore errors; best effort
+  }
+}

package/src/runtime/logger.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+export type Logger = ReturnType<typeof log>;
+
+export function log(client: Parameters<Plugin>[0]["client"], sessionID: string) {
+  const write = (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    extra?: Record<string, unknown>,
+  ) =>
+    client.app
+      .log({
+        body: {
+          service: "engram-plugin",
+          level,
+          message,
+          extra: { sessionID, ...extra },
+        },
+      })
+      .catch(() => undefined);
+
+  return {
+    trace: (message: string, extra?: Record<string, unknown>) =>
+      write("debug", message, extra),
+    debug: (message: string, extra?: Record<string, unknown>) =>
+      write("debug", message, extra),
+    info: (message: string, extra?: Record<string, unknown>) =>
+      write("info", message, extra),
+    warn: (message: string, extra?: Record<string, unknown>) =>
+      write("warn", message, extra),
+    error: (message: string, extra?: Record<string, unknown>) =>
+      write("error", message, extra),
+  };
+}