@oh-my-pi/pi-coding-agent 15.5.10 → 15.5.12

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [15.5.12] - 2026-05-29
+
+### Added
+
+- Added the `omp-plugins` discovery provider, which scans every extension package directory configured via `extensions:` (in `~/.omp/agent/settings.json` or `<cwd>/.omp/settings.json`) or `--extension`/`-e` on the CLI for `skills/`, `hooks/pre|post/`, `tools/`, `commands/`, `rules/`, `prompts/`, and `.mcp.json`. Prior to this, only the extension's TypeScript factory module ran; every sibling capability the docs (https://omp.sh/docs/extension-authoring) advertised was silently ignored ([#1496](https://github.com/can1357/oh-my-pi/issues/1496)).
+- Added the top-level `omp install <target>` subcommand documented at https://omp.sh/docs/extension-authoring. Local paths route to `omp plugin link` (so the directory is symlinked into the plugin set), and npm/marketplace specs route to `omp plugin install`. Before this, `install` was not a registered subcommand and the CLI runner silently forwarded `install ./my-extension` to `launch` as an initial LLM prompt ([#1496](https://github.com/can1357/oh-my-pi/issues/1496)).
+
+### Changed
+
+- Changed the sticky `Todos` panel above the editor to advance as tasks close, instead of pinning to the first 5 tasks of the active phase. `selectStickyTodoWindow` now shows up to 5 open (pending / in_progress) tasks in original phase order and reports the count of remaining open tasks for the `+N more` hint, so every `todo_write` flip produces a visible row shift. Closed-phase tail falls back to the last 5 tasks (with the `+N more` line suppressed) until `getActivePhase` walks to the next phase.
+- Linked the sticky `Todos` panel to the live `SessionObserverRegistry` so pending todos that have an in-flight subagent doing their work light up green with an animated spinner — the same `theme.spinnerFrames` ("status" preset) the `task` tool uses for its agent rows — instead of staying greyed out as if nothing is happening. A new exported `todoMatchesAnyDescription(content, descriptions)` does case- and whitespace-insensitive equality first with a 6-char minimum-overlap substring fallback in either direction, so "Sonnet #2: shallow bug scan" and a subagent description of "Sonnet #2" still link up. Completed todos now render with `theme.status.success` (✔ / `\uf00c` / `[ok]` per symbol preset, still wrapped in the `success` colour so themed palettes can keep their purple/green/whatever) and in_progress rows render with `theme.status.running`, matching the `task` tool's icon vocabulary. The spinner interval only ticks while at least one visible open todo has a matched active subagent, and self-stops once subagents finish, so plain in_progress todos do not animate forever in the absence of subagent activity.
+- Extracted the top-level CLI command table from `src/cli.ts` into a side-effect-free `src/cli-commands.ts` so test code can introspect the registered subcommands without triggering the entrypoint's top-level await.
+
+## [15.5.11] - 2026-05-29
+
+### Added
+
+- Added `SqlSessionStorage`, a `bun:sql`-backed implementation of `SessionStorage` that persists session JSONL into PostgreSQL, MySQL/MariaDB, or SQLite. Pass a connected `Bun.SQL` instance (the constructor accepts `postgres://`, `mysql://`, or `sqlite:` URLs) to `SqlSessionStorage.create({ client, table?, adapter?, createTable? })` and hand the returned storage to any `SessionManager` factory. The dialect is auto-detected from `client.options.adapter` and used to pick the correct DDL plus upsert-with-append syntax (`ON CONFLICT … DO UPDATE` for PG/SQLite, `ON DUPLICATE KEY UPDATE` for MySQL), so the agent's append-only persist pattern works in a single round-trip per line. Same in-memory mirror and `drain()` semantics as the Redis backend; blobs and tool artifacts still live on disk via `ArtifactManager`/`BlobStore`.
+- Added `RedisSessionStorage`, a `bun:redis`-backed implementation of the `SessionStorage` interface that lets API consumers route session JSONL through Redis instead of local disk. Pass a connected `Bun.RedisClient` (or any compatible adapter) to `RedisSessionStorage.create({ client, prefix? })` and hand the returned storage to `SessionManager.create(cwd, sessionDir, storage)` (or any other static factory that accepts a storage argument). An in-memory mirror is loaded on creation so the interface's synchronous methods (`existsSync`, `statSync`, `listFilesSync`, …) keep their contracts; `drain()` waits for queued background writes. Tool artifacts and image blobs still live on disk via `ArtifactManager`/`BlobStore` — Redis only owns the session JSONL keyspace under the configured prefix.
+- Exported the `SessionStorage` / `SessionStorageWriter` / `FileSessionStorage` / `MemorySessionStorage` symbols (already reachable via the `./session/session-storage` subpath) from the package root so SDK consumers can construct alternative storage backends without deep-importing.
+- Added a fresh `¶<relative-path>#TAG` snapshot header to the `write` tool's success text in hashline display mode, covering plain disk writes, ACP-bridge writes, and conflict resolutions (bulk resolutions emit a trailing `Snapshots:` block with one header per successfully written file). The header records a current snapshot in the file-snapshot store so the next `edit` can land without an extra `read` round-trip. Suppressed when the session is not in hashline mode and skipped for archive/SQLite writes and host-managed internal URL targets where hashline anchors do not apply.
+
+### Changed
+
+- The `edit` tool's stale-snapshot rejection message now distinguishes "file changed between read and edit" (the section's hash was recorded in this session but the file has since drifted — a prior in-session edit advanced it, or an external write changed it) from "hash #X is not from this session" (a fabricated or carried-over cross-session tag), the latter carrying explicit "never invent the tag" guidance. Both messages include the current file hash plus 2 lines of context around each anchor so the next attempt has everything it needs. Snapshot-based recovery still runs first; the sharper diagnostics only surface when recovery cannot reconcile the edit.
+
+### Fixed
+
+- Fixed Autonomous Memory phase 1/phase 2 failing with `Thinking effort low is not supported by <provider>/<model>` on models whose supported reasoning efforts exclude `low`/`medium` (e.g. `deepseek/deepseek-v4-pro`). Both stage1 (`Effort.Low`) and consolidation (`Effort.Medium`) call sites in `packages/coding-agent/src/memories/index.ts` now route through `clampThinkingLevelForModel`, lifting the requested effort to the model's lowest supported level instead of letting `requireSupportedEffort` throw ([#1480](https://github.com/can1357/oh-my-pi/issues/1480)).
+
 ## [15.5.10] - 2026-05-28
 
 ### Added
@@ -12,6 +42,10 @@
 
 - Fixed compaction surfacing raw HTTP 401/403 envelopes (e.g. `Compaction failed: 401 {"type":"error","error":{"type":"authentication_error",…}}`) instead of routing to an authenticated fallback model. The compaction layer now attaches the provider-reported HTTP status onto the thrown error, and `AgentSession`'s auth-failure detector branches on `error.status === 401 || 403` in addition to the existing `auth_unavailable` regex. When a fallback model role (e.g. `modelRoles.smol`) is configured, compaction retries it transparently; otherwise the user sees the actionable "Compaction requires usable credentials for …" hint instead of the raw provider envelope.
 
+### Fixed
+
+- Fixed compiled-binary legacy plugin loading for `@earendil-works/*` imports of bundled package roots such as `@earendil-works/pi-coding-agent`; compat now rewrites all bundled pi package roots to bunfs entrypoints and resolves fallback peer dependencies through the canonical `@oh-my-pi/*` specifier.
+
 ## [15.5.8] - 2026-05-28
 
 ### Breaking Changes

package/dist/types/cli-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Top-level CLI command table.
+ *
+ * Lives in its own module (importable without side effects) so that tests can
+ * inspect the registered subcommands without triggering the side-effectful
+ * top-level await in `cli.ts`. Adding a new subcommand here is enough to make
+ * `runCli` route to it instead of forwarding the argv as a prompt to
+ * `launch` — see #1496 for the original "args silently leak to the LLM"
+ * regression that motivated the split.
+ */
+import type { CommandEntry } from "@oh-my-pi/pi-utils/cli";
+export declare const commands: CommandEntry[];
+/**
+ * Return true when `first` matches a registered subcommand name or alias.
+ *
+ * Flags (`-…`) and `@file` arguments are never subcommands; for those the CLI
+ * runner skips ahead to the default `launch` command.
+ */
+export declare function isSubcommand(first: string | undefined): boolean;

package/dist/types/commands/install.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `omp install <target>` — top-level convenience over `omp plugin install` /
+ * `omp plugin link`.
+ *
+ * The docs (omp.sh/docs/extension-authoring) advertise
+ *
+ *   omp install ./my-extension
+ *
+ * as a third loading mechanism that "symlinks the directory into the plugin
+ * set and watches it for changes". Before this command existed, `install` was
+ * not a registered subcommand, so the CLI runner forwarded the argv to the
+ * default `launch` command and the model received `install ./my-extension`
+ * as an initial prompt — see #1496.
+ *
+ * Local-path targets (`./foo`, `/abs/foo`, `~/foo`, or an existing directory)
+ * route to `plugin link` so they are symlinked into the plugin set, matching
+ * the documented behavior. Everything else (`pkg`, `pkg@1.2.3`,
+ * `name@marketplace`) routes to `plugin install`.
+ */
+import { Command } from "@oh-my-pi/pi-utils/cli";
+/**
+ * Heuristic used to decide whether `omp install <target>` should `link` a
+ * local directory or `install` a remote spec. Exported for tests.
+ */
+export declare function looksLikeLocalPath(target: string): boolean;
+export default class Install extends Command {
+    static description: string;
+    static args: {
+        targets: import("@oh-my-pi/pi-utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            multiple: true;
+        };
+    };
+    static flags: {
+        json: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        force: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "dry-run": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        scope: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            options: string[];
+        };
+    };
+    run(): Promise<void>;
+}

package/dist/types/discovery/index.d.ts

@@ -30,6 +30,7 @@ import "./gemini";
 import "./opencode";
 import "./github";
 import "./mcp-json";
+import "./omp-plugins";
 import "./ssh";
 import "./vscode";
 import "./windsurf";

package/dist/types/discovery/omp-extension-roots.d.ts

@@ -0,0 +1,43 @@
+import type { LoadContext } from "../capability/types";
+/** A resolved extension package directory wired into the discovery surfaces. */
+export interface OmpExtensionRoot {
+    /** Absolute path to the package directory. */
+    path: string;
+    /** Stable display name (basename of the package directory). */
+    name: string;
+    /** Scope from which the path was sourced. */
+    level: "user" | "project";
+}
+/**
+ * Register CLI-provided extension package paths (e.g. from `--extension`/`-e`)
+ * so the sub-discovery providers can find their sibling `skills/`, `hooks/`,
+ * etc. Paths that do not resolve to a directory are silently dropped — file
+ * entrypoints have no package sub-tree to scan.
+ *
+ * Call once during startup before any capability load. Repeated calls extend
+ * the registered set; {@link clearOmpExtensionCliRoots} resets for tests.
+ */
+export declare function injectOmpExtensionCliRoots(paths: readonly string[], home: string, cwd: string): void;
+/** Drop every CLI-injected root. Tests use this between cases. */
+export declare function clearOmpExtensionCliRoots(): void;
+/** Inspect currently-injected CLI roots (read-only). Exposed for diagnostics + tests. */
+export declare function getInjectedOmpExtensionCliRoots(): readonly OmpExtensionRoot[];
+/**
+ * Resolve every configured extension package directory for the given context.
+ *
+ * Sources, in order of precedence (later entries with the same absolute path
+ * are dropped):
+ *
+ * 1. CLI roots injected via {@link injectOmpExtensionCliRoots}
+ * 2. Project `<cwd>/.omp/settings.json#extensions`
+ * 3. User `~/.omp/agent/settings.json#extensions`
+ * 4. Enabled plugins installed under `<plugins>/node_modules/` (e.g. via
+ *    `omp install <pkg>` / `omp plugin install` / `omp plugin link`)
+ *
+ * Only entries that resolve to a directory on disk are returned; file
+ * entrypoints contribute zero sub-discovery surface and are filtered out.
+ * Installed-plugin enumeration failures (missing lockfile, unreadable
+ * `package.json`, etc.) are logged at `debug` and degrade gracefully — the
+ * other sources still surface.
+ */
+export declare function listOmpExtensionRoots(ctx: LoadContext): Promise<OmpExtensionRoot[]>;

package/dist/types/discovery/omp-plugins.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/extensibility/legacy-pi-coding-agent-shim.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compatibility shim for legacy extensions importing the package root of
+ * `@oh-my-pi/pi-coding-agent` (or one of its aliased scopes like
+ * `@earendil-works/pi-coding-agent` or `@mariozechner/pi-coding-agent`).
+ *
+ * The coding-agent package's own barrel (`./src/index.ts`) cannot be listed
+ * as a `bun --compile` extra entrypoint alongside the CLI entry without
+ * silently breaking the main binary's startup (see issue #1474 follow-up).
+ * Routing legacy plugin imports through this sibling shim sidesteps that
+ * conflict: bun bundles a distinct entry whose path differs from the CLI
+ * entry, while still re-exporting the canonical surface so plugins observe
+ * the same module identity as a direct `@oh-my-pi/pi-coding-agent` import.
+ */
+export * from "../index";

package/dist/types/extensibility/plugins/legacy-pi-compat.d.ts

@@ -1,2 +1,4 @@
 export declare function loadLegacyPiModule(resolvedPath: string): Promise<unknown>;
 export declare function installLegacyPiSpecifierShim(): void;
+/** Test seam: clears the memoized canonical specifier resolutions. */
+export declare function __resetLegacyPiResolutionCache(): void;

package/dist/types/extensibility/plugins/loader.d.ts

@@ -1,9 +1,19 @@
 import type { InstalledPlugin } from "./types";
 /**
  * Get list of enabled plugins with their resolved configurations.
- * Respects both global runtime config and project overrides.
+ *
+ * Respects both global runtime config and project overrides. Iterates the
+ * union of `<plugins>/package.json#dependencies` (`bun install`-installed
+ * packages) and `<plugins>/omp-plugins.lock.json#plugins` (so locally
+ * `plugin link`-symlinked extensions, which never get a dependency entry,
+ * are still discovered). The optional `home` parameter pins the plugins
+ * root for callers that need to enumerate plugins relative to a non-default
+ * home (tests with a tempdir, discovery loaders threaded with
+ * `LoadContext.home`).
  */
-export declare function getEnabledPlugins(cwd: string): Promise<InstalledPlugin[]>;
+export declare function getEnabledPlugins(cwd: string, opts?: {
+    home?: string;
+}): Promise<InstalledPlugin[]>;
 export declare function resolvePluginToolPaths(plugin: InstalledPlugin): string[];
 export declare function resolvePluginHookPaths(plugin: InstalledPlugin): string[];
 export declare function resolvePluginCommandPaths(plugin: InstalledPlugin): string[];

package/dist/types/index.d.ts

@@ -23,8 +23,11 @@ export * from "./sdk";
 export * from "./session/agent-session";
 export * from "./session/auth-storage";
 export * from "./session/messages";
+export * from "./session/redis-session-storage";
 export * from "./session/session-dump-format";
 export * from "./session/session-manager";
+export * from "./session/session-storage";
+export * from "./session/sql-session-storage";
 export * from "./task/executor";
 export type * from "./task/types";
 export * from "./tools";

package/dist/types/modes/components/custom-editor.d.ts

@@ -1,11 +1,14 @@
 import { Editor, type KeyId } from "@oh-my-pi/pi-tui";
 import type { AppKeybinding } from "../../config/keybindings";
+import { highlightUltrathink } from "../ultrathink";
 type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.clipboard.pasteImage" | "app.clipboard.copyPrompt">;
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
 export declare class CustomEditor extends Editor {
     #private;
+    /** Rainbow-highlight the "ultrathink" keyword as the user types it. */
+    decorateText: typeof highlightUltrathink;
     onEscape?: () => void;
     shouldBypassAutocompleteOnEscape?: () => boolean;
     onClear?: () => void;

package/dist/types/modes/ultrathink.d.ts

@@ -0,0 +1,10 @@
+/** Hidden system notice appended after a user message that mentions "ultrathink". */
+export declare const ULTRATHINK_NOTICE: string;
+/** Whether `text` contains the standalone keyword "ultrathink" (any case). */
+export declare function containsUltrathink(text: string): boolean;
+/**
+ * Rainbow-highlight every standalone "ultrathink" in `text` for editor display.
+ * Adds only zero-width SGR escapes — the visible width is unchanged — and returns
+ * the input untouched when the keyword is absent.
+ */
+export declare function highlightUltrathink(text: string): string;

package/dist/types/session/redis-session-storage.d.ts

@@ -0,0 +1,124 @@
+import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from "./session-storage";
+/**
+ * Minimal subset of the `bun:redis` `RedisClient` surface used by
+ * {@link RedisSessionStorage}. Keeping the contract narrow (and accepting any
+ * client that conforms) lets callers swap in test doubles or shared clients
+ * without dragging the entire Bun typings into this module.
+ */
+export interface RedisSessionStorageClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    append(key: string, value: string): Promise<number>;
+    del(...keys: string[]): Promise<number>;
+    rename(src: string, dst: string): Promise<unknown>;
+    scan(cursor: string, ...args: string[]): Promise<[string, string[]]>;
+    hset(key: string, field: string, value: string): Promise<unknown>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<unknown>;
+}
+export interface RedisSessionStorageOptions {
+    /** A connected `bun:redis` RedisClient (or any compatible adapter). */
+    client: RedisSessionStorageClient;
+    /**
+     * Key prefix applied to every Redis key this storage owns. Default `omp:sessions:`.
+     * Trailing colon is preserved verbatim — set to a project-scoped prefix to share
+     * one Redis instance between multiple agents.
+     */
+    prefix?: string;
+    /**
+     * Maximum number of keys returned per SCAN batch when warming the mirror.
+     * Default 500.
+     */
+    scanCount?: number;
+}
+/**
+ * Redis-backed implementation of {@link SessionStorage}. Each session JSONL
+ * file maps to a Redis STRING key, with per-key metadata (mtime) tracked in a
+ * single sibling HASH. An in-memory mirror is loaded on construction so the
+ * interface's synchronous methods (`existsSync`, `statSync`, `listFilesSync`,
+ * `readTextSync`, `writeTextSync`) keep their contracts — Bun's Redis client
+ * is async only, and the persist hot path (`writer.writeLineSync`) cannot
+ * wait on a network round-trip.
+ *
+ * Trade-offs vs `FileSessionStorage`:
+ * - Mirror state is process-local. Two processes writing the same session key
+ *   will diverge until one of them reloads via {@link refresh}. This matches
+ *   `FileSessionStorage`'s existing single-writer assumption.
+ * - `writeLineSync` updates the mirror synchronously and queues an async
+ *   `APPEND`. The promise is awaited by `flush()` / `close()` / {@link drain}.
+ *   A SIGKILL landing between the sync mirror update and the network round
+ *   trip loses the last line; the file-backed implementation survives that
+ *   window because bytes are handed to the kernel page cache before
+ *   returning.
+ * - Blobs (image data) and tool artifact files still live on disk via
+ *   `BlobStore` / `ArtifactManager`. Those are out of scope for this storage.
+ */
+export declare class RedisSessionStorage implements SessionStorage {
+    #private;
+    private constructor();
+    /**
+     * Warm the in-memory mirror with every existing session key under the
+     * configured prefix and return the ready-to-use storage. Must be awaited
+     * before passing the storage into `SessionManager.create()` so synchronous
+     * lookups (session resume, recent sessions, EPERM-backup recovery) see
+     * the existing keyspace.
+     */
+    static create(options: RedisSessionStorageOptions): Promise<RedisSessionStorage>;
+    /**
+     * Re-scan Redis and replace the mirror's contents. Call this from a
+     * different process that took over a session keyspace, or after an
+     * out-of-band write made by another agent.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Resolve once every pending background write (issued via `writeTextSync`
+     * or `writer.writeLineSync`) has been acknowledged by Redis. Throws if any
+     * background write failed since the last drain.
+     *
+     * Call this on graceful shutdown to avoid losing the last unflushed line.
+     * The session-manager's own `flush()` / `close()` already drain through
+     * the writer chain — this method exists for callers (test harnesses,
+     * subprocess-style consumers) that bypass the writer.
+     */
+    drain(): Promise<void>;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    readTextSync(path: string): string;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(src: string, dst: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+    _writerClosed(writer: RedisSessionStorageWriter): void;
+    /** Mirror-only mutation, no Redis call. Used by writers to update local state synchronously. */
+    _mirrorAppend(path: string, line: string): void;
+    /** Mirror-only mutation, no Redis call. Used by writers opened with `flags: "w"` to truncate. */
+    _mirrorTruncate(path: string): void;
+    _remoteTruncate(path: string): Promise<void>;
+    _remoteAppend(path: string, line: string): Promise<void>;
+    /** Record a writer's pending promise on the storage-level tail so `drain()` waits for it. */
+    _attachPending(promise: Promise<void>): void;
+}
+declare class RedisSessionStorageWriter implements SessionStorageWriter {
+    #private;
+    constructor(storage: RedisSessionStorage, path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    });
+    writeLineSync(line: string): void;
+    writeLine(line: string): Promise<void>;
+    flush(): Promise<void>;
+    fsync(): Promise<void>;
+    close(): Promise<void>;
+    getError(): Error | undefined;
+}
+export {};

package/dist/types/session/sql-session-storage.d.ts

@@ -0,0 +1,141 @@
+import type { SessionStorage, SessionStorageStat, SessionStorageWriter } from "./session-storage";
+/**
+ * Supported `bun:sql` adapter dialects. `Bun.SQL` reports this string on
+ * `client.options.adapter`; we detect it once at construction and pick the
+ * correct DDL / upsert / concat syntax for the underlying engine.
+ */
+export type SqlSessionStorageAdapter = "postgres" | "mysql" | "sqlite";
+/**
+ * Minimal subset of the `Bun.SQL` instance surface used by
+ * {@link SqlSessionStorage}. The real client exposes a callable
+ * tagged-template too; we only ever call `unsafe()` so the contract here is
+ * narrow — making it trivial to swap in a test double or wrap a pooled
+ * client.
+ */
+export interface SqlSessionStorageClient {
+    unsafe(query: string, values?: unknown[]): Promise<unknown[]>;
+    /**
+     * `Bun.SQL` exposes the parsed connection options here. We only consult
+     * `adapter` to pick the dialect; the field is typed as
+     * `string | undefined` so the real `Bun.SQL` instance type slots in
+     * without casting (it reports `string | undefined` across adapters).
+     */
+    options: {
+        adapter?: string;
+        [key: string]: unknown;
+    };
+    end?(): Promise<void>;
+}
+export interface SqlSessionStorageOptions {
+    /** Connected `Bun.SQL` instance (PostgreSQL, MySQL, or SQLite). */
+    client: SqlSessionStorageClient;
+    /**
+     * Override the auto-detected adapter. Useful when the client is wrapped
+     * (e.g. by a pool) and `client.options.adapter` is unreliable.
+     */
+    adapter?: SqlSessionStorageAdapter;
+    /**
+     * Table name to use. Default: `omp_session_files`. Must match
+     * `[A-Za-z_][A-Za-z0-9_]{0,62}` — inlined into prepared statements at
+     * startup, so we accept identifier-safe inputs only (no quoted/dotted
+     * names).
+     */
+    table?: string;
+    /**
+     * If true, run `CREATE TABLE IF NOT EXISTS` during `create()`.
+     * Default: true. Disable when the table is owned by an external
+     * migration.
+     */
+    createTable?: boolean;
+}
+/**
+ * SQL-backed implementation of {@link SessionStorage} using `bun:sql`. Each
+ * session JSONL file maps to a row keyed by `path`; one table stores
+ * everything.
+ *
+ * Works against PostgreSQL, MySQL/MariaDB, and SQLite by selecting the
+ * dialect-correct DDL, upsert, and string-concat syntax at construction.
+ *
+ * Trade-offs vs `FileSessionStorage`:
+ * - An in-memory mirror is loaded on construction so the interface's
+ *   synchronous methods (`existsSync`, `statSync`, `listFilesSync`, …) keep
+ *   their contracts; `bun:sql` is async only. Mirror state is process-local,
+ *   matching `FileSessionStorage`'s existing single-writer assumption — peer
+ *   processes need {@link refresh} to pick up out-of-band writes.
+ * - `writeLineSync` updates the mirror synchronously and queues an async
+ *   upsert that appends the line to the existing row (or inserts it as the
+ *   first chunk). The promise is awaited by `flush()` / `close()` /
+ *   {@link drain}. A SIGKILL between the sync mirror update and the network
+ *   round-trip loses the last line.
+ * - Blobs (image data) and tool artifact files still live on disk via
+ *   `BlobStore` / `ArtifactManager`. Those are out of scope for this storage.
+ */
+export declare class SqlSessionStorage implements SessionStorage {
+    #private;
+    private constructor();
+    /**
+     * Apply the dialect-correct DDL (unless `createTable: false` is set) and
+     * warm the in-memory mirror with every existing row. Must be awaited
+     * before passing the storage into `SessionManager.create()`.
+     */
+    static create(options: SqlSessionStorageOptions): Promise<SqlSessionStorage>;
+    get adapter(): SqlSessionStorageAdapter;
+    get table(): string;
+    /**
+     * Re-load the mirror from the database. Call this from a different
+     * process that took over the table, or after an out-of-band write made
+     * by another agent.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Resolve once every pending background write (issued via `writeTextSync`
+     * or `writer.writeLineSync`) has been acknowledged by the database.
+     * Throws if any background write failed since the last drain. Call on
+     * graceful shutdown to avoid losing the last unflushed line.
+     */
+    drain(): Promise<void>;
+    ensureDirSync(_dir: string): void;
+    existsSync(path: string): boolean;
+    writeTextSync(path: string, content: string): void;
+    readTextSync(path: string): string;
+    statSync(path: string): SessionStorageStat;
+    listFilesSync(dir: string, pattern: string): string[];
+    exists(path: string): Promise<boolean>;
+    readText(path: string): Promise<string>;
+    readTextPrefix(path: string, maxBytes: number): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    rename(src: string, dst: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    deleteSessionWithArtifacts(sessionPath: string): Promise<void>;
+    openWriter(path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    }): SessionStorageWriter;
+    _writerClosed(writer: SqlSessionStorageWriter): void;
+    _mirrorAppend(path: string, line: string): {
+        content: string;
+        mtimeMs: number;
+    };
+    _mirrorTruncate(path: string): void;
+    _remoteTruncate(path: string): Promise<void>;
+    /**
+     * Append a chunk to the row at `path`, inserting if the row doesn't
+     * exist yet. Single round-trip via the dialect-specific `upsertAppend`.
+     */
+    _remoteAppend(path: string, line: string, mtimeMs: number): Promise<void>;
+    _attachPending(promise: Promise<void>): void;
+}
+declare class SqlSessionStorageWriter implements SessionStorageWriter {
+    #private;
+    constructor(storage: SqlSessionStorage, path: string, options?: {
+        flags?: "a" | "w";
+        onError?: (err: Error) => void;
+    });
+    writeLineSync(line: string): void;
+    writeLine(line: string): Promise<void>;
+    flush(): Promise<void>;
+    fsync(): Promise<void>;
+    close(): Promise<void>;
+    getError(): Error | undefined;
+}
+export {};

package/dist/types/tools/todo-write.d.ts

@@ -49,6 +49,36 @@ declare const todoWriteSchema: z.ZodObject<{
 type TodoWriteParams = z.infer<typeof todoWriteSchema>;
 export declare const USER_TODO_EDIT_CUSTOM_TYPE = "user_todo_edit";
 export declare function getLatestTodoPhasesFromEntries(entries: SessionEntry[]): TodoPhase[];
+/**
+ * Pick the actionable window of tasks to display in the sticky todo panel.
+ *
+ * Returns up to `maxVisible` open (pending / in_progress) tasks in their
+ * original phase order, plus the count of remaining open tasks not shown so
+ * the caller can render a `+N more` hint. When every task in `tasks` is
+ * closed (completed or abandoned), returns the trailing `maxVisible` tasks
+ * with `hiddenOpenCount = 0`, so the panel keeps useful context until the
+ * active-phase pointer advances on the next `todo_write`.
+ *
+ * Task identity and order are preserved — this is a slice, never a sort.
+ */
+export declare function selectStickyTodoWindow(tasks: TodoItem[], maxVisible?: number): {
+    visible: TodoItem[];
+    hiddenOpenCount: number;
+};
+/**
+ * Report whether `content` likely names the same work as any entry in
+ * `descriptions`. Used by the sticky todo panel to light up a pending todo
+ * when an in-flight subagent is doing the work for it, without requiring
+ * the caller to flip the todo's status.
+ *
+ * Matching is normalize-then-equal first (lowercased; punctuation and
+ * whitespace runs both collapsed to a single space; trimmed), with a
+ * substring fallback in either direction so minor wording drift
+ * ("Sonnet #2: bug scan" vs "Sonnet #2") still links up. The substring
+ * fallback requires at least {@link TODO_DESCRIPTION_MIN_OVERLAP} chars on
+ * the contained side.
+ */
+export declare function todoMatchesAnyDescription(content: string, descriptions: readonly string[]): boolean;
 /** Apply an array of `todo_write`-style ops to existing phases. Used by /todo slash command. */
 export declare function applyOpsToPhases(currentPhases: TodoPhase[], ops: TodoWriteParams["ops"]): {
     phases: TodoPhase[];

package/examples/sdk/12-redis-sessions.ts

@@ -0,0 +1,54 @@
+/**
+ * Redis-Backed Sessions
+ *
+ * Store session JSONL in Redis (or Valkey) instead of the local filesystem.
+ * Useful when the agent runs in an ephemeral container, behind a load
+ * balancer, or anywhere a shared session store beats per-host disk state.
+ *
+ * The storage substrate is the only thing that changes — every other SDK
+ * surface (extensions, hooks, custom tools, slash commands, branching,
+ * `SessionManager.list`, …) continues to work unmodified.
+ *
+ * Tool artifacts and image blobs are out of scope: `ArtifactManager` /
+ * `BlobStore` keep writing to `~/.omp/agent/...`. Reach for an object store
+ * (S3, R2, GCS) if you need those off-host too.
+ */
+
+import { createAgentSession, RedisSessionStorage, SessionManager } from "@oh-my-pi/pi-coding-agent";
+import { RedisClient } from "bun";
+
+// `bun:redis` picks up `REDIS_URL` / `VALKEY_URL` from the environment, or
+// you can pass an explicit `redis://`/`rediss://` URL.
+const redis = new RedisClient();
+await redis.ping();
+
+// `create()` warms an in-memory mirror with every existing key under the
+// prefix so SessionManager's synchronous lookups (resume, recent sessions,
+// list) work without per-call network round-trips.
+const storage = await RedisSessionStorage.create({
+	client: redis,
+	prefix: "omp:sessions:", // optional, this is the default
+});
+
+const sessionDir = "/sessions/my-project";
+
+// 1) Fresh persistent session, JSONL backed by Redis.
+const { session } = await createAgentSession({
+	sessionManager: SessionManager.create(process.cwd(), sessionDir, storage),
+});
+console.log("New Redis session:", session.sessionFile);
+
+// 2) Continue the most recent session for this `sessionDir`.
+const { session: continued } = await createAgentSession({
+	sessionManager: await SessionManager.continueRecent(process.cwd(), sessionDir, storage),
+});
+console.log("Resumed:", continued.sessionFile);
+
+// 3) List every Redis-backed session under this directory key prefix.
+const sessions = await SessionManager.list(process.cwd(), sessionDir, storage);
+console.log(`Found ${sessions.length} sessions under ${sessionDir}`);
+
+// On graceful shutdown, drain any background writes the writer queued and
+// close the Redis connection so containerized hosts can exit cleanly.
+await storage.drain();
+redis.close();