ashlrcode 1.0.0

package/src/persistence/memory.ts

@@ -0,0 +1,129 @@
+/**
+ * Memory system — cross-session persistent context.
+ *
+ * Per-project memory stored at ~/.ashlrcode/memory/<project-hash>/
+ * Memory types: user, feedback, project, reference (same as Claude Code).
+ */
+
+import { existsSync } from "fs";
+import { readFile, writeFile, readdir, mkdir, unlink } from "fs/promises";
+import { join } from "path";
+import { createHash } from "crypto";
+import { getConfigDir } from "../config/settings.ts";
+
+export interface MemoryEntry {
+  name: string;
+  description: string;
+  type: "user" | "feedback" | "project" | "reference";
+  content: string;
+  filePath: string;
+}
+
+function getProjectHash(cwd: string): string {
+  return createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+}
+
+function getMemoryDir(cwd: string): string {
+  return join(getConfigDir(), "memory", getProjectHash(cwd));
+}
+
+/**
+ * Load all memory entries for the current project.
+ */
+export async function loadMemories(cwd: string): Promise<MemoryEntry[]> {
+  const memDir = getMemoryDir(cwd);
+  if (!existsSync(memDir)) return [];
+
+  const files = await readdir(memDir);
+  const memories: MemoryEntry[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".md")) continue;
+    const filePath = join(memDir, file);
+    const content = await readFile(filePath, "utf-8");
+    const parsed = parseMemoryFile(content, filePath);
+    if (parsed) memories.push(parsed);
+  }
+
+  return memories;
+}
+
+/**
+ * Save a memory entry.
+ */
+export async function saveMemory(
+  cwd: string,
+  entry: Omit<MemoryEntry, "filePath">
+): Promise<string> {
+  const memDir = getMemoryDir(cwd);
+  await mkdir(memDir, { recursive: true });
+
+  const slug = entry.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .slice(0, 50);
+  const filePath = join(memDir, `${slug}.md`);
+
+  const fileContent = `---
+name: ${entry.name}
+description: ${entry.description}
+type: ${entry.type}
+---
+
+${entry.content}
+`;
+
+  await writeFile(filePath, fileContent, "utf-8");
+  return filePath;
+}
+
+/**
+ * Delete a memory by name.
+ */
+export async function deleteMemory(cwd: string, name: string): Promise<boolean> {
+  const memories = await loadMemories(cwd);
+  const match = memories.find(
+    (m) => m.name.toLowerCase() === name.toLowerCase()
+  );
+  if (!match) return false;
+
+  await unlink(match.filePath);
+  return true;
+}
+
+/**
+ * Format memories for inclusion in the system prompt.
+ */
+export function formatMemoriesForPrompt(memories: MemoryEntry[]): string {
+  if (memories.length === 0) return "";
+
+  const sections = memories.map(
+    (m) => `### ${m.name} (${m.type})\n${m.content}`
+  );
+
+  return `\n\n# Project Memory\n\n${sections.join("\n\n")}`;
+}
+
+function parseMemoryFile(
+  content: string,
+  filePath: string
+): MemoryEntry | null {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!frontmatterMatch) return null;
+
+  const frontmatter = frontmatterMatch[1]!;
+  const body = frontmatterMatch[2]!.trim();
+
+  const name = extractField(frontmatter, "name");
+  const description = extractField(frontmatter, "description");
+  const type = extractField(frontmatter, "type") as MemoryEntry["type"];
+
+  if (!name || !type) return null;
+
+  return { name, description: description ?? "", type, content: body, filePath };
+}
+
+function extractField(frontmatter: string, field: string): string | null {
+  const match = frontmatter.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
+  return match?.[1]?.trim() ?? null;
+}

package/src/persistence/session.ts

@@ -0,0 +1,289 @@
+/**
+ * Session persistence — JSONL append-only logs.
+ *
+ * Pattern from Claude Code: each session is a JSONL file at
+ * ~/.ashlrcode/sessions/<session-id>.jsonl
+ *
+ * Each line is a JSON object representing a message or event.
+ */
+
+import { existsSync } from "fs";
+import { readFile, writeFile, appendFile, mkdir, readdir } from "fs/promises";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { getConfigDir } from "../config/settings.ts";
+import type { Message } from "../providers/types.ts";
+
+export interface SessionMetadata {
+  id: string;
+  cwd: string;
+  createdAt: string;
+  updatedAt: string;
+  provider: string;
+  model: string;
+  messageCount: number;
+  title?: string;
+}
+
+interface SessionEntry {
+  type: "message" | "metadata" | "compact";
+  timestamp: string;
+  data: Message | SessionMetadata | { summary: string; messageCountBefore: number };
+}
+
+function getSessionsDir(): string {
+  return join(getConfigDir(), "sessions");
+}
+
+export class Session {
+  readonly id: string;
+  private filePath: string;
+  private metadata: SessionMetadata;
+
+  constructor(id?: string) {
+    this.id = id ?? randomUUID().slice(0, 8);
+    this.filePath = join(getSessionsDir(), `${this.id}.jsonl`);
+    this.metadata = {
+      id: this.id,
+      cwd: process.cwd(),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      provider: "",
+      model: "",
+      messageCount: 0,
+    };
+  }
+
+  async init(provider: string, model: string): Promise<void> {
+    await mkdir(getSessionsDir(), { recursive: true });
+    this.metadata.provider = provider;
+    this.metadata.model = model;
+    await this.appendEntry({
+      type: "metadata",
+      timestamp: new Date().toISOString(),
+      data: this.metadata,
+    });
+  }
+
+  async appendMessage(message: Message): Promise<void> {
+    this.metadata.messageCount++;
+    this.metadata.updatedAt = new Date().toISOString();
+    await this.appendEntry({
+      type: "message",
+      timestamp: new Date().toISOString(),
+      data: message,
+    });
+  }
+
+  async appendMessages(messages: Message[]): Promise<void> {
+    for (const msg of messages) {
+      await this.appendMessage(msg);
+    }
+  }
+
+  async insertCompactBoundary(summary: string, messageCountBefore: number): Promise<void> {
+    await this.appendEntry({
+      type: "compact",
+      timestamp: new Date().toISOString(),
+      data: { summary, messageCountBefore },
+    });
+  }
+
+  /**
+   * Load ALL messages, ignoring compact boundaries.
+   * Used for forking and compaction where full history is needed.
+   */
+  async loadAllMessages(): Promise<Message[]> {
+    if (!existsSync(this.filePath)) return [];
+
+    const content = await readFile(this.filePath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+    const messages: Message[] = [];
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line) as SessionEntry;
+        if (entry.type === "message") {
+          messages.push(entry.data as Message);
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Load messages from the last compact boundary forward.
+   * If a compact boundary exists, only messages after it are returned,
+   * with a synthetic assistant message prepended containing the summary.
+   */
+  async loadMessages(): Promise<Message[]> {
+    if (!existsSync(this.filePath)) return [];
+
+    const content = await readFile(this.filePath, "utf-8");
+    const lines = content.trim().split("\n").filter(Boolean);
+
+    // Scan in reverse to find last compact boundary
+    let lastCompactIndex = -1;
+    let compactSummary = "";
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const entry = JSON.parse(lines[i]!) as SessionEntry;
+        if (entry.type === "compact") {
+          lastCompactIndex = i;
+          compactSummary = (entry.data as { summary: string; messageCountBefore: number }).summary;
+          break;
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    // Load messages after the boundary (or all if no boundary)
+    const startIndex = lastCompactIndex >= 0 ? lastCompactIndex + 1 : 0;
+    const messages: Message[] = [];
+
+    for (let i = startIndex; i < lines.length; i++) {
+      try {
+        const entry = JSON.parse(lines[i]!) as SessionEntry;
+        if (entry.type === "message") {
+          messages.push(entry.data as Message);
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    // Prepend synthetic summary message if we found a compact boundary
+    if (lastCompactIndex >= 0) {
+      messages.unshift({
+        role: "user",
+        content: "[Previous session context]\n" + compactSummary,
+      });
+    }
+
+    return messages;
+  }
+
+  async setTitle(title: string): Promise<void> {
+    this.metadata.title = title;
+    // Persist the title update
+    await this.appendEntry({
+      type: "metadata",
+      timestamp: new Date().toISOString(),
+      data: { ...this.metadata, title },
+    });
+  }
+
+  private async appendEntry(entry: SessionEntry): Promise<void> {
+    await mkdir(getSessionsDir(), { recursive: true });
+    await appendFile(this.filePath, JSON.stringify(entry) + "\n", "utf-8");
+  }
+}
+
+/**
+ * List recent sessions.
+ */
+export async function listSessions(limit = 10): Promise<SessionMetadata[]> {
+  const sessionsDir = getSessionsDir();
+  if (!existsSync(sessionsDir)) return [];
+
+  const files = await readdir(sessionsDir);
+  const sessions: SessionMetadata[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith(".jsonl")) continue;
+
+    const content = await readFile(join(sessionsDir, file), "utf-8");
+    const lines = content.split("\n").filter(Boolean);
+    if (lines.length === 0) continue;
+
+    try {
+      // Find the LAST metadata entry (most recent, includes title updates)
+      let latestMetadata: SessionMetadata | null = null;
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line) as SessionEntry;
+          if (entry.type === "metadata") {
+            latestMetadata = entry.data as SessionMetadata;
+          }
+        } catch { /* skip malformed lines */ }
+      }
+      if (latestMetadata) {
+        sessions.push(latestMetadata);
+      }
+    } catch {
+      // Skip malformed files
+    }
+  }
+
+  // Sort by most recent first
+  sessions.sort(
+    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+  );
+
+  return sessions.slice(0, limit);
+}
+
+/**
+ * Resume a session by ID.
+ */
+export async function resumeSession(id: string): Promise<{
+  session: Session;
+  messages: Message[];
+} | null> {
+  const session = new Session(id);
+  const messages = await session.loadMessages();
+  if (messages.length === 0) return null;
+  return { session, messages };
+}
+
+/**
+ * Get the most recent session for a given working directory.
+ */
+export async function getLastSessionForCwd(cwd: string): Promise<string | null> {
+  const sessions = await listSessions(50);
+  const match = sessions.find((s) => s.cwd === cwd);
+  return match?.id ?? null;
+}
+
+/**
+ * Fork a session — create a new session with copied message history.
+ */
+export async function forkSession(
+  sourceId: string,
+  provider: string,
+  model: string
+): Promise<{ session: Session; messages: Message[] } | null> {
+  const source = new Session(sourceId);
+  const messages = await source.loadAllMessages();
+  if (messages.length === 0) return null;
+
+  const forked = new Session();
+  await forked.init(provider, model);
+  await forked.appendMessages(messages);
+
+  return { session: forked, messages };
+}
+
+/**
+ * Compact a session — insert a boundary marker with a summary of recent messages.
+ * Messages before the boundary are excluded from loadMessages() but preserved on disk.
+ */
+export async function compactSession(id: string): Promise<{ messagesBefore: number; summary: string }> {
+  const session = new Session(id);
+  const allMessages = await session.loadAllMessages();
+  const messagesBefore = allMessages.length;
+
+  // Generate summary from recent messages
+  const recentText = allMessages.slice(-10).map(m => {
+    const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+    return `${m.role}: ${content.slice(0, 200)}`;
+  }).join("\n");
+
+  const summary = `Session context (${messagesBefore} messages):\n${recentText}`;
+  await session.insertCompactBoundary(summary, messagesBefore);
+  return { messagesBefore, summary };
+}

package/src/planning/plan-mode.ts

@@ -0,0 +1,128 @@
+/**
+ * Plan Mode — read-only exploration → strategic questions → plan → execute.
+ *
+ * When plan mode is active:
+ * - Only read-only tools are available (Read, Glob, Grep, WebFetch, AskUser)
+ * - Write/Edit/Bash are blocked
+ * - The model writes a plan to a .md file
+ * - User approves → plan mode exits → execution begins
+ */
+
+import { writeFile, readFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { getConfigDir } from "../config/settings.ts";
+
+export interface PlanState {
+  active: boolean;
+  planFilePath: string | null;
+  startedAt: string | null;
+}
+
+function getPlansDir(): string {
+  return join(getConfigDir(), "plans");
+}
+
+let state: PlanState = {
+  active: false,
+  planFilePath: null,
+  startedAt: null,
+};
+
+/**
+ * Generate a memorable plan name (adjective-noun format).
+ */
+function generatePlanName(): string {
+  const adjectives = [
+    "swift", "bold", "calm", "deep", "keen", "bright", "clear", "sharp",
+    "steady", "agile", "precise", "focused", "direct", "elegant", "robust",
+    "clean", "solid", "smart", "lean", "fluid",
+  ];
+  const nouns = [
+    "falcon", "compass", "anchor", "bridge", "prism", "beacon", "forge",
+    "summit", "atlas", "cipher", "nexus", "pulse", "spark", "vector",
+    "zenith", "orbit", "ridge", "delta", "apex", "crest",
+  ];
+
+  const adj = adjectives[Math.floor(Math.random() * adjectives.length)]!;
+  const noun = nouns[Math.floor(Math.random() * nouns.length)]!;
+  return `${adj}-${noun}`;
+}
+
+export async function enterPlanMode(): Promise<string> {
+  const plansDir = getPlansDir();
+  await mkdir(plansDir, { recursive: true });
+
+  const planName = generatePlanName();
+  const planFile = join(plansDir, `${planName}.md`);
+
+  state = {
+    active: true,
+    planFilePath: planFile,
+    startedAt: new Date().toISOString(),
+  };
+
+  return planFile;
+}
+
+export function exitPlanMode(): void {
+  state = {
+    active: false,
+    planFilePath: null,
+    startedAt: null,
+  };
+}
+
+export function isPlanMode(): boolean {
+  return state.active;
+}
+
+export function getPlanFilePath(): string | null {
+  return state.planFilePath;
+}
+
+export function getPlanState(): PlanState {
+  return { ...state };
+}
+
+export async function writePlan(content: string): Promise<void> {
+  if (!state.planFilePath) throw new Error("No active plan");
+  await writeFile(state.planFilePath, content, "utf-8");
+}
+
+export async function readPlan(): Promise<string | null> {
+  if (!state.planFilePath || !existsSync(state.planFilePath)) return null;
+  return await readFile(state.planFilePath, "utf-8");
+}
+
+/**
+ * Get the plan mode system prompt addition.
+ */
+export function getPlanModePrompt(): string {
+  if (!state.active) return "";
+
+  return `
+## PLAN MODE ACTIVE
+
+You are in plan mode. You MUST follow these rules:
+- You MUST NOT make any edits to files (no Write, Edit, or Bash commands that modify files)
+- You CAN use read-only tools: Read, Glob, Grep, WebFetch, AskUser
+- You SHOULD explore the codebase to understand the problem
+- You SHOULD ask strategic questions using AskUser before proposing a plan
+- You MUST write your plan to the plan file: ${state.planFilePath}
+- Questions should emerge from actual code exploration, not be generic
+
+### Plan Workflow:
+1. Explore the codebase with read-only tools
+2. Ask 1-4 strategic questions using AskUser
+3. Write a detailed plan to the plan file using PlanWrite
+4. Call ExitPlan when the plan is ready for user approval
+
+### Plan File Format:
+- Start with a Context section explaining why the change is needed
+- Include specific file paths to modify
+- Reference existing functions/utilities to reuse
+- Include a verification section (how to test)
+- Be concise but detailed enough to execute
+`;
+}

package/src/planning/plan-tools.ts

@@ -0,0 +1,138 @@
+/**
+ * Plan mode tools — EnterPlan, ExitPlan, PlanWrite.
+ */
+
+import type { Tool, ToolContext } from "../tools/types.ts";
+import {
+  enterPlanMode,
+  exitPlanMode,
+  isPlanMode,
+  getPlanFilePath,
+  writePlan,
+  readPlan,
+} from "./plan-mode.ts";
+
+export const enterPlanTool: Tool = {
+  name: "EnterPlan",
+
+  prompt() {
+    return "Enter plan mode. In plan mode, only read-only tools are available. Use this when you need to explore a codebase and design an approach before making changes. Creates a plan file for writing your plan.";
+  },
+
+  inputSchema() {
+    return {
+      type: "object",
+      properties: {},
+      required: [],
+    };
+  },
+
+  isReadOnly() {
+    return true;
+  },
+  isDestructive() {
+    return false;
+  },
+  isConcurrencySafe() {
+    return false;
+  },
+
+  validateInput() {
+    if (isPlanMode()) return "Already in plan mode";
+    return null;
+  },
+
+  async call(_input, _context) {
+    const planFile = await enterPlanMode();
+    return `Plan mode activated. Write your plan to: ${planFile}\n\nAvailable tools: Read, Glob, Grep, WebFetch, AskUser, PlanWrite, ExitPlan\nBlocked tools: Write, Edit, Bash (anything that modifies files)`;
+  },
+};
+
+export const exitPlanTool: Tool = {
+  name: "ExitPlan",
+
+  prompt() {
+    return "Exit plan mode. Call this when your plan is complete and ready for user approval. The plan file will be presented to the user for review.";
+  },
+
+  inputSchema() {
+    return {
+      type: "object",
+      properties: {},
+      required: [],
+    };
+  },
+
+  isReadOnly() {
+    return true;
+  },
+  isDestructive() {
+    return false;
+  },
+  isConcurrencySafe() {
+    return false;
+  },
+
+  validateInput() {
+    if (!isPlanMode()) return "Not in plan mode";
+    return null;
+  },
+
+  async call(_input, _context) {
+    const plan = await readPlan();
+    const planFile = getPlanFilePath();
+    exitPlanMode();
+
+    if (!plan) {
+      return "Plan mode exited. Warning: No plan was written to the plan file.";
+    }
+
+    return `Plan mode exited. Plan saved to: ${planFile}\n\n--- Plan Preview ---\n${plan.slice(0, 2000)}${plan.length > 2000 ? "\n\n[... truncated ...]" : ""}`;
+  },
+};
+
+export const planWriteTool: Tool = {
+  name: "PlanWrite",
+
+  prompt() {
+    return "Write content to the plan file. Use this in plan mode to record your implementation plan. Can be called multiple times to build the plan incrementally.";
+  },
+
+  inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        content: {
+          type: "string",
+          description: "The plan content (markdown format)",
+        },
+      },
+      required: ["content"],
+    };
+  },
+
+  isReadOnly() {
+    return true; // Writing to the plan file is allowed in plan mode
+  },
+  isDestructive() {
+    return false;
+  },
+  isConcurrencySafe() {
+    return false;
+  },
+
+  validateInput(input) {
+    if (!isPlanMode()) return "Not in plan mode. Call EnterPlan first.";
+    if (!input.content || typeof input.content !== "string") {
+      return "content is required";
+    }
+    return null;
+  },
+
+  async call(input, _context) {
+    const content = input.content as string;
+    await writePlan(content);
+    const lines = content.split("\n").length;
+    return `Plan updated (${lines} lines). Call ExitPlan when ready for user review.`;
+  },
+};