pi-feats 0.1.4 → 0.1.7

package/README.md

@@ -10,6 +10,7 @@
 
 - [Glossary](#glossary)
 - [Features](#features)
+- [Context Memory](#context-memory)
 - [Command cookbook](#command-cookbook)
 - [Included extensions](#included-extensions)
 - [Installation](#installation)
@@ -28,6 +29,7 @@
 | **Identity Key mapping** | A rule that maps an external identity to an Application profile and session strategy. A single `*` mapping can be an explicit fallback. |
 | **Handoff** | Private context retained when an Application rolls a conversation into a replacement session. |
 | **Guardrail** | An ordered policy instruction executed at an input, tool, or output lifecycle stage. |
+| **Context Memory** | Bounded persistent operational and personal context loaded when a new session starts. |
 | **Shared Skill** | A Skill stored in the main Pi agent directory and selectively exposed to profiles. |
 | **Profile Skill** | A Skill stored in one profile directory and unavailable to other profiles unless explicitly copied or imported. |
 | **Skill Source** | A Git-backed staging catalog. Synchronizing it discovers Skills but does not activate them. |
@@ -56,6 +58,21 @@ Pi Coding Agent intentionally keeps its core lightweight and extensible. Pi Feat
 - Limit profile tools, shared Skills, and profile Skills through profile policy.
 - Keep extensions and packages in the default runtime; named profiles load those shared resources read-only and never clone or install them.
 - Load a profile-specific `SOUL.md` into every agent turn.
+- Select the default provider and model for each profile from the Console. After changing it, administrators can roll over active Application sessions so subsequent conversations use the new model.
+
+### Profile SSH
+
+Profile SSH is an optional, isolated host-registration mechanism. It complements normal SSH rather than replacing a user's global `~/.ssh/config`, agent, or keys.
+
+- Register, list, and delete SSH hosts for the active profile with `pi ssh add|list|delete <alias>`, or target a named profile with `pi profile <profile> ssh ...`.
+- Store aliases, keys, and known-host entries under `<PI_CODING_AGENT_DIR>/.ssh/`, keeping profile credentials separate from the host user's SSH configuration.
+- Require a hostname and IP address, display the scanned server fingerprint for explicit confirmation, and keep strict host-key verification enabled.
+- Generate Ed25519 keys for modern servers and RSA-4096 keys with legacy compatibility settings for older OpenSSH servers. The setup validates key-based access before saving; when needed, it invokes `ssh-copy-id` interactively once with a profile-isolated home directory.
+- Connect to a registered host explicitly through its profile configuration:
+
+  ```bash
+  ssh -F "$PI_CODING_AGENT_DIR/.ssh/config" <alias>
+  ```
 
 ### Remote Hosts
 
@@ -109,8 +126,15 @@ Applications are the integration boundary between Pi and external systems. Use o
   ```
 
 - Normalize provider-specific payloads in an inbound handler, enrich or redact data through transforms, and shape integration responses in an outbound handler.
-- Route each external identity to a profile and session strategy through explicit Identity Key mappings. Mappings may use automatic sessions or fixed prefixes; one `*` wildcard can serve as a deliberate fallback.
+- Route each external identity to a profile and session strategy through explicit Identity Key mappings. Mappings may use automatic sessions or fixed prefixes, or intentionally ignore an identity (`None` in the Console) after inbound handling without calling Pi. Exact mappings take precedence, so an ignore mapping can exclude an identity even when a single `*` wildcard fallback exists.
 - Choose acknowledgement mode for asynchronous webhook-style work or result mode when an integration needs the completed response.
+- Use **Direct Mode** (enabled by default) for integrations that already provide an Identity Key and message. Direct requests bypass transform, inbound, and outbound handlers and route exclusively through the configured Identity Key mapping.
+- When a Direct Mode request omits `sessionId`, Pi reuses the active Application session for the resolved profile and session prefix; if none exists, it creates one. This is scoped to the Application route, profile, and identity-derived prefix—not the Application's globally most recent session.
+- Provide `sessionId` in a Direct Mode request to explicitly create or adopt that session for the resolved route. A session cannot be associated with another Application route.
+- Pass transient `contextMemory` in a Direct Mode request to supply personal context only when initializing that request's session. It is not persisted in profile or identity memory.
+- In `ack` response mode, Direct Mode requires `responseWebhookUrl`; Pi immediately acknowledges the request and POSTs the completed response to that URL. In `result` mode, Pi returns the completed response synchronously and ignores `responseWebhookUrl`.
+- Direct Mode defaults to `sessionType: "stateful"`. Use `sessionType: "stateless"` with an optional client-supplied `history` array to keep the Application session ID and routing while rebuilding the Pi context in memory for each request; no Pi session transcript is written or reused. The client owns the full conversational history in stateless mode. Stateless sessions are currently unavailable for sandboxed profiles.
+- `POST /api/message/app/:slug` accepts request bodies up to 200 MiB. This limit applies to the complete HTTP body, so base64-encoded file content is larger than the original file.
 - Inspect active sessions, roll over a conversation, preserve private handoff context, test handlers with a JSON payload, and stream or clear application logs from the Console or API.
 - Include an Evolution API adapter implementation while keeping Applications structurally independent from adapters.
 
@@ -128,11 +152,35 @@ curl -X POST \
 curl -H "Authorization: Bearer $PI_API_TOKEN" \
   http://127.0.0.1:8767/api/applications/support-inbox/handlers
 
-# Deliver an integration payload to an enabled Application
+# Deliver a conventional integration payload to an enabled Application
 curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"message":"A customer needs help with an order."}' \
   http://127.0.0.1:8767/api/message/app/support-inbox
+
+# Direct Mode: route through the Identity Key mapping and return the result.
+# Omit sessionId to use/create the active session for that identity route.
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"identityKey":"customer@example.com","message":"Where is my order?"}' \
+  http://127.0.0.1:8767/api/message/app/support-inbox
+
+# Stateless Direct Mode: history belongs entirely to the caller. Omit history for an empty context.
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"identityKey":"customer@example.com","sessionType":"stateless","history":[{"role":"user","content":"Hello"},{"role":"assistant","content":"How can I help?"}],"message":"Continue."}' \
+  http://127.0.0.1:8767/api/message/app/support-inbox
+
+# A stateless request may use a stable logical sessionId for routing and logs,
+# but it never creates or reuses a Pi JSONL transcript.
+curl -X POST -H "Content-Type: application/json" \
+  -d '{"identityKey":"customer@example.com","sessionId":"integration-thread-42","sessionType":"stateless","message":"Start without prior context."}' \
+  http://127.0.0.1:8767/api/message/app/support-inbox
+
+# In ack mode, provide a webhook for the completed response.
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"identityKey":"customer@example.com","message":"Where is my order?","responseWebhookUrl":"https://integration.example.com/pi-response"}' \
+  http://127.0.0.1:8767/api/message/app/support-inbox
 ```
 
 ### API Server
@@ -162,8 +210,8 @@ curl \
 
 What the API exposes:
 
-- Persistent chat and streaming chat sessions, including profile-specific sessions.
-- Profile lifecycle, settings, `SOUL.md`, environment variables, Guardrails, tools, Skills, and sessions.
+- Persistent chat and streaming chat sessions, including profile-specific sessions. Streaming chat reports real-time agent activity such as tool execution, thinking state, completion, and failures alongside response tokens.
+- Profile lifecycle, settings, default model selection, `SOUL.md`, environment variables, Guardrails, Context Memory, tools, Skills, and sessions.
 - Runtime-wide extension and package inventory and configuration.
 - Pulse schedules and execution history.
 - Git-backed Skill Sources, document preview, synchronization, and explicit profile imports.
@@ -174,7 +222,7 @@ The service generates and stores its bearer token in `api-server.json`, supports
 
 ### Pi Console WebUI and terminal
 
-The Pi Console WebUI is an operations cockpit, not merely a settings page. It gives administrators a visual way to operate the same runtime exposed by the CLI and API: inspect activity, configure profiles, edit application handlers, manage schedules, examine logs, and open a real terminal when direct command-line access is needed.
+The Pi Console WebUI is an operations cockpit, not merely a settings page. It gives administrators a visual way to operate the same runtime exposed by the CLI and API: inspect activity, configure profiles, edit application handlers, manage schedules, examine logs, and open a real terminal when direct command-line access is needed. During a chat response, it renders the agent's live tool and work activity before the final answer is complete.
 
 ```bash
 # Start, inspect, restart, and stop the WebUI
@@ -189,8 +237,9 @@ pi console stop
 
 The console provides dedicated workspaces for:
 
-- **Profiles:** settings, environment, `SOUL.md`, Guardrails, tools, Skills, and sessions. Extensions and packages are shown and managed as shared runtime resources.
-- **Applications:** configuration, identity mappings, active sessions, handler editor, transform testing, rollover, handoff, and live logs.
+- **Profiles:** settings, default model selection, environment, `SOUL.md`, Guardrails, tools, Skills, and sessions. Extensions and packages are shown and managed as shared runtime resources.
+- **Context Memory:** personal-context source selection, persistent Markdown memory editing, and Application handler creation and testing.
+- **Applications:** configuration, identity mappings (including `None`/ignore rules), active sessions, handler editor, transform testing, rollover, handoff, and live logs.
 - **Skill Sources:** source registration, Git synchronization, Skill preview, and deliberate import into a profile.
 - **Pulse:** schedules, enablement, run history, and profile/session association.
 - **Operations:** API Server and Console configuration, service controls, and resource visibility.
@@ -239,7 +288,7 @@ Skills remain explicit resources rather than hidden package behavior. A profile
 ~/.pi/agent/profiles/<profile>/skills/<skill>/SKILL.md
 ```
 
-- **Shared Skills** are centrally maintained under `~/.pi/agent/skills/` and can be selectively exposed to each profile.
+- **Shared Skills** are centrally maintained under `~/.pi/agent/skills/` and can be selectively exposed to each profile. Skills declared by installed shared-runtime packages are also discovered for named profiles and follow the same shared-Skill policy and allowlist.
 - **Profile Skills** live under `~/.pi/agent/profiles/<profile>/skills/` and remain isolated from other profiles.
 - Profile policy controls whether shared and profile-local sources are available and can allow all Skills or a named allowlist.
 - List and enable or disable Skills from the CLI and Console without editing settings by hand.
@@ -275,6 +324,7 @@ Refreshing synchronizes the source and atomically replaces the complete installe
 
 - Create and manage persistent scheduled prompts, reminders, cron jobs, one-time jobs, and heartbeat jobs.
 - Bind scheduled work to the active profile and conversation session.
+- Pulse results are recorded in every active Application session for the same profile by default. Set `insertIntoApiSession: false` only when that recording is not wanted. This adds context only: it does not invoke an outbound handler or send a message through an Application channel.
 - Persist schedules and execution history in SQLite with WAL support.
 - Start and inspect the scheduler:
 
@@ -282,8 +332,21 @@ Refreshing synchronizes the source and atomically replaces the complete installe
   pi pulse start
   pi pulse status
   pi pulse list
+  # After confirming an interrupted worker is no longer running:
+  pi pulse recover
   ```
 
+### Context Memory
+
+Context Memory keeps compact, durable facts separate from a session transcript and injects them when a new session starts. It is intended for stable operational context and personal context, not an unbounded conversation archive.
+
+- Each profile can maintain shared operational context in `context-memory/OPERATIONAL.md` (maximum 2,750 characters).
+- Personal context is configurable as a profile-wide `context-memory/PROFILE.md`, an Application-identity-specific `applications/<application>/context-memory/identities/<identity>/USER.md`, or a TypeScript Application handler that resolves it dynamically. Profile and identity memory are limited to 1,375 characters.
+- Identity memory is available only in an Application session and is isolated by Application and Identity Key.
+- The `context_memory` tool supports `read`, `insert`, `update`, `remove`, and `replace` actions against `operational` or `personal` memory without exposing file paths to the agent. Personal memory writes to the configured profile or identity target; storing sensitive values requires explicit confirmation.
+- Dynamic handlers must return Markdown, run only for Application sessions, have a three-second timeout, and can be created, edited, and tested from the Console. Handler execution is recorded in Application logs.
+- Stored memory is presented to the model as data rather than instructions. Changes apply to newly started sessions.
+
 ### CLI resource management
 
 - Inspect tools, Skills, extensions, sessions, packages, and profile resources from the terminal.
@@ -310,6 +373,8 @@ Refreshing synchronizes the source and atomically replaces the complete installe
 
 The following commands are the operational entry points added by `pi-feats`. Commands can target the default profile, a named local profile, or a remote host.
 
+Finite `pi-feats` CLI commands run with Pi's regular TUI mode so their output remains in the terminal scrollback. This does not change profile settings or affect interactive launches; pass `--tui-mode fullscreen` explicitly to override it for one command.
+
 ### Profiles
 
 ```bash
@@ -330,6 +395,11 @@ pi profile support extensions list
 pi profile support sessions list
 pi profile support packages list
 
+# Register, list, or delete hosts scoped to this profile
+pi profile support ssh add production-db
+pi profile support ssh list
+pi profile support ssh delete production-db
+
 # Resume the latest session or open a specific one
 pi profile resume support
 pi profile open support <session-id>
@@ -355,6 +425,10 @@ pi skills disable my-skill
 pi skills enable my-skill
 pi extensions disable my-extension
 pi extensions enable my-extension
+# A package with a sole index extension uses its package name. These commands
+# also update an explicit runtime extension allowlist.
+pi extensions disable pi-mcp-adapter
+pi extensions enable pi-mcp-adapter
 
 # Enable or disable an installed package for the selected profile
 pi packages disable npm:some-package
@@ -423,6 +497,7 @@ The `remote:<name>` form forwards the rest of the command to the selected remote
 | API Server | HTTP API, Applications, profile administration, sessions, logs, and terminal tickets. |
 | Browser Harness | Steel Profile-scoped CDP browser automation for active Pi Profiles. |
 | CLI Resources | Resource, package, session, and profile commands. |
+| Context Memory | Persistent operational and personal context for new sessions. |
 | Guardrails | Input, tool, and output policy stages. |
 | Pi Console WebUI | Browser-based operations console and terminal client. |
 | Profiles | Profile lifecycle, policy, sandbox, and remote routing. |
@@ -498,7 +573,11 @@ npm install
 npm run build:web
 ```
 
-The root `package.json` is the package manifest. Its `pi.extensions` field explicitly exports every extension; the package does not rely on directory auto-discovery.
+The root `package.json` is the package manifest. Its `pi.extensions` and `pi.themes` fields explicitly export every extension and theme; the package does not rely on directory auto-discovery.
+
+### Themes
+
+The package includes `legacy-dark`, which preserves Pi's pre-`bf8e4b95` dark palette. After updating or installing `pi-feats`, select it in `/settings` → **Theme**, or set `"theme": "legacy-dark"` in `<agent-dir>/settings.json` and run `/reload`.
 
 ## Security
 
@@ -523,6 +602,8 @@ pi-feats/
 │   ├── cli-resources.ts
 │   ├── profiles.ts
 │   └── sequential-workflow.ts
+├── themes/
+│   └── legacy-dark.json          # Pre-bf8e4b95 Pi dark palette
 └── README.md
 ```
 

package/extensions/api-server/README.md

@@ -62,6 +62,26 @@ Request body:
 
 `/chat/stream` uses Server-Sent Events: `session`, `token`, and `done`.
 
+## Application Direct Mode
+
+`POST /api/message/app/:slug` supports Direct Mode for integrations that supply an Identity Key and a message. It resolves the Application's Identity Key mapping and bypasses application handlers.
+
+```json
+{
+  "identityKey": "customer@example.com",
+  "sessionType": "stateless",
+  "history": [
+    { "role": "user", "content": "My name is Ada." },
+    { "role": "assistant", "content": "Hello, Ada." }
+  ],
+  "message": "What is my name?"
+}
+```
+
+`sessionType` defaults to `stateful`, which creates or resumes a persistent Pi JSONL session. With `sessionType: "stateless"`, the server creates an in-memory Pi session for the request only and disposes it after responding. The optional `history` is supplied and owned by the caller; omitting it starts with no conversational context. A stateless `sessionId` is a logical identifier for Application routing, logs, and metrics only, not a transcript. Stateless mode is unavailable for sandboxed profiles.
+
+The Application message endpoint accepts complete HTTP request bodies up to 200 MiB. Account for base64 expansion when embedding file data in JSON.
+
 ## Sessions and profiles
 
 Sessions are created in the same persistent location used by the CLI. For example, a session created through the API can be resumed with:
@@ -81,7 +101,7 @@ All routes below require Bearer authentication. Resource responses expose only m
 
 ```text
 GET    /api/profiles
-POST   /api/profiles                         { "name": "work" }
+POST   /api/profiles                         { "name": "work", "cloneFrom": "existing-profile" }
 GET    /api/profiles/:profile
 DELETE /api/profiles/:profile                 { "force": true }
 

package/extensions/api-server/application-log-store.ts

@@ -4,10 +4,11 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import type { ContextMemoryExecutionLog } from "../lib/application-context.ts";
 export type CallStage = { id: string; type: string; label: string; startedAt: string; finishedAt?: string; input?: unknown; output?: unknown; payload?: unknown; stdout: string[]; stderr: string[]; error?: string };
-export type ApplicationCall = { id: string; application: string; origin: string; receivedAt: string; finishedAt?: string; status: "running" | "success" | "error"; headers: Record<string, unknown>; stages: CallStage[]; error?: string };
+export type ApplicationCall = { id: string; application: string; origin: string; receivedAt: string; finishedAt?: string; status: "running" | "success" | "ignored" | "error"; outcome?: "ignored"; headers: Record<string, unknown>; stages: CallStage[]; error?: string };
 export class ApplicationLogStore {
   private calls = new Map<string, ApplicationCall>(); private events = new EventEmitter(); private directory: string;
-  constructor(applicationDirectory: string, readonly application: string) { this.directory = join(applicationDirectory, "logs", "calls"); }
+  readonly application: string;
+  constructor(applicationDirectory: string, application: string) { this.application = application; this.directory = join(applicationDirectory, "logs", "calls"); }
   async initialize() { await mkdir(this.directory, { recursive: true }); const cutoff = Date.now() - 7 * 86400000; for (const entry of await readdir(this.directory)) { const path = join(this.directory, entry); try { const call = JSON.parse(await readFile(path, "utf8")) as ApplicationCall; if (new Date(call.receivedAt).getTime() < cutoff) await rm(path); else this.calls.set(call.id, call); } catch {} } }
   private async save(call: ApplicationCall) { await mkdir(this.directory, { recursive: true }); await writeFile(join(this.directory, `${call.id}.json`), JSON.stringify(call), "utf8"); this.events.emit("event", { type: "call.updated", call }); }
   start(payload: unknown, headers: Record<string, unknown>) { const call: ApplicationCall = { id: randomUUID(), application: this.application, origin: String(headers["x-forwarded-for"] ?? headers.origin ?? headers.host ?? "unknown"), receivedAt: new Date().toISOString(), status: "running", headers, stages: [{ id: randomUUID(), type: "request", label: "Request", startedAt: new Date().toISOString(), finishedAt: new Date().toISOString(), payload, stdout: [], stderr: [] }] }; this.calls.set(call.id, call); void this.save(call); return call; }
@@ -16,6 +17,7 @@ export class ApplicationLogStore {
   annotate(call: ApplicationCall, stage: CallStage, output: unknown) { stage.output = output; void this.save(call); }
   fail(call: ApplicationCall, stage: CallStage | undefined, error: unknown) { const message = error instanceof Error ? `${error.message}\n${error.stack ?? ""}` : String(error); if (stage) { stage.error = message; stage.finishedAt = new Date().toISOString(); } call.error = message; call.status = "error"; call.finishedAt = new Date().toISOString(); void this.save(call); }
   finish(call: ApplicationCall, output: unknown) { call.status = "success"; call.finishedAt = new Date().toISOString(); const stage = this.stage(call, "final-response", "Final response", output); this.complete(call, stage, output); }
+  ignore(call: ApplicationCall, identityKey: string, reason: "identity_miss" | "identity_mapping_none" = "identity_miss") { const mappingIgnore = reason === "identity_mapping_none", output = { status: "ignored", reason, identityKey }; call.status = "success"; call.outcome = "ignored"; call.finishedAt = new Date().toISOString(); const stage = this.stage(call, mappingIgnore ? "identity-ignored" : "identity-miss", mappingIgnore ? "Ignored by identity mapping" : "Identity miss", { identityKey, reason }); this.complete(call, stage, output); return output; }
   recordContextMemory(input: { profile: string; identityKey: string; sessionId: string; execution: ContextMemoryExecutionLog }) {
     const { execution } = input;
     const stage: CallStage = {

package/extensions/api-server/application-runtime.ts

@@ -8,9 +8,10 @@ import { inspect } from "node:util";
 import { ApplicationLogStore } from "./application-log-store.ts";
 
 type RecordValue = Record<string, any>;
-export type Settings = { responseMode: "ack" | "result"; transformHandlers?: string[]; inboundHandler: string; outboundHandler?: string; defaultProfile?: string | null; messageCoalescing?: { enabled?: boolean; silenceDebounceSeconds?: number } };
+export type Settings = { responseMode: "ack" | "result"; transformHandlers?: string[]; inboundHandler: string; outboundHandler?: string; defaultProfile?: string | null; directMode?: { enabled?: boolean }; messageCoalescing?: { enabled?: boolean; silenceDebounceSeconds?: number } };
+export type DirectRequest = { identityKey: string; message: string; sessionId?: string; contextMemory?: string; responseWebhookUrl?: string; profile: string; sessionPrefix: string; sessionType: "stateful" | "stateless"; history?: Array<{ role: "user" | "assistant"; content: string }> };
 type Handler = (payload: RecordValue, headers?: RecordValue | null, query?: RecordValue | null, context?: RecordValue | null, state?: RecordValue | null, env?: Record<string, string | undefined>) => Promise<any> | any;
-type ApplicationApi = { agentSettings(): Promise<Record<string, unknown>>; listSessions(profile: string): Promise<Array<Record<string, unknown>>>; createSession(profile: string, input: unknown): Promise<Record<string, unknown>>; getSessionConversation(profile: string, sessionId: string): Promise<Record<string, unknown>>; complete(profile: string, prompt: string): Promise<string>; prompt(profile: string, sessionId: string, message: string, handoff?: string, applicationContext?: { application: string; identityKey: string }): Promise<{ profile: string; sessionId: string; response: string }>; getIdentityMapping(application: string, identityKey: string): Promise<{ profile: string; sessionMode: "fixed" | "automatic"; sessionPrefix: string | null } | undefined>; automaticApplicationSessionPrefix(application: string, identityKey: string): Promise<string>;  getApplicationSession(application: string, profile: string, prefix: string): Promise<{ sessionId: string } | undefined>; getActiveApplicationSession(application: string, profile: string, prefix: string): Promise<{ sessionId: string } | undefined>; nextApplicationSessionId(application: string, profile: string, prefix: string): Promise<string>; recordApplicationSession(application: string, profile: string, prefix: string, sessionId: string, rollover: boolean): Promise<void>; touchApplicationSession(application: string, profile: string, prefix: string, sessionId: string, from?: string): Promise<void>;  retargetPulseThreadSessions(profile: string, fromSessionId: string, toSessionId: string): Promise<void>; handlerEnvironment(profile: string): Promise<Record<string, string | undefined>> };
+type ApplicationApi = { agentSettings(): Promise<Record<string, unknown>>; listSessions(profile: string): Promise<Array<Record<string, unknown>>>; createSession(profile: string, input: unknown): Promise<Record<string, unknown>>; getSessionConversation(profile: string, sessionId: string): Promise<Record<string, unknown>>; complete(profile: string, prompt: string): Promise<string>; prompt(profile: string, sessionId: string, message: string, handoff?: string, applicationContext?: { application: string; identityKey: string; directContextMemory?: string }): Promise<{ profile: string; sessionId: string; response: string }>; promptStateless(profile: string, sessionId: string, history: Array<{ role: "user" | "assistant"; content: string }>, message: string, applicationContext?: { application: string; identityKey: string; directContextMemory?: string }): Promise<{ profile: string; sessionId: string; response: string }>; getIdentityMapping(application: string, identityKey: string): Promise<{ profile: string | null; sessionMode: "fixed" | "automatic" | "ignore"; sessionPrefix: string | null } | undefined>; automaticApplicationSessionPrefix(application: string, identityKey: string): Promise<string>;  getApplicationSession(application: string, profile: string, prefix: string, sessionType?: "stateful" | "stateless"): Promise<{ sessionId: string; sessionType?: "stateful" | "stateless" } | undefined>; getActiveApplicationSession(application: string, profile: string, prefix: string): Promise<{ sessionId: string } | undefined>; nextApplicationSessionId(application: string, profile: string, prefix: string): Promise<string>; recordApplicationSession(application: string, profile: string, prefix: string, sessionId: string, rollover: boolean, sessionType?: "stateful" | "stateless"): Promise<void>; touchApplicationSession(application: string, profile: string, prefix: string, sessionId: string, from?: string): Promise<void>;  retargetPulseThreadSessions(profile: string, fromSessionId: string, toSessionId: string): Promise<void>; handlerEnvironment(profile: string): Promise<Record<string, string | undefined>> };
 type Handoff = { sourceSessionId: string | null; summary: string; createdAt: string; targetCreatedAt: string };
 type WorkingSession = { sessionId: string; updatedAt: string; reason: "message" | "rollover" };
 type CoalescedEntry = { call: ReturnType<ApplicationLogStore["start"]>; stage: ReturnType<ApplicationLogStore["stage"]>; message: string; state: RecordValue; version: number; dispatch: (message: string, state: RecordValue) => Promise<unknown>; resolve: (output: unknown) => void; reject: (error: unknown) => void };
@@ -95,12 +96,22 @@ export class ApplicationRuntime {
     try { return await operation(); } finally { release(); if (this.queues.get(key) === current) this.queues.delete(key); }
   }
 
+  private async createApplicationSession(profile: string, sessionPrefix: string, rollover: boolean): Promise<string> {
+    const id = await this.api.nextApplicationSessionId(this.application.slug, profile, sessionPrefix);
+    // A process can stop after Pi has persisted the session file but before the
+    // Application row is written. Reclaim that deterministic orphan instead of
+    // attempting to create it again and permanently failing with a 409.
+    const exists = (await this.api.listSessions(profile)).some((session) => session.id === id);
+    if (!exists) await this.api.createSession(profile, { id });
+    await this.api.recordApplicationSession(this.application.slug, profile, sessionPrefix, id, rollover);
+    return id;
+  }
+
   private async resolveSession(profile: string, sessionPrefix: string): Promise<string> {
     if (!safeName(sessionPrefix)) throw Object.assign(new Error("Invalid sessionPrefix."), { status: 422 });
     return this.withQueue(`${this.application.slug}:${profile}:${sessionPrefix}:${day()}`, async () => {
       const current = await this.api.getApplicationSession(this.application.slug, profile, sessionPrefix); if (current) return current.sessionId;
-      const id = await this.api.nextApplicationSessionId(this.application.slug, profile, sessionPrefix);
-      await this.api.createSession(profile, { id }); await this.api.recordApplicationSession(this.application.slug, profile, sessionPrefix, id, false); return id;
+      return this.createApplicationSession(profile, sessionPrefix, false);
     });
   }
 
@@ -176,8 +187,8 @@ export class ApplicationRuntime {
     if (typeof sessionPrefix !== "string" || !sessionPrefix) throw Object.assign(new Error("The 'sessionPrefix' field is required."), { status: 400 });
     if (!safeName(sessionPrefix)) throw Object.assign(new Error("Invalid sessionPrefix"), { status: 400 });
     return this.withQueue(`${this.application.slug}:${profile}:${sessionPrefix}:${day()}`, async () => {
-      const previous = await this.api.getActiveApplicationSession(this.application.slug, profile, sessionPrefix); const sessionId = await this.api.nextApplicationSessionId(this.application.slug, profile, sessionPrefix);
-      await this.api.createSession(profile, { id: sessionId }); await this.api.recordApplicationSession(this.application.slug, profile, sessionPrefix, sessionId, true); if (previous?.sessionId && previous.sessionId !== sessionId) await this.api.retargetPulseThreadSessions(profile, previous.sessionId, sessionId);
+      const previous = await this.api.getActiveApplicationSession(this.application.slug, profile, sessionPrefix); const sessionId = await this.createApplicationSession(profile, sessionPrefix, true);
+      if (previous?.sessionId && previous.sessionId !== sessionId) await this.api.retargetPulseThreadSessions(profile, previous.sessionId, sessionId);
       try {
         const handoff = await this.handoff(profile, sessionId, sessionPrefix, true);
         return { profile, sessionId, messageCount: 0, handoff: { status: handoff?.summary ? "ready" : "none", sourceSessionId: handoff?.sourceSessionId ?? null } };
@@ -233,14 +244,72 @@ export class ApplicationRuntime {
     this.coalescingBuffers.clear();
   }
 
-  async process(payload: unknown, headers: RecordValue, query: RecordValue): Promise<unknown> {
+  isDirectRequest(payload: unknown): boolean {
+    return this.settings.directMode?.enabled !== false && Object.prototype.hasOwnProperty.call(asRecord(payload), "identityKey");
+  }
+
+  async prepareDirectRequest(payload: unknown): Promise<DirectRequest> {
+    const body = asRecord(payload);
+    const identityKey = typeof body.identityKey === "string" ? body.identityKey.trim() : "";
+    const message = typeof body.message === "string" ? body.message.trim() : "";
+    if (!identityKey) throw Object.assign(new Error("identityKey must be a non-empty string for a Direct Mode request."), { status: 400 });
+    if (!message) throw Object.assign(new Error("message must be a non-empty string for a Direct Mode request."), { status: 400 });
+    const sessionType = body.sessionType === undefined ? "stateful" : body.sessionType; if (sessionType !== "stateful" && sessionType !== "stateless") throw Object.assign(new Error("sessionType must be 'stateful' or 'stateless'."), { status: 400 }); const history = body.history; if (history !== undefined && (!Array.isArray(history) || history.some((item) => !item || typeof item !== "object" || !["user", "assistant"].includes((item as RecordValue).role) || typeof (item as RecordValue).content !== "string"))) throw Object.assign(new Error("history must contain text user or assistant messages."), { status: 400 }); if (history !== undefined && (history.length > 100 || history.reduce((total, item) => total + (item as RecordValue).content.length, 0) > 100_000)) throw Object.assign(new Error("history exceeds the 100-message or 100,000-character limit."), { status: 413 }); if (sessionType === "stateful" && history !== undefined) throw Object.assign(new Error("history is only supported for stateless sessions."), { status: 400 });
+    const sessionId = body.sessionId;
+    if (sessionId !== undefined && (typeof sessionId !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(sessionId))) throw Object.assign(new Error("Invalid sessionId."), { status: 400 });
+    const contextMemory = body.contextMemory;
+    if (contextMemory !== undefined && typeof contextMemory !== "string") throw Object.assign(new Error("contextMemory must be a string."), { status: 400 });
+    if (typeof contextMemory === "string" && Array.from(contextMemory.trim()).length > 1375) throw Object.assign(new Error("contextMemory exceeds its 1375-character limit."), { status: 413 });
+    const responseWebhookUrl = body.responseWebhookUrl;
+    if (this.settings.responseMode === "ack") {
+      if (typeof responseWebhookUrl !== "string" || !responseWebhookUrl.trim()) throw Object.assign(new Error("responseWebhookUrl is required for Direct Mode requests when Response Mode is ack."), { status: 400 });
+      try { const url = new URL(responseWebhookUrl); if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(); } catch { throw Object.assign(new Error("responseWebhookUrl must be a valid HTTP or HTTPS URL."), { status: 400 }); }
+    }
+    const mapped = await this.api.getIdentityMapping(this.application.slug, identityKey);
+    if (!mapped) throw Object.assign(new Error("No Identity Key mapping was found for this Application."), { status: 422 });
+    if (mapped.sessionMode === "ignore") throw Object.assign(new Error("The Identity Key mapping is configured to ignore requests."), { status: 422 });
+    const profile = mapped.profile ?? undefined;
+    const sessionPrefix = mapped.sessionMode === "automatic" ? await this.api.automaticApplicationSessionPrefix(this.application.slug, identityKey) : mapped.sessionPrefix;
+    if (!profile || !sessionPrefix) throw Object.assign(new Error("The Identity Key mapping has no Application route."), { status: 422 });
+    return { identityKey, message, ...(typeof sessionId === "string" ? { sessionId } : {}), ...(typeof contextMemory === "string" ? { contextMemory } : {}), ...(this.settings.responseMode === "ack" && typeof responseWebhookUrl === "string" ? { responseWebhookUrl: responseWebhookUrl.trim() } : {}), profile, sessionPrefix, sessionType, ...(history !== undefined ? { history: history as Array<{ role: "user" | "assistant"; content: string }> } : {}) };
+  }
+
+  private async resolveDirectSession(request: DirectRequest): Promise<string> {
+    if (!request.sessionId && request.sessionType === "stateful") return this.resolveSession(request.profile, request.sessionPrefix); if (!request.sessionId) return this.withQueue(`${this.application.slug}:${request.profile}:${request.sessionPrefix}:stateless`, async () => { const current = await this.api.getApplicationSession(this.application.slug, request.profile, request.sessionPrefix, request.sessionType) as any; if (current) { if (current.sessionType !== "stateless") throw Object.assign(new Error("The active Application session is stateful."), { status: 409 }); return current.sessionId; } const id = await this.api.nextApplicationSessionId(this.application.slug, request.profile, request.sessionPrefix); await this.api.recordApplicationSession(this.application.slug, request.profile, request.sessionPrefix, id, false, "stateless"); return id; });
+    return this.withQueue(`${this.application.slug}:${request.profile}:${request.sessionPrefix}:direct:${request.sessionId}`, async () => {
+      const current = await this.api.getApplicationSession(this.application.slug, request.profile, request.sessionPrefix, request.sessionType) as any;
+      if (current?.sessionType && current.sessionType !== request.sessionType) throw Object.assign(new Error("sessionId belongs to a different sessionType."), { status: 409 });
+      if (request.sessionType === "stateful") { const exists = (await this.api.listSessions(request.profile)).some((session) => session.id === request.sessionId); if (!exists) await this.api.createSession(request.profile, { id: request.sessionId }); }
+      await this.api.recordApplicationSession(this.application.slug, request.profile, request.sessionPrefix, request.sessionId, false, request.sessionType);
+      return request.sessionId;
+    });
+  }
+
+  private async processDirect(payload: unknown, headers: RecordValue, query: RecordValue, prepared?: DirectRequest): Promise<unknown> {
+    const request = prepared ?? await this.prepareDirectRequest(payload);
+    const call = this.logs.start(payload, headers); let active: any;
+    const context = { application: this.application, settings: await this.api.agentSettings(), request: { id: call.id, headers, query }, log: { info: (...values: unknown[]) => active?.stdout.push(values.map(String).join(" ")), error: (...values: unknown[]) => active?.stderr.push(values.map(String).join(" ")) } };
+    const run = async (type: string, label: string, input: unknown, operation: () => Promise<any>) => { active = this.logs.stage(call, type, label, input); try { const output = await operation(); this.logs.complete(call, active, output); return output; } catch (error) { this.logs.fail(call, active, error); throw error; } finally { active = undefined; } };
+    try {
+      const sessionId = await this.resolveDirectSession(request);
+      const result = await run("pi-agent", "Pi agent (Direct Mode)", { profile: request.profile, sessionId, message: request.message }, () => request.sessionType === "stateless" ? this.api.promptStateless(request.profile, sessionId, request.history ?? [], request.message, { application: this.application.slug, identityKey: request.identityKey, ...(request.contextMemory !== undefined ? { directContextMemory: request.contextMemory } : {}) }) : this.api.prompt(request.profile, sessionId, request.message, undefined, { application: this.application.slug, identityKey: request.identityKey, ...(request.contextMemory !== undefined ? { directContextMemory: request.contextMemory } : {}) }));
+      await this.setWorkingSession(request.profile, request.sessionPrefix, sessionId, "message");
+      await this.api.touchApplicationSession(this.application.slug, request.profile, request.sessionPrefix, sessionId, request.identityKey);
+      const output = { ...result, direct: true };
+      this.logs.finish(call, output);
+      return output;
+    } catch (error) { if (call.status !== "error") this.logs.fail(call, undefined, error); throw error; }
+  }
+
+  async process(payload: unknown, headers: RecordValue, query: RecordValue, preparedDirect?: DirectRequest): Promise<unknown> {
+    if (preparedDirect || this.isDirectRequest(payload)) return this.processDirect(payload, headers, query, preparedDirect);
     const call = this.logs.start(payload, headers); let active: any; let current = asRecord(payload); let state: RecordValue = {};
     const context = { application: this.application, settings: await this.api.agentSettings(), request: { id: call.id, headers, query }, log: { info: (...values: unknown[]) => active?.stdout.push(values.map(String).join(" ")), error: (...values: unknown[]) => active?.stderr.push(values.map(String).join(" ")) } };
     const run = async (type: string, label: string, input: unknown, operation: () => Promise<any>) => { active = this.logs.stage(call, type, label, input); try { const output = await operation(); this.logs.complete(call, active, output); return output; } catch (error) { this.logs.fail(call, active, error); throw error; } finally { active = undefined; } };
     try {
       for (const name of this.settings.transformHandlers ?? []) { const result = await run("transform", `Transform: ${name}`, current, async () => this.handler("transform", name)(current, headers, query, context, state, await this.environmentFor(current, payload, query))); if (result && typeof result === "object" && "payload" in result) { current = asRecord(result.payload); state = { ...state, ...asRecord(result.state) }; } else current = asRecord(result); }
       const inbound = await run("inbound-handler", `Inbound handler: ${this.settings.inboundHandler}`, current, async () => this.handler("inbound", this.settings.inboundHandler)(current, headers, query, context, state, await this.environmentFor(current, payload, query)));
-      const routed = asRecord(inbound); const hasIdentityKey = Object.prototype.hasOwnProperty.call(routed, "identityKey"); const identityKey = typeof routed.identityKey === "string" ? routed.identityKey.trim() : undefined; if (hasIdentityKey && !identityKey) throw Object.assign(new Error("identityKey must be a non-empty string when provided."), { status: 422 }); let profile: string | undefined, sessionPrefix: string | null | undefined; if (identityKey) { const mapped = await this.api.getIdentityMapping(this.application.slug, identityKey); if (!mapped) throw Object.assign(new Error("No Identity Key mapping was found for this Application."), { status: 422 }); profile = mapped.profile; sessionPrefix = mapped.sessionMode === "automatic" ? await this.api.automaticApplicationSessionPrefix(this.application.slug, identityKey) : mapped.sessionPrefix; if (!sessionPrefix) throw Object.assign(new Error("The Identity Key mapping has no session prefix."), { status: 422 }); } else { profile = typeof routed.profile === "string" && routed.profile.trim() ? routed.profile.trim() : undefined; sessionPrefix = typeof (routed.sessionPrefix ?? routed.session_prefix) === "string" ? String(routed.sessionPrefix ?? routed.session_prefix).trim() || undefined : undefined; if (!profile) throw Object.assign(new Error("Inbound must return profile when identityKey is not provided."), { status: 422 }); sessionPrefix ??= "default"; } if (!profile || !sessionPrefix) throw Object.assign(new Error("No Application route was resolved."), { status: 422 }); const message = asRecord(routed.payload).message; if (typeof message !== "string" || !message.trim()) throw Object.assign(new Error("The Application did not produce a text message."), { status: 422 }); state = { ...state, ...asRecord(routed.state) };
+      const routed = asRecord(inbound); const rawIdentityKey = routed.identityKey; const identityKey = typeof rawIdentityKey === "string" ? rawIdentityKey.trim() || undefined : undefined; if (rawIdentityKey !== undefined && rawIdentityKey !== null && typeof rawIdentityKey !== "string") throw Object.assign(new Error("identityKey must be a string when provided."), { status: 422 }); let profile: string | undefined, sessionPrefix: string | null | undefined; if (identityKey) { const mapped = await this.api.getIdentityMapping(this.application.slug, identityKey); if (!mapped) return this.logs.ignore(call, identityKey, "identity_miss"); if (mapped.sessionMode === "ignore") return this.logs.ignore(call, identityKey, "identity_mapping_none"); profile = mapped.profile ?? undefined; sessionPrefix = mapped.sessionMode === "automatic" ? await this.api.automaticApplicationSessionPrefix(this.application.slug, identityKey) : mapped.sessionPrefix; if (!sessionPrefix) throw Object.assign(new Error("The Identity Key mapping has no session prefix."), { status: 422 }); } else { profile = typeof routed.profile === "string" && routed.profile.trim() ? routed.profile.trim() : this.application.defaultProfile ?? undefined; sessionPrefix = typeof (routed.sessionPrefix ?? routed.session_prefix) === "string" ? String(routed.sessionPrefix ?? routed.session_prefix).trim() || undefined : undefined; if (!profile) throw Object.assign(new Error("Inbound must return profile when identityKey is not provided and the Application has no default profile."), { status: 422 }); sessionPrefix ??= "default"; } if (!profile || !sessionPrefix) throw Object.assign(new Error("No Application route was resolved."), { status: 422 }); const message = asRecord(routed.payload).message; if (typeof message !== "string" || !message.trim()) throw Object.assign(new Error("The Application did not produce a text message."), { status: 422 }); state = { ...state, ...asRecord(routed.state) };
       const dispatch = async (coalescedMessage: string, coalescedState: RecordValue): Promise<unknown> => {
         const sessionId = await this.resolveSession(profile!, sessionPrefix!);
         let handoff: string | undefined;
@@ -268,6 +337,8 @@ export function validateApplicationSettings(raw: unknown): asserts raw is Settin
   if (!safeName(settings.inboundHandler)) throw Object.assign(new Error("Invalid inbound handler."), { status: 400 });
   if (settings.outboundHandler !== undefined && !safeName(settings.outboundHandler)) throw Object.assign(new Error("Invalid outbound handler."), { status: 400 });
   if (settings.transformHandlers !== undefined && (!Array.isArray(settings.transformHandlers) || settings.transformHandlers.some((name) => !safeName(name)))) throw Object.assign(new Error("Invalid transform handlers."), { status: 400 });
+  const directMode = settings.directMode;
+  if (directMode !== undefined && (!directMode || typeof directMode !== "object" || (directMode.enabled !== undefined && typeof directMode.enabled !== "boolean"))) throw Object.assign(new Error("Invalid Direct Mode settings."), { status: 400 });
   const coalescing = settings.messageCoalescing;
   if (coalescing !== undefined && (!coalescing || typeof coalescing !== "object" || (coalescing.enabled !== undefined && typeof coalescing.enabled !== "boolean") || (coalescing.silenceDebounceSeconds !== undefined && (!Number.isInteger(coalescing.silenceDebounceSeconds) || coalescing.silenceDebounceSeconds < 1 || coalescing.silenceDebounceSeconds > 3600)))) throw Object.assign(new Error("Invalid message coalescing settings."), { status: 400 });
 }

package/extensions/api-server/application-store.ts

@@ -6,23 +6,36 @@ export type ApplicationRecord = { id: string; name: string; slug: string; enable
 type Row = Record<string, unknown>; const now = () => new Date().toISOString();
 export class ApplicationStore {
   private db: DatabaseSync;
-  constructor(path: string) { mkdirSync(dirname(path), { recursive: true }); this.db = new DatabaseSync(path); this.db.exec(`CREATE TABLE IF NOT EXISTS applications (id TEXT PRIMARY KEY, name TEXT NOT NULL, slug TEXT NOT NULL UNIQUE, enabled INTEGER NOT NULL DEFAULT 1, response_mode TEXT NOT NULL CHECK(response_mode IN ('ack','result')), default_profile TEXT, routing_policy TEXT NOT NULL CHECK(routing_policy IN ('default_as_fallback','drop')), settings_json TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); CREATE TABLE IF NOT EXISTS application_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS application_sessions (id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, profile TEXT NOT NULL, session_prefix TEXT NOT NULL, session_id TEXT NOT NULL UNIQUE, session_date TEXT NOT NULL, sequence INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, last_message_at TEXT, message_count INTEGER NOT NULL DEFAULT 0, created_from_rollover INTEGER NOT NULL DEFAULT 0, last_identity_key TEXT, UNIQUE(application_slug, profile, session_prefix, session_date, sequence)); CREATE TABLE IF NOT EXISTS application_session_state (application_slug TEXT NOT NULL, profile TEXT NOT NULL, session_prefix TEXT NOT NULL, current_session_id TEXT NOT NULL, updated_at TEXT NOT NULL, reason TEXT NOT NULL, PRIMARY KEY(application_slug, profile, session_prefix)); CREATE TABLE IF NOT EXISTS application_identity_mappings (id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, identity_key TEXT NOT NULL, profile TEXT NOT NULL, session_mode TEXT NOT NULL DEFAULT 'fixed', session_prefix TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(application_slug, identity_key)); CREATE TABLE IF NOT EXISTS application_automatic_prefixes (application_slug TEXT NOT NULL, identity_key TEXT NOT NULL, session_prefix TEXT NOT NULL, created_at TEXT NOT NULL, PRIMARY KEY(application_slug, identity_key), UNIQUE(application_slug, session_prefix)); CREATE TABLE IF NOT EXISTS application_console_sessions (session_id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, profile TEXT NOT NULL, identity_key TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);`); this.migrate(); }
-  private migrate() { const tables = new Set((this.db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as Row[]).map((row) => String(row.name))); if (tables.has("application_from_mappings")) { if (!tables.has("application_identity_mappings")) this.db.exec("ALTER TABLE application_from_mappings RENAME TO application_identity_mappings; ALTER TABLE application_identity_mappings RENAME COLUMN from_identifier TO identity_key;"); else this.db.exec("INSERT OR IGNORE INTO application_identity_mappings (id,application_slug,identity_key,profile,session_mode,session_prefix,created_at,updated_at) SELECT id,application_slug,from_identifier,profile,'fixed',session_prefix,created_at,updated_at FROM application_from_mappings; DROP TABLE application_from_mappings;"); } const columns = (table: string) => new Set((this.db.prepare(`PRAGMA table_info(${table})`).all() as Row[]).map((row) => String(row.name))); const mapping = columns("application_identity_mappings"); if (!mapping.has("session_mode")) this.db.exec("ALTER TABLE application_identity_mappings ADD COLUMN session_mode TEXT NOT NULL DEFAULT 'fixed';"); const sessions = columns("application_sessions"); if (sessions.has("last_from") && !sessions.has("last_identity_key")) this.db.exec("ALTER TABLE application_sessions RENAME COLUMN last_from TO last_identity_key;"); }
+  constructor(path: string) { mkdirSync(dirname(path), { recursive: true }); this.db = new DatabaseSync(path); this.db.exec(`CREATE TABLE IF NOT EXISTS applications (id TEXT PRIMARY KEY, name TEXT NOT NULL, slug TEXT NOT NULL UNIQUE, enabled INTEGER NOT NULL DEFAULT 1, response_mode TEXT NOT NULL CHECK(response_mode IN ('ack','result')), default_profile TEXT, routing_policy TEXT NOT NULL CHECK(routing_policy IN ('default_as_fallback','drop')), settings_json TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); CREATE TABLE IF NOT EXISTS application_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL); CREATE TABLE IF NOT EXISTS application_sessions (id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, profile TEXT NOT NULL, session_prefix TEXT NOT NULL, session_id TEXT NOT NULL UNIQUE, session_date TEXT NOT NULL, sequence INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, last_message_at TEXT, message_count INTEGER NOT NULL DEFAULT 0, created_from_rollover INTEGER NOT NULL DEFAULT 0, last_identity_key TEXT, session_type TEXT NOT NULL DEFAULT 'stateful' CHECK(session_type IN ('stateful','stateless')), UNIQUE(application_slug, profile, session_prefix, session_date, sequence)); CREATE TABLE IF NOT EXISTS application_session_state (application_slug TEXT NOT NULL, profile TEXT NOT NULL, session_prefix TEXT NOT NULL, session_type TEXT NOT NULL DEFAULT 'stateful' CHECK(session_type IN ('stateful','stateless')), current_session_id TEXT NOT NULL, updated_at TEXT NOT NULL, reason TEXT NOT NULL, PRIMARY KEY(application_slug, profile, session_prefix, session_type)); CREATE TABLE IF NOT EXISTS application_identity_mappings (id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, identity_key TEXT NOT NULL, profile TEXT, session_mode TEXT NOT NULL DEFAULT 'fixed', session_prefix TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(application_slug, identity_key)); CREATE TABLE IF NOT EXISTS application_automatic_prefixes (application_slug TEXT NOT NULL, identity_key TEXT NOT NULL, session_prefix TEXT NOT NULL, created_at TEXT NOT NULL, PRIMARY KEY(application_slug, identity_key), UNIQUE(application_slug, session_prefix)); CREATE TABLE IF NOT EXISTS application_console_sessions (session_id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, profile TEXT NOT NULL, identity_key TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);`); this.migrate(); }
+  private migrate() { const tables = new Set((this.db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as Row[]).map((row) => String(row.name))); if (tables.has("application_from_mappings")) { if (!tables.has("application_identity_mappings")) this.db.exec("ALTER TABLE application_from_mappings RENAME TO application_identity_mappings; ALTER TABLE application_identity_mappings RENAME COLUMN from_identifier TO identity_key;"); else this.db.exec("INSERT OR IGNORE INTO application_identity_mappings (id,application_slug,identity_key,profile,session_mode,session_prefix,created_at,updated_at) SELECT id,application_slug,from_identifier,profile,'fixed',session_prefix,created_at,updated_at FROM application_from_mappings; DROP TABLE application_from_mappings;"); } const columns = (table: string) => new Set((this.db.prepare(`PRAGMA table_info(${table})`).all() as Row[]).map((row) => String(row.name))); const mapping = columns("application_identity_mappings"); if (!mapping.has("session_mode")) this.db.exec("ALTER TABLE application_identity_mappings ADD COLUMN session_mode TEXT NOT NULL DEFAULT 'fixed';"); if (mapping.has("profile") && (this.db.prepare("PRAGMA table_info(application_identity_mappings)").all() as Row[]).find((row) => String(row.name) === "profile")?.notnull) this.db.exec("BEGIN; CREATE TABLE application_identity_mappings_next (id TEXT PRIMARY KEY, application_slug TEXT NOT NULL, identity_key TEXT NOT NULL, profile TEXT, session_mode TEXT NOT NULL DEFAULT 'fixed', session_prefix TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, UNIQUE(application_slug, identity_key)); INSERT INTO application_identity_mappings_next SELECT id,application_slug,identity_key,profile,session_mode,session_prefix,created_at,updated_at FROM application_identity_mappings; DROP TABLE application_identity_mappings; ALTER TABLE application_identity_mappings_next RENAME TO application_identity_mappings; COMMIT;"); const sessions = columns("application_sessions"); if (sessions.has("last_from") && !sessions.has("last_identity_key")) this.db.exec("ALTER TABLE application_sessions RENAME COLUMN last_from TO last_identity_key;"); if (!columns("application_sessions").has("session_type")) this.db.exec("ALTER TABLE application_sessions ADD COLUMN session_type TEXT NOT NULL DEFAULT 'stateful' CHECK(session_type IN ('stateful','stateless'));"); const state = columns("application_session_state"); if (!state.has("session_type")) this.db.exec("BEGIN; CREATE TABLE application_session_state_next (application_slug TEXT NOT NULL, profile TEXT NOT NULL, session_prefix TEXT NOT NULL, session_type TEXT NOT NULL DEFAULT 'stateful' CHECK(session_type IN ('stateful','stateless')), current_session_id TEXT NOT NULL, updated_at TEXT NOT NULL, reason TEXT NOT NULL, PRIMARY KEY(application_slug,profile,session_prefix,session_type)); INSERT INTO application_session_state_next (application_slug,profile,session_prefix,session_type,current_session_id,updated_at,reason) SELECT application_slug,profile,session_prefix,'stateful',current_session_id,updated_at,reason FROM application_session_state; DROP TABLE application_session_state; ALTER TABLE application_session_state_next RENAME TO application_session_state; COMMIT;"); }
   private value(row: Row): ApplicationRecord { return { id: String(row.id), name: String(row.name), slug: String(row.slug), enabled: Boolean(row.enabled), responseMode: row.response_mode as "ack" | "result", defaultProfile: row.default_profile == null ? null : String(row.default_profile), routingPolicy: row.routing_policy as "default_as_fallback" | "drop", settings: JSON.parse(String(row.settings_json)), createdAt: String(row.created_at), updatedAt: String(row.updated_at) }; }
   list() { return (this.db.prepare("SELECT * FROM applications ORDER BY name").all() as Row[]).map((row) => this.value(row)); } get(slug: string) { const row = this.db.prepare("SELECT * FROM applications WHERE slug=?").get(slug) as Row | undefined; return row ? this.value(row) : undefined; }
   create(input: Pick<ApplicationRecord, "name" | "slug" | "enabled" | "responseMode" | "defaultProfile" | "routingPolicy" | "settings">) { const timestamp = now(), record = { ...input, id: randomUUID(), createdAt: timestamp, updatedAt: timestamp }; this.db.prepare("INSERT INTO applications VALUES (?,?,?,?,?,?,?,?,?,?)").run(record.id, record.name, record.slug, record.enabled ? 1 : 0, record.responseMode, record.defaultProfile, record.routingPolicy, JSON.stringify(record.settings), timestamp, timestamp); return this.get(record.slug)!; }
   update(slug: string, input: Omit<ApplicationRecord, "id" | "slug" | "createdAt" | "updatedAt">) { const result = this.db.prepare("UPDATE applications SET name=?,enabled=?,response_mode=?,default_profile=?,routing_policy=?,settings_json=?,updated_at=? WHERE slug=?").run(input.name, input.enabled ? 1 : 0, input.responseMode, input.defaultProfile, input.routingPolicy, JSON.stringify(input.settings), now(), slug); if (!result.changes) throw new Error("Application not found."); return this.get(slug)!; }
   delete(slug: string) { if (!this.db.prepare("DELETE FROM applications WHERE slug=?").run(slug).changes) throw new Error("Application not found."); for (const table of ["application_sessions", "application_session_state", "application_identity_mappings", "application_automatic_prefixes", "application_console_sessions"]) this.db.prepare(`DELETE FROM ${table} WHERE application_slug=?`).run(slug); }
-  identityMapping(slug: string, identityKey: string) { const row = this.db.prepare("SELECT profile, session_mode, session_prefix FROM application_identity_mappings WHERE application_slug=? AND identity_key IN (?, '*') ORDER BY CASE identity_key WHEN '*' THEN 1 ELSE 0 END LIMIT 1").get(slug, identityKey) as Row | undefined; return row ? { profile: String(row.profile), sessionMode: String(row.session_mode) as "fixed" | "automatic", sessionPrefix: row.session_prefix == null ? null : String(row.session_prefix) } : undefined; }
-  identityMappings(slug: string) { return (this.db.prepare("SELECT id, identity_key, profile, session_mode, session_prefix, created_at, updated_at FROM application_identity_mappings WHERE application_slug=? ORDER BY identity_key='*', identity_key").all(slug) as Row[]).map((row) => ({ id: String(row.id), identityKey: String(row.identity_key), profile: String(row.profile), sessionMode: String(row.session_mode), sessionPrefix: row.session_prefix == null ? null : String(row.session_prefix), createdAt: String(row.created_at), updatedAt: String(row.updated_at) })); }
-  saveIdentityMapping(slug: string, identityKey: string, profile: string, sessionMode: "fixed" | "automatic", sessionPrefix: string | null) { const timestamp = now(), current = this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, identityKey) as Row | undefined; if (current) this.db.prepare("UPDATE application_identity_mappings SET profile=?,session_mode=?,session_prefix=?,updated_at=? WHERE id=?").run(profile, sessionMode, sessionPrefix, timestamp, current.id); else this.db.prepare("INSERT INTO application_identity_mappings VALUES (?,?,?,?,?,?,?,?)").run(randomUUID(), slug, identityKey, profile, sessionMode, sessionPrefix, timestamp, timestamp); return this.identityMapping(slug, identityKey)!; }
-  renameIdentityMapping(slug: string, previousIdentityKey: string, identityKey: string, profile: string, sessionMode: "fixed" | "automatic", sessionPrefix: string | null) { if (previousIdentityKey === identityKey) return this.saveIdentityMapping(slug, identityKey, profile, sessionMode, sessionPrefix); const current = this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, previousIdentityKey) as Row | undefined; if (!current) throw Object.assign(new Error("Identity mapping not found."), { status: 404 }); if (this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, identityKey)) throw Object.assign(new Error("An Identity Key mapping with this key already exists."), { status: 409 }); this.db.prepare("UPDATE application_identity_mappings SET identity_key=?,profile=?,session_mode=?,session_prefix=?,updated_at=? WHERE id=?").run(identityKey, profile, sessionMode, sessionPrefix, now(), current.id); return this.identityMapping(slug, identityKey)!; }
+  deleteProfile(profile: string) {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.prepare("DELETE FROM application_automatic_prefixes WHERE EXISTS (SELECT 1 FROM application_identity_mappings m WHERE m.profile=? AND m.application_slug=application_automatic_prefixes.application_slug AND m.identity_key=application_automatic_prefixes.identity_key)").run(profile);
+      this.db.prepare("DELETE FROM application_console_sessions WHERE profile=?").run(profile);
+      this.db.prepare("DELETE FROM application_session_state WHERE profile=?").run(profile);
+      this.db.prepare("DELETE FROM application_sessions WHERE profile=?").run(profile);
+      this.db.prepare("DELETE FROM application_identity_mappings WHERE profile=?").run(profile);
+      this.db.exec("COMMIT");
+    } catch (error) { this.db.exec("ROLLBACK"); throw error; }
+  }
+  identityMapping(slug: string, identityKey: string) { const row = this.db.prepare("SELECT profile, session_mode, session_prefix FROM application_identity_mappings WHERE application_slug=? AND identity_key IN (?, '*') ORDER BY CASE identity_key WHEN '*' THEN 1 ELSE 0 END LIMIT 1").get(slug, identityKey) as Row | undefined; return row ? { profile: row.profile == null ? null : String(row.profile), sessionMode: String(row.session_mode) as "fixed" | "automatic" | "ignore", sessionPrefix: row.session_prefix == null ? null : String(row.session_prefix) } : undefined; }
+  identityMappings(slug: string) { return (this.db.prepare("SELECT id, identity_key, profile, session_mode, session_prefix, created_at, updated_at FROM application_identity_mappings WHERE application_slug=? ORDER BY identity_key='*', identity_key").all(slug) as Row[]).map((row) => ({ id: String(row.id), identityKey: String(row.identity_key), profile: row.profile == null ? null : String(row.profile), sessionMode: String(row.session_mode), sessionPrefix: row.session_prefix == null ? null : String(row.session_prefix), createdAt: String(row.created_at), updatedAt: String(row.updated_at) })); }
+  saveIdentityMapping(slug: string, identityKey: string, profile: string | null, sessionMode: "fixed" | "automatic" | "ignore", sessionPrefix: string | null) { const timestamp = now(), current = this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, identityKey) as Row | undefined; if (current) this.db.prepare("UPDATE application_identity_mappings SET profile=?,session_mode=?,session_prefix=?,updated_at=? WHERE id=?").run(profile, sessionMode, sessionPrefix, timestamp, current.id); else this.db.prepare("INSERT INTO application_identity_mappings VALUES (?,?,?,?,?,?,?,?)").run(randomUUID(), slug, identityKey, profile, sessionMode, sessionPrefix, timestamp, timestamp); return this.identityMapping(slug, identityKey)!; }
+  renameIdentityMapping(slug: string, previousIdentityKey: string, identityKey: string, profile: string | null, sessionMode: "fixed" | "automatic" | "ignore", sessionPrefix: string | null) { if (previousIdentityKey === identityKey) return this.saveIdentityMapping(slug, identityKey, profile, sessionMode, sessionPrefix); const current = this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, previousIdentityKey) as Row | undefined; if (!current) throw Object.assign(new Error("Identity mapping not found."), { status: 404 }); if (this.db.prepare("SELECT id FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").get(slug, identityKey)) throw Object.assign(new Error("An Identity Key mapping with this key already exists."), { status: 409 }); this.db.prepare("UPDATE application_identity_mappings SET identity_key=?,profile=?,session_mode=?,session_prefix=?,updated_at=? WHERE id=?").run(identityKey, profile, sessionMode, sessionPrefix, now(), current.id); return this.identityMapping(slug, identityKey)!; }
   deleteIdentityMapping(slug: string, identityKey: string) { if (!this.db.prepare("DELETE FROM application_identity_mappings WHERE application_slug=? AND identity_key=?").run(slug, identityKey).changes) throw new Error("Identity mapping not found."); }
   automaticPrefix(slug: string, identityKey: string) { const existing = this.db.prepare("SELECT session_prefix FROM application_automatic_prefixes WHERE application_slug=? AND identity_key=?").get(slug, identityKey) as Row | undefined; if (existing) return String(existing.session_prefix); const normalized = identityKey.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9_-]+/g, "_").replace(/_+/g, "_").replace(/^[_-]+|[_-]+$/g, ""); const base = (normalized && /^[a-z]/.test(normalized) ? normalized : `id_${normalized || "identity"}`).slice(0, 63); let prefix = base; const collision = () => this.db.prepare("SELECT identity_key FROM application_automatic_prefixes WHERE application_slug=? AND session_prefix=?").get(slug, prefix) as Row | undefined; if (collision()) { const suffix = `--${createHash("sha256").update(identityKey).digest("hex").slice(0, 8)}`; prefix = `${base.slice(0, 63 - suffix.length)}${suffix}`; } this.db.prepare("INSERT INTO application_automatic_prefixes VALUES (?,?,?,?)").run(slug, identityKey, prefix, now()); return prefix; }
-  session(slug: string, profile: string, prefix: string) { const row = this.db.prepare("SELECT s.* FROM application_session_state st JOIN application_sessions s ON s.session_id=st.current_session_id WHERE st.application_slug=? AND st.profile=? AND st.session_prefix=?").get(slug, profile, prefix) as Row | undefined; return row ? this.sessionValue(row) : undefined; }
-  private sessionValue(row: Row) { return { application: String(row.application_slug), profile: String(row.profile), sessionPrefix: String(row.session_prefix), sessionId: String(row.session_id), sessionDate: String(row.session_date), sequence: Number(row.sequence), createdAt: String(row.created_at), updatedAt: String(row.updated_at), lastMessageAt: row.last_message_at == null ? null : String(row.last_message_at), messageCount: Number(row.message_count), createdFromRollover: Boolean(row.created_from_rollover), lastIdentityKey: row.last_identity_key == null ? null : String(row.last_identity_key) }; }
-  nextSessionId(slug: string, profile: string, prefix: string) { const date = new Date().toISOString().slice(0, 10), sequence = Number((this.db.prepare("SELECT COALESCE(MAX(sequence),0)+1 AS sequence FROM application_sessions WHERE application_slug=? AND profile=? AND session_prefix=? AND session_date=?").get(slug, profile, prefix, date) as Row).sequence); return `${slug}_${prefix}_${date}-${String(sequence).padStart(2, "0")}`; }
-  createSession(slug: string, profile: string, prefix: string, sessionId: string, rollover: boolean) { const date = new Date().toISOString().slice(0, 10), timestamp = now(), sequence = Number((this.db.prepare("SELECT COALESCE(MAX(sequence),0)+1 AS sequence FROM application_sessions WHERE application_slug=? AND profile=? AND session_prefix=? AND session_date=?").get(slug, profile, prefix, date) as Row).sequence); this.db.prepare("INSERT INTO application_sessions VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)").run(randomUUID(), slug, profile, prefix, sessionId, date, sequence, timestamp, timestamp, null, 0, rollover ? 1 : 0, null); this.db.prepare("INSERT INTO application_session_state VALUES (?,?,?,?,?,?) ON CONFLICT(application_slug,profile,session_prefix) DO UPDATE SET current_session_id=excluded.current_session_id,updated_at=excluded.updated_at,reason=excluded.reason").run(slug, profile, prefix, sessionId, timestamp, rollover ? "rollover" : "message"); return this.session(slug, profile, prefix)!; }
+  session(slug: string, profile: string, prefix: string, sessionType: "stateful" | "stateless" = "stateful") { const row = this.db.prepare("SELECT s.* FROM application_session_state st JOIN application_sessions s ON s.session_id=st.current_session_id WHERE st.application_slug=? AND st.profile=? AND st.session_prefix=? AND st.session_type=?").get(slug, profile, prefix, sessionType) as Row | undefined; return row ? this.sessionValue(row) : undefined; }
+  private sessionValue(row: Row) { return { application: String(row.application_slug), profile: String(row.profile), sessionPrefix: String(row.session_prefix), sessionId: String(row.session_id), sessionDate: String(row.session_date), sequence: Number(row.sequence), createdAt: String(row.created_at), updatedAt: String(row.updated_at), lastMessageAt: row.last_message_at == null ? null : String(row.last_message_at), messageCount: Number(row.message_count), createdFromRollover: Boolean(row.created_from_rollover), lastIdentityKey: row.last_identity_key == null ? null : String(row.last_identity_key), sessionType: String(row.session_type ?? "stateful") as "stateful" | "stateless" }; }
+  // Session IDs omit the profile name and are globally unique in SQLite, so
+  // their sequence must be shared by profiles that use the same Application/prefix.
+  nextSessionId(slug: string, profile: string, prefix: string) { void profile; const date = new Date().toISOString().slice(0, 10), sequence = Number((this.db.prepare("SELECT COALESCE(MAX(sequence),0)+1 AS sequence FROM application_sessions WHERE application_slug=? AND session_prefix=? AND session_date=?").get(slug, prefix, date) as Row).sequence); return `${slug}_${prefix}_${date}-${String(sequence).padStart(2, "0")}`; }
+  createSession(slug: string, profile: string, prefix: string, sessionId: string, rollover: boolean, sessionType: "stateful" | "stateless" = "stateful") { const date = new Date().toISOString().slice(0, 10), timestamp = now(); const existing = this.db.prepare("SELECT application_slug,profile,session_prefix,session_type FROM application_sessions WHERE session_id=?").get(sessionId) as Row | undefined; if (existing && (String(existing.application_slug) !== slug || String(existing.profile) !== profile || String(existing.session_prefix) !== prefix || String(existing.session_type ?? "stateful") !== sessionType)) throw Object.assign(new Error("sessionId is already associated with another Application route."), { status: 409 }); if (!existing) { const sequence = Number((this.db.prepare("SELECT COALESCE(MAX(sequence),0)+1 AS sequence FROM application_sessions WHERE application_slug=? AND session_prefix=? AND session_date=?").get(slug, prefix, date) as Row).sequence); this.db.prepare("INSERT INTO application_sessions VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)").run(randomUUID(), slug, profile, prefix, sessionId, date, sequence, timestamp, timestamp, null, 0, rollover ? 1 : 0, null, sessionType); } this.db.prepare("INSERT INTO application_session_state VALUES (?,?,?,?,?,?,?) ON CONFLICT(application_slug,profile,session_prefix,session_type) DO UPDATE SET current_session_id=excluded.current_session_id,updated_at=excluded.updated_at,reason=excluded.reason").run(slug, profile, prefix, sessionType, sessionId, timestamp, rollover ? "rollover" : "message"); return this.session(slug, profile, prefix, sessionType)!; }
   touchSession(slug: string, profile: string, prefix: string, sessionId: string, identityKey?: string) { const timestamp = now(); this.db.prepare("UPDATE application_sessions SET updated_at=?,last_message_at=?,message_count=message_count+1,last_identity_key=COALESCE(?,last_identity_key) WHERE application_slug=? AND profile=? AND session_prefix=? AND session_id=?").run(timestamp, timestamp, identityKey ?? null, slug, profile, prefix, sessionId); this.db.prepare("UPDATE application_session_state SET updated_at=?,reason='message' WHERE application_slug=? AND profile=? AND session_prefix=?").run(timestamp, slug, profile, prefix); }
   activeSession(slug: string, profile: string, prefix: string) { return this.session(slug, profile, prefix); }
   removeActiveSession(slug: string, profile: string, sessionId: string) { const session = this.db.prepare("SELECT session_prefix FROM application_sessions WHERE application_slug=? AND profile=? AND session_id=?").get(slug, profile, sessionId) as Row | undefined; if (!session) throw Object.assign(new Error("Application session not found."), { status: 404 }); if (!this.db.prepare("DELETE FROM application_session_state WHERE application_slug=? AND profile=? AND session_prefix=? AND current_session_id=?").run(slug, profile, String(session.session_prefix), sessionId).changes) throw Object.assign(new Error("Application session is no longer active."), { status: 409 }); }

package/extensions/api-server/index.ts

@@ -5,6 +5,8 @@ import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
+import { withoutTuiModeArgs } from "../lib/cli-tui-mode.ts";
+import { piCommand } from "../lib/pi-command.ts";
 
 type ApiSettings = { host?: string; port?: number; apiToken?: string; cors?: { origin?: string } };
 type LegacySettings = Record<string, unknown> & { api?: ApiSettings };
@@ -14,6 +16,7 @@ const configPath = () => join(agentDir(), "api-server.json");
 const legacySettingsPath = () => join(agentDir(), "settings.json");
 const statePath = () => join(agentDir(), "api-server.state.json");
 const logPath = () => join(agentDir(), "api-server.log");
+const persistentCommand = "dir=$(mktemp -d) || exit 1; fifo=$dir/stdin; mkfifo \"$fifo\" || { rmdir \"$dir\"; exit 1; }; cleanup() { kill \"$tail_pid\" 2>/dev/null || true; wait \"$tail_pid\" 2>/dev/null || true; rm -f \"$fifo\"; rmdir \"$dir\"; }; trap cleanup EXIT HUP INT TERM; tail -f /dev/null >\"$fifo\" & tail_pid=$!; \"$@\" <\"$fifo\"; exit $?";
 
 async function readJson<T>(path: string): Promise<T | undefined> { try { return JSON.parse(await readFile(path, "utf8")) as T; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw new Error(`could not read ${path}: ${error instanceof Error ? error.message : String(error)}`); } }
 async function writeJson(path: string, value: unknown) { await mkdir(agentDir(), { recursive: true }); await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8"); }
@@ -42,11 +45,12 @@ async function start() {
   const api = await getApiSettings(); await clearStaleState(); const current = await readState();
   if (current && isAlive(current.pid)) return console.log(`API is already running (PID ${current.pid}) at http://${current.host}:${current.port}`);
   const fd = openSync(logPath(), "a");
-  const child = spawn("sh", ["-c", "tail -f /dev/null | \"$@\"", "pi-api-worker", process.execPath, process.argv[1], "--mode", "rpc", "--no-session"], { cwd: process.cwd(), detached: true, stdio: ["ignore", fd, fd], env: { ...process.env, PI_API_WORKER: "1" } });
+  const pi = piCommand();
+  const child = spawn("sh", ["-c", persistentCommand, "pi-api-worker", pi.command, ...pi.args, "--mode", "rpc", "--no-session"], { cwd: process.cwd(), detached: true, stdio: ["ignore", fd, fd], env: { ...process.env, PI_API_WORKER: "1" } });
   child.unref(); await writeJson(statePath(), { pid: child.pid!, host: api.host, port: api.port, startedAt: new Date().toISOString() });
   console.log(`API started at http://${api.host}:${api.port} (PID ${child.pid}).`); console.log(`The token is stored in ${configPath()}.`);
 }
 async function stop() { const state = await readState(); if (!state || !isAlive(state.pid)) { await unlink(statePath()).catch(() => {}); return console.log("API is not running."); } try { process.kill(-state.pid, "SIGTERM"); } catch { process.kill(state.pid, "SIGTERM"); } for (let i = 0; i < 30 && isAlive(state.pid); i++) await new Promise((resolve) => setTimeout(resolve, 100)); if (isAlive(state.pid)) { try { process.kill(-state.pid, "SIGKILL"); } catch { process.kill(state.pid, "SIGKILL"); } } await unlink(statePath()).catch(() => {}); console.log("API stopped."); }
 async function status() { await clearStaleState(); const state = await readState(); console.log(!state || !isAlive(state.pid) ? "API: stopped" : `API: running (PID ${state.pid}) at http://${state.host}:${state.port}`); }
-async function handleCliCommand(): Promise<boolean> { const args = process.argv.slice(2); if (args[0] !== "api" || process.env.PI_API_WORKER === "1") return false; switch (args[1]) { case "start": await start(); break; case "stop": await stop(); break; case "status": await status(); break; case "restart": await stop(); await start(); break; default: console.error("Usage: pi api start | stop | restart | status"); process.exitCode = 1; } return true; }
+async function handleCliCommand(): Promise<boolean> { const args = withoutTuiModeArgs(process.argv.slice(2)); if (args[0] !== "api" || process.env.PI_API_WORKER === "1") return false; switch (args[1]) { case "start": await start(); break; case "stop": await stop(); break; case "status": await status(); break; case "restart": await stop(); await start(); break; default: console.error("Usage: pi api start | stop | restart | status"); process.exitCode = 1; } return true; }
 export default async function (pi: ExtensionAPI) { if (await handleCliCommand()) process.exit(); if (process.env.PI_API_WORKER !== "1") return; pi.on("session_start", async () => { const { startApiServer } = await import("./server.ts"); await startApiServer({ agentDir: agentDir(), cwd: process.cwd() }); }); }