reflex-state 0.1.0-alpha.1

package/dist/typesafe/questions.d.ts

@@ -0,0 +1,5 @@
+import type { StateUpdateContext } from "../core/updater.js";
+import type { Question } from "./client.js";
+export declare const phases: readonly ["planning", "exploring", "editing", "testing", "debugging", "done", "unknown"];
+export declare const categories: readonly ["implementation", "environment", "dependency", "test", "permissions", "network", "unknown"];
+export declare function buildQuestions(context: StateUpdateContext): Record<string, Question>;

package/dist/typesafe/questions.js

@@ -0,0 +1,50 @@
+import { buildRequestPlan } from "./request_plan.js";
+export const phases = [
+    "planning",
+    "exploring",
+    "editing",
+    "testing",
+    "debugging",
+    "done",
+    "unknown",
+];
+export const categories = [
+    "implementation",
+    "environment",
+    "dependency",
+    "test",
+    "permissions",
+    "network",
+    "unknown",
+];
+export function buildQuestions(context) {
+    const questions = {};
+    const plan = buildRequestPlan(context);
+    for (const item of plan.items) {
+        if (item.kind === "blocker_introduced")
+            questions[item.id] = noul("Does this observation introduce a currently unresolved blocker to the user's goal?");
+        if (item.kind === "failure_category")
+            questions[item.id] = choice("Classify the cause of this failure using the evidence. Choose unknown when it does not establish a cause.", categories);
+        if (item.kind === "resolve")
+            questions[item.id] = noul("Does the latest observation resolve or supersede blocker " +
+                item.eventId +
+                "? Success alone is insufficient without evidence of a relationship.");
+        if (item.kind === "relevance")
+            questions[item.id] = noul("Is evidence " + item.eventId + " still relevant to the current user goal?");
+        if (item.kind === "task_complete")
+            questions[item.id] = noul("Does the final response and verification evidence establish that the current user goal is fully completed? An aborted or failed run is not completion.");
+        if (item.kind === "phase_shadow")
+            questions[item.id] = choice("What phase is the coding task currently in? This answer is recorded for comparison only.", phases);
+    }
+    return questions;
+}
+function noul(instructions) {
+    return { type: "noul", instructions };
+}
+function choice(instructions, values) {
+    return {
+        type: "choice",
+        instructions,
+        criteria: Object.fromEntries(values.map((value) => [value, value.replaceAll("_", " ")])),
+    };
+}

package/dist/typesafe/request_plan.d.ts

@@ -0,0 +1,19 @@
+import type { EventId } from "../core/types.js";
+import type { StateUpdateContext } from "../core/updater.js";
+type RequestQuestionKind = "blocker_introduced" | "failure_category" | "resolve" | "relevance" | "task_complete" | "phase_shadow";
+interface RequestPlanItem {
+    readonly id: string;
+    readonly kind: RequestQuestionKind;
+    readonly eventId?: EventId;
+    readonly requiredEvidence: readonly EventId[];
+}
+interface RequestPlan {
+    readonly items: readonly RequestPlanItem[];
+    readonly skipped: readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[];
+    readonly evidenceIds: readonly EventId[];
+}
+export declare function buildRequestPlan(context: StateUpdateContext): RequestPlan;
+export {};

package/dist/typesafe/request_plan.js

@@ -0,0 +1,96 @@
+import { admitsEvidence } from "../core/reducer.js";
+const MAX_QUESTIONS = 8;
+const MAX_INPUT_BYTES = 24_000;
+const INPUT_OVERHEAD_BYTES = 6_000;
+export function buildRequestPlan(context) {
+    const { event, facts, state, evidence, config } = context;
+    if (isReadEvent(event))
+        return { items: [], skipped: [], evidenceIds: [] };
+    const candidates = [];
+    const latest = event.id;
+    if (event.type === "tool_result" && event.isError) {
+        if (facts.verification?.status !== "failed")
+            candidates.push({
+                id: "blocker_introduced",
+                kind: "blocker_introduced",
+                requiredEvidence: [latest],
+            });
+        candidates.push({
+            id: "failure_category",
+            kind: "failure_category",
+            requiredEvidence: [latest],
+        });
+    }
+    if (event.type === "tool_result" && !event.isError) {
+        for (const blocker of state.activeBlockers.filter((item) => item.origin === "tool_error")) {
+            candidates.push({
+                id: "resolves_" + blocker.eventId,
+                kind: "resolve",
+                eventId: blocker.eventId,
+                requiredEvidence: [blocker.eventId, latest],
+            });
+        }
+    }
+    if (event.type === "agent_end")
+        candidates.push({
+            id: "task_complete",
+            kind: "task_complete",
+            requiredEvidence: completionEvidence(state, latest),
+        });
+    const remaining = state.workingSet.filter((id) => !facts.supersededInWorkingSet.includes(id) && !facts.deterministicallyResolved.includes(id));
+    if (admitsEvidence(event, facts) && remaining.length + 1 > config.limits.maxWorkingSetEvents) {
+        for (const id of remaining.slice(0, 4))
+            candidates.push({
+                id: "relevant_" + id,
+                kind: "relevance",
+                eventId: id,
+                requiredEvidence: [id],
+            });
+    }
+    const items = [];
+    const skipped = [];
+    const available = candidates.filter((item) => {
+        const missing = item.requiredEvidence.filter((id) => !evidence.has(id) && id !== latest);
+        if (!missing.length)
+            return true;
+        skipped.push({ id: item.id, reason: "evidence_unavailable" });
+        return false;
+    });
+    if (config.shadowQuestions.includes("phase") && available.length)
+        available.push({ id: "phase_shadow", kind: "phase_shadow", requiredEvidence: [latest] });
+    const selected = [];
+    let estimatedBytes = INPUT_OVERHEAD_BYTES + Buffer.byteLength(JSON.stringify({ state, event }));
+    for (const item of available) {
+        const evidenceBytes = item.requiredEvidence.reduce((total, id) => {
+            const source = id === latest ? event : evidence.get(id);
+            return total + (source ? Buffer.byteLength(JSON.stringify(source)) : 0);
+        }, 0);
+        const itemBytes = Buffer.byteLength(JSON.stringify(item)) + evidenceBytes;
+        if (estimatedBytes + itemBytes > MAX_INPUT_BYTES) {
+            skipped.push({ id: item.id, reason: "input_budget" });
+            continue;
+        }
+        selected.push(item);
+        estimatedBytes += itemBytes;
+    }
+    for (const item of available) {
+        if (!selected.includes(item))
+            continue;
+        if (items.length >= MAX_QUESTIONS) {
+            skipped.push({ id: item.id, reason: "question_limit" });
+            continue;
+        }
+        items.push(item);
+    }
+    const evidenceIds = [...new Set(items.flatMap((item) => item.requiredEvidence))];
+    return { items, skipped, evidenceIds };
+}
+function completionEvidence(state, latest) {
+    const verification = Object.values(state.verification).flatMap((item) => item.evidence ? [item.evidence] : []);
+    return [
+        ...new Set([...state.activeBlockers.map((item) => item.eventId), ...verification, latest]),
+    ];
+}
+function isReadEvent(event) {
+    return event.type === "tool_result" && ["read", "grep", "find", "ls"].includes(event.toolName);
+}

package/dist/typesafe/updater.d.ts

@@ -0,0 +1,17 @@
+import type { SemanticDecisions } from "../core/types.js";
+import type { StateUpdateContext, StateUpdater, UpdaterHealth } from "../core/updater.js";
+import type { TypeSafeSystemOneClient } from "./client.js";
+export declare class JevStateUpdater implements StateUpdater {
+    private readonly client;
+    private readonly options;
+    readonly name = "jev";
+    private failures;
+    private openedUntil;
+    private disabledReason;
+    constructor(client: TypeSafeSystemOneClient, options?: {
+        notify?: (message: string) => void;
+    });
+    get health(): UpdaterHealth;
+    evaluate(context: StateUpdateContext, signal?: AbortSignal): Promise<SemanticDecisions>;
+    private recordFailure;
+}

package/dist/typesafe/updater.js

@@ -0,0 +1,82 @@
+import { emptyDecisions } from "../core/updater.js";
+import { failureKind } from "./client.js";
+import { RequestCancelledError, withinDeadline } from "./deadline.js";
+import { decodeDecisions, describeResponse, errorDecisions } from "./decisions.js";
+import { buildInput } from "./input.js";
+import { buildQuestions } from "./questions.js";
+export class JevStateUpdater {
+    client;
+    options;
+    name = "jev";
+    failures = 0;
+    openedUntil = 0;
+    disabledReason;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+    }
+    get health() {
+        if (this.disabledReason)
+            return { status: "disabled", circuit: "closed", reason: this.disabledReason };
+        if (this.openedUntil > Date.now())
+            return { status: "degraded", circuit: "open" };
+        if (this.openedUntil)
+            return { status: "degraded", circuit: "half_open" };
+        return { status: this.failures ? "degraded" : "ok", circuit: "closed" };
+    }
+    async evaluate(context, signal) {
+        if (!context.config.jev.enabled)
+            return emptyDecisions();
+        if (this.disabledReason)
+            return errorDecisions([], this.disabledReason);
+        if (this.openedUntil > Date.now())
+            return errorDecisions([], "circuit_open");
+        const questions = buildQuestions(context);
+        const ids = Object.keys(questions);
+        if (!ids.length)
+            return emptyDecisions();
+        const started = performance.now();
+        let invoked = false;
+        let response;
+        let responseShape;
+        let decisions;
+        try {
+            response = await withinDeadline((requestSignal) => {
+                const state = buildInput(context);
+                invoked = true;
+                return this.client.systemOne({ state, questions, model: context.config.jev.model }, { signal: requestSignal });
+            }, { deadlineMs: context.config.jev.deadlineMs, signal });
+            decisions = decodeDecisions(response, ids, context.config.thresholds);
+            this.failures = 0;
+            this.openedUntil = 0;
+        }
+        catch (error) {
+            const kind = error instanceof RequestCancelledError ? error.kind : failureKind(error);
+            if (kind === "invalid_response")
+                responseShape = describeResponse(response, ids);
+            if (kind !== "aborted")
+                this.recordFailure(kind, context);
+            decisions = errorDecisions(ids, kind);
+        }
+        return {
+            ...decisions,
+            telemetry: {
+                ...decisions.telemetry,
+                questionsAsked: invoked ? ids.length : 0,
+                questionIds: invoked ? ids : [],
+                ...(invoked ? { latencyMs: performance.now() - started } : {}),
+                ...(responseShape ? { responseShape } : {}),
+            },
+        };
+    }
+    recordFailure(kind, context) {
+        this.failures++;
+        if (kind === "auth_error") {
+            this.disabledReason = kind;
+            this.options.notify?.("ReflexState: Jev authentication failed; deterministic updates remain active.");
+        }
+        else if (this.failures >= 3) {
+            this.openedUntil = Date.now() + context.config.jev.cooldownMs;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "reflex-state",
+  "version": "0.1.0-alpha.1",
+  "description": "SKILL.state + Jev for Pi: execution state maintained by typed decisions and code, separate from the reasoning LLM.",
+  "keywords": [
+    "agent-memory",
+    "agent-state",
+    "ai-agents",
+    "coding-agent",
+    "context-engineering",
+    "context-management",
+    "jev",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "replay",
+    "skill-state",
+    "typesafe-ai"
+  ],
+  "homepage": "https://github.com/furedea/reflex-state#readme",
+  "bugs": {
+    "url": "https://github.com/furedea/reflex-state/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/furedea/reflex-state.git"
+  },
+  "bin": {
+    "reflex-state-export": "./dist/export_trace_cli.js",
+    "reflex-state-replay": "./dist/replay_cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README_ja.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "package:check": "node scripts/check_package.mjs",
+    "replay": "pnpm --silent run build && node dist/replay_cli.js",
+    "export-trace": "pnpm --silent run build && node dist/export_trace_cli.js",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "typecheck": "oxlint --type-aware --type-check .",
+    "test": "vitest run",
+    "test:release": "node --test scripts/*.test.mjs",
+    "test:watch": "vitest",
+    "knip": "knip",
+    "knip:production": "knip --production",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run test:release && pnpm run knip"
+  },
+  "dependencies": {
+    "@typesafe-ai/sdk": "0.6.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@types/node": "24.13.3",
+    "knip": "6.4.1",
+    "oxfmt": "0.45.0",
+    "oxlint": "1.60.0",
+    "oxlint-tsgolint": "0.21.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "pi": {
+    "extensions": [
+      "./dist/pi/index.js"
+    ]
+  }
+}