Skip to content

v1.0.1

Choose a tag to compare

@sblattj sblattj released this 07 Oct 02:56
· 30 commits to main since this release
  • New: the session's native Todo list is drawn from the goal plan. While a plan exists the plugin rewrites the arguments of the model's own todowrite call in tool.execute.before, so the host performs exactly one write and the checklist every client renders is the plan: one row per action in plan order, content a3 · rebuild dist (the action id, ·, and the title bounded to 120 characters), and a plan past 20 actions ending in one counted +N more actions — /goal status row. The status map exists to stop the native [✓] asserting something the plugin's own evidence gate refuses — a done action becomes completed only once it is verified, a done action without a passing verdict mirrors as in_progress with — needs claim/evidence/verdict, and a blocked action mirrors as in_progress with — BLOCKED: <reason>, which is what the host's own todo contract asks for. Rows the model wrote itself are kept, below the plan rows, at most 10 of them and each bounded to 120 characters; nothing of the model's is silently deleted, and the tool result names how many were kept and how many the cap trimmed. todowrite({todos: []}) is the refresh idiom and it is a redraw, never a delete: with a live plan it re-emits the projection and leaves the kept rows alone, with no live plan it re-emits the last mirrored rows or the terminal snapshot taken when the goal ended, and only in a session that never mirrored anything does an empty call reach the host as an empty list. A stale mirror is nudged at most three times per goal run — Todo panel is stale — call todowrite({todos: []}) once; the plan is copied into it for you. — shared across the auto-continue block and goal_action_update's result, and /goal resume refunds the budget in full. /goal stop, /goal clear and a genuine completion each hand the list back in one line, because the mirror is one-way and the rows outlive the goal.
    • New option mirrorTodos: "plan" (default) or "off". "off" restores 1.0.0 exactly: all three todowrite hooks return before touching anything, every prompt surface that mentions the mirror is silent, and goal_plan_set's, goal_action_update's and todowrite's descriptions are the stock bytes — the <existing_todos> offer below is skipped along with the host read that produces it, so an "off" instance makes no session.todo call at all. The option is static and instance-wide by construction, so it cannot introduce cross-session skew.
    • There is no "adopt" mode. A session that already has native todo rows when /goal set runs gets them described back to the model once, in an <existing_todos> block on the goal's first continuation, with the instruction to either record them as the plan through goal_plan_set — rewritten as falsifiable claims — or ignore them. The read is best-effort and read-only: nothing is adopted, goal.mirror.extra starts empty, and a failing or absent host call is logged and skipped rather than blocking /goal set.
    • The Goal panel becomes an exception list while the mirror is on, because the Todo section is already showing the plan: unverified done actions first, then blocked, then in_progress, each group in plan order, and pending actions are not repeated. A done action without a verdict gains the same — needs claim/evidence/verdict suffix on its panel line that its mirrored row carries, and the progress line gains · todo mirror fresh (5), · todo list stale, or · mirror drift (7≠5) when the panel's own live read of the host's list disagrees with the payload. Under the exception list +N more counts only the exception rows the 12-row cap dropped, over the published actions rather than the whole plan, so a server-capped plan cannot promise rows the payload does not carry. A payload with no plan.mirror, or one whose state is off, renders exactly as it did in 1.0.0.
    • metadata.goal payload is now v: 3, adding two keys: plan.mirror and plan.actions[].verified. plan.mirror carries state ("fresh", "stale" or "off"), rows and extra (how many rows the last mirrored write held and how many of those were the model's own), and at (when that write landed, 0 for never). verified is the server's own CEV verdict on each published action — done and a claim and evidence and verdict: "pass" — and it exists because a consumer cannot re-derive it: claim and evidence are goal-private prose that never go on the wire, and goal_plan_set accepts a done action with a passing verdict and no ledger (only goal_action_update enforces the gate), so status plus verdict renders exactly that action as finished. The Goal panel now reads the flag rather than inferring it, which is what puts such an action back in the exception list with its — needs claim/evidence/verdict suffix, agreeing with the mirrored todo row and the progress count that already named it unverified. Every v2 key is still written and both keys are purely additive. Skew warning, unchanged in shape from the v1→v2 one: the two halves are registered separately (opencode.json and tui.json), and the panel never reads v at all, so a 0.11.0 panel against a v3 payload simply lists every action and shows no mirror suffix, and the current panel against a v2 payload does the same. Upgrade both halves together.
    • Two new hooks: tool.execute.after and tool.definition. The freshness stamp lives in the after hook because only that hook proves the host actually wrote the list — between the two hooks the host decodes the arguments and asks for permission, and either can abort the call, so a mirror stamped fresh for a write that never landed would suppress the very nudge that repairs it. tool.definition appends a static paragraph to the builtin todowrite description telling the model what the tool now does in a goal-bearing session; it is never gated on goal state, because the hook carries no session id. scripts/verify.mjs requires both, so the hook surface it checks is now eleven names. A host that does not know tool.definition simply never fires it.
    • The todowrite description suffix is stamped at most once per object. The tool.definition hook returns early when the description it was handed already carries the mirror paragraph, so a host that re-triggers the hook against the same output object — or a second registration of this plugin in one directory — cannot double it. OpenCode 1.18.29 rebuilds the description object on every ToolRegistry.tools() call, so this is defensive rather than a fix for an observed host; it is pinned by a unit that stamps one object twice and by a mutation anchor that deletes the guard.
    • Seven hazards are documented rather than fixed, in docs/compatibility.md: the suffixed todowrite description reaching goal-less sessions in the same project, todowrite: "ask" turning every refresh into a permission modal, hosts where todowrite is denied (the mirror never becomes fresh, so the panel reads stale for the whole run and the nudge self-suppresses), another plugin's tool.execute.before overwriting the mirror with no way to detect it, the host's second and hookless todowrite implementation, /undo not rewinding todos, and one deliberate departure from the host's one-in_progress convention. The same document records the transcript bubbles — which the mirror reaches through the args rewrite rather than through a plugin slot, so on 1.18.29 they show the mirrored rows and npm run smoke:todo-safety re-measures that every run — and that priority is wire-only in the TUI.
    • The published type declarations carry the whole surface. index.d.ts: GoalSidebarStatus.v becomes 3, plan.mirror ({ state: "fresh" | "stale" | "off"; rows; extra; at }) and verified: boolean on every published action join GoalSidebarStatus, mirrorTodos joins GoalPluginOptions, and tool.execute.after and tool.definition join GoalPluginHooks. tui.d.ts: GoalPanelModel gains an optional mirror (state, rows, extra, liveTodoCount, drift), and goalPanelModel gains a second parameter — goalPanelModel(raw, options?: { liveTodoCount?: number }). That parameter is optional, so a 1.0.0 call site that passes only the payload still typechecks and simply renders no drift comparison. Reading a payload is likewise unchanged; only code that constructs a GoalSidebarStatus literal has to grow the three new required fields, since that type describes what the server writes. One deliberate asymmetry between the two files: the panel's mirror.state is declared string rather than the server's three-value union, because the panel forwards whatever state the payload carried — a newer server can invent one — and it stands the progress suffix and the drift comparison down for a state it does not recognise, while still treating the mirror as active. Both files are typechecked as a consumer sees them, under NodeNext and Bundler resolution, by npm run type:check.
    • The packed type contract exercises the 1.0.1 surface, not just the 1.0.0 one. The npm run type:check fixture now sets mirrorTodos: "plan" in its satisfies GoalPluginOptions object with a @ts-expect-error negative case for an invalid value, calls tool.execute.after and tool.definition beside tool.execute.before, reads plan.mirror.state and plan.mirror.rows off a GoalSidebarStatus, and calls goalPanelModel both with and without its new options argument — so a declaration that stops compiling for a consumer fails the gate instead of waiting for the next reader.
  • New: two real-host smokes and a benchmark for the mirror. npm run smoke:todo-mirror boots a real opencode serve against a mock model and asserts the plan is redrawn over a divergent list, with two controls — the same run under mirrorTodos: "off", and a session with no goal — plus the SQLite row order and survival across a restart of the serve process. npm run smoke:todo-safety is the destructive half, and every assertion in it is about rows surviving: an empty todowrite arriving after /goal stop or after a genuine completion must re-emit the last mirrored rows rather than wipe the list, and the same call in a session that never had a goal must still clear it. Both need the opencode binary on PATH and a freshly bundled dist/, and neither is in release:check, because that binary is not a dev dependency. scripts/bench-todo-mirror.mjs measures the metric the design set: the number of distinct persistent checklists the sidebar renders, target one, under "plan" against an "off" control.
  • Unchanged: the identifier policy, and the state file version. No new wire identifier and no new state path. STATE_FILE_VERSION is deliberately not bumped — a mismatch is rejected rather than migrated, so a bump would refuse every existing record; instead the mirror record is normalised on load, and a goal written before 1.0.1 comes back with an empty, never-mirrored one. The part metadata key, the plugin id, the log service field and both legacy state paths keep their historical opencode-goal-plugin strings, per the standing rule below.

Install: opencode-goal-pro-max-complete-plugin@github:sblattj/opencode-goal-pro-max-complete-plugin#v1.0.1 (see docs/reference.md).