pi-anchor 0.2.4 → 0.4.0

package/src/decay.ts

@@ -1,125 +0,0 @@
-import type { Anchor, AnchorStatus } from './types.ts';
-import type { AnchorStore } from './store.ts';
-import fs from 'node:fs';
-
-const MS_PER_DAY = 86_400_000;
-
-export interface DecayEvaluation {
-  currentStatus: AnchorStatus;
-  nextStatus: AnchorStatus;
-  daysUntouched: number;
-  remainingActiveDays: number;
-  remainingSleepDays: number;
-}
-
-/**
- * Calculate precise decay status based on elapsed time since last touch
- */
-export function evaluateAnchorDecay(anchor: Anchor, now: number = Date.now()): DecayEvaluation {
-  if (anchor.status === 'settled' || (anchor.status as string) === 'graveyard') {
-    return {
-      currentStatus: anchor.status,
-      nextStatus: anchor.status,
-      daysUntouched: 0,
-      remainingActiveDays: 0,
-      remainingSleepDays: 0
-    };
-  }
-
-  const elapsedMs = Math.max(0, now - anchor.lastTouchedAt);
-  const daysUntouched = elapsedMs / MS_PER_DAY;
-
-  const activeDays = anchor.decay.activeDays;
-  const graveyardDays = anchor.decay.graveyardDays;
-
-  let nextStatus: AnchorStatus = anchor.status;
-
-  if (daysUntouched <= activeDays) {
-    nextStatus = 'active';
-  } else if (daysUntouched <= graveyardDays) {
-    nextStatus = 'sleeping';
-  } else {
-    nextStatus = 'graveyard';
-  }
-
-  return {
-    currentStatus: anchor.status,
-    nextStatus,
-    daysUntouched: Math.round(daysUntouched * 10) / 10,
-    remainingActiveDays: Math.max(0, Math.round((activeDays - daysUntouched) * 10) / 10),
-    remainingSleepDays: Math.max(0, Math.round((graveyardDays - daysUntouched) * 10) / 10)
-  };
-}
-
-export interface SweepResult {
-  transitionedToSleeping: string[];
-  wokenToActive: string[];
-  evictedToGraveyard: string[];
-}
-
-/**
- * Run decay sweep across store: transitions statuses and evicts expired anchors
- */
-export function sweepStore(store: AnchorStore, now: number = Date.now()): SweepResult {
-  return store.withLock(() => {
-    const state = store.loadState();
-    const result: SweepResult = {
-      transitionedToSleeping: [],
-      wokenToActive: [],
-      evictedToGraveyard: []
-    };
-
-    const toEvict: Anchor[] = [];
-    let stateModified = false;
-
-    for (const anchor of state.anchors) {
-      const evalResult = evaluateAnchorDecay(anchor, now);
-
-      if (evalResult.nextStatus === 'graveyard') {
-        toEvict.push(anchor);
-      } else if (evalResult.nextStatus !== anchor.status) {
-        if (evalResult.nextStatus === 'sleeping' && anchor.status === 'active') {
-          anchor.status = 'sleeping';
-          anchor.updatedAt = now;
-          result.transitionedToSleeping.push(anchor.id);
-          stateModified = true;
-        } else if (evalResult.nextStatus === 'active' && anchor.status === 'sleeping') {
-          anchor.status = 'active';
-          anchor.updatedAt = now;
-          result.wokenToActive.push(anchor.id);
-          stateModified = true;
-        }
-      }
-    }
-
-    // Single-pass batch eviction and state save
-    if (toEvict.length > 0) {
-      const evictIds = new Set(toEvict.map(e => e.id));
-      state.anchors = state.anchors.filter(a => !evictIds.has(a.id));
-      stateModified = true;
-
-      const graveyardLines = toEvict.map(exp => {
-        const rec = {
-          ...exp,
-          status: 'graveyard',
-          updatedAt: now,
-          evictedAt: now,
-          evictionReason: `Exceeded decay threshold (${exp.decay.graveyardDays} days untouched)`
-        };
-        return JSON.stringify(rec);
-      }).join('\n') + '\n';
-
-      fs.appendFileSync(store.graveyardPath, graveyardLines, 'utf-8');
-      for (const exp of toEvict) {
-        result.evictedToGraveyard.push(exp.id);
-      }
-    }
-
-    state.lastSweepAt = now;
-    if (stateModified) {
-      store.saveState(state);
-    }
-
-    return result;
-  });
-}

package/src/matcher.ts

@@ -1,151 +0,0 @@
-import path from 'node:path';
-import type { Anchor, TouchMatchResult } from './types.ts';
-
-/**
- * Convert simple glob pattern (e.g. *.ts, src/**\/*.ts, src/auth/*.ts) to RegExp
- */
-export function globToRegExp(pattern: string): RegExp {
-  const collapsed = pattern
-    .slice(0, 512)
-    .replace(/\/+(\*\*\/+)+/g, '/**/')
-    .replace(/\*{3,}/g, '**');
-  const escaped = collapsed
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    .replace(/\/\*\*\//g, '___GLOB_DIR_SLASH___')
-    .replace(/\*\*/g, '___GLOB_STAR_STAR___')
-    .replace(/\*/g, '[^/]*')
-    .replace(/___GLOB_DIR_SLASH___/g, '(?:/|/(?:[^/]+/)+)')
-    .replace(/___GLOB_STAR_STAR___/g, '.*');
-  return new RegExp(`^${escaped}$`);
-}
-
-/**
- * Normalize path separators to POSIX forward slashes and optionally relative to baseCwd
- */
-export function normalizePath(filePath: string, baseCwd?: string): string {
-  if (typeof filePath !== 'string') return '';
-  let norm = filePath.trim().replace(/\\/g, '/').replace(/^\.\//, '');
-  if (baseCwd && (path.isAbsolute(filePath) || norm.startsWith('/') || /^[a-zA-Z]:\//.test(norm))) {
-    const normBase = baseCwd.trim().replace(/\\/g, '/').replace(/\/+$/, '');
-    const lowerNorm = norm.toLowerCase();
-    const lowerBase = normBase.toLowerCase();
-    if (lowerNorm === lowerBase) {
-      norm = '';
-    } else if (lowerNorm.startsWith(lowerBase + '/')) {
-      norm = norm.slice(normBase.length + 1).replace(/^\/+/, '');
-    }
-  }
-  return norm;
-}
-
-/**
- * Compare two workspace CWDs safely (case-insensitive on Windows, supports subdirectory scoping)
- */
-export function isSameOrSubPath(anchorCwd?: string, targetCwd?: string): boolean {
-  if (!anchorCwd || !targetCwd) return false;
-  const normA = anchorCwd.trim().replace(/\\/g, '/').replace(/\/+$/, '');
-  const normT = targetCwd.trim().replace(/\\/g, '/').replace(/\/+$/, '');
-  const isWinStyle = process.platform === 'win32' || /^[a-zA-Z]:\//.test(normA) || /^[a-zA-Z]:\//.test(normT);
-  const cmpA = isWinStyle ? normA.toLowerCase() : normA;
-  const cmpT = isWinStyle ? normT.toLowerCase() : normT;
-  return cmpA === cmpT || cmpT.startsWith(cmpA + '/') || cmpA.startsWith(cmpT + '/');
-}
-
-/**
- * Match touched files against an anchor's registered physical patterns
- * Only anchors with explicit files/globs/prefixes are matched against file touches.
- * Anchors with files: [] (pure mental notes or macro tasks) NEVER trigger on file operations.
- */
-export function matchAnchorAgainstTouchedFiles(
-  anchor: Anchor,
-  touchedFiles: string[]
-): TouchMatchResult | null {
-  if (!anchor.files || anchor.files.length === 0) return null;
-
-  const normTouched = touchedFiles.map(f => normalizePath(f, anchor.cwd)).filter(Boolean);
-  if (normTouched.length === 0) return null;
-
-  const matchedExact: string[] = [];
-  const matchedPrefix: string[] = [];
-
-  for (const touched of normTouched) {
-    // Exact match or configured glob match
-    for (const pattern of anchor.files) {
-      const normPattern = normalizePath(pattern, anchor.cwd);
-      if (normPattern === touched) {
-        matchedExact.push(touched);
-        break;
-      }
-
-      // Glob pattern matching
-      if (normPattern.includes('*')) {
-        const regex = globToRegExp(normPattern);
-        if (regex.test(touched)) {
-          matchedExact.push(touched);
-          break;
-        }
-      }
-
-      // Directory prefix match, e.g. "src/auth/" matches "src/auth/login.ts"
-      const dirPrefix = normPattern.endsWith('/') ? normPattern : normPattern + '/';
-      if (touched.startsWith(dirPrefix)) {
-        matchedPrefix.push(touched);
-        break;
-      }
-    }
-  }
-
-  if (matchedExact.length > 0) {
-    return {
-      anchor,
-      score: 1.0,
-      matchedFiles: Array.from(new Set(matchedExact)),
-      reason: 'exact-file'
-    };
-  }
-
-  if (matchedPrefix.length > 0) {
-    return {
-      anchor,
-      score: 0.85,
-      matchedFiles: Array.from(new Set(matchedPrefix)),
-      reason: 'dir-prefix'
-    };
-  }
-
-  return null;
-}
-
-/**
- * Filter and sort anchors that match a set of touched files
- * Prioritizes high confidence (exact > prefix > keyword) and priority (P0 > P1 > P2).
- */
-export function findMatchedAnchors(
-  anchors: Anchor[],
-  touchedFiles: string[]
-): TouchMatchResult[] {
-  const priorityWeight: Record<string, number> = { p0: 3, p1: 2, p2: 1 };
-  const results: TouchMatchResult[] = [];
-
-  for (const anchor of anchors) {
-    const match = matchAnchorAgainstTouchedFiles(anchor, touchedFiles);
-    if (match) {
-      results.push(match);
-    }
-  }
-
-  return results.sort((a, b) => {
-    // 1. Match score confidence desc
-    if (b.score !== a.score) {
-      return b.score - a.score;
-    }
-    // 2. Anchor priority desc
-    const weightA = priorityWeight[a.anchor.priority] || 0;
-    const weightB = priorityWeight[b.anchor.priority] || 0;
-    if (weightB !== weightA) {
-      return weightB - weightA;
-    }
-    // 3. Recency desc
-    return b.anchor.lastTouchedAt - a.anchor.lastTouchedAt;
-  });
-}

package/src/observer.ts

@@ -1,141 +0,0 @@
-import { normalizePath } from './matcher.ts';
-import type { Anchor } from './types.ts';
-
-const MUTATION_TOOLS = new Set(['edit', 'write', 'patch', 'apply_diff', 'create_file', 'modify']);
-
-export class SessionTouchObserver {
-  private touchedFiles: Set<string> = new Set();
-  private modifiedFiles: Set<string> = new Set();
-  private inspectedFiles: Set<string> = new Set();
-  private committed: boolean = false;
-  private commitMessages: string[] = [];
-
-  public clear(): void {
-    this.touchedFiles.clear();
-    this.modifiedFiles.clear();
-    this.inspectedFiles.clear();
-    this.committed = false;
-    this.commitMessages = [];
-  }
-
-  /**
-   * Observe and record a tool call invocation, separating inspection from mutation
-   */
-  public recordToolCall(toolName: string, input: Record<string, unknown>): void {
-    if (!input || typeof input !== 'object') return;
-    const lowerTool = (toolName || '').toLowerCase();
-    const isMutation = MUTATION_TOOLS.has(lowerTool);
-
-    const paths: string[] = [];
-    const pathField = (input as any).path || (input as any).filePath || (input as any).file;
-    if (typeof pathField === 'string') {
-      paths.push(normalizePath(pathField));
-    }
-
-    if (Array.isArray((input as any).paths)) {
-      for (const p of (input as any).paths) {
-        if (typeof p === 'string') {
-          paths.push(normalizePath(p));
-        }
-      }
-    }
-
-    for (const p of paths) {
-      this.touchedFiles.add(p);
-      if (isMutation) {
-        this.modifiedFiles.add(p);
-      } else {
-        this.inspectedFiles.add(p);
-      }
-    }
-
-    // Shell executions that might involve git commits
-    if (lowerTool === 'bash' || lowerTool === 'powershell') {
-      const cmd = String((input as any).command || '');
-      if (cmd.includes('git commit')) {
-        this.committed = true;
-        const msgMatch = cmd.match(/-m\s+["']([^"']+)["']/);
-        if (msgMatch && msgMatch[1]) {
-          this.commitMessages.push(msgMatch[1]);
-        }
-      }
-    }
-  }
-
-  /**
-   * Add a file path manually (e.g. from git status diff)
-   */
-  public addTouchedFile(filePath: string, isModified = true): void {
-    if (filePath) {
-      const norm = normalizePath(filePath);
-      this.touchedFiles.add(norm);
-      if (isModified) {
-        this.modifiedFiles.add(norm);
-      } else {
-        this.inspectedFiles.add(norm);
-      }
-    }
-  }
-
-  public getModifiedFiles(): string[] {
-    return Array.from(this.modifiedFiles);
-  }
-
-  public getInspectedFiles(): string[] {
-    return Array.from(this.inspectedFiles);
-  }
-
-  public getTouchedFiles(): string[] {
-    return Array.from(this.touchedFiles);
-  }
-
-  public hasCommitted(): boolean {
-    return this.committed;
-  }
-
-  public getCommitMessages(): string[] {
-    return [...this.commitMessages];
-  }
-
-  /**
-   * Check if any commit message explicitly references or resolves an anchor
-   */
-  public matchesCommit(anchor: Anchor): { matched: boolean; message?: string } {
-    const idLower = anchor.id.toLowerCase();
-    const title = anchor.title.toLowerCase();
-
-    // Universal tokenization for CJK & Latin words
-    let titleTokens: string[] = [];
-    if (typeof Intl !== 'undefined' && (Intl as any).Segmenter) {
-      try {
-        const segmenter = new (Intl as any).Segmenter('und', { granularity: 'word' });
-        titleTokens = Array.from(segmenter.segment(title))
-          .filter((s: any) => s.isWordLike)
-          .map((s: any) => s.segment.trim().toLowerCase())
-          .filter((t: string) => t.length >= 2);
-      } catch {
-        titleTokens = title.split(/[\s,._\-\/]+/).filter(t => t.length >= 2);
-      }
-    } else {
-      titleTokens = title.split(/[\s,._\-\/]+/).filter(t => t.length >= 2);
-    }
-
-    for (const msg of this.commitMessages) {
-      const msgLower = msg.toLowerCase();
-      // 1. Explicit ID reference, e.g. "fix: auth leak (#anc-1)" or "anc-1"
-      if (msgLower.includes(idLower)) {
-        return { matched: true, message: msg };
-      }
-
-      // 2. High-confidence token intersection
-      if (titleTokens.length > 0) {
-        const matchingCount = titleTokens.filter(tok => msgLower.includes(tok)).length;
-        if (matchingCount >= Math.min(2, titleTokens.length)) {
-          return { matched: true, message: msg };
-        }
-      }
-    }
-
-    return { matched: false };
-  }
-}

package/src/protocol.ts

@@ -1,95 +0,0 @@
-import type { AnchorStore } from './store.ts';
-import type { Anchor } from './types.ts';
-import { renderColdStartAnchorsContext, makeSafeTaskAnnotation } from './context_injector.ts';
-import { findMatchedAnchors, normalizePath } from './matcher.ts';
-import { sweepStore } from './decay.ts';
-import { SessionTouchObserver } from './observer.ts';
-
-/**
- * Universal Agent Adapter Interface.
- * Any AI coding harness (Pi, Claude Code, Cursor, Aider, custom MCP server) implements this thin layer.
- */
-export interface AgentAdapter {
-  readonly name: string;
-  getCwd(): string;
-  notify?(message: string, level: 'info' | 'warn' | 'error'): void;
-}
-
-/**
- * Anchor protocol engine for cross-session task management.
- * Decoupled, harness-agnostic core managing state, decay, JIT annotations, and settlement.
- */
-export class AnchorProtocol {
-  public readonly store: AnchorStore;
-  public readonly observer: SessionTouchObserver;
-  private readonly annotatedThisSession = new Set<string>();
-
-  constructor(store: AnchorStore) {
-    this.store = store;
-    this.observer = new SessionTouchObserver();
-  }
-
-  /**
-   * Run session initialization lifecycle: sweeps stale anchors and resets session state
-   */
-  public handleSessionStart(now: number = Date.now()): { sleepingCount: number } {
-    this.observer.clear();
-    this.annotatedThisSession.clear();
-    const sweep = sweepStore(this.store, now);
-    return { sleepingCount: sweep.transitionedToSleeping.length };
-  }
-
-  /**
-   * Handle turn lifecycle: injects cold-start prompt on turn 1, returns null (0 tokens) on turn 2+
-   */
-  public handleBeforeTurn(turnCount: number, cwd: string, now: number = Date.now()): string | null {
-    if (turnCount <= 1) {
-      return renderColdStartAnchorsContext(this.store, cwd, now) || null;
-    }
-    return null;
-  }
-
-  /**
-   * Handle tool execution result: detects touched paths, refreshes mutation touch timers,
-   * and returns safe language-specific JIT annotation (or null if syntax incompatible/already annotated).
-   */
-  public handleToolResult(input: {
-    toolName: string;
-    filePath?: string;
-    isError?: boolean;
-    isMutation?: boolean;
-    cwd: string;
-  }): { annotation: string | null; matchedAnchors: Anchor[] } {
-    if (!input.isError) {
-      this.observer.recordToolCall(input.toolName, input.filePath ? { path: input.filePath } : {});
-    }
-
-    if (!input.filePath) {
-      return { annotation: null, matchedAnchors: [] };
-    }
-
-    const touchedPath = normalizePath(input.filePath);
-    const anchors = this.store.list({ cwd: input.cwd }).filter(a => a.status === 'active' || a.status === 'sleeping');
-    const matches = findMatchedAnchors(anchors, [touchedPath]);
-
-    if (matches.length === 0) {
-      return { annotation: null, matchedAnchors: [] };
-    }
-
-    // Physical mutations refresh decay timer and wake sleeping anchors
-    if (input.isMutation && !input.isError) {
-      for (const m of matches) {
-        this.store.touch(m.anchor.id);
-      }
-    }
-
-    const a = matches[0].anchor;
-    if (!this.annotatedThisSession.has(a.id)) {
-      this.annotatedThisSession.add(a.id);
-      const annotation = makeSafeTaskAnnotation(touchedPath, a);
-      return { annotation, matchedAnchors: matches.map(m => m.anchor) };
-    }
-
-    return { annotation: null, matchedAnchors: matches.map(m => m.anchor) };
-  }
-}

package/src/settlement.ts

@@ -1,74 +0,0 @@
-import type { AnchorStore } from './store.ts';
-import { findMatchedAnchors } from './matcher.ts';
-import type { Anchor, SettlementProposal } from './types.ts';
-import { execSync } from 'node:child_process';
-
-/**
- * Execute physical verification test command for an anchor
- */
-export function runPhysicalVerification(anchor: Anchor, cwd: string): { success: boolean; output: string } {
-  if (!anchor.verifyCommand?.trim()) {
-    return { success: false, output: 'No verification command specified' };
-  }
-
-  const targetCwd = anchor.cwd || cwd;
-  try {
-    const stdout = execSync(anchor.verifyCommand, {
-      cwd: targetCwd,
-      encoding: 'utf-8',
-      timeout: 8000,
-      maxBuffer: 4 * 1024 * 1024,
-      stdio: ['ignore', 'pipe', 'pipe']
-    });
-    return { success: true, output: stdout.trim() };
-  } catch (err: any) {
-    return { success: false, output: String(err.stderr || err.stdout || err.message).trim() };
-  }
-}
-
-/**
- * Generate settlement candidates based on files touched during the session
- */
-export function generateSettlementProposals(
-  store: AnchorStore,
-  touchedFiles: string[],
-  cwd?: string
-): SettlementProposal[] {
-  // Only match active/sleeping anchors belonging to current workspace
-  const activeAndSleeping = store.list({ cwd }).filter(a => a.status === 'active' || a.status === 'sleeping');
-  const matches = findMatchedAnchors(activeAndSleeping, touchedFiles);
-
-  const proposals: SettlementProposal[] = [];
-
-  for (const match of matches) {
-    const fileList = match.matchedFiles.slice(0, 3).join(', ');
-    const moreSuffix = match.matchedFiles.length > 3 ? ` 等 ${match.matchedFiles.length} 个文件` : '';
-
-    proposals.push({
-      anchor: match.anchor,
-      matchedFiles: match.matchedFiles,
-      reason: `本次会话修改了 ${fileList}${moreSuffix}`,
-      recommendedAction: match.score >= 0.85 ? 'settle' : 'defer'
-    });
-  }
-
-  return proposals;
-}
-
-/**
- * Format settlement proposal into terminal-ready card
- */
-export function formatSettlementCard(proposal: SettlementProposal): string {
-  const a = proposal.anchor;
-  const tagStr = a.tags.length > 0 ? ` [${a.tags.join(', ')}]` : '';
-  const fileStr = proposal.matchedFiles.slice(0, 2).join(', ');
-
-  return [
-    `───────────────────────────────────────────────────────────────────`,
-    `⚓ 关门结案提议 | Anchor Settlement`,
-    `   任务 #${a.id}: ${a.title}${tagStr} (${a.priority.toUpperCase()})`,
-    `   证据触发: 修改了 ${fileStr}`,
-    `   [Enter 确认结案并归档]  /  [Tab 暂未完成，继续挂起]`,
-    `───────────────────────────────────────────────────────────────────`
-  ].join('\n');
-}