@jakedowns/progress-tool-opencode-plugin 0.0.0-stage → 2.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,85 @@
1
- # Temporary Holding Version
1
+ # @jakedowns/progress-tool-opencode-plugin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ OpenCode plugin that gives agents a **fire-and-forget progress tool** and an
4
+ **out-of-band relay** for long-running commands — a live, glance-able tree above
5
+ the transcript, at zero model tokens for telemetry.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ opencode plugin add @jakedowns/progress-tool-opencode-plugin
11
+ ```
12
+
13
+ Restart the service (or reload the window) and a progress pill appears above the
14
+ composer. The plugin also installs and registers the MCP server
15
+ (`@jakedowns/progress-tool-mcp`) automatically, and ships four skills
16
+ (`progress-tool`, `delegation`, `osc-demo`, `tree-demo`).
17
+
18
+ The MCP entrypoint is spawned with a real JavaScript runtime (`node`, then
19
+ `bun`, then `npx -y @jakedowns/progress-tool-mcp`). It deliberately never uses
20
+ `process.execPath`, which is the `opencode` binary in OpenCode Desktop. If no
21
+ runtime is found, auto-registration is skipped with a warning, and the progress
22
+ rules / strict-mode nudges stay off until the `progress` tool is actually
23
+ available to the model. Pin a runtime with
24
+ `{ "options": { "mcpRuntime": "/absolute/path/to/node" } }` if detection picks
25
+ the wrong one.
26
+
27
+ Prefer manual configuration? Add to `opencode.json`:
28
+
29
+ ```jsonc
30
+ {
31
+ "plugins": ["@jakedowns/progress-tool-opencode-plugin"],
32
+ "mcp": {
33
+ "servers": {
34
+ "progress-server": {
35
+ "type": "local",
36
+ "command": ["npx", "-y", "@jakedowns/progress-tool-mcp"]
37
+ }
38
+ }
39
+ }
40
+ }
41
+ ```
42
+
43
+ ## What it does
44
+
45
+ - **`progress` tool** — dual purpose: a drop-in replacement for todo/task
46
+ trackers (tree of tasks, parent/child roll-up) *and* a milestone reporter.
47
+ - **`list` tool** — read-only view of your session's trees (dismissed hidden).
48
+ - **`progress-relay`** — wraps long commands so stdout/stderr drive the UI
49
+ (`progress-relay --id build-1 -- npm run build`); exit code maps to
50
+ done/error. Parses `OSC 9;4` progress sequences natively.
51
+ - **Desktop pill** — `(N · agg%)` title, collapsible trees (animated),
52
+ dismissals that persist, started/last-updated tooltips, nudge telemetry.
53
+ - **Guidance that adapts** — injected rules, skill playbooks, pre-flight relay
54
+ hints, strict-mode nudges (silent runs, stale progress), a turn-end idle
55
+ reminder, and an optional 2-minute wall-clock nudge.
56
+
57
+ ## Options
58
+
59
+ Pass under the plugin entry's `options` in `opencode.json`:
60
+
61
+ | option | default | meaning |
62
+ |---|---|---|
63
+ | `injectInstructions` | `true` | inject progress/relay rules into every session |
64
+ | `registerSkills` | `true` | register the bundled skills |
65
+ | `autoRegisterMcp` | `true` | register `@jakedowns/progress-tool-mcp` automatically |
66
+ | `mcpRuntime` | auto | absolute path to the `node`/`bun` used to spawn the MCP server (auto-detected; set this if detection picks wrong) |
67
+ | `strictMode` | `"nudge"` | `"nudge"` / `"force"` / `"off"` tool-call monitor |
68
+ | `wallClockMs` | `120000` | wall-clock nudge threshold (`0` disables) |
69
+ | `idleReminder` | `true` | turn-end nudge when open tasks remain |
70
+ | `unhinged` | `false` | append a task-list reminder to every user message |
71
+ | `verboseLogging` | `false` | JSONL nudge telemetry (`~/.opencode-progress-nudges.log`) |
72
+ | `autoHideDone` | `false` | hide completed tasks after the success hold |
73
+ | `expandRootsByDefault` | `false` | expand pill tree roots by default |
74
+ | `barStyle` | `"blocks"` | `"blocks"` or `"emoji"` |
75
+ | `refreshMs` | `1000` | view refresh interval |
76
+
77
+ State lives in `~/.opencode-progress-state.json` (override with
78
+ `PROGRESS_STATE_PATH`). Retention is opt-in (`PROGRESS_AUTO_PRUNE_S`); entries
79
+ ride by default so the store doubles as a report.
80
+
81
+ ## Links
82
+
83
+ - Repository & full docs: <https://github.com/jakedowns/progress-tool>
84
+ - Spec: `docs/out-of-band-relay-spec.md`
85
+ - License: MIT
@@ -0,0 +1,10 @@
1
+ "use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("solid-js/web"),B=require("@opencode/plugin/gui"),v=require("solid-js"),Y=require("@opencode/plugin/rpc"),Z="2.14.1",F={version:Z},K=Y.Rpc.define({id:"opencode-progress",methods:{list:{input:{},output:{type:"object",properties:{entries:{type:"object",additionalProperties:!0},updatedAt:{type:"number"}},required:["entries","updatedAt"],additionalProperties:!1}},dismiss:{input:{type:"object",properties:{key:{type:"string"},status:{type:"string"}},required:["key","status"],additionalProperties:!1},output:{type:"object",properties:{ok:{type:"boolean"}},required:["ok"],additionalProperties:!1}}},events:{updated:{schema:{type:"object",properties:{updatedAt:{type:"number"}},required:["updatedAt"],additionalProperties:!1}}}}),N={error:4,running:3,waiting:2,done:1};function E(e){if(e==null)return"";let t=String(e);return t=t.replace(/\r\n?/g,`
2
+ `),t=t.replace(/\\u000[ad]/gi,`
3
+ `),t=t.replace(/\\r\\n|\\n|\\r/gi,`
4
+ `),t=t.replace(/<br\s*\/?>/gi,`
5
+ `),t=t.split(`
6
+ `).map(s=>s.replace(/[ \t]+$/g,"")).join(`
7
+ `),t.replace(/\n{3,}/g,`
8
+
9
+ `).trim()}function z(e){return E(e).replace(/\s*\n+\s*/g," ").replace(/[ \t]+/g," ").trim()}function W(e){const t=new Map,s=new Map;for(const[l,n]of Object.entries(e))!n||typeof n!="object"||(t.set(l,{...n,title:E(n.title),detail:n.detail==null?n.detail:E(n.detail)}),n.id&&!s.has(n.id)&&s.set(n.id,l));const o=new Map;for(const l of t.keys())o.set(l,[]);const i=[];for(const[l,n]of t){const g=n.parentId?t.has(n.parentId)?n.parentId:s.get(n.parentId):void 0;g&&g!==l?o.get(g)?.push(l):i.push(l)}const f=(l,n)=>{const g=t.get(l),$=t.get(n),k=(N[$?.status??""]??0)-(N[g?.status??""]??0);return k!==0?k:($?.updatedAt??0)-(g?.updatedAt??0)};for(const l of o.values())l.sort(f);i.sort(f);const d=new Set,b=l=>{const n=t.get(l);d.add(l);const g=(o.get(l)??[]).filter(M=>!d.has(M)).map(b);let $=n.status,k=n.progress,S=n.updatedAt;if(g.length>0){const M=g.map(a=>a.status);M.includes("error")?$="error":M.includes("running")?$="running":M.includes("waiting")?$="waiting":M.every(a=>a==="done")&&($="done");const c=g.map(a=>a.progress).filter(a=>typeof a=="number"&&Number.isFinite(a));k==null&&c.length>0&&(k=c.reduce((a,u)=>a+u,0)/c.length);const m=g.reduce((a,u)=>Math.max(a,u.updatedAt??0),0);m>(S??0)&&(S=m)}return{...n,key:l,children:g,status:$,progress:k,updatedAt:S,reportedAt:n.updatedAt}};return i.map(b)}function ee(e){const t=[],s=o=>{t.push(o);for(const i of o.children)s(i)};for(const o of e)s(o);return t}function I(e,t=0){const s=[];for(const o of e)s.push({node:o,depth:t}),s.push(...I(o.children,t+1));return s}function te(e,t){const s=[];for(const o of e)s.push({node:o,depth:0}),t[o.key]||s.push(...I(o.children,1));return s}function H(e){return(e.children??[]).reduce((t,s)=>t+1+H(s),0)}function ne(e,t,s){const o={};for(const i of e)!i.children||i.children.length===0||(o[i.key]=!(s[i.key]??t));return o}function re(e){let t=0,s=0,o=0;for(const i of Object.values(e))!i||typeof i!="object"||((i.status==="running"||i.status==="waiting")&&t++,i.status==="done"&&s++,i.dismissed&&o++);return{active:t,done:s,dismissed:o}}function se(e){return ee(e).filter(t=>t.status==="running"||t.status==="waiting").length}function J(e,t){const s=t[e.key];return!(!s||(e.reportedAt??0)>s.at||(!(s.status==="done"||s.status==="error")||e.status==="error")&&(e.status??"")!==s.status)}function oe(e){return e==null?0:Math.max(0,Math.min(1,e))}function ie(e){const t=e??{};return{style:t.barStyle==="emoji"?"emoji":"blocks",segments:typeof t.barSegments=="number"&&t.barSegments>0?t.barSegments:void 0,total:typeof t.barTotal=="number"&&t.barTotal>0?t.barTotal:void 0}}function ae(e,t=1e3){const s=e??{},o=s.refreshMs??s.intervalMs;return typeof o=="number"&&Number.isFinite(o)&&o>=100?o:t}function le(e){const t=e??{};return{successHoldMs:typeof t.successHoldMs=="number"&&t.successHoldMs>=0?t.successHoldMs:void 0,showDone:t.showDone!==!1,autoHideDone:t.autoHideDone===!0,scope:t.scope==="all"?"all":"session"}}function U(e,t,s={}){if(s.scope==="all")return e;if(!t)return{};const o=`${t}:`,i={};for(const[f,d]of Object.entries(e))!d||typeof d!="object"||(d.sessionId===t||f.startsWith(o))&&(i[f]=d);return i}function V(e,t,s={}){const o=s.successHoldMs??8e3,i=s.showDone!==!1,f=s.autoHideDone===!0,d={};for(const[b,l]of Object.entries(e))!l||typeof l!="object"||l.status==="done"&&(!i||f&&t-(l.updatedAt??0)>=o)||(d[b]=l);return d}function L(e,t={}){const s=t.style==="emoji"?"emoji":"blocks",o=t.segments??(s==="emoji"?6:10),i=t.total??100,f=oe(e),d=Math.round(f*o),b=s==="emoji"?"🟩".repeat(d)+"⬛️".repeat(Math.max(0,o-d)):"█".repeat(d)+"░".repeat(Math.max(0,o-d)),l=Math.round(f*i);return{bar:b,done:l,total:i,fraction:`(${l}/${i})`,style:s}}function q(e){return e==null?null:`${Math.round(e*100)}%`}var ce=r.template("<br>"),de=r.template('<span aria-hidden=true style="flex:0 0 auto;opacity:0.6;font-size:11px;width:14px;margin-top:4px;user-select:none;line-height:1;display:inline-block;transition:transform 0.35s ease-in-out">'),ue=r.template("<div style=margin-top:2px;font-size:12px;opacity:0.72;white-space:normal;overflow-wrap:anywhere;word-break:break-word>"),pe=r.template("<span>"),fe=r.template("<span> descendant"),ge=r.template("<span style=white-space:nowrap;cursor:default>started "),me=r.template('<button type=button title=Dismiss aria-label=Dismiss style="flex:0 0 auto;border:1px solid rgba(127,127,127,0.35);background:transparent;color:inherit;opacity:0.65;border-radius:50%;width:22px;height:22px;cursor:pointer;line-height:1">×'),he=r.template('<div style=display:flex;align-items:flex-start;gap:8px;padding-top:5px;padding-bottom:5px><div style="width:8px;height:8px;border-radius:50%;margin-top:6px;flex:0 0 auto"></div><div style="flex:1 1 auto;min-width:0"><div style=white-space:normal;overflow-wrap:anywhere;word-break:break-word></div><div style=margin-top:4px;display:flex;gap:8px;align-items:center;font-size:11px;opacity:0.58><span style="font-family:ui-monospace, SFMono-Regular, Menlo, monospace">'),ye=r.template('<button type=button style="margin-top:6px;border:none;background:transparent;color:inherit;opacity:0.65;cursor:pointer;text-align:left;padding:6px 8px;font-size:12px">✕ Dismiss all'),be=r.template('<div style="display:flex;flex-direction:column;gap:2px;max-height:min(60vh, 520px);overflow-y:auto;overflow-x:hidden;min-width:320px;max-width:520px;padding-right:4px"><div style="margin-top:4px;padding:4px 8px 6px;font-size:10px;opacity:0.45;user-select:none">progress plugin desktop v'),ve=r.template("<div style=opacity:0.6;font-size:13px;padding:8px>No active progress"),$e=r.template('<div style="display:grid;transition:grid-template-rows 0.5s ease-in-out"><div style=overflow:hidden;min-height:0>');function we(e,t){return Promise.race([e,new Promise((s,o)=>setTimeout(()=>o(new Error(`timeout after ${t}ms`)),t))])}function xe(e){if(e==="error")return"danger";if(e==="done")return"success";if(e==="waiting")return"warning"}function ke(e){return e==="error"?"#ef4444":e==="done"?"#10b981":e==="waiting"?"#f59e0b":"#3b82f6"}function G(e){if(!e)return"";try{return new Date(e).toLocaleString(void 0,{month:"short",day:"numeric",hour:"numeric",minute:"2-digit"})}catch{return new Date(e).toISOString()}}function Se(e){if(!e)return"";const t=Math.max(0,Date.now()-e);if(t<1e4)return"just now";const s=Math.floor(t/1e3);if(s<60)return`${s} second${s===1?"":"s"} ago`;const o=Math.floor(s/60);if(o<60)return`${o} minute${o===1?"":"s"} ago`;const i=Math.floor(o/60);if(i<24)return`${i} hour${i===1?"":"s"} ago`;const f=Math.floor(i/24);return`${f} day${f===1?"":"s"} ago`}function Q(e){return r.createComponent(v.Index,{get each(){return E(e.text).split(`
10
+ `)},children:(t,s)=>[s>0?ce():null,r.memo(t)]})}function X(e){const t=()=>q(e.node.progress),s=()=>L(e.node.progress,e.options);return(()=>{var o=he(),i=o.firstChild,f=i.nextSibling,d=f.firstChild,b=d.nextSibling,l=b.firstChild;return o.$$click=n=>{!e.hasChildren||window.getSelection?.()?.toString()||(n.preventDefault(),e.onToggle?.())},r.insert(o,r.createComponent(v.Show,{get when(){return e.hasChildren},get children(){var n=de();return r.insert(n,()=>e.collapsed?"▸":"▾"),r.effect(g=>r.setStyleProperty(n,"transform",e.collapsed?"rotate(0deg)":"rotate(90deg)")),n}}),i),r.insert(d,r.createComponent(Q,{get text(){return e.node.title}})),r.insert(f,r.createComponent(v.Show,{get when(){return e.node.detail},get children(){var n=ue();return r.insert(n,r.createComponent(Q,{get text(){return e.node.detail??""}})),r.effect(()=>r.setAttribute(n,"title",e.node.detail?`${e.node.status}: ${z(e.node.detail)}`:"")),n}}),b),r.insert(l,()=>s().bar),r.insert(b,r.createComponent(v.Show,{get when(){return t()},get children(){var n=pe();return r.insert(n,t),n}}),null),r.insert(b,r.createComponent(v.Show,{get when(){return r.memo(()=>!!e.collapsed)()&&e.node.children.length>0},get children(){var n=fe(),g=n.firstChild;return r.insert(n,()=>H(e.node),g),r.insert(n,()=>H(e.node)===1?"":"s",null),n}}),null),r.insert(b,r.createComponent(v.Show,{get when(){return e.node.startedAt},get children(){var n=ge();return n.firstChild,r.insert(n,()=>G(e.node.startedAt),null),r.effect(()=>r.setAttribute(n,"title",`Last updated ${Se(e.node.updatedAt)} (${G(e.node.updatedAt)})`)),n}}),null),r.insert(o,r.createComponent(v.Show,{get when(){return e.onDismiss},get children(){var n=me();return n.$$click=g=>{g.stopPropagation(),e.onDismiss?.()},n}}),null),r.effect(n=>{var g=`${e.depth*14}px`,$=e.hasChildren?"pointer":"default",k=ke(e.node.status),S=e.depth===0?"650":"500",M=`${e.node.status}: ${z(e.node.title)}`;return g!==n.e&&r.setStyleProperty(o,"padding-left",n.e=g),$!==n.t&&r.setStyleProperty(o,"cursor",n.t=$),k!==n.a&&r.setStyleProperty(i,"background",n.a=k),S!==n.o&&r.setStyleProperty(d,"font-weight",n.o=S),M!==n.i&&r.setAttribute(d,"title",n.i=M),n},{e:void 0,t:void 0,a:void 0,o:void 0,i:void 0}),o})()}function Me(e,t,s){const o=L(e.progress,s),i=q(e.progress),f=t>0?"  ".repeat(t)+"└─ ":"",d=o.style==="emoji"?`: ${o.bar}${o.fraction}`:i?` · ${i}`:"";return{id:e.key,label:`${f}${z(e.title)}${d}`,detail:e.detail?z(e.detail):void 0,tone:xe(e.status)}}const je=B.Plugin.define({setup(e){const[t,s]=v.createSignal({entries:{},loaded:!1}),[o,i]=v.createSignal({}),f=ie(e.options),d=le(e.options),b=ae(e.options);let l=!0;const n=async()=>{try{const c=e.sessions.current();if(!c){s(a=>({...a,loaded:!0}));return}const m=await we(c.server.client.rpc(K).list({}),4e3);if(!l)return;s({entries:m?.entries??{},loaded:!0}),i(a=>{const u={...a};for(const[O,y]of Object.entries(a)){const D=(m?.entries??{})[O]?.dismissed;D&&typeof D=="object"&&D.at>=y.at-500&&delete u[O]}return u})}catch(c){if(!l)return;s(m=>({...m,loaded:!0,error:String(c)})),console.error("[opencode-progress] rpc list failed",String(c))}};console.log(`[opencode-progress] gui setup v${F.version} (opencode ${e.app.version}, ${e.app.platform})`),e.options?.notifyOnLoad===!0&&e.toast.show({title:"Progress plugin loaded",description:`${e.app.platform} · opencode-progress v${F.version}`,variant:"success",duration:2500}),n();const g=setInterval(()=>{n()},b),$=()=>{const c={};for(const[m,a]of Object.entries(t().entries)){const u=a.dismissed;u&&typeof u=="object"&&typeof u.at=="number"&&(c[m]={status:String(u.status??""),at:u.at})}return c},k=()=>{const c=$();for(const[m,a]of Object.entries(o())){const u=c[m];(!u||a.at>u.at)&&(c[m]=a)}return c},S=(c,m,a)=>{i(u=>({...u,[m]:{status:a,at:Date.now()}})),c.server.client.rpc(K).dismiss({key:m,status:a}).catch(u=>console.error("[opencode-progress] dismiss rpc failed",String(u)))},M=c=>{const m=()=>U(t().entries,c.sessionID,d),a=()=>W(V(m(),Date.now(),d)).filter(j=>!J(j,k())),[u,O]=v.createSignal({}),y=e.options?.expandRootsByDefault===!0,D=()=>ne(a(),y,u()),T=()=>te(a(),D());let P,A=0;return v.createEffect(()=>{T();const w=A;queueMicrotask(()=>{P&&P.scrollTop!==w&&(P.scrollTop=w)})}),(()=>{var w=be(),j=w.firstChild;return j.firstChild,w.addEventListener("scroll",h=>{A=h.currentTarget.scrollTop}),r.use(h=>P=h,w),r.insert(w,r.createComponent(v.Show,{get when(){return T().length>0},get fallback(){return ve()},get children(){return[r.createComponent(v.For,{get each(){return a()},children:h=>{const C=()=>D()[h.key]??!1;return[r.createComponent(X,{node:h,depth:0,options:f,get hasChildren(){return h.children.length>0},get collapsed(){return C()},onToggle:()=>O(_=>({..._,[h.key]:!(_[h.key]??y)})),onDismiss:()=>S(c.session,h.key,h.status??"")}),(()=>{var _=$e(),p=_.firstChild;return r.insert(p,r.createComponent(v.For,{get each(){return I(h.children,1)},children:({node:x,depth:R})=>r.createComponent(X,{node:x,depth:R,options:f})})),r.effect(x=>r.setStyleProperty(_,"grid-template-rows",C()?"0fr":"1fr")),_})()]}}),(()=>{var h=ye();return h.$$click=()=>{for(const C of a())S(c.session,C.key,C.status??"")},h})()]}}),j),r.insert(j,()=>F.version,null),w})()};return e.add(B.ComposerPill,()=>({id:"progress",show:c=>{const m=t(),a=U(m.entries,c.session.id,d),u=Object.keys(a).length===0;if(m.error&&u)return{label:"progress: error",title:"Progress plugin error",rows:[{id:"error",label:m.error.slice(0,160),tone:"danger"}]};if(!m.loaded&&u)return{label:"progress: loading",title:"Progress plugin"};const y=W(V(a,Date.now(),d)).filter(p=>!J(p,k()));if(y.length===0)return;const D=se(y),T=y[0],P=q(T.progress),A=L(T.progress,f),w=z(T.title),j=y.map(p=>p.progress).filter(p=>typeof p=="number"&&Number.isFinite(p)),h=j.length>0?q(j.reduce((p,x)=>p+x,0)/j.length):null,C=h?`(${y.length>1?`${y.length} · `:""}${h}) `:y.length>1?`(${y.length}) `:"";return{label:A.style==="emoji"?`${C}${w}: ${A.bar}${A.fraction}`:D>0?`${C}${w}${P?` ${P}`:""}`:`${C}${w}`,title:(()=>{const p=re(a),x=[];return p.active>0&&x.push(`${p.active} active`),p.done>0&&x.push(`${p.done} done`),p.dismissed>0&&x.push(`${p.dismissed} dismissed`),x.length>0?x.join(" · "):"Agent progress"})(),rows:[...I(y).slice(0,7).map(({node:p,depth:x})=>{const R=Me(p,x,f);return x!==0?R:{...R,icon:"circle-x",detail:R.detail??"dismiss",run:()=>S(c.session,p.key,p.status??"")}}),{id:"dismiss",label:"✕ Dismiss all",run:()=>{for(const p of y)S(c.session,p.key,p.status??"")}}]}},menu:c=>r.createComponent(M,{get session(){return c.session},get sessionID(){return c.session.id}})})),()=>{l=!1,clearInterval(g)}}});r.delegateEvents(["click"]);exports.default=je;
package/package.json CHANGED
@@ -1,6 +1,65 @@
1
1
  {
2
2
  "name": "@jakedowns/progress-tool-opencode-plugin",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "2.14.1",
4
+ "description": "OpenCode plugin: native progress indicators for the TUI and desktop GUI, with an out-of-band relay for zero-token long-running command telemetry",
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts",
8
+ "./tui": "./src/tui.tsx",
9
+ "./rpc": "./src/rpc.ts",
10
+ "./gui-experimental": "./dist/gui-experimental.cjs"
11
+ },
12
+ "files": [
13
+ "src",
14
+ "dist",
15
+ "skills",
16
+ "README.md"
17
+ ],
18
+ "scripts": {
19
+ "build": "vite build",
20
+ "dev": "vite build --watch",
21
+ "test": "node --test test/dismissal.test.cjs test/instructions.test.cjs test/mcp.test.cjs test/monitor.test.cjs test/skills.test.cjs test/telemetry.test.cjs",
22
+ "prepublishOnly": "npm test && npm run build"
23
+ },
24
+ "dependencies": {
25
+ "@jakedowns/progress-tool-mcp": "^2.8.0",
26
+ "@opencode/plugin": "^2.3.0"
27
+ },
28
+ "devDependencies": {
29
+ "solid-js": "^1.9.0",
30
+ "vite": "^7.0.0",
31
+ "vite-plugin-solid": "^2.11.0"
32
+ },
33
+ "peerDependencies": {
34
+ "@opentui/core": ">=0.6.6",
35
+ "@opentui/solid": ">=0.6.6",
36
+ "solid-js": ">=1.9.0"
37
+ },
38
+ "engines": {
39
+ "node": ">=18"
40
+ },
41
+ "publishConfig": {
42
+ "access": "public"
43
+ },
44
+ "license": "MIT",
45
+ "author": "Jake Downs <mail@jakedowns.com>",
46
+ "homepage": "https://github.com/jakedowns/progress-tool#readme",
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "git+https://github.com/jakedowns/progress-tool.git",
50
+ "directory": "plugin"
51
+ },
52
+ "bugs": {
53
+ "url": "https://github.com/jakedowns/progress-tool/issues"
54
+ },
55
+ "keywords": [
56
+ "opencode",
57
+ "opencode-plugin",
58
+ "progress",
59
+ "progress-bar",
60
+ "mcp",
61
+ "relay",
62
+ "telemetry",
63
+ "osc-9-4"
64
+ ]
65
+ }
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: Delegation (Subagents)
3
+ description: Use subagents well — fan out independent research and verification in parallel, pick explore vs general, inherit the session's model, and avoid parallel-edit conflicts
4
+ ---
5
+
6
+ # Delegating work to subagents
7
+
8
+ OpenCode runs subagents in their own **child sessions** with fresh context. They
9
+ work in the background; you get a report when each goes idle, and again after
10
+ later rounds. Use them when parallel work genuinely exists.
11
+
12
+ ## When to fan out
13
+
14
+ Good candidates — work that is **independent** and **read-heavy**:
15
+
16
+ - Research several files/areas/modules at once ("find every caller of X",
17
+ "how does auth work here", "what does this API expect").
18
+ - Verify while you implement: one child runs the tests/build while you edit.
19
+ - Compare approaches: ask two children for different designs, synthesize.
20
+ - Broad searches (docs + code + web) that don't depend on each other.
21
+
22
+ Bad candidates:
23
+
24
+ - Sequential work where step 2 needs step 1's result.
25
+ - Trivial one-liners (a child's fresh context costs tokens for no gain).
26
+ - **Parallel edits in the same tree** — see safety below.
27
+
28
+ ## `explore` vs `general`
29
+
30
+ | agent | mode | use for |
31
+ |---|---|---|
32
+ | `explore` | subagent, read-only | searches, reading code/docs, answering "where/what" — cannot edit |
33
+ | `general` | subagent, broad tools | multi-step research or implementation chunks; cannot launch its own subagents |
34
+
35
+ Rule of thumb: **`explore` for questions, `general` for work**.
36
+
37
+ ## Model
38
+
39
+ - A subagent **inherits the parent session's model when no model is configured** —
40
+ so simply **omit `model`** on subagent definitions you want on the session model.
41
+ - The V2 parent can override a subagent's configured model at dispatch time
42
+ (highest priority). If you want this enforced regardless of config, the community
43
+ plugin `opencode-subagent-model-selector` routes by the primary session's model/variant.
44
+
45
+ ## Safety before delegating
46
+
47
+ - **Scope tightly**: one clear deliverable, explicit files/paths, "report
48
+ file:line evidence", and what *not* to touch.
49
+ - **No concurrent edits to the same tree** without worktree isolation — two
50
+ children editing overlapping files will conflict. For parallel editing, use
51
+ `opencode-workflows` (git worktrees per agent) or serialize the edits.
52
+ - Children inherit permissions from their own agent config, not yours; the parent's
53
+ `subagent` permission decides which agents it may launch.
54
+ - Ask for evidence (commands run, output) — subagent claims are not verification.
55
+
56
+ ## Reporting
57
+
58
+ - Mirror delegation in the progress tree: one child `progress` entry per
59
+ delegated workstream (`parentId` = the phase), updated when the subagent reports.
60
+ - The completion notification is your cue — do not poll the child.
61
+
62
+ ## Related community plugins
63
+
64
+ - `opencode-workflows` — scripted parallel subagents, worktree isolation, resume.
65
+ - `opencode-smart-subagents` — two-way messages between child and parent, batching.
66
+ - `opencode-agent-tree` — enforces decomposition into many small parallel subagents.
67
+ - `opencode-subagent-model-selector` — routes subagent models by the session model.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: OSC 9;4 Demo
3
+ description: Demo OSC 9;4 terminal progress support in progress-tool — run a fake build that streams native OSC 9;4 progress sequences through the out-of-band relay (progress-relay), zero agent tokens
4
+ ---
5
+
6
+ # OSC 9;4 demo
7
+
8
+ Run the demo and explain what the viewer sees:
9
+
10
+ 1. Optionally, start the GUI first in a second terminal: `./launch-gui.sh` (from
11
+ the progress-tool repository root — clone it to run the demos; this skill
12
+ ships both in-repo and packaged with the plugin).
13
+ 2. Run the demo: `bash demo/osc-demo.sh` (also works from any directory; set
14
+ `PROGRESS_STATE_PATH` to isolate the state file if needed).
15
+ 3. Report the outcome: the fake build emits `OSC 9;4` sequences
16
+ (`ESC ] 9;4;<state>;<progress> BEL`), the relay parses them before text
17
+ heuristics (state 1 → percent, state 3 → indeterminate, state 4 → waiting),
18
+ writes throttled telemetry to the shared state file at zero token cost, and
19
+ maps the exit code to `done`/`error`. The task `osc-demo` ends done at 100%.
20
+ 4. Never poll or sleep to refresh the indicator — that is the whole point of
21
+ the out-of-band relay.
22
+
23
+ For the full contract, see `docs/out-of-band-relay-spec.md` §6.3.1. For the
24
+ corresponding test coverage, see the "OSC 9;4" tests in
25
+ `mcp-server/test/smoke.test.js` (`cd mcp-server && npm test`).
@@ -0,0 +1,91 @@
1
+ ---
2
+ name: Progress Tool Usage
3
+ description: Use the progress-tool MCP correctly — report long-horizon work (research, planning, exploration, refactors, docs) with the fire-and-forget progress tool, structure multi-step plans as a parentId tree, keep entries current between tool calls, and wrap long-running commands with the out-of-band progress-relay at zero token cost
4
+ ---
5
+
6
+ # Using the progress tool well
7
+
8
+ The `progress` tool (progress-server MCP) is **dual purpose**:
9
+
10
+ 1. **Drop-in replacement for todo/task-tracking tools** (`todowrite` / `TaskCreate`):
11
+ any multi-step plan belongs in this tree, where it also drives the user's
12
+ live indicator.
13
+ 2. **A wrapper for long-running programmatic tool calls** (build scripts,
14
+ compilers, test suites, installs — anything that reports progress on
15
+ stdout) via the out-of-band relay.
16
+
17
+ ## When to report
18
+
19
+ Anything expected to run **longer than a couple of minutes or a single reply** —
20
+ including work with no shell command at all: research, planning, codebase
21
+ exploration, multi-file refactors, documentation.
22
+
23
+ - **Start:** one call with `status: "running"`, a clean stable `id`
24
+ (e.g. `"build-1"` — never session-prefixed), short `title`; put detail in
25
+ `detail`, not the title.
26
+ - **Keep it current while you work:** non-shell work has no relay, so spend
27
+ one of your turns **between tool calls** — roughly every few calls, or
28
+ whenever you start or finish a step — on an update (fresh `detail`, a
29
+ `progress: 0.0–1.0` fraction, or a status change). This todowrite-style
30
+ cadence keeps the summary rollup live.
31
+ - **Re-arm:** when your current tree is `done` and new work begins, open a
32
+ **fresh tree**. And if you have already made 2+ consecutive edits or shell
33
+ calls on one task with no active entry, that **is** multi-step work —
34
+ start a tree now (never too late: record what is done and what remains).
35
+ - **Steering is work:** when the user redirects you mid-flight while a tree
36
+ is in progress, record the steer as a child entry — one line summarizing
37
+ the ask plus what you plan to do in reaction — and update it as you
38
+ respond. The user should see their steer land in the rollup.
39
+ - **Why this tool exists:** the transcript — thought traces, tool calls,
40
+ command output — is a wall of text. The tree is the glance-able layer above
41
+ it: a live, high-level view of what you are doing, what you are waiting on,
42
+ and what is next. Keep it accurate at that level — a short headline title,
43
+ the current step in `detail`, an honest `progress` fraction — so the user
44
+ can read the pill instead of scrolling the log.
45
+ - **Close:** end with `status: "done"` or `"error"`. **Close what you open** —
46
+ an abandoned `running` entry is a zombie the user has to dismiss by hand.
47
+ - Statuses are exactly `running | waiting | done | error` (use `waiting` for
48
+ "not started yet / blocked"; there is no `pending`).
49
+
50
+ ## Structure multi-step plans as a tree
51
+
52
+ One child entry per step — `progress({ id: "<parent>-step-1", status:
53
+ "running", title: "<step>", parentId: "<parent>" })` — then update each child
54
+ as you go. The parent's status/progress roll up automatically (error beats
55
+ running beats waiting; parent progress = mean of children). **Never embed a
56
+ numbered step list inside one title/detail** — the rollup cannot see
57
+ individual steps inside text.
58
+
59
+ ## Long-running shell commands: use the relay
60
+
61
+ Call `progress` once (`status: "running"`), then run the command **through**
62
+ the out-of-band relay instead of waiting on it:
63
+
64
+ ```sh
65
+ progress-relay --id <id> -- <cmd> # wrap: exit 0 → done, non-zero → error
66
+ <cmd> | progress-relay --id <id> # pipe: done on EOF
67
+ ```
68
+
69
+ Use the exact relay command printed in the `progress` tool response (it
70
+ guarantees a working invocation path). When the harness supports background
71
+ commands, run the wrapped command in the background and keep working; the
72
+ completion notification is your cue for the final milestone.
73
+
74
+ The relay parses `OSC 9;4` terminal progress sequences (Gradle rich console,
75
+ mise, PowerShell 7.4+, …) before text heuristics like `"45%"`, and streams
76
+ throttled telemetry into the indicator at **zero token cost**.
77
+
78
+ ## Never poll
79
+
80
+ No `sleep` loops, no re-calling `progress` on a timer for elapsed time or
81
+ percentages, no reading terminal output in a loop. Between-turn updates during
82
+ non-shell work are the intended cadence, not polling. The relay's exit code
83
+ maps to done/error automatically — do not re-call `progress` with `"done"`
84
+ unless adding semantic detail.
85
+
86
+ ## See it live
87
+
88
+ - `bash demo/osc-demo.sh` — OSC 9;4 structured progress through the relay.
89
+ - `bash demo/tree-demo.sh` — nested parent/child roll-up
90
+ (`PROGRESS_TREE_DEMO_FAIL=1` shows error roll-up).
91
+ - Full contract: `docs/out-of-band-relay-spec.md`.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: Task Tree Demo
3
+ description: Demo nested task trees (parentId roll-up) in progress-tool — run a fake release pipeline with parent, child, and grandchild tasks streaming through the out-of-band relay at zero agent tokens, with an optional failure mode that rolls an error up the tree
4
+ ---
5
+
6
+ # Task tree demo
7
+
8
+ Run the demo and explain what the viewer sees:
9
+
10
+ 1. Optionally, start the GUI first in a second terminal: `./launch-gui.sh` (from
11
+ the progress-tool repository root — clone it to run the demos; this skill
12
+ ships both in-repo and packaged with the plugin).
13
+ 2. Run the happy path: `bash demo/tree-demo.sh` (works from any directory; set
14
+ `PROGRESS_STATE_PATH` to isolate the state file if needed).
15
+ 3. Run the failure mode: `PROGRESS_TREE_DEMO_FAIL=1 bash demo/tree-demo.sh` —
16
+ `test-e2e` fails and the error rolls up through its parent to `tree-demo`.
17
+ 4. Explain the mechanics: child tasks are real background commands wrapped in
18
+ `progress-relay` (exit code → done/error, output → detail/percent at zero
19
+ token cost); the parent is created once with `parentId`-linked children and
20
+ its status/progress are a read-time roll-up (error beats running beats
21
+ waiting; parent progress = mean of child progress), per
22
+ `docs/out-of-band-relay-spec.md` §5.6.
23
+ 5. Never poll or sleep to refresh the indicator — the tree converges on its own.
24
+
25
+ For OSC 9;4 structured progress (orthogonal feature), see the `osc-demo` skill.