@flowcodex/core 0.3.0

package/src/session/session-store.ts

@@ -0,0 +1,339 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { SessionEvent, SessionSummary, SessionStore } from './types.js';
+import type { ContentBlock, Message } from '../types/blocks.js';
+import type { SecretScrubber } from '../infrastructure/secret-scrubber.js';
+import { DefaultSecretScrubber } from '../infrastructure/secret-scrubber.js';
+
+export interface SessionStoreOptions {
+  dir: string;
+  model?: string | undefined;
+  sessionId?: string | undefined;
+  secretScrubber?: SecretScrubber | undefined;
+}
+
+function sanitizeModel(model: string): string {
+  return model
+    .replace(/[^a-zA-Z0-9_-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+}
+
+export function generateSessionId(now: Date = new Date(), model?: string): string {
+  const iso = now.toISOString();
+  const date = iso.slice(0, 10);
+  const time = iso.slice(11, 19).replace(/:/g, '-');
+  const suffix = randomBytes(2).toString('hex');
+  const modelPart = model ? `_${sanitizeModel(model)}` : '';
+  return `${date}/${time}Z${modelPart}_${suffix}`;
+}
+
+export function projectHash(cwd: string): string {
+  return createHash('sha256').update(cwd).digest('hex').slice(0, 12);
+}
+
+export function flowcodexHome(): string {
+  return process.env.FLOWCODEX_HOME ?? path.join(os.homedir(), '.flowcodex');
+}
+
+export function sessionsDir(cwd: string): string {
+  return path.join(flowcodexHome(), 'projects', projectHash(cwd), 'sessions');
+}
+
+export function recordsDir(sessionId: string): string {
+  return path.join(flowcodexHome(), 'records', sessionId);
+}
+
+export function keyFilePath(): string {
+  return path.join(flowcodexHome(), '.key');
+}
+
+export function configFilePath(): string {
+  const home = flowcodexHome();
+  const jsoncPath = path.join(home, 'config.jsonc');
+  const jsonPath = path.join(home, 'config.json');
+  try {
+    if (existsSync(jsoncPath)) return jsoncPath;
+  } catch {
+    // fall through
+  }
+  return jsonPath;
+}
+
+export function authFilePath(): string {
+  return path.join(flowcodexHome(), 'auth.json');
+}
+
+export function reconstructMessages(events: SessionEvent[]): Message[] {
+  const messages: Message[] = [];
+  let pendingToolUses: ContentBlock[] = [];
+
+  const flushToolUses = (): void => {
+    if (pendingToolUses.length > 0) {
+      messages.push({ role: 'assistant', content: pendingToolUses });
+      pendingToolUses = [];
+    }
+  };
+
+  for (const event of events) {
+    if (event.type === 'user_input') {
+      flushToolUses();
+      messages.push({ role: 'user', content: event.content });
+    } else if (event.type === 'tool_use') {
+      pendingToolUses.push({
+        type: 'tool_use',
+        id: event.id,
+        name: event.name,
+        input: event.input,
+      });
+    } else if (event.type === 'tool_result') {
+      flushToolUses();
+      const block: ContentBlock = {
+        type: 'tool_result',
+        tool_use_id: event.id,
+        content: event.content as string,
+        is_error: event.isError,
+      };
+      const last = messages[messages.length - 1];
+      if (
+        last &&
+        last.role === 'user' &&
+        Array.isArray(last.content) &&
+        last.content.length > 0 &&
+        last.content[0]?.type === 'tool_result'
+      ) {
+        (last.content as ContentBlock[]).push(block);
+      } else {
+        messages.push({ role: 'user', content: [block] });
+      }
+    } else if (event.type === 'llm_response') {
+      flushToolUses();
+      messages.push({ role: 'assistant', content: event.content });
+    }
+  }
+  flushToolUses();
+  return messages;
+}
+
+export class DefaultSessionStore implements SessionStore {
+  readonly sessionId: string;
+  readonly filePath: string;
+  private readonly dir: string;
+  private readonly scrubber: SecretScrubber;
+  private closed = false;
+  private summaryStats: {
+    totalTokens?: number | undefined;
+    totalCost?: number | undefined;
+    iterations?: number | undefined;
+    provider?: string | undefined;
+  } = {};
+
+  constructor(opts: SessionStoreOptions) {
+    this.dir = opts.dir;
+    this.scrubber = opts.secretScrubber ?? new DefaultSecretScrubber();
+    this.sessionId = opts.sessionId ?? generateSessionId(new Date(), opts.model);
+    this.filePath = path.join(this.dir, `${this.sessionId}.jsonl`);
+  }
+
+  get sessionsDirPath(): string {
+    return this.dir;
+  }
+
+  get summaryPath(): string {
+    return this.filePath.replace(/\.jsonl$/, '.summary.json');
+  }
+
+  setSummaryStats(stats: {
+    totalTokens?: number | undefined;
+    totalCost?: number | undefined;
+    iterations?: number | undefined;
+    provider?: string | undefined;
+  }): void {
+    this.summaryStats = stats;
+  }
+
+  static async create(cwd: string, model?: string): Promise<DefaultSessionStore> {
+    const dir = sessionsDir(cwd);
+    await fsp.mkdir(dir, { recursive: true });
+    const store = new DefaultSessionStore({ dir, model });
+    await fsp.mkdir(path.dirname(store.filePath), { recursive: true });
+    return store;
+  }
+
+  static async openExisting(cwd: string, sessionId: string): Promise<DefaultSessionStore> {
+    const dir = sessionsDir(cwd);
+    await fsp.mkdir(dir, { recursive: true });
+    const store = new DefaultSessionStore({ dir, sessionId });
+    await fsp.mkdir(path.dirname(store.filePath), { recursive: true });
+    return store;
+  }
+
+  async append(event: SessionEvent): Promise<void> {
+    if (this.closed) return;
+    await fsp.mkdir(path.dirname(this.filePath), { recursive: true }).catch(() => {});
+    const scrubbed = this.scrubEvent(event);
+    const line = JSON.stringify(scrubbed) + '\n';
+    await fsp.appendFile(this.filePath, line, 'utf8');
+  }
+
+  async readAll(): Promise<SessionEvent[]> {
+    let raw: string;
+    try {
+      raw = await fsp.readFile(this.filePath, 'utf8');
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw err;
+    }
+    const out: SessionEvent[] = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line) as SessionEvent);
+      } catch {
+        // skip corrupt lines
+      }
+    }
+    return out;
+  }
+
+  async writeSummary(summary: SessionSummary): Promise<void> {
+    await fsp.mkdir(path.dirname(this.summaryPath), { recursive: true }).catch(() => {});
+    await fsp.writeFile(this.summaryPath, JSON.stringify(summary, null, 2), 'utf8');
+  }
+
+  async close(reason: 'normal' | 'aborted' | 'error' | 'crashed' = 'normal'): Promise<void> {
+    if (this.closed) return;
+    await this.append({ type: 'session_end', ts: new Date().toISOString(), reason });
+    this.closed = true;
+    const events = await this.readAll();
+    const summary = this.computeSummary(events, reason);
+    await this.writeSummary(summary);
+  }
+
+  static async listSessions(projectRoot: string): Promise<SessionSummary[]> {
+    const dir = sessionsDir(projectRoot);
+    let entries: string[];
+    try {
+      entries = await fsp.readdir(dir, { recursive: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw err;
+    }
+    const summaries: SessionSummary[] = [];
+    for (const entry of entries) {
+      if (entry.endsWith('.summary.json')) {
+        try {
+          const raw = await fsp.readFile(path.join(dir, entry), 'utf8');
+          summaries.push(JSON.parse(raw) as SessionSummary);
+        } catch {
+          // skip corrupt
+        }
+      }
+    }
+    return summaries;
+  }
+
+  static async deleteSession(projectRoot: string, sessionIdPrefix: string): Promise<void> {
+    const dir = sessionsDir(projectRoot);
+    let entries: string[];
+    try {
+      entries = await fsp.readdir(dir, { recursive: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+      throw err;
+    }
+    for (const entry of entries) {
+      const base = path.basename(entry);
+      const idPart = base.replace(/\.(jsonl|summary\.json)$/, '');
+      if (
+        idPart === sessionIdPrefix ||
+        idPart.startsWith(sessionIdPrefix) ||
+        idPart.endsWith(sessionIdPrefix)
+      ) {
+        await fsp.unlink(path.join(dir, entry)).catch(() => {});
+      }
+    }
+  }
+
+  private computeSummary(events: SessionEvent[], outcome: string): SessionSummary {
+    let title = '(empty session)';
+    let startedAt = '';
+    let endedAt = '';
+    let messageCount = 0;
+    let toolCallCount = 0;
+    let toolErrorCount = 0;
+    let model = this.summaryStats.provider ?? '';
+
+    for (const event of events) {
+      switch (event.type) {
+        case 'session_start':
+          startedAt = event.ts;
+          model = event.model;
+          break;
+        case 'session_resumed':
+          startedAt = event.ts;
+          model = event.model;
+          break;
+        case 'user_input':
+          if (title === '(empty session)') {
+            title =
+              typeof event.content === 'string' ? event.content.slice(0, 50) : '(structured input)';
+          }
+          messageCount++;
+          break;
+        case 'llm_response':
+          messageCount++;
+          break;
+        case 'tool_use':
+          toolCallCount++;
+          break;
+        case 'tool_result':
+          if (event.isError) toolErrorCount++;
+          break;
+        case 'session_end':
+          endedAt = event.ts;
+          break;
+      }
+    }
+
+    if (!endedAt) endedAt = new Date().toISOString();
+
+    return {
+      id: this.sessionId,
+      title,
+      model,
+      provider: this.summaryStats.provider ?? model,
+      startedAt,
+      endedAt,
+      messageCount,
+      iterationCount: this.summaryStats.iterations ?? 0,
+      toolCallCount,
+      toolErrorCount,
+      totalTokens: this.summaryStats.totalTokens ?? 0,
+      totalCost: this.summaryStats.totalCost ?? 0,
+      outcome: outcome === 'normal' ? 'completed' : outcome === 'aborted' ? 'aborted' : 'error',
+    };
+  }
+
+  private scrubEvent(event: SessionEvent): SessionEvent {
+    if (event.type === 'user_input') {
+      if (typeof event.content === 'string') {
+        return { ...event, content: this.scrubber.scrub(event.content) };
+      }
+      return {
+        ...event,
+        content: this.scrubber.scrubObject(event.content),
+      };
+    }
+    if (event.type === 'llm_response') {
+      return { ...event, content: this.scrubber.scrubObject(event.content) };
+    }
+    if (event.type === 'tool_result') {
+      return { ...event, content: this.scrubber.scrubObject(event.content) };
+    }
+    return event;
+  }
+}

package/src/session/types.ts

@@ -0,0 +1,100 @@
+import type { ContentBlock } from '../types/blocks.js';
+import type { Usage } from '../infrastructure/token-counter.js';
+
+export type SessionEvent =
+  | { type: 'session_start'; ts: string; id: string; model: string; cwd: string }
+  | { type: 'session_resumed'; ts: string; id: string; model: string }
+  | { type: 'user_input'; ts: string; content: string | ContentBlock[] }
+  | {
+      type: 'llm_request';
+      ts: string;
+      model: string;
+      messageCount: number;
+      estimatedInputTokens?: number | undefined;
+      toolCount?: number | undefined;
+    }
+  | {
+      type: 'llm_response';
+      ts: string;
+      content: ContentBlock[];
+      stopReason: string;
+      usage: Usage;
+    }
+  | { type: 'tool_use'; ts: string; name: string; id: string; input: unknown }
+  | { type: 'tool_result'; ts: string; id: string; content: unknown; isError: boolean }
+  | {
+      type: 'compaction';
+      ts: string;
+      before: number;
+      after: number;
+      level: string;
+      aggressive: boolean;
+    }
+  | { type: 'ctx_pct'; ts: string; pct: number }
+  | { type: 'in_flight_start'; ts: string; kind: 'tool_batch' | 'llm_call' }
+  | { type: 'in_flight_end'; ts: string; kind: 'tool_batch' | 'llm_call' }
+  | { type: 'checkpoint'; ts: string; label?: string | undefined }
+  | { type: 'error'; ts: string; error: unknown }
+  | { type: 'session_end'; ts: string; reason: 'normal' | 'aborted' | 'error' | 'crashed' };
+
+export interface AuditEntry {
+  index: number;
+  id: string;
+  ts: string;
+  prevHash: string;
+  hash: string;
+  toolName: string;
+  toolUseId: string;
+  input: unknown;
+  output: unknown;
+  isError: boolean;
+}
+
+export type VerifyResult =
+  | { ok: true; entries: number }
+  | { ok: false; brokenAt: number; reason: string };
+
+export interface SessionSummary {
+  id: string;
+  title: string;
+  model: string;
+  provider: string;
+  startedAt: string;
+  endedAt: string;
+  messageCount: number;
+  iterationCount: number;
+  toolCallCount: number;
+  toolErrorCount: number;
+  totalTokens: number;
+  totalCost: number;
+  outcome: 'completed' | 'error' | 'aborted';
+}
+
+export interface SessionStore {
+  append(event: SessionEvent): Promise<void>;
+  readAll(): Promise<SessionEvent[]>;
+  close(reason?: 'normal' | 'aborted' | 'error' | 'crashed'): Promise<void>;
+  writeSummary(summary: SessionSummary): Promise<void>;
+  readonly sessionId: string;
+  readonly filePath: string;
+}
+
+export interface SecretVault {
+  isEncrypted(value: string): boolean;
+  encrypt(plaintext: string): string;
+  decrypt(value: string): string;
+}
+
+export interface AuditLog {
+  record(input: {
+    sessionId: string;
+    toolName: string;
+    toolUseId: string;
+    input: unknown;
+    output: unknown;
+    isError: boolean;
+  }): Promise<AuditEntry>;
+  verify(sessionId: string): Promise<VerifyResult>;
+  load(sessionId: string): Promise<AuditEntry[]>;
+  flush(sessionId: string): Promise<void>;
+}

package/src/types/blocks.ts

@@ -0,0 +1,56 @@
+export type ImageSource =
+  | { type: 'base64'; media_type: string; data: string }
+  | { type: 'url'; url: string };
+
+export interface CacheControl {
+  type: 'ephemeral';
+  ttl?: '5m' | '1h' | undefined;
+}
+
+export interface TextBlock {
+  type: 'text';
+  text: string;
+  cache_control?: CacheControl | undefined;
+}
+
+export type ContentBlock =
+  | TextBlock
+  | { type: 'thinking'; text: string; signature?: string | undefined }
+  | { type: 'tool_use'; id: string; name: string; input: unknown }
+  | { type: 'tool_result'; tool_use_id: string; content: string | ContentBlock[]; is_error?: boolean | undefined }
+  | { type: 'image'; source: ImageSource }
+  | { type: 'pdf'; source: { type: 'base64'; media_type: 'application/pdf'; data: string } };
+
+export type Role = 'system' | 'user' | 'assistant';
+
+export interface Message {
+  role: Role;
+  content: ContentBlock[] | string;
+}
+
+export type ModelId = string;
+export type ModelRef = { provider: string; model: ModelId };
+
+export function isToolUseBlock(block: ContentBlock): block is { type: 'tool_use'; id: string; name: string; input: unknown } {
+  return block.type === 'tool_use';
+}
+
+export function isToolResultBlock(block: ContentBlock): block is { type: 'tool_result'; tool_use_id: string; content: string | ContentBlock[]; is_error?: boolean | undefined } {
+  return block.type === 'tool_result';
+}
+
+export function isTextBlock(block: ContentBlock): block is TextBlock {
+  return block.type === 'text';
+}
+
+export function isThinkingBlock(block: ContentBlock): block is { type: 'thinking'; text: string; signature?: string | undefined } {
+  return block.type === 'thinking';
+}
+
+export function isImageBlock(block: ContentBlock): block is { type: 'image'; source: ImageSource } {
+  return block.type === 'image';
+}
+
+export function isPdfBlock(block: ContentBlock): block is { type: 'pdf'; source: { type: 'base64'; media_type: 'application/pdf'; data: string } } {
+  return block.type === 'pdf';
+}

package/src/types/context.ts

@@ -0,0 +1,54 @@
+import type { ContentBlock, Message, ModelRef } from './blocks.js';
+import type { StructuredOutputConfig } from './provider.js';
+import type { ConversationState } from '../agent/conversation-state.js';
+
+export interface ToolUse {
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+export interface ToolResult {
+  toolUseId: string;
+  block: { type: 'tool_result'; tool_use_id: string; content: string | ContentBlock[]; is_error?: boolean | undefined };
+}
+
+export interface Budget {
+  maxIterations: number;
+  maxTokens: number;
+  maxCost: number;
+}
+
+export type AgentStatus = 'completed' | 'aborted' | 'limit_reached' | 'budget_exceeded' | 'failed' | 'structured';
+
+export interface RunResult {
+  status: AgentStatus;
+  iterations: number;
+  finalText: string;
+  error?: unknown | undefined;
+  abortReason?: string | undefined;
+  structuredResult?: unknown | undefined;
+}
+
+export interface Context {
+  messages: Message[];
+  state: ConversationState;
+  model: ModelRef;
+  projectRoot: string;
+  workingDir: string;
+  tools: unknown[];
+  readFiles: Map<string, number>;
+  btwNotes: string[];
+  lastRequestTokens: number;
+  budget: Budget;
+  signal: AbortSignal;
+  systemPrompt: ContentBlock[];
+  readOnly: boolean;
+  structuredOutput?: StructuredOutputConfig | undefined;
+  maxTokens?: number | undefined;
+  batchToolUse?: boolean | undefined;
+  registerAbortHook(fn: () => void | Promise<void>): () => void;
+  setWorkingDir(path: string): void;
+  recordRead(absPath: string, mtimeMs: number): void;
+  hasRead(absPath: string): boolean;
+}