@parall/parall 1.26.3 → 1.28.0

package/dist/config-manager.js

@@ -71,7 +71,7 @@ function applyToOpenClawConfig(configPath, platformConfig, credentials) {
     // Strip keys OpenClaw doesn't recognize from agents.defaults — platform-only
     // keys like thinking_effort are consumed by agent-core's PlatformConfigManager.
     // See: OpenClaw agents.defaults config schema.
-    const OPENCLAW_AGENTS_DEFAULTS_KEYS = new Set(["model", "compaction"]);
+    const OPENCLAW_AGENTS_DEFAULTS_KEYS = new Set(["model", "compaction", "memorySearch"]);
     // Unconditionally sanitize existing defaults to self-heal already-poisoned
     // openclaw.json files (e.g. mode=self agents that were poisoned while in
     // platform mode).

package/dist/fork.d.ts

@@ -4,6 +4,7 @@ export type ForkSessionResult = {
     sessionFile: string;
 };
 export declare function resolveTranscriptFile(sessionsDir: string, sessionKey: string): string | null;
+export declare function resolveSessionId(sessionsDir: string, sessionKey: string): string | null;
 /**
  * Fork the orchestrator session's transcript into a new parallel session.
  *

package/dist/fork.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA+CF,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB5F;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,sBAAsB,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,iBAAiB,GAAG,IAAI,CA+D3B;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,IAAI,CASP"}
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../src/fork.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA+CF,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqB5F;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvF;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,sBAAsB,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,iBAAiB,GAAG,IAAI,CA+D3B;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,IAAI,CASP"}

package/dist/fork.js

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { CURRENT_SESSION_VERSION, SessionManager } from "@mariozechner/pi-coding-agent";
+import { CURRENT_SESSION_VERSION, SessionManager } from "./oc-session.js";
 function readStoreEntry(sessionsDir, sessionKey) {
     const storeFile = path.join(sessionsDir, "sessions.json");
     try {
@@ -73,6 +73,10 @@ export function resolveTranscriptFile(sessionsDir, sessionKey) {
         return null;
     }
 }
+export function resolveSessionId(sessionsDir, sessionKey) {
+    const entry = readStoreEntry(sessionsDir, sessionKey);
+    return entry?.sessionId?.trim() || null;
+}
 // ---------------------------------------------------------------------------
 // Fork creation
 // ---------------------------------------------------------------------------

package/dist/gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAsBnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA6NxD,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CA2HtE,CAAC"}
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,uGAAuG;AACvG,KAAK,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAuBnF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAkQxD,eAAO,MAAM,aAAa,EAAE,qBAAqB,CAAC,qBAAqB,CAiItE,CAAC"}

package/dist/gateway.js

@@ -4,12 +4,12 @@ import * as crypto from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveParallAccount } from "./accounts.js";
-import { getParallRuntime, removeParallAccountState, setAgentIdentity, setDispatchGroupKey, setParallAccountState, } from "./runtime.js";
+import { getParallRuntime, removeParallAccountState, setAgentIdentity, setAgentSessionBinding, setDispatchGroupKey, setParallAccountState, } from "./runtime.js";
 import { buildOrchestratorSessionKey } from "./session.js";
 import { fetchAndApplyPlatformConfig } from "./config-manager.js";
 import { startWikiHelper } from "./wiki-helper.js";
-import { SessionManager } from "@mariozechner/pi-coding-agent";
-import { cleanupForkSession, forkOrchestratorSession, resolveTranscriptFile } from "./fork.js";
+import { SessionManager } from "./oc-session.js";
+import { cleanupForkSession, forkOrchestratorSession, resolveSessionId, resolveTranscriptFile } from "./fork.js";
 function resolveWsUrl(account) {
     if (account.config.ws_url)
         return account.config.ws_url;
@@ -107,7 +107,9 @@ function createRuntimeEventStream() {
         },
         fail(err) {
             failure = err;
-            flush();
+            while (waiters.length > 0) {
+                waiters.shift().reject(err);
+            }
         },
         async *stream() {
             while (true) {
@@ -129,6 +131,19 @@ function createRuntimeEventStream() {
         },
     };
 }
+async function waitForOpenClawSessionId(sessionsDir, sessionKey, timeoutMs = 10_000) {
+    const existing = resolveSessionId(sessionsDir, sessionKey);
+    if (existing)
+        return existing;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        const sessionId = resolveSessionId(sessionsDir, sessionKey);
+        if (sessionId)
+            return sessionId;
+    }
+    return null;
+}
 function createOpenClawDispatchAdapter(opts) {
     return {
         async *dispatch({ event, earlierEvents = [], bodyForAgent, sessionKey }) {
@@ -172,6 +187,26 @@ function createOpenClawDispatchAdapter(opts) {
                 },
             });
             run.then(() => stream.end()).catch((err) => stream.fail(err));
+            let sessionId;
+            try {
+                sessionId = await Promise.race([
+                    waitForOpenClawSessionId(opts.sessionsDir, sessionKey),
+                    run.then(() => null, (err) => { throw err; }),
+                ]);
+            }
+            catch {
+                sessionId = null;
+            }
+            if (!sessionId) {
+                stream.fail(new Error(`OpenClaw did not expose a sessionId for ${sessionKey}`));
+            }
+            else {
+                yield {
+                    type: "runtime_session",
+                    runtimeSessionId: sessionId,
+                    runtimeLaneKey: sessionKey,
+                };
+            }
             yield* stream.stream();
         },
         getBranchPoint(sessionKey) {
@@ -307,11 +342,17 @@ export const parallGateway = {
                     orgId: config.org_id,
                     agentUserId,
                     activeSessionId,
+                    sessionBindings: new Map(),
+                    sessionsDir,
+                    runtimeRef: { hostname: os.hostname(), pid: process.pid },
                     wikiMountRoot,
                     ws,
                     orchestratorSessionKey: orchestratorKey,
                 });
             },
+            onSessionBinding: async ({ sessionKey, agentSessionId }) => {
+                setAgentSessionBinding(ctx.accountId, sessionKey, agentSessionId);
+            },
             onBeforeDisconnect: async () => {
                 stopWikiHelper?.();
                 removeParallAccountState(ctx.accountId);

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA6D7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QAiIzD"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA4F7D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,QAqIzD"}

package/dist/hooks.js

@@ -1,6 +1,7 @@
 import { PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity } from "@parall/agent-core";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { clearDispatchGroupKey, getAgentIdentity, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId } from "./runtime.js";
+import { clearDispatchGroupKey, getAgentIdentity, getAgentSessionBinding, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId, setAgentSessionBinding } from "./runtime.js";
+import { resolveSessionId } from "./fork.js";
 /**
  * Map the session's stored target ID (whatever the current dispatch routed
  * to — chat, task, or schedule) to the `target_type` field on agent_step.
@@ -19,7 +20,7 @@ function stepTargetType(targetId) {
  * Resolve the ParallClient + orgId + sessionId for a hook context.
  * Returns undefined if the account/session is not active.
  */
-function resolveClientForHook(sessionKey) {
+async function resolveClientForHook(sessionKey) {
     if (!sessionKey)
         return undefined;
     const chatId = getSessionChatId(sessionKey);
@@ -31,7 +32,37 @@ function resolveClientForHook(sessionKey) {
     const state = getParallAccountState(accountId);
     if (!state)
         return undefined;
-    return { ...state, chatId, sessionId: state.activeSessionId };
+    let sessionId = getAgentSessionBinding(accountId, sessionKey);
+    if (!sessionId && sessionKey === state.orchestratorSessionKey) {
+        sessionId = state.activeSessionId;
+    }
+    if (!sessionId && state.sessionsDir) {
+        const runtimeSessionId = resolveSessionId(state.sessionsDir, sessionKey);
+        if (runtimeSessionId) {
+            const parentSessionId = sessionKey === state.orchestratorSessionKey
+                ? undefined
+                : state.orchestratorSessionKey
+                    ? getAgentSessionBinding(accountId, state.orchestratorSessionKey)
+                    : undefined;
+            try {
+                const session = await state.client.createAgentSession(state.orgId, state.agentUserId, {
+                    runtime_type: "openclaw",
+                    runtime_key: sessionKey,
+                    runtime_lane_key: sessionKey,
+                    runtime_session_id: runtimeSessionId,
+                    parent_session_id: parentSessionId,
+                    runtime_ref: state.runtimeRef,
+                });
+                sessionId = session.id;
+                setAgentSessionBinding(accountId, sessionKey, session.id);
+            }
+            catch {
+                // Hook step creation is best-effort; the gateway binding path will log
+                // the dispatch-level failure if the session cannot be created.
+            }
+        }
+    }
+    return { ...state, chatId, sessionId };
 }
 const PRLL_CHANNEL_CONTEXT = `## Parall Channel — Message Delivery
 
@@ -79,7 +110,7 @@ export function registerParallHooks(api) {
         const sessionKey = ctx.sessionKey;
         // (1) Create tool_call step and await to get step ID
         let stepId;
-        const resolved = resolveClientForHook(sessionKey);
+        const resolved = await resolveClientForHook(sessionKey);
         if (resolved?.sessionId && event.toolCallId) {
             const groupKey = sessionKey ? getDispatchGroupKey(sessionKey) : undefined;
             try {
@@ -122,8 +153,12 @@ export function registerParallHooks(api) {
         injectedEnv.PRLL_API_KEY = state.apiKey;
         injectedEnv.PRLL_ORG_ID = state.orgId;
         injectedEnv.PRLL_AGENT_ID = state.agentUserId;
-        if (state.activeSessionId)
+        if (resolved?.sessionId) {
+            injectedEnv.PRLL_SESSION_ID = resolved.sessionId;
+        }
+        else if (state.activeSessionId) {
             injectedEnv.PRLL_SESSION_ID = state.activeSessionId;
+        }
         if (stepId)
             injectedEnv.PRLL_STEP_ID = stepId;
         if (chatId) {
@@ -161,7 +196,7 @@ export function registerParallHooks(api) {
     });
     // after_tool_call -> send tool_result step to AgentSession
     api.on("after_tool_call", async (event, ctx) => {
-        const resolved = resolveClientForHook(ctx.sessionKey);
+        const resolved = await resolveClientForHook(ctx.sessionKey);
         if (!resolved?.sessionId || !event.toolCallId)
             return;
         try {

package/dist/oc-session.d.ts

@@ -0,0 +1,27 @@
+export declare const CURRENT_SESSION_VERSION = 3;
+export declare class SessionManager {
+    private sessionId;
+    private sessionFile;
+    private readonly sessionDir;
+    private readonly cwd;
+    private fileEntries;
+    private byId;
+    private labelsById;
+    private labelTimestampsById;
+    private leafId;
+    private flushed;
+    private constructor();
+    private load;
+    private initEmpty;
+    private buildIndex;
+    private rewrite;
+    getLeafId(): string | null;
+    getCwd(): string;
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    private getBranch;
+    createBranchedSession(leafId: string): string | undefined;
+    static open(path: string): SessionManager;
+}
+//# sourceMappingURL=oc-session.d.ts.map

package/dist/oc-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oc-session.d.ts","sourceRoot":"","sources":["../src/oc-session.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAkHzC,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,IAAI,CAAmC;IAC/C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO;IAeP,OAAO,CAAC,IAAI;IA+BZ,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,UAAU;IAsBlB,OAAO,CAAC,OAAO;IAOf,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,MAAM,IAAI,MAAM;IAIhB,aAAa,IAAI,MAAM;IAIvB,YAAY,IAAI,MAAM;IAItB,cAAc,IAAI,MAAM,GAAG,SAAS;IAMpC,OAAO,CAAC,SAAS;IAWjB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA+DzD,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;CAO1C"}

package/dist/oc-session.js

@@ -0,0 +1,281 @@
+// Minimal subset of OpenClaw's SessionManager inlined to avoid a runtime
+// dependency on @mariozechner/pi-coding-agent (14 MB + 100 MB transitive).
+//
+// Covers only: open → getLeafId / createBranchedSession / accessors.
+// Sync check: when bumping devDependencies.openclaw, diff upstream
+// pi-coding-agent/dist/core/session-manager.js for new migration steps
+// or structural changes to createBranchedSession / _buildIndex.
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+export const CURRENT_SESSION_VERSION = 3;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function generateId(existing) {
+    for (let i = 0; i < 100; i++) {
+        const id = randomUUID().slice(0, 8);
+        if (!existing.has(id))
+            return id;
+    }
+    return randomUUID();
+}
+function loadEntries(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const lines = readFileSync(filePath, "utf-8").trim().split("\n");
+    const entries = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    if (entries.length === 0)
+        return entries;
+    const h = entries[0];
+    if (h.type !== "session" || typeof h.id !== "string")
+        return [];
+    return entries;
+}
+// -- Migrations (v1→v2→v3) --------------------------------------------------
+function migrateV1ToV2(entries) {
+    const ids = new Set();
+    let prevId = null;
+    for (const entry of entries) {
+        if (entry.type === "session") {
+            entry.version = 2;
+            continue;
+        }
+        const e = entry;
+        e.id = generateId(ids);
+        ids.add(e.id);
+        e.parentId = prevId;
+        prevId = e.id;
+        if (e.type === "compaction") {
+            const comp = e;
+            if (typeof comp.firstKeptEntryIndex === "number") {
+                const target = entries[comp.firstKeptEntryIndex];
+                if (target && target.type !== "session") {
+                    comp.firstKeptEntryId = target.id;
+                }
+                delete comp.firstKeptEntryIndex;
+            }
+        }
+    }
+}
+function migrateV2ToV3(entries) {
+    for (const entry of entries) {
+        if (entry.type === "session") {
+            entry.version = 3;
+            continue;
+        }
+        const e = entry;
+        if (e.type === "message" && e.message && e.message.role === "hookMessage") {
+            e.message.role = "custom";
+        }
+    }
+}
+function migrate(entries) {
+    const header = entries.find((e) => e.type === "session");
+    const version = header?.version ?? 1;
+    if (version >= CURRENT_SESSION_VERSION)
+        return false;
+    if (version < 2)
+        migrateV1ToV2(entries);
+    if (version < 3)
+        migrateV2ToV3(entries);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// SessionManager (read-only subset + createBranchedSession)
+// ---------------------------------------------------------------------------
+export class SessionManager {
+    sessionId = "";
+    sessionFile;
+    sessionDir;
+    cwd;
+    fileEntries = [];
+    byId = new Map();
+    labelsById = new Map();
+    labelTimestampsById = new Map();
+    leafId = null;
+    flushed = false;
+    constructor(cwd, sessionDir, sessionFile) {
+        this.cwd = cwd;
+        this.sessionDir = sessionDir;
+        if (sessionDir && !existsSync(sessionDir)) {
+            mkdirSync(sessionDir, { recursive: true });
+        }
+        if (sessionFile) {
+            this.load(sessionFile);
+        }
+        else {
+            this.initEmpty();
+        }
+    }
+    // -- Init / load -----------------------------------------------------------
+    load(file) {
+        this.sessionFile = resolve(file);
+        if (!existsSync(this.sessionFile)) {
+            const p = this.sessionFile;
+            this.initEmpty();
+            this.sessionFile = p;
+            return;
+        }
+        this.fileEntries = loadEntries(this.sessionFile);
+        if (this.fileEntries.length === 0) {
+            const p = this.sessionFile;
+            this.initEmpty();
+            this.sessionFile = p;
+            this.rewrite();
+            this.flushed = true;
+            return;
+        }
+        const header = this.fileEntries.find((e) => e.type === "session");
+        if (header && header.version > CURRENT_SESSION_VERSION) {
+            throw new Error(`Session file ${this.sessionFile} uses version ${header.version}, ` +
+                `but oc-session.ts only supports up to ${CURRENT_SESSION_VERSION}. ` +
+                `Sync oc-session.ts with upstream pi-coding-agent (see AGENTS.md step 4).`);
+        }
+        this.sessionId = header?.id ?? randomUUID();
+        if (migrate(this.fileEntries))
+            this.rewrite();
+        this.buildIndex();
+        this.flushed = true;
+    }
+    initEmpty() {
+        this.sessionId = randomUUID();
+        const timestamp = new Date().toISOString();
+        this.fileEntries = [
+            { type: "session", version: CURRENT_SESSION_VERSION, id: this.sessionId, timestamp, cwd: this.cwd },
+        ];
+        this.byId.clear();
+        this.labelsById.clear();
+        this.leafId = null;
+        this.flushed = false;
+        const ts = timestamp.replace(/[:.]/g, "-");
+        this.sessionFile = join(this.sessionDir, `${ts}_${this.sessionId}.jsonl`);
+    }
+    buildIndex() {
+        this.byId.clear();
+        this.labelsById.clear();
+        this.labelTimestampsById.clear();
+        this.leafId = null;
+        for (const entry of this.fileEntries) {
+            if (entry.type === "session")
+                continue;
+            const e = entry;
+            this.byId.set(e.id, e);
+            this.leafId = e.id;
+            if (e.type === "label") {
+                if (e.label) {
+                    this.labelsById.set(e.targetId, e.label);
+                    this.labelTimestampsById.set(e.targetId, e.timestamp);
+                }
+                else {
+                    this.labelsById.delete(e.targetId);
+                    this.labelTimestampsById.delete(e.targetId);
+                }
+            }
+        }
+    }
+    rewrite() {
+        if (!this.sessionFile)
+            return;
+        writeFileSync(this.sessionFile, this.fileEntries.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    }
+    // -- Public accessors ------------------------------------------------------
+    getLeafId() {
+        return this.leafId;
+    }
+    getCwd() {
+        return this.cwd;
+    }
+    getSessionDir() {
+        return this.sessionDir;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    getSessionFile() {
+        return this.sessionFile;
+    }
+    // -- Branching -------------------------------------------------------------
+    getBranch(fromId) {
+        const path = [];
+        const startId = fromId ?? this.leafId;
+        let current = startId ? this.byId.get(startId) : undefined;
+        while (current) {
+            path.unshift(current);
+            current = current.parentId ? this.byId.get(current.parentId) : undefined;
+        }
+        return path;
+    }
+    createBranchedSession(leafId) {
+        const branch = this.getBranch(leafId);
+        if (branch.length === 0)
+            throw new Error(`Entry ${leafId} not found`);
+        const pathWithoutLabels = branch.filter((e) => e.type !== "label");
+        const newId = randomUUID();
+        const timestamp = new Date().toISOString();
+        const ts = timestamp.replace(/[:.]/g, "-");
+        const newFile = join(this.sessionDir, `${ts}_${newId}.jsonl`);
+        const header = {
+            type: "session",
+            version: CURRENT_SESSION_VERSION,
+            id: newId,
+            timestamp,
+            cwd: this.cwd,
+            parentSession: this.sessionFile,
+        };
+        const pathEntryIds = new Set(pathWithoutLabels.map((e) => e.id));
+        const labelsToWrite = [];
+        for (const [targetId, label] of this.labelsById) {
+            if (pathEntryIds.has(targetId)) {
+                labelsToWrite.push({ targetId, label, timestamp: this.labelTimestampsById.get(targetId) });
+            }
+        }
+        const lastEntryId = pathWithoutLabels.at(-1)?.id ?? null;
+        let parentId = lastEntryId;
+        const labelEntries = [];
+        for (const { targetId, label, timestamp: labelTs } of labelsToWrite) {
+            const le = {
+                type: "label",
+                id: generateId(pathEntryIds),
+                parentId,
+                timestamp: labelTs ?? timestamp,
+                targetId,
+                label,
+            };
+            pathEntryIds.add(le.id);
+            labelEntries.push(le);
+            parentId = le.id;
+        }
+        this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
+        this.sessionId = newId;
+        this.sessionFile = newFile;
+        this.buildIndex();
+        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message?.role === "assistant");
+        if (hasAssistant) {
+            this.rewrite();
+            this.flushed = true;
+        }
+        else {
+            this.flushed = false;
+        }
+        return newFile;
+    }
+    // -- Factory ---------------------------------------------------------------
+    static open(path) {
+        const entries = loadEntries(path);
+        const header = entries.find((e) => e.type === "session");
+        const cwd = header?.cwd ?? process.cwd();
+        const dir = resolve(path, "..");
+        return new SessionManager(cwd, dir, path);
+    }
+}

package/dist/runtime.d.ts

@@ -10,6 +10,9 @@ export type ParallAccountState = {
     orgId: string;
     agentUserId: string;
     activeSessionId?: string;
+    sessionBindings?: Map<string, string>;
+    sessionsDir?: string;
+    runtimeRef?: Record<string, unknown>;
     wikiMountRoot?: string;
     ws?: ParallWs;
     orchestratorSessionKey?: string;
@@ -20,6 +23,8 @@ export declare function getParallRuntime(): PluginRuntime;
 export declare function setParallAccountState(accountId: string, state: ParallAccountState): void;
 export declare function removeParallAccountState(accountId: string): void;
 export declare function getParallAccountState(accountId: string): ParallAccountState | undefined;
+export declare function setAgentSessionBinding(accountId: string, sessionKey: string, agentSessionId: string): void;
+export declare function getAgentSessionBinding(accountId: string, sessionKey: string): string | undefined;
 export declare function getAllParallAccountStates(): ReadonlyMap<string, ParallAccountState>;
 export declare function setAgentIdentity(identity: AgentIdentity): void;
 export declare function getAgentIdentity(): AgentIdentity | undefined;

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,QAEnD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAKD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,QAEjF;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,QAEzD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEvF;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,QAMnG;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED,wBAAgB,yBAAyB,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAEnF;AAID,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,QAEvD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}

package/dist/runtime.js

@@ -20,6 +20,17 @@ export function removeParallAccountState(accountId) {
 export function getParallAccountState(accountId) {
     return accountStates.get(accountId);
 }
+export function setAgentSessionBinding(accountId, sessionKey, agentSessionId) {
+    const state = accountStates.get(accountId);
+    if (!state)
+        return;
+    const sessionBindings = state.sessionBindings ?? new Map();
+    sessionBindings.set(sessionKey, agentSessionId);
+    accountStates.set(accountId, { ...state, sessionBindings });
+}
+export function getAgentSessionBinding(accountId, sessionKey) {
+    return accountStates.get(accountId)?.sessionBindings?.get(sessionKey);
+}
 export function getAllParallAccountStates() {
     return new Map(accountStates);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.26.3",
+  "version": "1.28.0",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -16,8 +16,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.26.3",
-    "@parall/sdk": "1.26.3"
+    "@parall/agent-core": "1.28.0",
+    "@parall/sdk": "1.28.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -25,7 +25,6 @@
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
     "openclaw": ">=2026.5.7"
   },
   "openclaw": {

package/src/config-manager.ts

@@ -99,7 +99,7 @@ function applyToOpenClawConfig(
   // Strip keys OpenClaw doesn't recognize from agents.defaults — platform-only
   // keys like thinking_effort are consumed by agent-core's PlatformConfigManager.
   // See: OpenClaw agents.defaults config schema.
-  const OPENCLAW_AGENTS_DEFAULTS_KEYS = new Set(["model", "compaction"]);
+  const OPENCLAW_AGENTS_DEFAULTS_KEYS = new Set(["model", "compaction", "memorySearch"]);
 
   // Unconditionally sanitize existing defaults to self-heal already-poisoned
   // openclaw.json files (e.g. mode=self agents that were poisoned while in

package/src/fork.ts

@@ -10,7 +10,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { CURRENT_SESSION_VERSION, SessionManager } from "@mariozechner/pi-coding-agent";
+import { CURRENT_SESSION_VERSION, SessionManager } from "./oc-session.js";
 
 export type ForkSessionResult = {
   sessionKey: string;
@@ -86,6 +86,11 @@ export function resolveTranscriptFile(sessionsDir: string, sessionKey: string):
   }
 }
 
+export function resolveSessionId(sessionsDir: string, sessionKey: string): string | null {
+  const entry = readStoreEntry(sessionsDir, sessionKey);
+  return entry?.sessionId?.trim() || null;
+}
+
 // ---------------------------------------------------------------------------
 // Fork creation
 // ---------------------------------------------------------------------------

package/src/gateway.ts

@@ -20,6 +20,7 @@ import {
   getParallRuntime,
   removeParallAccountState,
   setAgentIdentity,
+  setAgentSessionBinding,
   setDispatchGroupKey,
   setParallAccountState,
 } from "./runtime.js";
@@ -27,8 +28,8 @@ import { buildOrchestratorSessionKey } from "./session.js";
 import type { ResolvedParallAccount } from "./types.js";
 import { fetchAndApplyPlatformConfig } from "./config-manager.js";
 import { startWikiHelper } from "./wiki-helper.js";
-import { SessionManager } from "@mariozechner/pi-coding-agent";
-import { cleanupForkSession, forkOrchestratorSession, resolveTranscriptFile } from "./fork.js";
+import { SessionManager } from "./oc-session.js";
+import { cleanupForkSession, forkOrchestratorSession, resolveSessionId, resolveTranscriptFile } from "./fork.js";
 
 function resolveWsUrl(account: ResolvedParallAccount): string {
   if (account.config.ws_url) return account.config.ws_url;
@@ -139,7 +140,9 @@ function createRuntimeEventStream() {
     },
     fail(err: unknown) {
       failure = err;
-      flush();
+      while (waiters.length > 0) {
+        waiters.shift()!.reject(err);
+      }
     },
     async *stream(): AsyncGenerator<RuntimeEvent> {
       while (true) {
@@ -160,6 +163,23 @@ function createRuntimeEventStream() {
   };
 }
 
+async function waitForOpenClawSessionId(
+  sessionsDir: string,
+  sessionKey: string,
+  timeoutMs = 10_000,
+): Promise<string | null> {
+  const existing = resolveSessionId(sessionsDir, sessionKey);
+  if (existing) return existing;
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const sessionId = resolveSessionId(sessionsDir, sessionKey);
+    if (sessionId) return sessionId;
+  }
+  return null;
+}
+
 function createOpenClawDispatchAdapter(opts: {
   core: PluginRuntime;
   cfg: Record<string, unknown>;
@@ -208,6 +228,24 @@ function createOpenClawDispatchAdapter(opts: {
       });
 
       run.then(() => stream.end()).catch((err) => stream.fail(err));
+      let sessionId: string | null;
+      try {
+        sessionId = await Promise.race([
+          waitForOpenClawSessionId(opts.sessionsDir, sessionKey),
+          run.then(() => null as string | null, (err) => { throw err; }),
+        ]);
+      } catch {
+        sessionId = null;
+      }
+      if (!sessionId) {
+        stream.fail(new Error(`OpenClaw did not expose a sessionId for ${sessionKey}`));
+      } else {
+        yield {
+          type: "runtime_session",
+          runtimeSessionId: sessionId,
+          runtimeLaneKey: sessionKey,
+        };
+      }
       yield* stream.stream();
     },
 
@@ -348,11 +386,17 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
           orgId: config.org_id,
           agentUserId,
           activeSessionId,
+          sessionBindings: new Map<string, string>(),
+          sessionsDir,
+          runtimeRef: { hostname: os.hostname(), pid: process.pid },
           wikiMountRoot,
           ws,
           orchestratorSessionKey: orchestratorKey,
         });
       },
+      onSessionBinding: async ({ sessionKey, agentSessionId }) => {
+        setAgentSessionBinding(ctx.accountId, sessionKey, agentSessionId);
+      },
       onBeforeDisconnect: async () => {
         stopWikiHelper?.();
         removeParallAccountState(ctx.accountId);

package/src/hooks.ts

@@ -1,7 +1,8 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity } from "@parall/agent-core";
 import { extractAccountIdFromSessionKey } from "./session.js";
-import { clearDispatchGroupKey, getAgentIdentity, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId } from "./runtime.js";
+import { clearDispatchGroupKey, getAgentIdentity, getAgentSessionBinding, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId, setAgentSessionBinding } from "./runtime.js";
+import { resolveSessionId } from "./fork.js";
 
 /**
  * Map the session's stored target ID (whatever the current dispatch routed
@@ -19,7 +20,7 @@ function stepTargetType(targetId: string): string {
  * Resolve the ParallClient + orgId + sessionId for a hook context.
  * Returns undefined if the account/session is not active.
  */
-function resolveClientForHook(sessionKey: string | undefined) {
+async function resolveClientForHook(sessionKey: string | undefined) {
   if (!sessionKey) return undefined;
   const chatId = getSessionChatId(sessionKey);
   if (!chatId) return undefined;
@@ -29,7 +30,37 @@ function resolveClientForHook(sessionKey: string | undefined) {
   const state = getParallAccountState(accountId);
   if (!state) return undefined;
 
-  return { ...state, chatId, sessionId: state.activeSessionId };
+  let sessionId = getAgentSessionBinding(accountId, sessionKey);
+  if (!sessionId && sessionKey === state.orchestratorSessionKey) {
+    sessionId = state.activeSessionId;
+  }
+  if (!sessionId && state.sessionsDir) {
+    const runtimeSessionId = resolveSessionId(state.sessionsDir, sessionKey);
+    if (runtimeSessionId) {
+      const parentSessionId = sessionKey === state.orchestratorSessionKey
+        ? undefined
+        : state.orchestratorSessionKey
+          ? getAgentSessionBinding(accountId, state.orchestratorSessionKey)
+          : undefined;
+      try {
+        const session = await state.client.createAgentSession(state.orgId, state.agentUserId, {
+          runtime_type: "openclaw",
+          runtime_key: sessionKey,
+          runtime_lane_key: sessionKey,
+          runtime_session_id: runtimeSessionId,
+          parent_session_id: parentSessionId,
+          runtime_ref: state.runtimeRef,
+        });
+        sessionId = session.id;
+        setAgentSessionBinding(accountId, sessionKey, session.id);
+      } catch {
+        // Hook step creation is best-effort; the gateway binding path will log
+        // the dispatch-level failure if the session cannot be created.
+      }
+    }
+  }
+
+  return { ...state, chatId, sessionId };
 }
 
 const PRLL_CHANNEL_CONTEXT = `## Parall Channel — Message Delivery
@@ -82,7 +113,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
     // (1) Create tool_call step and await to get step ID
     let stepId: string | undefined;
-    const resolved = resolveClientForHook(sessionKey);
+    const resolved = await resolveClientForHook(sessionKey);
     if (resolved?.sessionId && event.toolCallId) {
       const groupKey = sessionKey ? getDispatchGroupKey(sessionKey) : undefined;
       try {
@@ -122,7 +153,11 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     injectedEnv.PRLL_API_KEY = state.apiKey;
     injectedEnv.PRLL_ORG_ID = state.orgId;
     injectedEnv.PRLL_AGENT_ID = state.agentUserId;
-    if (state.activeSessionId) injectedEnv.PRLL_SESSION_ID = state.activeSessionId;
+    if (resolved?.sessionId) {
+      injectedEnv.PRLL_SESSION_ID = resolved.sessionId;
+    } else if (state.activeSessionId) {
+      injectedEnv.PRLL_SESSION_ID = state.activeSessionId;
+    }
     if (stepId) injectedEnv.PRLL_STEP_ID = stepId;
     if (chatId) {
       if (chatId.startsWith("sch_")) {
@@ -159,7 +194,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
 
   // after_tool_call -> send tool_result step to AgentSession
   api.on("after_tool_call", async (event, ctx) => {
-    const resolved = resolveClientForHook(ctx.sessionKey);
+    const resolved = await resolveClientForHook(ctx.sessionKey);
     if (!resolved?.sessionId || !event.toolCallId) return;
     try {
       await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {

package/src/oc-session.ts

@@ -0,0 +1,337 @@
+// Minimal subset of OpenClaw's SessionManager inlined to avoid a runtime
+// dependency on @mariozechner/pi-coding-agent (14 MB + 100 MB transitive).
+//
+// Covers only: open → getLeafId / createBranchedSession / accessors.
+// Sync check: when bumping devDependencies.openclaw, diff upstream
+// pi-coding-agent/dist/core/session-manager.js for new migration steps
+// or structural changes to createBranchedSession / _buildIndex.
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+
+export const CURRENT_SESSION_VERSION = 3;
+
+// ---------------------------------------------------------------------------
+// Types (minimal)
+// ---------------------------------------------------------------------------
+
+interface SessionHeader {
+  type: "session";
+  version: number;
+  id: string;
+  timestamp: string;
+  cwd?: string;
+  parentSession?: string;
+}
+
+interface SessionEntry {
+  type: string;
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+  // label entries
+  targetId?: string;
+  label?: string;
+  // message entries
+  message?: { role: string };
+  [key: string]: unknown;
+}
+
+type AnyEntry = SessionHeader | SessionEntry;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function generateId(existing: Map<string, unknown> | Set<string>): string {
+  for (let i = 0; i < 100; i++) {
+    const id = randomUUID().slice(0, 8);
+    if (!existing.has(id)) return id;
+  }
+  return randomUUID();
+}
+
+function loadEntries(filePath: string): AnyEntry[] {
+  if (!existsSync(filePath)) return [];
+  const lines = readFileSync(filePath, "utf-8").trim().split("\n");
+  const entries: AnyEntry[] = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+  }
+  if (entries.length === 0) return entries;
+  const h = entries[0] as Record<string, unknown>;
+  if (h.type !== "session" || typeof h.id !== "string") return [];
+  return entries;
+}
+
+// -- Migrations (v1→v2→v3) --------------------------------------------------
+
+function migrateV1ToV2(entries: AnyEntry[]): void {
+  const ids = new Set<string>();
+  let prevId: string | null = null;
+  for (const entry of entries) {
+    if ((entry as SessionHeader).type === "session") {
+      (entry as SessionHeader).version = 2;
+      continue;
+    }
+    const e = entry as SessionEntry;
+    e.id = generateId(ids);
+    ids.add(e.id);
+    e.parentId = prevId;
+    prevId = e.id;
+    if (e.type === "compaction") {
+      const comp = e as Record<string, unknown>;
+      if (typeof comp.firstKeptEntryIndex === "number") {
+        const target = entries[comp.firstKeptEntryIndex as number] as SessionEntry | undefined;
+        if (target && target.type !== "session") {
+          comp.firstKeptEntryId = target.id;
+        }
+        delete comp.firstKeptEntryIndex;
+      }
+    }
+  }
+}
+
+function migrateV2ToV3(entries: AnyEntry[]): void {
+  for (const entry of entries) {
+    if ((entry as SessionHeader).type === "session") {
+      (entry as SessionHeader).version = 3;
+      continue;
+    }
+    const e = entry as SessionEntry;
+    if (e.type === "message" && e.message && (e.message as Record<string, unknown>).role === "hookMessage") {
+      (e.message as Record<string, unknown>).role = "custom";
+    }
+  }
+}
+
+function migrate(entries: AnyEntry[]): boolean {
+  const header = entries.find((e) => e.type === "session") as SessionHeader | undefined;
+  const version = header?.version ?? 1;
+  if (version >= CURRENT_SESSION_VERSION) return false;
+  if (version < 2) migrateV1ToV2(entries);
+  if (version < 3) migrateV2ToV3(entries);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// SessionManager (read-only subset + createBranchedSession)
+// ---------------------------------------------------------------------------
+
+export class SessionManager {
+  private sessionId = "";
+  private sessionFile: string | undefined;
+  private readonly sessionDir: string;
+  private readonly cwd: string;
+
+  private fileEntries: AnyEntry[] = [];
+  private byId = new Map<string, SessionEntry>();
+  private labelsById = new Map<string, string>();
+  private labelTimestampsById = new Map<string, string>();
+  private leafId: string | null = null;
+  private flushed = false;
+
+  private constructor(cwd: string, sessionDir: string, sessionFile?: string) {
+    this.cwd = cwd;
+    this.sessionDir = sessionDir;
+    if (sessionDir && !existsSync(sessionDir)) {
+      mkdirSync(sessionDir, { recursive: true });
+    }
+    if (sessionFile) {
+      this.load(sessionFile);
+    } else {
+      this.initEmpty();
+    }
+  }
+
+  // -- Init / load -----------------------------------------------------------
+
+  private load(file: string): void {
+    this.sessionFile = resolve(file);
+    if (!existsSync(this.sessionFile)) {
+      const p = this.sessionFile;
+      this.initEmpty();
+      this.sessionFile = p;
+      return;
+    }
+    this.fileEntries = loadEntries(this.sessionFile);
+    if (this.fileEntries.length === 0) {
+      const p = this.sessionFile;
+      this.initEmpty();
+      this.sessionFile = p;
+      this.rewrite();
+      this.flushed = true;
+      return;
+    }
+    const header = this.fileEntries.find((e) => e.type === "session") as SessionHeader | undefined;
+    if (header && header.version > CURRENT_SESSION_VERSION) {
+      throw new Error(
+        `Session file ${this.sessionFile} uses version ${header.version}, ` +
+        `but oc-session.ts only supports up to ${CURRENT_SESSION_VERSION}. ` +
+        `Sync oc-session.ts with upstream pi-coding-agent (see AGENTS.md step 4).`,
+      );
+    }
+    this.sessionId = header?.id ?? randomUUID();
+    if (migrate(this.fileEntries)) this.rewrite();
+    this.buildIndex();
+    this.flushed = true;
+  }
+
+  private initEmpty(): void {
+    this.sessionId = randomUUID();
+    const timestamp = new Date().toISOString();
+    this.fileEntries = [
+      { type: "session", version: CURRENT_SESSION_VERSION, id: this.sessionId, timestamp, cwd: this.cwd },
+    ];
+    this.byId.clear();
+    this.labelsById.clear();
+    this.leafId = null;
+    this.flushed = false;
+    const ts = timestamp.replace(/[:.]/g, "-");
+    this.sessionFile = join(this.sessionDir, `${ts}_${this.sessionId}.jsonl`);
+  }
+
+  private buildIndex(): void {
+    this.byId.clear();
+    this.labelsById.clear();
+    this.labelTimestampsById.clear();
+    this.leafId = null;
+    for (const entry of this.fileEntries) {
+      if (entry.type === "session") continue;
+      const e = entry as SessionEntry;
+      this.byId.set(e.id, e);
+      this.leafId = e.id;
+      if (e.type === "label") {
+        if (e.label) {
+          this.labelsById.set(e.targetId!, e.label);
+          this.labelTimestampsById.set(e.targetId!, e.timestamp);
+        } else {
+          this.labelsById.delete(e.targetId!);
+          this.labelTimestampsById.delete(e.targetId!);
+        }
+      }
+    }
+  }
+
+  private rewrite(): void {
+    if (!this.sessionFile) return;
+    writeFileSync(this.sessionFile, this.fileEntries.map((e) => JSON.stringify(e)).join("\n") + "\n");
+  }
+
+  // -- Public accessors ------------------------------------------------------
+
+  getLeafId(): string | null {
+    return this.leafId;
+  }
+
+  getCwd(): string {
+    return this.cwd;
+  }
+
+  getSessionDir(): string {
+    return this.sessionDir;
+  }
+
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  getSessionFile(): string | undefined {
+    return this.sessionFile;
+  }
+
+  // -- Branching -------------------------------------------------------------
+
+  private getBranch(fromId?: string | null): SessionEntry[] {
+    const path: SessionEntry[] = [];
+    const startId = fromId ?? this.leafId;
+    let current = startId ? this.byId.get(startId) : undefined;
+    while (current) {
+      path.unshift(current);
+      current = current.parentId ? this.byId.get(current.parentId) : undefined;
+    }
+    return path;
+  }
+
+  createBranchedSession(leafId: string): string | undefined {
+    const branch = this.getBranch(leafId);
+    if (branch.length === 0) throw new Error(`Entry ${leafId} not found`);
+
+    const pathWithoutLabels = branch.filter((e) => e.type !== "label");
+    const newId = randomUUID();
+    const timestamp = new Date().toISOString();
+    const ts = timestamp.replace(/[:.]/g, "-");
+    const newFile = join(this.sessionDir, `${ts}_${newId}.jsonl`);
+
+    const header: SessionHeader = {
+      type: "session",
+      version: CURRENT_SESSION_VERSION,
+      id: newId,
+      timestamp,
+      cwd: this.cwd,
+      parentSession: this.sessionFile,
+    };
+
+    const pathEntryIds = new Set(pathWithoutLabels.map((e) => e.id));
+    const labelsToWrite: { targetId: string; label: string; timestamp?: string }[] = [];
+    for (const [targetId, label] of this.labelsById) {
+      if (pathEntryIds.has(targetId)) {
+        labelsToWrite.push({ targetId, label, timestamp: this.labelTimestampsById.get(targetId) });
+      }
+    }
+
+    const lastEntryId = pathWithoutLabels.at(-1)?.id ?? null;
+    let parentId: string | null = lastEntryId;
+    const labelEntries: SessionEntry[] = [];
+    for (const { targetId, label, timestamp: labelTs } of labelsToWrite) {
+      const le: SessionEntry = {
+        type: "label",
+        id: generateId(pathEntryIds),
+        parentId,
+        timestamp: labelTs ?? timestamp,
+        targetId,
+        label,
+      };
+      pathEntryIds.add(le.id);
+      labelEntries.push(le);
+      parentId = le.id;
+    }
+
+    this.fileEntries = [header as AnyEntry, ...pathWithoutLabels, ...labelEntries];
+    this.sessionId = newId;
+    this.sessionFile = newFile;
+    this.buildIndex();
+
+    const hasAssistant = this.fileEntries.some(
+      (e) => e.type === "message" && (e as SessionEntry).message?.role === "assistant",
+    );
+    if (hasAssistant) {
+      this.rewrite();
+      this.flushed = true;
+    } else {
+      this.flushed = false;
+    }
+    return newFile;
+  }
+
+  // -- Factory ---------------------------------------------------------------
+
+  static open(path: string): SessionManager {
+    const entries = loadEntries(path);
+    const header = entries.find((e) => e.type === "session") as SessionHeader | undefined;
+    const cwd = header?.cwd ?? process.cwd();
+    const dir = resolve(path, "..");
+    return new SessionManager(cwd, dir, path);
+  }
+}

package/src/runtime.ts

@@ -26,6 +26,9 @@ export type ParallAccountState = {
   orgId: string;
   agentUserId: string;
   activeSessionId?: string;
+  sessionBindings?: Map<string, string>;
+  sessionsDir?: string;
+  runtimeRef?: Record<string, unknown>;
   wikiMountRoot?: string;
   ws?: ParallWs;
   orchestratorSessionKey?: string;
@@ -60,6 +63,18 @@ export function getParallAccountState(accountId: string): ParallAccountState | u
   return accountStates.get(accountId);
 }
 
+export function setAgentSessionBinding(accountId: string, sessionKey: string, agentSessionId: string) {
+  const state = accountStates.get(accountId);
+  if (!state) return;
+  const sessionBindings = state.sessionBindings ?? new Map<string, string>();
+  sessionBindings.set(sessionKey, agentSessionId);
+  accountStates.set(accountId, { ...state, sessionBindings });
+}
+
+export function getAgentSessionBinding(accountId: string, sessionKey: string): string | undefined {
+  return accountStates.get(accountId)?.sessionBindings?.get(sessionKey);
+}
+
 export function getAllParallAccountStates(): ReadonlyMap<string, ParallAccountState> {
   return new Map(accountStates);
 }