Skip to content

feat(plugin): add experimental.session.compacting hook for pre-compaction context injection #5698

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
rekram1-node merged 2 commits into from
Dec 17, 2025
Merged

feat(plugin): add experimental.session.compacting hook for pre-compaction context injection #5698

rekram1-node merged 2 commits into from
Dec 17, 2025

Conversation

@joelhooks
Copy link
Contributor

@joelhooks joelhooks commented Dec 17, 2025 •
edited
Loading

Summary

Adds a session.compacting plugin hook that fires before compaction starts, allowing plugins to append additional context to the compaction prompt.

Use Case

The opencode-swarm-plugin uses multi-agent coordination with beads (issue tracker), Swarm Mail (agent communication), and semantic memory. When compaction happens, the generic prompt loses all swarm coordination state. This hook lets plugins inject:

  • Active bead ID and status
  • Agent name and role
  • File reservations
  • Recent swarm mail context
  • Instructions to re-sync state after resuming

Changes

File Change
packages/plugin/src/index.ts Add session.compacting hook type
packages/opencode/src/session/compaction.ts Call hook before processor.process(), append context to prompt
packages/web/src/content/docs/plugins.mdx Add example showing hook usage

Hook Signature

"session.compacting"?: (
  input: { sessionID: string },
  output: { context: string[] },
) => Promise<void>

Example Usage

export const SwarmPlugin: Plugin = async (ctx) => {
  return {
    "session.compacting": async (input, output) => {
      output.context.push(`
## Swarm Coordination State

IMPORTANT: This session is part of a multi-agent swarm. After resuming:
1. Run beads_query to check current task status
2. Run swarmmail_inbox to sync communications
3. Check file reservations before editing
`)
    }
  }
}

Design Decisions

  • Append-only: Plugins can only add context, not replace the base prompt
  • Minimal input: Just sessionID - plugins fetch their own state
  • Not experimental: This is a stable hook for a real use case

@joelhooks joelhooks force-pushed the feat/session-compacting-hook branch from 55c14e4 to f418cd9 Compare December 17, 2025 18:14
@arsham
Copy link

arsham commented Dec 17, 2025

This is great! How would you recommend wiring it up with a slash command?

@joelhooks
Copy link
Contributor Author

joelhooks commented Dec 17, 2025

This isn't a slash command - it's a plugin hook that fires whenever compaction happens (via /compact or auto-overflow). Just implement "session.compacting" in your plugin and it injects your context into the summary prompt.

Agreed /compact taking args would be nice - separate PR though.

@arsham
Copy link

arsham commented Dec 17, 2025

I agree. I had this PR #4616 a while back but I like your solution better.

@joelhooks
Copy link
Contributor Author

joelhooks commented Dec 17, 2025

Nice! Your PR adds the user-facing trigger, this one adds the plugin hook. They're complementary - with both merged, users could /compact "focus on auth flow" AND plugins could inject their own context automatically. 🤝

@joelhooks joelhooks force-pushed the feat/session-compacting-hook branch from f418cd9 to dde4a2f Compare December 17, 2025 19:45
@rekram1-node
Copy link
Collaborator

rekram1-node commented Dec 17, 2025

Talked w/ Dax we will merge but mark as experimental for now

@rekram1-node rekram1-node changed the title feat(plugin): add session.compacting hook for pre-compaction context injection feat(plugin): add experimental.session.compacting hook for pre-compaction context injection Dec 17, 2025
@spoons-and-mirrors spoons-and-mirrors mentioned this pull request Dec 17, 2025
Closed
@rekram1-node rekram1-node merged commit 2443028 into sst:dev Dec 17, 2025
3 checks passed
This was referenced Dec 17, 2025
Closed
Closed
@joelhooks
Copy link
Contributor Author

joelhooks commented Dec 17, 2025

@rekram1-node hell ya! what's the process for getting it out of experimental? I've been testing it and it works exactly how I'd hoped, so curious.

@rekram1-node
Copy link
Collaborator

rekram1-node commented Dec 17, 2025

Normally it's just that he likes to think about APIs more and when we release as experimental we get to different usecases surface that we didn't think about originally, helps the API be better when it's "official", like I imagine there are people who'd wanna override the instructions instead of just append and this hook doesnt support that but we prolly wouldn't want a brand new one

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.

3 participants

@joelhooks @arsham @rekram1-node