@gkzhb/pi-roles 0.2.4-beta.1 → 0.2.4-beta.2

package/README.md

@@ -186,7 +186,11 @@ By default, a normal new conversation resolves its role again from `--role`, `PI
 { "pi-roles": { "preserveRoleOnNewSession": true } }
 ```
 
-This applies only to ordinary new conversations. `/role <name> --reset` still uses its explicitly requested role; reload and resume restore their session role as before. The setting does not persist a role across a Pi restart—on startup, the normal initial-role resolution still applies.
+A normal replacement reads the old session file. **Before the first assistant
+response, Pi deliberately has not created that file yet**; during that narrow
+case pi-roles transfers the active role through a process-local snapshot taken
+at `session_before_switch`. The replacement instance consumes that snapshot
+once. This fallback does not persist roles across a Pi restart.
 
 ---
 
@@ -295,7 +299,7 @@ If you have Pi's [auto-reload](https://github.com/badlogic/pi-mono/blob/main/pac
 |---|---|---|
 | `roleScope` | `"both"` | Discovery scope. `"user"`, `"project"`, or `"both"`. |
 | `defaultRole` | `"role-assistant"` | Role applied at session start when no `--role` or `PI_ROLE`. |
-| `preserveRoleOnNewSession` | `false` | Keep the current process's active role when creating a normal new conversation. Does not apply across restarts or to explicit `/role <name> --reset`. |
+| `preserveRoleOnNewSession` | `false` | Keep the prior session's active role when creating a normal new conversation. Does not apply across restarts or to explicit `/role <name> --reset`. |
 | `intercomMode` | `"off"` | Default intercom behavior for roles that don't set it explicitly. |
 | `titleModel` | `null` (auto) | Model used for session-intent summarization. Its API key and request headers are resolved from Pi's model registry, including `models.json` environment-variable configuration. Falls back to the session's current model. |
 | `warnOnMissingMcp` | `true` | Whether to surface a warning when a role's `mcp:*` entry can't be resolved. |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { ExtensionAPI, SessionEntry } from '@mariozechner/pi-coding-agent';
 import { AutocompleteItem } from '@mariozechner/pi-tui';
 import { Static, Type } from 'typebox';
 
@@ -192,6 +192,50 @@ declare const PiRolesSettingsSchema: Type.TObject<{
     warnOnMissingMcp: Type.TOptional<Type.TBoolean>;
 }>;
 type PiRolesSettings = Static<typeof PiRolesSettingsSchema>;
+/**
+ * State persisted via `pi.appendEntry("pi-roles:active-role", ...)`. Read on
+ * `session_start` (with reason="reload" or "resume") to restore the active
+ * role after a reload, since extension memory is wiped on /reload.
+ *
+ * `appliedAt` is the leaf role's source/path so we can re-resolve the chain
+ * fresh on restore — the extends parents may have been edited in the
+ * meantime.
+ *
+ * `intent` carries the session-intent summary we generated for the title, so
+ * a /role swap mid-session can keep the intent and just replace the role
+ * prefix in the session name without re-summarizing.
+ */
+declare const ActiveRoleStateSchema: Type.TObject<{
+    name: Type.TString;
+    /** Source of the LEAF role file when it was applied. */
+    source: Type.TUnion<[Type.TLiteral<"project">, Type.TLiteral<"user">, Type.TLiteral<"built-in">]>;
+    /** Path of the LEAF role file. */
+    path: Type.TString;
+    /** Cached session-intent summary for the title. May be empty pre-first-message. */
+    intent: Type.TOptional<Type.TString>;
+    /** Unix ms timestamp; for diagnostics only. */
+    appliedAt: Type.TNumber;
+}>;
+type ActiveRoleState = Static<typeof ActiveRoleStateSchema>;
+interface ResetRoleRequest {
+    /** Name explicitly requested by `/role <name> --reset`. */
+    name: string;
+    /** Unix ms timestamp, retained for diagnostics. */
+    requestedAt: number;
+}
+
+/**
+ * State a replacement session may inherit from the previous session.
+ *
+ * Persisted session entries are authoritative. This process-local state only
+ * bridges Pi's pre-first-assistant-response gap, during which the old session
+ * has entries in memory but no session file on disk yet.
+ */
+interface PreviousSessionRoleState {
+    activeRole: ActiveRoleState | undefined;
+    /** Present only when the final reset lifecycle event is a valid request. */
+    pendingResetRole: ResetRoleRequest | undefined;
+}
 
 /**
  * pi-roles extension entry point.
@@ -200,12 +244,13 @@ type PiRolesSettings = Static<typeof PiRolesSettingsSchema>;
  * (settings.ts) into the three Pi integration points the role lifecycle
  * actually needs:
  *
- *   - `session_start` — restore from persisted state on reload/resume,
- *     otherwise resolve a role name from the precedence chain (pendingReset
- *     > --role > PI_ROLE > settings.defaultRole > built-in role-assistant),
- *     then apply it. When `preserveRoleOnNewSession` is enabled, a normal new
- *     session instead retains the role currently active in this extension
- *     instance.
+ *   - `session_start` — restore the current session's persisted role on
+ *     reload/resume. For a new session, resolve an explicit persisted reset
+ *     request first, then (when configured) preserve the previous session's
+ *     active role, otherwise use --role > PI_ROLE > defaultRole > built-in.
+ *     New-session transfer reads `previousSessionFile`; Pi recreates the
+ *     extension instance during session replacement, so in-memory state is
+ *     intentionally never used as a cross-session handoff.
  *   - `before_agent_start` — re-inject the active role's body as the system
  *     prompt every turn (Pi rebuilds the prompt per turn; this is the
  *     stable hook).
@@ -221,8 +266,12 @@ type PiRolesSettings = Static<typeof PiRolesSettingsSchema>;
 interface RuntimeState {
     /** Live role applied to this session, or null before first apply. */
     activeRole: ResolvedRole | null;
-    /** Set by `/role <name> --reset` so the next session_start (reason="new") applies it. */
-    pendingRoleAfterReset: string | null;
+    /**
+     * Explicit reset requested in this still-live instance. It is copied into
+     * the process bridge by session_before_switch, then read by the replacement
+     * instance if Pi has not yet created the old session file.
+     */
+    pendingResetRequest: ResetRoleRequest | undefined;
     /** Cached discovery result; refreshed on session_start, every `/role` invocation, and `/role reload`. */
     roles: RawRole[];
     /** Shadowed roles found at lower-precedence scopes; shown in `/role list`. */
@@ -265,15 +314,15 @@ declare function composeSystemPrompt(state: Pick<RuntimeState, "activeRole" | "s
     systemPrompt: string;
 } | undefined;
 /**
- * Pick the role for an ordinary new conversation. When configured, retain the
- * role active in this extension instance; otherwise use normal initial-role
- * resolution. An explicit --reset role is handled by session_start before
- * this helper is reached.
+ * Pick the role for an ordinary new conversation. `activeRole` must come
+ * from the previous session's persisted state, not the current extension
+ * instance: Pi recreates extensions for `/new`. An explicit --reset role is
+ * resolved before this helper is reached.
  */
 declare function pickNewSessionRoleName(activeRole: Pick<ResolvedRole, "name"> | null, pi: ExtensionAPI, settings: PiRolesSettings, roles: RawRole[]): string;
 /**
- * Pick the role to launch with on a fresh session_start (no pendingReset, no
- * persisted state to restore). Precedence per BUILD-STATUS.md:
+ * Pick the role to launch with on a fresh session_start (no persisted
+ * previous-session override). Precedence per BUILD-STATUS.md:
  *
  *   --role flag > PI_ROLE env > settings.defaultRole > built-in role-assistant
  *
@@ -282,10 +331,32 @@ declare function pickNewSessionRoleName(activeRole: Pick<ResolvedRole, "name"> |
  * of the session.
  */
 declare function pickInitialRoleName(pi: ExtensionAPI, settings: PiRolesSettings, roles: RawRole[]): string;
+/**
+ * Prefer durable state from the previous session log. The process-local
+ * transfer is only a fallback for Pi's pre-first-response persistence gap.
+ */
+declare function pickPreviousSessionRoleState(diskState: PreviousSessionRoleState | undefined, processState: PreviousSessionRoleState | undefined): PreviousSessionRoleState | undefined;
+/**
+ * Read transferable state from an earlier session file. Session files may be
+ * missing, corrupted, or unavailable in ephemeral modes; those cases simply
+ * disable inheritance and fall back to ordinary initial resolution.
+ */
+declare function findPreviousSessionRoleState(previousSessionFile: string | undefined): PreviousSessionRoleState | undefined;
+/**
+ * Interpret entries from a previous session for a fresh `reason="new"`
+ * session. Exported as a pure test seam: the runtime reader above only opens
+ * the file, while this function contains the lifecycle semantics.
+ *
+ * Reset events are intentionally an ordered two-event protocol without a
+ * requestId. The final reset lifecycle event is authoritative: cancellation
+ * suppresses every earlier request; a valid final request overrides ordinary
+ * role preservation.
+ */
+declare function resolvePreviousSessionRoleState(entries: readonly SessionEntry[]): PreviousSessionRoleState;
 /**
  * Provide tab completions for `/role <here>`. Combines built-in subcommands
  * with discovered role names; case-insensitive prefix match.
  */
 declare function roleCompletions(prefix: string, roles: RawRole[]): AutocompleteItem[] | null;
 
-export { composeSystemPrompt, export_default as default, pickInitialRoleName, pickNewSessionRoleName, roleCompletions };
+export { composeSystemPrompt, export_default as default, findPreviousSessionRoleState, pickInitialRoleName, pickNewSessionRoleName, pickPreviousSessionRoleState, resolvePreviousSessionRoleState, roleCompletions };

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/index.ts
+import {
+  SessionManager
+} from "@mariozechner/pi-coding-agent";
+
 // src/schemas.ts
 import { Type } from "typebox";
 var ThinkingLevelSchema = Type.Union(
@@ -120,6 +125,8 @@ var ActiveRoleStateSchema = Type.Object(
   { additionalProperties: false }
 );
 var ACTIVE_ROLE_ENTRY_TYPE = "pi-roles:active-role";
+var RESET_ROLE_REQUEST_ENTRY_TYPE = "pi-roles:reset-role-request";
+var RESET_ROLE_CANCELLED_ENTRY_TYPE = "pi-roles:reset-role-cancelled";
 var ROLE_NOTIFICATION_MESSAGE_TYPE = "pi-roles:notification";
 var STATUS_KEY = "pi-roles";
 var BUILTIN_ROLE_ASSISTANT_NAME = "role-assistant";
@@ -712,6 +719,26 @@ async function generateAndApplyTitle(args) {
   }
 }
 
+// src/utils/process-transfer.ts
+var PROCESS_TRANSFER_KEY = /* @__PURE__ */ Symbol.for("pi-roles.previous-session-transfer");
+function getStore() {
+  const root = globalThis;
+  return root[PROCESS_TRANSFER_KEY] ??= /* @__PURE__ */ new Map();
+}
+function storeProcessTransfer(sessionFile, state) {
+  if (sessionFile) getStore().set(sessionFile, state);
+}
+function takeProcessTransfer(sessionFile) {
+  if (!sessionFile) return void 0;
+  const store = getStore();
+  const state = store.get(sessionFile);
+  store.delete(sessionFile);
+  return state;
+}
+function discardProcessTransfer(sessionFile) {
+  if (sessionFile) getStore().delete(sessionFile);
+}
+
 // src/index.ts
 var FLAG_NAME = "role";
 var ENV_VAR = "PI_ROLE";
@@ -719,7 +746,7 @@ var SUBCOMMANDS = ["list", "current", "reload"];
 function index_default(pi) {
   const state = {
     activeRole: null,
-    pendingRoleAfterReset: null,
+    pendingResetRequest: void 0,
     roles: [],
     shadowed: [],
     settings: {},
@@ -740,22 +767,42 @@ function index_default(pi) {
   pi.registerMessageRenderer(ROLE_NOTIFICATION_MESSAGE_TYPE, () => {
     return void 0;
   });
+  pi.on("session_before_switch", (event, ctx) => {
+    if (event.reason !== "new") return;
+    storeProcessTransfer(ctx.sessionManager.getSessionFile(), {
+      activeRole: state.activeRole ? activeRoleStateFromResolved(state.activeRole, state.intent) : void 0,
+      pendingResetRole: state.pendingResetRequest
+    });
+  });
   pi.on("session_start", async (event, ctx) => {
     refreshFromDisk(ctx.cwd);
     const restored = findRestoredState(ctx);
-    debugLog("index", `session_start reason=${event.reason}`, restored ? { name: restored.name, intent: restored.intent } : void 0);
+    const diskPrevious = event.reason === "new" ? findPreviousSessionRoleState(event.previousSessionFile) : void 0;
+    const memoryPrevious = event.reason === "new" ? takeProcessTransfer(event.previousSessionFile) : void 0;
+    const previous = pickPreviousSessionRoleState(diskPrevious, memoryPrevious);
+    debugLog("index", `session_start reason=${event.reason}`, {
+      restored: restored ? { name: restored.name, intent: restored.intent } : void 0,
+      previousActiveRole: previous?.activeRole?.name,
+      previousResetRole: previous?.pendingResetRole?.name
+    });
     let targetName;
     let preservedIntent;
     let silent = false;
-    if (state.pendingRoleAfterReset) {
-      targetName = state.pendingRoleAfterReset;
-      state.pendingRoleAfterReset = null;
-    } else if ((event.reason === "reload" || event.reason === "resume") && restored) {
+    if ((event.reason === "reload" || event.reason === "resume") && restored) {
       targetName = restored.name;
       preservedIntent = restored.intent;
       silent = true;
+    } else if (event.reason === "new" && previous?.pendingResetRole) {
+      targetName = previous.pendingResetRole.name;
+    } else if (event.reason === "new") {
+      targetName = pickNewSessionRoleName(
+        previous?.activeRole ?? null,
+        pi,
+        state.settings,
+        state.roles
+      );
     } else {
-      targetName = event.reason === "new" ? pickNewSessionRoleName(state.activeRole, pi, state.settings, state.roles) : pickInitialRoleName(pi, state.settings, state.roles);
+      targetName = pickInitialRoleName(pi, state.settings, state.roles);
       silent = event.reason === "startup";
     }
     state.intent = preservedIntent;
@@ -800,10 +847,14 @@ function index_default(pi) {
       const wantsReset = tokens.includes("--reset");
       const name = sub;
       if (wantsReset) {
-        state.pendingRoleAfterReset = name;
+        const request = { name, requestedAt: Date.now() };
+        state.pendingResetRequest = request;
+        pi.appendEntry(RESET_ROLE_REQUEST_ENTRY_TYPE, request);
         const result = await resetSession(ctx);
         if (result.cancelled) {
-          state.pendingRoleAfterReset = null;
+          state.pendingResetRequest = void 0;
+          discardProcessTransfer(ctx.sessionManager.getSessionFile());
+          pi.appendEntry(RESET_ROLE_CANCELLED_ENTRY_TYPE, { cancelledAt: Date.now() });
           ctx.ui.notify(`Role switch to "${name}" cancelled.`, "info");
         }
         return;
@@ -843,14 +894,72 @@ function findRestoredState(ctx) {
   } catch {
     return void 0;
   }
+  return findActiveRoleState(entries);
+}
+function pickPreviousSessionRoleState(diskState, processState) {
+  return hasPreviousRoleState(diskState) ? diskState : processState ?? diskState;
+}
+function hasPreviousRoleState(state) {
+  return !!state && (!!state.activeRole || !!state.pendingResetRole);
+}
+function activeRoleStateFromResolved(role, intent) {
+  return {
+    name: role.name,
+    source: role.source,
+    path: role.path,
+    intent,
+    appliedAt: Date.now()
+  };
+}
+function findPreviousSessionRoleState(previousSessionFile) {
+  if (!previousSessionFile) return void 0;
+  try {
+    return resolvePreviousSessionRoleState(SessionManager.open(previousSessionFile).getEntries());
+  } catch (err) {
+    debugLog("index", `could not read previous session ${previousSessionFile}`, String(err));
+    return void 0;
+  }
+}
+function resolvePreviousSessionRoleState(entries) {
+  let pendingResetRole;
   for (let i = entries.length - 1; i >= 0; i--) {
-    const e = entries[i];
-    if (e && e.type === "custom" && e.customType === ACTIVE_ROLE_ENTRY_TYPE) {
-      return e.data ?? void 0;
+    const entry = entries[i];
+    if (!entry || entry.type !== "custom") continue;
+    if (entry.customType === RESET_ROLE_CANCELLED_ENTRY_TYPE) break;
+    if (entry.customType === RESET_ROLE_REQUEST_ENTRY_TYPE) {
+      const request = asResetRoleRequest(entry.data);
+      if (request) pendingResetRole = request;
+      break;
+    }
+  }
+  return { activeRole: findActiveRoleState(entries), pendingResetRole };
+}
+function findActiveRoleState(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry?.type === "custom" && entry.customType === ACTIVE_ROLE_ENTRY_TYPE) {
+      const state = asActiveRoleState(entry.data);
+      if (state) return state;
     }
   }
   return void 0;
 }
+function asActiveRoleState(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const candidate = data;
+  if (typeof candidate.name !== "string" || candidate.name.length === 0 || typeof candidate.source !== "string" || typeof candidate.path !== "string" || typeof candidate.appliedAt !== "number" || candidate.intent !== void 0 && typeof candidate.intent !== "string") {
+    return void 0;
+  }
+  return candidate;
+}
+function asResetRoleRequest(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const candidate = data;
+  if (typeof candidate.name !== "string" || candidate.name.trim().length === 0 || typeof candidate.requestedAt !== "number") {
+    return void 0;
+  }
+  return { name: candidate.name, requestedAt: candidate.requestedAt };
+}
 async function applyResolved(pi, ctx, state, name, options) {
   let resolved;
   try {
@@ -951,7 +1060,10 @@ function subcommandDescription(sub) {
 export {
   composeSystemPrompt,
   index_default as default,
+  findPreviousSessionRoleState,
   pickInitialRoleName,
   pickNewSessionRoleName,
+  pickPreviousSessionRoleState,
+  resolvePreviousSessionRoleState,
   roleCompletions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkzhb/pi-roles",
-  "version": "0.2.4-beta.1",
+  "version": "0.2.4-beta.2",
   "description": "Role-based session configuration for pi coding agent. Launch a session as a named role and hot-swap roles mid-session, with optional pi-intercom and pi-mcp-adapter integration.",
   "keywords": [
     "pi-package",