reflex-state 0.1.0-alpha.1

package/dist/core/updater.js

@@ -0,0 +1,27 @@
+export function emptyDecisions() {
+    return { resolvedBlockers: [], relevance: [], telemetry: { questionsAsked: 0, questionIds: [] } };
+}
+export class NoopStateUpdater {
+    name = "noop";
+    evaluate() {
+        return Promise.resolve(emptyDecisions());
+    }
+}
+export class RecordedDecisionsUpdater {
+    name = "recorded";
+    records;
+    constructor(records) {
+        this.records = new Map(records.map((record) => [record.event.id, record]));
+        if (this.records.size !== records.length)
+            throw new Error("Duplicate event ID in recording");
+    }
+    evaluate(context) {
+        const record = this.records.get(context.event.id);
+        if (!record)
+            return Promise.reject(new Error("No recorded decisions for " + context.event.id));
+        if (!isDeepStrictEqual(record.event, context.event))
+            return Promise.reject(new Error("Recorded event differs: " + context.event.id));
+        return Promise.resolve(record.decisions);
+    }
+}
+import { isDeepStrictEqual } from "node:util";

package/dist/core/verification.d.ts

@@ -0,0 +1,20 @@
+import type { ReflexStateConfig } from "./config.js";
+import type { AgentEvent, EventId, ToolCallEvent, VerificationFact, VerificationKind } from "./types.js";
+export interface VerificationClassification {
+    readonly kind?: VerificationKind;
+    readonly command: string;
+    readonly cwd: string;
+    readonly compound: boolean;
+    readonly attributable: boolean;
+    readonly checkKey?: string;
+    readonly unknownReason?: string;
+}
+export declare function normalizeCwd(cwd: string): string;
+export declare function normalizeCommand(command: string): string;
+export declare function verificationCheckKey(kind: VerificationKind, cwd: string, command: string): string;
+export declare function classifyVerification(command: string, cwd: string, config: ReflexStateConfig, truncated?: boolean): VerificationClassification | undefined;
+export declare function verificationFact(event: AgentEvent, call: ToolCallEvent | undefined, config: ReflexStateConfig, generation: number, pendingChanges: readonly EventId[], started?: {
+    readonly eventId: EventId;
+    readonly generation: number;
+    readonly checkKey?: string;
+}): VerificationFact | undefined;

package/dist/core/verification.js

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { relative, resolve } from "node:path";
+const commands = {
+    test: /^(pytest|vitest|jest|cargo\s+test|go\s+test|(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test)(?:\s|$)/,
+    build: /^(tsc|cargo\s+build|go\s+build|(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:build|typecheck))(?:\s|$)/,
+    lint: /^(eslint|oxlint|biome|ruff|cargo\s+clippy|clippy|golangci-lint|(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?lint)(?:\s|$)/,
+};
+export function normalizeCwd(cwd) {
+    const absolute = resolve("/", cwd || ".");
+    return relative("/", absolute) ? absolute.replace(/\/$/, "") : "/";
+}
+export function normalizeCommand(command) {
+    let result = "";
+    let quote = "";
+    let escaped = false;
+    let pendingSpace = false;
+    for (const char of command.trim()) {
+        if (escaped) {
+            result += char;
+            escaped = false;
+            pendingSpace = false;
+            continue;
+        }
+        if (char === "\\" && quote !== "'") {
+            result += char;
+            escaped = true;
+            pendingSpace = false;
+            continue;
+        }
+        if (quote) {
+            result += char;
+            if (char === quote)
+                quote = "";
+            pendingSpace = false;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            if (pendingSpace)
+                result += " ";
+            result += char;
+            quote = char;
+            pendingSpace = false;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            pendingSpace = result.length > 0;
+            continue;
+        }
+        if (pendingSpace)
+            result += " ";
+        result += char;
+        pendingSpace = false;
+    }
+    return result;
+}
+export function verificationCheckKey(kind, cwd, command) {
+    const identity = JSON.stringify([kind, normalizeCwd(cwd), normalizeCommand(command)]);
+    return "check:" + createHash("sha256").update(identity).digest("hex");
+}
+export function classifyVerification(command, cwd, config, truncated = false) {
+    const normalized = normalizeCommand(command);
+    const kind = detectKind(normalized, config);
+    if (!kind)
+        return undefined;
+    const shell = shellOperators(normalized);
+    const compound = shell.length > 0 || hasUnclosedSyntax(normalized);
+    const unknownReason = truncated
+        ? "command_truncated"
+        : shell.length > 0
+            ? "compound_command"
+            : compound
+                ? "ambiguous_shell_syntax"
+                : undefined;
+    return {
+        kind,
+        command,
+        cwd: normalizeCwd(cwd),
+        compound,
+        attributable: !unknownReason,
+        ...(unknownReason ? { unknownReason } : {}),
+        ...(!unknownReason ? { checkKey: verificationCheckKey(kind, cwd, command) } : {}),
+    };
+}
+export function verificationFact(event, call, config, generation, pendingChanges, started) {
+    if (!call || call.toolName !== "bash" || typeof call.input.command !== "string")
+        return undefined;
+    const classification = classifyVerification(call.input.command, call.cwd ?? ".", config, call.commandTruncated);
+    if (!classification?.kind)
+        return undefined;
+    const kind = classification.kind;
+    const status = statusFor(event, classification);
+    const current = event.type === "tool_call"
+        ? true
+        : Boolean(started &&
+            started.generation === generation &&
+            pendingChanges.every((id) => id === started.eventId));
+    const freshness = event.type === "tool_call"
+        ? "unknown"
+        : classification.attributable
+            ? current
+                ? "current"
+                : "stale"
+            : "unknown";
+    return {
+        ...classification,
+        kind,
+        status,
+        ...(started ? { startedEvent: started.eventId, observedGeneration: started.generation } : {}),
+        freshness,
+    };
+}
+function detectKind(command, config) {
+    return candidateSegments(command)
+        .map((segment) => detectSingle(segment, config))
+        .find(Boolean);
+}
+function detectSingle(command, config) {
+    const executable = command.trim().replace(/^(?:npx\s+|(?:npm|pnpm|yarn|bun)\s+exec\s+)/, "");
+    return ["test", "build", "lint"].find((kind) => commands[kind].test(executable) ||
+        config.verificationCommands[kind].some((pattern) => {
+            try {
+                return new RegExp(pattern).test(executable);
+            }
+            catch {
+                return false;
+            }
+        }));
+}
+function candidateSegments(command) {
+    const segments = [];
+    let part = "";
+    let quote = "";
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            part += char;
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quote !== "'") {
+            part += char;
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            part += char;
+            if (char === quote)
+                quote = "";
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            part += char;
+            quote = char;
+            continue;
+        }
+        if (";|&<>\n".includes(char)) {
+            if (part.trim())
+                segments.push(part.trim());
+            part = "";
+            continue;
+        }
+        part += char;
+    }
+    if (part.trim())
+        segments.push(part.trim());
+    return segments;
+}
+function shellOperators(command) {
+    const operators = [];
+    let quote = "";
+    let escaped = false;
+    for (let index = 0; index < command.length; index++) {
+        const char = command[index] ?? "";
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = "";
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            continue;
+        }
+        if (char === "$" && command[index + 1] === "(")
+            operators.push("substitution");
+        else if (char === "`" || ";|&<>\n".includes(char))
+            operators.push(char);
+    }
+    return operators;
+}
+function hasUnclosedSyntax(command) {
+    let quote = "";
+    let escaped = false;
+    for (const char of command) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\" && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = "";
+            continue;
+        }
+        if (char === "'" || char === '"')
+            quote = char;
+    }
+    return Boolean(quote || escaped);
+}
+function statusFor(event, classification) {
+    if (event.type === "tool_call")
+        return "running";
+    if (event.type !== "tool_result")
+        return "unknown";
+    if (!classification.attributable)
+        return "unknown";
+    if (!event.isError)
+        return "passed";
+    const text = event.excerpt.head + (event.excerpt.tail ? "\n" + event.excerpt.tail : "");
+    const match = /(?:^|\n)Command exited with code (\d+)\s*$/.exec(text);
+    if (!match)
+        return "unknown";
+    return Number(match[1]) === 0 ? "passed" : "failed";
+}

package/dist/export_trace_cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/export_trace_cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { jsonLines, readConfigFile, writeArtifacts } from "./cli_io.js";
+import { isRecord, parseJsonLines } from "./core/serialization.js";
+import { exportSession } from "./pi/trace.js";
+import { redact } from "./typesafe/input.js";
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            leaf: { type: "string" },
+            config: { type: "string" },
+            out: { type: "string", default: "trace-output" },
+        },
+    });
+    const input = positionals[0];
+    if (!input || positionals.length !== 1)
+        throw new Error("Usage: reflex-state-export <session.jsonl> [--leaf id] [--out dir] [--config file]");
+    const entries = parseJsonLines(await readFile(input, "utf8"), (value) => {
+        if (!isRecord(value) || typeof value.type !== "string")
+            throw new Error("Invalid Pi entry");
+        return value;
+    });
+    const result = exportSession(entries, {
+        config: await readConfigFile(values.config),
+        ...(values.leaf ? { leaf: values.leaf } : {}),
+    });
+    await writeArtifacts(values.out, {
+        "events.jsonl": jsonLines(result.events),
+        "transitions.jsonl": jsonLines(result.transitions),
+        "trace_meta.json": JSON.stringify({
+            cwd: result.cwd,
+            config: result.config,
+            leaf: result.leaf,
+            formatVersion: result.formatVersion,
+            legacy: result.legacy,
+        }, null, 2) + "\n",
+    }, [input]);
+    console.log(result.events.length + " events exported to " + values.out);
+}
+await main().catch((error) => {
+    console.error(redact(error instanceof Error ? error.message : "Trace export failed"));
+    process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { defaultConfig } from "./core/config.js";
+export type { ReflexStateConfig } from "./core/config.js";
+export { StateEngine } from "./core/engine.js";
+export { extractFacts } from "./core/extraction.js";
+export type { ExtractionContext } from "./core/extraction.js";
+export { classifyVerification, normalizeCommand, normalizeCwd, verificationCheckKey, } from "./core/verification.js";
+export type { VerificationClassification } from "./core/verification.js";
+export { blockerView, stateView, workingSetView } from "./core/state_view.js";
+export { Metrics } from "./core/metrics.js";
+export { initialState, reduce } from "./core/reducer.js";
+export type * from "./core/types.js";
+export { NoopStateUpdater, RecordedDecisionsUpdater } from "./core/updater.js";
+export type { StateUpdater, StateUpdateContext, UpdaterHealth } from "./core/updater.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { defaultConfig } from "./core/config.js";
+export { StateEngine } from "./core/engine.js";
+export { extractFacts } from "./core/extraction.js";
+export { classifyVerification, normalizeCommand, normalizeCwd, verificationCheckKey, } from "./core/verification.js";
+export { blockerView, stateView, workingSetView } from "./core/state_view.js";
+export { Metrics } from "./core/metrics.js";
+export { initialState, reduce } from "./core/reducer.js";
+export { NoopStateUpdater, RecordedDecisionsUpdater } from "./core/updater.js";

package/dist/pi/commands.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SessionRuntime } from "./runtime.js";
+export declare function registerCommands(pi: ExtensionAPI, runtime: () => SessionRuntime | undefined): void;

package/dist/pi/commands.js

@@ -0,0 +1,123 @@
+import { decisionEntries } from "../core/metrics.js";
+import { blockerView, workingSetView } from "../core/state_view.js";
+const suggestions = [
+    "history",
+    "stats",
+    "debug",
+    "reset",
+    "projection on",
+    "projection off",
+    "jev on",
+    "jev off",
+];
+export function registerCommands(pi, runtime) {
+    pi.registerCommand("state", {
+        description: "Inspect ReflexState, its evidence, and updater health",
+        getArgumentCompletions: (prefix) => suggestions
+            .filter((value) => value.startsWith(prefix))
+            .map((value) => ({ value, label: value })),
+        handler: async (args, ctx) => {
+            const session = runtime();
+            if (!session) {
+                ctx.ui.notify("ReflexState is unavailable for this session.", "warning");
+                return;
+            }
+            await session.engine.idle();
+            await handleCommand(args.trim(), session, ctx);
+            session.widget(ctx);
+        },
+    });
+}
+async function handleCommand(args, session, ctx) {
+    if (!args) {
+        ctx.ui.notify(renderState(session), "info");
+        return;
+    }
+    if (args === "stats") {
+        const blockers = blockerView(session.state, session.config);
+        const workingSet = workingSetView(session.state, session.config.limits.maxWorkingSetEvents);
+        ctx.ui.notify(JSON.stringify({
+            ...session.metrics.snapshot(),
+            health: session.health,
+            workingSet: {
+                count: workingSet.total,
+                shown: workingSet.shownCount,
+                omitted: workingSet.omittedCount,
+                cap: session.config.limits.maxWorkingSetEvents,
+            },
+            blockers: {
+                count: blockers.unresolvedTotal,
+                shown: blockers.shownCount,
+                omitted: blockers.omittedCount,
+                cap: session.config.limits.maxProjectedBlockers,
+            },
+        }, missingMetric, 2), "info");
+        return;
+    }
+    if (args === "debug") {
+        ctx.ui.notify(JSON.stringify(session.history.findLast((record) => record.decisions.telemetry.questionsAsked > 0)
+            ?.decisions ?? { message: "No semantic decisions yet" }, null, 2), "info");
+        return;
+    }
+    const history = /^history(?:\s+(\d+))?$/.exec(args);
+    if (history) {
+        const count = Math.min(1000, Math.max(1, Number(history[1] ?? 10)));
+        ctx.ui.notify(session.history
+            .slice(-count)
+            .map((record) => record.id +
+            " " +
+            record.event.id +
+            " " +
+            record.event.type +
+            "\n" +
+            record.changes.join("\n") +
+            "\n" +
+            decisionEntries(record.decisions)
+                .map(([id, decision]) => id + ": " + decision.gate + (decision.shadow ? " (shadow)" : ""))
+                .join(", "))
+            .join("\n\n") || "No transitions yet", "info");
+        return;
+    }
+    if (args === "reset") {
+        await ctx.waitForIdle();
+        if (await ctx.ui.confirm("Reset ReflexState?", "The current hot state will be cleared. The original session history remains available."))
+            await session.reset();
+        return;
+    }
+    const toggle = /^(projection|jev)\s+(on|off)$/.exec(args);
+    if (toggle) {
+        await session.toggle(toggle[1], toggle[2] === "on");
+        ctx.ui.notify("ReflexState " + args, "info");
+        return;
+    }
+    ctx.ui.notify("Usage: /state [history [n] | stats | debug | reset | projection on|off | jev on|off]", "warning");
+}
+function renderState(session) {
+    const state = session.state;
+    const blockers = blockerView(state, session.config);
+    const workingSet = workingSetView(state, session.config.limits.maxWorkingSetEvents);
+    return [
+        "goal: " + (state.goal ?? "none"),
+        "phase: " + state.phase,
+        "task_status: " + state.taskStatus,
+        "modified_files: " + JSON.stringify(state.modifiedFiles),
+        "relevant_files: " + JSON.stringify(state.relevantFiles),
+        "verification: " + JSON.stringify(state.verification),
+        "active_blockers: " +
+            JSON.stringify({
+                unresolved_total: blockers.unresolvedTotal,
+                shown: blockers.blockers,
+                omitted: blockers.omittedCount,
+            }),
+        "working_set: " +
+            JSON.stringify({
+                total: workingSet.total,
+                shown: workingSet.events,
+                omitted: workingSet.omittedCount,
+            }),
+        ...(state.stateHealth && state.stateHealth !== "valid" ? [state.stateHealth] : []),
+    ].join("\n");
+}
+function missingMetric(_key, value) {
+    return value === undefined ? "n/a" : value;
+}

package/dist/pi/configuration.d.ts

@@ -0,0 +1,12 @@
+interface ConfigOptions {
+    readonly cwd: string;
+    readonly trusted: boolean;
+    readonly globalPath?: string;
+    readonly readText?: (path: string) => Promise<string>;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+export declare function loadConfig(options: ConfigOptions): Promise<{
+    config: import("../core/config.js").ReflexStateConfig;
+    warnings: string[];
+}>;
+export {};

package/dist/pi/configuration.js

@@ -0,0 +1,48 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { defaultConfig } from "../core/config.js";
+import { mergeConfig } from "../core/config_validation.js";
+import { isRecord } from "../core/serialization.js";
+export async function loadConfig(options) {
+    const env = options.environment ?? process.env;
+    let config = defaultConfig();
+    const warnings = [];
+    const files = [
+        options.globalPath ??
+            join(env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "reflex-state.json"),
+    ];
+    if (options.trusted)
+        files.push(join(options.cwd, ".pi", "reflex-state.json"));
+    for (const path of files) {
+        try {
+            const raw = JSON.parse(await (options.readText ?? ((file) => readFile(file, "utf8")))(path));
+            const result = mergeConfig(config, raw);
+            config = result.config;
+            warnings.push(...result.warnings.map((warning) => path + ": " + warning));
+        }
+        catch (error) {
+            if (isRecord(error) && error.code === "ENOENT")
+                continue;
+            config = defaultConfig();
+            warnings.push("Ignoring unreadable or malformed configuration: " + path);
+        }
+    }
+    config = {
+        ...config,
+        enabled: env.REFLEX_STATE_DISABLE === "1" ? false : config.enabled,
+        jev: {
+            ...config.jev,
+            enabled: env.REFLEX_STATE_DISABLE_JEV === "1" ? false : config.jev.enabled,
+        },
+        projection: {
+            ...config.projection,
+            enabled: env.REFLEX_STATE_PROJECTION === "1"
+                ? true
+                : env.REFLEX_STATE_PROJECTION === "0"
+                    ? false
+                    : config.projection.enabled,
+        },
+    };
+    return { config, warnings };
+}

package/dist/pi/extension.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { UpdaterFactory } from "./runtime.js";
+export declare function registerExtension(pi: ExtensionAPI, createUpdater: UpdaterFactory): void;

package/dist/pi/extension.js

@@ -0,0 +1,113 @@
+import { textContent } from "../core/events.js";
+import { registerCommands } from "./commands.js";
+import { loadConfig } from "./configuration.js";
+import { projectContext } from "./projection.js";
+import { SessionRuntime } from "./runtime.js";
+export function registerExtension(pi, createUpdater) {
+    let runtime;
+    const start = async (_event, ctx) => {
+        await runtime?.engine.idle();
+        runtime = undefined;
+        await guarded(ctx, async () => {
+            const { config, warnings } = await loadConfig({
+                cwd: ctx.cwd,
+                trusted: ctx.isProjectTrusted(),
+            });
+            for (const warning of warnings)
+                ctx.ui.notify(warning, "warning");
+            runtime = new SessionRuntime({ pi, ctx, config, createUpdater });
+            const reason = typeof _event === "object" && _event !== null && "newLeafId" in _event
+                ? "branch_switch"
+                : "resume";
+            await runtime.record(runtime.normalizer.resume(reason), ctx);
+            runtime.widget(ctx);
+        });
+    };
+    pi.on("session_start", start);
+    pi.on("session_tree", start);
+    pi.on("context", async (event, ctx) => {
+        if (!runtime || !runtime.projectionSafe)
+            return { messages: event.messages };
+        const session = runtime;
+        await session.engine.idle();
+        const result = projectContext(event.messages, {
+            state: session.state,
+            evidence: session.engine.events,
+            config: session.config,
+            compacting: session.compacting,
+        });
+        session.metrics.projection(result.measurement);
+        session.widget(ctx);
+        return { messages: result.messages };
+    });
+    pi.on("session_shutdown", async () => {
+        await runtime?.engine.idle();
+    });
+    pi.on("before_agent_start", async (event, ctx) => {
+        if (!runtime?.config.enabled)
+            return;
+        const session = runtime;
+        session.compacting = false;
+        session.expectedPrompt = event.prompt;
+        await guarded(ctx, () => session.record(session.normalizer.prompt(event.prompt), ctx));
+    });
+    pi.on("tool_call", async (event, ctx) => {
+        if (runtime?.config.enabled) {
+            const session = runtime;
+            await guarded(ctx, () => session.record(session.normalizer.call(event), ctx));
+        }
+    });
+    pi.on("tool_result", async (event, ctx) => {
+        if (runtime?.config.enabled) {
+            const session = runtime;
+            await guarded(ctx, () => session.record(session.normalizer.result(event), ctx));
+        }
+    });
+    pi.on("agent_end", async (event, ctx) => {
+        if (runtime?.config.enabled) {
+            const session = runtime;
+            await guarded(ctx, () => session.record(session.normalizer.end(event.messages), ctx));
+        }
+    });
+    pi.on("message_end", async ({ message }, ctx) => {
+        if (!runtime?.config.enabled)
+            return;
+        const session = runtime;
+        if (message.role === "assistant")
+            session.metrics.provider(message.usage);
+        if (message.role !== "user")
+            return;
+        const text = textContent(message.content);
+        const duplicate = session.expectedPrompt === text;
+        session.expectedPrompt = undefined;
+        if (!duplicate)
+            await guarded(ctx, () => session.record(session.normalizer.prompt(text, message.timestamp), ctx));
+    });
+    pi.on("session_before_compact", (event) => {
+        if (!runtime)
+            return;
+        const session = runtime;
+        session.compacting = true;
+        event.signal.addEventListener("abort", () => {
+            session.compacting = false;
+        }, { once: true });
+    });
+    pi.on("session_compact", () => {
+        if (runtime)
+            runtime.compacting = false;
+    });
+    pi.on("agent_settled", () => {
+        if (runtime)
+            runtime.compacting = false;
+    });
+    registerCommands(pi, () => runtime);
+}
+async function guarded(ctx, operation) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        ctx.ui.notify("ReflexState could not update: " +
+            (error instanceof Error ? error.name + ": " + error.message : "unknown error"), "warning");
+    }
+}

package/dist/pi/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function reflexState(pi: ExtensionAPI): void;

package/dist/pi/index.js

@@ -0,0 +1,5 @@
+import { createUpdater } from "../composition.js";
+import { registerExtension } from "./extension.js";
+export default function reflexState(pi) {
+    registerExtension(pi, createUpdater);
+}