Skip to content

docs: Add plugin-side daemon spawn pattern documentation (#1056)#1193

Open
unn-Known1 wants to merge 1 commit intojackwener:mainfrom
unn-Known1:docs/plugin-daemon-documentation-1056
Open

docs: Add plugin-side daemon spawn pattern documentation (#1056)#1193
unn-Known1 wants to merge 1 commit intojackwener:mainfrom
unn-Known1:docs/plugin-daemon-documentation-1056

Conversation

@unn-Known1
Copy link
Copy Markdown

Summary

This PR addresses issue #1056 by adding comprehensive documentation for plugin-side daemon spawning.

Changes

1. New Documentation: docs/developer/plugin-daemons.md

Added a complete guide for plugin authors on how to spawn background daemons, including:

  • Verified spawn pattern from src/browser/bridge.ts:132-137 with detailed explanation
  • Key properties: detached: true, stdio: "ignore", .unref(), and environment inheritance
  • Why the pattern works: No setsid or explicit process group management needed on macOS/Linux
  • Lazy spawning: Spawn from CLI entry point, not at module import
  • Daemon communication: HTTP server patterns and port selection
  • Multi-daemon considerations: Unique ports, discovery, conflict handling
  • Testing guidelines: Verification checklist for plugin daemon authors

2. Updated: docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md

Added Multi-Daemon Namespace Reservation section that:

  • Defines daemon naming convention (e.g., browser-bridge for built-in)
  • Reserves CLI surface for opencli daemon status/stop/restart [name]
  • Specifies status response format for both single and multi-daemon scenarios
  • Proposes discovery mechanism via ~/.opencli/daemons/<name>.json
  • Includes backward compatibility notes

Issue Resolution

  • Add a short "plugin-side daemons" section to developer docs citing the spawn pattern
  • Amend the daemon lifecycle redesign spec to reserve single-vs-multi daemon namespace in the CLI surface

Testing

Documentation changes only. Verified:

  • New file follows existing docs style and structure
  • Links to related documentation are valid
  • Code examples match actual implementation in src/browser/bridge.ts

Screenshots

N/A - Documentation changes only

This PR addresses issue jackwener#1056 by:

1. Added docs/developer/plugin-daemons.md with:
   - Verified spawn pattern from src/browser/bridge.ts:132-137
   - Explanation of detached: true + stdio: 'ignore' + unref()
   - Environment inheritance guidance
   - Lazy spawning recommendations
   - Daemon communication patterns
   - Multi-daemon considerations
   - Testing guidelines

2. Updated docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md:
   - Added Multi-Daemon Namespace Reservation section
   - Defined daemon naming convention
   - Reserved CLI surface for status/stop/restart [name] argument
   - Specified discovery mechanism via ~/.opencli/daemons/<name>.json
   - Added backward compatibility notes

Signed-off-by: MiniMax Agent <agent@minimax.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant