@jpowersdev/effect-pi 0.1.0

package/src/internal/Pi.ts

@@ -0,0 +1,346 @@
+import * as Pi from "@earendil-works/pi-coding-agent"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Fiber from "effect/Fiber"
+import * as FileSystem from "effect/FileSystem"
+import * as Path from "effect/Path"
+import * as PubSub from "effect/PubSub"
+import * as Queue from "effect/Queue"
+import * as Schema from "effect/Schema"
+import * as Scope from "effect/Scope"
+import * as Semaphore from "effect/Semaphore"
+import * as Stream from "effect/Stream"
+import type * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+
+import * as ModelRuntime from "./ModelRuntime.js"
+import * as Persistence from "./Persistence.js"
+import * as Session from "./Session.js"
+
+type SdkSession = Pick<Pi.AgentSession,
+  "messages" | "isStreaming" | "subscribe" | "prompt" | "dispose" |
+  "abortRetry" | "abortCompaction" | "abortBranchSummary" | "abortBash"
+> & { readonly agent: Pick<Pi.AgentSession["agent"], "abort"> }
+
+/** Internal SDK boundary for deterministic lifecycle tests. */
+export type CreateSession = (options: Pi.CreateAgentSessionOptions & {
+  readonly cwd: string
+  readonly sessionManager: Pi.SessionManager
+}) => Promise<{
+  readonly session: SdkSession
+  readonly modelFallbackMessage?: string
+  readonly extensionsResult?: Pick<Pi.CreateAgentSessionResult["extensionsResult"], "errors">
+}>
+
+const failureMessage = (cause: unknown): string => {
+  if (typeof cause === "object" && cause !== null && "message" in cause) {
+    return String(cause.message)
+  }
+  return String(cause)
+}
+
+const sessionError = (
+  id: Session.Id,
+  operation: Session.Operation,
+  cause: unknown
+) => new Session.Error({ sessionId: id, operation, message: failureMessage(cause) })
+
+const serialize = (
+  id: Session.Id,
+  manager: Pi.SessionManager,
+  operation: Session.Operation = "save"
+): Effect.Effect<string, Session.Error> => Effect.gen(function*() {
+  const header = yield* Effect.try({
+    try: () => manager.getHeader(),
+    catch: (cause) => sessionError(id, operation, cause)
+  })
+  if (header === null) return yield* sessionError(id, operation, "Pi session has no header")
+  return yield* Effect.try({
+    try: () => [header, ...manager.getEntries()].map((entry) => JSON.stringify(entry)).join("\n") + "\n",
+    catch: (cause) => sessionError(id, operation, cause)
+  })
+})
+
+const assistantText = (message: SdkSession["messages"][number]): string => {
+  if (message.role !== "assistant") return ""
+  return message.content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("")
+}
+
+const snapshot = (id: Session.Id, session: SdkSession): Session.Snapshot => {
+  const lastAssistant = session.messages
+    .filter((message) => message.role === "assistant")
+    .at(-1)
+  return new Session.Snapshot({
+    id,
+    status: session.isStreaming ? "streaming" : "idle",
+    messageCount: session.messages.length,
+    lastAssistantText: lastAssistant === undefined ? "" : assistantText(lastAssistant)
+  })
+}
+
+/** Internal constructor seam; all lifecycle and persistence behavior is shared with make. */
+export const makeWith = Effect.fn("Session.make")(function* (
+  options: Session.MakeOptions,
+  createSession: CreateSession,
+  prepare?: ModelRuntime.Operations["sessionOptions"]
+) {
+  const id = options.id
+  const fs = yield* FileSystem.FileSystem
+  const path = yield* Path.Path
+  const store = yield* Persistence.make(id, options.keyPrefix)
+  const persisted = yield* store.load
+  const temporaryDirectory = yield* fs.makeTempDirectoryScoped({ prefix: "effect-pi-" }).pipe(
+    Effect.mapError((cause) => sessionError(id, "make", cause))
+  )
+
+  let manager: Pi.SessionManager
+  if (persisted === undefined) {
+    manager = yield* Effect.try({
+      try: () => Pi.SessionManager.create(options.cwd, temporaryDirectory, { id }),
+      catch: (cause) => sessionError(id, "make", cause)
+    })
+  } else {
+    // Reject torn JSON instead of allowing Pi's tolerant reader to silently skip
+    // it and overwrite the authoritative document with a shorter conversation.
+    // Entry shapes, versions, migrations, and tree semantics still belong to Pi.
+    yield* Effect.forEach(persisted.split("\n"), (line, index) => line.trim() === ""
+      ? Effect.void
+      : Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))(line).pipe(
+        Effect.mapError(() => sessionError(id, "load", `Invalid JSON at line ${index + 1}`))
+      ), { discard: true })
+    const sessionFile = path.join(temporaryDirectory, `${id}.jsonl`)
+    yield* fs.writeFileString(sessionFile, persisted).pipe(
+      Effect.mapError((cause) => sessionError(id, "load", cause))
+    )
+    manager = yield* Effect.try({
+      try: () => Pi.SessionManager.open(sessionFile, temporaryDirectory, options.cwd),
+      catch: (cause) => sessionError(id, "load", cause)
+    })
+  }
+
+  if (manager.getSessionId() !== id) {
+    return yield* sessionError(id, "load", `stored session id ${manager.getSessionId()} does not match ${id}`)
+  }
+
+  const piOptions = yield* Effect.try({
+    try: () => options.configure?.(id) ?? {},
+    catch: (cause) => sessionError(id, "make", cause)
+  })
+  const runtimeOptions = prepare === undefined ? {} : yield* prepare(options.cwd).pipe(
+    Effect.mapError((cause) => sessionError(id, "make", cause))
+  )
+  // Pi's factory has no cancellation API. Wait for acquisition before honoring
+  // interruption, so even a late result is disposed before its temp directory.
+  const result = yield* Effect.acquireRelease(
+    Effect.tryPromise({
+      try: () => createSession({ ...piOptions, ...runtimeOptions, cwd: options.cwd, sessionManager: manager }),
+      catch: (cause) => sessionError(id, "make", cause)
+    }),
+    (result) => Effect.try({
+      try: () => result.session.dispose(),
+      catch: (cause) => sessionError(id, "make", cause)
+    }).pipe(Effect.orDie)
+  )
+  const pi = result.session
+  if (result.modelFallbackMessage !== undefined) {
+    yield* Effect.logWarning("Pi model selection", { sessionId: id, message: result.modelFallbackMessage })
+  }
+  for (const diagnostic of result.extensionsResult?.errors ?? []) {
+    yield* Effect.logWarning("Pi extension failed to load", { sessionId: id, ...diagnostic })
+  }
+
+  const events = yield* Effect.acquireRelease(PubSub.sliding<Session.Event>(1024), PubSub.shutdown)
+  // A checkpoint serializes current state, not the state at notification time.
+  const checkpoints = yield* Effect.acquireRelease(Queue.dropping<void>(1), Queue.shutdown)
+  const operations = yield* Effect.acquireRelease(Scope.make("parallel"), (scope) => Scope.close(scope, Exit.void))
+  const promptGate = yield* Semaphore.make(1)
+  const saveGate = yield* Semaphore.make(1)
+  let sequence = 0
+  let closed = false
+  let active: Fiber.Fiber<unknown, unknown> | undefined
+
+  const ensureOpen = (operation: Session.Operation) => Effect.suspend(() => closed
+    ? sessionError(id, operation, "Session scope is closed")
+    : Effect.void)
+  // Don't interrupt an in-flight replacement of the authoritative document.
+  // Atomicity and crash durability still depend on the supplied store.
+  const save = saveGate.withPermits(1)(
+    serialize(id, manager).pipe(Effect.flatMap(store.save), Effect.uninterruptible)
+  )
+  // Sliding publish is synchronous; publishUnsafe would silently use dropping
+  // behavior on overflow. This is the one synchronous SDK-to-Effect boundary.
+  const publish = (event: Session.Event): void => { Effect.runSync(PubSub.publish(events, event)) }
+  yield* Effect.acquireRelease(
+    Effect.try({
+      try: () => pi.subscribe((event) => {
+        switch (event.type) {
+          case "entry_appended":
+          case "session_info_changed":
+          case "thinking_level_changed":
+          case "turn_end":
+          case "compaction_end":
+          case "agent_settled":
+            Queue.offerUnsafe(checkpoints, undefined)
+            if (event.type === "agent_settled") {
+              publish({ _tag: "Status", sequence: sequence++, status: "idle" })
+            }
+            return
+          case "agent_start":
+            publish({ _tag: "Status", sequence: sequence++, status: "streaming" })
+            return
+          case "message_update":
+            if (event.assistantMessageEvent.type === "text_delta") {
+              publish({ _tag: "TextDelta", sequence: sequence++, delta: event.assistantMessageEvent.delta })
+            }
+            return
+          case "tool_execution_start":
+            publish({ _tag: "ToolStarted", sequence: sequence++, toolName: event.toolName })
+            return
+          case "tool_execution_end":
+            publish({ _tag: "ToolFinished", sequence: sequence++, toolName: event.toolName, isError: event.isError })
+            return
+          default:
+            return
+        }
+      }),
+      catch: (cause) => sessionError(id, "make", cause)
+    }),
+    (unsubscribe) => Effect.try({
+      try: unsubscribe,
+      catch: (cause) => sessionError(id, "events", cause)
+    }).pipe(Effect.orDie)
+  )
+  const checkpointWorker = yield* Queue.take(checkpoints).pipe(
+    Effect.andThen(save.pipe(
+      Effect.tapError((cause) => Effect.logError("Unable to checkpoint Pi session", {
+        sessionId: id, cause: cause.message
+      })),
+      Effect.ignore
+    )),
+    Effect.forever,
+    Effect.forkScoped
+  )
+
+  // Pi.abort() waits for idle and only signals the agent/retry path. Using the
+  // public synchronous signals also stops compaction/summaries/bash and lets us
+  // re-signal a later continuation without accumulating pending abort promises.
+  const abortSdk = Effect.forEach([
+    () => pi.abortRetry(),
+    () => pi.abortCompaction(),
+    () => pi.abortBranchSummary(),
+    () => pi.abortBash(),
+    () => pi.agent.abort()
+  ], (abort) => Effect.try({
+    try: abort,
+    catch: (cause) => sessionError(id, "abort", cause)
+  }).pipe(Effect.ignore), { discard: true })
+  const cancel = (wait: Effect.Effect<void, Session.Error>) => Effect.raceFirst(
+    wait.pipe(Effect.ignore, Effect.interruptible),
+    // Abort signals during async preflight may be a no-op. Keep requesting cancellation
+    // until the invocation settles, including any later model run or retry.
+    abortSdk.pipe(
+      Effect.andThen(Effect.sleep("25 millis")),
+      Effect.forever,
+      Effect.interruptible
+    )
+  )
+
+  const runPrompt = (text: string) => promptGate.withPermits(1)(
+    Effect.uninterruptibleMask((restore) => Effect.gen(function*() {
+      yield* ensureOpen("prompt")
+      active = yield* Effect.fiber
+      const firstEntry = manager.getEntries().length
+      const invocation = Promise.resolve().then(() => pi.prompt(text))
+      const wait = Effect.tryPromise({
+        try: () => invocation,
+        catch: (cause) => sessionError(id, "prompt", cause)
+      })
+      const exit = yield* Effect.exit(restore(wait).pipe(Effect.onInterrupt(() => cancel(wait))))
+      yield* save
+      yield* exit
+
+      // Read newly appended entries, not the active context: compaction can shrink
+      // that context, and handled extension commands need not produce a response.
+      const entries = manager.getEntries().slice(firstEntry)
+      const messages = entries.flatMap((entry) =>
+        entry.type === "message" && entry.message.role === "assistant" ? [entry.message] : [])
+      const message = messages.at(-1)
+      if (message === undefined) {
+        return yield* sessionError(id, "prompt", "Pi returned no new assistant response")
+      }
+      if (message.stopReason === "error" || message.stopReason === "aborted") {
+        return yield* sessionError(id, "prompt", message.errorMessage ?? `Pi response ${message.stopReason}`)
+      }
+      const usage = entries.flatMap((entry) => {
+        if (entry.type === "message") {
+          const message = entry.message
+          return (message.role === "assistant" || message.role === "toolResult") && message.usage !== undefined
+            ? [message.usage] : []
+        }
+        return (entry.type === "compaction" || entry.type === "branch_summary") && entry.usage !== undefined
+          ? [entry.usage] : []
+      })
+      return new Session.PromptResult({
+        snapshot: snapshot(id, pi),
+        text: assistantText(message),
+        stopReason: message.stopReason,
+        inputTokens: usage.reduce((sum, item) => sum + item.input, 0),
+        outputTokens: usage.reduce((sum, item) => sum + item.output, 0),
+        totalTokens: usage.reduce((sum, item) => sum + item.totalTokens, 0),
+        costUsd: usage.reduce((sum, item) => sum + item.cost.total, 0)
+      })
+    }).pipe(Effect.ensuring(Effect.sync(() => { active = undefined }))))
+  )
+
+  const owned = <A>(operation: Session.Operation, work: Effect.Effect<A, Session.Error>) =>
+    Effect.uninterruptibleMask((restore) => Effect.gen(function*() {
+      yield* ensureOpen(operation)
+      // Own work in the session scope as well as in its caller. Closing either
+      // scope must settle Pi before another owner can restore the document.
+      const fiber = yield* Effect.forkIn(work, operations)
+      return yield* restore(Fiber.join(fiber)).pipe(Effect.onInterrupt(() => Fiber.interrupt(fiber)))
+    }))
+
+  const prompt: Session.Session["prompt"] = Effect.fn("Session.prompt")((text) =>
+    owned("prompt", Schema.decodeUnknownEffect(Schema.NonEmptyString)(text).pipe(
+      Effect.mapError((cause) => sessionError(id, "prompt", cause)),
+      Effect.andThen(runPrompt(text))
+    )))
+
+  const abort = owned("abort", Effect.uninterruptible(Effect.gen(function*() {
+    const running = active
+    if (running !== undefined) yield* Fiber.interrupt(running)
+    yield* save
+  })))
+
+  yield* Effect.addFinalizer(() => Effect.gen(function*() {
+    closed = true
+    yield* Scope.close(operations, Exit.void)
+    yield* Fiber.interrupt(checkpointWorker)
+    // Finalizer errors cannot inhabit the typed error channel. Surface a defect
+    // rather than reporting successful release after losing the last checkpoint.
+    yield* save.pipe(Effect.orDie)
+  }))
+  yield* save
+
+  return {
+    id,
+    snapshot: ensureOpen("snapshot").pipe(Effect.andThen(Effect.sync(() => snapshot(id, pi)))),
+    prompt,
+    abort,
+    events: Stream.unwrap(ensureOpen("events").pipe(Effect.as(Stream.fromPubSub(events)))),
+    jsonl: ensureOpen("jsonl").pipe(Effect.andThen(serialize(id, manager, "jsonl")))
+  } satisfies Session.Session
+})
+
+/** Construct one scoped Pi SDK session backed by its KeyValueStore document. */
+export const make: (
+  options: Session.MakeOptions
+) => Effect.Effect<
+  Session.Session,
+  Session.Error,
+  FileSystem.FileSystem | KeyValueStore.KeyValueStore | Path.Path | Scope.Scope | ModelRuntime.ModelRuntime
+> = (options) => Effect.flatMap(ModelRuntime.ModelRuntime, (runtime) =>
+  makeWith(options, Pi.createAgentSession, runtime.sessionOptions))

package/src/internal/Protocol.ts

@@ -0,0 +1,39 @@
+import * as Schema from "effect/Schema"
+import * as Entity from "effect/unstable/cluster/Entity"
+import * as Rpc from "effect/unstable/rpc/Rpc"
+
+import * as Session from "./Session.js"
+
+export const Snapshot = Rpc.make("Snapshot", {
+  success: Session.Snapshot,
+  error: Session.Error
+})
+
+export const Prompt = Rpc.make("Prompt", {
+  payload: { text: Schema.NonEmptyString },
+  success: Session.PromptResult,
+  error: Session.Error
+})
+
+export const Abort = Rpc.make("Abort", {
+  error: Session.Error
+})
+
+export const Jsonl = Rpc.make("Jsonl", {
+  success: Schema.String,
+  error: Session.Error
+})
+
+export const Events = Rpc.make("Events", {
+  success: Session.Event,
+  error: Session.Error,
+  stream: true
+})
+
+export const entity = Entity.make("PiSession", [
+  Snapshot,
+  Prompt,
+  Abort,
+  Jsonl,
+  Events
+])

package/src/internal/ResourceLoader.ts

@@ -0,0 +1,128 @@
+import * as Pi from "@earendil-works/pi-coding-agent"
+import * as Config from "effect/Config"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+
+export type Settings = NonNullable<Parameters<typeof Pi.SettingsManager.inMemory>[0]>
+
+type SdkOptions = ConstructorParameters<typeof Pi.DefaultResourceLoader>[0]
+
+export interface Options extends Omit<SdkOptions, "cwd" | "settingsManager" | "agentDir"> {
+  /** Defaults to Pi's agent directory. Discovery executes trusted extensions. */
+  readonly agentDir?: string
+
+  /** When supplied, use in-memory settings rather than discovering settings files. */
+  readonly settings?: Settings
+}
+
+export interface EmptyOptions {
+  readonly systemPrompt?: string
+  readonly settings?: Settings
+}
+
+export class Error extends Schema.TaggedError<Error>()("ResourceLoaderError", {
+  operation: Schema.Literals(["load", "release"]),
+  message: Schema.String
+}) {}
+
+/** SDK interoperability values. Each load owns a fresh, session-local extension runtime. */
+export interface Loaded {
+  readonly resourceLoader: Pi.ResourceLoader
+  readonly settingsManager: Pi.SettingsManager
+}
+
+export interface Operations {
+  readonly load: (cwd: string) => Effect.Effect<Loaded, Error, Scope.Scope>
+}
+
+export class ResourceLoader extends Context.Service<ResourceLoader, Operations>()(
+  "@jpowersdev/effect-pi/ResourceLoader"
+) {}
+
+const scoped = (create: (cwd: string) => Loaded): Operations => ({
+  load: Effect.fn("ResourceLoader.load")(function* (cwd) {
+    // Register invalidation before reload: even failed/late extension loading must
+    // release its tracked event-bus subscriptions. Pi reload has no AbortSignal.
+    const loaded = yield* Effect.acquireRelease(
+      Effect.try({
+        try: () => create(cwd),
+        catch: () => new Error({ operation: "load", message: "Unable to construct Pi resources" })
+      }),
+      ({ resourceLoader }) => Effect.try({
+        try: () => resourceLoader.getExtensions().runtime.invalidate(),
+        catch: () => new Error({ operation: "release", message: "Unable to release Pi resources" })
+      }).pipe(Effect.orDie)
+    )
+
+    yield* Effect.tryPromise({
+      try: () => loaded.resourceLoader.reload(),
+      catch: () => new Error({ operation: "load", message: "Unable to load Pi resources" })
+    }).pipe(Effect.uninterruptible)
+
+    return loaded
+  })
+})
+
+/** Opt into Pi resource discovery. Prefer layerEmpty for isolated applications. */
+export const layer = (options: Options = {}): Layer.Layer<ResourceLoader> =>
+  Layer.sync(ResourceLoader, () =>
+    scoped((cwd) => {
+      const { settings, ...loaderOptions } = options
+
+      const agentDir = options.agentDir ?? Pi.getAgentDir()
+
+      const settingsManager = settings === undefined
+        ? Pi.SettingsManager.create(cwd, agentDir)
+        : Pi.SettingsManager.inMemory(settings)
+
+      return {
+        settingsManager,
+        resourceLoader: new Pi.DefaultResourceLoader({
+          ...loaderOptions,
+          cwd,
+          agentDir,
+          settingsManager
+        })
+      }
+    })
+  )
+
+/** Resolve discovery options using the active ConfigProvider at layer build time. */
+export const layerConfig = (options: Config.Wrap<Options>) =>
+  Layer.unwrap(Effect.map(Config.unwrap<Options>(options), layer))
+
+/** Resolve isolated resource options using the active ConfigProvider at layer build time. */
+export const layerEmptyConfig = (options: Config.Wrap<EmptyOptions>) =>
+  Layer.unwrap(Effect.map(Config.unwrap<EmptyOptions>(options), layerEmpty))
+
+/** No filesystem discovery, extensions, context files, or ambient settings. */
+export const layerEmpty = (options: EmptyOptions = {}): Layer.Layer<ResourceLoader> =>
+  Layer.sync(ResourceLoader, () =>
+    scoped(() => {
+      const extensions = {
+        extensions: [],
+        errors: [],
+        runtime: Pi.createExtensionRuntime()
+      }
+
+      return {
+        settingsManager: Pi.SettingsManager.inMemory(options.settings),
+        resourceLoader: {
+          getExtensions: () => extensions,
+          getSkills: () => ({ skills: [], diagnostics: [] }),
+          getPrompts: () => ({ prompts: [], diagnostics: [] }),
+          getThemes: () => ({ themes: [], diagnostics: [] }),
+          getAgentsFiles: () => ({ agentsFiles: [] }),
+          getSystemPrompt: () => options.systemPrompt,
+          getSystemPromptSource: () => undefined,
+          getAppendSystemPrompt: () => [],
+          getAppendSystemPromptSources: () => [],
+          extendResources: () => {},
+          reload: async () => {}
+        }
+      }
+    })
+  )

package/src/internal/Session.ts

@@ -0,0 +1,109 @@
+import type * as Pi from "@earendil-works/pi-coding-agent"
+import type * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type * as Stream from "effect/Stream"
+
+/** A Pi session id accepted by Pi's SessionManager. */
+export const Id = Schema.String.check(
+  Schema.isPattern(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/)
+).pipe(Schema.brand("@jpowersdev/effect-pi/SessionId"))
+export type Id = typeof Id.Type
+
+export const Status = Schema.Literals(["idle", "streaming"])
+export type Status = typeof Status.Type
+
+export class Snapshot extends Schema.Class<Snapshot>("@jpowersdev/effect-pi/SessionSnapshot")({
+  id: Id,
+  status: Status,
+  messageCount: Schema.Natural,
+  lastAssistantText: Schema.String
+}) {}
+
+/** Last new assistant response, with usage summed over entries appended by this invocation. */
+export class PromptResult extends Schema.Class<PromptResult>("@jpowersdev/effect-pi/PromptResult")({
+  snapshot: Snapshot,
+  text: Schema.String,
+  stopReason: Schema.String,
+  inputTokens: Schema.Natural,
+  outputTokens: Schema.Natural,
+  totalTokens: Schema.Natural,
+  costUsd: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0))
+}) {}
+
+const StatusEvent = Schema.TaggedStruct("Status", {
+  sequence: Schema.Natural,
+  status: Status
+})
+const TextDeltaEvent = Schema.TaggedStruct("TextDelta", {
+  sequence: Schema.Natural,
+  delta: Schema.String
+})
+const ToolStartedEvent = Schema.TaggedStruct("ToolStarted", {
+  sequence: Schema.Natural,
+  toolName: Schema.String
+})
+const ToolFinishedEvent = Schema.TaggedStruct("ToolFinished", {
+  sequence: Schema.Natural,
+  toolName: Schema.String,
+  isError: Schema.Boolean
+})
+
+/** Stable, serializable subset of Pi's live session events. */
+export const Event = Schema.Union([
+  StatusEvent,
+  TextDeltaEvent,
+  ToolStartedEvent,
+  ToolFinishedEvent
+])
+export type Event = typeof Event.Type
+
+export const Operation = Schema.Literals([
+  "abort",
+  "events",
+  "jsonl",
+  "load",
+  "make",
+  "prompt",
+  "save",
+  "snapshot"
+])
+export type Operation = typeof Operation.Type
+
+export class Error extends Schema.TaggedError<Error>()("SessionError", {
+  sessionId: Id,
+  operation: Operation,
+  message: Schema.String
+}) {}
+
+/** One scoped Pi session, whether local or represented by a cluster client. */
+export interface Session {
+  readonly id: Id
+  readonly snapshot: Effect.Effect<Snapshot, Error>
+  /** Nonempty text. Interruption waits for SDK settlement and a checkpoint. */
+  readonly prompt: (text: string) => Effect.Effect<PromptResult, Error>
+  /** Interrupt the active prompt; queued prompts remain eligible to run. */
+  readonly abort: Effect.Effect<void, Error>
+  /** Ephemeral, bounded stream. Sequence gaps indicate lost events; restoration resets sequence numbers. */
+  readonly events: Stream.Stream<Event, Error>
+  /** Current serialization, not an acknowledgement that the backing store has been flushed. */
+  readonly jsonl: Effect.Effect<string, Error>
+}
+
+export type PiOptions = Omit<
+  Pi.CreateAgentSessionOptions,
+  "cwd" | "sessionManager" | "modelRuntime" | "model" | "resourceLoader" | "settingsManager"
+>
+
+/** Configuration shared by direct, local-pool, and cluster session construction. */
+export interface Config {
+  /** Tool working directory, not a sandbox or filesystem access boundary. */
+  readonly cwd: string
+  /** Defaults to "effect-pi/sessions/". Keep stable across all owners of a document. */
+  readonly keyPrefix?: string
+  /** Per-session SDK options (such as tools). ModelRuntime owns model, auth, resources, and settings. */
+  readonly configure?: (sessionId: Id) => PiOptions
+}
+
+export interface MakeOptions extends Config {
+  readonly id: Id
+}