Feature: Session-aware extension lifecycle for multi-session processes

[heresyrj]

Problem

The current extension lifecycle assumes one process = one session. registerTools(pi) receives an ExtensionAPI but no session context, so extensions that need per-session state must store it on globalThis. This works fine for single-session TUI usage, but breaks when a single process hosts multiple sessions.

Real-world scenario

We run a daemon process (headless pi + WebSocket thin client) that hosts two sessions: a conversation session for human interaction and a background session for automated task execution. When the second session's registerTools() runs, it clobbers the first session's callbacks and bridge references on globalThis.

Issues encountered

1. Callback clobber

Extensions commonly clear and re-register callbacks during init:

// Extension does this to be idempotent on /reload:
const callbacks = (globalThis as any).__myCallbacks;
callbacks.splice(0); // Wipes ALL sessions' callbacks
callbacks.push(myCallback);

Second session's init wipes first session's callbacks — job completion notifications, alerts, etc. are silently lost.

2. Singleton state override

Any singleton on globalThis (e.g. active session reference, bridge, shadow state) is overwritten by the second session.

3. /reload identity loss

On /reload, jiti re-imports the extension module and SDK creates a fresh ExtensionAPI (pi) object. Since registerTools(pi) receives a new pi and bindSessionHooks() doesn't re-run, the extension has no way to know which session is being reloaded. We tried 5 different heuristic approaches (tagging pi, counting calls, checking active bridges, etc.) — all fail because "reload of session A" and "creation of session B after A is bound" produce identical observable state from within the extension.

Current workarounds

• TaggedCallback = { fn, sessionId } — callbacks tagged with session identity, scoped cleanup
• Map<sessionId, Bridge> — replaces singleton bridge
• __lucaSingleSession flag — set by entry point to enable reload-specific cleanup
• __lucaReloadBridgeId marker — explicit reload signal (mechanism exists but no pre-reload hook to set it)

These work but are discipline-based — every new per-session state requires manual keying by sessionId.

Proposed solution

Extend registerTools (or add a new lifecycle) with session context:

// Option A: Session lifecycle events
export function activate(pi: PiExtension) {
  pi.onSessionCreated((session, ctx) => {
    // ctx is per-session, managed by SDK
    ctx.onJobDone((meta, result) => { ... });
  });

  pi.onSessionReloaded((session, ctx) => {
    // Same ctx preserved — no identity guessing needed
  });

  pi.onSessionDestroyed((session, ctx) => {
    // SDK auto-cleans ctx
  });
}

// Option B: Minimal — just add ctx to registerTools
export default function registerTools(pi: ExtensionAPI, ctx: SessionContext) {
  // ctx.sessionId, ctx.onDispose(), ctx.store (per-session Map)
}

Either approach would:

• Make per-session state structural (impossible to clobber across sessions)
• Eliminate all globalThis.__luca* hacks
• Make /reload trivial (SDK reuses ctx, extension doesn't need to detect it)
• Support N sessions per process with zero extension changes

Backward compatibility

Option B is minimal — existing extensions that don't use ctx continue to work. The parameter is simply available for extensions that need it.

Happy to discuss further or contribute a PR if there's interest.