@trevonistrevon/pi-loop 0.4.11 → 0.5.1

package/src/goal-reducer.ts

@@ -0,0 +1,280 @@
+import type {
+  GoalCriteria,
+  GoalEntry,
+  GoalProgressSnapshot,
+  GoalReducerState,
+  GoalScope,
+  GoalVerificationState,
+} from "./goal-types.js";
+
+export type GoalReducerEvent =
+  | {
+    type: "GOAL_CREATED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: {
+      title: string;
+      description: string;
+      scope: GoalScope;
+      criteria: GoalCriteria;
+      metadata?: Record<string, unknown>;
+    };
+  }
+  | {
+    type: "GOAL_ACTIVATED" | "GOAL_VERIFICATION_STARTED" | "GOAL_UNBLOCKED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: { id: string };
+  }
+  | {
+    type: "GOAL_PROGRESS_RECORDED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: { id: string; progress: GoalProgressSnapshot };
+  }
+  | {
+    type: "GOAL_VERIFICATION_PASSED" | "GOAL_VERIFICATION_FAILED" | "GOAL_BLOCKED" | "GOAL_FAILED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: { id: string; reason: string; progress?: GoalProgressSnapshot };
+  }
+  | {
+    type: "GOAL_SATISFIED" | "GOAL_ARCHIVED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: { id: string; reason?: string };
+  }
+  | {
+    type: "GOAL_UPDATED";
+    at: number;
+    source: "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+    entityType?: "goal";
+    entityId?: string;
+    payload: {
+      id: string;
+      title?: string;
+      description?: string;
+      scope?: GoalScope;
+      criteria?: GoalCriteria;
+      metadata?: Record<string, unknown>;
+    };
+  };
+
+export type GoalReducerEffect =
+  | {
+    type: "PERSIST_GOAL";
+    entityType: "goal";
+    entityId: string;
+    payload: { goal: GoalEntry };
+  }
+  | {
+    type: "REQUEST_GOAL_VERIFICATION";
+    entityType: "goal";
+    entityId: string;
+    payload: { id: string };
+  };
+
+export interface GoalReduceResult {
+  state: GoalReducerState;
+  effects: GoalReducerEffect[];
+}
+
+function cloneState(state: GoalReducerState): GoalReducerState {
+  return {
+    nextId: state.nextId,
+    goalsById: { ...state.goalsById },
+  };
+}
+
+function emptyProgress(): GoalProgressSnapshot {
+  return {
+    totalTasks: 0,
+    pendingTasks: 0,
+    inProgressTasks: 0,
+    completedTasks: 0,
+    activeLoops: 0,
+    pausedLoops: 0,
+    runningMonitors: 0,
+    completedMonitors: 0,
+    erroredMonitors: 0,
+    stoppedMonitors: 0,
+  };
+}
+
+function emptyVerification(): GoalVerificationState {
+  return {
+    attempts: 0,
+    passes: 0,
+    failures: 0,
+  };
+}
+
+function persist(goal: GoalEntry): GoalReducerEffect {
+  return {
+    type: "PERSIST_GOAL",
+    entityType: "goal",
+    entityId: goal.id,
+    payload: { goal },
+  };
+}
+
+function isTerminal(goal: GoalEntry): boolean {
+  return goal.status === "satisfied" || goal.status === "failed" || goal.status === "archived";
+}
+
+export function reduceGoalState(state: GoalReducerState, event: GoalReducerEvent): GoalReduceResult {
+  if (event.type === "GOAL_CREATED") {
+    const next = cloneState(state);
+    const id = String(next.nextId++);
+    const goal: GoalEntry = {
+      id,
+      title: event.payload.title,
+      description: event.payload.description,
+      status: "pending",
+      verificationStatus: "unknown",
+      createdAt: event.at,
+      updatedAt: event.at,
+      scope: event.payload.scope,
+      criteria: event.payload.criteria,
+      progress: emptyProgress(),
+      verification: emptyVerification(),
+      metadata: event.payload.metadata,
+    };
+    next.goalsById[id] = goal;
+    return {
+      state: next,
+      effects: [persist(goal)],
+    };
+  }
+
+  const id = event.payload.id;
+  const current = state.goalsById[id];
+  if (!current) return { state, effects: [] };
+  if (isTerminal(current) && event.type !== "GOAL_ARCHIVED") return { state, effects: [] };
+
+  const next = cloneState(state);
+  const goal: GoalEntry = {
+    ...current,
+    progress: { ...current.progress },
+    verification: { ...current.verification },
+  };
+
+  let extraEffects: GoalReducerEffect[] = [];
+
+  if (event.type === "GOAL_ACTIVATED") {
+    goal.status = "active";
+    goal.activatedAt ??= event.at;
+    goal.updatedAt = event.at;
+    extraEffects = [{
+      type: "REQUEST_GOAL_VERIFICATION",
+      entityType: "goal",
+      entityId: id,
+      payload: { id },
+    }];
+  }
+
+  if (event.type === "GOAL_PROGRESS_RECORDED") {
+    goal.progress = event.payload.progress;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_VERIFICATION_STARTED") {
+    goal.verificationStatus = "checking";
+    goal.verification.attempts += 1;
+    goal.verification.lastCheckedAt = event.at;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_VERIFICATION_PASSED") {
+    if (event.payload.progress) goal.progress = event.payload.progress;
+    goal.status = "satisfied";
+    goal.verificationStatus = "verified";
+    goal.verification.passes += 1;
+    goal.verification.lastPassedAt = event.at;
+    goal.verification.lastCheckedAt = event.at;
+    goal.verification.lastReason = event.payload.reason;
+    goal.resolvedAt = event.at;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_VERIFICATION_FAILED") {
+    if (event.payload.progress) goal.progress = event.payload.progress;
+    goal.verificationStatus = "unverified";
+    goal.verification.failures += 1;
+    goal.verification.lastFailedAt = event.at;
+    goal.verification.lastCheckedAt = event.at;
+    goal.verification.lastReason = event.payload.reason;
+    if (goal.status === "pending") goal.status = "active";
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_BLOCKED") {
+    if (event.payload.progress) goal.progress = event.payload.progress;
+    goal.status = "blocked";
+    goal.verificationStatus = "inconclusive";
+    goal.verification.failures += 1;
+    goal.verification.lastFailedAt = event.at;
+    goal.verification.lastCheckedAt = event.at;
+    goal.verification.lastReason = event.payload.reason;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_UNBLOCKED") {
+    goal.status = "active";
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_SATISFIED") {
+    goal.status = "satisfied";
+    goal.verificationStatus = "verified";
+    goal.verification.lastReason = event.payload.reason ?? goal.verification.lastReason;
+    goal.resolvedAt = event.at;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_FAILED") {
+    if (event.payload.progress) goal.progress = event.payload.progress;
+    goal.status = "failed";
+    goal.verificationStatus = "unverified";
+    goal.verification.failures += 1;
+    goal.verification.lastFailedAt = event.at;
+    goal.verification.lastCheckedAt = event.at;
+    goal.verification.lastReason = event.payload.reason;
+    goal.resolvedAt = event.at;
+    goal.updatedAt = event.at;
+  }
+
+  if (event.type === "GOAL_ARCHIVED") {
+    goal.status = "archived";
+    goal.resolvedAt = event.at;
+    goal.updatedAt = event.at;
+    if (event.payload.reason !== undefined) {
+      goal.verification.lastReason = event.payload.reason;
+    }
+  }
+
+  if (event.type === "GOAL_UPDATED") {
+    if (event.payload.title !== undefined) goal.title = event.payload.title;
+    if (event.payload.description !== undefined) goal.description = event.payload.description;
+    if (event.payload.scope !== undefined) goal.scope = event.payload.scope;
+    if (event.payload.criteria !== undefined) goal.criteria = event.payload.criteria;
+    if (event.payload.metadata !== undefined) goal.metadata = event.payload.metadata;
+    goal.updatedAt = event.at;
+  }
+
+  next.goalsById[id] = goal;
+  return {
+    state: next,
+    effects: [persist(goal), ...extraEffects],
+  };
+}

package/src/goal-store.ts

@@ -0,0 +1,315 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { type GoalReducerEvent, reduceGoalState } from "./goal-reducer.js";
+import type {
+  GoalCriteria,
+  GoalEntry,
+  GoalProgressSnapshot,
+  GoalReducerState,
+  GoalScope,
+  GoalStoreData,
+} from "./goal-types.js";
+
+const GOALS_DIR = join(homedir(), ".pi", "goals");
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+const MAX_GOALS = 200;
+
+function acquireLock(lockPath: string): void {
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+      return;
+    } catch (e: any) {
+      if (e.code === "EEXIST") {
+        try {
+          const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+          if (!pid || !isProcessRunning(pid)) {
+            try { unlinkSync(lockPath); } catch { /* ignore */ }
+            continue;
+          }
+        } catch { /* ignore read errors */ }
+        const start = Date.now();
+        while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new Error(`Failed to acquire lock: ${lockPath}`);
+}
+
+function releaseLock(lockPath: string): void {
+  try { unlinkSync(lockPath); } catch { /* ignore */ }
+}
+
+function isProcessRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export class GoalStore {
+  private filePath: string | undefined;
+  private lockPath: string | undefined;
+
+  private nextId = 1;
+  private goals = new Map<string, GoalEntry>();
+
+  constructor(listIdOrPath?: string) {
+    if (!listIdOrPath) return;
+    const isAbsPath = isAbsolute(listIdOrPath);
+    const filePath = isAbsPath ? listIdOrPath : join(GOALS_DIR, `${listIdOrPath}.json`);
+    mkdirSync(dirname(filePath), { recursive: true });
+    this.filePath = filePath;
+    this.lockPath = filePath + ".lock";
+    this.load();
+  }
+
+  private load(): void {
+    if (!this.filePath) return;
+    if (!existsSync(this.filePath)) return;
+    try {
+      const data: GoalStoreData = JSON.parse(readFileSync(this.filePath, "utf-8"));
+      this.nextId = data.nextId;
+      this.goals.clear();
+      for (const goal of data.goals) {
+        this.goals.set(goal.id, goal);
+      }
+    } catch { /* corrupt file — start fresh */ }
+  }
+
+  private save(): void {
+    if (!this.filePath) return;
+    const data: GoalStoreData = {
+      nextId: this.nextId,
+      goals: Array.from(this.goals.values()),
+    };
+    const tmpPath = this.filePath + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+    renameSync(tmpPath, this.filePath);
+  }
+
+  private withLock<T>(fn: () => T): T {
+    if (!this.lockPath) return fn();
+    acquireLock(this.lockPath);
+    try {
+      this.load();
+      const result = fn();
+      this.save();
+      return result;
+    } finally {
+      releaseLock(this.lockPath);
+    }
+  }
+
+  private toReducerState(): GoalReducerState {
+    return {
+      nextId: this.nextId,
+      goalsById: Object.fromEntries(this.goals.entries()),
+    };
+  }
+
+  private applyReducerEvent(event: GoalReducerEvent): void {
+    const result = reduceGoalState(this.toReducerState(), event);
+    this.nextId = result.state.nextId;
+    this.goals = new Map(Object.entries(result.state.goalsById));
+  }
+
+  create(
+    title: string,
+    description: string,
+    scope: GoalScope,
+    criteria: GoalCriteria,
+    metadata?: Record<string, unknown>,
+  ): GoalEntry {
+    return this.withLock(() => {
+      if (this.goals.size >= MAX_GOALS) {
+        throw new Error(`Maximum of ${MAX_GOALS} goals reached. Archive some before creating new ones.`);
+      }
+      this.applyReducerEvent({
+        type: "GOAL_CREATED",
+        at: Date.now(),
+        source: "tool",
+        entityType: "goal",
+        payload: {
+          title,
+          description,
+          scope,
+          criteria,
+          metadata,
+        },
+      });
+      return this.goals.get(String(this.nextId - 1))!;
+    });
+  }
+
+  get(id: string): GoalEntry | undefined {
+    if (this.filePath) this.load();
+    return this.goals.get(id);
+  }
+
+  list(): GoalEntry[] {
+    if (this.filePath) this.load();
+    return Array.from(this.goals.values()).sort((a, b) => Number(a.id) - Number(b.id));
+  }
+
+  activate(id: string): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_ACTIVATED",
+        at: Date.now(),
+        source: "tool",
+        entityType: "goal",
+        entityId: id,
+        payload: { id },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  recordProgress(id: string, progress: GoalProgressSnapshot): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_PROGRESS_RECORDED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id, progress },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  markVerificationStarted(id: string): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_VERIFICATION_STARTED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  markVerified(id: string, reason: string, progress?: GoalProgressSnapshot): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_VERIFICATION_PASSED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id, reason, progress },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  markFailed(id: string, reason: string, progress?: GoalProgressSnapshot): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_FAILED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id, reason, progress },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  markBlocked(id: string, reason: string, progress?: GoalProgressSnapshot): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_BLOCKED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id, reason, progress },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  unblock(id: string): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_UNBLOCKED",
+        at: Date.now(),
+        source: "coordinator",
+        entityType: "goal",
+        entityId: id,
+        payload: { id },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  updateDetails(
+    id: string,
+    fields: {
+      title?: string;
+      description?: string;
+      scope?: GoalScope;
+      criteria?: GoalCriteria;
+      metadata?: Record<string, unknown>;
+    },
+  ): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      if (
+        fields.title === undefined
+        && fields.description === undefined
+        && fields.scope === undefined
+        && fields.criteria === undefined
+        && fields.metadata === undefined
+      ) {
+        return this.goals.get(id);
+      }
+      this.applyReducerEvent({
+        type: "GOAL_UPDATED",
+        at: Date.now(),
+        source: "tool",
+        entityType: "goal",
+        entityId: id,
+        payload: {
+          id,
+          title: fields.title,
+          description: fields.description,
+          scope: fields.scope,
+          criteria: fields.criteria,
+          metadata: fields.metadata,
+        },
+      });
+      return this.goals.get(id);
+    });
+  }
+
+  archive(id: string, reason?: string): GoalEntry | undefined {
+    return this.withLock(() => {
+      if (!this.goals.has(id)) return undefined;
+      this.applyReducerEvent({
+        type: "GOAL_ARCHIVED",
+        at: Date.now(),
+        source: "tool",
+        entityType: "goal",
+        entityId: id,
+        payload: { id, reason },
+      });
+      return this.goals.get(id);
+    });
+  }
+}

package/src/goal-types.ts

@@ -0,0 +1,104 @@
+export type GoalStatus =
+  | "pending"
+  | "active"
+  | "satisfied"
+  | "blocked"
+  | "failed"
+  | "archived";
+
+export type GoalVerificationStatus =
+  | "unknown"
+  | "checking"
+  | "verified"
+  | "unverified"
+  | "inconclusive";
+
+export interface GoalScope {
+  taskIds?: string[];
+  loopIds?: string[];
+  monitorIds?: string[];
+  tags?: string[];
+  subjectPrefixes?: string[];
+  includeFutureMatchingTasks?: boolean;
+  includeFutureMatchingLoops?: boolean;
+  includeFutureMatchingMonitors?: boolean;
+}
+
+export interface GoalSuccessCriteria {
+  minCompletedTasks?: number;
+  requiredTaskIds?: string[];
+  requiredMonitorIdsCompleted?: string[];
+  requiredLoopIdsPresent?: string[];
+  requireNoPendingTasksInScope?: boolean;
+  requireLatestVerificationPass?: boolean;
+}
+
+export interface GoalFailureCriteria {
+  anyMonitorIdsErrored?: string[];
+  maxVerificationFailures?: number;
+  failIfTaskIdsDeleted?: string[];
+}
+
+export interface GoalBlockedCriteria {
+  blockedIfAllTasksCompletedButVerificationFails?: boolean;
+  blockedIfNoScopedProgressSinceMs?: number;
+  blockedIfRequiredLoopMissing?: boolean;
+}
+
+export interface GoalCriteria {
+  success: GoalSuccessCriteria;
+  failure?: GoalFailureCriteria;
+  blocked?: GoalBlockedCriteria;
+}
+
+export interface GoalProgressSnapshot {
+  totalTasks: number;
+  pendingTasks: number;
+  inProgressTasks: number;
+  completedTasks: number;
+  activeLoops: number;
+  pausedLoops: number;
+  runningMonitors: number;
+  completedMonitors: number;
+  erroredMonitors: number;
+  stoppedMonitors: number;
+  lastProgressAt?: number;
+}
+
+export interface GoalVerificationState {
+  attempts: number;
+  passes: number;
+  failures: number;
+  lastCheckedAt?: number;
+  lastPassedAt?: number;
+  lastFailedAt?: number;
+  lastReason?: string;
+  nextCheckAfter?: number;
+}
+
+export interface GoalEntry {
+  id: string;
+  title: string;
+  description: string;
+  status: GoalStatus;
+  verificationStatus: GoalVerificationStatus;
+  createdAt: number;
+  updatedAt: number;
+  activatedAt?: number;
+  resolvedAt?: number;
+  scope: GoalScope;
+  criteria: GoalCriteria;
+  progress: GoalProgressSnapshot;
+  verification: GoalVerificationState;
+  metadata?: Record<string, unknown>;
+}
+
+export interface GoalReducerState {
+  nextId: number;
+  goalsById: Record<string, GoalEntry>;
+}
+
+export interface GoalStoreData {
+  nextId: number;
+  goals: GoalEntry[];
+}