opencode-planpilot 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-planpilot",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Planpilot plugin for OpenCode",
   "type": "module",
   "repository": {

package/src/command.ts

@@ -13,6 +13,7 @@ import {
 import { AppError, invalidInput } from "./lib/errors"
 import { ensureNonEmpty, projectMatchesPath, resolveMaybeRealpath } from "./lib/util"
 import { formatGoalDetail, formatPlanDetail, formatPlanMarkdown, formatStepDetail } from "./lib/format"
+import { PLANPILOT_HELP_TEXT } from "./prompt"
 
 const DEFAULT_PAGE = 1
 const DEFAULT_LIMIT = 20
@@ -72,6 +73,14 @@ export async function runCommand(argv: string[], context: CommandContext, io: Co
     let shouldSync = false
 
     switch (section) {
+      case "help": {
+        if (subcommand !== undefined || args.length) {
+          const rest = [subcommand, ...args].filter((x) => x !== undefined)
+          throw invalidInput(`help unexpected argument: ${rest.join(" ")}`)
+        }
+        log(PLANPILOT_HELP_TEXT)
+        return
+      }
       case "plan": {
         const result = await handlePlan(app, subcommand, args, { cwd: context.cwd })
         planIds = result.planIds
@@ -234,6 +243,11 @@ function handlePlanAddTree(app: PlanpilotApp, args: string[]): number[] {
   log(`Created plan ID: ${result.plan.id}: ${result.plan.title} (steps: ${result.stepCount}, goals: ${result.goalCount})`)
   app.setActivePlan(result.plan.id, false)
   log(`Active plan set to ${result.plan.id}: ${result.plan.title}`)
+
+  // Print full detail so the AI can reference plan/step/goal IDs immediately.
+  const detail = app.getPlanDetail(result.plan.id)
+  log("")
+  log(formatPlanDetail(detail.plan, detail.steps, detail.goals))
   return [result.plan.id]
 }
 
@@ -1464,4 +1478,3 @@ function syncPlanMarkdown(app: PlanpilotApp, planIds: number[]) {
     fs.writeFileSync(mdPath, markdown, "utf8")
   })
 }
-

package/src/index.ts

@@ -5,62 +5,14 @@ import { openDatabase } from "./lib/db"
 import { invalidInput } from "./lib/errors"
 import { formatStepDetail } from "./lib/format"
 import { parseWaitFromComment } from "./lib/util"
-
-const PLANPILOT_TOOL_DESCRIPTION = [
-  "Planpilot planner for plan workflows.",
-  "Hints: 1. Model is plan/step/goal with ai/human executors and status auto-propagation upward (goals -> steps -> plan). 2. Keep comments short and decision-focused. 3. Add human steps only when AI cannot act. 4. Use `step wait` when ending a reply while waiting on external tasks.",
-  "",
-  "Usage:",
-  "- argv is tokenized: [section, subcommand, ...args]",
-  "- section: plan | step | goal",
-  "",
-  "Plan commands:",
-  "- plan add <title> <content>",
-  "- plan add-tree <title> <content> --step <content> [--executor ai|human] [--goal <content>]... [--step ...]...",
-  "- plan list [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
-  "- plan count [--scope project|all] [--status todo|done|all]",
-  "- plan search --search <term> [--search <term> ...] [--search-mode any|all] [--search-field plan|title|content|comment|steps|goals|all] [--match-case] [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
-  "- plan show <id>",
-  "- plan export <id> <path>",
-  "- plan comment <id> <comment> [<id> <comment> ...]",
-  "- plan update <id> [--title <title>] [--content <content>] [--status todo|done] [--comment <comment>]",
-  "- plan done <id>",
-  "- plan remove <id>",
-  "- plan activate <id> [--force]",
-  "- plan show-active",
-  "- plan deactivate",
-  "",
-  "Step commands:",
-  "- step add <plan_id> <content...> [--executor ai|human] [--at <pos>]",
-  "- step add-tree <plan_id> <content> [--executor ai|human] [--goal <content> ...]",
-  "- step list <plan_id> [--status todo|done|all] [--executor ai|human] [--limit N] [--page N]",
-  "- step count <plan_id> [--status todo|done|all] [--executor ai|human]",
-  "- step show <id>",
-  "- step show-next",
-  "- step wait <id> --delay <ms> [--reason <text>]",
-  "- step wait <id> --clear",
-  "- step comment <id> <comment> [<id> <comment> ...]",
-  "- step update <id> [--content <content>] [--status todo|done] [--executor ai|human] [--comment <comment>]",
-  "- step done <id> [--all-goals]",
-  "- step move <id> --to <pos>",
-  "- step remove <id...>",
-  "",
-  "Goal commands:",
-  "- goal add <step_id> <content...>",
-  "- goal list <step_id> [--status todo|done|all] [--limit N] [--page N]",
-  "- goal count <step_id> [--status todo|done|all]",
-  "- goal show <id>",
-  "- goal comment <id> <comment> [<id> <comment> ...]",
-  "- goal update <id> [--content <content>] [--status todo|done] [--comment <comment>]",
-  "- goal done <id...>",
-  "- goal remove <id...>",
-].join("\n")
+import { PLANPILOT_SYSTEM_INJECTION, PLANPILOT_TOOL_DESCRIPTION, formatPlanpilotAutoContinueMessage } from "./prompt"
 
 export const PlanpilotPlugin: Plugin = async (ctx) => {
   const inFlight = new Set<string>()
   const skipNextAuto = new Set<string>()
   const lastIdleAt = new Map<string, number>()
   const waitTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  const runSeq = new Map<string, number>()
 
   const clearWaitTimer = (sessionID: string) => {
     const existing = waitTimers.get(sessionID)
@@ -85,6 +37,16 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
     }
   }
 
+  const logDebug = async (message: string, extra?: Record<string, any>) => {
+    await log("debug", message, extra)
+  }
+
+  const nextRun = (sessionID: string) => {
+    const next = (runSeq.get(sessionID) ?? 0) + 1
+    runSeq.set(sessionID, next)
+    return next
+  }
+
   type SessionMessage = {
     info?: {
       role?: string
@@ -162,32 +124,76 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
       aborted,
       ready,
       missingUser: false,
+      assistantFinish: finish,
+      assistantErrorName: typeof error === "object" && error ? (error as any).name : undefined,
     }
   }
 
-  const handleSessionIdle = async (sessionID: string) => {
-    if (inFlight.has(sessionID)) return
-    if (skipNextAuto.has(sessionID)) {
-      skipNextAuto.delete(sessionID)
+  const handleSessionIdle = async (sessionID: string, source: string) => {
+    const now = Date.now()
+    const run = nextRun(sessionID)
+
+    if (inFlight.has(sessionID)) {
+      await logDebug("auto-continue skipped: already in-flight", { sessionID, source, run })
       return
     }
-    const lastIdle = lastIdleAt.get(sessionID)
-    const now = Date.now()
-    if (lastIdle && now - lastIdle < 1000) return
-    lastIdleAt.set(sessionID, now)
     inFlight.add(sessionID)
     try {
+      if (skipNextAuto.has(sessionID)) {
+        skipNextAuto.delete(sessionID)
+        await logDebug("auto-continue skipped: skipNextAuto", { sessionID, source, run })
+        return
+      }
+
+      const lastIdle = lastIdleAt.get(sessionID)
+      if (lastIdle && now - lastIdle < 1000) {
+        await logDebug("auto-continue skipped: idle debounce", {
+          sessionID,
+          source,
+          run,
+          lastIdle,
+          now,
+          deltaMs: now - lastIdle,
+        })
+        return
+      }
+
+      lastIdleAt.set(sessionID, now)
+
       const app = new PlanpilotApp(openDatabase(), sessionID)
       const active = app.getActivePlan()
-      if (!active) return
+      if (!active) {
+        clearWaitTimer(sessionID)
+        await logDebug("auto-continue skipped: no active plan", { sessionID, source, run })
+        return
+      }
       const next = app.nextStep(active.plan_id)
-      if (!next) return
-      if (next.executor !== "ai") return
+      if (!next) {
+        clearWaitTimer(sessionID)
+        await logDebug("auto-continue skipped: no pending step", { sessionID, source, run, planId: active.plan_id })
+        return
+      }
+      if (next.executor !== "ai") {
+        clearWaitTimer(sessionID)
+        await logDebug("auto-continue skipped: next executor is not ai", {
+          sessionID,
+          source,
+          run,
+          planId: active.plan_id,
+          stepId: next.id,
+          executor: next.executor,
+        })
+        return
+      }
+
       const wait = parseWaitFromComment(next.comment)
       if (wait && wait.until > now) {
         clearWaitTimer(sessionID)
         await log("info", "auto-continue delayed by step wait", {
           sessionID,
+          source,
+          run,
+          planId: active.plan_id,
           stepId: next.id,
           until: wait.until,
           reason: wait.reason,
@@ -195,7 +201,7 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
         const msUntil = Math.max(0, wait.until - now)
         const timer = setTimeout(() => {
           waitTimers.delete(sessionID)
-          handleSessionIdle(sessionID).catch((err) => {
+          handleSessionIdle(sessionID, "wait_timer").catch((err) => {
             void log("warn", "auto-continue retry failed", {
               sessionID,
               error: err instanceof Error ? err.message : String(err),
@@ -211,22 +217,61 @@ export const PlanpilotPlugin: Plugin = async (ctx) => {
 
       const goals = app.goalsForStep(next.id)
       const detail = formatStepDetail(next, goals)
-      if (!detail.trim()) return
+      if (!detail.trim()) {
+        await log("warn", "auto-continue stopped: empty step detail", {
+          sessionID,
+          source,
+          run,
+          planId: active.plan_id,
+          stepId: next.id,
+        })
+        return
+      }
 
       const autoContext = await resolveAutoContext(sessionID)
       if (autoContext?.missingUser) {
         await log("warn", "auto-continue stopped: missing user context", { sessionID })
         return
       }
-      if (autoContext?.aborted || autoContext?.ready === false) return
+      if (!autoContext) {
+        await logDebug("auto-continue stopped: missing autoContext (no recent messages?)", {
+          sessionID,
+          source,
+          run,
+          planId: active.plan_id,
+          stepId: next.id,
+        })
+        return
+      }
+      if (autoContext.aborted) {
+        await logDebug("auto-continue skipped: last assistant aborted", {
+          sessionID,
+          source,
+          run,
+          planId: active.plan_id,
+          stepId: next.id,
+          assistantErrorName: autoContext.assistantErrorName,
+          assistantFinish: autoContext.assistantFinish,
+        })
+        return
+      }
+      if (autoContext.ready === false) {
+        await logDebug("auto-continue skipped: last assistant not ready", {
+          sessionID,
+          source,
+          run,
+          planId: active.plan_id,
+          stepId: next.id,
+          assistantFinish: autoContext.assistantFinish,
+        })
+        return
+      }
 
       const timestamp = new Date().toISOString()
-      const message = `Planpilot plugin auto message @ ${timestamp}
-Hints:
-- If the next step needs human action, insert a human step before it.
-- If you need to wait for something to finish, use the step wait subcommand.
-Next step details:
-${detail.trimEnd()}`
+      const message = formatPlanpilotAutoContinueMessage({
+        timestamp,
+        stepDetail: detail,
+      })
 
       const promptBody: any = {
         agent: autoContext?.agent ?? undefined,
@@ -237,18 +282,51 @@ ${detail.trimEnd()}`
         promptBody.variant = autoContext.variant
       }
 
+      await logDebug("auto-continue sending prompt_async", {
+        sessionID,
+        source,
+        run,
+        planId: active.plan_id,
+        stepId: next.id,
+        agent: promptBody.agent,
+        model: promptBody.model,
+        variant: promptBody.variant,
+        messageChars: message.length,
+      })
+
       await ctx.client.session.promptAsync({
         path: { id: sessionID },
         body: promptBody,
       })
+
+      await log("info", "auto-continue prompt_async accepted", {
+        sessionID,
+        source,
+        run,
+        planId: active.plan_id,
+        stepId: next.id,
+      })
     } catch (err) {
-      await log("warn", "failed to auto-continue plan", { error: err instanceof Error ? err.message : String(err) })
+      await log("warn", "failed to auto-continue plan", {
+        sessionID,
+        source,
+        error: err instanceof Error ? err.message : String(err),
+        stack: err instanceof Error ? err.stack : undefined,
+      })
     } finally {
       inFlight.delete(sessionID)
     }
   }
 
+  await log("info", "planpilot plugin initialized", {
+    directory: ctx.directory,
+    worktree: ctx.worktree,
+  })
+
   return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(PLANPILOT_SYSTEM_INJECTION)
+    },
     tool: {
       planpilot: tool({
         description: PLANPILOT_TOOL_DESCRIPTION,
@@ -285,17 +363,22 @@ ${detail.trimEnd()}`
         },
       }),
     },
-    "experimental.session.compacting": async ({ sessionID }) => {
+    "experimental.session.compacting": async ({ sessionID }, output) => {
       skipNextAuto.add(sessionID)
       lastIdleAt.set(sessionID, Date.now())
+
+      await logDebug("compaction hook: skip next auto-continue", { sessionID })
+
+      // Compaction runs with tools disabled; inject Planpilot guidance into the continuation summary.
+      output.context.push(PLANPILOT_TOOL_DESCRIPTION)
     },
     event: async ({ event }) => {
       if (event.type === "session.idle") {
-        await handleSessionIdle(event.properties.sessionID)
+        await handleSessionIdle(event.properties.sessionID, "session.idle")
         return
       }
       if (event.type === "session.status" && event.properties.status.type === "idle") {
-        await handleSessionIdle(event.properties.sessionID)
+        await handleSessionIdle(event.properties.sessionID, "session.status")
       }
     },
   }
@@ -310,4 +393,3 @@ function containsForbiddenFlags(argv: string[]): boolean {
     return false
   })
 }
-

package/src/prompt.ts

@@ -0,0 +1,104 @@
+export const PLANPILOT_HELP_TEXT = [
+  "Planpilot - Plan/Step/Goal auto-continue workflow.",
+  "",
+  "Model:",
+  "- plan -> step -> goal",
+  "- step.executor: ai | human",
+  "- status rolls up: goals -> steps -> plan",
+  "",
+  "Rules (important):",
+  "- Prefer assigning steps to ai. Use human steps only for actions that require human approval/credentials",
+  "  or elevated permissions / destructive operations (e.g. GitHub web UI, sudo, deleting data/files).",
+  "- One step = one executor. Do NOT mix ai/human work within the same step.",
+  "  If a person must do something, create a separate human step.",
+  "- Keep statuses up to date. Mark goals/steps done as soon as they are completed so roll-up and auto-continue stay correct.",
+  "- `step wait` is ONLY for asynchronous, non-blocking external work that is already in progress",
+  "  (build/test/job/CI/network/remote service).",
+  "  If you can run something now, do it instead of waiting.",
+  "  Do NOT use `step wait` to wait for human action.",
+  "- Keep comments short and decision-focused.",
+  "",
+  "Status propagation:",
+  "- Step with goals: done iff ALL goals are done; else todo.",
+  "- Plan with steps: done iff ALL steps are done; else todo.",
+  "- Step with 0 goals: manual status (`step update` / `step done`).",
+  "- Plan with 0 steps: manual status (`plan update` / `plan done`).",
+  "- When a plan becomes done, it is removed from active plan.",
+  "",
+  "Auto-continue:",
+  "- When the session is idle and an active plan exists:",
+  "  - if next pending step.executor is ai: Planpilot auto-sends the next step + goals.",
+  "  - if next pending step.executor is human: no auto-continue.",
+  "- Pause while waiting on external systems: `step wait`.",
+  "- Stop auto-continue:",
+  "  - `plan deactivate`, OR",
+  "  - insert a human step BEFORE the next pending ai step (so the next executor becomes human).",
+  "",
+  "Invocation:",
+  "- argv is tokenized: [section, subcommand, ...args]",
+  "- section: help | plan | step | goal",
+  "",
+  "Commands:",
+  "- help",
+  "",
+  "Plan:",
+  "- plan add <title> <content>",
+  "- plan add-tree <title> <content> --step <content> [--executor ai|human] [--goal <content>]... [--step ...]...",
+  "- plan list [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
+  "- plan count [--scope project|all] [--status todo|done|all]",
+  "- plan search --search <term> [--search <term> ...] [--search-mode any|all] [--search-field plan|title|content|comment|steps|goals|all] [--match-case] [--scope project|all] [--status todo|done|all] [--limit N] [--page N] [--order id|title|created|updated] [--desc]",
+  "- plan show <id>",
+  "- plan export <id> <path>",
+  "- plan comment <id> <comment> [<id> <comment> ...]",
+  "- plan update <id> [--title <title>] [--content <content>] [--status todo|done] [--comment <comment>]",
+  "- plan done <id>",
+  "- plan remove <id>",
+  "- plan activate <id> [--force]",
+  "- plan show-active",
+  "- plan deactivate",
+  "",
+  "Step:",
+  "- step add <plan_id> <content...> [--executor ai|human] [--at <pos>]",
+  "- step add-tree <plan_id> <content> [--executor ai|human] [--goal <content> ...]",
+  "- step list <plan_id> [--status todo|done|all] [--executor ai|human] [--limit N] [--page N]",
+  "- step count <plan_id> [--status todo|done|all] [--executor ai|human]",
+  "- step show <id>",
+  "- step show-next",
+  "- step wait <id> --delay <ms> [--reason <text>]",
+  "- step wait <id> --clear",
+  "- step comment <id> <comment> [<id> <comment> ...]",
+  "- step update <id> [--content <content>] [--status todo|done] [--executor ai|human] [--comment <comment>]",
+  "- step done <id> [--all-goals]",
+  "- step move <id> --to <pos>",
+  "- step remove <id...>",
+  "",
+  "Goal:",
+  "- goal add <step_id> <content...>",
+  "- goal list <step_id> [--status todo|done|all] [--limit N] [--page N]",
+  "- goal count <step_id> [--status todo|done|all]",
+  "- goal show <id>",
+  "- goal comment <id> <comment> [<id> <comment> ...]",
+  "- goal update <id> [--content <content>] [--status todo|done] [--comment <comment>]",
+  "- goal done <id...>",
+  "- goal remove <id...>",
+].join("\n")
+
+export const PLANPILOT_TOOL_DESCRIPTION = [
+  "Planpilot planner for auto-continue plan workflows.",
+  "For multi-step and complex tasks, use Planpilot to structure work into plans/steps/goals.",
+  "Run `planpilot help` for full usage + rules.",
+].join("\n")
+
+export const PLANPILOT_SYSTEM_INJECTION =
+  "If the task is multi-step or complex, must use the `planpilot` plan tool. For full usage + rules, run: planpilot help."
+
+export function formatPlanpilotAutoContinueMessage(input: { timestamp: string; stepDetail: string }): string {
+  const detail = (input.stepDetail ?? "").trimEnd()
+  return [
+    `Planpilot @ ${input.timestamp}`,
+    "This message was automatically sent by the Planpilot tool because the next pending step executor is ai.",
+    "For full usage + rules, run: planpilot help",
+    "Next step details:",
+    detail,
+  ].join("\n")
+}