colelawrence

Durable Sessions and Reconstruction in Pi

This note explains how to think about durable state in Pi when the user navigates the session tree with /tree, starts a new session, resumes another session, or forks.

The short version:

• Pi sessions are an append-only tree of entries with a movable leaf pointer.
• /tree does not restart the extension runtime. It changes the active leaf and rebuilds the active conversation context.
• If your extension keeps in-memory state, you are responsible for reconstructing it from durable session entries.
• The central design decision is whether your state should be:

colelawrence

notes

Pi resources: skills vs prompts vs extensions (tools/commands)

Type	What it is	How it’s used	Auto-included from	settings.json keys	Notes / capabilities
Skill	SKILL.md (Agent Skills standard) or top-level .md in skills dir	Loaded on demand (/skill:name or auto-detected by model). Expands to instructions.	~/.pi/agent/skills/, .pi/skills/, packages (skills/), settings skills paths	"skills": ["/path", "./dir"], "packages": [...], "enableSkillCommands": true/false	Skill commands are optional (enableSkillCommands). Skills can include scripts/assets. Missing description prevents load.
Prompt template	Markdown snippet (prompt)	User invokes via /name in editor. Expands into full prompt.	~/.pi/agent/prompts/, .pi/prompts/, packages (prompts/), settings prompts paths	"prompts": ["/path", "./dir"], "packages": [...]	No special toggle besides discovery/CLI --no-prompt-templates. Supports

colelawrence

notes

Pi resources: skills vs prompts vs extensions (tools/commands)

Type	What it is	How it’s used	Auto-included from	settings.json keys	Notes / capabilities
Skill	SKILL.md (Agent Skills standard) or top-level .md in skills dir	Loaded on demand (/skill:name or auto-detected by model). Expands to instructions.	~/.pi/agent/skills/, .pi/skills/, packages (skills/), settings skills paths	"skills": ["/path", "./dir"], "packages": [...], "enableSkillCommands": true/false	Skill commands are optional (enableSkillCommands). Skills can include scripts/assets. Missing description prevents load.
Prompt template	Markdown snippet (prompt)	User invokes via /name in editor. Expands into full prompt.	~/.pi/agent/prompts/, .pi/prompts/, packages (prompts/), settings prompts paths	"prompts": ["/path", "./dir"], "packages": [...]	No special toggle besides discovery/CLI --no-prompt-templates. Supports

colelawrence

type PathString = string & { __brand: "path" }
function call<R>(fn: () => R) { return fn(); }

/** TODO: Return null if the user cancels/doesn't save the file (like in git) */
export async function editTextInSystemEditor(originalText: string): Promise<string | null> {
  // Create a unique temp directory using Bun's file APIs
  const tmpDir = `/tmp/context-edit-${Date.now()}-${Math.random().toString(36).slice(2)}`;
  await Bun.$`mkdir -p ${tmpDir}`;
  const tmpFile = `${tmpDir}/prompt-edit.txt` as PathString;

colelawrence

Entity Durability Patterns in Effect Cluster

Understanding how state survives failures - and how to test it.

The Two Durability Concerns

When an entity "dies" (runner crashes, shard reassigned), there are two separate things to worry about:

Concern	Question	Effect Cluster Solution

colelawrence

#!/usr/bin/env python3

import iterm2
import os
import re

async def main(connection):
    @iterm2.TitleProviderRPC
    async def custom_amp_title(
        auto_name=iterm2.Reference("autoName?"),

colelawrence

import { makeInMemoryAdapter } from "@livestore/adapter-web";
import { type Store, createStorePromise } from "@livestore/livestore";
import { LogLevel } from "effect";
import { JotaiBatchCoordinator } from "./jotai-batch-coordinator.ts";
import { schema } from "./schema.ts";

export async function createLiveStoreForTesting({
  batchUpdates,
  batchCoordinator,
}: {

colelawrence

#!/usr/bin/env bun
/// <reference types="bun" />
import { existsSync } from "node:fs";
import { writeFile } from "node:fs/promises";
import { basename, extname } from "node:path";

interface Options {
  /** e.g. `false` */
  interactive: boolean;
  /** e.g. `100` */

colelawrence

const secrets = new WeakMap<EnvSecret<unknown>, unknown>();

/**
 * A secure wrapper for environment variables that contain sensitive data.
 *
 * Values are stored privately using WeakMap to prevent accidental exposure
 * in logs, serialization, or debugging output.
 *
 * @template T The type of the secret value

colelawrence

[tools."http:jaeger"]
# single authoritative version for every OS/arch
version = "2.8.0"
[tools."http:jaeger".platforms]
macos-x64  = { url = "https://download.jaegertracing.io/v1.71.0/jaeger-2.8.0-darwin-amd64.tar.gz" }
macos-arm64 = { url = "https://download.jaegertracing.io/v1.71.0/jaeger-2.8.0-darwin-arm64.tar.gz" }
linux-x64  = { url = "https://download.jaegertracing.io/v1.71.0/jaeger-2.8.0-linux-amd64.tar.gz" }

[tasks.start-jaeger]