pi-session-state

Session-scoped, optionally branch-scoped JSON state over one SQLite file, for Pi extensions

Packages

Package details

extension

Install pi-session-state from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-session-state
Package
pi-session-state
Version
0.1.1
Published
Oct 9, 2026
Downloads
459/mo · 459/wk
Author
eykettle
License
MIT
Types
extension
Size
55.9 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/extension.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

session-state extension

npm Conventional Commits License: MIT

English | 中文

[!note] AI-generated artifacts. May include low-quality code.

A Pi extension and a library for other extensions: it holds session-scoped persistent state in one SQLite file.

Features

  • Session scope and branch scope
  • A value can be any JSON; its structure is the integrator's to define
  • One writer per session at a time, while reads proceed in parallel
  • A crash-left lock ages out on its own, so a session is never sealed

For integrators

import { openSessionState } from "pi-session-state";

const state = openSessionState<Identity>({ pluginId: "role" });

The contract, the scopes, and the boundaries are in the API.

For users

The package registers two commands for inspection and reset:

Command What it does
/state:status who holds this session's lock row and whether that pid is alive (unknown when it cannot be told); how many state rows this session has, per extension
/state:force-refresh clear this session's lock row and drop this process's cache, then read from disk

The database defaults to {agent_dir}/sessions/states.sqlite and can be replaced from settings.json — see Storage.

Docs

Install

pi install npm:pi-session-state

Or clone it into Pi's user extension path (e.g. ~/.pi/agent/extensions):

git clone https://github.com/EyKettle/pi-session-state.git ~/.pi/agent/extensions/session-state
cd ~/.pi/agent/extensions/session-state
pnpm install

Pi loads the package through its pi.extensions entry. Reload Pi after installing.

Developed against Pi 1.1.0.

Develop

pnpm install
pnpm test
pnpm run typecheck