@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2653-next.71811ca

package/src/factory-board.ts

@@ -194,7 +194,7 @@ function placeTicket(prepared: PreparedTicket): BoardPlacement {
   }
   if (latest.station === "coder") return "coder";
   if (latest.station === "fixer" || latest.station === "reviewer") return "marshal";
-  // ADR 0053: marshal-driven runs land in 尚书省 once the seat ships (station maps now).
+  // ADR 0053: marshal-driven runs land in 刑部 once the seat ships (station maps now).
   if (latest.station === "marshal") return "marshal";
   if (latest.station === "collector") return "collector";
   return `other:${latest.station}`;
@@ -399,7 +399,7 @@ const YAMEN_LABELS: Readonly<Record<string, string>> = {
   collector: "通进司",
   doctor: "太医署",
   merger: "校书郎",
-  marshal: "尚书省",
+  marshal: "刑部",
 };
 
 function latestKnownStation(runs: readonly TicketTrajectoryRun[]): string | undefined {
@@ -805,7 +805,7 @@ const COLUMN_LABELS: Readonly<Record<string, string>> = {
   pending: "待发",
   court: "大理寺 · 审票",
   coder: "将作监",
-  marshal: "尚书省",
+  marshal: "刑部",
   collector: "通进司",
   done: "已完成",
 };

package/src/gatekeeper-role.ts

@@ -1,7 +1,8 @@
 import { Type } from "typebox";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { HostContext } from "./host-contracts.ts";
 
-import { executeAuditorChild, type AuditorCompletion, type AuditorDecisionTool } from "./evidence-child-executor.ts";
+import { executeAuditorChild, type AuditorDecisionTool } from "./evidence-child-executor.ts";
 import { openToolObject } from "./open-tool-schema.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 import { loadGatekeeperSessionMaterials } from "./session-opening-materials.ts";
@@ -69,17 +70,19 @@ export class GatekeeperDecisionError extends Error {
 }
 
 export type RunGatekeeperOptions = {
-  readonly context: ExtensionContext;
+  readonly context: ExtensionContext | HostContext;
   readonly subject: GatekeeperSubject;
   readonly signal?: AbortSignal;
-  readonly runCompletion?: AuditorCompletion;
   readonly loadSoul?: (role: "gatekeeper" | "inspector" | "notary") => Promise<string>;
+  /** Run directory carrying the institutional resolution page (#518). Derives
+   * from context when absent. */
+  readonly runDirectory?: string;
 };
 
 export type GatekeeperPassHostActions = {
-  failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never;
+  failInfrastructure(error: unknown, ctx: ExtensionContext | HostContext, toolCallId?: string): never;
   /** Envelope-owned execute→tool_result bridge (role-runtime); role module only throws typed error. */
-  bindGatekeeperNonPass(toolCallId: string, result: GatekeeperNonPassResult): void;
+  bindSubmissionNonPass(toolCallId: string, result: GatekeeperNonPassResult): void;
 };
 
 // Unknown fields so wrong types/spellings still reach projection (ADR 0055/0057; 仓第 0 条).
@@ -144,10 +147,18 @@ function asStringArray(value: unknown): readonly string[] {
 /** Serializable stand-in when the child tool call had no arguments object. */
 export const MISSING_ARGUMENTS_SUBMISSION = Object.freeze({ missing: "arguments" as const });
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /** Keep original decision bytes for the next reader; undefined becomes a serializable missing-args fact. */
 function retainedSubmission(decision: unknown): unknown {
   // undefined must not be stored: JSON drops it and the missing-args fact vanishes.
-  return decision === undefined ? MISSING_ARGUMENTS_SUBMISSION : decision;
+  // Through the real provider adapter an undefined root argument arrives as an
+  // empty object after serialization; that must also project a missing-args fact.
+  return decision === undefined || (isRecord(decision) && Object.keys(decision).length === 0)
+    ? MISSING_ARGUMENTS_SUBMISSION
+    : decision;
 }
 
 /**
@@ -219,7 +230,7 @@ export async function runGatekeeper(options: RunGatekeeperOptions): Promise<Gate
       tool: createGatekeeperOutputTool(),
       dossierTool: subjectTool(options.subject),
       ...(options.signal === undefined ? {} : { signal: options.signal }),
-      ...(options.runCompletion === undefined ? {} : { runCompletion: options.runCompletion }),
+      ...(options.runDirectory === undefined ? {} : { runDirectory: options.runDirectory }),
     });
   } catch (error) {
     return { status: "transport_failure", stage: "gatekeeper", reason: failureReason(error) };
@@ -242,7 +253,7 @@ export async function runGatekeeper(options: RunGatekeeperOptions): Promise<Gate
       tool: createOfficerDecisionTool(officer === "inspector" ? INSPECTOR_OUTPUT_TOOL : NOTARY_OUTPUT_TOOL),
       dossierTool: subjectTool(options.subject),
       ...(options.signal === undefined ? {} : { signal: options.signal }),
-      ...(options.runCompletion === undefined ? {} : { runCompletion: options.runCompletion }),
+      ...(options.runDirectory === undefined ? {} : { runDirectory: options.runDirectory }),
     });
     if (officerRun.noReceiptLifecycle !== undefined) {
       return { status: "no_receipt", stage: officer, reason: `${gateSeatLabel(officer)}未产生已接受回执即散局`, facts: officerRun.noReceiptLifecycle };
@@ -255,7 +266,7 @@ export async function runGatekeeper(options: RunGatekeeperOptions): Promise<Gate
 
 /** Project GatekeeperResult onto a submit path: transport→failInfrastructure; bounce/no_receipt→typed throw; pass silent. */
 export async function requireGatekeeperPass(options: {
-  readonly context: ExtensionContext;
+  readonly context: ExtensionContext | HostContext;
   readonly subject: GatekeeperSubject;
   readonly signal?: AbortSignal;
   readonly hostActions: GatekeeperPassHostActions;
@@ -280,6 +291,6 @@ export async function requireGatekeeperPass(options: {
     options.hostActions.failInfrastructure(error, options.context, options.toolCallId);
   }
   // Envelope owns the execute→tool_result bridge; this module only projects + throws.
-  options.hostActions.bindGatekeeperNonPass(options.toolCallId, gatekeeper);
+  options.hostActions.bindSubmissionNonPass(options.toolCallId, gatekeeper);
   throw new GatekeeperDecisionError(gatekeeper);
 }

package/src/host-contracts.ts

@@ -0,0 +1,386 @@
+import { Type, type Static, type TLiteral, type TSchema } from "typebox";
+
+type HostContentPart = { type: "text"; text: string } | { type: "toolCall"; id: string; name: string; arguments?: unknown } | { type: string };
+type HostMessage = { role: string; content?: unknown; toolName?: string; isError?: boolean; stopReason?: string };
+type HostEventMessage = { role: string; content: readonly HostContentPart[]; toolName?: string; isError?: boolean; stopReason?: string };
+type HostSessionEntry = { type: string; message?: HostMessage };
+
+export type HostToolResult<T = unknown> = {
+  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
+  details: T;
+  terminate?: boolean;
+};
+
+/** Opaque host-owned identity persisted with a Role run. */
+export type DurablePrincipal = object & { readonly __durablePrincipal?: never };
+
+/** Controlled post-admission failure classes (ADR 0052 / #107). Owner = host contract. */
+export type ControlledFailureCause =
+  | "activation"
+  | "provider"
+  | "session"
+  | "output"
+  | "timeout"
+  | "unrecognized";
+
+/** Production-owned typed failure carried on a resolved turn result. */
+export type RoleTurnKnownFailure = {
+  readonly cause: ControlledFailureCause;
+  readonly identity?: {
+    readonly name?: string;
+    readonly code?: string | number;
+  };
+  /**
+   * Optional diagnostic already owned by a typed production field (e.g. session
+   * assistant errorMessage). Settlement prefers this over child stderr selection.
+   */
+  readonly diagnostic?: string;
+  /** Secondary evidence attached to the same typed failure record. */
+  readonly details?: Readonly<Record<string, unknown>>;
+};
+
+/**
+ * Thrown activation failure with a production-owned typed cause.
+ * Prefer this over ad-hoc Error property tags so settlement retains typed identity.
+ * Final owner = host contract (#526); public-cli/pi/role-runtime all import here.
+ */
+export class ExplicitInternalActivationError extends Error {
+  readonly knownCause: ControlledFailureCause;
+  readonly failureCode?: string | number;
+
+  constructor(
+    message: string,
+    options: {
+      knownCause: ControlledFailureCause;
+      code?: string | number;
+      name?: string;
+      cause?: unknown;
+    },
+  ) {
+    super(
+      message,
+      options.cause === undefined ? undefined : { cause: options.cause },
+    );
+    this.name = options.name ?? "ExplicitInternalActivationError";
+    this.knownCause = options.knownCause;
+    if (options.code !== undefined) {
+      this.failureCode = options.code;
+    }
+  }
+}
+
+/** Packaged method skill binding (zero/one/many). */
+export type MethodBinding = {
+  readonly kind: "skill";
+  readonly path: string;
+};
+
+/**
+ * Host-neutral closed role activation projection.
+ * Adapter translates to host-specific flags; does not reverse-parse prompt prose.
+ */
+export type RoleTurnActivation =
+  | { readonly role: "judge" }
+  | {
+      readonly role: "coder";
+      readonly phase: string;
+      readonly taskPath: string;
+    }
+  | {
+      readonly role: "fixer";
+      readonly phase: string;
+      readonly packetPath: string;
+      readonly prerequisitesPath?: string;
+    }
+  | {
+      readonly role: "reviewer";
+      readonly baseRevision: string;
+      readonly authorityRefs: readonly string[];
+      readonly ticketNumber?: number;
+    }
+  | { readonly role: "merger"; readonly inputPath: string }
+  | {
+      readonly role: "collector";
+      readonly repo: string;
+      readonly pr: string;
+      readonly requestManifestPath?: string;
+    }
+  | { readonly role: "doctor"; readonly casePath: string }
+  | { readonly role: "notary"; readonly sourceRun: string };
+
+export type RoleTurnContinuation =
+  | { readonly kind: "initial"; readonly prompt: string }
+  | { readonly kind: "resume"; readonly prompt: string };
+
+/** Seat model consumed by the turn host (provider/model/thinking). */
+export type RoleTurnModelConfig = {
+  readonly provider: string;
+  readonly model: string;
+  readonly thinking?: string;
+};
+
+/** One main-session turn request over the host-neutral execution seam. */
+export type RoleTurnRequest = {
+  readonly principal: DurablePrincipal;
+  readonly activation: RoleTurnActivation;
+  readonly methods: readonly MethodBinding[];
+  readonly continuation: RoleTurnContinuation;
+  readonly model?: RoleTurnModelConfig;
+  readonly engine?: string;
+  readonly cwd: string;
+  readonly home: string;
+  readonly agentDir: string;
+  readonly runDirectory: string;
+  readonly correlationId?: string;
+  readonly timeoutMs?: number;
+};
+
+/** Turn result — only fields upper layers currently consume. */
+export type RoleTurnResult = {
+  readonly code: number | null;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+  readonly knownFailure?: RoleTurnKnownFailure;
+};
+
+/** Host-neutral session custom-entry appender (Pi adapter provides the concrete codec). */
+export type SessionCustomEntryAppender = (
+  authority: DurablePrincipalAuthority,
+  principal: DurablePrincipal,
+  customType: string,
+  data: unknown,
+) => Promise<void>;
+
+/** Host-neutral main-session execution seam (S1b-2 / #526). */
+export interface RoleTurnHost {
+  executeTurn(request: RoleTurnRequest): Promise<RoleTurnResult>;
+}
+
+export type DurablePrincipalCoordinates = {
+  readonly sessionDirectory: string;
+  readonly sessionFile: string;
+};
+
+export type NewDurablePrincipalRequest = {
+  readonly cwd: string;
+  readonly runId: string;
+  readonly role: string;
+  readonly home?: string;
+};
+
+/** Host authority for issuing, checking, and temporarily decoding durable principals. */
+export interface DurablePrincipalAuthority {
+  issue(request: NewDurablePrincipalRequest): DurablePrincipal;
+  isAvailable(principal: DurablePrincipal): Promise<boolean>;
+  decode(principal: unknown): DurablePrincipalCoordinates;
+}
+
+type HostSessionManager = { getLeafEntry(): HostSessionEntry | undefined; getLeafId(): string | null | undefined; getEntries(): Iterable<HostSessionEntry>; getSessionDir(): string; getSessionFile(): string | undefined; getHeader?(): { readonly type: string; readonly id?: string } | null; setSessionFile?(path: string): void; appendCustomEntry?(customType: string, data?: unknown): unknown; };
+
+/** Context supplied by a host for one activation and its interceptable events. */
+export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
+
+export type HostToolDefinition<S extends TSchema = TSchema, D = unknown, C = HostContext> = { name: string; label: string; description: string; promptSnippet?: string; parameters: S; execute( toolCallId: string, params: Static<S>, signal: AbortSignal | undefined, update: ((result: HostToolResult<D>) => void) | undefined, context: C, ): Promise<HostToolResult<D>>; };
+
+type BeforeAgentStartEvent = { prompt: string; systemPrompt: string; systemPromptOptions: { skills?: readonly unknown[]; contextFiles?: readonly unknown[]; appendSystemPrompt?: string } };
+type InputEvent = { text: string; images?: Array<{ type: "image"; data: string; mimeType: string }>; source?: string };
+type ToolCallEvent = { toolName: string; toolCallId: string; input: Record<string, unknown> };
+type ToolResultEvent = { toolName: string; toolCallId: string; isError: boolean; content: HostToolResult["content"]; details: unknown };
+type SessionStartEvent = { reason: string };
+type ProviderResponseEvent = { status?: number };
+type AgentEndEvent = { messages: readonly HostEventMessage[] };
+type ToolExecutionEvent = { toolName: string; toolCallId: string };
+type ToolExecutionUpdateEvent = ToolExecutionEvent & { partialResult: unknown };
+type ToolExecutionEndEvent = ToolExecutionEvent & { isError: boolean };
+
+type HostEventMap = {
+  before_agent_start: BeforeAgentStartEvent;
+  input: InputEvent;
+  tool_call: ToolCallEvent;
+  tool_result: ToolResultEvent;
+  session_start: SessionStartEvent;
+  session_shutdown: Record<never, never>;
+  after_provider_response: ProviderResponseEvent;
+  agent_end: AgentEndEvent;
+  agent_settled: Record<never, never>;
+  tool_execution_start: ToolExecutionEvent;
+  tool_execution_update: ToolExecutionUpdateEvent;
+  tool_execution_end: ToolExecutionEndEvent;
+};
+
+type HostInputResult = { action: "continue" } | { action: "transform"; text: string; images?: Array<{ type: "image"; data: string; mimeType: string }> } | { action: "handled" };
+type HostEventResultMap = {
+  before_agent_start: { systemPrompt?: string };
+  input: HostInputResult;
+  tool_call: { block?: boolean; reason?: string; terminate?: boolean };
+  tool_result: { content?: HostToolResult["content"]; details?: unknown; isError?: boolean };
+  session_start: void;
+  session_shutdown: void;
+  after_provider_response: void;
+  agent_end: void;
+  agent_settled: void;
+  tool_execution_start: void;
+  tool_execution_update: void;
+  tool_execution_end: void;
+};
+type HostEventHandler<K extends keyof HostEventMap> = (event: HostEventMap[K], ctx: HostContext) => HostEventResultMap[K] | void | Promise<HostEventResultMap[K] | void>;
+export type HostEventRegistration = { [K in keyof HostEventMap]: [event: K, handler: HostEventHandler<K>] }[keyof HostEventMap];
+
+type HostGatekeeperSubject = { readonly kind: "worker_completion" | "judge_draft"; readonly material: string };
+/** Gatekeeper bounce/no_receipt plus other correct submission rejects share one projection map. */
+type HostGatekeeperNonPass = { readonly status: "bounce" | "no_receipt" } & Record<string, unknown>;
+export type HostSubmissionNonPass =
+  | HostGatekeeperNonPass
+  | { readonly code: "coder_skill_expansion_evidence_missing" };
+export type HostGatekeeperActions = {
+  failInfrastructure(error: unknown, context: HostContext, toolCallId?: string): never;
+  /** Envelope-owned execute→tool_result bridge for any structured submission non-pass. */
+  bindSubmissionNonPass(toolCallId: string, result: HostSubmissionNonPass): void;
+};
+
+export type HostSkillExpansionEvidence = Readonly<{
+  name: string;
+  location: string;
+  content: string;
+  userMessage: string;
+}>;
+
+/** Host capability declaration (contract verb ④). */
+export type HostCapabilityDeclaration = Readonly<{
+  skillExpansion(prompt: string): HostSkillExpansionEvidence | undefined;
+}>;
+
+/** The activation surface consumed by package role factories. */
+export interface RoleHost {
+  readonly capabilities?: HostCapabilityDeclaration;
+  registerFlag(name: string, definition: { description: string; type: "boolean" | "string"; default?: boolean | string }): void;
+  getFlag(name: string): boolean | string | undefined;
+  registerTool<S extends TSchema, D = unknown>(tool: HostToolDefinition<S, D>): void;
+  getAllTools(): Array<{ name: string; sourceInfo?: { path?: string } }>;
+  setActiveTools(names: string[]): void;
+  getActiveTools(): string[];
+  requireGatekeeperPass?(options: { context: HostContext; subject: HostGatekeeperSubject; signal?: AbortSignal; hostActions: HostGatekeeperActions; toolCallId: string }): Promise<void>;
+  on(event: "before_agent_start", handler: HostEventHandler<"before_agent_start">): void;
+  on(event: "input", handler: HostEventHandler<"input">): void;
+  on(event: "tool_call", handler: HostEventHandler<"tool_call">): void;
+  on(event: "tool_result", handler: HostEventHandler<"tool_result">): void;
+  on(event: "session_start", handler: HostEventHandler<"session_start">): void;
+  on(event: "session_shutdown", handler: HostEventHandler<"session_shutdown">): void;
+  on(event: "after_provider_response", handler: HostEventHandler<"after_provider_response">): void;
+  on(event: "agent_end", handler: HostEventHandler<"agent_end">): void;
+  on(event: "agent_settled", handler: HostEventHandler<"agent_settled">): void;
+  on(event: "tool_execution_start", handler: HostEventHandler<"tool_execution_start">): void;
+  on(event: "tool_execution_update", handler: HostEventHandler<"tool_execution_update">): void;
+  on(event: "tool_execution_end", handler: HostEventHandler<"tool_execution_end">): void;
+  getCommands?(): Array<{ name: string }>;
+}
+
+/** Institutional sub-session seats (#518 §1). */
+export type InstitutionalSeat =
+  | "gatekeeper"
+  | "inspector"
+  | "notary"
+  | "auditor"
+  | "evidenceChild"
+  | (string & {});
+
+/** Non-secret host-neutral seat model selection. Single truth source is RoleTurnModelConfig. */
+export type HostInstitutionalModelSelection = RoleTurnModelConfig;
+
+/** Usage statistics for institutional sub-session events and turns. */
+export type HostSessionUsage = {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly totalTokens: number;
+  readonly cost: {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+  };
+};
+
+/** Closed stream event union consumed by institutional callers (#518 §1③). */
+export type HostInstitutionalSessionEvent =
+  | {
+      readonly type: "message_end";
+      readonly role: "assistant" | "user" | string;
+      readonly message?: unknown;
+      readonly usage?: HostSessionUsage;
+    }
+  | {
+      readonly type: "turn_end";
+      readonly stopReason?: string;
+    }
+  | {
+      readonly type: "tool_call";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly args?: unknown;
+    }
+  | {
+      readonly type: "tool_result";
+      readonly toolCallId: string;
+      readonly toolName: string;
+      readonly isError?: boolean;
+      readonly details?: unknown;
+    };
+
+/** Terminal result of an institutional assistant turn (#518 §1③). */
+export type HostAssistantTurnResult = {
+  readonly text: string;
+  readonly stopReason?: string;
+  readonly errorMessage?: string;
+  readonly usage?: HostSessionUsage;
+  readonly messages?: readonly unknown[];
+};
+
+/**
+ * Handle to an active institutional sub-session (#518 §1②).
+ * Does not leak AgentSession, ModelRuntime, or Provider objects out of the adapter.
+ */
+export interface HostInstitutionalSessionHandle {
+  readonly sessionFile?: string;
+  readonly sessionId?: string;
+  prompt(text: string): Promise<HostAssistantTurnResult>;
+  subscribe(listener: (event: HostInstitutionalSessionEvent) => void): () => void;
+  abort(): void;
+  close(): Promise<void>;
+}
+
+/** Open options for an institutional sub-session (#518 §1①). */
+export type HostInstitutionalSessionOptions = {
+  readonly cwd: string;
+  readonly selection: HostInstitutionalModelSelection;
+  readonly systemPrompt: string;
+  readonly tools?: readonly HostToolDefinition[];
+  readonly customTools?: readonly unknown[];
+  readonly noTools?: "all" | "builtin";
+  readonly toolsAllowlist?: readonly string[];
+  readonly agentDir?: string;
+  readonly credentialScratchParent?: string;
+  readonly signal?: AbortSignal;
+  readonly idleRetry?: boolean;
+  readonly sessionIdentity?: {
+    readonly kind: string;
+    readonly subject?: string;
+    readonly parent?: { getSessionFile(): string | undefined };
+  };
+  readonly sessionManager?: unknown;
+};
+
+/** Host-neutral institutional sub-session open seam. */
+export interface InstitutionalSessionHost {
+  openInstitutionalSession(
+    options: HostInstitutionalSessionOptions,
+  ): Promise<HostInstitutionalSessionHandle>;
+}
+
+/** Local replacement for Pi AI's convenience constructor. */
+export function stringEnum<const V extends readonly string[]>(values: V, options: Record<string, unknown> = {}) {
+  return Type.Union(values.map((value) => Type.Literal(value)) as [TLiteral<V[number]>, ...TLiteral<V[number]>[]], options);
+}
+

package/src/in-process-session.ts

@@ -1,115 +1 @@
-/**
- * Thin shared in-process AgentSession open (#233).
- * Static Pi imports are safe for Navigator (same module instance as ModelRuntime).
- * Auditor/evidence callers must dynamic-import this module so public-cli bundling
- * does not statically reach @earendil-works/pi-coding-agent.
- */
-import {
-  createAgentSession,
-  DefaultResourceLoader,
-  SettingsManager,
-  type ModelRuntime,
-  type SessionManager,
-  type ToolDefinition,
-} from "@earendil-works/pi-coding-agent";
-import type { Api, Model } from "@earendil-works/pi-ai";
-
-import { createRecordSession } from "./archivist-record-entry.ts";
-
-type OpenInProcessAgentSessionBase = {
-  readonly cwd: string;
-  /** Required when loading a resource loader / systemPrompt. Callers own scratch lifecycle. */
-  readonly agentDir?: string;
-  readonly model: Model<Api>;
-  readonly modelRuntime: ModelRuntime;
-  readonly thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  readonly systemPrompt?: string;
-  readonly customTools?: ToolDefinition[];
-  readonly noTools?: "all" | "builtin";
-  /** Optional allowlist — omit for unrestricted Pi defaults (ADR 0064). */
-  readonly tools?: string[];
-};
-
-/**
- * Shared open admits exactly one session source:
- * - pre-built sessionManager, or
- * - kind/subject/parent identity relations (Archivist obtains the manager).
- * Encoded as a type relation — no runtime missing-arg guard.
- */
-export type OpenInProcessAgentSessionOptions =
-  | (OpenInProcessAgentSessionBase & {
-      readonly sessionManager: SessionManager;
-      readonly kind?: never;
-      readonly subject?: never;
-      readonly parent?: never;
-    })
-  | (OpenInProcessAgentSessionBase & {
-      readonly sessionManager?: undefined;
-      /** Record kind for the Archivist entry. */
-      readonly kind: string;
-      /** Stable work identity for book-level records which continue across role runs. */
-      readonly subject?: string;
-      /** Optional parent session — supplies parentSession link / nest principal. */
-      readonly parent?: { getSessionFile(): string | undefined };
-    });
-
-function resolveSessionManager(options: OpenInProcessAgentSessionOptions): SessionManager {
-  if (options.sessionManager !== undefined) return options.sessionManager;
-  return createRecordSession({
-    cwd: options.cwd,
-    kind: options.kind,
-    ...(options.subject === undefined ? {} : { subject: options.subject }),
-    ...(options.parent === undefined ? {} : { parent: options.parent }),
-  });
-}
-
-/**
- * Single createAgentSession + Settings construction for all in-process children.
- * Child SessionManager construction for identity-declared records lives here so
- * role modules do not call createRecordSession directly.
- */
-export async function openInProcessAgentSession(
-  options: OpenInProcessAgentSessionOptions,
-): Promise<{ session: Awaited<ReturnType<typeof createAgentSession>>["session"]; dispose(): void }> {
-  const settings = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: false } });
-  const sessionManager = resolveSessionManager(options);
-
-  const createArgs: Parameters<typeof createAgentSession>[0] = {
-    cwd: options.cwd,
-    model: options.model,
-    thinkingLevel: options.thinkingLevel ?? "off",
-    modelRuntime: options.modelRuntime,
-    sessionManager,
-    settingsManager: settings,
-    ...(options.noTools === undefined ? {} : { noTools: options.noTools }),
-    ...(options.tools === undefined ? {} : { tools: options.tools }),
-    ...(options.customTools === undefined ? {} : { customTools: options.customTools }),
-  };
-
-  if (options.agentDir !== undefined) {
-    const loader = new DefaultResourceLoader({
-      cwd: options.cwd,
-      agentDir: options.agentDir,
-      settingsManager: settings,
-      noExtensions: true,
-      noSkills: true,
-      noPromptTemplates: true,
-      noThemes: true,
-      noContextFiles: true,
-      ...(options.systemPrompt === undefined ? {} : { systemPrompt: options.systemPrompt }),
-    });
-    await loader.reload();
-    createArgs.agentDir = options.agentDir;
-    createArgs.resourceLoader = loader;
-  } else if (options.systemPrompt !== undefined) {
-    throw new Error("openInProcessAgentSession requires agentDir when systemPrompt is set");
-  }
-
-  const { session } = await createAgentSession(createArgs);
-  return {
-    session,
-    dispose() {
-      session.dispose();
-    },
-  };
-}
+export * from "./pi/in-process-session.ts";