-
-
Save cassiodias/83a56ad40e1add6b95ab9b7dc9d99963 to your computer and use it in GitHub Desktop.
opencode session-bootstrap.js
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| // OpenCode session-bootstrap plugin -- generic skeleton. | |
| // | |
| // Demonstrates the `session.created` pattern discussed in | |
| // sst/opencode#5409: run a one-time setup step when a new session begins, | |
| // surface a short status to the user, and inject a brief primer for the model. | |
| // | |
| // Two non-obvious things this guards against, both hit in real use: | |
| // | |
| // 1. `session.created` fires on the first real interaction, not at TUI launch. | |
| // Subscribing to the event (not the plugin `init`) is what catches a new | |
| // session. | |
| // | |
| // 2. The plugin factory can be evaluated more than once per process (e.g. the | |
| // same plugin present in more than one loaded config layer), so the handler | |
| // can see `session.created` twice for ONE new session. A module-level Set of | |
| // already-seen session ids makes the bootstrap at-most-once. The id is added | |
| // BEFORE the async work so a second event arriving mid-flight is still | |
| // dropped. | |
| // | |
| // What this does NOT solve: resume. `--continue` / `--resume` / `/resume` emit | |
| // no bus event, so a resumed session never reaches this handler. That gap is the | |
| // motivation for a native `session.start` hook with a `source` matcher. | |
| const seen = new Set(); | |
| // Replace with your own setup work (gather git status, install deps, load | |
| // context, etc.). Must never throw -- a failed bootstrap should not crash the | |
| // session. Return whatever you want to surface, or null for a silent no-op. | |
| async function bootstrap({ directory }) { | |
| try { | |
| // example: const out = await Bun.spawn(["./scripts/setup.sh"], { cwd: directory, stdout: "pipe" }); | |
| return { status: "session bootstrapped" }; | |
| } catch (_err) { | |
| return null; | |
| } | |
| } | |
| export const plugin = async ({ client, directory: inputDirectory }) => { | |
| return { | |
| event: async ({ event }) => { | |
| if (!event || event.type !== "session.created") return; | |
| const info = event.properties && event.properties.info; | |
| // Skip child / subagent sessions -- only bootstrap a top-level session. | |
| if (info && info.parentID) return; | |
| const sessionID = info && info.id; | |
| if (!sessionID) return; | |
| // At-most-once per session id. Set BEFORE the async work so a second | |
| // event for the same session (double factory eval) is dropped. | |
| if (seen.has(sessionID)) return; | |
| seen.add(sessionID); | |
| // Prefer the session's own workspace dir; fall back to the plugin cwd. | |
| const directory = (info && info.directory) || inputDirectory; | |
| const result = await bootstrap({ directory }); | |
| if (!result) return; | |
| // Short status to the user (single-line toast). | |
| if (client && client.tui && typeof client.tui.showToast === "function") { | |
| try { | |
| await client.tui.showToast({ | |
| ...(directory ? { query: { directory } } : {}), | |
| body: { message: result.status, variant: "info", title: "bootstrap" }, | |
| }); | |
| } catch (_err) { | |
| /* toast failure is non-fatal */ | |
| } | |
| } | |
| // Optional: a one-line primer for the model. `noReply: true` appends a | |
| // single user message with no assistant turn (no reply, no token burn). | |
| // Deferred + un-awaited so it never blocks the handler. | |
| if (client && client.session && typeof client.session.prompt === "function") { | |
| queueMicrotask(() => { | |
| Promise.resolve( | |
| client.session.prompt({ | |
| path: { id: sessionID }, | |
| ...(directory ? { query: { directory } } : {}), | |
| body: { | |
| noReply: true, | |
| parts: [{ type: "text", text: "Session context is loaded for this session." }], | |
| }, | |
| }) | |
| ).catch(() => { | |
| /* injection failure is non-fatal */ | |
| }); | |
| }); | |
| } | |
| }, | |
| }; | |
| }; |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment