@trevonistrevon/pi-loop 0.4.10 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 ## Install
 
 ```bash
-pi install @trevonistrevon/pi-loop
+pi install npm:@trevonistrevon/pi-loop
 ```
 
 ## Quick start
@@ -109,6 +109,16 @@ Only task counts and the single active/next task are shown in the widget so atte
 
 In `session` scope (default), loop and task files are saved per session ID (e.g. `.pi/tasks/tasks-<sessionId>.json`) so concurrent sessions and worktree agents do not share state. In `memory` scope nothing persists to disk.
 
+### Recommended scope policy
+
+Keep `PI_LOOP_SCOPE=session` as the default.
+
+- `session` is the best balance for normal use: it preserves loops/tasks across a session restart while isolating concurrent sessions and worktrees.
+- `memory` is best for disposable scratch work, tests, or situations where you explicitly do not want any persisted loop/task state.
+- `project` should be opt-in for intentionally shared automation, because it allows multiple sessions in the same repo to see the same persisted state.
+
+This matches the current wake model well: pending notifications stay in memory and are cancelable, while durable loop/task intent remains scoped per session.
+
 ## Limits
 
 25 active loops, 25 running monitors. Recurring loops expire after 7 days.

package/dist/coordinator.d.ts

@@ -0,0 +1,35 @@
+export type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
+export type ReducerEntityType = "task" | "loop" | "monitor" | "notification" | "goal";
+export interface ReducerEvent<TType extends string = string, TPayload = unknown> {
+    type: TType;
+    at: number;
+    source: ReducerSource;
+    entityType?: ReducerEntityType;
+    entityId?: string;
+    payload: TPayload;
+}
+export interface ReducerEffect<TEffect extends string = string, TPayload = unknown> {
+    type: TEffect;
+    entityType?: ReducerEntityType;
+    entityId?: string;
+    payload: TPayload;
+}
+export type DispatchEventEffect = ReducerEffect<"DISPATCH_EVENT", {
+    event: ReducerEvent;
+}>;
+export type AnyReducerEffect = ReducerEffect | DispatchEventEffect;
+export type ReducerHandler = (event: ReducerEvent) => undefined | AnyReducerEffect[] | Promise<undefined | AnyReducerEffect[]>;
+export type EffectHandler = (effect: ReducerEffect) => void | Promise<void>;
+export interface CoordinatorOptions {
+    reducers: ReducerHandler[];
+    effectHandlers?: Partial<Record<string, EffectHandler>>;
+    effectExecutor?: EffectHandler;
+    maxDispatchDepth?: number;
+}
+export declare class CoordinatorError extends Error {
+    constructor(message: string);
+}
+export interface Coordinator {
+    dispatch(event: ReducerEvent): Promise<void>;
+}
+export declare function createCoordinator(options: CoordinatorOptions): Coordinator;

package/dist/coordinator.js

@@ -0,0 +1,56 @@
+export class CoordinatorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CoordinatorError";
+    }
+}
+export function createCoordinator(options) {
+    const { reducers, effectHandlers = {}, effectExecutor, maxDispatchDepth = 100, } = options;
+    function isPromiseLike(value) {
+        return typeof value === "object" && value !== null && "then" in value;
+    }
+    async function executeEffect(effect, depth) {
+        if (effect.type === "DISPATCH_EVENT") {
+            const dispatchEffect = effect;
+            const derivedEvent = dispatchEffect.payload.event;
+            if (!derivedEvent) {
+                throw new CoordinatorError("DISPATCH_EVENT effect missing payload.event");
+            }
+            await dispatchAtDepth(derivedEvent, depth + 1);
+            return;
+        }
+        const specificHandler = effectHandlers[effect.type];
+        if (specificHandler) {
+            const handled = specificHandler(effect);
+            if (isPromiseLike(handled))
+                await handled;
+            return;
+        }
+        if (effectExecutor) {
+            const handled = effectExecutor(effect);
+            if (isPromiseLike(handled))
+                await handled;
+        }
+    }
+    async function dispatchAtDepth(event, depth) {
+        if (depth > maxDispatchDepth) {
+            throw new CoordinatorError(`Maximum dispatch depth exceeded (${maxDispatchDepth})`);
+        }
+        const effects = [];
+        for (const reducer of reducers) {
+            const emitted = reducer(event);
+            const resolved = isPromiseLike(emitted) ? await emitted : emitted;
+            if (!resolved || resolved.length === 0)
+                continue;
+            effects.push(...resolved);
+        }
+        for (const effect of effects) {
+            await executeEffect(effect, depth);
+        }
+    }
+    return {
+        async dispatch(event) {
+            await dispatchAtDepth(event, 1);
+        },
+    };
+}

package/dist/goal-types.d.ts

@@ -0,0 +1,78 @@
+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>;
+}

package/dist/goal-types.js

@@ -0,0 +1 @@
+export {};

package/dist/goal-verifier.d.ts

@@ -0,0 +1,20 @@
+import type { ReducerEffect } from "./coordinator.js";
+import type { GoalEntry, GoalProgressSnapshot } from "./goal-types.js";
+import type { LoopReducerState } from "./loop-reducer.js";
+import type { MonitorReducerState } from "./monitor-reducer.js";
+import type { TaskReducerState } from "./task-reducer.js";
+export interface GoalVerifierInput {
+    goal: GoalEntry;
+    taskState: TaskReducerState;
+    loopState: LoopReducerState;
+    monitorState: MonitorReducerState;
+    at: number;
+}
+export interface GoalVerifierResult {
+    progress: GoalProgressSnapshot;
+    verdict: "passed" | "failed" | "blocked";
+    reason: string;
+    effects: ReducerEffect[];
+}
+export declare function projectGoalProgress(goal: GoalEntry, taskState: TaskReducerState, loopState: LoopReducerState, monitorState: MonitorReducerState): GoalProgressSnapshot;
+export declare function verifyGoal(input: GoalVerifierInput): GoalVerifierResult;

package/dist/goal-verifier.js

@@ -0,0 +1,198 @@
+function uniqueById(items) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        if (seen.has(item.id))
+            continue;
+        seen.add(item.id);
+        result.push(item);
+    }
+    return result;
+}
+function selectTasks(goal, taskState) {
+    const selected = [];
+    for (const id of goal.scope.taskIds ?? []) {
+        const task = taskState.tasksById[id];
+        if (task)
+            selected.push(task);
+    }
+    for (const prefix of goal.scope.subjectPrefixes ?? []) {
+        for (const task of Object.values(taskState.tasksById)) {
+            if (task.subject.startsWith(prefix))
+                selected.push(task);
+        }
+    }
+    return uniqueById(selected);
+}
+function selectLoops(goal, loopState) {
+    const selected = [];
+    for (const id of goal.scope.loopIds ?? []) {
+        const loop = loopState.loopsById[id];
+        if (loop)
+            selected.push(loop);
+    }
+    return uniqueById(selected);
+}
+function selectMonitors(goal, monitorState) {
+    const selected = [];
+    for (const id of goal.scope.monitorIds ?? []) {
+        const monitor = monitorState.monitorsById[id];
+        if (monitor)
+            selected.push(monitor);
+    }
+    return uniqueById(selected);
+}
+export function projectGoalProgress(goal, taskState, loopState, monitorState) {
+    const tasks = selectTasks(goal, taskState);
+    const loops = selectLoops(goal, loopState);
+    const monitors = selectMonitors(goal, monitorState);
+    const timestamps = [];
+    for (const task of tasks)
+        timestamps.push(task.updatedAt);
+    for (const loop of loops)
+        timestamps.push(loop.updatedAt);
+    for (const monitor of monitors)
+        timestamps.push(monitor.completedAt ?? monitor.startedAt);
+    return {
+        totalTasks: tasks.length,
+        pendingTasks: tasks.filter(task => task.status === "pending").length,
+        inProgressTasks: tasks.filter(task => task.status === "in_progress").length,
+        completedTasks: tasks.filter(task => task.status === "completed").length,
+        activeLoops: loops.filter(loop => loop.status === "active").length,
+        pausedLoops: loops.filter(loop => loop.status === "paused").length,
+        runningMonitors: monitors.filter(monitor => monitor.status === "running").length,
+        completedMonitors: monitors.filter(monitor => monitor.status === "completed").length,
+        erroredMonitors: monitors.filter(monitor => monitor.status === "error").length,
+        stoppedMonitors: monitors.filter(monitor => monitor.status === "stopped").length,
+        lastProgressAt: timestamps.length > 0 ? Math.max(...timestamps) : undefined,
+    };
+}
+function dispatchEffect(event) {
+    return {
+        type: "DISPATCH_EVENT",
+        entityType: "goal",
+        entityId: event.entityId,
+        payload: { event },
+    };
+}
+function buildEffects(goal, at, progress, resultType, reason) {
+    return [
+        dispatchEffect({
+            type: "GOAL_VERIFICATION_STARTED",
+            at,
+            source: "coordinator",
+            entityType: "goal",
+            entityId: goal.id,
+            payload: { id: goal.id },
+        }),
+        dispatchEffect({
+            type: "GOAL_PROGRESS_RECORDED",
+            at,
+            source: "coordinator",
+            entityType: "goal",
+            entityId: goal.id,
+            payload: { id: goal.id, progress },
+        }),
+        dispatchEffect({
+            type: resultType,
+            at,
+            source: "coordinator",
+            entityType: "goal",
+            entityId: goal.id,
+            payload: { id: goal.id, reason, progress },
+        }),
+    ];
+}
+export function verifyGoal(input) {
+    const { goal, taskState, loopState, monitorState, at } = input;
+    const progress = projectGoalProgress(goal, taskState, loopState, monitorState);
+    if (goal.criteria.failure?.maxVerificationFailures !== undefined
+        && goal.verification.failures >= goal.criteria.failure.maxVerificationFailures) {
+        return {
+            progress,
+            verdict: "failed",
+            reason: "maximum verification failures reached",
+            effects: buildEffects(goal, at, progress, "GOAL_FAILED", "maximum verification failures reached"),
+        };
+    }
+    for (const monitorId of goal.criteria.failure?.anyMonitorIdsErrored ?? []) {
+        if (monitorState.monitorsById[monitorId]?.status === "error") {
+            return {
+                progress,
+                verdict: "failed",
+                reason: `monitor #${monitorId} errored`,
+                effects: buildEffects(goal, at, progress, "GOAL_FAILED", `monitor #${monitorId} errored`),
+            };
+        }
+    }
+    for (const taskId of goal.criteria.failure?.failIfTaskIdsDeleted ?? []) {
+        if (!taskState.tasksById[taskId]) {
+            return {
+                progress,
+                verdict: "failed",
+                reason: `task #${taskId} missing`,
+                effects: buildEffects(goal, at, progress, "GOAL_FAILED", `task #${taskId} missing`),
+            };
+        }
+    }
+    const requiredTasksDone = (goal.criteria.success.requiredTaskIds ?? [])
+        .every(taskId => taskState.tasksById[taskId]?.status === "completed");
+    const requiredMonitorsDone = (goal.criteria.success.requiredMonitorIdsCompleted ?? [])
+        .every(monitorId => monitorState.monitorsById[monitorId]?.status === "completed");
+    const requiredLoopsPresent = (goal.criteria.success.requiredLoopIdsPresent ?? [])
+        .every(loopId => Boolean(loopState.loopsById[loopId]));
+    const minCompletedTasksMet = progress.completedTasks >= (goal.criteria.success.minCompletedTasks ?? 0);
+    const noPendingWork = !goal.criteria.success.requireNoPendingTasksInScope
+        || (progress.pendingTasks === 0 && progress.inProgressTasks === 0);
+    const latestVerificationPass = !goal.criteria.success.requireLatestVerificationPass
+        || goal.verificationStatus === "verified";
+    const success = requiredTasksDone
+        && requiredMonitorsDone
+        && requiredLoopsPresent
+        && minCompletedTasksMet
+        && noPendingWork
+        && latestVerificationPass;
+    if (success) {
+        return {
+            progress,
+            verdict: "passed",
+            reason: "success criteria satisfied",
+            effects: buildEffects(goal, at, progress, "GOAL_VERIFICATION_PASSED", "success criteria satisfied"),
+        };
+    }
+    if (goal.criteria.blocked?.blockedIfRequiredLoopMissing && !requiredLoopsPresent) {
+        return {
+            progress,
+            verdict: "blocked",
+            reason: "required loop missing",
+            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "required loop missing"),
+        };
+    }
+    if (goal.criteria.blocked?.blockedIfNoScopedProgressSinceMs !== undefined
+        && progress.lastProgressAt !== undefined
+        && at - progress.lastProgressAt >= goal.criteria.blocked.blockedIfNoScopedProgressSinceMs) {
+        return {
+            progress,
+            verdict: "blocked",
+            reason: "no scoped progress within configured interval",
+            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "no scoped progress within configured interval"),
+        };
+    }
+    if (goal.criteria.blocked?.blockedIfAllTasksCompletedButVerificationFails
+        && progress.totalTasks > 0
+        && progress.pendingTasks === 0
+        && progress.inProgressTasks === 0) {
+        return {
+            progress,
+            verdict: "blocked",
+            reason: "all scoped tasks completed but verification has not passed",
+            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "all scoped tasks completed but verification has not passed"),
+        };
+    }
+    return {
+        progress,
+        verdict: "failed",
+        reason: "success criteria not yet satisfied",
+        effects: buildEffects(goal, at, progress, "GOAL_VERIFICATION_FAILED", "success criteria not yet satisfied"),
+    };
+}