@w32191/just-loop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @w32191/just-loop
+
+OpenCode plugin package for just-loop.
+
+## Requirements
+
+- Node 20+
+
+## Install
+
+```bash
+npm install @w32191/just-loop
+```
+
+## Usage
+
+Put this in your OpenCode plugin entry or config file:
+
+```ts
+import justLoop from "@w32191/just-loop"
+
+export default justLoop
+```
+
+This package is intended for OpenCode plugin usage.
+
+## Publishing notes
+
+Bun is only a maintenance and release prerequisite. It is not a runtime dependency for normal installers.
+
+## Release
+
+Prerequisites: Node 20+, Bun, and a valid npm login/token.
+
+1. Run `npm login`.
+2. Run `npm whoami`.
+3. Confirm `@w32191` scope access with `npm access list packages @w32191` (or equivalent access check).
+4. Run `npm view @w32191/just-loop version`.
+   - For the first publish, a 404 is expected until the package exists.
+   - The real unblock condition is: `npm whoami` succeeds and scope access checks pass.
+5. Bump the package version.
+6. Run `npm run verify:publish`.
+7. Publish with `npm publish --access public`.

package/dist/src/commands/parse-ralph-loop-command.d.ts

@@ -0,0 +1,11 @@
+export type RalphLoopStartCommand = {
+    kind: "start";
+    prompt: string;
+    maxIterations?: number;
+    completionPromise: string;
+};
+export type RalphLoopCancelCommand = {
+    kind: "cancel";
+};
+export type ParsedRalphLoopCommand = RalphLoopStartCommand | RalphLoopCancelCommand;
+export declare function parseRalphLoopCommand(input: string): ParsedRalphLoopCommand | null;

package/dist/src/commands/parse-ralph-loop-command.js

@@ -0,0 +1,58 @@
+import { DEFAULT_COMPLETION_PROMISE } from "../ralph-loop/constants.js";
+export function parseRalphLoopCommand(input) {
+    const trimmed = input.trim();
+    if (trimmed === "/cancel-ralph") {
+        return { kind: "cancel" };
+    }
+    if (!/^\/ralph-loop(?:\s|$)/.test(trimmed)) {
+        return null;
+    }
+    let rest = trimmed.slice("/ralph-loop".length);
+    let maxIterations;
+    let completionPromise = DEFAULT_COMPLETION_PROMISE;
+    while (true) {
+        rest = rest.replace(/^\s+/, "");
+        if (!rest.startsWith("--")) {
+            break;
+        }
+        if (/^--max(?:\s|$)/.test(rest)) {
+            const valueMatch = rest.match(/^--max(?:\s+(\S+))(?:\s+|$)/);
+            if (!valueMatch || !/^[0-9]+$/.test(valueMatch[1])) {
+                throw new Error("invalid --max value");
+            }
+            maxIterations = Number(valueMatch[1]);
+            rest = rest.slice(valueMatch[0].length);
+            continue;
+        }
+        if (/^--promise(?:\s|$)/.test(rest)) {
+            const promiseMatch = rest.match(/^--promise\s+"([^"]+)"(?:\s+|$)/);
+            if (!promiseMatch) {
+                throw new Error("invalid --promise format");
+            }
+            completionPromise = promiseMatch[1];
+            rest = rest.slice(promiseMatch[0].length);
+            continue;
+        }
+        if (/^--strategy(?:\s|$)/.test(rest)) {
+            const strategyMatch = rest.match(/^--strategy(?:\s+(\S+))(?:\s+|$)/);
+            if (!strategyMatch) {
+                throw new Error("invalid --strategy value");
+            }
+            if (strategyMatch[1] === "reset") {
+                throw new Error("reset strategy is not supported in v1");
+            }
+            throw new Error("invalid --strategy value");
+        }
+        throw new Error("unknown flag");
+    }
+    const prompt = rest.trim().replace(/\s+/g, " ");
+    if (!prompt) {
+        throw new Error("prompt is required");
+    }
+    return {
+        kind: "start",
+        prompt,
+        maxIterations,
+        completionPromise,
+    };
+}

package/dist/src/host-adapter/opencode-host-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { HostAdapter, OpenCodeHostAdapterContext } from "./types.js";
+export declare function createOpenCodeHostAdapter(ctx: OpenCodeHostAdapterContext): HostAdapter;

package/dist/src/host-adapter/opencode-host-adapter.js

@@ -0,0 +1,80 @@
+function buildSessionInput(directory, sessionID) {
+    return {
+        sessionID,
+        directory,
+    };
+}
+function buildPromptInput(directory, sessionID, text) {
+    return {
+        sessionID,
+        directory,
+        parts: [{ type: "text", text }],
+    };
+}
+function extractMessages(response) {
+    const records = Array.isArray(response)
+        ? response
+        : response && typeof response === "object" && Array.isArray(response.data)
+            ? response.data
+            : [];
+    return records.map((item) => {
+        const record = item;
+        const role = typeof record.info?.role === "string" ? record.info.role : "unknown";
+        const text = Array.isArray(record.parts)
+            ? record.parts
+                .filter((part) => part.type === "text" && typeof part.text === "string")
+                .map((part) => part.text)
+                .join("\n")
+            : "";
+        return { role, text };
+    });
+}
+function isNotFoundError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const record = error;
+    return (record.code === "ENOENT" ||
+        record.status === 404 ||
+        error.message.toLowerCase().includes("not found") ||
+        error.message.toLowerCase().includes("missing"));
+}
+export function createOpenCodeHostAdapter(ctx) {
+    return {
+        async getMessageCount(sessionID) {
+            const response = await ctx.client.session.messages(buildSessionInput(ctx.directory, sessionID));
+            if (Array.isArray(response))
+                return response.length;
+            if (response && typeof response === "object" && Array.isArray(response.data)) {
+                return response.data.length;
+            }
+            return 0;
+        },
+        async getMessages(sessionID) {
+            const response = await ctx.client.session.messages(buildSessionInput(ctx.directory, sessionID));
+            return extractMessages(response);
+        },
+        async prompt(sessionID, text) {
+            const input = buildPromptInput(ctx.directory, sessionID, text);
+            if (ctx.client.session.promptAsync) {
+                await ctx.client.session.promptAsync(input);
+                return;
+            }
+            await ctx.client.session.prompt(input);
+        },
+        async abortSession(sessionID) {
+            await ctx.client.session.abort({ sessionID, directory: ctx.directory });
+        },
+        async sessionExists(sessionID) {
+            try {
+                await ctx.client.session.messages(buildSessionInput(ctx.directory, sessionID));
+                return true;
+            }
+            catch (error) {
+                if (isNotFoundError(error)) {
+                    return false;
+                }
+                throw error;
+            }
+        },
+    };
+}

package/dist/src/host-adapter/types.d.ts

@@ -0,0 +1,42 @@
+export type HostMessage = {
+    role: string;
+    text: string;
+};
+export interface HostAdapter {
+    getMessageCount(sessionID: string): Promise<number>;
+    getMessages(sessionID: string): Promise<Array<HostMessage>>;
+    prompt(sessionID: string, text: string): Promise<void>;
+    abortSession(sessionID: string): Promise<void>;
+    sessionExists(sessionID: string): Promise<boolean>;
+}
+export type OpenCodeHostAdapterContext = {
+    directory: string;
+    client: {
+        session: {
+            messages: (input: {
+                sessionID: string;
+                directory: string;
+            }) => Promise<unknown>;
+            promptAsync?: (input: {
+                sessionID: string;
+                directory: string;
+                parts: Array<{
+                    type: "text";
+                    text: string;
+                }>;
+            }) => Promise<unknown>;
+            prompt: (input: {
+                sessionID: string;
+                directory: string;
+                parts: Array<{
+                    type: "text";
+                    text: string;
+                }>;
+            }) => Promise<unknown>;
+            abort: (input: {
+                sessionID: string;
+                directory?: string;
+            }) => Promise<unknown>;
+        };
+    };
+};

package/dist/src/host-adapter/types.js

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

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const plugin: Plugin;
+export default plugin;

package/dist/src/index.js

@@ -0,0 +1,3 @@
+import { createPlugin } from "./plugin/create-plugin.js";
+const plugin = (ctx) => createPlugin(ctx);
+export default plugin;

package/dist/src/plugin/chat-message-handler.d.ts

@@ -0,0 +1,9 @@
+type LoopCore = {
+    startLoop: (sessionID: string, prompt: string, options: {
+        maxIterations?: number;
+        completionPromise?: string;
+    }) => Promise<unknown>;
+    cancelLoop: (sessionID: string) => Promise<unknown>;
+};
+export declare function handleChatMessage(input: string, core: LoopCore, sessionID: string): Promise<void>;
+export {};

package/dist/src/plugin/chat-message-handler.js

@@ -0,0 +1,16 @@
+import { parseRalphLoopCommand } from "../commands/parse-ralph-loop-command.js";
+export async function handleChatMessage(input, core, sessionID) {
+    if (typeof input !== "string")
+        return;
+    const command = parseRalphLoopCommand(input);
+    if (!command)
+        return;
+    if (command.kind === "cancel") {
+        await core.cancelLoop(sessionID);
+        return;
+    }
+    await core.startLoop(sessionID, command.prompt, {
+        maxIterations: command.maxIterations,
+        completionPromise: command.completionPromise,
+    });
+}

package/dist/src/plugin/create-plugin.d.ts

@@ -0,0 +1,33 @@
+import { createOpenCodeHostAdapter } from "../host-adapter/opencode-host-adapter.js";
+import { createLoopCore } from "../ralph-loop/loop-core.js";
+import type { Plugin } from "@opencode-ai/plugin";
+export type CreatePluginDeps = {
+    createOpenCodeHostAdapter?: typeof createOpenCodeHostAdapter;
+    createLoopCore?: typeof createLoopCore;
+};
+type PluginInput = Parameters<Plugin>[0];
+type TextPart = {
+    type?: unknown;
+    text?: unknown;
+};
+type ChatMessageInput = {
+    sessionID?: unknown;
+    properties?: {
+        sessionID?: unknown;
+    };
+    path?: {
+        id?: unknown;
+    };
+};
+type ChatMessageOutput = {
+    parts?: Array<TextPart>;
+};
+type EventInput = {
+    event?: unknown;
+};
+export type PluginHooks = {
+    "chat.message": (input: ChatMessageInput, output: ChatMessageOutput) => Promise<void>;
+    event: (input: EventInput) => Promise<void>;
+};
+export declare function createPlugin(ctx?: PluginInput, deps?: CreatePluginDeps): Promise<PluginHooks>;
+export {};

package/dist/src/plugin/create-plugin.js

@@ -0,0 +1,52 @@
+import { createOpenCodeHostAdapter } from "../host-adapter/opencode-host-adapter.js";
+import { createLoopCore } from "../ralph-loop/loop-core.js";
+import { handleChatMessage } from "./chat-message-handler.js";
+import { handleEvent } from "./event-handler.js";
+function extractSessionID(input) {
+    if (typeof input.sessionID === "string")
+        return input.sessionID;
+    if (typeof input.properties?.sessionID === "string")
+        return input.properties.sessionID;
+    if (typeof input.path?.id === "string")
+        return input.path.id;
+    return null;
+}
+function extractChatText(parts) {
+    return (parts ?? [])
+        .filter((part) => part?.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n");
+}
+export async function createPlugin(ctx, deps = {}) {
+    if (!ctx)
+        throw new Error("plugin context is required");
+    const createAdapter = deps.createOpenCodeHostAdapter ?? createOpenCodeHostAdapter;
+    const createCore = deps.createLoopCore ?? createLoopCore;
+    const adapter = createAdapter({
+        directory: ctx.directory,
+        client: {
+            session: {
+                messages: async ({ sessionID, directory }) => ctx.client.session.messages({ path: { id: sessionID }, query: { directory } }),
+                promptAsync: ctx.client.session.promptAsync
+                    ? async ({ sessionID, directory, parts }) => ctx.client.session.promptAsync?.({ path: { id: sessionID }, body: { parts }, query: { directory } })
+                    : undefined,
+                prompt: async ({ sessionID, directory, parts }) => ctx.client.session.prompt({ path: { id: sessionID }, body: { parts }, query: { directory } }),
+                abort: async ({ sessionID }) => ctx.client.session.abort({ path: { id: sessionID } }),
+            },
+        },
+    });
+    const core = createCore({ rootDir: ctx.directory, adapter });
+    return {
+        "chat.message": async (input, output) => {
+            const sessionID = extractSessionID(input);
+            if (!sessionID)
+                return;
+            await handleChatMessage(extractChatText(output.parts), core, sessionID);
+        },
+        event: async (input) => {
+            if (!input.event)
+                return;
+            await handleEvent(input.event, core);
+        },
+    };
+}

package/dist/src/plugin/event-handler.d.ts

@@ -0,0 +1,15 @@
+type LoopEvent = {
+    type: "session.idle";
+    sessionID: string;
+} | {
+    type: "session.deleted";
+    sessionID: string;
+} | {
+    type: "session.error";
+    sessionID: string;
+};
+type LoopCore = {
+    handleEvent: (event: LoopEvent) => Promise<unknown>;
+};
+export declare function handleEvent(input: unknown, core: LoopCore): Promise<void>;
+export {};

package/dist/src/plugin/event-handler.js

@@ -0,0 +1,21 @@
+function getSessionID(input) {
+    if (input.type === "session.deleted") {
+        return typeof input.properties?.info?.id === "string" ? input.properties.info.id : null;
+    }
+    if (input.type === "session.idle" || input.type === "session.error") {
+        return typeof input.properties?.sessionID === "string" ? input.properties.sessionID : null;
+    }
+    return null;
+}
+export async function handleEvent(input, core) {
+    if (!input || typeof input !== "object")
+        return;
+    const record = input;
+    if (record.type !== "session.idle" && record.type !== "session.deleted" && record.type !== "session.error") {
+        return;
+    }
+    const sessionID = getSessionID(record);
+    if (!sessionID)
+        return;
+    await core.handleEvent({ type: record.type, sessionID });
+}

package/dist/src/ralph-loop/completion-detector.d.ts

@@ -0,0 +1,5 @@
+export type RalphLoopMessage = {
+    role: string;
+    text: string;
+};
+export declare function detectCompletion(messages: ReadonlyArray<RalphLoopMessage>, promise: string, boundary: number): boolean;

package/dist/src/ralph-loop/completion-detector.js

@@ -0,0 +1,4 @@
+export function detectCompletion(messages, promise, boundary) {
+    return messages.slice(boundary).some((message) => message.role === "assistant" &&
+        message.text.split(/\r?\n/).some((line) => line.trim() === promise));
+}

package/dist/src/ralph-loop/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_STATE_PATH = ".loop/ralph-loop.local.md";
+export declare const DEFAULT_COMPLETION_PROMISE = "<promise>DONE</promise>";

package/dist/src/ralph-loop/constants.js

@@ -0,0 +1,2 @@
+export const DEFAULT_STATE_PATH = ".loop/ralph-loop.local.md";
+export const DEFAULT_COMPLETION_PROMISE = "<promise>DONE</promise>";

package/dist/src/ralph-loop/continuation-prompt.d.ts

@@ -0,0 +1,7 @@
+export type BuildContinuationPromptInput = {
+    iteration: number;
+    prompt: string;
+    completionPromise: string;
+    maxIterations?: number;
+};
+export declare function buildContinuationPrompt(input: BuildContinuationPromptInput): string;

package/dist/src/ralph-loop/continuation-prompt.js

@@ -0,0 +1,8 @@
+export function buildContinuationPrompt(input) {
+    return [
+        `Continue Ralph Loop iteration ${input.iteration}.`,
+        ...(input.maxIterations === undefined ? [] : [`Max iterations: ${input.maxIterations}`]),
+        `Original task: ${input.prompt}`,
+        `Emit ${input.completionPromise} when complete.`,
+    ].join("\n");
+}

package/dist/src/ralph-loop/loop-core.d.ts

@@ -0,0 +1,24 @@
+import type { HostAdapter } from "../host-adapter/types.js";
+export type LoopEvent = {
+    type: "session.idle";
+    sessionID: string;
+} | {
+    type: "session.deleted";
+    sessionID: string;
+} | {
+    type: "session.error";
+    sessionID: string;
+};
+export type CreateLoopCoreDeps = {
+    rootDir: string;
+    adapter: HostAdapter;
+};
+export type StartLoopOptions = {
+    maxIterations?: number;
+    completionPromise?: string;
+};
+export declare function createLoopCore(deps: CreateLoopCoreDeps): {
+    startLoop(sessionID: string, prompt: string, options?: StartLoopOptions): Promise<void>;
+    cancelLoop(sessionID: string): Promise<void>;
+    handleEvent(event: LoopEvent): Promise<void>;
+};

package/dist/src/ralph-loop/loop-core.js

@@ -0,0 +1,122 @@
+import { DEFAULT_COMPLETION_PROMISE } from "./constants.js";
+import { buildContinuationPrompt } from "./continuation-prompt.js";
+import { detectCompletion } from "./completion-detector.js";
+import { clearState, readState, writeState } from "./state-store.js";
+import { randomUUID } from "node:crypto";
+export function createLoopCore(deps) {
+    const inFlight = new Map();
+    const getToken = (state) => state.incarnation_token ?? state.started_at;
+    return {
+        async startLoop(sessionID, prompt, options = {}) {
+            const existing = await readState(deps.rootDir);
+            if (existing?.active) {
+                const stillExists = await deps.adapter.sessionExists(existing.session_id);
+                if (stillExists) {
+                    throw new Error("an active Ralph Loop already exists; use /cancel-ralph first");
+                }
+                await clearState(deps.rootDir);
+            }
+            else if (existing) {
+                await clearState(deps.rootDir);
+            }
+            const messageCountAtStart = await deps.adapter.getMessageCount(sessionID);
+            const incarnationToken = randomUUID();
+            const state = {
+                active: true,
+                session_id: sessionID,
+                prompt,
+                iteration: 0,
+                max_iterations: options.maxIterations,
+                completion_promise: options.completionPromise ?? DEFAULT_COMPLETION_PROMISE,
+                message_count_at_start: messageCountAtStart,
+                incarnation_token: incarnationToken,
+                started_at: new Date().toISOString(),
+            };
+            await writeState(deps.rootDir, state);
+        },
+        async cancelLoop(sessionID) {
+            const state = await readState(deps.rootDir);
+            if (!state || !state.active || state.session_id !== sessionID)
+                return;
+            await deps.adapter.abortSession(sessionID);
+            await clearState(deps.rootDir);
+        },
+        async handleEvent(event) {
+            if (event.type === "session.deleted" || event.type === "session.error") {
+                const state = await readState(deps.rootDir);
+                if (state && state.active && state.session_id === event.sessionID) {
+                    await clearState(deps.rootDir);
+                }
+                return;
+            }
+            try {
+                const state = await readState(deps.rootDir);
+                if (!state || !state.active || state.session_id !== event.sessionID)
+                    return;
+                const incarnationToken = getToken(state);
+                const inFlightToken = inFlight.get(event.sessionID);
+                if (inFlightToken === incarnationToken)
+                    return;
+                inFlight.set(event.sessionID, incarnationToken);
+                const messages = await deps.adapter.getMessages(event.sessionID);
+                const batchMessageCount = messages.length;
+                const baselineMessageCount = state.last_message_count_processed ?? state.message_count_at_start;
+                if (batchMessageCount <= baselineMessageCount)
+                    return;
+                const hasNewAssistantMessages = messages
+                    .slice(baselineMessageCount)
+                    .some((message) => message.role === "assistant");
+                if (!hasNewAssistantMessages)
+                    return;
+                const liveState = await readState(deps.rootDir);
+                if (!liveState ||
+                    !liveState.active ||
+                    liveState.session_id !== event.sessionID ||
+                    getToken(liveState) !== incarnationToken) {
+                    return;
+                }
+                const currentLiveState = liveState;
+                if (detectCompletion(messages, currentLiveState.completion_promise, currentLiveState.message_count_at_start)) {
+                    await clearState(deps.rootDir);
+                    return;
+                }
+                const nextIteration = currentLiveState.iteration + 1;
+                if (typeof currentLiveState.max_iterations === "number" &&
+                    nextIteration > currentLiveState.max_iterations) {
+                    await clearState(deps.rootDir);
+                    return;
+                }
+                await deps.adapter.prompt(event.sessionID, buildContinuationPrompt({
+                    iteration: nextIteration,
+                    prompt: currentLiveState.prompt,
+                    completionPromise: currentLiveState.completion_promise,
+                    maxIterations: currentLiveState.max_iterations,
+                }));
+                const currentState = await readState(deps.rootDir);
+                if (!currentState ||
+                    !currentState.active ||
+                    currentState.session_id !== event.sessionID ||
+                    getToken(currentState) !== incarnationToken) {
+                    return;
+                }
+                const persistedState = currentState;
+                const nextState = {
+                    ...persistedState,
+                    iteration: nextIteration,
+                    last_message_count_processed: batchMessageCount,
+                };
+                await writeState(deps.rootDir, nextState);
+            }
+            finally {
+                const currentToken = inFlight.get(event.sessionID);
+                if (currentToken !== undefined) {
+                    const state = await readState(deps.rootDir);
+                    const stateToken = state?.session_id === event.sessionID && state?.active ? getToken(state) : undefined;
+                    if (currentToken === stateToken) {
+                        inFlight.delete(event.sessionID);
+                    }
+                }
+            }
+        },
+    };
+}

package/dist/src/ralph-loop/state-store.d.ts

@@ -0,0 +1,4 @@
+import type { RalphLoopState } from "./types.js";
+export declare function writeState(root: string, state: RalphLoopState): Promise<void>;
+export declare function readState(root: string): Promise<RalphLoopState | null>;
+export declare function clearState(root: string): Promise<void>;

package/dist/src/ralph-loop/state-store.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { DEFAULT_STATE_PATH } from "./constants.js";
+function getStateFilePath(root) {
+    return join(root, DEFAULT_STATE_PATH);
+}
+function isRalphLoopState(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.active === "boolean" &&
+        typeof record.session_id === "string" &&
+        typeof record.prompt === "string" &&
+        typeof record.iteration === "number" &&
+        (record.max_iterations === undefined || typeof record.max_iterations === "number") &&
+        typeof record.completion_promise === "string" &&
+        typeof record.message_count_at_start === "number" &&
+        (record.last_message_count_processed === undefined || typeof record.last_message_count_processed === "number") &&
+        (record.incarnation_token === undefined || typeof record.incarnation_token === "string") &&
+        typeof record.started_at === "string");
+}
+export async function writeState(root, state) {
+    const filePath = getStateFilePath(root);
+    const tempFilePath = `${filePath}.${randomUUID()}.tmp`;
+    await mkdir(dirname(filePath), { recursive: true });
+    try {
+        await writeFile(tempFilePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        await rename(tempFilePath, filePath);
+    }
+    catch (error) {
+        await rm(tempFilePath, { force: true });
+        throw error;
+    }
+}
+export async function readState(root) {
+    const filePath = getStateFilePath(root);
+    try {
+        const content = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        if (!isRalphLoopState(parsed)) {
+            throw new Error("invalid RalphLoopState shape");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error("invalid RalphLoopState JSON", { cause: error });
+        }
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function clearState(root) {
+    await rm(getStateFilePath(root), { force: true });
+}

package/dist/src/ralph-loop/types.d.ts

@@ -0,0 +1,12 @@
+export type RalphLoopState = {
+    active: boolean;
+    session_id: string;
+    prompt: string;
+    iteration: number;
+    max_iterations?: number;
+    completion_promise: string;
+    message_count_at_start: number;
+    last_message_count_processed?: number;
+    incarnation_token?: string;
+    started_at: string;
+};

package/dist/src/ralph-loop/types.js

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@w32191/just-loop",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "OpenCode plugin package for just-loop.",
+  "license": "MIT",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": ["dist/", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun run build && bun test",
+    "smoke:pack": "node scripts/smoke-pack.mjs",
+    "verify:publish": "npm run build && npm run test && node scripts/verify-publish.mjs",
+    "prepublishOnly": "npm run verify:publish"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.3.0"
+  },
+  "devDependencies": {
+    "bun-types": "1.3.11",
+    "typescript": "^5.7.0"
+  }
+}