@fickydev/pigent 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+## 0.1.14 - 2026-05-18
+
 ### Added
 
 - Added `task_runs` table and `TaskRepository` for scheduled task persistence.
@@ -59,6 +61,10 @@
 - Planned Telegram inline-button model and thinking level pickers backed by configured model choices.
 - Added Telegram inline-button pickers for `/model` and `/thinking`, callback handling, and bot command menu registration.
 - Added `/task` to Telegram bot command list (shows subcommands in help text).
+- Added `/new` Telegram command to start a fresh active chat session.
+- Added `/status` Telegram command with session/model/workspace/task info and estimated context usage.
+- Added persistent Pi session files per Pigent session so chat memory survives across messages and daemon restarts.
+- Added Pi session metadata to `/status`, with real Pi context usage when available.
 - Changed `/model` picker to use Pi's currently available models automatically when explicit `modelChoices` are not configured.
 - Kept daemon process alive after startup so CLI runs do not exit after `pigent ready`.
 

package/README.md

@@ -354,6 +354,13 @@ Available Telegram commands:
 /help
 /start
 /agents
+/new
+/status
+/model
+/thinking
+/task list
+/task create <intervalMs> <prompt>
+/task remove <id>
 /agent <agentId> <message>
 ```
 
@@ -373,6 +380,7 @@ Planned commands:
 - Keep Telegram-specific logic inside `src/channels/telegram` or routing config.
 - Channel adapters must not call Pi directly.
 - Pi runner must not know channel secrets.
+- Pi sessions are persisted under `~/.pigent/pi-sessions` by default (`PIGENT_PI_SESSION_DIR` overrides this).
 - Use repositories for database access.
 - Keep SQLite/PostgreSQL portability in mind.
 - Never inject secrets or raw `.env` values into model prompts.

package/TODO.md

@@ -72,6 +72,7 @@
 - [x] Define `runtime_kv` table for offsets and daemon state
 - [x] Add `agent_sessions.model` for session model override
 - [x] Add `agent_sessions.thinking_level` for session thinking override
+- [x] Add active/inactive session lifecycle fields for `/new` sessions
 - [x] Implement repositories
   - [x] `AgentRepository`
   - [x] `SessionRepository`
@@ -138,7 +139,9 @@
 - [x] Apply session model override
 - [x] Apply thinking level selection
 - [x] Confirm SDK APIs needed for session creation
-- [ ] Confirm persistent session manager approach
+- [x] Confirm persistent session manager approach
+- [x] Persist Pi session file path per active Pigent session
+- [x] Reuse Pi session files across messages
 - [ ] Confirm per-agent system prompt injection
 - [ ] Confirm per-agent skills loading
 - [ ] Confirm per-agent extensions loading
@@ -183,6 +186,8 @@
 - [ ] `/default-agent <id>` set chat default
 - [ ] `/instructions <text>` set chat instructions
 - [ ] `/sessions` list active sessions for chat
+- [x] `/new` start a fresh active chat session
+- [x] `/status` show current session, model, workspace, tasks, and estimated context usage
 - [ ] `/reset-session <agentId>` clear chat session
 - [ ] `/heartbeat status` show heartbeat state
 - [x] `/model` show current model for default chat agent session

package/drizzle/migrations/0004_active_agent_sessions.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `agent_sessions` ADD `active` integer DEFAULT true NOT NULL;
+ALTER TABLE `agent_sessions` ADD `ended_at` integer;
+DROP INDEX `agent_sessions_key_unique`;
+CREATE INDEX `agent_sessions_active_key_idx` ON `agent_sessions` (`agent_id`, `channel`, `chat_id`, `thread_id`, `active`);

package/drizzle/migrations/0005_pi_session_path.sql

@@ -0,0 +1 @@
+ALTER TABLE `agent_sessions` ADD `pi_session_path` text;

package/drizzle/migrations/meta/_journal.json

@@ -29,6 +29,20 @@
       "when": 1779097464805,
       "tag": "0003_secret_stone_men",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1779099600000,
+      "tag": "0004_active_agent_sessions",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1779099900000,
+      "tag": "0005_pi_session_path",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fickydev/pigent",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "private": false,
   "type": "module",
   "description": "Autonomous multi-agent daemon using Pi as core execution engine.",

package/src/agents/AgentRunner.ts

@@ -104,14 +104,21 @@ export class AgentRunner {
     if (!agent) return { text: `Unknown agent: ${input.agentId}` };
 
     try {
-      const text = await this.piRunner.run({
+      const result = await this.piRunner.run({
         agent,
         profile: this.registry.getProfile(agent.profile),
         session,
         prompt: this.composePrompt(input, chatInstructions),
       });
 
-      return { text };
+      if (session.piSessionId !== result.piSessionId || session.piSessionPath !== result.piSessionPath) {
+        await this.repositories.sessions.updatePiSession(session.id, {
+          piSessionId: result.piSessionId,
+          piSessionPath: result.piSessionPath,
+        });
+      }
+
+      return { text: result.text };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
 

package/src/agents/BotCommandHandler.ts

@@ -1,8 +1,11 @@
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { InboundMessage, InlineKeyboardButton } from "../channels/types";
-import type { ModelChoiceConfig } from "../config/schemas";
+import type { LoadedAgentConfig, ModelChoiceConfig, ProfileConfig } from "../config/schemas";
+import type { AgentSessionRow } from "../db/schema";
 import type { Repositories } from "../db/repositories";
+import { PiAgentRunner, type PiContextUsage } from "../pi/PiAgentRunner";
 import { getAvailableModelChoices } from "../pi/PiAvailableModels";
-import { isValidModelRef } from "../pi/PiModelResolver";
+import { isValidModelRef, resolveModelSelection } from "../pi/PiModelResolver";
 import type { AgentRegistry } from "./AgentRegistry";
 import type { Scheduler } from "../daemon/Scheduler";
 
@@ -20,6 +23,8 @@ const THINKING_LEVELS = ["off", "low", "medium", "high"] as const;
 type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
 export class BotCommandHandler {
+  private readonly piRunner = new PiAgentRunner();
+
   constructor(
     private readonly registry: AgentRegistry,
     private readonly repositories: Repositories,
@@ -38,6 +43,10 @@ export class BotCommandHandler {
         return { handled: true, text: this.helpText() };
       case "/agents":
         return { handled: true, text: await this.agentsText(message) };
+      case "/new":
+        return { handled: true, text: await this.newSessionText(message) };
+      case "/status":
+        return { handled: true, text: await this.statusText(message) };
       case "/model":
         return await this.modelResult(message);
       case "/thinking":
@@ -60,6 +69,8 @@ export class BotCommandHandler {
       "Pigent commands:",
       "/help - show this help",
       "/agents - list agents for this chat",
+      "/new - start a fresh session for this chat",
+      "/status - show current session status",
       "/model - show model picker for this chat session",
       "/model <provider/modelId> - set model for this chat session",
       "/model default - clear model override for this chat session",
@@ -96,6 +107,90 @@ export class BotCommandHandler {
     ].join("\n");
   }
 
+  private async newSessionText(message: InboundMessage): Promise<string> {
+    const sessionResult = await this.getDefaultSession(message);
+    if (!sessionResult.ok) return sessionResult.message;
+
+    const session = await this.repositories.sessions.startNew({
+      agentId: sessionResult.agentId,
+      channel: message.channel,
+      chatId: message.chatId,
+      threadId: message.threadId,
+      userId: message.senderId,
+    });
+
+    return [
+      "New session created.",
+      "",
+      "Agent: " + session.agentId,
+      "Session: " + session.id,
+      "Model: " + (session.model ?? "default"),
+      "Thinking: " + (session.thinkingLevel ?? "default"),
+      "Workspace: " + formatPath(sessionResult.agent.workspace),
+    ].join("\n");
+  }
+
+  private async statusText(message: InboundMessage): Promise<string> {
+    const sessionResult = await this.getDefaultSession(message);
+    if (!sessionResult.ok) return sessionResult.message;
+
+    const agent = sessionResult.agent;
+    const profile = this.registry.getProfile(agent.profile);
+    const messageStats = await this.repositories.messages.statsBySession(sessionResult.session.id);
+    const modelInfo = this.resolveStatusModel(sessionResult.session, agent, profile);
+    const piStatus = await this.loadPiStatus(sessionResult.session, agent, profile);
+    const contextText = piStatus?.contextUsage
+      ? formatPiContext(piStatus.contextUsage)
+      : formatEstimatedContext(messageStats.estimatedTokens, modelInfo.contextWindow);
+    const contextSource = piStatus?.contextUsage ? "Pi session" : "Pigent DB estimate";
+    const taskCount = this.scheduler
+      ? this.scheduler.getTasks().filter((task) => task.chatId === message.chatId || !task.chatId).length
+      : null;
+
+    return [
+      "Pigent status",
+      "",
+      "Agent: " + agent.id,
+      "Profile: " + agent.profile,
+      "Session: " + sessionResult.session.id,
+      "Session age: " + formatDuration(Date.now() - sessionResult.session.createdAt),
+      "Messages: " + messageStats.count,
+      "Last message: " + (messageStats.lastMessageAt ? formatDuration(Date.now() - messageStats.lastMessageAt) + " ago" : "none"),
+      "Model: " + modelInfo.model,
+      "Thinking: " + (sessionResult.session.thinkingLevel ?? agent.thinkingLevel ?? profile?.thinkingLevel ?? "default"),
+      "Context: " + contextText,
+      "Context source: " + contextSource,
+      "Pi session: " + (piStatus?.piSessionId ?? sessionResult.session.piSessionId ?? "not created"),
+      "Workspace: " + formatPath(agent.workspace),
+      "Chat: " + message.chatId,
+      "Thread: " + (message.threadId ?? "none"),
+      "Tasks: " + (taskCount === null ? "scheduler unavailable" : String(taskCount)),
+      "Fake runner: " + (process.env.PIGENT_FAKE_AGENT === "1" ? "on" : "off"),
+    ].join("\n");
+  }
+
+  private async loadPiStatus(session: AgentSessionRow, agent: LoadedAgentConfig, profile: ProfileConfig | null) {
+    try {
+      return await this.piRunner.status({ agent, profile, session });
+    } catch {
+      return null;
+    }
+  }
+
+  private resolveStatusModel(session: { model: string | null }, agent: { model?: string | null }, profile: { model?: string | null } | null) {
+    const configuredModel = session.model ?? agent.model ?? profile?.model ?? null;
+    if (!configuredModel) return { model: "default", contextWindow: null as number | null };
+
+    const authStorage = AuthStorage.create();
+    const modelRegistry = ModelRegistry.create(authStorage);
+    const resolved = resolveModelSelection(modelRegistry, [session, agent, profile ?? {}]);
+
+    return {
+      model: configuredModel,
+      contextWindow: resolved.model?.contextWindow ?? null,
+    };
+  }
+
   private async modelResult(message: InboundMessage): Promise<BotCommandResult> {
     const sessionResult = await this.getDefaultSession(message);
     if (!sessionResult.ok) return { handled: true, text: sessionResult.message };
@@ -343,7 +438,8 @@ export class BotCommandHandler {
       return { ok: false as const, message: "No default agent configured for this chat." };
     }
 
-    if (!this.registry.hasAgent(agentId)) {
+    const agent = this.registry.getAgent(agentId);
+    if (!agent) {
       return { ok: false as const, message: "Unknown agent: " + agentId };
     }
 
@@ -359,7 +455,7 @@ export class BotCommandHandler {
       userId: message.senderId,
     });
 
-    return { ok: true as const, agentId, session };
+    return { ok: true as const, agentId, agent, session };
   }
 }
 
@@ -376,3 +472,50 @@ function chunk<T>(items: T[], size: number): T[][] {
 
   return rows;
 }
+
+function formatPiContext(contextUsage: PiContextUsage): string {
+  if (contextUsage.percent === null || contextUsage.tokens === null) {
+    return "? / " + formatTokens(contextUsage.contextWindow);
+  }
+
+  return contextUsage.percent.toFixed(1) + "% / " + formatTokens(contextUsage.contextWindow);
+}
+
+function formatEstimatedContext(tokens: number, contextWindow: number | null): string {
+  if (!contextWindow || contextWindow <= 0) {
+    return "~" + formatTokens(tokens) + " tokens estimated / unknown limit";
+  }
+
+  const percent = (tokens / contextWindow) * 100;
+  return "~" + percent.toFixed(1) + "% / " + formatTokens(contextWindow) + " tokens estimated";
+}
+
+function formatTokens(count: number): string {
+  if (count < 1000) return String(count);
+  if (count < 10000) return (count / 1000).toFixed(1) + "k";
+  if (count < 1000000) return Math.round(count / 1000) + "k";
+  if (count < 10000000) return (count / 1000000).toFixed(1) + "M";
+  return Math.round(count / 1000000) + "M";
+}
+
+function formatDuration(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  if (seconds < 60) return seconds + "s";
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return minutes + "m";
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return hours + "h " + (minutes % 60) + "m";
+
+  return Math.floor(hours / 24) + "d " + (hours % 24) + "h";
+}
+
+function formatPath(path: string): string {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (home && path.startsWith(home)) {
+    return "~" + path.slice(home.length);
+  }
+
+  return path;
+}

package/src/daemon/AgentDaemon.ts

@@ -178,6 +178,8 @@ function telegramCommands() {
   return [
     { command: "help", description: "Show Pigent commands" },
     { command: "agents", description: "List agents available in this chat" },
+    { command: "new", description: "Start a fresh chat session" },
+    { command: "status", description: "Show current session status" },
     { command: "model", description: "Choose model for this chat session" },
     { command: "thinking", description: "Choose thinking level for this chat session" },
     { command: "agent", description: "Send message to a specific agent" },

package/src/db/repositories/MessageRepository.ts

@@ -1,3 +1,4 @@
+import { eq } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import type { DbClient } from "../client";
 import { messages, type MessageRow } from "../schema";
@@ -42,4 +43,27 @@ export class MessageRepository {
     if (!row) throw new Error(`failed to create message ${id}`);
     return row;
   }
+
+  async statsBySession(sessionId: string): Promise<{ count: number; estimatedTokens: number; lastMessageAt: number | null }> {
+    const rows = await this.db
+      .select({ content: messages.content, createdAt: messages.createdAt })
+      .from(messages)
+      .where(eq(messages.sessionId, sessionId));
+
+    let chars = 0;
+    let lastMessageAt: number | null = null;
+
+    for (const row of rows) {
+      chars += row.content.length;
+      if (lastMessageAt === null || row.createdAt > lastMessageAt) {
+        lastMessageAt = row.createdAt;
+      }
+    }
+
+    return {
+      count: rows.length,
+      estimatedTokens: Math.ceil(chars / 4),
+      lastMessageAt,
+    };
+  }
 }

package/src/db/repositories/SessionRepository.ts

@@ -17,27 +17,25 @@ export class SessionRepository {
   constructor(private readonly db: DbClient) {}
 
   async getOrCreate(key: SessionKey): Promise<AgentSessionRow> {
-    const existing = await this.findByKey(key);
+    const existing = await this.findActiveByKey(key);
     if (existing) return existing;
 
-    const now = Date.now();
-    const id = nanoid();
+    return await this.create(key);
+  }
 
-    await this.db.insert(agentSessions).values({
-      id,
-      agentId: key.agentId,
-      channel: key.channel,
-      chatId: key.chatId,
-      threadId: key.threadId ?? null,
-      userId: key.userId ?? null,
-      createdAt: now,
-      updatedAt: now,
-    });
+  async startNew(key: SessionKey): Promise<AgentSessionRow> {
+    const now = Date.now();
 
-    const created = await this.findById(id);
-    if (!created) throw new Error(`failed to create session ${id}`);
+    await this.db
+      .update(agentSessions)
+      .set({
+        active: false,
+        endedAt: now,
+        updatedAt: now,
+      })
+      .where(this.keyPredicate(key, true));
 
-    return created;
+    return await this.create(key);
   }
 
   async updateModel(id: string, model: string | null): Promise<AgentSessionRow> {
@@ -64,6 +62,19 @@ export class SessionRepository {
     return this.requireById(id);
   }
 
+  async updatePiSession(id: string, input: { piSessionId: string; piSessionPath: string }): Promise<AgentSessionRow> {
+    await this.db
+      .update(agentSessions)
+      .set({
+        piSessionId: input.piSessionId,
+        piSessionPath: input.piSessionPath,
+        updatedAt: Date.now(),
+      })
+      .where(eq(agentSessions.id, id));
+
+    return this.requireById(id);
+  }
+
   async findById(id: string): Promise<AgentSessionRow | null> {
     const row = await this.db.query.agentSessions.findFirst({
       where: eq(agentSessions.id, id),
@@ -79,20 +90,52 @@ export class SessionRepository {
     return row;
   }
 
-  private async findByKey(key: SessionKey): Promise<AgentSessionRow | null> {
-    const threadPredicate = key.threadId
-      ? eq(agentSessions.threadId, key.threadId)
-      : isNull(agentSessions.threadId);
+  private async create(key: SessionKey): Promise<AgentSessionRow> {
+    const now = Date.now();
+    const id = nanoid();
+
+    await this.db.insert(agentSessions).values({
+      id,
+      agentId: key.agentId,
+      channel: key.channel,
+      chatId: key.chatId,
+      threadId: key.threadId ?? null,
+      userId: key.userId ?? null,
+      active: true,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    const created = await this.findById(id);
+    if (!created) throw new Error(`failed to create session ${id}`);
 
+    return created;
+  }
+
+  private async findActiveByKey(key: SessionKey): Promise<AgentSessionRow | null> {
     const row = await this.db.query.agentSessions.findFirst({
-      where: and(
-        eq(agentSessions.agentId, key.agentId),
-        eq(agentSessions.channel, key.channel),
-        eq(agentSessions.chatId, key.chatId),
-        threadPredicate,
-      ),
+      where: this.keyPredicate(key, true),
     });
 
     return row ?? null;
   }
+
+  private keyPredicate(key: SessionKey, active?: boolean) {
+    const threadPredicate = key.threadId
+      ? eq(agentSessions.threadId, key.threadId)
+      : isNull(agentSessions.threadId);
+
+    const predicates = [
+      eq(agentSessions.agentId, key.agentId),
+      eq(agentSessions.channel, key.channel),
+      eq(agentSessions.chatId, key.chatId),
+      threadPredicate,
+    ];
+
+    if (active !== undefined) {
+      predicates.push(eq(agentSessions.active, active));
+    }
+
+    return and(...predicates);
+  }
 }

package/src/db/schema.ts

@@ -1,4 +1,4 @@
-import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { index, integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 
 export const agents = sqliteTable("agents", {
   id: text("id").primaryKey(),
@@ -47,18 +47,22 @@ export const agentSessions = sqliteTable(
     threadId: text("thread_id"),
     userId: text("user_id"),
     piSessionId: text("pi_session_id"),
+    piSessionPath: text("pi_session_path"),
     instructionsHash: text("instructions_hash"),
     model: text("model"),
     thinkingLevel: text("thinking_level", { enum: ["off", "low", "medium", "high"] }),
+    active: integer("active", { mode: "boolean" }).notNull().default(true),
+    endedAt: integer("ended_at"),
     createdAt: integer("created_at").notNull(),
     updatedAt: integer("updated_at").notNull(),
   },
   (table) => ({
-    sessionKeyUnique: uniqueIndex("agent_sessions_key_unique").on(
+    sessionActiveKeyIndex: index("agent_sessions_active_key_idx").on(
       table.agentId,
       table.channel,
       table.chatId,
       table.threadId,
+      table.active,
     ),
   }),
 );

package/src/pi/PiAgentRunner.ts

@@ -4,7 +4,6 @@ import {
   DefaultResourceLoader,
   ModelRegistry,
   getAgentDir,
-  SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { mkdir } from "node:fs/promises";
@@ -12,6 +11,7 @@ import { resolve } from "node:path";
 import type { LoadedAgentConfig, ProfileConfig } from "../config/schemas";
 import type { AgentSessionRow } from "../db/schema";
 import { resolveModelSelection } from "./PiModelResolver";
+import { loadOrCreatePiSession } from "./PiSessionFactory";
 
 export type PiAgentRunInput = {
   agent: LoadedAgentConfig;
@@ -20,8 +20,58 @@ export type PiAgentRunInput = {
   prompt: string;
 };
 
+export type PiContextUsage = {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+};
+
+export type PiAgentRunResult = {
+  text: string;
+  piSessionId: string;
+  piSessionPath: string;
+  contextUsage?: PiContextUsage;
+};
+
+export type PiSessionStatus = {
+  piSessionId: string;
+  piSessionPath: string;
+  contextUsage?: PiContextUsage;
+};
+
 export class PiAgentRunner {
-  async run(input: PiAgentRunInput): Promise<string> {
+  async run(input: PiAgentRunInput): Promise<PiAgentRunResult> {
+    const prepared = await this.prepare(input);
+
+    let response = "";
+    prepared.session.subscribe((event) => {
+      if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+        response += event.assistantMessageEvent.delta;
+      }
+    });
+
+    await prepared.session.prompt(input.prompt);
+
+    return {
+      text: response.trim() || "(no response)",
+      piSessionId: prepared.piSession.sessionId,
+      piSessionPath: prepared.piSession.sessionPath,
+      contextUsage: prepared.session.getContextUsage(),
+    };
+  }
+
+  async status(input: Omit<PiAgentRunInput, "prompt">): Promise<PiSessionStatus | null> {
+    if (!input.session.piSessionPath) return null;
+
+    const prepared = await this.prepare({ ...input, prompt: "" });
+    return {
+      piSessionId: prepared.piSession.sessionId,
+      piSessionPath: prepared.piSession.sessionPath,
+      contextUsage: prepared.session.getContextUsage(),
+    };
+  }
+
+  private async prepare(input: PiAgentRunInput) {
     const workspace = resolve(input.agent.workspace);
     await mkdir(workspace, { recursive: true });
 
@@ -41,6 +91,7 @@ export class PiAgentRunner {
     const authStorage = AuthStorage.create();
     const modelRegistry = ModelRegistry.create(authStorage);
     const modelSelection = resolveModelSelection(modelRegistry, [input.session, input.agent, input.profile ?? {}]);
+    const piSession = await loadOrCreatePiSession(workspace, input.session);
     const { session } = await createAgentSession({
       cwd: workspace,
       authStorage,
@@ -48,22 +99,13 @@ export class PiAgentRunner {
       model: modelSelection.model,
       thinkingLevel: modelSelection.thinkingLevel,
       resourceLoader,
-      sessionManager: SessionManager.create(workspace),
+      sessionManager: piSession.manager,
       settingsManager,
       agentDir,
       tools: [],
     });
 
-    let response = "";
-    session.subscribe((event) => {
-      if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-        response += event.assistantMessageEvent.delta;
-      }
-    });
-
-    await session.prompt(input.prompt);
-
-    return response.trim() || "(no response)";
+    return { session, piSession };
   }
 }
 

package/src/pi/PiSessionFactory.ts

@@ -0,0 +1,49 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { AgentSessionRow } from "../db/schema";
+
+export type PiSessionHandle = {
+  manager: SessionManager;
+  sessionId: string;
+  sessionPath: string;
+  created: boolean;
+};
+
+export async function loadOrCreatePiSession(workspace: string, session: AgentSessionRow): Promise<PiSessionHandle> {
+  const sessionDir = piSessionDir();
+  await mkdir(sessionDir, { recursive: true });
+
+  if (session.piSessionPath && existsSync(session.piSessionPath)) {
+    const manager = SessionManager.open(session.piSessionPath, sessionDir, workspace);
+    return {
+      manager,
+      sessionId: manager.getSessionId(),
+      sessionPath: manager.getSessionFile() ?? session.piSessionPath,
+      created: false,
+    };
+  }
+
+  const manager = SessionManager.create(workspace, sessionDir);
+  manager.newSession({ id: session.piSessionId ?? session.id });
+
+  const sessionPath = manager.getSessionFile();
+  if (!sessionPath) {
+    throw new Error("failed to create persisted Pi session file");
+  }
+
+  await mkdir(dirname(sessionPath), { recursive: true });
+
+  return {
+    manager,
+    sessionId: manager.getSessionId(),
+    sessionPath,
+    created: true,
+  };
+}
+
+export function piSessionDir(): string {
+  return resolve(process.env.PIGENT_PI_SESSION_DIR ?? join(process.env.PIGENT_HOME ?? join(homedir(), ".pigent"), "pi-sessions"));
+}