@jakedowns/progress-tool-opencode-plugin 0.0.0-stage → 2.14.0
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 +74 -2
- package/dist/gui-experimental.cjs +10 -0
- package/package.json +63 -4
- package/skills/delegation/SKILL.md +67 -0
- package/skills/osc-demo/SKILL.md +25 -0
- package/skills/progress-tool/SKILL.md +91 -0
- package/skills/tree-demo/SKILL.md +25 -0
- package/src/gui.tsx +613 -0
- package/src/index.ts +473 -0
- package/src/instructions.ts +27 -0
- package/src/monitor.ts +366 -0
- package/src/rpc.ts +60 -0
- package/src/state.ts +94 -0
- package/src/telemetry.ts +76 -0
- package/src/tree.ts +433 -0
- package/src/tui.tsx +151 -0
- package/src/types.ts +48 -0
package/README.md
CHANGED
|
@@ -1,3 +1,75 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @jakedowns/progress-tool-opencode-plugin
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
Prefer manual configuration? Add to `opencode.json`:
|
|
19
|
+
|
|
20
|
+
```jsonc
|
|
21
|
+
{
|
|
22
|
+
"plugins": ["@jakedowns/progress-tool-opencode-plugin"],
|
|
23
|
+
"mcp": {
|
|
24
|
+
"servers": {
|
|
25
|
+
"progress-server": {
|
|
26
|
+
"type": "local",
|
|
27
|
+
"command": ["npx", "-y", "@jakedowns/progress-tool-mcp"]
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## What it does
|
|
35
|
+
|
|
36
|
+
- **`progress` tool** — dual purpose: a drop-in replacement for todo/task
|
|
37
|
+
trackers (tree of tasks, parent/child roll-up) *and* a milestone reporter.
|
|
38
|
+
- **`list` tool** — read-only view of your session's trees (dismissed hidden).
|
|
39
|
+
- **`progress-relay`** — wraps long commands so stdout/stderr drive the UI
|
|
40
|
+
(`progress-relay --id build-1 -- npm run build`); exit code maps to
|
|
41
|
+
done/error. Parses `OSC 9;4` progress sequences natively.
|
|
42
|
+
- **Desktop pill** — `(N · agg%)` title, collapsible trees (animated),
|
|
43
|
+
dismissals that persist, started/last-updated tooltips, nudge telemetry.
|
|
44
|
+
- **Guidance that adapts** — injected rules, skill playbooks, pre-flight relay
|
|
45
|
+
hints, strict-mode nudges (silent runs, stale progress), a turn-end idle
|
|
46
|
+
reminder, and an optional 2-minute wall-clock nudge.
|
|
47
|
+
|
|
48
|
+
## Options
|
|
49
|
+
|
|
50
|
+
Pass under the plugin entry's `options` in `opencode.json`:
|
|
51
|
+
|
|
52
|
+
| option | default | meaning |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `injectInstructions` | `true` | inject progress/relay rules into every session |
|
|
55
|
+
| `registerSkills` | `true` | register the bundled skills |
|
|
56
|
+
| `autoRegisterMcp` | `true` | register `@jakedowns/progress-tool-mcp` automatically |
|
|
57
|
+
| `strictMode` | `"nudge"` | `"nudge"` / `"force"` / `"off"` tool-call monitor |
|
|
58
|
+
| `wallClockMs` | `120000` | wall-clock nudge threshold (`0` disables) |
|
|
59
|
+
| `idleReminder` | `true` | turn-end nudge when open tasks remain |
|
|
60
|
+
| `unhinged` | `false` | append a task-list reminder to every user message |
|
|
61
|
+
| `verboseLogging` | `false` | JSONL nudge telemetry (`~/.opencode-progress-nudges.log`) |
|
|
62
|
+
| `autoHideDone` | `false` | hide completed tasks after the success hold |
|
|
63
|
+
| `expandRootsByDefault` | `false` | expand pill tree roots by default |
|
|
64
|
+
| `barStyle` | `"blocks"` | `"blocks"` or `"emoji"` |
|
|
65
|
+
| `refreshMs` | `1000` | view refresh interval |
|
|
66
|
+
|
|
67
|
+
State lives in `~/.opencode-progress-state.json` (override with
|
|
68
|
+
`PROGRESS_STATE_PATH`). Retention is opt-in (`PROGRESS_AUTO_PRUNE_S`); entries
|
|
69
|
+
ride by default so the store doubles as a report.
|
|
70
|
+
|
|
71
|
+
## Links
|
|
72
|
+
|
|
73
|
+
- Repository & full docs: <https://github.com/jakedowns/progress-tool>
|
|
74
|
+
- Spec: `docs/out-of-band-relay-spec.md`
|
|
75
|
+
- 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.0",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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "2.14.0",
|
|
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/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.
|