@pi-harness/pi-harness 0.1.2 → 0.1.4

package/packages/core/src/plugins/runtime.ts

@@ -1,7 +1,8 @@
 import type { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { createAgentSessionFromServices, createAgentSessionRuntime, type AgentSession, type CreateAgentSessionRuntimeFactory } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, type AgentSession, type CreateAgentSessionRuntimeFactory, type SessionManager } from "@earendil-works/pi-coding-agent";
 import { PiRuntime } from "../runtime.js";
+import { assertKnownConfigKeys } from "../config.js";
 
 export interface RuntimePluginConfig {
   thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -11,11 +12,30 @@ export const Config: z<RuntimePluginConfig> = z.object({
   thinkingLevel: z.union(["off", "minimal", "low", "medium", "high", "xhigh", "max"]).default("medium"),
 });
 
+// Cordis disposes the outgoing fiber and applies the replacement concurrently, so an HMR reload
+// would otherwise build a second AgentSession over the same SessionManager while the first is still
+// streaming, interleaving both runs into one JSONL transcript. Each manager therefore has at most
+// one runtime under construction or teardown at a time.
+const sessionManagerGate = new WeakMap<SessionManager, Promise<void>>();
+
+function enterSessionManagerGate(manager: SessionManager): { ready: Promise<void>; release: () => void } {
+  const ready = sessionManagerGate.get(manager) ?? Promise.resolve();
+  let release!: () => void;
+  const held = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  sessionManagerGate.set(manager, ready.then(() => held, () => held));
+  return { ready, release };
+}
+
 export default {
   name: "pi-runtime",
   inject: ["piModels", "piResources", "piSession", "piTools"],
   Config,
   async apply(context: Context, config: RuntimePluginConfig) {
+    assertKnownConfigKeys("pi-runtime", config, ["thinkingLevel"]);
+    const gate = enterSessionManagerGate(context.piSession.manager);
+    await gate.ready;
     const tools = context.piTools.acquire();
     context.effect(() => () => tools.release());
     const requestedTools = [...tools.names, ...tools.customTools.map((tool) => tool.name)];
@@ -30,6 +50,10 @@ export default {
         tools: requestedTools,
         customTools: tools.customTools,
       });
+      if (result.extensionsResult.errors.length > 0) {
+        result.session.dispose();
+        throw new Error(`Pi extensions failed to load:\n${result.extensionsResult.errors.map((failure) => `${failure.path}: ${failure.error}`).join("\n")}`);
+      }
       return { ...result, services, diagnostics: services.diagnostics };
     };
     const sessionRuntime = await createAgentSessionRuntime(createRuntime, {
@@ -39,9 +63,6 @@ export default {
     });
     const runtime = new PiRuntime(sessionRuntime);
     const bindSession = async (session: AgentSession): Promise<void> => {
-      const activeTools = new Set(session.getAllTools().map((tool) => tool.name));
-      const missingTools = requestedTools.filter((name) => !activeTools.has(name));
-      if (missingTools.length > 0) throw new Error(`Pi tools are not registered: ${missingTools.join(", ")}`);
       await session.bindExtensions({
         mode: "print",
         abortHandler: () => {
@@ -51,23 +72,49 @@ export default {
           context.emit("pi/extension-error", error);
         },
       });
+      // Reconciled after binding so a tool an extension registers from session_start is visible here.
+      const registeredTools = session.getAllTools().map((tool) => tool.name);
+      const missingTools = requestedTools.filter((name) => !registeredTools.includes(name));
+      if (missingTools.length > 0) throw new Error(`Pi tools are not registered: ${missingTools.join(", ")}`);
+      // Pi treats the tool list as an allowlist, so anything an extension contributed but the
+      // profile did not name is dropped. Report it rather than letting the tool vanish silently.
+      const activeTools = new Set(session.getActiveToolNames());
+      const droppedTools = registeredTools.filter((name) => !activeTools.has(name));
+      if (droppedTools.length > 0) context.emit("pi/extension-error", { extensionPath: "pi-tools", event: "session_start", error: `Pi tools registered by extensions are not enabled because the profile does not list them: ${droppedTools.join(", ")}; add them to the pi-tools names option to enable them` });
     };
-    context.provide("piRuntime", runtime);
     let unsubscribe: (() => void) | undefined;
     const rebindSession = async (session: AgentSession): Promise<void> => {
       unsubscribe?.();
       await bindSession(session);
       unsubscribe = session.subscribe((event) => {
-        context.emit("pi/session-event", event);
+        // A throwing listener must not unwind back into Pi's event dispatch and kill the run.
+        try {
+          context.emit("pi/session-event", event);
+        } catch (error) {
+          context.emit("pi/extension-error", { extensionPath: "pi/session-event", event: event.type, error: error instanceof Error ? error.message : String(error) });
+        }
       });
     };
-    sessionRuntime.setRebindSession(rebindSession);
-    await rebindSession(sessionRuntime.session);
-    context.effect(() => {
-      return async () => {
-        unsubscribe?.();
-        await runtime.dispose();
-      };
-    });
+    try {
+      context.effect(() => {
+        return async () => {
+          unsubscribe?.();
+          try {
+            await runtime.dispose();
+          } finally {
+            // Released only once teardown has finished, so a replacement fiber cannot build a
+            // second session over this SessionManager while this one is still writing to it.
+            gate.release();
+          }
+        };
+      });
+      context.provide("piRuntime", runtime);
+      sessionRuntime.setRebindSession(rebindSession);
+      await rebindSession(sessionRuntime.session);
+    } catch (error) {
+      await runtime.dispose();
+      gate.release();
+      throw error;
+    }
   },
 };

package/packages/core/src/plugins/secure-audit.ts

@@ -0,0 +1,146 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { resolveExistingWorkspacePath } from "../workspace-path.js";
+
+const maxFiles = 500;
+const maxFileBytes = 512 * 1024;
+const ignoredDirectories = new Set([".git", ".pi", "node_modules", "dist", "build", "coverage"]);
+
+export type AuditSeverity = "critical" | "high" | "medium";
+export type AuditFindingKind = "credential" | "private-key" | "shell-pipeline" | "destructive-command";
+
+export interface AuditFinding {
+  path: string;
+  line: number;
+  severity: AuditSeverity;
+  kind: AuditFindingKind;
+  message: string;
+}
+
+export interface AuditSummary {
+  root: string;
+  scanned: number;
+  skipped: number;
+  total: number;
+  critical: number;
+  high: number;
+  medium: number;
+  changed: boolean;
+  findings: AuditFinding[];
+}
+
+const credentialPattern = /\b(?:sk-[A-Za-z0-9_-]{10,}|gh[pousr]_[A-Za-z0-9]{10,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{12,})\b/iu;
+const privateKeyPattern = /-----BEGIN (?:RSA|EC|OPENSSH|DSA|PGP )?PRIVATE KEY-----/u;
+const assignmentPattern = /^\s*(?:password|secret|api[_-]?key|token)\s*[:=]\s*["']?[^\s"']{8,}/iu;
+const shellPipelinePattern = /\b(?:curl|wget)\b[^\n|]{0,240}\|\s*(?:sh|bash|zsh)\b/iu;
+const destructiveCommandPattern = /\brm\s+-rf(?:\s|$)/iu;
+
+function finding(path: string, line: number, severity: AuditSeverity, kind: AuditFindingKind, message: string): AuditFinding {
+  return { path, line, severity, kind, message };
+}
+
+export function auditText(path: string, source: string): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  source.split("\n").forEach((lineText, index) => {
+    const line = index + 1;
+    if (privateKeyPattern.test(lineText)) findings.push(finding(path, line, "critical", "private-key", "Private key material is present in source text."));
+    else if (credentialPattern.test(lineText) || assignmentPattern.test(lineText))
+      findings.push(finding(path, line, "critical", "credential", "A credential-like value is present in source text."));
+    if (shellPipelinePattern.test(lineText)) findings.push(finding(path, line, "high", "shell-pipeline", "A remote script is piped directly into a shell."));
+    if (destructiveCommandPattern.test(lineText))
+      findings.push(finding(path, line, "high", "destructive-command", "A recursive force delete command is present."));
+  });
+  return findings;
+}
+
+export function summarizeAudit(findings: readonly AuditFinding[], root = ".", scanned = 0, skipped = 0): AuditSummary {
+  const critical = findings.filter((item) => item.severity === "critical").length;
+  const high = findings.filter((item) => item.severity === "high").length;
+  const medium = findings.filter((item) => item.severity === "medium").length;
+  return { root, scanned, skipped, total: findings.length, critical, high, medium, changed: findings.length > 0, findings: [...findings] };
+}
+
+async function workspaceFiles(root: string, current: string, files: string[]): Promise<void> {
+  if (files.length >= maxFiles) return;
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    if (files.length >= maxFiles) return;
+    const fullPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignoredDirectories.has(entry.name)) await workspaceFiles(root, fullPath, files);
+    } else if (entry.isFile()) {
+      files.push(relative(root, fullPath));
+    }
+  }
+}
+
+export async function auditWorkspace(root: string, requested = "."): Promise<AuditSummary> {
+  const resolved = await resolveExistingWorkspacePath(root, requested, "Audit path must stay inside the current workspace");
+  root = resolved.root;
+  const target = resolved.target;
+  const metadata = await stat(target);
+  const files: string[] = [];
+  if (metadata.isFile()) files.push(relative(root, target));
+  else if (metadata.isDirectory()) await workspaceFiles(root, target, files);
+  else throw new Error("Audit target must be a file or directory");
+  const findings: AuditFinding[] = [];
+  let skipped = 0;
+  for (const file of files) {
+    const fullPath = resolve(root, file);
+    const fileMetadata = await stat(fullPath);
+    if (fileMetadata.size > maxFileBytes) {
+      skipped += 1;
+      continue;
+    }
+    const source = await readFile(fullPath, "utf8");
+    if (source.includes("\u0000")) {
+      skipped += 1;
+      continue;
+    }
+    findings.push(...auditText(file || basename(fullPath), source));
+  }
+  return summarizeAudit(findings, relative(root, target) || ".", files.length, skipped);
+}
+
+function emptySummary(): AuditSummary {
+  return summarizeAudit([], ".");
+}
+
+export default {
+  name: "pi-secure-audit",
+  inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: AuditSummary | undefined;
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "security_audit",
+        label: "Security audit",
+        description: "Read-only scan of workspace text files for exposed credentials and dangerous shell commands; findings are value-redacted.",
+        promptSnippet: "audit the workspace for secrets and dangerous commands",
+        parameters: Type.Object({ path: Type.Optional(Type.String({ description: "Workspace-relative file or directory to scan" })) }),
+        async execute(_toolCallId, params): Promise<AgentToolResult<AuditSummary>> {
+          latest = await auditWorkspace(context.piHarnessLaunch.cwd, params.path ?? ".");
+          return {
+            content: [{ type: "text", text: `${latest.total} findings across ${latest.scanned} files (${latest.critical} critical, ${latest.high} high).` }],
+            details: latest,
+          };
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "secure-audit-panel",
+      pluginId: "@pi-harness/core/plugins/secure-audit",
+      title: "Secure Audit",
+      description: "只读扫描工作区中的凭据泄露和危险命令，结果不会显示敏感值。",
+      icon: "⌕",
+      read: () => latest ?? emptySummary(),
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session-bookmarks.ts

@@ -0,0 +1,89 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+const maxLabelLength = 120;
+
+export type SessionBookmark = { id: string; entryId: string; label: string };
+
+export function normalizeBookmarkLabel(value: string): string {
+  const normalized = value.trim();
+  if (normalized.length < 1 || normalized.length > maxLabelLength) throw new Error("Bookmark label must contain 1-120 characters");
+  return normalized;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+export function listSessionBookmarks(entries: readonly unknown[]): SessionBookmark[] {
+  const labels = new Map<string, string>();
+  for (const entry of entries) {
+    const item = record(entry);
+    if (item?.type !== "label" || typeof item.targetId !== "string") continue;
+    if (typeof item.label === "string" && item.label.trim() !== "") labels.set(item.targetId, item.label.trim());
+    else labels.delete(item.targetId);
+  }
+  return [...labels].map(([entryId, label]) => ({ id: entryId, entryId, label }));
+}
+
+export default {
+  name: "pi-session-bookmarks",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    const manager = context.piSession.manager;
+    const readBookmarks = (): SessionBookmark[] => listSessionBookmarks(manager.getEntries());
+    const unregister = context.piTools.register(
+      defineTool({
+        name: "session_bookmarks",
+        label: "Session bookmarks",
+        description: "Add, list, or remove labels on entries in the current Pi session using native session history.",
+        promptSnippet: "bookmark an important point in the current session",
+        parameters: Type.Object({
+          action: Type.Union([Type.Literal("add"), Type.Literal("list"), Type.Literal("remove")]),
+          label: Type.Optional(Type.String({ description: "Bookmark label for add" })),
+          entryId: Type.Optional(Type.String({ description: "Native session entry id for add" })),
+          bookmarkId: Type.Optional(Type.String({ description: "Bookmark id for remove" })),
+        }),
+        execute(_toolCallId, params): Promise<AgentToolResult<{ bookmarks: SessionBookmark[] }>> {
+          return Promise.resolve().then(() => {
+            if (params.action === "add") {
+              const label = normalizeBookmarkLabel(params.label ?? "");
+              const entryId = params.entryId?.trim();
+              if (entryId === undefined || entryId === "") throw new Error("Bookmark entryId is required when adding a bookmark");
+              manager.appendLabelChange(entryId, label);
+              return { content: [{ type: "text", text: `Bookmark added: ${label}` }], details: { bookmarks: readBookmarks() } };
+            }
+            if (params.action === "remove") {
+              const bookmarkId = params.bookmarkId?.trim();
+              if (bookmarkId === undefined || bookmarkId === "") throw new Error("Bookmark bookmarkId is required when removing a bookmark");
+              const bookmark = readBookmarks().find((item) => item.id === bookmarkId);
+              if (bookmark === undefined) throw new Error("Bookmark was not found");
+              manager.appendLabelChange(bookmark.entryId, undefined);
+            }
+            const bookmarks = readBookmarks();
+            return {
+              content: [{ type: "text", text: bookmarks.map((bookmark) => `${bookmark.id}: ${bookmark.label}`).join("\n") || "No bookmarks found." }],
+              details: { bookmarks },
+            };
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-bookmarks-panel",
+      pluginId: "@pi-harness/core/plugins/session-bookmarks",
+      title: "Session Bookmarks",
+      description: "为重要会话节点添加原生持久化标签，不修改已有消息内容。",
+      icon: "☆",
+      read: () => {
+        const bookmarks = readBookmarks();
+        return { bookmarks, total: bookmarks.length };
+      },
+    });
+    context.effect(() => () => {
+      unregister();
+      disposePanel();
+    });
+  },
+};

package/packages/core/src/plugins/session-bridge.ts

@@ -0,0 +1,299 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type AgentToolResult, type SessionManager } from "@earendil-works/pi-coding-agent";
+
+const bridgeVersion = 1 as const;
+const maxMessages = 100;
+const maxMessageChars = 16_000;
+const maxTotalChars = 64_000;
+const bridgeType = "pi-harness/session-bridge";
+const roles = new Set(["user", "assistant", "toolResult", "system", "other"]);
+
+export interface BridgeSource {
+  sessionId: string;
+  cwd: string;
+  model?: { provider: string; modelId: string };
+}
+
+export interface BridgeMessage {
+  role: "user" | "assistant" | "toolResult" | "system" | "other";
+  text: string;
+  hasImages: boolean;
+}
+
+export interface BridgePackage {
+  version: typeof bridgeVersion;
+  source: BridgeSource;
+  createdAt: string;
+  messageCount: number;
+  messages: BridgeMessage[];
+  unresolvedAttachments: string[];
+}
+
+export interface HandoffPreview {
+  goal: string;
+  currentState: string;
+  decisions: string[];
+  keyFiles: string[];
+  nextStep: string;
+}
+
+type MessageInput = { role?: unknown; content?: unknown };
+
+function textContent(content: unknown): { text: string; imageTypes: string[] } {
+  if (typeof content === "string") return { text: content, imageTypes: [] };
+  if (!Array.isArray(content)) return { text: "", imageTypes: [] };
+  const text: string[] = [];
+  const imageTypes: string[] = [];
+  for (const item of content) {
+    if (item === null || typeof item !== "object") continue;
+    const value = item as { type?: unknown; text?: unknown; mimeType?: unknown };
+    if (value.type === "text" && typeof value.text === "string") text.push(value.text);
+    if (value.type === "image") imageTypes.push(typeof value.mimeType === "string" && value.mimeType.trim() !== "" ? value.mimeType : "image/unknown");
+  }
+  return { text: text.join("\n"), imageTypes };
+}
+
+function role(value: unknown): BridgeMessage["role"] {
+  return typeof value === "string" && roles.has(value) ? (value as BridgeMessage["role"]) : "other";
+}
+
+const previewTextLimit = 1_000;
+const previewListLimit = 8;
+
+function boundedPreviewText(value: string): string {
+  const normalized = value.trim();
+  return normalized.length <= previewTextLimit ? normalized : `${normalized.slice(0, previewTextLimit - 1)}…`;
+}
+
+function extractKeyFiles(messages: readonly BridgeMessage[]): string[] {
+  const files: string[] = [];
+  const seen = new Set<string>();
+  const pattern =
+    /(?:^|[^\w@])((?:\.\.?\/|[\w-]+\/)+[\w.-]+\.[a-z0-9]{1,12}|[\w.-]+\.(?:json|toml|yaml|yml|md|ts|tsx|js|jsx|rs|go|py|swift|css|html))(?![\w])/giu;
+  for (const message of messages) {
+    for (const match of message.text.matchAll(pattern)) {
+      const file = match[1];
+      if (file !== undefined && !seen.has(file)) {
+        seen.add(file);
+        files.push(file);
+        if (files.length === previewListLimit) return files;
+      }
+    }
+  }
+  return files;
+}
+
+export function buildHandoffPreview(packageValue: BridgePackage): HandoffPreview {
+  const userMessages = packageValue.messages.filter((message) => message.role === "user" && message.text.trim() !== "");
+  const assistantMessages = packageValue.messages.filter((message) => message.role === "assistant" && message.text.trim() !== "");
+  const goal = boundedPreviewText(userMessages[0]?.text ?? "No explicit goal was found in the source session.");
+  const currentState = boundedPreviewText(assistantMessages.at(-1)?.text ?? "No assistant progress message was found.");
+  const decisions = userMessages
+    .filter((message) => /(?:\b(?:fix|keep|use|avoid|must|should|decide|preserve)\b|不要|保持|使用|改|修复|决定)/iu.test(message.text))
+    .slice(0, previewListLimit)
+    .map((message) => boundedPreviewText(message.text));
+  const nextStep = boundedPreviewText(userMessages.at(-1)?.text ?? "Continue from the current state after reviewing this preview.");
+  return { goal, currentState, decisions, keyFiles: extractKeyFiles(packageValue.messages), nextStep };
+}
+
+export function buildBridgePackage(source: BridgeSource, input: readonly MessageInput[]): BridgePackage {
+  const messages: BridgeMessage[] = [];
+  const unresolvedAttachments: string[] = [];
+  let totalChars = 0;
+  for (const [index, message] of input.slice(-maxMessages).entries()) {
+    const content = textContent(message.content);
+    const text = content.text.slice(0, maxMessageChars);
+    if (text !== "") totalChars += text.length;
+    const boundedText = totalChars > maxTotalChars ? text.slice(0, Math.max(0, maxTotalChars - (totalChars - text.length))) : text;
+    messages.push({ role: role(message.role), text: boundedText, hasImages: content.imageTypes.length > 0 });
+    for (const type of content.imageTypes) unresolvedAttachments.push(`message-${index + 1}:${type}`);
+    if (totalChars >= maxTotalChars) break;
+  }
+  return {
+    version: bridgeVersion,
+    source: { sessionId: source.sessionId, cwd: source.cwd, ...(source.model === undefined ? {} : { model: { ...source.model } }) },
+    createdAt: new Date().toISOString(),
+    messageCount: messages.length,
+    messages,
+    unresolvedAttachments,
+  };
+}
+
+export function parseBridgePackage(raw: string): BridgePackage {
+  if (Buffer.byteLength(raw, "utf8") > 256 * 1024) throw new Error("Session bridge package exceeds the 256 KiB limit");
+  let value: unknown;
+  try {
+    value = JSON.parse(raw) as unknown;
+  } catch (error) {
+    throw new Error(`Session bridge package is invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Session bridge package must be an object");
+  const packageValue = value as Record<string, unknown>;
+  if (packageValue.version !== bridgeVersion) throw new Error("Session bridge package version must be 1");
+  const source = packageValue.source;
+  if (source === null || typeof source !== "object" || Array.isArray(source)) throw new Error("Session bridge package source is required");
+  const sourceValue = source as Record<string, unknown>;
+  if (typeof sourceValue.sessionId !== "string" || typeof sourceValue.cwd !== "string")
+    throw new Error("Session bridge package source requires sessionId and cwd");
+  const messages = packageValue.messages;
+  if (!Array.isArray(messages) || messages.length > maxMessages) throw new Error(`Session bridge package must contain 0-${maxMessages} messages`);
+  let totalChars = 0;
+  const normalized = messages.map((message, index) => {
+    if (message === null || typeof message !== "object" || Array.isArray(message)) throw new Error(`Session bridge message ${index + 1} is invalid`);
+    const item = message as Record<string, unknown>;
+    if (
+      typeof item.role !== "string" ||
+      !roles.has(item.role) ||
+      typeof item.text !== "string" ||
+      item.text.length > maxMessageChars ||
+      typeof item.hasImages !== "boolean"
+    )
+      throw new Error(`Session bridge message ${index + 1} is invalid`);
+    totalChars += item.text.length;
+    if (totalChars > maxTotalChars) throw new Error("Session bridge message text exceeds the 64 KiB limit");
+    return { role: item.role as BridgeMessage["role"], text: item.text, hasImages: item.hasImages };
+  });
+  const rawAttachments = packageValue.unresolvedAttachments;
+  if (!Array.isArray(rawAttachments)) throw new Error("Session bridge attachment markers are invalid");
+  const attachments = (rawAttachments as unknown[]).filter((item): item is string => typeof item === "string" && item.length <= 256);
+  if (attachments.length !== rawAttachments.length) throw new Error("Session bridge attachment markers are invalid");
+  const model = sourceValue.model;
+  const modelRecord = model !== null && typeof model === "object" && !Array.isArray(model) ? (model as Record<string, unknown>) : undefined;
+  const provider = typeof modelRecord?.provider === "string" ? modelRecord.provider : undefined;
+  const modelId = typeof modelRecord?.modelId === "string" ? modelRecord.modelId : undefined;
+  const normalizedModel = provider === undefined || modelId === undefined ? undefined : { provider, modelId };
+  const sessionId = sourceValue.sessionId;
+  const cwd = sourceValue.cwd;
+  return {
+    version: bridgeVersion,
+    source: { sessionId, cwd, ...(normalizedModel === undefined ? {} : { model: normalizedModel }) },
+    createdAt: typeof packageValue.createdAt === "string" ? packageValue.createdAt : "",
+    messageCount: normalized.length,
+    messages: normalized,
+    unresolvedAttachments: [...attachments],
+  };
+}
+
+function sessionMessages(manager: SessionManager): MessageInput[] {
+  return manager.buildSessionContext().messages.map((message) => {
+    const value = message as unknown as MessageInput;
+    return { role: value.role, content: value.content };
+  });
+}
+
+function importedText(packageValue: BridgePackage): string {
+  const model = packageValue.source.model === undefined ? "unknown model" : `${packageValue.source.model.provider}/${packageValue.source.model.modelId}`;
+  const lines = [`Session handoff from ${packageValue.source.sessionId} (${packageValue.source.cwd})`, `Source model: ${model}`, ""];
+  for (const message of packageValue.messages) {
+    lines.push(`[${message.role}]`, message.text || "(no text)");
+    if (message.hasImages) lines.push("[unresolved image attachment]");
+    lines.push("");
+  }
+  if (packageValue.unresolvedAttachments.length > 0) lines.push(`Unresolved attachments: ${packageValue.unresolvedAttachments.join(", ")}`);
+  return lines.join("\n").trim();
+}
+
+export default {
+  name: "pi-session-bridge",
+  inject: ["piSession", "piPluginUi", "piTools"],
+  apply(context: Context) {
+    let latest: { direction: "export" | "import"; sessionId: string; messages: number; attachments: number; at: string } | undefined;
+    let latestPreview: { source: BridgeSource; preview: HandoffPreview; at: string } | undefined;
+    const exportCurrentSession = (): BridgePackage => {
+      const manager = context.get("piRuntime")?.session.sessionManager ?? context.piSession.manager;
+      const current = manager.buildSessionContext();
+      const model = current.model === null ? undefined : current.model;
+      return buildBridgePackage(
+        { sessionId: manager.getSessionId(), cwd: manager.getCwd(), ...(model === undefined ? {} : { model }) },
+        sessionMessages(manager),
+      );
+    };
+    const unregisterExport = context.piTools.register(
+      defineTool({
+        name: "session_bridge_export",
+        label: "Export session handoff",
+        description: "Export the active conversation as a bounded, reviewable handoff package without modifying the source session.",
+        promptSnippet: "export the current session as a handoff package",
+        parameters: Type.Object({}),
+        execute(): Promise<AgentToolResult<BridgePackage>> {
+          const packageValue = exportCurrentSession();
+          latest = {
+            direction: "export",
+            sessionId: packageValue.source.sessionId,
+            messages: packageValue.messageCount,
+            attachments: packageValue.unresolvedAttachments.length,
+            at: packageValue.createdAt,
+          };
+          return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(packageValue) }], details: packageValue });
+        },
+      }),
+    );
+    const unregisterPreview = context.piTools.register(
+      defineTool({
+        name: "session_bridge_preview",
+        label: "Preview session handoff",
+        description: "Create a bounded five-part handoff preview without creating a target session or changing the source session.",
+        promptSnippet: "preview the current session handoff before migration",
+        parameters: Type.Object({ package: Type.Optional(Type.String({ description: "Optional JSON produced by session_bridge_export" })) }),
+        execute(_toolCallId, params): Promise<AgentToolResult<{ source: BridgeSource; preview: HandoffPreview }>> {
+          const packageValue = params.package === undefined ? exportCurrentSession() : parseBridgePackage(params.package);
+          const preview = buildHandoffPreview(packageValue);
+          latestPreview = { source: packageValue.source, preview, at: new Date().toISOString() };
+          return Promise.resolve({
+            content: [{ type: "text", text: `Prepared a five-part handoff preview for ${packageValue.source.sessionId}.` }],
+            details: { source: packageValue.source, preview },
+          });
+        },
+      }),
+    );
+    const unregisterImport = context.piTools.register(
+      defineTool({
+        name: "session_bridge_import",
+        label: "Import session handoff",
+        description: "Validate a handoff package and append it to the current session as a visible context message; the source session remains untouched.",
+        promptSnippet: "import a validated session handoff package",
+        parameters: Type.Object({ package: Type.String({ description: "JSON produced by session_bridge_export" }) }),
+        execute(_toolCallId, params): Promise<AgentToolResult<{ imported: true; source: BridgeSource; messages: number }>> {
+          const packageValue = parseBridgePackage(params.package);
+          context.piSession.manager.appendCustomMessageEntry(bridgeType, importedText(packageValue), true, {
+            source: packageValue.source,
+            messageCount: packageValue.messageCount,
+          });
+          latest = {
+            direction: "import",
+            sessionId: packageValue.source.sessionId,
+            messages: packageValue.messageCount,
+            attachments: packageValue.unresolvedAttachments.length,
+            at: new Date().toISOString(),
+          };
+          return Promise.resolve({
+            content: [{ type: "text", text: `Imported ${packageValue.messageCount} handoff message(s).` }],
+            details: { imported: true, source: packageValue.source, messages: packageValue.messageCount },
+          });
+        },
+      }),
+    );
+    const disposePanel = context.piPluginUi.register({
+      id: "session-bridge-panel",
+      pluginId: "@pi-harness/core/plugins/session-bridge",
+      title: "Session Bridge",
+      description: "导出或导入可审查的会话交接包，不改写源会话树。",
+      icon: "⇄",
+      read: () => ({
+        latest: latest ?? null,
+        latestPreview: latestPreview ?? null,
+        currentPreview: buildHandoffPreview(exportCurrentSession()),
+        formatVersion: bridgeVersion,
+        maxMessages,
+        maxTotalChars,
+      }),
+    });
+    context.effect(() => () => {
+      unregisterExport();
+      unregisterImport();
+      unregisterPreview();
+      disposePanel();
+    });
+  },
+};