@jpowersdev/effect-pi 0.1.0

package/examples/single-session.ts

@@ -0,0 +1,85 @@
+/** Create one session, send a prompt, and save its history in SQLite. */
+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 { ModelRuntime, ResourceLoader, Session } 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 cli = Command.make("single-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 session = yield* Session.make({
+      id: Session.Id.make("single-session"),
+      cwd: ".",
+      configure: () => ({ tools: ["read", "grep", "find", "ls"] })
+    })
+
+    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)
+  }).pipe(Effect.scoped)
+).pipe(
+  Command.provide(Layer.merge(ModelLive, StoreLive))
+)
+
+const program = Command.run(cli, { version: "0.1.0" }).pipe(
+  Effect.provide(NodeServices.layer)
+)
+
+NodeRuntime.runMain(program)

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@jpowersdev/effect-pi",
+  "version": "0.1.0",
+  "description": "Local and clustered Effect services for durable Pi coding-agent sessions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpowersdev/effect-pi.git"
+  },
+  "homepage": "https://github.com/jpowersdev/effect-pi#readme",
+  "bugs": "https://github.com/jpowersdev/effect-pi/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "examples/*.ts",
+    "examples/README.md",
+    "dist-examples",
+    "docs/**/*.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.86.1"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.116"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.116",
+    "@effect/sql-sqlite-node": "4.0.0-rc.116",
+    "effect": "4.0.0-rc.116",
+    "@effect/vitest": "4.0.0-rc.116",
+    "@types/node": "26.4.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "scripts": {
+    "build": "tsc -b src examples",
+    "check": "tsc -b",
+    "clean": "tsc -b --clean && rm -rf dist dist-test dist-examples .tsbuildinfo",
+    "test": "vitest run",
+    "example:session": "pnpm build && node dist-examples/single-session.js",
+    "example:pool": "pnpm build && node dist-examples/local-session-pool.js",
+    "example:cluster": "pnpm build && node dist-examples/cluster-session.js"
+  }
+}

package/src/ClusterSessions.ts

@@ -0,0 +1,6 @@
+export {
+  clientLayer,
+  runnerLayer,
+  runnerLayerConfig,
+  type Options
+} from "./internal/ClusterSessions.js"

package/src/LocalSessions.ts

@@ -0,0 +1 @@
+export { layer, layerConfig, type Options } from "./internal/LocalSessions.js"

package/src/ModelRuntime.ts

@@ -0,0 +1,10 @@
+export {
+  type Binding,
+  Error,
+  layer,
+  layerConfig,
+  make,
+  ModelRuntime,
+  type Operations,
+  type Options
+} from "./internal/ModelRuntime.js"

package/src/ResourceLoader.ts

@@ -0,0 +1,13 @@
+export {
+  Error,
+  layer,
+  layerConfig,
+  layerEmpty,
+  layerEmptyConfig,
+  type EmptyOptions,
+  type Loaded,
+  type Operations,
+  type Options,
+  ResourceLoader,
+  type Settings
+} from "./internal/ResourceLoader.js"

package/src/Session.ts

@@ -0,0 +1,14 @@
+export {
+  Error,
+  Event,
+  Id,
+  type Config,
+  type MakeOptions,
+  type Operation,
+  type PiOptions,
+  PromptResult,
+  type Session,
+  Snapshot,
+  Status
+} from "./internal/Session.js"
+export { make } from "./internal/Pi.js"

package/src/Sessions.ts

@@ -0,0 +1,17 @@
+import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+
+import type * as Session from "./internal/Session.js"
+
+export interface Operations {
+  /** Acquire the session for an id within the current scope. */
+  readonly open: (
+    id: Session.Id
+  ) => Effect.Effect<Session.Session, Session.Error, Scope.Scope>
+}
+
+/** Location-independent access to keyed Pi sessions. */
+export class Sessions extends Context.Service<Sessions, Operations>()(
+  "@jpowersdev/effect-pi/Sessions"
+) {}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * as ClusterSessions from "./ClusterSessions.js"
+export * as LocalSessions from "./LocalSessions.js"
+export * as ModelRuntime from "./ModelRuntime.js"
+export * as ResourceLoader from "./ResourceLoader.js"
+export * as Session from "./Session.js"
+export { Sessions } from "./Sessions.js"

package/src/internal/ClusterSessions.ts

@@ -0,0 +1,126 @@
+import * as Config from "effect/Config"
+import type * as Duration from "effect/Duration"
+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"
+import * as Stream from "effect/Stream"
+import * as Entity from "effect/unstable/cluster/Entity"
+import * as EntityResource from "effect/unstable/cluster/EntityResource"
+import type * as Sharding from "effect/unstable/cluster/Sharding"
+
+import { Sessions } from "../Sessions.js"
+import * as Pi from "./Pi.js"
+import * as Protocol from "./Protocol.js"
+import * as Session from "./Session.js"
+
+export interface Options extends Session.Config {
+  /** Idle live-resource lifetime; defaults to 15 minutes. */
+  readonly resourceIdleTimeToLive?: Duration.Input
+  readonly entityMaxIdleTime?: Duration.Input
+  /** Queued entity messages; does not limit all concurrently executing handlers. Defaults to 128. */
+  readonly mailboxCapacity?: number | "unbounded"
+}
+
+type MakeSession<R> = (
+  options: Session.MakeOptions
+) => Effect.Effect<Session.Session, Session.Error, Scope.Scope | R>
+
+const failureMessage = (cause: unknown): string => {
+  if (typeof cause === "object" && cause !== null && "message" in cause) {
+    return String(cause.message)
+  }
+  return String(cause)
+}
+
+const transportError = (
+  id: Session.Id,
+  operation: Session.Operation,
+  cause: unknown
+) => cause instanceof Session.Error
+  ? cause
+  : new Session.Error({
+    sessionId: id,
+    operation,
+    message: failureMessage(cause)
+  })
+
+/** Internal constructor seam used to test entity behavior without model calls. */
+export const runnerLayerWith = <R>(
+  options: Options,
+  makeSession: MakeSession<R>
+): Layer.Layer<never, never, Sharding.Sharding | R> => {
+  const handlers = Effect.gen(function*() {
+    const address = yield* Entity.CurrentAddress
+    const id = yield* Schema.decodeUnknownEffect(Session.Id)(address.entityId).pipe(
+      Effect.orDie
+    )
+    const resource = yield* EntityResource.make({
+      acquire: makeSession({
+        id,
+        cwd: options.cwd,
+        ...(options.keyPrefix === undefined ? {} : { keyPrefix: options.keyPrefix }),
+        ...(options.configure === undefined ? {} : { configure: options.configure })
+      }),
+      idleTimeToLive: options.resourceIdleTimeToLive ?? "15 minutes"
+    }).pipe(Effect.orDie)
+
+    return Protocol.entity.of({
+      Snapshot: () => resource.get.pipe(Effect.flatMap((session) => session.snapshot)),
+      Prompt: (request) => resource.get.pipe(
+        Effect.flatMap((session) => session.prompt(request.payload.text))
+      ),
+      Abort: () => resource.get.pipe(Effect.flatMap((session) => session.abort)),
+      Jsonl: () => resource.get.pipe(Effect.flatMap((session) => session.jsonl)),
+      Events: () => Stream.unwrap(resource.get.pipe(
+        Effect.map((session) => session.events)
+      ))
+    })
+  })
+
+  return Protocol.entity.toLayer(handlers, {
+    concurrency: "unbounded",
+    mailboxCapacity: options.mailboxCapacity ?? 128,
+    maxIdleTime: options.entityMaxIdleTime ?? "20 minutes"
+  })
+}
+
+/** Registers the server-side cluster entity handlers. */
+export const runnerLayer = (options: Options) => runnerLayerWith(options, Pi.make)
+
+/** Resolve runner options using the active ConfigProvider at layer build time. */
+export const runnerLayerConfig = (options: Config.Wrap<Options>) =>
+  Layer.unwrap(Effect.map(Config.unwrap<Options>(options), runnerLayer))
+
+/** Implements Sessions using location-transparent Effect Cluster clients. */
+export const clientLayer: Layer.Layer<Sessions, never, Sharding.Sharding> = Layer.effect(
+  Sessions,
+  Protocol.entity.client.pipe(
+    Effect.map((makeClient) => Sessions.of({
+      open: (id) => Effect.succeed((() => {
+        const client = makeClient(id)
+        return {
+          id,
+          snapshot: client.Snapshot().pipe(
+            Effect.mapError((cause) => transportError(id, "snapshot", cause))
+          ),
+          prompt: (text) => Schema.decodeUnknownEffect(Schema.NonEmptyString)(text).pipe(
+            Effect.flatMap((text) => client.Prompt({ text })),
+            Effect.mapError((cause) => transportError(id, "prompt", cause))
+          ),
+          abort: client.Abort().pipe(
+            Effect.mapError((cause) => transportError(id, "abort", cause))
+          ),
+          events: client.Events().pipe(
+            Stream.mapError((cause) => transportError(id, "events", cause))
+          ),
+          jsonl: client.Jsonl().pipe(
+            Effect.mapError((cause) => transportError(id, "jsonl", cause))
+          )
+        } satisfies Session.Session
+      })())
+    }))
+  )
+)
+
+export const entity = Protocol.entity

package/src/internal/LocalSessions.ts

@@ -0,0 +1,45 @@
+import * as Config from "effect/Config"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as RcMap from "effect/RcMap"
+import type * as Scope from "effect/Scope"
+
+import { Sessions } from "../Sessions.js"
+import * as Pi from "./Pi.js"
+import type * as Session from "./Session.js"
+
+export interface Options extends Session.Config {
+  /** How long an unreferenced live Pi session remains resident. */
+  readonly idleTimeToLive?: Duration.Input
+}
+
+type MakeSession<R> = (
+  options: Session.MakeOptions
+) => Effect.Effect<Session.Session, Session.Error, Scope.Scope | R>
+
+/** Internal constructor seam used to verify pool behavior without model calls. */
+export const layerWith = <R>(
+  options: Options,
+  makeSession: MakeSession<R>
+): Layer.Layer<Sessions, never, R> => Layer.effect(Sessions, Effect.gen(function*() {
+  const sessions = yield* RcMap.make({
+    lookup: (id: Session.Id) => makeSession({
+      id,
+      cwd: options.cwd,
+      ...(options.keyPrefix === undefined ? {} : { keyPrefix: options.keyPrefix }),
+      ...(options.configure === undefined ? {} : { configure: options.configure })
+    }),
+    idleTimeToLive: options.idleTimeToLive ?? "15 minutes"
+  })
+
+  return Sessions.of({
+    open: (id) => RcMap.get(sessions, id)
+  })
+}))
+
+export const layer = (options: Options) => layerWith(options, Pi.make)
+
+/** Resolve pool 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))

package/src/internal/ModelRuntime.ts

@@ -0,0 +1,105 @@
+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 Redacted from "effect/Redacted"
+import * as Schema from "effect/Schema"
+import type * as Scope from "effect/Scope"
+
+import * as ResourceLoader from "./ResourceLoader.js"
+
+export interface Options extends Omit<Pi.CreateModelRuntimeOptions, "signal"> {
+  /** Omit to let Pi restore/select the model using the session and settings. */
+  readonly model?: { readonly provider: string; readonly id: string }
+
+  /** Runtime-only overrides. Keys are never persisted to auth.json. */
+  readonly apiKeys?: Readonly<Record<string, Redacted.Redacted<string>>>
+}
+
+export class Error extends Schema.TaggedError<Error>()("ModelRuntimeError", {
+  operation: Schema.Literals(["create", "providers", "credentials", "model"]),
+  message: Schema.String
+}) {}
+
+/** SDK interoperability values; never share one binding between live sessions. */
+export interface Binding extends ResourceLoader.Loaded {
+  readonly modelRuntime: Pi.ModelRuntime
+  readonly model?: NonNullable<Pi.CreateAgentSessionOptions["model"]>
+}
+
+export interface Operations {
+  readonly sessionOptions: (
+    cwd: string
+  ) => Effect.Effect<Binding, Error | ResourceLoader.Error, Scope.Scope>
+}
+
+export class ModelRuntime extends Context.Service<ModelRuntime, Operations>()(
+  "@jpowersdev/effect-pi/ModelRuntime"
+) {}
+
+/** Capture the loading policy; SDK objects are owned by each live session's scope. */
+export const make = Effect.fn("ModelRuntime.make")(function* (options: Options = {}) {
+  const resources = yield* ResourceLoader.ResourceLoader
+
+  const { model: selection, apiKeys, ...runtimeOptions } = options
+
+  const sessionOptions: Operations["sessionOptions"] = Effect.fn("ModelRuntime.sessionOptions")(function* (cwd) {
+    const loaded = yield* resources.load(cwd)
+
+    const modelRuntime = yield* Effect.tryPromise({
+      try: (signal) => Pi.ModelRuntime.create({ ...runtimeOptions, signal }),
+      // SDK credential errors can contain raw keys. Do not retain or stringify them.
+      catch: () => new Error({ operation: "create", message: "Unable to create Pi model runtime" })
+    })
+
+    // Extensions can define the selected model. Register their providers before
+    // lookup; leave Pi's pending queues intact for its own subsequent binding.
+    yield* Effect.try({
+      try: () => {
+        const runtime = loaded.resourceLoader.getExtensions().runtime
+
+        for (const { name, config } of runtime.pendingProviderRegistrations) {
+          modelRuntime.registerProvider(name, config)
+        }
+
+        for (const { provider } of runtime.pendingNativeProviderRegistrations) {
+          modelRuntime.registerNativeProvider(provider)
+        }
+      },
+      catch: () => new Error({ operation: "providers", message: "Unable to register resource providers" })
+    })
+
+    for (const [provider, key] of Object.entries(apiKeys ?? {})) {
+      yield* Effect.tryPromise({
+        try: (signal) => modelRuntime.setRuntimeApiKey(provider, Redacted.value(key), { signal }),
+        catch: () => new Error({ operation: "credentials", message: "Unable to configure runtime credentials" })
+      })
+    }
+
+    if (selection === undefined) return { ...loaded, modelRuntime }
+
+    const model = yield* Effect.try({
+      try: () => modelRuntime.getModel(selection.provider, selection.id),
+      catch: () => new Error({ operation: "model", message: "Unable to resolve the configured model" })
+    })
+
+    if (model === undefined) {
+      return yield* new Error({
+        operation: "model",
+        message: `Unknown model ${selection.provider}/${selection.id}`
+      })
+    }
+
+    return { ...loaded, modelRuntime, model }
+  })
+
+  return ModelRuntime.of({ sessionOptions })
+})
+
+export const layer = (options: Options = {}): Layer.Layer<ModelRuntime, never, ResourceLoader.ResourceLoader> =>
+  Layer.effect(ModelRuntime, make(options))
+
+/** Resolve configuration when the layer is built, using the active ConfigProvider. */
+export const layerConfig = (options: Config.Wrap<Options>) =>
+  Layer.unwrap(Effect.map(Config.unwrap<Options>(options), layer))

package/src/internal/Persistence.ts

@@ -0,0 +1,40 @@
+import * as Effect from "effect/Effect"
+import * as KeyValueStore from "effect/unstable/persistence/KeyValueStore"
+
+import * as Session from "./Session.js"
+
+const message = (cause: unknown): string => {
+  if (typeof cause === "object" && cause !== null && "message" in cause) {
+    return String(cause.message)
+  }
+  return String(cause)
+}
+
+export interface Store {
+  readonly load: Effect.Effect<string | undefined, Session.Error>
+  readonly save: (jsonl: string) => Effect.Effect<void, Session.Error>
+}
+
+export const make = Effect.fnUntraced(function* (
+  id: Session.Id,
+  keyPrefix = "effect-pi/sessions/"
+) {
+  const backing = yield* KeyValueStore.KeyValueStore
+  const store = KeyValueStore.prefix(backing, keyPrefix)
+  return {
+    load: store.get(id).pipe(
+      Effect.mapError((cause) => new Session.Error({
+        sessionId: id,
+        operation: "load",
+        message: message(cause)
+      }))
+    ),
+    save: (jsonl) => store.set(id, jsonl).pipe(
+      Effect.mapError((cause) => new Session.Error({
+        sessionId: id,
+        operation: "save",
+        message: message(cause)
+      }))
+    )
+  } satisfies Store
+})