interference-agent 0.1.0

package/src/session/__tests__/session.test.ts

@@ -0,0 +1,180 @@
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import * as path from "node:path";
+import {
+  createSession,
+  saveSession,
+  loadSession,
+  listSessions,
+  latestSession,
+  deleteSession,
+  cleanupSessions,
+  initStore,
+} from "../store.ts";
+import {
+  initSnapshot,
+  snapshotFile,
+  undo,
+  redo,
+  nextTurn,
+  canUndo,
+  canRedo,
+  cleanupSnapshots,
+  finalizeSnapshots,
+} from "../snapshot.ts";
+import type { ModelMessage } from "ai";
+
+const TMP = path.join(process.cwd(), ".test-tmp-session");
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(TMP, { recursive: true });
+  await writeFile(path.join(TMP, "a.txt"), "original a\n");
+  await writeFile(path.join(TMP, "b.txt"), "original b\n");
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("session store", () => {
+  test("create and save session", async () => {
+    const session = createSession({ mode: "plan" });
+    expect(session.meta.id).toBeTruthy();
+    expect(session.messages).toEqual([]);
+
+    session.messages.push({ role: "user", content: "hello" } as ModelMessage);
+    await saveSession(session);
+
+    const loaded = await loadSession(session.meta.id);
+    expect(loaded).not.toBeNull();
+    expect(loaded!.messages.length).toBe(1);
+    expect(loaded!.meta.mode).toBe("plan");
+
+    await deleteSession(session.meta.id);
+  });
+
+  test("load nonexistent session returns null", async () => {
+    const s = await loadSession("nonexistent-id");
+    expect(s).toBeNull();
+  });
+
+  test("list sessions", async () => {
+    const a = createSession();
+    const b = createSession();
+    a.messages.push({ role: "user", content: "a" } as ModelMessage);
+    b.messages.push({ role: "user", content: "b" } as ModelMessage);
+    await saveSession(a);
+    await saveSession(b);
+
+    const list = await listSessions();
+    expect(list.length).toBeGreaterThanOrEqual(2);
+
+    await deleteSession(a.meta.id);
+    await deleteSession(b.meta.id);
+  });
+
+  test("latest session", async () => {
+    const a = createSession();
+    await saveSession(a);
+    const latest = await latestSession();
+    expect(latest).not.toBeNull();
+    expect(latest!.meta.id).toBe(a.meta.id);
+    await deleteSession(a.meta.id);
+  });
+
+  test("cleanup keeps N most recent", async () => {
+    for (let i = 0; i < 5; i++) {
+      const s = createSession();
+      await saveSession(s);
+      await Bun.sleep(10);
+    }
+    await cleanupSessions(2);
+    const list = await listSessions();
+    expect(list.length).toBeLessThanOrEqual(2);
+    for (const m of list) await deleteSession(m.id);
+  });
+});
+
+describe("snapshot undo/redo", () => {
+  test("snapshot and undo single file", async () => {
+    initSnapshot("test-s1");
+    await snapshotFile(path.join(TMP, "a.txt"));
+    nextTurn();
+
+    await writeFile(path.join(TMP, "a.txt"), "modified\n");
+    await finalizeSnapshots();
+    let content = await Bun.file(path.join(TMP, "a.txt")).text();
+    expect(content).toBe("modified\n");
+
+    const restored = await undo();
+    expect(restored).toContain(path.join(TMP, "a.txt"));
+    content = await Bun.file(path.join(TMP, "a.txt")).text();
+    expect(content).toBe("original a\n");
+    expect(canUndo()).toBe(false);
+    expect(canRedo()).toBe(true);
+
+    await cleanupSnapshots();
+  });
+
+  test("snapshot and redo", async () => {
+    initSnapshot("test-s2");
+    await writeFile(path.join(TMP, "b.txt"), "original b\n");
+
+    await snapshotFile(path.join(TMP, "b.txt"));
+    nextTurn();
+    await writeFile(path.join(TMP, "b.txt"), "changed\n");
+    await finalizeSnapshots();
+
+    await undo();
+    await redo();
+    const content = await Bun.file(path.join(TMP, "b.txt")).text();
+    expect(content).toBe("changed\n");
+    expect(canRedo()).toBe(false);
+
+    await cleanupSnapshots();
+  });
+
+  test("multiple snapshots in one turn", async () => {
+    initSnapshot("test-s3");
+    await writeFile(path.join(TMP, "a.txt"), "v1\n");
+    await writeFile(path.join(TMP, "b.txt"), "v1\n");
+
+    await snapshotFile(path.join(TMP, "a.txt"));
+    await snapshotFile(path.join(TMP, "b.txt"));
+    nextTurn();
+
+    await writeFile(path.join(TMP, "a.txt"), "v2\n");
+    await writeFile(path.join(TMP, "b.txt"), "v2\n");
+    await finalizeSnapshots();
+
+    const restored = await undo();
+    expect(restored.length).toBe(2);
+
+    expect(await Bun.file(path.join(TMP, "a.txt")).text()).toBe("v1\n");
+    expect(await Bun.file(path.join(TMP, "b.txt")).text()).toBe("v1\n");
+
+    await cleanupSnapshots();
+  });
+
+  test("undo with no snapshots returns empty", async () => {
+    initSnapshot("test-s4");
+    const restored = await undo();
+    expect(restored).toEqual([]);
+    expect(canUndo()).toBe(false);
+    await cleanupSnapshots();
+  });
+
+  test("redo with no redo stack returns empty", async () => {
+    initSnapshot("test-s5");
+    const restored = await redo();
+    expect(restored).toEqual([]);
+    await cleanupSnapshots();
+  });
+
+  test("snapshot without initSession is no-op", async () => {
+    initSnapshot("");
+    await snapshotFile(path.join(TMP, "a.txt"));
+    expect(canUndo()).toBe(false);
+  });
+});

package/src/session/snapshot.ts

@@ -0,0 +1,122 @@
+import { mkdir, copyFile, rm } from "node:fs/promises";
+import * as path from "node:path";
+import { snapshotsDir } from "./store.ts";
+
+interface SnapshotEntry {
+  turn: number;
+  file: string;
+  beforePath: string;
+  afterPath: string;
+}
+
+interface UndoEntry {
+  turn: number;
+  entries: SnapshotEntry[];
+}
+
+let undoStack: UndoEntry[] = [];
+let redoStack: UndoEntry[] = [];
+let sessionId = "";
+let turnCounter = 0;
+
+export function initSnapshot(sid: string) {
+  sessionId = sid;
+  undoStack = [];
+  redoStack = [];
+  turnCounter = 0;
+}
+
+export function nextTurn() {
+  turnCounter++;
+}
+
+export async function snapshotFile(filePath: string): Promise<void> {
+  if (!sessionId) return;
+  const dir = path.join(snapshotsDir(sessionId), String(turnCounter));
+  await mkdir(dir, { recursive: true });
+
+  const abs = path.resolve(process.cwd(), filePath);
+  const base = path.basename(abs);
+  const beforePath = path.join(dir, `before_${base}`);
+  const afterPath = path.join(dir, `after_${base}`);
+
+  try {
+    await copyFile(abs, beforePath);
+  } catch {
+    return;
+  }
+
+  const entry: SnapshotEntry = { turn: turnCounter, file: filePath, beforePath, afterPath };
+
+  if (undoStack.length > 0 && undoStack[undoStack.length - 1]!.turn === turnCounter) {
+    undoStack[undoStack.length - 1]!.entries.push(entry);
+  } else {
+    undoStack.push({ turn: turnCounter, entries: [entry] });
+  }
+
+  if (undoStack.length > 50) undoStack.shift();
+}
+
+export async function finalizeSnapshots(): Promise<void> {
+  if (!sessionId || undoStack.length === 0) return;
+  const entry = undoStack[undoStack.length - 1]!;
+  for (const e of entry.entries) {
+    try {
+      await copyFile(path.resolve(process.cwd(), e.file), e.afterPath);
+    } catch {}
+  }
+}
+
+export async function undo(): Promise<string[]> {
+  if (undoStack.length === 0) return [];
+
+  const entry = undoStack.pop()!;
+  redoStack.push(entry);
+  const restored: string[] = [];
+
+  for (const e of entry.entries) {
+    try {
+      await copyFile(e.beforePath, path.resolve(process.cwd(), e.file));
+      restored.push(e.file);
+    } catch {}
+  }
+
+  turnCounter = Math.max(1, turnCounter - 1);
+  return restored;
+}
+
+export async function redo(): Promise<string[]> {
+  if (redoStack.length === 0) return [];
+
+  const entry = redoStack.pop()!;
+  undoStack.push(entry);
+  const restored: string[] = [];
+
+  for (const e of entry.entries) {
+    try {
+      await copyFile(e.afterPath, path.resolve(process.cwd(), e.file));
+      restored.push(e.file);
+    } catch {}
+  }
+
+  turnCounter++;
+  return restored;
+}
+
+export function canUndo(): boolean {
+  return undoStack.length > 0;
+}
+
+export function canRedo(): boolean {
+  return redoStack.length > 0;
+}
+
+export function undoRedoState() {
+  return { canUndo: canUndo(), canRedo: canRedo() };
+}
+
+export async function cleanupSnapshots(): Promise<void> {
+  try {
+    await rm(snapshotsDir(sessionId), { recursive: true, force: true });
+  } catch {}
+}

package/src/session/store.ts

@@ -0,0 +1,120 @@
+import { mkdir, readFile, writeFile, readdir, rm } from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import type { ModelMessage } from "ai";
+import type { Todo } from "../tools/todowrite.ts";
+
+export interface SessionMeta {
+  id: string;
+  workspace: string;
+  startedAt: string;
+  updatedAt: string;
+  turnCount: number;
+  mode: string;
+  provider: string;
+  model: string;
+}
+
+export interface Session {
+  meta: SessionMeta;
+  messages: ModelMessage[];
+  todos?: Todo[];
+}
+
+function projectDir(): string {
+  const hash = createHash("sha256")
+    .update(process.cwd())
+    .digest("hex")
+    .slice(0, 12);
+  return path.join(
+    process.env.HOME ?? process.env.USERPROFILE ?? "/tmp",
+    ".interference",
+    hash,
+  );
+}
+
+function sessionsDir(): string {
+  return path.join(projectDir(), "sessions");
+}
+
+export function snapshotsDir(sessionId: string): string {
+  return path.join(projectDir(), "snapshots", sessionId);
+}
+
+export async function initStore(): Promise<void> {
+  await mkdir(sessionsDir(), { recursive: true });
+}
+
+export async function saveSession(session: Session): Promise<void> {
+  await initStore();
+  session.meta.updatedAt = new Date().toISOString();
+  const file = path.join(sessionsDir(), `${session.meta.id}.json`);
+  await writeFile(file, JSON.stringify(session, null, 2));
+}
+
+export async function loadSession(id: string): Promise<Session | null> {
+  const file = path.join(sessionsDir(), `${id}.json`);
+  try {
+    const raw = await readFile(file, "utf-8");
+    return JSON.parse(raw) as Session;
+  } catch {
+    return null;
+  }
+}
+
+export async function listSessions(): Promise<SessionMeta[]> {
+  try {
+    const entries = await readdir(sessionsDir());
+    const metas: SessionMeta[] = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      const session = await loadSession(entry.replace(".json", ""));
+      if (session) metas.push(session.meta);
+    }
+    return metas.sort(
+      (a, b) =>
+        new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+    );
+  } catch {
+    return [];
+  }
+}
+
+export async function latestSession(): Promise<Session | null> {
+  const metas = await listSessions();
+  if (metas.length === 0) return null;
+  return loadSession(metas[0]!.id);
+}
+
+export async function deleteSession(id: string): Promise<void> {
+  const file = path.join(sessionsDir(), `${id}.json`);
+  try { await rm(file); } catch {}
+  try { await rm(snapshotsDir(id), { recursive: true }); } catch {}
+}
+
+export async function cleanupSessions(keep: number = 10): Promise<void> {
+  const metas = await listSessions();
+  for (const meta of metas.slice(keep)) {
+    await deleteSession(meta.id);
+  }
+}
+
+export function createSession(metaOverrides?: Partial<SessionMeta>): Session {
+  const id =
+    metaOverrides?.id ??
+    `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const now = new Date().toISOString();
+  return {
+    meta: {
+      id,
+      workspace: process.cwd(),
+      startedAt: metaOverrides?.startedAt ?? now,
+      updatedAt: now,
+      turnCount: 0,
+      mode: metaOverrides?.mode ?? "plan",
+      provider: metaOverrides?.provider ?? "unknown",
+      model: metaOverrides?.model ?? "unknown",
+    },
+    messages: [],
+  };
+}

package/src/skills.ts

@@ -0,0 +1,177 @@
+import { readFile, readdir, mkdir, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+
+export const SKILLS_DIR = path.join(
+  process.env.HOME ?? process.env.USERPROFILE ?? "/tmp",
+  ".interference",
+  "skills",
+);
+
+const BUNDLED_SKILLS: Record<string, string> = {
+  "agents-setup": `---
+name: agents-setup
+description: Generate or update AGENTS.md for a project. Use when the user asks /init,
+  "setup agent", "initialize AGENTS.md", "configure project for agents", or wants to
+  bootstrap a project for AI coding agents.
+---
+
+# agents-setup — Project bootstrap for AI agents
+
+Generate an AGENTS.md file (the cross-tool standard). This file is the source of truth for any AI agent working on this project.
+
+## Structure of AGENTS.md
+
+- §1 Overview: name, description, stack, references
+- §2 Agent skills: trigger → skill mapping table
+- §3 Project-specific skills: .agents/skills/<name>/SKILL.md
+- §4 Decision log: .agents/decisions/ (on-demand only)
+- §5 Project memory: .agents/memory/ (living facts)
+- §6 Non-negotiable rules: align to requirements, propagate fixes, completeness pass
+- §7 State snapshot
+- §8 What NOT to do`,
+
+  "iterations-planner": `---
+name: iterations-planner
+description: Organize a backlog of features/fixes into local iteration folders. Use when
+  the user provides a client brief with multiple features, asks to "plan iterations",
+  "/iterations", "organize backlog", or reports a bug with "/fix", "correggi", "regressione".
+  Creates iterazioni/NN-name/ folders with task.md + plan.md.
+---
+
+# iterations-planner — Organize project backlog into iterations
+
+Transform a client brief into a structured, trackable backlog — local to the developer, not committed.
+
+## Output structure
+
+iterazioni/NN-name/task.md + plan.md (gitignored)
+fix/NN-problem/bug.md + fix.md (gitignored)
+
+## task.md: status, verbatim brief, objective, atomic tasks, files, deps, DoD
+## plan.md: decisions table, concrete steps, files touched, validation
+## Ordering: foundation first, high-impact next, cosmetic last, bugs by severity`,
+
+  "interference-tool": `---
+name: interference-tool
+description: Pattern for adding or modifying a tool in the interference agent. Use when
+  creating a new tool (read, write, edit, bash, etc.) or modifying an existing one.
+  Covers: zod schema, path containment, permission gates, output truncation, registry,
+  system prompt update, tests.
+---
+
+# Adding a tool to interference
+
+All tools live in src/tools/ and follow the same skeleton.
+
+## Skeleton
+- import { tool } from "ai"; import { z } from "zod";
+- import { resolveInWorkspace } from "./_fs.ts";
+- import { decide, requestConfirmation } from "../permissions.ts";
+- tool({ description, inputSchema: z.object({...}), execute: async (args) => {...} })
+
+## Checklist
+- Zod inputSchema with .describe() on every field
+- resolveInWorkspace() on every file path
+- Permission gate for mutating tools
+- Output truncated (OUTPUT_CAP)
+- Registered in tools/index.ts
+- System prompt updated
+- Tests in tools/__tests__/`,
+};
+
+export interface SkillInfo {
+  name: string;
+  description: string;
+}
+
+let registryCache: SkillInfo[] | null = null;
+
+export async function loadSkillRegistry(): Promise<SkillInfo[]> {
+  if (registryCache) return registryCache;
+  const list: SkillInfo[] = [];
+  try {
+    const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(SKILLS_DIR, entry.name, "SKILL.md");
+      try {
+        const content = await readFile(skillFile, "utf-8");
+        const info = parseSkillFrontmatter(content);
+        if (info) list.push(info);
+      } catch {}
+    }
+  } catch {}
+  registryCache = list;
+  return list;
+}
+
+export function getCachedRegistry(): SkillInfo[] {
+  return registryCache ?? [];
+}
+
+function parseSkillFrontmatter(content: string): SkillInfo | null {
+  const match = content.match(/^---\nname:\s*(.+)\ndescription:\s*([\s\S]*?)\n---/);
+  if (!match) return null;
+  return {
+    name: (match[1] ?? "").trim(),
+    description: (match[2] ?? "").replace(/\n\s*/g, " ").trim(),
+  };
+}
+
+export async function loadSkillBody(name: string): Promise<string | null> {
+  const skillFile = path.join(SKILLS_DIR, name, "SKILL.md");
+  try {
+    return await readFile(skillFile, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function matchSkills(userMessage: string, skills: SkillInfo[], max = 3): string[] {
+  const tokens = tokenize(userMessage);
+  if (tokens.length === 0) return [];
+
+  const scored = skills.map((s) => {
+    const descTokens = tokenize(s.description);
+    const matches = tokens.filter((t) => descTokens.includes(t));
+    return {
+      name: s.name,
+      score: matches.length,
+    };
+  });
+
+  return scored
+    .filter((s) => s.score >= 2)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, max)
+    .map((s) => s.name);
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s/_-]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+
+const STOPWORDS = new Set([
+  "the", "and", "for", "use", "when", "this", "that", "with", "from",
+  "your", "have", "has", "are", "was", "will", "can", "not", "but",
+  "all", "any", "its", "you", "how", "what", "where", "which", "who",
+  "into", "just", "also", "very", "much", "some", "than", "then",
+  "does", "more", "most", "such", "each", "over", "only", "per",
+]);
+
+export async function bootstrapSkills(): Promise<void> {
+  for (const [name, content] of Object.entries(BUNDLED_SKILLS)) {
+    const dir = path.join(SKILLS_DIR, name);
+    try { await mkdir(dir, { recursive: true }); } catch {}
+    const fp = path.join(dir, "SKILL.md");
+    try {
+      const existing = await readFile(fp, "utf-8");
+      if (existing.trim() === content.trim()) continue;
+    } catch {}
+    await writeFile(fp, content);
+  }
+}