@hiai-gg/hiai-opencode 0.1.8 → 0.1.9

package/README.md

@@ -1,6 +1,6 @@
 # hiai-opencode
 
-[![CI](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml/badge.svg)](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml)
+[![CI](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml?query=branch%3Amain)
 
 `hiai-opencode` is an OpenCode plugin that turns vanilla OpenCode into an opinionated multi-agent cockpit.
 
@@ -98,6 +98,29 @@ MCP integrations and which agents use them:
 - MCP wiring for `playwright`, `stitch`, `sequential-thinking`, `firecrawl`, `rag`, `mempalace`, `context7`, plus remote `websearch` and `grep_app`
 - LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint
 
+## Continuation, Ralph-Loop, And Auto-Start
+
+The plugin runs three layered mechanisms so a session does not give up halfway through a TODO list.
+
+| Mechanism | Trigger | What it does |
+|-----------|---------|--------------|
+| **Todo continuation enforcer** | `session.idle` while open todos remain | Injects a continuation prompt after a 2s countdown. Backs off on stagnation, abort, token-limit, and pending-question. |
+| **Ralph-loop** | `/ralph-loop <goal>` or `/ulw-loop <goal>` | Runs an explicit completion loop. Stops on `<promise>DONE</promise>`. Cancel with `/cancel-ralph`. |
+| **Auto ralph-loop** | N+ open todos in one session | Auto-starts ralph-loop in ULTRAWORK mode so each iteration is forced to delegate to specialist agents (researcher / strategist / coder / critic). |
+
+Tune the auto-start threshold in `hiai-opencode.json`:
+
+```json
+{
+  "ralph_loop": {
+    "enabled": true,
+    "auto_start_threshold": 5
+  }
+}
+```
+
+`auto_start_threshold: 0` disables auto-start. The enforcer always yields to ralph-loop while it owns the session, so the two never inject duplicate prompts.
+
 ## Requirements
 
 Minimum:
@@ -493,6 +516,50 @@ On some Windows/OpenCode environments, local MCP process spawning can fail with
 
 This most often affects `sequential-thinking` and `mempalace`, and sometimes local `npx`-backed tools.
 
+## Troubleshooting MCP Servers
+
+### Firecrawl tools return "FIRECRAWL_API_KEY missing"
+
+The `skill_mcp` env scrubber filters `process.env` before launching stdio MCP servers — secret-shaped names (`*_API_KEY`, `*_TOKEN`, etc.) and npm/pnpm config vars are stripped so they cannot leak into a malicious server. Keys you set via `hiai-opencode.json` are an explicit allowlist and pass through.
+
+If your key only lives in `process.env`, move it into the MCP `environment` block:
+
+```json
+{
+  "mcp": {
+    "firecrawl": {
+      "enabled": true,
+      "environment": { "FIRECRAWL_API_KEY": "fc-..." }
+    }
+  }
+}
+```
+
+(Versions ≤ 0.1.8 had a bug where customEnv was merged before filtering, so even an explicit `FIRECRAWL_API_KEY` got stripped. Fixed in 0.1.9 — explicit `environment` always wins over the filter.)
+
+### Playwright MCP fails to find Chromium
+
+When `@playwright/mcp` cannot locate a system browser, point it at one explicitly:
+
+```json
+{
+  "mcp": {
+    "playwright": {
+      "enabled": true,
+      "environment": {
+        "PLAYWRIGHT_MCP_EXECUTABLE_PATH": "/usr/bin/chromium"
+      }
+    }
+  }
+}
+```
+
+The path can be Chromium, Chrome, or Edge. Run `npx playwright install chromium` first if no browser is installed.
+
+### `skill_mcp(playwright)` connects to localhost:3001 and fails
+
+If `mcp__playwright__browser_*` works but `skill_mcp(mcp_name="playwright", ...)` errors with a connection to `localhost:3001/mcp`, you have a leftover HTTP-mode MCP registration in your global or parent `opencode.json`. Either start the HTTP server, or remove that registration so the plugin's stdio registration (`npx @playwright/mcp@latest`) is the only one. As a workaround, agents (Vision, Critic) can call `mcp__playwright__browser_*` direct tools instead of going through `skill_mcp`.
+
 ## Diagnostics
 
 The plugin now emits startup warnings for common misconfiguration, including:

package/dist/config/schema/oh-my-opencode-config.d.ts

@@ -4177,6 +4177,8 @@ export declare const HiaiOpenCodeConfigSchema: z.ZodObject<{
             reset: "reset";
             continue: "continue";
         }>>;
+        auto_start_threshold: z.ZodDefault<z.ZodNumber>;
+        auto_start_with_strategist: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     runtime_fallback: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;

package/dist/config/schema/ralph-loop.d.ts

@@ -7,5 +7,7 @@ export declare const RalphLoopConfigSchema: z.ZodObject<{
         reset: "reset";
         continue: "continue";
     }>>;
+    auto_start_threshold: z.ZodDefault<z.ZodNumber>;
+    auto_start_with_strategist: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RalphLoopConfig = z.infer<typeof RalphLoopConfigSchema>;

package/dist/hooks/todo-continuation-enforcer/auto-loop.d.ts

@@ -0,0 +1,23 @@
+import type { Todo } from "./types";
+export type AutoLoopDecision = {
+    kind: "skip";
+    reason: string;
+} | {
+    kind: "start";
+    openTodos: number;
+    goal: string;
+};
+export type AutoLoopInputs = {
+    threshold: number | undefined;
+    todos: Todo[];
+    alreadyStarted: boolean;
+    hasStartCallback: boolean;
+};
+/**
+ * Pure decision: should the enforcer auto-start ralph-loop right now?
+ * Kept separate so it can be unit-tested without mocking the full plugin
+ * context. The caller is responsible for actually invoking startRalphLoop
+ * and updating session state.
+ */
+export declare function decideAutoLoop(input: AutoLoopInputs): AutoLoopDecision;
+export declare function buildAutoLoopGoal(openTodos: number): string;

package/dist/hooks/todo-continuation-enforcer/handler.d.ts

@@ -7,6 +7,11 @@ export declare function createTodoContinuationHandler(args: {
     backgroundManager?: BackgroundManager;
     skipAgents?: string[];
     isContinuationStopped?: (sessionID: string) => boolean;
+    autoLoopThreshold?: number;
+    startRalphLoop?: (sessionID: string, prompt: string, options?: {
+        ultrawork?: boolean;
+    }) => boolean;
+    isRalphLoopActive?: (sessionID: string) => boolean;
 }): (input: {
     event: {
         type: string;

package/dist/hooks/todo-continuation-enforcer/idle-event.d.ts

@@ -8,4 +8,9 @@ export declare function handleSessionIdle(args: {
     backgroundManager?: BackgroundManager;
     skipAgents?: string[];
     isContinuationStopped?: (sessionID: string) => boolean;
+    autoLoopThreshold?: number;
+    startRalphLoop?: (sessionID: string, prompt: string, options?: {
+        ultrawork?: boolean;
+    }) => boolean;
+    isRalphLoopActive?: (sessionID: string) => boolean;
 }): Promise<void>;

package/dist/hooks/todo-continuation-enforcer/types.d.ts

@@ -4,6 +4,23 @@ export interface TodoContinuationEnforcerOptions {
     backgroundManager?: BackgroundManager;
     skipAgents?: string[];
     isContinuationStopped?: (sessionID: string) => boolean;
+    /**
+     * If set to N >= 1, the enforcer will auto-start ralph-loop on a session that
+     * has N or more open todos and no active loop. 0/undefined disables.
+     */
+    autoLoopThreshold?: number;
+    /**
+     * Lazy callback to start ralph-loop. Lazy because ralph-loop is created
+     * after the enforcer in the plugin wiring.
+     */
+    startRalphLoop?: (sessionID: string, prompt: string, options?: {
+        ultrawork?: boolean;
+    }) => boolean;
+    /**
+     * Lazy callback returning true if ralph-loop is currently active for the
+     * session. Used to avoid double-injection.
+     */
+    isRalphLoopActive?: (sessionID: string) => boolean;
 }
 export interface TodoContinuationEnforcer {
     handler: (input: {
@@ -40,6 +57,7 @@ export interface SessionState {
     recentCompactionAt?: number;
     recentCompactionEpoch?: number;
     acknowledgedCompactionEpoch?: number;
+    autoLoopStarted?: boolean;
 }
 export interface MessageInfo {
     id?: string;