pi-feats 0.1.5 → 0.1.7

package/README.md

@@ -128,6 +128,13 @@ 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, 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.
 
@@ -145,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
@@ -179,7 +210,7 @@ curl \
 
 What the API exposes:
 
-- Persistent chat and streaming chat sessions, including profile-specific 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.
@@ -191,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
@@ -293,7 +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.
-- Set `insertIntoApiSession: true` when a Pulse result should also be recorded in every active Application session for the same profile. This adds context only: it does not invoke an outbound handler or send a message through an Application channel.
+- 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:
 
@@ -342,6 +373,8 @@ Context Memory keeps compact, durable facts separate from a session transcript a
 
 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
@@ -392,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
@@ -536,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
 
@@ -561,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-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 | null; sessionMode: "fixed" | "automatic" | "ignore"; 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 };
@@ -243,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) 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() : 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;
@@ -278,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,8 +6,8 @@ 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, 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;"); }
+  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)!; }
@@ -30,12 +30,12 @@ export class ApplicationStore {
   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) }; }
+  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) { 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 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); 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)!; }
+  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() }); }); }

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

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
-import { copyFile, mkdir, readFile, readlink, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile, readlink, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { ensureProfileSandbox } from "../lib/profile-sandbox.ts";
 import { BUILTIN_TOOLS, activeBuiltinTools, updatedBuiltinTools } from "../lib/builtin-tools.ts";
+import { packageExtensions } from "../lib/package-resources.ts";
 
 export { BUILTIN_TOOLS } from "../lib/builtin-tools.ts";
 export const RESOURCE_KINDS = ["tools", "skills", "extensions"] as const;
@@ -10,12 +11,24 @@ export type ResourceKind = typeof RESOURCE_KINDS[number];
 type PolicyKey = "enabledTools" | "enabledSkills" | "enabledProfileSkills" | "enabledExtensions";
 type SkillSources = { shared?: boolean; profile?: boolean };
 type SkillResourceSource = "shared" | "profile" | "package";
-type ProfilePolicy = Partial<Record<PolicyKey, string[]>> & { skillSources?: SkillSources; contextMemory?: { mode: "file"; target: "profile" | "identity" } | { mode: "handler"; handler: string } };
+export type ProfileMetadata = { description: string; tags: string[] };
+type ProfilePolicy = Partial<Record<PolicyKey, string[]>> & Partial<ProfileMetadata> & { skillSources?: SkillSources; contextMemory?: { mode: "file"; target: "profile" | "identity" } | { mode: "handler"; handler: string } };
 export type ProfileSettings = Record<string, unknown> & { profile?: ProfilePolicy; sandbox?: boolean };
 export type Resource = { name: string; kind: ResourceKind; path?: string; source: "builtin" | "shared" | "profile" | "extension" | "package"; package?: string; enabled: boolean; protected?: boolean };
 export type Package = { name: string; version?: string; description?: string; enabled: boolean; installed: boolean };
 
 const validName = (name: string) => /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name);
+const maxProfileDescriptionLength = 500;
+const maxProfileTags = 20;
+const maxProfileTagLength = 50;
+const profileMetadata = (value: unknown): ProfileMetadata => {
+  const input = value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+  if (input.description !== undefined && (typeof input.description !== "string" || input.description.length > maxProfileDescriptionLength)) throw Object.assign(new Error(`description must be a string of at most ${maxProfileDescriptionLength} characters.`), { status: 400 });
+  if (input.tags !== undefined && (!Array.isArray(input.tags) || input.tags.some((tag) => typeof tag !== "string"))) throw Object.assign(new Error("tags must be an array of strings."), { status: 400 });
+  const tags = [...new Map((input.tags as string[] | undefined ?? []).map((tag) => tag.trim()).filter(Boolean).map((tag) => [tag.toLocaleLowerCase(), tag])).values()];
+  if (tags.length > maxProfileTags || tags.some((tag) => tag.length > maxProfileTagLength)) throw Object.assign(new Error(`Use at most ${maxProfileTags} tags of at most ${maxProfileTagLength} characters.`), { status: 400 });
+  return { description: (input.description as string | undefined ?? "").trim(), tags };
+};
 const policyKey: Record<ResourceKind, PolicyKey> = {
   tools: "enabledTools",
   skills: "enabledSkills",
@@ -80,14 +93,13 @@ export class ProfileStore {
     }
   }
 
-  async list(): Promise<Array<{ name: string; path: string }>> {
-    const profiles = [{ name: "default", path: this.agentDir }];
-    if (!existsSync(this.profilesDir())) return profiles;
-    for (const entry of await readdir(this.profilesDir(), { withFileTypes: true })) {
-      if (entry.isDirectory() && existsSync(join(this.profilesDir(), entry.name, "settings.json"))) {
-        profiles.push({ name: entry.name, path: this.directory(entry.name) });
-      }
-    }
+  async list(): Promise<Array<{ name: string; path: string } & ProfileMetadata>> {
+    const names = ["default"];
+    if (existsSync(this.profilesDir())) for (const entry of await readdir(this.profilesDir(), { withFileTypes: true })) if (entry.isDirectory() && existsSync(join(this.profilesDir(), entry.name, "settings.json"))) names.push(entry.name);
+    const profiles = await Promise.all(names.map(async (name) => {
+      const settings = await this.readSettings(name);
+      return { name, path: this.directory(name), ...profileMetadata(settings.profile) };
+    }));
     return profiles.sort((a, b) => a.name.localeCompare(b.name));
   }
 
@@ -183,11 +195,7 @@ export class ProfileStore {
   }
 
   private async packageExtensions(settings: ProfileSettings): Promise<Array<{ name: string; path: string; package: string }>> {
-    const entries: Array<{ name: string; path: string; package: string }> = [];
-    for (const pkg of await this.configuredPackages(settings)) {
-      for (const extension of Array.isArray(pkg.manifest?.pi?.extensions) ? pkg.manifest.pi.extensions : []) if (typeof extension === "string") entries.push({ name: extension.split("/").pop()?.replace(/\.(?:ts|js)$/, "") ?? pkg.name, path: join(pkg.base, extension), package: pkg.name });
-    }
-    return entries;
+    return packageExtensions(await this.configuredPackages(settings)).map(({ name, path, packageName }) => ({ name, path, package: packageName }));
   }
 
   private async packageToolSources(settings: ProfileSettings, names: Iterable<string>): Promise<Map<string, string>> {
@@ -323,28 +331,67 @@ export class ProfileStore {
     await this.refreshSkills(profile);
   }
 
-  async create(name: string): Promise<{ name: string; path: string }> {
+  async create(name: string, metadata: unknown = {}, cloneFrom?: string): Promise<{ name: string; path: string } & ProfileMetadata> {
     if (!validName(name) || name === "default") throw Object.assign(new Error("Invalid profile name"), { status: 400 });
     const destination = this.directory(name);
     if (existsSync(destination)) throw Object.assign(new Error("Profile already exists"), { status: 409 });
-    await mkdir(join(destination, "sessions"), { recursive: true });
-    let base: ProfileSettings = {};
-    try { base = await this.readSettings("default"); } catch {}
-    const { packages: _packages, extensions: _extensions, ...profileBase } = base;
-    const settings: ProfileSettings = {
-      ...profileBase,
-      defaultTools: BUILTIN_TOOLS,
-      sandbox: true,
-      profile: { enabledTools: ["*"], enabledSkills: ["*"], enabledProfileSkills: ["*"], skillSources: { shared: true, profile: false } },
-    };
-    await this.writeSettings(name, settings);
-    await ensureProfileSandbox(destination, resolve(process.argv[1]));
-    await writeFile(join(destination, "SOUL.md"), "", "utf8");
-    await writeFile(join(destination, "guardrails.json"), "{\n  \"guardrails\": []\n}\n", "utf8");
-    const auth = join(this.agentDir, "auth.json");
-    if (existsSync(auth)) await copyFile(auth, join(destination, "auth.json"));
-    await this.linkSharedModels(name);
-    return { name, path: destination };
+    const details = profileMetadata(metadata);
+    if (cloneFrom !== undefined && (typeof cloneFrom !== "string" || !validName(cloneFrom) || cloneFrom === "default")) throw Object.assign(new Error("Clone source must be an existing named profile."), { status: 400 });
+
+    let sourceSettings: ProfileSettings | undefined;
+    let sourceDirectory: string | undefined;
+    if (cloneFrom) {
+      sourceSettings = await this.readSettings(cloneFrom);
+      sourceDirectory = this.directory(cloneFrom);
+    }
+
+    try {
+      await mkdir(join(destination, "sessions"), { recursive: true });
+      let settings: ProfileSettings;
+      if (sourceSettings && sourceDirectory) {
+        const sourceSkills = join(sourceDirectory, "skills");
+        if (existsSync(sourceSkills)) await cp(sourceSkills, join(destination, "skills"), { recursive: true, force: false });
+        for (const file of ["SOUL.md", "REFINE.md", "guardrails.json", ".env", "auth.json"]) {
+          const source = join(sourceDirectory, file);
+          if (existsSync(source)) await copyFile(source, join(destination, file));
+        }
+        settings = {
+          ...sourceSettings,
+          sandbox: true,
+          profile: { ...(sourceSettings.profile ?? {}), ...details },
+        };
+      } else {
+        let base: ProfileSettings = {};
+        try { base = await this.readSettings("default"); } catch {}
+        const { packages: _packages, extensions: _extensions, ...profileBase } = base;
+        settings = {
+          ...profileBase,
+          defaultTools: BUILTIN_TOOLS,
+          sandbox: true,
+          profile: { enabledTools: ["*"], enabledSkills: ["*"], enabledProfileSkills: ["*"], skillSources: { shared: true, profile: false }, ...details },
+        };
+      }
+      await this.writeSettings(name, settings);
+      await ensureProfileSandbox(destination, resolve(process.argv[1]));
+      if (!sourceSettings) {
+        await writeFile(join(destination, "SOUL.md"), "", "utf8");
+        await writeFile(join(destination, "guardrails.json"), "{\n  \"guardrails\": []\n}\n", "utf8");
+        const auth = join(this.agentDir, "auth.json");
+        if (existsSync(auth)) await copyFile(auth, join(destination, "auth.json"));
+      }
+      await this.linkSharedModels(name);
+      return { name, path: destination, ...details };
+    } catch (error) {
+      await rm(destination, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
+  async updateMetadata(name: string, metadata: unknown): Promise<{ name: string; path: string } & ProfileMetadata> {
+    const details = profileMetadata(metadata);
+    const settings = await this.readSettings(name);
+    await this.writeSettings(name, { ...settings, profile: { ...(settings.profile ?? {}), ...details } });
+    return { name, path: this.directory(name), ...details };
   }
 
   async delete(name: string): Promise<void> {