@aryaminus/controlkeel-opencode 0.2.45 → 0.2.47

package/.opencode/commands/controlkeel-submit-plan.md

@@ -10,7 +10,7 @@ Recommended flow:
 3. Run `controlkeel review plan submit --body-file .opencode/review-plan.md --submitted-by opencode --task-id <task_id> --json` (or use `--session-id <session_id>`)
 4. Read the returned `review.id` and `browser_url`
 5. If `browser_url` is available, wait with `controlkeel review plan wait --id <review_id> --timeout 30 --json`
-6. If `browser_url` is missing/unreachable **or** wait times out while still `pending`, do **not** loop on wait; ask for explicit user approval in chat and record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes "User approved in chat; browser unavailable or timed out" --json` (or `ck_review_feedback`)
+6. If `browser_url` is missing/unreachable, the browser does not actually open, **or** wait times out while still `pending`, do **not** loop on wait; ask for explicit user approval in chat and record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes "User approved in chat; browser unavailable or timed out" --json` (or `ck_review_feedback`)
 7. Do not execute until the review is approved
 
 Fallback when the `submit_plan` tool is stale in a long-running OpenCode session:

package/.opencode/plugins/controlkeel-governance.ts

@@ -343,29 +343,45 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         submitPayload?.review?.browser_url ??
         null
 
+      const buildPlanResult = (overrides = {}) => ({
+        reviewId,
+        browserUrl: overrides.browserUrl ?? browserUrl,
+        status: overrides.status ?? submitPayload?.review?.status ?? "pending",
+        feedbackNotes:
+          overrides.feedbackNotes ?? submitPayload?.review?.feedback_notes ?? null,
+        opened: overrides.opened ?? (openPayload?.opened === true),
+        timedOut: overrides.timedOut ?? false,
+        waitSkipped: overrides.waitSkipped ?? false,
+        manualApprovalRequired: overrides.manualApprovalRequired ?? false,
+        reason: overrides.reason ?? null,
+        guidance: overrides.guidance ?? null,
+      })
+
       const openError = typeof openPayload?.open_error === "string" ? openPayload.open_error.trim() : ""
       const openFailure = typeof openPayload?.error === "string" ? openPayload.error.trim() : ""
+      const browserNotOpened = openPayload?.opened !== true
+      const serverUnavailable = openPayload?.server_serving === false
 
       const remoteLocalhostMismatch =
         typeof browserUrl === "string" &&
         browserUrl.includes("localhost") &&
         openPayload?.remote === true
 
-      if (!browserUrl || openError || openFailure || remoteLocalhostMismatch) {
-        return {
-          reviewId,
-          submitPayload,
-          openPayload,
-          browserUrl,
-          status: submitPayload?.review?.status ?? "pending",
-          feedbackNotes: submitPayload?.review?.feedback_notes ?? null,
-          timedOut: false,
+      if (!browserUrl || serverUnavailable || openError || openFailure || remoteLocalhostMismatch || browserNotOpened) {
+        return buildPlanResult({
           waitSkipped: true,
           manualApprovalRequired: true,
-          reason: !browserUrl ? "browser_url_unavailable" : "browser_unreachable",
+          reason:
+            !browserUrl
+              ? "browser_url_unavailable"
+              : serverUnavailable
+                ? "review_server_unavailable"
+                : browserNotOpened
+                  ? "browser_not_opened"
+                  : "browser_unreachable",
           guidance:
-            "Browser review is unavailable from this environment. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser unavailable\" --json` or `ck_review_feedback`.",
-        }
+            "Browser review is unavailable, the CK review server is not reachable, or the browser did not actually open. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser/review server unavailable\" --json` or `ck_review_feedback`.",
+        })
       }
 
       const waitEnv = process.env.LOGGER_LEVEL
@@ -388,10 +404,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
 
       if (waitExit !== 0) {
         if (waitTimedOut && waitPending) {
-          return {
-            reviewId,
-            submitPayload,
-            waitPayload,
+          return buildPlanResult({
             browserUrl: waitPayload?.browser_url ?? submitPayload?.browser_url,
             status: "pending",
             feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
@@ -401,7 +414,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
             reason: "review_timeout",
             guidance:
               "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
-          }
+          })
         }
 
         throw new Error(
@@ -409,17 +422,13 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
         )
       }
 
-      return {
-        reviewId,
-        submitPayload,
-        openPayload,
-        waitPayload,
+      return buildPlanResult({
         browserUrl: waitPayload?.browser_url ?? browserUrl,
         status: waitPayload?.review?.status,
         feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
         waitSkipped: false,
         manualApprovalRequired: false,
-      }
+      })
     } finally {
       // Clean up temp file
       try { await Bun.file(tmpFile).unlink?.() ?? (await $`rm -f ${tmpFile}`.quiet()) } catch {}
@@ -479,7 +488,7 @@ export const ControlKeelGovernance: Plugin = async ({ project, client, $, direct
             args.task_id,
             args.session_id
           )
-          return JSON.stringify(result, null, 2)
+          return JSON.stringify(result)
         },
       }),
     },

package/AGENTS.md

@@ -11,8 +11,9 @@ Required workflow:
 2. Call `ck_validate` before writing code, config, shell, or deploy content.
 3. Submit plans or approval packets with `ck_review_submit` and check `ck_review_status` before execution.
 4. Record any human-review issue with `ck_finding`.
-5. Check `ck_budget` before expensive model or multi-agent work.
-6. Use `ck_route`, `ck_skill_list`, and `ck_skill_load` to delegate or activate specialized CK workflows.
+5. Check `ck_budget` before expensive model or multi-agent work, and keep `ck_context` compact unless full raw context is needed.
+6. Before AFK or delegated implementation, split large work into human-approved vertical slices with explicit dependencies; prefer durable behavior-first issues, stable deep-module interfaces, and branch-level automated review plus human QA before merge.
+7. Use `ck_route`, `ck_skill_list`, and `ck_skill_load` to delegate or activate specialized CK workflows.
 
 Install ControlKeel:
 - Homebrew: `brew tap aryaminus/controlkeel && brew install controlkeel`

package/index.js

@@ -326,29 +326,45 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         submitPayload?.review?.browser_url ??
         null
 
+      const buildPlanResult = (overrides = {}) => ({
+        reviewId,
+        browserUrl: overrides.browserUrl ?? browserUrl,
+        status: overrides.status ?? submitPayload?.review?.status ?? "pending",
+        feedbackNotes:
+          overrides.feedbackNotes ?? submitPayload?.review?.feedback_notes ?? null,
+        opened: overrides.opened ?? (openPayload?.opened === true),
+        timedOut: overrides.timedOut ?? false,
+        waitSkipped: overrides.waitSkipped ?? false,
+        manualApprovalRequired: overrides.manualApprovalRequired ?? false,
+        reason: overrides.reason ?? null,
+        guidance: overrides.guidance ?? null,
+      })
+
       const openError = typeof openPayload?.open_error === "string" ? openPayload.open_error.trim() : ""
       const openFailure = typeof openPayload?.error === "string" ? openPayload.error.trim() : ""
+      const browserNotOpened = openPayload?.opened !== true
+      const serverUnavailable = openPayload?.server_serving === false
 
       const remoteLocalhostMismatch =
         typeof browserUrl === "string" &&
         browserUrl.includes("localhost") &&
         openPayload?.remote === true
 
-      if (!browserUrl || openError || openFailure || remoteLocalhostMismatch) {
-        return {
-          reviewId,
-          submitPayload,
-          openPayload,
-          browserUrl,
-          status: submitPayload?.review?.status ?? "pending",
-          feedbackNotes: submitPayload?.review?.feedback_notes ?? null,
-          timedOut: false,
+      if (!browserUrl || serverUnavailable || openError || openFailure || remoteLocalhostMismatch || browserNotOpened) {
+        return buildPlanResult({
           waitSkipped: true,
           manualApprovalRequired: true,
-          reason: !browserUrl ? "browser_url_unavailable" : "browser_unreachable",
+          reason:
+            !browserUrl
+              ? "browser_url_unavailable"
+              : serverUnavailable
+                ? "review_server_unavailable"
+                : browserNotOpened
+                  ? "browser_not_opened"
+                  : "browser_unreachable",
           guidance:
-            "Browser review is unavailable from this environment. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser unavailable\" --json` or `ck_review_feedback`.",
-        }
+            "Browser review is unavailable, the CK review server is not reachable, or the browser did not actually open. Ask the user for explicit approval in chat, then record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat; browser/review server unavailable\" --json` or `ck_review_feedback`.",
+        })
       }
 
       const waitEnv = process.env.LOGGER_LEVEL
@@ -371,10 +387,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
 
       if (waitExit !== 0) {
         if (waitTimedOut && waitPending) {
-          return {
-            reviewId,
-            submitPayload,
-            waitPayload,
+          return buildPlanResult({
             browserUrl: waitPayload?.browser_url ?? submitPayload?.browser_url,
             status: "pending",
             feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
@@ -384,7 +397,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
             reason: "review_timeout",
             guidance:
               "Plan review is still pending after timeout. Show the `browser_url` to the user if reachable. If browser review is unavailable or the user explicitly approves in chat, record it with `controlkeel review plan respond --id <review_id> --decision approved --feedback-notes \"User approved in chat after timeout/browser issue\" --json` (or `ck_review_feedback`) before proceeding.",
-          }
+          })
         }
 
         throw new Error(
@@ -392,17 +405,13 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
         )
       }
 
-      return {
-        reviewId,
-        submitPayload,
-        openPayload,
-        waitPayload,
+      return buildPlanResult({
         browserUrl: waitPayload?.browser_url ?? browserUrl,
         status: waitPayload?.review?.status,
         feedbackNotes: waitPayload?.review?.feedback_notes ?? null,
         waitSkipped: false,
         manualApprovalRequired: false,
-      }
+      })
     } finally {
       // Clean up temp file
       try { await Bun.file(tmpFile).unlink?.() ?? (await $`rm -f ${tmpFile}`.quiet()) } catch {}
@@ -462,7 +471,7 @@ export const ControlKeelGovernance = async ({ $, directory }) => {
             args.task_id,
             args.session_id
           )
-          return JSON.stringify(result, null, 2)
+          return JSON.stringify(result)
         },
       }),
     },

package/package.json

@@ -35,5 +35,5 @@
     "url": "git+https://github.com/aryaminus/controlkeel.git"
   },
   "type": "module",
-  "version": "0.2.45"
+  "version": "0.2.47"
 }