@ipul-labs/forge 1.13.0

package/server/forge/core/openclawClient.js

@@ -0,0 +1,125 @@
+/**
+ * server/forge/core/openclawClient.js
+ *
+ * Communicates with a locally-running OpenClaw Gateway over HTTP.
+ * Configure with:
+ *   OPENCLAW_GATEWAY_URL  — e.g. http://192.168.x.x:18789 (Tailscale) or SSH tunnel
+ *   OPENCLAW_TOKEN        — Bearer token if your Gateway requires auth
+ *
+ * The Gateway runs on 127.0.0.1:18789 by default. Expose it remotely via:
+ *   Tailscale: bind to tailnet interface
+ *   SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host
+ */
+
+import {
+	buildIdentifyFilesPrompt,
+	buildProposeFixPrompt,
+	buildRefineOrAskPrompt,
+	buildCheckResolutionPrompt,
+} from "./prompts.js";
+
+const GATEWAY_URL = process.env.OPENCLAW_GATEWAY_URL?.replace(/\/$/, "");
+const GATEWAY_TOKEN = process.env.OPENCLAW_TOKEN;
+const TIMEOUT_MS = 120_000;
+
+// ─── JSON output helpers ──────────────────────────────────────────────────────
+
+function extractJSON(text) {
+	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+	if (fenced) return JSON.parse(fenced[1].trim());
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start !== -1 && end !== -1) return JSON.parse(text.slice(start, end + 1));
+	throw new Error("No JSON found in OpenClaw response");
+}
+
+// ─── Gateway transport ────────────────────────────────────────────────────────
+
+/**
+ * Send a prompt to the OpenClaw Gateway and return the text response.
+ *
+ * @param {string} prompt
+ * @param {string} [model]
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {Promise<string>}
+ */
+async function callGateway(prompt, model, opts = {}) {
+	if (!GATEWAY_URL) {
+		throw new Error(
+			"OPENCLAW_GATEWAY_URL is not set. Add it to your .env and point it at your OpenClaw Gateway.",
+		);
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+	// Chain the external cancel signal so a job cancel aborts the fetch in
+	// addition to the timeout.
+	const external = opts.signal;
+	const onExternalAbort = () => controller.abort();
+	if (external) {
+		if (external.aborted) controller.abort();
+		else external.addEventListener("abort", onExternalAbort, { once: true });
+	}
+
+	try {
+		const body = { message: prompt };
+		if (model) body.model = model;
+
+		const res = await fetch(`${GATEWAY_URL}/api/v1/agent`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...(GATEWAY_TOKEN ? { Authorization: `Bearer ${GATEWAY_TOKEN}` } : {}),
+			},
+			body: JSON.stringify(body),
+			signal: controller.signal,
+		});
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`OpenClaw gateway ${res.status}: ${text.slice(0, 300)}`);
+		}
+
+		const data = await res.json();
+		return data.result ?? data.message ?? data.content ?? data.text ?? JSON.stringify(data);
+	} catch (err) {
+		if (err.name === "AbortError") {
+			// External cancellation wins over "timeout" framing so the terminal
+			// event the job emits reflects the user action, not a stale timer.
+			if (external?.aborted) throw err;
+			throw new Error("OpenClaw gateway timed out after 2 minutes");
+		}
+		throw err;
+	} finally {
+		clearTimeout(timer);
+		external?.removeEventListener("abort", onExternalAbort);
+	}
+}
+
+// ─── Public API (mirrors claudeClient.js) ────────────────────────────────────
+
+export async function checkResolution(issue, diffs, model, opts = {}) {
+	const text = await callGateway(buildCheckResolutionPrompt(issue, diffs), model, opts);
+	const data = extractJSON(text);
+	return { ...data, cost: 0, serviceTier: "openclaw", inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+
+export async function identifyRelevantFiles(issue, fileTree, model, opts = {}) {
+	const text = await callGateway(buildIdentifyFilesPrompt(issue, fileTree), model, opts);
+	const data = extractJSON(text);
+	return { ...data, cost: 0, serviceTier: "openclaw", inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+
+export async function proposeFix(issue, fileContents, options = {}, model, opts = {}) {
+	const text = await callGateway(buildProposeFixPrompt(issue, fileContents, options), model, opts);
+	const data = extractJSON(text);
+	return { ...data, cost: 0, serviceTier: "openclaw", inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+
+export async function refineOrAsk(issue, fileContents, options = {}, model, _onEvent, opts = {}) {
+	// OpenClaw is a single HTTP round-trip — no streaming surface. The onEvent
+	// callback is accepted for signature parity with claudeClient and ignored.
+	const text = await callGateway(buildRefineOrAskPrompt(issue, fileContents, options), model, opts);
+	const data = extractJSON(text);
+	return { ...data, cost: 0, serviceTier: "openclaw", inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}

package/server/forge/core/prompts.js

@@ -0,0 +1,369 @@
+/**
+ * server/forge/core/prompts.js
+ *
+ * Shared prompt builders used by both claudeClient and openclawClient.
+ *
+ * Multi-repo awareness: when more than one repo is in play (full-stack fixes),
+ * every file reference carries a `repo` field so the model can target changes
+ * to the correct repository. Single-repo callers can still pass file trees /
+ * contents without a repo field — they are normalised before rendering.
+ */
+
+export const SELECT_FILES_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: {
+		files: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					repo: { type: "string", description: "Repository id, as given in the 'Available repositories' list." },
+					path: { type: "string", description: "Path from that repo's root." },
+				},
+				required: ["repo", "path"],
+			},
+			description: "Minimum set of files relevant to the fix. Maximum 10 across all repos.",
+		},
+		reasoning: {
+			type: "string",
+			description: "One or two sentences explaining why these files are relevant and, if the fix spans multiple repos, why both are needed.",
+		},
+	},
+	required: ["files", "reasoning"],
+});
+
+export const PROPOSE_FIX_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: {
+		title: {
+			type: "string",
+			description: "Conventional-commit MR title describing the actual fix, e.g. 'fix: resolve token refresh race condition in AuthService'. Max 72 chars. No issue number.",
+		},
+		explanation: {
+			type: "string",
+			description: "2-4 sentences on root cause and approach. If changes span multiple repos, describe how the pieces fit together.",
+		},
+		changes: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					repo: { type: "string", description: "Repository id this change belongs to, exactly as given in the 'Available repositories' list." },
+					file: { type: "string", description: "Path from that repo's root." },
+					action: { type: "string", enum: ["create", "modify", "delete"] },
+					proposed: { type: "string", description: "For create/modify: the COMPLETE new file content. For delete: empty string." },
+					summary: { type: "string", description: "One sentence describing this file's change." },
+				},
+				required: ["repo", "file", "action", "proposed", "summary"],
+			},
+		},
+	},
+	required: ["title", "explanation", "changes"],
+});
+
+export const REFINE_OR_ASK_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: {
+		kind: {
+			type: "string",
+			enum: ["answer", "refine"],
+			description: "\"answer\" when the user is asking about state (lint status, readiness, rationale); \"refine\" when they are directing a code change.",
+		},
+		answer: {
+			type: "string",
+			description: "User-facing response (markdown OK). Always present. For refine, summarise what you changed; for answer, directly address the question grounded in validation results and the proposed changes.",
+		},
+		changes: {
+			type: "array",
+			description: "Only present when kind=refine. Same shape as PROPOSE_FIX_SCHEMA.changes.",
+			items: {
+				type: "object",
+				properties: {
+					repo: { type: "string" },
+					file: { type: "string" },
+					action: { type: "string", enum: ["create", "modify", "delete"] },
+					proposed: { type: "string" },
+					summary: { type: "string" },
+				},
+				required: ["repo", "file", "action", "proposed", "summary"],
+			},
+		},
+		title: {
+			type: "string",
+			description: "Only when kind=refine. Updated conventional-commit MR title for the revised fix.",
+		},
+	},
+	required: ["kind", "answer"],
+});
+
+export const RESOLUTION_CHECK_SCHEMA = JSON.stringify({
+	type: "object",
+	properties: {
+		resolved: {
+			type: "boolean",
+			description: "True if the changes fully address the issue.",
+		},
+		reasoning: {
+			type: "string",
+			description: "2-3 sentences explaining why the issue is or isn't resolved.",
+		},
+	},
+	required: ["resolved", "reasoning"],
+});
+
+/**
+ * Builds a human-readable block listing each repo's file tree.
+ * Accepts either:
+ *   - a flat string[] (single-repo, legacy callers) — wrapped as one repo
+ *   - an array of { repo, files: string[] } (multi-repo)
+ */
+function renderRepoTrees(repoTrees) {
+	const normalized = Array.isArray(repoTrees) && typeof repoTrees[0] === "string"
+		? [{ repo: "repo", files: repoTrees }]
+		: repoTrees;
+
+	return normalized
+		.map(({ repo, files }) =>
+			`### ${repo} (${files.length} files)\n${files.join("\n")}`,
+		)
+		.join("\n\n");
+}
+
+/**
+ * Builds the file-contents block. Accepts either a flat array
+ * (legacy: { path, content }) or multi-repo ({ repo, path, content }).
+ */
+function renderFileContents(fileContents) {
+	return fileContents
+		.map((f) => {
+			const header = f.repo ? `${f.repo} — ${f.path}` : f.path;
+			return `### ${header}\n\`\`\`\n${f.content}\n\`\`\``;
+		})
+		.join("\n\n");
+}
+
+function renderPreviousChanges(previousChanges) {
+	return previousChanges
+		.map((c) => {
+			const header = c.repo ? `${c.repo} — ${c.file} (${c.action})` : `${c.file} (${c.action})`;
+			return `### ${header}\n${c.summary}\n\`\`\`\n${c.proposed}\n\`\`\``;
+		})
+		.join("\n\n");
+}
+
+export function buildIdentifyFilesPrompt(issue, repoTrees) {
+	const multi = Array.isArray(repoTrees) && typeof repoTrees[0] === "object";
+	const repoIds = multi
+		? repoTrees.map((r) => r.repo).join(", ")
+		: "repo";
+
+	const multiBlock = multi && repoTrees.length > 1
+		? `\n\n## Multi-repo guidance\nThese repositories are deployed together as a full-stack application. If the issue genuinely requires coordinated changes in more than one repo (e.g. a new API endpoint in the backend AND its client in the frontend), select files from each affected repo. If the fix is self-contained, pick files from only one repo.`
+		: "";
+
+	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
+
+Schema: {"files": [{"repo": "<repo id>", "path": "src/foo/bar.ts"}], "reasoning": "one or two sentences"}
+
+Identify the minimum set of source files (max 10 across all repos) relevant to fixing this issue.
+Always use an exact repo id from the "Available repositories" list below — do not invent or abbreviate.
+
+Selection rules:
+- When a bug points at a failing assertion, guard, or validation (e.g. "undefined priceId", "X is not defined", "cannot read property of undefined"), include the IMMEDIATE CALLER(S) of that function — not just the file where the error is thrown. The bad value usually originates upstream.
+- When a bug points at an event handler or React component, include the component that renders the handler AND the handler's implementation.
+- Prefer fewer files over more, but never omit a caller when the reported symptom is a downstream consequence of input received from that caller.
+
+## Issue #${issue.iid}: ${issue.title}
+${issue.description || "(no description)"}
+Labels: ${issue.labels?.join(", ") || "none"}
+
+## Available repositories
+${repoIds}${multiBlock}
+
+## Repository file trees
+${renderRepoTrees(repoTrees)}`;
+}
+
+export function buildProposeFixPrompt(issue, fileContents, options = {}) {
+	const { feedback, previousChanges, ciContext, userPrompt, repos } = options;
+
+	const filesBlock = renderFileContents(fileContents);
+
+	const previousBlock = previousChanges?.length
+		? `\n\n## Previous proposed changes\n${renderPreviousChanges(previousChanges)}`
+		: "";
+
+	const feedbackBlock = feedback?.trim()
+		? `\n\n## Reviewer feedback\n${feedback.trim()}\n\nAdjust the proposed changes to address this feedback.`
+		: "";
+
+	const ciBlock = ciContext?.trim()
+		? `\n\n## CI pipeline failure logs\nThe pipeline failed. Propose changes that fix the pipeline.\n\n${ciContext.trim()}`
+		: "";
+
+	const userBlock = userPrompt?.trim()
+		? `\n\n## Additional instructions\n${userPrompt.trim()}`
+		: "";
+
+	const reposLine = repos?.length
+		? `\n\n## Available repositories\n${repos.join(", ")}\n\nEvery "repo" field in your response MUST be one of these exact ids.`
+		: "";
+
+	const multiNote = repos && repos.length > 1
+		? `\n\n## Multi-repo guidance\nThis is a full-stack change. If the fix requires coordinated updates in more than one repo, produce changes tagged with the correct repo for each. Make sure API shapes, types, and field names agree across repos.`
+		: "";
+
+	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
+
+Schema: {"title": "fix: concise description of the actual change (max 72 chars)", "explanation": "...", "changes": [{"repo": "<repo id>", "file": "...", "action": "modify|create|delete", "proposed": "<full file content>", "summary": "..."}]}
+
+Propose a targeted fix for this issue.
+
+Root-cause discipline (read BEFORE writing any change):
+1. Identify the ORIGIN of the bad value, not just where it's observed. If a guard, assertion, or validation is failing, trace the value one or two frames up and name the caller that produced the bad input.
+2. A fix that only makes an error message clearer (e.g. replacing \`assertIsDefined(x)\` with \`if (!x) toast.error(…)\`) is NOT a fix — it is a symptom suppressor. Reject it and propose the upstream fix instead.
+3. In your "explanation", state (a) where the bad value originates, (b) why the fix closes the reported symptom end-to-end, and (c) what would have to be true for the reported error to still appear after your change.
+4. If the origin is in a file that was not selected in pass 1, your "changes" should include that file. Do not constrain yourself to only the files listed under "Relevant files" when doing so would force a symptom-level patch.
+
+## Issue #${issue.iid}: ${issue.title}
+${issue.description || "(no description)"}
+Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${multiNote}${previousBlock}${feedbackBlock}${ciBlock}${userBlock}
+
+## Relevant files
+${filesBlock}`;
+}
+
+/**
+ * Renders the latest pre-flight validation state (lint/typecheck/test) so the
+ * refine model can ground answers like "are lint issues fixed?" in real data.
+ * Omits silently when no state is available — the prompt will tell the model
+ * to say "validation hasn't been run yet" in that case.
+ */
+function renderValidationState(state) {
+	if (!state) return "";
+	const lines = [`## Latest pre-flight validation (${state.checkedAt ?? "unknown time"})`];
+	if (state.allPassed === true) lines.push("Overall: **all checks passed**");
+	else if (state.allPassed === false) lines.push("Overall: **some checks failed**");
+	const steps = state.steps ?? {};
+	for (const name of ["lint", "typecheck", "test"]) {
+		const s = steps[name];
+		if (!s) continue;
+		const status = s.skipped ? "skipped" : s.status ?? (s.passed ? "passed" : "failed");
+		const detail = s.exitCode != null ? ` (exit ${s.exitCode})` : "";
+		lines.push(`- **${name}**: ${status}${detail}`);
+		if (!s.passed && !s.skipped && s.tail) {
+			lines.push(`  Last output:\n\`\`\`\n${String(s.tail).split("\n").slice(-20).join("\n")}\n\`\`\``);
+		}
+	}
+	return "\n\n" + lines.join("\n");
+}
+
+/**
+ * Single-prompt conversational refine: the model auto-classifies the user's
+ * message as a question about state or a directive to change code, then
+ * responds with EITHER a grounded answer OR a fresh changes[] payload.
+ */
+export function buildRefineOrAskPrompt(issue, fileContents, options = {}) {
+	const { feedback, previousChanges, validationState, repos, repoTrees, repoAccessMode } = options;
+
+	const filesBlock = renderFileContents(fileContents);
+	const previousBlock = previousChanges?.length
+		? `\n\n## Proposed changes so far\n${renderPreviousChanges(previousChanges)}`
+		: "";
+	const validationBlock = renderValidationState(validationState);
+	const reposLine = repos?.length
+		? `\n\n## Available repositories\n${repos.join(", ")}\n\nEvery "repo" field in a refine response MUST be one of these exact ids.`
+		: "";
+
+	const treeBlock = repoTrees?.length
+		? `\n\n## Repository file trees\n${renderRepoTrees(repoTrees)}`
+		: "";
+
+	const accessBlock = repoAccessMode === "tools"
+		? `\n\n## Repo access\nThe current working directory is a checkout of the primary repo with the proposed changes already overlaid. Use the Read, Glob, and Grep tools to inspect any file you need before answering or refining. Do NOT claim you lack repo access.`
+		: `\n\n## Repo access\nYou have the full file tree above and the complete content of every file currently in scope. Treat these as authoritative. If you need a file not attached, name the path and ask the user to share it — do NOT claim you lack repo access.`;
+
+	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
+
+Schema: {
+  "kind": "answer" | "refine",
+  "answer": "your user-facing reply (markdown ok)",
+  "title": "fix: ...",              // refine only
+  "changes": [ { "repo": "...", "file": "...", "action": "modify|create|delete", "proposed": "<full file>", "summary": "..." } ]  // refine only
+}
+
+## How to classify
+
+Set kind="answer" when the user is asking about the current state of the work. Examples:
+- "are lint issues fixed?"
+- "is this safe to merge?"
+- "what did you change?"
+- "why this approach?"
+Ground your answer in the validation state below, the proposed changes, and any file you read from the working tree. Be direct. If validation hasn't been run, say so and recommend running it. Do NOT produce a "changes" array on this path.
+
+Set kind="refine" when the user is directing a code change. Examples:
+- "use the existing log utility"
+- "split this into two functions"
+- "handle null here"
+- "fix the typecheck error: Foo is not assignable to Bar"
+Produce a complete updated "changes" array addressing the feedback, plus an "answer" that briefly summarises what you changed (one or two sentences). Every file you modify must be a COMPLETE file in "proposed" — never a diff.
+
+If the message is ambiguous, prefer "answer" and ask a clarifying question.
+
+## Issue #${issue.iid}: ${issue.title}
+${issue.description || "(no description)"}
+Labels: ${issue.labels?.join(", ") || "none"}${reposLine}${accessBlock}${treeBlock}${previousBlock}${validationBlock}
+
+## Relevant files (current state as of the proposed changes)
+${filesBlock}
+
+## User message
+${feedback?.trim() || "(empty)"}`;
+}
+
+/**
+ * Slim continuation prompt for refine turns 2+ when the Claude session is
+ * being resumed via `--resume <id>`. The model already has the issue, repo
+ * access, prior proposed changes, and full file contents from the first
+ * turn — repeating them would waste tokens and dilute the cache hit. We only
+ * inject what's new: the user's message and the latest validation state.
+ */
+export function buildRefineResumePrompt(options = {}) {
+	const { feedback, validationState } = options;
+	const validationBlock = renderValidationState(validationState);
+	return `Continuing the same refine session. Same schema as before — respond with ONLY a raw JSON object matching { kind, answer, title?, changes? }. No prose, no code fences.
+
+If you need a file you haven't read yet, use Read / Glob / Grep against the working tree as before.${validationBlock}
+
+## User message
+${feedback?.trim() || "(empty)"}`;
+}
+
+export function buildCheckResolutionPrompt(issue, diffs) {
+	// Budget: 24K chars total for diffs, split evenly across files so small
+	// MRs (1-3 files) get enough per-file context to see route registrations,
+	// handler bodies, etc. — previously 800/file caused false negatives on
+	// any file >20 lines.
+	const TOTAL_DIFF_BUDGET = 24000;
+	const perFile = Math.max(2000, Math.floor(TOTAL_DIFF_BUDGET / diffs.length));
+	const diffBlock = diffs
+		.map((d) => {
+			const path = d.new_path !== d.old_path ? `${d.old_path} → ${d.new_path}` : d.new_path;
+			const label = d.new_file ? "created" : d.deleted_file ? "deleted" : "modified";
+			const snippet = d.diff ? d.diff.slice(0, perFile) + (d.diff.length > perFile ? "\n… (truncated)" : "") : "(binary or empty)";
+			return `### ${path} (${label})\n\`\`\`diff\n${snippet}\n\`\`\``;
+		})
+		.join("\n\n");
+
+	return `Respond with ONLY a raw JSON object — no markdown, no prose, no code fences.
+
+Schema: {"resolved": true|false, "reasoning": "2-3 sentences"}
+
+Determine whether the following code changes fully resolve the reported issue.
+
+## Issue #${issue.iid}: ${issue.title}
+${issue.description || "(no description)"}
+
+## Changes made in the merged MR
+${diffBlock}`;
+}