@loicngr/kobo 2.1.19 → 2.1.20

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.20
+
+- fix(progress): clarify activity updates and completion
+
 ## 2.1.19
 
 - feat(progress): add session activity bars and improve launch prompts

package/CONFIGURATION.md

@@ -885,10 +885,23 @@ the previous process are interrupted; external reporters may still be running
 elsewhere, so their last state is preserved. A new internal launch uses a new
 reporting identity.
 
-Workspace launch instructions require agents to use these tools for long tasks
-and pass the requirement to subagents. When a restricted subagent cannot access
-the tools, its parent reports the activity on its behalf. Reporting permissions
-do not grant permission to edit project files or complete tasks during a review.
+Workspace launch instructions require the full reporting lifecycle: create a
+bar, keep its returned ID and sequence, update that same bar at actual phase
+changes and meaningful completed milestones, and finish it before the final
+report once the outcome is known. Even without a measurable percentage, agents
+must update the current step; omitting both numeric values preserves
+indeterminate progress. No percentage is inferred from tool calls, elapsed time
+or model activity. Unchanged updates, polling and timer-driven reporting loops
+are not requested.
+
+Parents pass this lifecycle to subagents, which report and finish their own
+activities before returning. When a restricted subagent cannot access the tools,
+its parent reports observed milestones and the outcome on its behalf, without
+duplicate bars. Yielding while background work continues does not mean success.
+Reporting permissions do not grant permission to edit project files or complete
+tasks during a review. These instructions guide the model; they cannot guarantee
+that it reports every milestone. Updated guidance applies on the next launch or
+resume, not retroactively to an already running agent.
 
 The service retains at most 1,000 indicators per session, with at most 32 running
 at once. Hidden records are retained so retries cannot recreate dismissed bars.

package/dist/shared/progress-bar-prompts.js

@@ -2,6 +2,10 @@ export const PROGRESS_BAR_PLAN_EXCEPTION = 'Operational exception in Plan/read-o
 /** Shared across engines, fresh/resumed launches and delegated agents. */
 export const PROGRESS_BAR_PROMPT = `<kobo-progress-reporting>
 ${PROGRESS_BAR_PLAN_EXCEPTION}
-Use Kōbō's create_progress_bar, update_progress_bar and finish_progress_bar for long-running tasks, including tests and delegated work. Give each activity a clear label and stable activity_key; follow tool schemas for ordered updates and retries. Report meaningful steps and measured current/total only when known; otherwise keep progress indeterminate. Never invent percentages or poll these tools. Finish with succeeded or failed only when known. A dismissed bar stays hidden: continue without recreating it; dismissal is not cancellation. Reporting never substitutes for verification, and an interrupted reporter does not prove background work stopped.
-Pass this requirement to all subagents when delegating. Subagents must not schedule or replace workspace wakeups; the parent coordinates follow-up. Each subagent reports its own long task through the inherited Kōbō MCP tools; the parent must not duplicate that activity. If a custom subagent lacks these tools, the parent reports its observed progress accurately instead. After resume, start new activity keys for new work; do not reopen a finished activity.
+For each long-running activity (tests, audits, builds or delegated work), follow this reporting lifecycle:
+1. Call create_progress_bar with a clear label, current step and stable activity_key. Save its returned id and sequence; creating a bar is only the start of reporting.
+2. Call update_progress_bar with that id and an increasing sequence: update the same bar at each actual phase change or meaningful completed milestone, including during a long phase. Even without a measured percentage, report the current step; omit both current and total for step-only updates. Use measured numbers only when known. Never invent percentages, poll, send unchanged updates or start timer-driven reporting loops; follow tool retry guidance.
+3. Call finish_progress_bar on that id before your final report (or return to the parent) when the activity's succeeded/failed outcome is known. Do not declare ongoing background work finished merely because you are yielding control.
+Pass this requirement to all subagents when delegating: each reports and finishes its own long activity through inherited Kōbō MCP tools; the parent must not duplicate it. If a custom subagent lacks these tools, the parent reports its observed milestones and outcome instead. Subagents must not schedule or replace workspace wakeups; the parent coordinates follow-up.
+A dismissed bar stays hidden: continue without recreating it; dismissal is not cancellation. Reporting never substitutes for verification, and an interrupted reporter does not prove background work stopped. After resume, use new activity keys for new work; do not reopen finished activities.
 </kobo-progress-reporting>`;

package/dist/shared/progress-bar-tools.js

@@ -22,15 +22,15 @@ function tools(external) {
         annotations: { readOnlyHint: readOnly, destructiveHint: false, openWorldHint: false },
     });
     return [
-        definition('create_progress_bar', 'Report a labelled long-running activity in this session. Use a new activity_key per activity; identical retries return its current state, including dismissal. Report measured current/total together, or omit both for indeterminate progress. Closing a bar never cancels work.', {
+        definition('create_progress_bar', 'Start reporting a labelled long-running activity. Save the returned id and sequence, update that same bar at actual phase changes and meaningful completed milestones, and finish it before the final report when the outcome is known. Use a new activity_key per activity; identical retries return its current state, including dismissal. Supply measured current/total together or omit both for indeterminate progress. Closing a bar never cancels work.', {
             activity_key: { type: 'string', minLength: 1, maxLength: 100 },
             label: { type: 'string', minLength: 1, maxLength: 200 },
             step,
             current: numberOrNull,
             total: numberOrNull,
         }, ['activity_key', 'label']),
-        definition('update_progress_bar', 'Update absolute measured progress and/or step. Both numbers must be provided together, or both null. At most one accepted running update per second; respect retry guidance. Dismissed bars remain hidden. Never invent a percentage.', { progress_id: id, sequence, step, current: numberOrNull, total: numberOrNull }, ['progress_id', 'sequence']),
-        definition('finish_progress_bar', 'Finish reporting with succeeded or failed. Terminal state is immutable except an exact retry. Success hides after five seconds; failure remains until the user closes it. Reporting does not mark workspace tasks done.', { progress_id: id, sequence, step, outcome: { type: 'string', enum: ['succeeded', 'failed'] } }, ['progress_id', 'sequence', 'outcome']),
+        definition('update_progress_bar', 'Update the existing bar at actual phase changes or meaningful completed milestones, even when no percentage is known. Omit both numbers for step-only updates (previous numeric values are preserved); provide both measured numbers together, or both null to switch to indeterminate. Use the returned id as progress_id and increase sequence. Never invent percentages or send unchanged updates. At most one accepted running update per second; respect retry guidance without polling. Dismissed bars remain hidden.', { progress_id: id, sequence, step, current: numberOrNull, total: numberOrNull }, ['progress_id', 'sequence']),
+        definition('finish_progress_bar', 'Finish the same bar with succeeded or failed before your final report or return to the parent, only once the activity outcome is known. Do not finish ongoing background work merely because you yield control. Increase sequence; terminal state is immutable except an exact retry. Success hides after five seconds; failure remains until the user closes it. Reporting does not mark workspace tasks done.', { progress_id: id, sequence, step, outcome: { type: 'string', enum: ['succeeded', 'failed'] } }, ['progress_id', 'sequence', 'outcome']),
         definition('list_progress_bars', 'Read progress bars in the explicitly selected session, including dismissed/terminal bars. Responses contain bounded pages and serverTime; do not poll without a concrete need.', {
             limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
             offset: { type: 'integer', minimum: 0, default: 0 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loicngr/kobo",
-  "version": "2.1.19",
+  "version": "2.1.20",
   "description": "Kōbō — local multi-workspace orchestrator for Claude Code and OpenAI Codex, with isolated Git worktrees, live review and optional automation.",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/src/mcp-server/README.md

@@ -578,7 +578,9 @@ IDs. Workspace-bound callers omit those fields: the backend derives their scope
 from a per-launch capability. They cannot forge another workspace, session or
 launch. The managed server exposes the same tools to capable subagents; custom
 subagent tool restrictions still apply. If a child lacks access, the parent
-reports its activity rather than creating a duplicate indicator.
+reports its observed milestones and outcome rather than creating a duplicate
+indicator. Pass the full create → update → finish lifecycle to delegates; they
+must finish their own activity before returning when its outcome is known.
 
 For example, an external client can create an activity with:
 
@@ -593,7 +595,9 @@ For example, an external client can create an activity with:
 }
 ```
 
-Keep the returned `id`. Report absolute progress with `update_progress_bar`:
+Keep the returned `id` and `sequence`. Update **the same bar** at actual phase
+changes and meaningful completed milestones, including during a long phase.
+Report absolute progress with `update_progress_bar`:
 
 ```json
 {
@@ -607,8 +611,28 @@ Keep the returned `id`. Report absolute progress with `update_progress_bar`:
 }
 ```
 
-Then call `finish_progress_bar` with the same scope/id, a higher `sequence`,
-`outcome: "succeeded"` or `"failed"`, and an optional summary in `step`.
+An audit with no measurable denominator still needs step updates. After creating
+an indeterminate activity, send this when its phase changes:
+
+```json
+{
+  "workspace_id": "<workspace ID>",
+  "session_id": "<session ID>",
+  "progress_id": "<returned id>",
+  "sequence": 1,
+  "step": "Code inspection complete; verifying findings"
+}
+```
+
+Omitting **both** `current` and `total` is valid on updates. It keeps an
+indeterminate activity indeterminate, or preserves existing numeric values.
+Do not invent a percentage, send unchanged updates or create periodic LLM turns
+just to refresh a bar.
+
+Before your final report (or return to the parent), call `finish_progress_bar`
+with the same scope/id, a higher `sequence`, `outcome: "succeeded"` or `"failed"`,
+and an optional summary in `step`, once the outcome is known. Do not finish an
+activity merely because you yield while its background work continues.
 Supply numeric progress only when known: both values must be finite, with
 `total > 0` and `0 <= current <= total`. Omit both at creation, or send both as
 `null`, for an indeterminate indicator. Updates with no numeric pair keep the