gnhf 0.1.39 → 0.1.41

package/README.md

@@ -97,6 +97,12 @@ npm run build
 npm link
 ```
 
+## Agent Skill
+
+The npm package includes an agent-facing skill at `skills/gnhf/SKILL.md`. Agents that support local skills can copy or reference this file to learn how to run GNHF in Hands-Off mode for bounded overnight work, or Companion mode when the outer agent should steer and review a long-running GNHF run.
+
+After installing from npm, the skill is available under the installed package directory. From a source checkout, use `skills/gnhf/SKILL.md` directly.
+
 ## How It Works
 
 ```

package/dist/cli.mjs

@@ -13524,16 +13524,15 @@ function createAcpRuntime(options) {
 	return new AcpxRuntime(options);
 }
 //#endregion
-//#region src/core/agents/acp.ts
-function buildAcpPrompt(prompt, schema) {
-	return `${prompt}
-
-## gnhf final output contract
-
-When the iteration is complete, your final assistant message must be a single JSON object that matches this JSON Schema. Return only the JSON object. Do not wrap it in Markdown fences. Do not include prose before or after the JSON.
-
-${JSON.stringify(schema, null, 2)}`;
-}
+//#region src/core/agents/json-extract.ts
+/**
+* Helpers for pulling a JSON object out of an agent's final assistant message.
+*
+* Agents are instructed to return JSON only, but several (rovodev, ACP targets)
+* sometimes prepend prose or wrap the JSON in markdown fences. These helpers
+* recover the structured payload in those cases without changing behaviour for
+* the well-formed pure-JSON path.
+*/
 function stripJsonFences(text) {
 	const trimmed = text.trim();
 	if (!trimmed.startsWith("```")) return trimmed;
@@ -13585,22 +13584,29 @@ function tryExtractBalancedObject(text, start) {
 * Look for a balanced JSON object inside `text`, preferring the rightmost one
 * (since the agent is supposed to end the message with the structured answer).
 */
-function extractLastJsonObject(text) {
+function extractLastJsonObject(text, accepts) {
 	let cursor = text.lastIndexOf("{");
 	while (cursor >= 0) {
 		const candidate = tryExtractBalancedObject(text, cursor);
-		if (candidate !== null) return candidate;
+		if (candidate !== null) {
+			if (!accepts) return candidate;
+			try {
+				if (accepts(JSON.parse(candidate))) return candidate;
+			} catch {}
+		}
 		cursor = text.lastIndexOf("{", cursor - 1);
 	}
 	return null;
 }
-function parseAgentJson(text) {
+function parseAgentJson(text, accepts) {
 	const cleaned = stripJsonFences(text);
 	if (!cleaned) return null;
 	try {
-		return JSON.parse(cleaned);
+		const parsed = JSON.parse(cleaned);
+		if (!accepts || accepts(parsed)) return parsed;
+		return null;
 	} catch {}
-	const extracted = extractLastJsonObject(cleaned);
+	const extracted = extractLastJsonObject(cleaned, accepts);
 	if (!extracted) return null;
 	try {
 		return JSON.parse(extracted);
@@ -13608,6 +13614,17 @@ function parseAgentJson(text) {
 		return null;
 	}
 }
+//#endregion
+//#region src/core/agents/acp.ts
+function buildAcpPrompt(prompt, schema) {
+	return `${prompt}
+
+## gnhf final output contract
+
+When the iteration is complete, your final assistant message must be a single JSON object that matches this JSON Schema. Return only the JSON object. Do not wrap it in Markdown fences. Do not include prose before or after the JSON.
+
+${JSON.stringify(schema, null, 2)}`;
+}
 function isAbortError$2(error) {
 	return error instanceof Error && (error.name === "AbortError" || error.message === "Agent was aborted");
 }
@@ -14476,6 +14493,29 @@ var CodexAgent = class {
 };
 //#endregion
 //#region src/core/agents/opencode.ts
+const RETRYABLE_PROVIDER_ERROR_CODES = new Set(["server_is_overloaded"]);
+const RETRYABLE_PROVIDER_ERROR_TYPES = new Set(["service_unavailable_error", "overloaded_error"]);
+function extractStreamError(event, sessionId) {
+	if (event.type === "error" && event.error) return event.error;
+	const payload = event.payload;
+	if (!payload) return null;
+	if (payload.type === "error" || payload.type === "session.error") {
+		if (payload.properties?.sessionID !== sessionId) return null;
+		return payload.error ?? payload.properties?.error ?? null;
+	}
+	return null;
+}
+function isRetryableProviderError(error) {
+	if (error.code && RETRYABLE_PROVIDER_ERROR_CODES.has(error.code)) return true;
+	if (error.type && RETRYABLE_PROVIDER_ERROR_TYPES.has(error.type)) return true;
+	return false;
+}
+function buildProviderErrorMessage(error) {
+	const detail = error.message ?? error.type ?? error.code ?? "unknown error";
+	if (error.code === "server_is_overloaded") return `OpenCode provider overloaded: ${detail}`;
+	if (isRetryableProviderError(error)) return `OpenCode provider error: ${detail}`;
+	return `OpenCode provider error: ${detail}`;
+}
 const BLANKET_PERMISSION_RULESET = [{
 	permission: "*",
 	pattern: "*",
@@ -14855,10 +14895,10 @@ var OpenCodeAgent = class {
 		};
 		const usageByMessageId = /* @__PURE__ */ new Map();
 		const textParts = /* @__PURE__ */ new Map();
-		let lastText = null;
 		let lastFinalAnswerText = null;
 		let lastUsageSignature = "0:0:0:0";
 		let structuredOutputFromSSE = null;
+		let streamErrorInfo = null;
 		const eventCounts = {};
 		let firstEventAtMs = null;
 		let lastEventAtMs = null;
@@ -15000,11 +15040,22 @@ var OpenCodeAgent = class {
 			});
 			notePhase(phase);
 			if (!trimmed) return;
-			lastText = nextText;
 			if (phase === "final_answer") lastFinalAnswerText = nextText;
 			onMessage?.(trimmed);
 		};
 		const handleEvent = (event) => {
+			const errorInfo = extractStreamError(event, sessionId);
+			if (errorInfo) {
+				streamErrorInfo = errorInfo;
+				appendDebugLog("opencode:stream:provider-error", {
+					sessionId,
+					type: errorInfo.type ?? null,
+					code: errorInfo.code ?? null,
+					message: errorInfo.message ?? null,
+					retryable: isRetryableProviderError(errorInfo)
+				});
+				return true;
+			}
 			const payload = event.payload;
 			const properties = payload?.properties;
 			if (!properties || properties.sessionID !== sessionId) return false;
@@ -15156,20 +15207,20 @@ var OpenCodeAgent = class {
 				usage
 			};
 		}
-		const outputText = toNonEmptyString(lastFinalAnswerText) ?? toNonEmptyString(lastText);
-		if (outputText === null) {
+		if (streamErrorInfo) throw new Error(buildProviderErrorMessage(streamErrorInfo));
+		const finalOutputText = toNonEmptyString(lastFinalAnswerText);
+		if (finalOutputText === null) {
 			appendDebugLog("opencode:output:missing", {
 				sessionId,
 				hasStructuredOutput: structuredOutputFromSSE !== null
 			});
-			throw new Error("opencode returned no text output");
+			throw new Error("OpenCode produced no final answer");
 		}
-		const finalOutputText = outputText;
 		try {
 			const output = JSON.parse(finalOutputText);
 			appendDebugLog("opencode:output:structured", {
 				sessionId,
-				source: lastFinalAnswerText ? "final_answer" : "last_text",
+				source: "final_answer",
 				outputTextLength: finalOutputText.length
 			});
 			return {
@@ -15565,6 +15616,7 @@ function buildSystemPrompt(schema) {
 		"When you finish, reply with only valid JSON.",
 		"Do not wrap the JSON in markdown fences.",
 		"Do not include any prose before or after the JSON.",
+		"Your final assistant message must contain the JSON object only - no preamble, no commentary, no build-status lines, nothing else.",
 		`The JSON must match this schema exactly: ${schema}`
 	].join(" ");
 }
@@ -16053,25 +16105,47 @@ var RovoDevAgent = class {
 			appendDebugLog("rovodev:output:missing", { sessionId });
 			throw new Error("rovodev returned no text output");
 		}
-		try {
-			const output = JSON.parse(finalText);
-			appendDebugLog("rovodev:output:parsed", {
-				sessionId,
-				outputTextLength: finalText.length
-			});
-			return {
-				output,
-				usage
-			};
-		} catch (error) {
+		const schema = JSON.parse(readFileSync(this.schemaPath, "utf-8"));
+		const parsed = parseAgentJson(finalText, (value) => {
+			try {
+				validateAgentOutput(value, schema);
+				return true;
+			} catch {
+				return false;
+			}
+		});
+		if (parsed === null) {
+			const fallbackParsed = parseAgentJson(finalText);
+			if (fallbackParsed !== null) try {
+				validateAgentOutput(fallbackParsed, schema);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				throw new Error(`Failed to parse rovodev output: ${message}`);
+			}
+			const parseError = /* @__PURE__ */ new SyntaxError("rovodev output did not contain a parseable JSON object");
 			appendDebugLog("rovodev:output:parse-error", {
 				sessionId,
 				outputTextLength: finalText.length,
 				outputTextSample: finalText.slice(0, 512),
-				error: serializeError(error)
+				error: serializeError(parseError)
 			});
-			throw new Error(`Failed to parse rovodev output: ${error instanceof Error ? error.message : String(error)}`);
+			throw new Error(`Failed to parse rovodev output: ${parseError.message}`);
 		}
+		appendDebugLog("rovodev:output:parsed", {
+			sessionId,
+			outputTextLength: finalText.length
+		});
+		let output;
+		try {
+			output = validateAgentOutput(parsed, schema);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`Failed to parse rovodev output: ${message}`);
+		}
+		return {
+			output,
+			usage
+		};
 	}
 	async shutdownServer() {
 		if (!this.server || this.server.closed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnhf",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Before I go to bed, I tell my agents: good night, have fun",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "LICENSE",
     "README.md"
   ],

package/skills/gnhf/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: gnhf
+description: Use when the user asks to run GNHF, says they are going to sleep or leaving and wants an agent-managed coding run, asks to supervise, steer, or review an active GNHF run, or gives feedback on GNHF results.
+---
+
+# GNHF
+
+## Overview
+
+GNHF is an agent orchestrator: it repeatedly calls another coding agent until a natural-language stop condition is met. This skill teaches the host agent to prepare one durable run and, in Companion mode, steer or review it.
+
+Core rule: the host agent orchestrates; GNHF executes. Do not manually implement inside the same scope while a GNHF worker is responsible for it unless the user explicitly changes the delegation.
+
+In Companion mode, GNHF completion is not user acceptance. "Stop condition met" only means the worker stopped; the host still compares the result to the user's latest requirements and fresh verification.
+
+## Modes
+
+Choose exactly one mode for the run.
+
+### Hands-Off
+
+Use when the task is bounded, verification is clear, and the user wants one configured run to proceed without steering.
+
+- Prepare a precise prompt with constraints, non-goals, verification, and stop condition.
+- Launch GNHF and wait for completion.
+- Intervene early only for hard failure, runaway scope, destructive behavior, or impossible prerequisites.
+- Report the final GNHF status after exit.
+
+Examples:
+
+- English: "I'm going to bed. Use GNHF with Copilot to keep working on this branch and stop when the test suite passes."
+- Chinese: "我要睡了。用 GNHF 接着跑这个分支，测试都过了就停。"
+
+### Companion
+
+Use when the task is uncertain, exploratory, design-heavy, research-heavy, or likely to need course correction.
+
+Default to Companion when the user asks to iterate until satisfied, requests multi-round work, provides review findings, asks for design/skill/documentation improvement, or asks for supervision.
+
+- Keep a note of original intent, branch, session id, and last known result.
+- Poll the active GNHF process until exit or until an intervention point appears.
+- Intervene when the worker optimizes the wrong thing, repeats failed fixes, skips requested research, drifts scope, or claims success without evidence.
+- Treat review findings as the next acceptance criteria.
+- Prefer a new bounded GNHF prompt over manually taking over implementation.
+
+Examples:
+
+- English: "Run GNHF for a few rounds on this onboarding flow. Check the diff between rounds and tighten the next prompt if it starts polishing the wrong thing."
+- Chinese: "用 GNHF 多跑几轮这个 onboarding 流程。每轮看一下 diff，如果它开始改偏了，就收窄下一轮 prompt。"
+
+## Launch
+
+Check the installed CLI before relying on flags:
+
+```bash
+gnhf --help
+```
+
+Known shape:
+
+```bash
+gnhf \
+  --agent <claude|codex|rovodev|opencode|copilot|pi|acp:<target>> \
+  --max-iterations <n> \
+  --stop-when "<observable completion condition>" \
+  --prevent-sleep on \
+  "<worker prompt>"
+```
+
+If GNHF has no `--model` flag, put model requirements in the worker prompt or backend config. Do not invent unsupported flags.
+
+Before launch:
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline --max-count=5
+```
+
+Prompt skeleton:
+
+```text
+Objective: <one concrete outcome>.
+
+Use <agent/model requirement>. Work in this repo. Treat this as a long-running GNHF task.
+
+Before coding, inspect the current repo, relevant docs, and recent commits. Preserve user changes. Do not make unrelated refactors.
+
+After each meaningful slice, run relevant verification. If blocked, commit no fake success; leave notes with the blocker and evidence.
+
+Stop only when: <observable completion condition>.
+```
+
+## Steer
+
+In Companion mode, evaluate after each iteration or meaningful output chunk:
+
+| Signal                                                        | Action                                                               |
+| ------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Worker found a real blocker                                   | Stop or relaunch with blocker-specific instructions                  |
+| Good partial slice                                            | Let it continue or tighten the next stop condition                   |
+| Skipped requested research                                    | Relaunch with research as explicit first deliverable                 |
+| Worker changes unrelated files                                | Stop and review before continuing                                    |
+| Worker claims success without verification                    | Review immediately; relaunch only with evidence-based stop condition |
+| Reviewer finds a blocking issue or user says not satisfactory | Relaunch with that finding as the sole bounded correction            |
+
+Steering prompt:
+
+```text
+Continue from the current repo state. The previous run partially succeeded: <evidence>.
+
+Do not redo completed work. Focus only on <bounded correction>.
+
+The issue to fix now is <specific observed issue>. Verify with <commands/checks>.
+
+Stop only when <observable condition>.
+```
+
+## Companion Review
+
+Use only in Companion mode, when the host is supervising quality or deciding whether to continue with another bounded run.
+
+1. Inspect branch, status, commits, changed files, and diff.
+2. Read GNHF notes/logs as claims, not evidence.
+3. Run independent verification: tests, lint, build, typecheck, manual QA, or domain-specific checks.
+4. Compare the result to the stop condition and the user's latest feedback.
+5. Decide: **Mergeable**, **Needs follow-up GNHF run**, or **Do not merge**.
+
+If the result needs follow-up, continue in Companion mode instead of presenting the run as complete. Do not merge unless explicitly authorized.
+
+## Findings
+
+Use when the user provides findings such as "not preserved", "scope drift", "missing requirement", or "why did you stop".
+
+1. Treat the run as Companion mode.
+2. Convert each finding into an observable correction. Preserve severity, file/line scope, and the user's wording.
+3. Relaunch on the same candidate branch when salvageable.
+4. Prompt the worker to fix only the bounded finding, preserve completed valid work, verify, and stop only when the finding is no longer true.
+5. Review again after the follow-up.
+6. Repeat until no blocking findings remain, verification passes, or a real blocker is found.
+
+## Morning Review
+
+Use when the user returns with "good morning", "how did last night's run go?", or similar after a GNHF run.
+
+Do not ask what to review first. Reconstruct state:
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline --decorate --max-count=20
+pgrep -fl 'gnhf|claude|codex|copilot|opencode|rovodev' || true
+```
+
+Inspect likely GNHF branches, notes, logs, terminal sessions, and changed files. If a GNHF process is still running, report that first.
+
+Report mode, agent, branch, status, changes, verification, stop-condition result, quality assessment, and recommended next action. Never summarize an overnight run from memory.
+
+## Agent
+
+- `copilot`: explicit GitHub Copilot CLI request or local Copilot config.
+- `codex`: repo-aware code work or review-heavy tasks.
+- `claude`: reasoning-heavy implementation or prose-heavy planning when configured.
+- `pi`: explicit Pi request or local Pi configuration.
+- `opencode` / `rovodev`: explicit request or repo-specific setup.
+- `acp:<target>`: explicit ACP target request, or when the user wants to drive a custom ACP-compatible agent through GNHF.
+
+## Safety
+
+- Preserve user changes. Never run destructive git commands to clean up a GNHF branch.
+- In Companion mode, do not trust a worker's success summary without fresh verification.
+- Keep prompts outcome-based and evidence-based.
+- Use concrete stop conditions. Bad: "looks good". Good: "the target workflow succeeds, relevant checks pass, and no unrelated files changed."
+- If the user is away, produce branches and a status report, not irreversible changes, unless explicitly authorized.