Skip to content

fix(walkthrough): wait for the walkthrough to be ready before completing open_walkthrough - #437

Merged
chriswritescode-dev merged 1 commit into
mainfrom
fix/walkthrough-tool-waits-until-ready
Oct 16, 2026
Merged

fix(walkthrough): wait for the walkthrough to be ready before completing open_walkthrough#437
chriswritescode-dev merged 1 commit into
mainfrom
fix/walkthrough-tool-waits-until-ready

Conversation

@chriswritescode-dev

@chriswritescode-dev chriswritescode-dev commented Oct 16, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Owner

Summary

open_walkthrough returned as soon as generation started. The desktop auto-open fires when that tool call completes, so the panel opened empty while the walkthrough was still building, and nothing happened when it finished. On mobile the "Open walkthrough" button appeared before there was anything to open.

The tool call now completes only once the walkthrough is ready, so the existing frontend behavior lines up with completion without frontend changes.

Tool plugin (services/opencode-manager-tool-plugin.ts)

  • After starting generation, the action polls GET /change-walkthroughs/:sessionId?source=<key> every 2 seconds while generating is true.
  • The source key comes from the shared walkthroughSourceKey, embedded in the generated plugin source rather than duplicated.
  • Returns "The walkthrough is ready" once published; throws with the error message on failure, and a cancelled message on cancel.
  • Waiting honors the tool's abort signal; aborting leaves the walkthrough generation running.
  • Action and tool descriptions now state the call waits until ready and can take several minutes.

Trade-off (accepted)

  • The originating agent turn stays busy while the walkthrough builds, bounded by the existing 15-minute generation limit.

Type of Change

  • Bug fix
  • New feature
  • Refactor
  • Documentation

Checklist

  • Code follows project style (no comments, named imports)
  • TypeScript types are properly defined
  • Tests added/updated (80% coverage target)
  • pnpm lint passes locally
  • pnpm typecheck passes locally

Tests

  • Tool plugin: already ready, polling until ready, source key encoding (staged, branch:main), failure, cancellation, abort while waiting, description.

Validation

  • test/services/opencode-manager-tool-plugin.test.ts: 42 passed.
  • Backend lint 0 errors (41 pre-existing warnings), typecheck clean.

Summary by CodeRabbit

  • Bug Fixes
    • Opening a walkthrough now waits for generation to finish and reports failures, cancellations, or interrupted waits instead of returning before the walkthrough is ready.
    • Walkthroughs that are already ready still open immediately.

@coderabbitai

coderabbitai Bot commented Oct 16, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: 53a011e5-b22e-4d86-a6d5-4ef9fc774e98
📥 Commits

Reviewing files that changed from the base of the PR and between 1d31286 and a0bdecd.

📒 Files selected for processing: 2
  • backend/src/services/opencode-manager-tool-plugin.ts
  • backend/test/services/opencode-manager-tool-plugin.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 5 included reviews per hour; 3 remain after this review.

📝 Walkthrough

open_walkthrough now waits for walkthrough generation to finish. It polls the session state every two seconds using the selected or default source, returns when ready, and reports failure, cancellation, or an aborted wait.

Changes: Walkthrough Readiness

Layer / File(s) Summary
Polling support
backend/src/services/opencode-manager-tool-plugin.ts		 The plugin adds a GET request wrapper that shares JSON parsing with POST requests. It adds a two-second polling interval and an abort-aware delay.
Wait for walkthrough readiness
backend/src/services/opencode-manager-tool-plugin.ts, backend/test/services/opencode-manager-tool-plugin.test.ts		 open_walkthrough polls until the walkthrough is ready and reports failure, cancellation, or an aborted wait. The action descriptions and tests reflect the wait behavior, including source-key encoding and polling outcomes.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Tool as open_walkthrough
  participant Endpoint as Session walkthrough state endpoint
  participant Signal as AbortSignal
  Tool->>Endpoint: Query state with selected or default source
  Endpoint-->>Tool: Return walkthrough state
  Tool->>Endpoint: Repeat query after polling delay while generation is active
  Signal-->>Tool: Abort the wait
Loading
Merge Risk: ⚪ Minimal · up to a0bde

The walkthrough wait has a cancellation path, and no merge-blocking issue was identified.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly identifies the walkthrough behavior fix and the affected open_walkthrough action.
Description check Passed The description includes the summary, change type, implementation details, trade-off, tests, and validation results. Required checklist items are addressed.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
  • Fix all pre-merge checks with AI
✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@chriswritescode-dev
chriswritescode-dev merged commit 4e8051b into main Oct 16, 2026
2 checks passed
@chriswritescode-dev
chriswritescode-dev deleted the fix/walkthrough-tool-waits-until-ready branch October 16, 2026 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@chriswritescode-dev