@jpowersdev/effect-pi 0.1.0

package/docs/reference.md

@@ -0,0 +1,248 @@
+# API and behavior reference
+
+This guide covers installation, configuration, the public API, persistence, and cancellation. See the [README](../README.md) for an overview and the [examples](../examples/README.md) for runnable programs.
+
+## Installation and compatibility
+
+The package is named `@jpowersdev/effect-pi`. To install a local build, run this from a checkout:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm pack --pack-destination /tmp/effect-pi-pack
+```
+
+Then, from the consuming project:
+
+```sh
+pnpm add /tmp/effect-pi-pack/jpowersdev-effect-pi-0.1.0.tgz effect@4.0.0-rc.116
+```
+
+For a published release, use the package name in place of the tarball path.
+
+The supported configuration is Node.js 26+, ESM, Effect `4.0.0-rc.116`, and Pi `0.86.1`. Effect is an exact peer dependency while these APIs are release candidates. Keep all `@effect/*` packages on the matching release.
+
+The Pi SDK is an exact runtime dependency. Normal usage and the examples don't import it directly. Add `@earendil-works/pi-coding-agent@0.86.1` only for advanced SDK interoperability. The optional Node/SQLite example dependencies are:
+
+```sh
+pnpm add @effect/platform-node@4.0.0-rc.116 @effect/sql-sqlite-node@4.0.0-rc.116
+```
+
+TypeScript consumers currently need `skipLibCheck: true` because the pinned upstream Pi/provider declarations have NodeNext compatibility issues. The library and examples are otherwise checked with strict TypeScript. Browser and CommonJS usage are not supported.
+
+## Public API
+
+Six concepts are exported from the package root:
+
+| Export | Purpose |
+| --- | --- |
+| `ResourceLoader` | `layer` / `layerConfig` for Pi discovery; `layerEmpty` / `layerEmptyConfig` for isolation |
+| `ModelRuntime` | `layer` / `layerConfig`, depending on `ResourceLoader` |
+| `Session` | Id/event/result schemas, `Session.Error`, the session interface, and scoped `Session.make` |
+| `Sessions` | Service providing `open(id)` within a scope |
+| `LocalSessions` | `layer` / `layerConfig`, backed by `RcMap` |
+| `ClusterSessions` | `runnerLayer` / `runnerLayerConfig`, and `clientLayer` |
+
+A session provides:
+
+- `prompt(text)` — accept a nonempty prompt, wait its turn, run Pi, save a checkpoint, and return a result.
+- `abort` — interrupt the active prompt and wait for settlement and a checkpoint. Queued prompts are not cancelled by this call.
+- `snapshot` — current status, message count, and last assistant text.
+- `events` — ephemeral status, text-delta, and tool lifecycle events.
+- `jsonl` — serialize current state. This is **not** a store flush operation.
+
+`configure(id)` synchronously returns per-session SDK options such as tool policy and thinking level. The library owns `cwd`, `sessionManager`, `modelRuntime`, `model`, `resourceLoader`, and `settingsManager`. SDK interoperability options remain version-coupled.
+
+### Resources and models
+
+Declare reusable configuration recipes and layers at module scope. Compose them at the application boundary, rather than building the graph inside the application Effect:
+
+```ts
+import * as Config from "effect/Config"
+import * as Layer from "effect/Layer"
+
+import { LocalSessions, ModelRuntime, ResourceLoader } from "@jpowersdev/effect-pi"
+
+const ModelConfig = Config.all({
+  provider: Config.NonEmptyString("EFFECT_PI_PROVIDER"),
+  modelId: Config.NonEmptyString("EFFECT_PI_MODEL"),
+  apiKey: Config.Redacted("EFFECT_PI_API_KEY")
+}).pipe(
+  Config.map(({ provider, modelId, apiKey }) => ({
+    model: { provider, id: modelId },
+    apiKeys: { [provider]: apiKey },
+    authPath: ".data/auth.json",
+    modelsPath: null,
+    refreshOnCreate: false
+  }))
+)
+
+const ResourcesLive = ResourceLoader.layerEmpty({
+  systemPrompt: "You are a helpful assistant.",
+  settings: { retry: { enabled: false } }
+})
+
+const ModelLive = ModelRuntime.layerConfig(ModelConfig).pipe(
+  Layer.provide(ResourcesLive)
+)
+
+const SessionsLive = LocalSessions.layerConfig({
+  cwd: Config.NonEmptyString("EFFECT_PI_CWD").pipe(Config.withDefault(".")),
+  configure: Config.succeed(() => ({ tools: ["read", "grep", "find", "ls"] }))
+}).pipe(
+  Layer.provide(ModelLive)
+)
+
+// Provide Node services and a KeyValueStore at the application boundary.
+```
+
+The config constructors accept `Config.Wrap<Options>`: either a complete `Config<Options>` or a nested record of individual `Config` values. Use `Config.succeed` for constant fields and callbacks, or use the plain `layer` constructors when all options are already known. Config is parsed **when the layer builds**, using the active `ConfigProvider`, so the same layer definition can be composed with different providers. Missing or invalid config fails the layer with `Config.ConfigError`, before sessions are opened.
+
+For genuinely effectful construction that needs other services, `Layer.unwrap` remains available. Keep such work at the relevant layer boundary; the application Effect should consume services, not assemble them.
+
+Supply runtime-only keys with `apiKeys: { [provider]: apiKey }`, where `apiKey` is an Effect `Redacted<string>` (for example, from `Config.Redacted`). The library installs these keys without persisting them; Pi may still create an empty auth file. Other model options follow Pi's `CreateModelRuntimeOptions`, except that the library supplies the cancellation signal. Omitting `model` lets Pi restore/select it from session history and settings.
+
+`ResourceLoader.layerEmpty` does no filesystem discovery and uses in-memory settings. `ResourceLoader.layer` opts into trusted Pi discovery, defaulting to Pi's agent directory; `agentDir` overrides the resource directory, and `settings` replaces discovered settings with an in-memory configuration. Configure model/auth paths separately on `ModelRuntime` when using a custom directory.
+
+These services capture reusable configuration, **not shared mutable SDK instances**. The `ResourceLoader` service's `load(cwd)` and the `ModelRuntime` service's `sessionOptions(cwd)` are scoped Effects; sessions call them automatically. Each live session receives a fresh resource loader, settings manager, and model runtime. Extension-provided models are registered before model selection. Reusing a layer does not share extension bindings or runtime credentials between live sessions.
+
+Direct service calls fail with `ResourceLoader.Error` or `ModelRuntime.Error`, each carrying `operation` and `message`. Session construction maps these to `Session.Error` with operation `make`. Raw SDK error payloads are not retained because they can contain credentials. Loaded/binding values expose SDK handles only as an advanced interoperability boundary; don't share them between live sessions or use them after their scope closes.
+
+### Direct sessions
+
+`Session.make({ id, cwd, configure? })` needs `ModelRuntime`, `FileSystem`, `Path`, `KeyValueStore`, and a `Scope`. It does not require `Sessions` or Cluster. Each call creates its own resource; do not independently construct the same stored id twice.
+
+See [single-session.ts](../examples/single-session.ts).
+
+### Local sessions
+
+`LocalSessions.layer` shares one live resource per id **within that layer instance**. Reuse the layer rather than making one per request. `open` holds a reference until its scope closes; unreferenced resources stay resident for `idleTimeToLive` (default: 15 minutes). Closing the layer releases them immediately.
+
+This is the preferred choice for a single owning Node process. Other processes can use that application's existing HTTP/RPC interface.
+
+See [local-session-pool.ts](../examples/local-session-pool.ts).
+
+### Cluster sessions
+
+Clients provide `ClusterSessions.clientLayer`; runners register `ClusterSessions.runnerLayer`. Both need Effect Cluster sharding. Runners additionally need `ModelRuntime`, the Node services, and the authoritative store. Cluster clients do not need model credentials or resource-loading layers. A client `open` is lightweight; construction/load errors can arrive on the first operation rather than at `open`.
+
+Runner defaults:
+
+| Option | Default |
+| --- | --- |
+| `resourceIdleTimeToLive` | 15 minutes |
+| `entityMaxIdleTime` | 20 minutes |
+| `mailboxCapacity` | 128 |
+
+Long-lived event subscriptions keep resources in use. Runner and client processes must use compatible package versions and cluster configuration. The mailbox limit is not a global cap on active prompt requests; handlers run concurrently so aborts and events can proceed during prompts.
+
+The self-contained [cluster example](../examples/cluster-session.ts) starts a runner and a client in one process. They use separate sharding runtimes and communicate over a loopback socket. Discovery and cluster message storage are shared in memory; SQLite stores the conversation documents. `Layer.fresh` keeps the differently configured cluster runtimes from sharing memoized services. Their lifetimes are scoped together, so both shut down when the example finishes.
+
+SQLite supports this local demo. Across machines, use a shared database for coordination and session documents; do not put SQLite on a network filesystem.
+
+## Local setup using existing Pi configuration
+
+The [runnable examples](../examples/README.md) configure Pi explicitly without loading your usual extensions, settings, or context files. If you instead want to reuse your existing **trusted** Pi setup, you can provide a smaller configuration:
+
+```ts
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import * as SqliteClient from "@effect/sql-sqlite-node/SqliteClient"
+
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+
+import { LocalSessions, ModelRuntime, ResourceLoader, Session, Sessions } from "@jpowersdev/effect-pi"
+
+const StoreLive = KeyValueStore.layerSql({ table: "pi_sessions" }).pipe(
+  Layer.provide(
+    SqliteClient.layer({ filename: ".data/effect-pi.sqlite" })
+  )
+)
+
+const ModelLive = ModelRuntime.layer().pipe(
+  Layer.provide(ResourceLoader.layer())
+)
+
+const SessionsLive = LocalSessions.layer({
+  cwd: process.cwd(),
+  configure: () => ({ tools: ["read", "grep", "find", "ls"] })
+}).pipe(
+  Layer.provide([ModelLive, NodeServices.layer, StoreLive])
+)
+
+const program = Effect.gen(function* () {
+  const sessions = yield* Sessions
+
+  const id = Session.Id.make("experiment-1")
+
+  const session = yield* sessions.open(id)
+
+  const result = yield* session.prompt("Describe the top-level files in this repository")
+
+  yield* Console.log(result.text)
+}).pipe(
+  Effect.scoped,
+  Effect.provide(SessionsLive)
+)
+
+NodeRuntime.runMain(program)
+```
+
+Create a private `.data/` directory first (`mkdir -p .data && chmod 700 .data` on Unix). The SQLite database contains unencrypted conversation data.
+
+This example uses Pi's existing model/auth configuration and resource discovery. Its read-only tool allowlist does **not** disable extension discovery or prevent reads outside `cwd`. Running it again with the same id and store restores the conversation.
+
+## Cancellation and lifetime
+
+- Prompt effects are owned by both the caller and the live session. Interrupting either cancels the SDK invocation and waits for it to settle before releasing the prompt gate.
+- Cancellation signals the agent, retries, compaction, summaries, and SDK bash execution. During asynchronous preflight it keeps requesting abort, so a subsequently started model run is also cancelled.
+- Interrupting a queued prompt does not abort the currently running prompt.
+- Resource release stops owned work, stops the checkpoint worker, saves final state, unsubscribes, disposes Pi, and removes temporary files.
+- Pi's resource reload and session factory have no cancellation API. Acquisition waits for them to return so late resources can be released. Resource scopes invalidate extension runtimes even when later model/session setup fails. Model creation and credential setup receive Effect's cancellation signal. An in-flight store commit is also protected from interruption.
+
+**Cancellation is cooperative, not a hard deadline.** Broken/stalled tools, extensions, SDK acquisition, or stores can delay timeout completion and shutdown. Use bounded backend operations and process isolation when you need a forced termination boundary.
+
+Cluster prompt handlers are interruptible and prompt RPCs are **not persisted**. Cancellation must reach the runner to stop remote work. A lost connection, timeout, or runner failure does not prove that no model/tool work occurred; do not automatically retry an uncertain prompt.
+
+## Results, errors, and events
+
+`PromptResult.text` and `stopReason` describe the last **new** assistant response. An extension command that produces no assistant response fails rather than returning an old answer. SDK terminal `error`/`aborted` responses become `Session.Error` failures with the SDK diagnostic when available.
+
+Token and cost fields sum usage recorded in entries appended during the invocation: assistant responses, tool-reported nested usage, compaction, and branch summaries. Total tokens can include cached tokens. These are SDK estimates, not billing guarantees; unreported extension/provider work cannot be counted.
+
+Operational failures use `_tag: "SessionError"` with `sessionId`, `operation`, and `message`. An explicit abort or caller interruption interrupts the prompt Effect. A failed release checkpoint surfaces as a **defect carrying `Session.Error`**, since scope finalizers do not have a typed error channel. Model-fallback and extension-load diagnostics are logged as warnings; background checkpoint failures are logged and retried at subsequent checkpoint boundaries.
+
+Events have monotonically increasing sequence numbers **per live resource**, resetting on restoration. The live buffer holds 1,024 events and discards oldest events on overflow. Slow subscribers can see gaps. There is no replay or subscription persistence. Reconcile using `snapshot`/`jsonl` or the completed prompt result; an event is not a durability acknowledgement.
+
+Start the stream before prompting. Across Cluster, starting a client fiber does not acknowledge that the remote subscription is established, so initial events can be missed. See [cluster-session.ts](../examples/cluster-session.ts) for best-effort event consumption in a scope.
+
+## Persistence contract
+
+The configured `KeyValueStore` holds `<keyPrefix><sessionId>`; the default prefix is `effect-pi/sessions/`. Each value is one complete Pi JSONL document.
+
+The document is materialized in a scoped temporary directory and opened with Pi's `SessionManager`. Pi owns entry formats, migrations, and conversation-tree behavior. Malformed JSON syntax and mismatched session ids fail loading without overwriting the store; this is not a complete validator for hostile documents.
+
+- Successful construction, prompt completion, and abort include a successful checkpoint.
+- SDK state-change notifications request background checkpoints; redundant pending requests are coalesced.
+- Failed/interrupted calls may still have changed state or performed external work.
+- After abrupt process loss, recovery is limited to the last **successfully committed** document.
+
+The backend must provide **atomic replacement**, suitable durability, and enough capacity for a whole conversation document. `KeyValueStore.layerMemory` is useful only for ephemeral sessions/tests. The pinned Effect `layerFileSystem` overwrites files directly and is **not crash-atomic**; the examples use `layerSql` instead.
+
+There must be one writer per key. Separate local pools, direct constructors, or unrelated clusters must not share ownership accidentally. This library does not add compare-and-swap revisions or fencing; deployments that need protection from independent writers or stale owners need stronger coordination at the storage boundary. Back up the store and define retention/deletion policies in the host application.
+
+## Trust and security
+
+Without explicit configuration, Pi can inherit credentials, model settings, extensions, skills, and context from the environment, home directory, and workspace. Its default tool set includes shell execution and file mutation. Extensions are executable code; `noTools` does not turn them into a sandbox.
+
+Host applications are responsible for:
+
+- Authenticating callers and authorizing access to session ids and JSONL.
+- Isolating untrusted code/prompts from credentials, files, and network access.
+- Protecting transcripts and logs, which may contain source code, tool output, or secrets.
+- Model spending limits, request/concurrency limits, tool policies, storage permissions, encryption, backups, and retention.
+- Securing cluster transport and database access. The example binds loopback and has no application authentication.
+
+There is no multi-tenant security boundary here. Treat stored JSONL, configured SDK resources, and runner configuration as trusted inputs. Report security concerns privately to the maintainer rather than including credentials or private transcripts in an issue.

package/examples/README.md

@@ -0,0 +1,111 @@
+# Examples
+
+Each example is a complete program. Pick one file and copy it into your project—there are no imports from other examples or shared helpers. The repeated setup is intentional.
+
+| Example | What it shows |
+| --- | --- |
+| [single-session.ts](single-session.ts) | Create one session, send a prompt, and save its history in SQLite. |
+| [local-session-pool.ts](local-session-pool.ts) | Open a session through a pool, release it, then reopen it in another request scope. |
+| [cluster-session.ts](cluster-session.ts) | Start a runner and a client in the same process, send requests over a local socket, then shut both down. |
+
+## Setup
+
+Use Node 26 and the pnpm version in `package.json`:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+Create the fixed data directory before running (Unix commands):
+
+```sh
+mkdir -p .data/effect-pi
+chmod 700 .data/effect-pi
+```
+
+Choose a model in Pi's built-in catalog and supply its API key. For example:
+
+```sh
+export EFFECT_PI_PROVIDER=anthropic
+export EFFECT_PI_MODEL=claude-sonnet-4-5
+# Set EFFECT_PI_API_KEY through your shell or secret manager. Don't commit it.
+```
+
+The layers are defined at module scope: resources feed the model runtime, which feeds sessions. Only the model and credentials come from configuration; incidental paths and settings are ordinary literals you can edit.
+
+There are no Pi imports or Promise adapters. Your API key is not saved, and your usual Pi extensions, skills, prompts, and context files aren't loaded. The enabled tools are `read`, `grep`, `find`, and `ls`.
+
+## Run an example
+
+Effect CLI handles the optional prompt, `--snapshot`, and `--help`. With no prompt argument, the default is “Say hello in one short sentence.” Quote prompts containing spaces. `--help` needs neither credentials nor the data directory.
+
+```sh
+pnpm example:session "Say hello in one sentence"
+pnpm example:pool "Say hello in one sentence"
+pnpm example:cluster "Say hello in one sentence"
+```
+
+Or run the compiled files directly:
+
+```sh
+node dist-examples/single-session.js "Say hello in one sentence"
+node dist-examples/local-session-pool.js "Say hello in one sentence"
+node dist-examples/cluster-session.js "Say hello in one sentence"
+```
+
+All three save conversations in `.data/effect-pi/sessions.sqlite`. Run an example again from the same working directory to continue its conversation. The pool example also reopens the session before exiting and prints its snapshot, showing how separate requests can use the same pool.
+
+### Try it without a model request
+
+Pass `--snapshot` instead of a prompt. This creates or restores a real session but doesn't invoke a model or any tools, so a dummy key is sufficient:
+
+```sh
+EFFECT_PI_API_KEY=unused-snapshot-only pnpm example:cluster --snapshot
+```
+
+Keep the provider and model variables set. Normal prompt mode makes paid model calls and prints live events followed by the result.
+
+## Defaults you can edit
+
+Paths, session ids, and the cluster port are fixed in the source. Tools work in `"."`; session ids are `single-session`, `pooled-session`, and `cluster-session`. The cluster runner listens on `127.0.0.1:34431`. Change those literals if your application needs something different.
+
+Independent owners must not write to the same session id in the same database concurrently.
+
+## How the cluster example runs
+
+You only need **one command and one terminal**. `cluster-session.ts` starts the runner, creates a separate client runtime, and uses the public `Sessions` API to make a request. The client discovers the runner through a shared in-memory store and connects over a real loopback socket; this isn't a fake transport or a direct call to the runner's session.
+
+Both runtimes live in the same Effect scope. When the program finishes or is interrupted, it closes the client and runner and releases their resources. There is no background server to stop manually.
+
+This is a local demonstration. Running across machines requires a shared database such as Postgres and secured transport, not SQLite on a network share. The example uses in-memory storage for cluster coordination and SQLite for saved conversations. Prompt requests are not persisted for replay. See the [reference guide](../docs/reference.md#cluster-sessions) for deployment details.
+
+## Safety and cancellation
+
+- Read-only tools are **not a sandbox**: they can read outside the working directory. Use trusted workspaces.
+- Keep `.data/effect-pi` private (the setup command uses mode `0700` on Unix). Conversations and logs are not encrypted and may contain private data.
+- Live events are best-effort. A remote subscription can miss initial events; use the completed result or a snapshot to reconcile.
+- Prompts have a two-minute timeout. Cancellation and Ctrl+C still wait for Pi, its tools, and storage writes to settle. They do not undo file changes or model charges.
+
+## Copying an example into another project
+
+Install `@jpowersdev/effect-pi` using a [local tarball or published release](../docs/reference.md#installation-and-compatibility), then add the packages imported by the example:
+
+```sh
+pnpm add effect@4.0.0-rc.116 \
+  @effect/platform-node@4.0.0-rc.116 @effect/sql-sqlite-node@4.0.0-rc.116
+```
+
+Use an ESM project (`"type": "module"`). Node 26 can run the copied TypeScript file directly:
+
+```sh
+node single-session.ts --snapshot
+```
+
+Create `.data/effect-pi` and set the model/credential variables as described above. If you compile with TypeScript, use NodeNext and `skipLibCheck` for the pinned upstream declarations.
+
+The npm tarball includes the source and compiled examples too. With their optional dependencies installed, you can run one without copying it:
+
+```sh
+node node_modules/@jpowersdev/effect-pi/dist-examples/single-session.js --snapshot
+```

package/examples/cluster-session.ts

@@ -0,0 +1,131 @@
+/** Start a runner and a separate cluster client in one process, then shut both down. */
+import * as NodeClusterSocket from "@effect/platform-node/NodeClusterSocket"
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import * as SqliteClient from "@effect/sql-sqlite-node/SqliteClient"
+
+import * as Config from "effect/Config"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import * as Stream from "effect/Stream"
+import * as Argument from "effect/unstable/cli/Argument"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import * as MessageStorage from "effect/unstable/cluster/MessageStorage"
+import * as RunnerAddress from "effect/unstable/cluster/RunnerAddress"
+import * as RunnerStorage from "effect/unstable/cluster/RunnerStorage"
+import * as ShardingConfig from "effect/unstable/cluster/ShardingConfig"
+import * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+
+import { ClusterSessions, ModelRuntime, ResourceLoader, Session, Sessions } from "@jpowersdev/effect-pi"
+
+// Model and resource configuration belongs to the runner, not the cluster client.
+const ResourcesLive = ResourceLoader.layerEmpty({
+  systemPrompt: "You are a helpful assistant. Use the read-only tools only when asked to inspect files.",
+  settings: { retry: { enabled: false } }
+})
+
+const ModelLive = ModelRuntime.layerConfig(
+  Config.all({
+    provider: Config.NonEmptyString("EFFECT_PI_PROVIDER"),
+    modelId: Config.NonEmptyString("EFFECT_PI_MODEL"),
+    apiKey: Config.Redacted("EFFECT_PI_API_KEY")
+  }).pipe(
+    Config.map(({ provider, modelId, apiKey }) => ({
+      model: { provider, id: modelId },
+      apiKeys: { [provider]: apiKey },
+      authPath: ".data/effect-pi/auth.json",
+      modelsPath: null,
+      refreshOnCreate: false
+    }))
+  )
+).pipe(
+  Layer.provide(ResourcesLive)
+)
+
+const StoreLive = KeyValueStore.layerSql({ table: "pi_sessions" }).pipe(
+  Layer.provide(
+    SqliteClient.layer({ filename: ".data/effect-pi/sessions.sqlite" })
+  )
+)
+
+// Both runtimes share in-memory discovery; only conversation documents use SQLite.
+const DiscoveryLive = Layer.merge(RunnerStorage.layerMemory, MessageStorage.layerMemory).pipe(
+  Layer.provide(ShardingConfig.layer())
+)
+
+const RunnerSharding = NodeClusterSocket.layer({
+  storage: "byo",
+  serialization: "ndjson",
+  shardingConfig: {
+    runnerAddress: Option.some(RunnerAddress.make("127.0.0.1", 34431))
+  }
+}).pipe(
+  Layer.fresh,
+  Layer.provide(DiscoveryLive)
+)
+
+// Fresh sharding runtimes make requests travel over the socket, not local dispatch.
+const ClientSharding = NodeClusterSocket.layer({
+  clientOnly: true,
+  storage: "byo",
+  serialization: "ndjson",
+  shardingConfig: { runnerAddress: Option.none() }
+}).pipe(
+  Layer.fresh,
+  Layer.provide(DiscoveryLive)
+)
+
+const RunnerLive = ClusterSessions.runnerLayer({
+  cwd: ".",
+  configure: () => ({ tools: ["read", "grep", "find", "ls"] })
+}).pipe(
+  Layer.provide([ModelLive, StoreLive, RunnerSharding])
+)
+
+const ClientLive = ClusterSessions.clientLayer.pipe(
+  Layer.provide(ClientSharding),
+  // Register the runner first and keep it alive until the client exits.
+  Layer.provide(RunnerLive)
+)
+
+const cli = Command.make("cluster-session", {
+  prompt: Argument.String("prompt").pipe(
+    Argument.withDefault("Say hello in one short sentence.")
+  ),
+  snapshot: Flag.Boolean("snapshot").pipe(
+    Flag.withDefault(false),
+    Flag.withDescription("Print saved state without calling a model")
+  )
+}, ({ prompt, snapshot }) =>
+  Effect.gen(function* () {
+    const sessions = yield* Sessions
+
+    const session = yield* sessions.open(Session.Id.make("cluster-session"))
+
+    if (snapshot) {
+      return yield* Console.log(yield* session.snapshot)
+    }
+
+    // Remote subscriptions are best-effort; use the prompt result to reconcile.
+    yield* session.events.pipe(
+      Stream.runForEach((event) => Console.log(event)),
+      Effect.catch((error) => Console.warn(error)),
+      Effect.forkScoped({ startImmediately: true })
+    )
+
+    const result = yield* session.prompt(prompt).pipe(Effect.timeout("2 minutes"))
+
+    yield* Console.log("Result:", result)
+  }).pipe(Effect.scoped)
+).pipe(
+  Command.provide(ClientLive)
+)
+
+const program = Command.run(cli, { version: "0.1.0" }).pipe(
+  Effect.provide(NodeServices.layer)
+)
+
+NodeRuntime.runMain(program)

package/examples/local-session-pool.ts

@@ -0,0 +1,107 @@
+/** Share sessions by id and reopen them across separate request scopes. */
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import * as SqliteClient from "@effect/sql-sqlite-node/SqliteClient"
+
+import * as Config from "effect/Config"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Stream from "effect/Stream"
+import * as Argument from "effect/unstable/cli/Argument"
+import * as Command from "effect/unstable/cli/Command"
+import * as Flag from "effect/unstable/cli/Flag"
+import * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+
+import { LocalSessions, ModelRuntime, ResourceLoader, Session, Sessions } from "@jpowersdev/effect-pi"
+
+const ResourcesLive = ResourceLoader.layerEmpty({
+  systemPrompt: "You are a helpful assistant. Use the read-only tools only when asked to inspect files.",
+  settings: { retry: { enabled: false } }
+})
+
+const ModelLive = ModelRuntime.layerConfig(
+  Config.all({
+    provider: Config.NonEmptyString("EFFECT_PI_PROVIDER"),
+    modelId: Config.NonEmptyString("EFFECT_PI_MODEL"),
+    apiKey: Config.Redacted("EFFECT_PI_API_KEY")
+  }).pipe(
+    Config.map(({ provider, modelId, apiKey }) => ({
+      model: { provider, id: modelId },
+      apiKeys: { [provider]: apiKey },
+      authPath: ".data/effect-pi/auth.json",
+      modelsPath: null,
+      refreshOnCreate: false
+    }))
+  )
+).pipe(
+  Layer.provide(ResourcesLive)
+)
+
+const StoreLive = KeyValueStore.layerSql({ table: "pi_sessions" }).pipe(
+  Layer.provide(
+    SqliteClient.layer({ filename: ".data/effect-pi/sessions.sqlite" })
+  )
+)
+
+const SessionsLive = LocalSessions.layer({
+  cwd: ".",
+  idleTimeToLive: "1 minute",
+  configure: () => ({ tools: ["read", "grep", "find", "ls"] })
+}).pipe(
+  Layer.provide([ModelLive, StoreLive])
+)
+
+const cli = Command.make("local-session-pool", {
+  prompt: Argument.String("prompt").pipe(
+    Argument.withDefault("Say hello in one short sentence.")
+  ),
+  snapshot: Flag.Boolean("snapshot").pipe(
+    Flag.withDefault(false),
+    Flag.withDescription("Print saved state without calling a model")
+  )
+}, ({ prompt, snapshot }) =>
+  Effect.gen(function* () {
+    const sessions = yield* Sessions
+
+    const id = Session.Id.make("pooled-session")
+
+    // A request holds a reference to the session for the duration of its scope.
+    yield* Effect.scoped(
+      Effect.gen(function* () {
+        const session = yield* sessions.open(id)
+
+        if (snapshot) {
+          return yield* Console.log(yield* session.snapshot)
+        }
+
+        yield* session.events.pipe(
+          Stream.runForEach((event) => Console.log(event)),
+          Effect.catch((error) => Console.warn(error)),
+          Effect.forkScoped({ startImmediately: true })
+        )
+
+        const result = yield* session.prompt(prompt).pipe(Effect.timeout("2 minutes"))
+
+        yield* Console.log("Result:", result)
+      })
+    )
+
+    // Reuse the same live session before the idle TTL; after eviction, restore from SQLite.
+    yield* Effect.scoped(
+      Effect.gen(function* () {
+        const session = yield* sessions.open(id)
+
+        yield* Console.log("Reopened:", yield* session.snapshot)
+      })
+    )
+  }).pipe(Effect.scoped)
+).pipe(
+  Command.provide(SessionsLive)
+)
+
+const program = Command.run(cli, { version: "0.1.0" }).pipe(
+  Effect.provide(NodeServices.layer)
+)
+
+NodeRuntime.runMain(program)