pi-feats 0.1.5 → 0.1.7

package/extensions/api-server/server.ts

@@ -22,6 +22,7 @@ import { applicationExecutionContext, type ContextMemoryExecutionLog } from "../
 import { contextMemoryCharacters, contextMemoryConfig, contextMemoryLimit, memoryPath, readMemory } from "../lib/context-memory.ts";
 import { isSandboxEnabled } from "../lib/profile-sandbox.ts";
 import { handlerEnvironment, HOST_SSH_CREDENTIAL_KEYS, parseProfileEnv, profileEnvironment } from "../lib/profile-env.ts";
+import { piCommand } from "../lib/pi-command.ts";
 import { PulseStore } from "../pulse/store.ts";
 import { SkillSourceStore } from "../skill-sources/store.ts";
 
@@ -38,6 +39,7 @@ type ChatBody = { message: string };
 type ChatParams = { profile?: string; sessionId: string };
 
 const MAX_BODY_BYTES = 1_048_576;
+const MAX_APPLICATION_BODY_BYTES = 200 * 1024 * 1024;
 let serverPromise: Promise<FastifyInstance> | undefined;
 // Some third-party extensions read PI_CODING_AGENT_DIR while loading.
 // Only bootstrap is serialized so each runtime captures its own profile.
@@ -79,12 +81,32 @@ function objectBody(input: unknown): Record<string, unknown> {
   return input as Record<string, unknown>;
 }
 
+async function hasOpenRouterCredential(directory: string, environment: NodeJS.ProcessEnv): Promise<boolean> {
+  if (environment.OPENROUTER_API_KEY?.trim()) return true;
+  try {
+    const auth: unknown = JSON.parse(await readFile(join(directory, "auth.json"), "utf8"));
+    return !!auth && typeof auth === "object" && !Array.isArray(auth) && typeof (auth as { openrouter?: { key?: unknown } }).openrouter?.key === "string" && !!(auth as { openrouter: { key: string } }).openrouter.key.trim();
+  } catch { return false; }
+}
+
 function resourceKind(value: string): ResourceKind {
   if (!(RESOURCE_KINDS as readonly string[]).includes(value)) throw Object.assign(new Error("Unknown resource type."), { status: 404 });
   return value as ResourceKind;
 }
 function skillSourceIdentifier(value: string): string { return value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^[^a-z]+/, "").replace(/^-+|-+$/g, "").slice(0, 64).replace(/-+$/g, ""); }
 
+function activityFromAgentEvent(event: Record<string, any>): Record<string, unknown> | undefined {
+  if (event.type === "tool_execution_start") return { id: String(event.toolCallId), kind: "tool", status: "started", name: String(event.toolName), parentToolCallId: event.parentToolCallId, summary: `Running ${String(event.toolName)}…` };
+  if (event.type === "tool_execution_update") return { id: String(event.toolCallId), kind: "tool", status: "running", name: String(event.toolName), parentToolCallId: event.parentToolCallId, summary: `Running ${String(event.toolName)}…` };
+  if (event.type === "tool_execution_end") return { id: String(event.toolCallId), kind: "tool", status: event.isError ? "failed" : "completed", name: String(event.toolName), parentToolCallId: event.parentToolCallId, summary: event.isError ? `${String(event.toolName)} failed.` : `${String(event.toolName)} completed.` };
+  if (event.type === "agent_start") return { id: "agent", kind: "agent", status: "running", name: "Pi", summary: "Pi is working…" };
+  if (event.type === "agent_settled") return { id: "agent", kind: "agent", status: "completed", name: "Pi", summary: "Pi completed its work." };
+  const update = event.type === "message_update" ? event.assistantMessageEvent as Record<string, unknown> | undefined : undefined;
+  if (update?.type === "thinking_start" || update?.type === "thinking_delta") return { id: `thinking-${String(update.contentIndex ?? 0)}`, kind: "thinking", status: "running", name: "Thinking", summary: "Pi is thinking…" };
+  if (update?.type === "thinking_end") return { id: `thinking-${String(update.contentIndex ?? 0)}`, kind: "thinking", status: "completed", name: "Thinking", summary: "Pi finished thinking." };
+  return undefined;
+}
+
 function textFromMessage(message: unknown): string {
   const content = (message as { content?: unknown })?.content;
   if (typeof content === "string") return content;
@@ -150,10 +172,10 @@ class ApiServer {
 
   async getIdentityMapping(application: string, identityKey: string) { return this.applications.identityMapping(application, identityKey); }
   async automaticApplicationSessionPrefix(application: string, identityKey: string) { return this.applications.automaticPrefix(application, identityKey); }
-  async getApplicationSession(application: string, profile: string, prefix: string) { return this.applications.session(application, profile, prefix); }
+  async getApplicationSession(application: string, profile: string, prefix: string, sessionType: "stateful" | "stateless" = "stateful") { return this.applications.session(application, profile, prefix, sessionType); }
   async getActiveApplicationSession(application: string, profile: string, prefix: string) { return this.applications.activeSession(application, profile, prefix); }
   async nextApplicationSessionId(application: string, profile: string, prefix: string) { return this.applications.nextSessionId(application, profile, prefix); }
-  async recordApplicationSession(application: string, profile: string, prefix: string, sessionId: string, rollover: boolean) { this.applications.createSession(application, profile, prefix, sessionId, rollover); }
+  async recordApplicationSession(application: string, profile: string, prefix: string, sessionId: string, rollover: boolean, sessionType: "stateful" | "stateless" = "stateful") { this.applications.createSession(application, profile, prefix, sessionId, rollover, sessionType); }
   async touchApplicationSession(application: string, profile: string, prefix: string, sessionId: string, identityKey?: string) { this.applications.touchSession(application, profile, prefix, sessionId, identityKey); }
   async getApplicationWorkingSessions(profile: string, application: string) { return this.profiles.readApplicationWorkingSessions(profile, application); }
   async setApplicationWorkingSession(profile: string, application: string, key: string, session: { sessionId: string; updatedAt: string; reason: "message" | "rollover" }): Promise<void> { await this.profiles.setApplicationWorkingSession(profile, application, key, session); }
@@ -200,6 +222,12 @@ class ApiServer {
     return SessionManager.listAll(sessionDir);
   }
 
+  private isPulseOnlySession(profile: string, session: { path: string; cwd: string }): boolean {
+    const entries = SessionManager.open(session.path, this.sessionDirectory(profile), session.cwd).getBranch() as Array<{ type?: string }>;
+    const relevant = entries.filter((entry) => entry.type !== "session_info");
+    return relevant.length > 0 && relevant.some((entry) => entry.type === "pulse") && relevant.every((entry) => entry.type === "pulse");
+  }
+
   async deleteProfile(profile: string): Promise<void> {
     if (profile === "default") throw Object.assign(new Error("The default profile cannot be deleted"), { status: 400 });
     await this.profiles.readSettings(profile);
@@ -214,18 +242,26 @@ class ApiServer {
     this.pulses.deleteProfile(profile);
   }
 
-  async listSessions(profile: string): Promise<Array<Record<string, unknown>>> {
+  async listSessions(profile: string, includePulseSessions = false): Promise<Array<Record<string, unknown>>> {
     await this.profiles.readSettings(profile);
+    const pulseExecutions = this.pulses.executionSessions(profile);
     const sessions = await this.listProfileSessions(profile);
-    return sessions.map((session) => ({
-      id: session.id,
-      name: session.name,
-      cwd: session.cwd,
-      createdAt: session.created.toISOString(),
-      updatedAt: session.modified.toISOString(),
-      messageCount: session.messageCount,
-      preview: session.firstMessage,
-    }));
+    return sessions.flatMap((session) => {
+      const execution = pulseExecutions.get(session.id), pulseOnly = !execution && this.isPulseOnlySession(profile, session);
+      if (!includePulseSessions && (execution || pulseOnly)) return [];
+      const pulse = execution ? { id: execution.pulseId, name: execution.pulseName, type: execution.pulseType, runId: execution.runId, status: execution.status, startedAt: execution.startedAt, finishedAt: execution.finishedAt, source: "execution" } : pulseOnly ? { source: "injected-result" } : undefined;
+      return [{
+        id: session.id,
+        name: session.name,
+        cwd: session.cwd,
+        createdAt: session.created.toISOString(),
+        updatedAt: session.modified.toISOString(),
+        messageCount: session.messageCount,
+        preview: session.firstMessage,
+        kind: execution ? "pulse-execution" : pulseOnly ? "pulse-only" : "conversation",
+        ...(pulse ? { pulse } : {}),
+      }];
+    });
   }
 
   async createSession(profile: string, input: unknown): Promise<Record<string, unknown>> {
@@ -297,6 +333,8 @@ class ApiServer {
     const info = sessions.find((session) => session.id === id);
     if (!info) throw Object.assign(new Error("Session not found"), { status: 404 });
     const session = SessionManager.open(info.path, this.sessionDirectory(profile), this.options.cwd);
+    // System prompt entries and empty assistant messages are session internals,
+    // not conversation content. Neither must become an empty chat bubble.
     const entries = session.getBranch().filter((entry) => entry.type !== "session_info").map((entry) => {
       if (entry.type === "message") {
         const message = entry.message as { role?: string; content?: unknown; toolName?: string; isError?: boolean; timestamp?: number };
@@ -310,7 +348,7 @@ class ApiServer {
       }
       if (entry.type === "compaction" || entry.type === "branch_summary") return { id: entry.id, type: entry.type, timestamp: entry.timestamp, summary: (entry as any).summary };
       return { id: entry.id, type: entry.type, timestamp: entry.timestamp };
-    });
+    }).filter((entry: any) => entry.type !== "message" || (entry.role !== "system" && (entry.role !== "assistant" || entry.content.some((block: { text?: unknown }) => typeof block.text === "string" && block.text.trim().length > 0) || entry.tools.length > 0 || !!entry.toolName)));
     const limit = Math.max(1, Math.min(16, Math.floor(requestedLimit) || 16));
     const end = before ? entries.findIndex((entry) => entry.id === before) : entries.length;
     if (before && end < 0) throw Object.assign(new Error("Conversation cursor not found."), { status: 400 });
@@ -323,7 +361,8 @@ class ApiServer {
     const environment = { ...(await profileEnvironment(agentDir)), PI_PROFILE_ROOT: this.options.agentDir, PI_PROFILE_DISCOVER_TOOLS: "1" };
     const output = await new Promise<{ stdout: string; stderr: string }>((resolveRun, reject) => {
       delete environment.PI_API_WORKER;
-      const child = spawn(process.execPath, [process.argv[1], "profile", profile, "--no-session", "--print", ""], {
+      const pi = piCommand();
+      const child = spawn(pi.command, [...pi.args, "profile", profile, "--no-session", "--print", ""], {
         cwd: agentDir,
         env: environment,
         stdio: ["ignore", "pipe", "pipe"],
@@ -349,7 +388,8 @@ class ApiServer {
       const environment = { ...(await profileEnvironment(agentDir)), PI_PROFILE_ROOT: this.options.agentDir };
       delete environment.PI_API_WORKER;
       return new Promise<string>((resolveRun, reject) => {
-        const child = spawn(process.execPath, [process.argv[1], "profile", profile, "--no-session", "--print", prompt], { cwd: agentDir, env: environment, stdio: ["ignore", "pipe", "pipe"] });
+        const pi = piCommand();
+        const child = spawn(pi.command, [...pi.args, "profile", profile, "--no-session", "--print", prompt], { cwd: agentDir, env: environment, stdio: ["ignore", "pipe", "pipe"] });
         let stdout = "", stderr = "";
         child.stdout.on("data", (chunk) => { stdout += String(chunk); }); child.stderr.on("data", (chunk) => { stderr += String(chunk); });
         child.once("error", reject); child.once("exit", (code) => code === 0 ? resolveRun(stdout.trim()) : reject(new Error(stderr.trim() || `Handoff completion exited with ${code ?? "unknown"}`)));
@@ -364,6 +404,20 @@ class ApiServer {
     });
   }
 
+  async promptStateless(profile: string, id: string, history: Array<{ role: "user" | "assistant"; content: string }>, message: string, applicationContext?: { application: string; identityKey: string; directContextMemory?: string }): Promise<{ profile: string; sessionId: string; response: string }> {
+    if (await this.sandboxed(profile)) throw Object.assign(new Error("Stateless sessions are not yet available for sandboxed profiles."), { status: 501 });
+    const agentDir = this.profileDirectory(profile); await this.profiles.readSettings(profile);
+    return this.withProfileEnvironment(agentDir, async () => {
+      const settingsManager = SettingsManager.create(this.options.cwd, agentDir); const loader = new DefaultResourceLoader({ cwd: this.options.cwd, agentDir, settingsManager }); await loader.reload();
+      let runtime = this.runtimes.get(agentDir); if (!runtime) { runtime = ModelRuntime.create({ authPath: join(agentDir, "auth.json"), modelsPath: join(agentDir, "models.json") }); this.runtimes.set(agentDir, runtime); }
+      const manager = SessionManager.inMemory(this.options.cwd);
+      for (const item of history) { const timestamp = Date.now(); if (item.role === "user") manager.appendMessage({ role: "user", content: item.content, timestamp }); else manager.appendMessage({ role: "assistant", content: [{ type: "text", text: item.content }], api: "openai-completions", provider: "external-history", model: "external-history", usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, stopReason: "stop", timestamp } as any); }
+      const { session } = await createAgentSession({ cwd: this.options.cwd, agentDir, sessionManager: manager, settingsManager, resourceLoader: loader, modelRuntime: await runtime });
+      let response = ""; const unsubscribe = session.subscribe((event) => { if (event.type === "message_end" && event.message.role === "assistant") response = textFromMessage(event.message); });
+      try { const run = () => session.prompt(message, { source: "rpc" }); if (applicationContext) await applicationExecutionContext.run({ ...applicationContext, profile, sessionId: id, onContextMemoryExecution: (execution) => this.recordContextMemoryExecution(applicationContext.application, profile, applicationContext.identityKey, id, execution) }, run); else await run(); response ||= session.getLastAssistantText() ?? ""; if (!response) throw Object.assign(new Error("Pi completed without an assistant response."), { status: 502, code: "STATELESS_RESPONSE_MISSING", stage: "response_extraction" }); return { profile, sessionId: id, response }; } finally { unsubscribe(); session.dispose(); }
+    });
+  }
+
   async discoverExtensionTools(profile: string): Promise<void> {
     const existing = this.toolDiscoveries.get(profile);
     if (existing) return existing;
@@ -422,29 +476,42 @@ class ApiServer {
     return isSandboxEnabled(this.profileDirectory(profile), profile === "default");
   }
 
-  private async runSandboxedPrompt(profile: string, id: string, message: string, onData?: (text: string) => void, handoff?: string, applicationContext?: { application: string; identityKey: string }): Promise<string> {
+  private async runSandboxedPrompt(profile: string, id: string, message: string, onData?: (text: string) => void, handoff?: string, applicationContext?: { application: string; identityKey: string; directContextMemory?: string }, onEvent?: (event: Record<string, unknown>) => void): Promise<string> {
     const key = `${profile}:${id}`;
     if (this.sandboxBusy.has(key)) throw Object.assign(new Error("The session is already processing a request."), { status: 409 });
     this.sandboxBusy.add(key);
     try {
       const session = (await this.listProfileSessions(profile)).find((item) => item.id === id);
       if (!session) throw Object.assign(new Error(`No session found matching '${id}'`), { status: 404 });
-      const workerEnv: NodeJS.ProcessEnv = { ...(await profileEnvironment(this.profileDirectory(profile))), PI_PROFILE_ROOT: this.options.agentDir, ...(handoff ? { PI_APPLICATION_HANDOFF: handoff } : {}), ...(applicationContext ? { PI_APPLICATION_IDENTITY_KEY: applicationContext.identityKey, PI_APPLICATION_SLUG: applicationContext.application, PI_APPLICATION_SESSION_ID: id } : {}) };
+      const workerEnv: NodeJS.ProcessEnv = { ...(await profileEnvironment(this.profileDirectory(profile))), PI_PROFILE_ROOT: this.options.agentDir, ...(handoff ? { PI_APPLICATION_HANDOFF: handoff } : {}), ...(applicationContext ? { PI_APPLICATION_IDENTITY_KEY: applicationContext.identityKey, PI_APPLICATION_SLUG: applicationContext.application, PI_APPLICATION_SESSION_ID: id, ...(applicationContext.directContextMemory !== undefined ? { PI_APPLICATION_DIRECT_CONTEXT_MEMORY: Buffer.from(applicationContext.directContextMemory, "utf8").toString("base64url") } : {}) } : {}) };
       // The HTTP gateway is an API worker itself. Its children are agent
       // runtimes, not additional HTTP servers.
       delete workerEnv.PI_API_WORKER;
       const result = await new Promise<{ stdout: string; stderr: string; code: number }>((resolveRun, reject) => {
         // Supply the native file path, not only its ID. The session manager
         // otherwise scopes an ID lookup to the API worker CWD (`/` in Docker).
-        const child = spawn(process.execPath, [process.argv[1], "profile", profile, "--session", session.path, "--print", message], {
+        const pi = piCommand();
+        const child = spawn(pi.command, [...pi.args, "profile", profile, "--session", session.path, ...(onEvent ? ["--mode", "json"] : ["--print"]), message], {
           // The sandboxed agent sees its profile directory as CWD, never the
           // HTTP server's CWD or the caller's project directory.
-          cwd: this.profileDirectory(profile),
-          env: workerEnv,
-          stdio: ["ignore", "pipe", "pipe"],
+          cwd: this.profileDirectory(profile), env: workerEnv, stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = ""; let stderr = ""; let jsonBuffer = ""; let finalResponse = "";
+        child.stdout.on("data", (chunk) => {
+          const text = String(chunk);
+          if (!onEvent) { stdout += text; onData?.(text); return; }
+          jsonBuffer += text;
+          const lines = jsonBuffer.split("\n"); jsonBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const event = JSON.parse(line) as Record<string, unknown>; onEvent(event);
+              if (event.type === "message_update") { const update = event.assistantMessageEvent as Record<string, unknown> | undefined; if (update?.type === "text_delta" && typeof update.delta === "string") onData?.(update.delta); }
+              if (event.type === "message_end" && (event.message as Record<string, unknown> | undefined)?.role === "assistant") finalResponse = textFromMessage(event.message);
+            } catch { stderr += `Invalid JSON event from sandboxed Pi: ${line}\n`; }
+          }
+          stdout = finalResponse;
         });
-        let stdout = ""; let stderr = "";
-        child.stdout.on("data", (chunk) => { const text = String(chunk); stdout += text; onData?.(text); });
         child.stderr.on("data", (chunk) => { stderr += String(chunk); });
         child.once("error", reject);
         child.once("exit", (code) => resolveRun({ stdout, stderr, code: code ?? 1 }));
@@ -462,7 +529,7 @@ class ApiServer {
     } finally { this.sandboxBusy.delete(key); }
   }
 
-  async prompt(profile: string, id: string, message: string, handoff?: string, applicationContext?: { application: string; identityKey: string }): Promise<{ profile: string; sessionId: string; response: string }> {
+  async prompt(profile: string, id: string, message: string, handoff?: string, applicationContext?: { application: string; identityKey: string; directContextMemory?: string }): Promise<{ profile: string; sessionId: string; response: string }> {
     if (await this.sandboxed(profile)) return { profile, sessionId: id, response: await this.runSandboxedPrompt(profile, id, message, undefined, handoff, applicationContext) };
     const handle = await this.getSession(profile, id);
     if (handle.busy || !handle.session.isIdle) throw Object.assign(new Error("The session is already processing a request."), { status: 409 });
@@ -485,7 +552,7 @@ class ApiServer {
       reply.raw.writeHead(200, { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache, no-transform", connection: "keep-alive", "x-accel-buffering": "no" });
       reply.raw.write(`event: session\ndata: ${JSON.stringify({ profile, sessionId: id })}\n\n`);
       try {
-        const response = await this.runSandboxedPrompt(profile, id, message, (text) => reply.raw.write(`event: token\ndata: ${JSON.stringify({ text })}\n\n`), undefined, applicationContext);
+        const response = await this.runSandboxedPrompt(profile, id, message, (text) => reply.raw.write(`event: token\ndata: ${JSON.stringify({ text })}\n\n`), undefined, applicationContext, (event) => { const activity = activityFromAgentEvent(event); if (activity) reply.raw.write(`event: activity\ndata: ${JSON.stringify(activity)}\n\n`); });
         reply.raw.write(`event: done\ndata: ${JSON.stringify({ response, sessionId: id, profile })}\n\n`);
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -513,9 +580,10 @@ class ApiServer {
         });
         response.write(`event: session\ndata: ${JSON.stringify({ profile, sessionId: id })}\n\n`);
         unsubscribe = handle.session.subscribe((event) => {
-          if (!closed && event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-            response.write(`event: token\ndata: ${JSON.stringify({ text: event.assistantMessageEvent.delta })}\n\n`);
-          }
+          if (closed) return;
+          const activity = activityFromAgentEvent(event as unknown as Record<string, any>);
+          if (activity) response.write(`event: activity\ndata: ${JSON.stringify(activity)}\n\n`);
+          if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") response.write(`event: token\ndata: ${JSON.stringify({ text: event.assistantMessageEvent.delta })}\n\n`);
         });
         response.once("close", () => { closed = true; void handle.session.abort(); });
       }
@@ -594,13 +662,14 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     };
     const profileName = (request: FastifyRequest<{ Params: { profile: string } }>) => request.params.profile;
     const pulseTick = async (action: "start" | "stop" | "status") => new Promise<string>((resolveRun, reject) => {
-      const child = spawn(process.execPath, [process.argv[1], "pulse", action], { cwd: options.cwd, env: { ...process.env, PI_API_WORKER: "" }, stdio: ["ignore", "pipe", "pipe"] });
+      const pi = piCommand();
+      const child = spawn(pi.command, [...pi.args, "pulse", action], { cwd: options.cwd, env: { ...process.env, PI_API_WORKER: "" }, stdio: ["ignore", "pipe", "pipe"] });
       let stdout = "", stderr = ""; child.stdout.on("data", (chunk) => stdout += String(chunk)); child.stderr.on("data", (chunk) => stderr += String(chunk));
       child.once("error", reject); child.once("exit", (code) => code === 0 ? resolveRun(stdout.trim()) : reject(new Error(stderr.trim() || `Pulse command exited with ${code}`)));
     });
     const pulseTickStatus = async () => {
-      try { const state = JSON.parse(await readFile(join(options.agentDir, "pulse-tick.state.json"), "utf8")) as { pid?: unknown; startedAt?: unknown }; const pid = typeof state.pid === "number" ? state.pid : 0; let running = false; try { process.kill(pid, 0); running = pid > 0; } catch {} return { running, status: running ? `Pulse tick running (PID ${pid}).` : "Pulse tick stopped." }; }
-      catch { return { running: false, status: "Pulse tick stopped." }; }
+      try { const state = JSON.parse(await readFile(join(options.agentDir, "pulse-tick.state.json"), "utf8")) as { pid?: unknown; startedAt?: unknown; lastHeartbeatAt?: unknown }; const pid = typeof state.pid === "number" ? state.pid : 0, heartbeat = typeof state.lastHeartbeatAt === "string" ? Date.parse(state.lastHeartbeatAt) : NaN; let running = false; try { process.kill(pid, 0); running = pid > 0; } catch {} if (!running) return { running: false, status: `Pulse tick abandoned (PID ${pid} is not running).`, state: "abandoned", lastHeartbeatAt: state.lastHeartbeatAt ?? null }; if (!Number.isNaN(heartbeat) && Date.now() - heartbeat > 2 * 60_000) return { running: false, status: `Pulse tick stale (last heartbeat ${state.lastHeartbeatAt}).`, state: "stale", lastHeartbeatAt: state.lastHeartbeatAt }; return { running: true, status: `Pulse tick running (PID ${pid}).`, state: "healthy", lastHeartbeatAt: state.lastHeartbeatAt ?? null }; }
+      catch { return { running: false, status: "Pulse tick stopped.", state: "stopped", lastHeartbeatAt: null }; }
     };
     server.get("/api/pulse/tick/status", async (request, reply) => {
       if (!guard(request, reply)) return;
@@ -618,9 +687,10 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     });
     server.post("/api/profiles", async (request, reply) => {
       if (!guard(request, reply)) return;
-      const name = objectBody(request.body).name;
+      const body = objectBody(request.body), name = body.name, cloneFrom = body.cloneFrom;
       if (typeof name !== "string") throw Object.assign(new Error("The 'name' field must be a string."), { status: 400 });
-      const profile = await api.profiles.create(name);
+      if (cloneFrom !== undefined && typeof cloneFrom !== "string") throw Object.assign(new Error("The 'cloneFrom' field must be a string."), { status: 400 });
+      const profile = await api.profiles.create(name, { description: body.description, tags: body.tags }, cloneFrom);
       return reply.code(201).send(profile);
     });
     server.get<{ Params: { profile: string } }>("/api/profiles/:profile", async (request, reply) => {
@@ -628,6 +698,12 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       const settings = await api.profiles.readSettings(profileName(request));
       return { name: profileName(request), path: api.profiles.directory(profileName(request)), hasSoul: true, hasRefine: true, policy: settings.profile ?? {} };
     });
+    server.patch<{ Params: { profile: string } }>("/api/profiles/:profile", async (request, reply) => {
+      if (!guard(request, reply)) return;
+      const body = objectBody(request.body);
+      if (body.description === undefined || body.tags === undefined) throw Object.assign(new Error("description and tags are required."), { status: 400 });
+      return { profile: await api.profiles.updateMetadata(profileName(request), { description: body.description, tags: body.tags }) };
+    });
     server.delete<{ Params: { profile: string } }>("/api/profiles/:profile", async (request, reply) => {
       if (!guard(request, reply)) return;
       if (objectBody(request.body).force !== true) throw Object.assign(new Error('Profile deletion requires { "force": true }.'), { status: 400 });
@@ -670,6 +746,43 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       return { settings: await api.profiles.writeSettings(profileName(request), settings) };
     });
 
+    const workflowEvaluation = async (profile: string, value: unknown) => {
+      const input = objectBody(value), modelType = input.modelType;
+      if (modelType === "llm") return { modelType: "llm" as const };
+      const systemOne = objectBody(input.systemOne), provider = typeof systemOne.provider === "string" ? systemOne.provider.trim() : "", model = typeof systemOne.model === "string" ? systemOne.model.trim() : "", endpoint = systemOne.endpoint && typeof systemOne.endpoint === "object" && !Array.isArray(systemOne.endpoint) ? systemOne.endpoint as Record<string, unknown> : {}, baseUrl = typeof endpoint.baseUrl === "string" && endpoint.baseUrl.trim() ? endpoint.baseUrl.trim() : "https://openrouter.ai/api/", path = typeof endpoint.path === "string" && endpoint.path.trim() ? endpoint.path.trim().replace(/^\/+/, "") : "alpha/decisions";
+      try { const url = new URL(baseUrl); if (!/^https?:$/.test(url.protocol) || /^(?:https?:)?\/\//i.test(path)) throw new Error(); }
+      catch { throw Object.assign(new Error("Invalid System One endpoint configuration."), { status: 400 }); }
+      if (modelType !== "system_one" || !provider || !model || (systemOne.onUncertain !== undefined && systemOne.onUncertain !== "block")) throw Object.assign(new Error("Invalid Sequential Workflow evaluation configuration."), { status: 400 });
+      const directory = api.profiles.directory(profile), runtime = await ModelRuntime.create({ authPath: join(directory, "auth.json"), modelsPath: join(directory, "models.json"), refreshOnCreate: false });
+      if (runtime.getError()) throw Object.assign(new Error(runtime.getError()), { status: 400 });
+      if (!runtime.getModels().some((available) => available.provider === provider)) throw Object.assign(new Error("The selected provider is not available for this profile."), { status: 400 });
+      return { modelType: "system_one" as const, systemOne: { provider, model, endpoint: { baseUrl, path }, onUncertain: "block" as const } };
+    };
+    const configuredWorkflowEvaluation = async (profile: string, settings: ProfileSettings) => {
+      const value = (settings as Record<string, unknown>).sequentialWorkflow;
+      if (!value || typeof value !== "object" || Array.isArray(value)) return { modelType: "llm" as const };
+      const evaluation = (value as Record<string, unknown>).evaluation;
+      return !evaluation || typeof evaluation !== "object" || Array.isArray(evaluation) ? { modelType: "llm" as const } : workflowEvaluation(profile, evaluation);
+    };
+    server.get<{ Params: { profile: string } }>("/api/profiles/:profile/sequential-workflows/config", async (request, reply) => {
+      if (!guard(request, reply)) return;
+      const profile = profileName(request); return { evaluation: await configuredWorkflowEvaluation(profile, await api.profiles.readSettings(profile)) };
+    });
+    server.put<{ Params: { profile: string } }>("/api/profiles/:profile/sequential-workflows/config", async (request, reply) => {
+      if (!guard(request, reply)) return;
+      const profile = profileName(request), evaluation = await workflowEvaluation(profile, objectBody(request.body).evaluation), settings = await api.profiles.readSettings(profile);
+      const sequentialWorkflow = { ...(((settings as Record<string, unknown>).sequentialWorkflow as Record<string, unknown> | undefined) ?? {}), evaluation };
+      await api.profiles.writeSettings(profile, { ...settings, sequentialWorkflow } as ProfileSettings);
+      return { evaluation };
+    });
+    server.get<{ Params: { profile: string } }>("/api/profiles/:profile/sequential-workflows/status", async (request, reply) => {
+      if (!guard(request, reply)) return;
+      const profile = profileName(request), evaluation = await configuredWorkflowEvaluation(profile, await api.profiles.readSettings(profile));
+      const directory = api.profiles.directory(profile), environment = await api.handlerEnvironment(profile);
+      const credentialConfigured = evaluation.modelType !== "system_one" || await hasOpenRouterCredential(directory, environment);
+      return { evaluation, credentialConfigured };
+    });
+
     const documentRoute = (name: "soul" | "refine", file: "SOUL.md" | "REFINE.md") => {
       server.get<{ Params: { profile: string } }>(`/api/profiles/:profile/${name}`, async (request, reply) => {
         if (!guard(request, reply)) return;
@@ -779,9 +892,9 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       return { content };
     });
 
-    server.get<{ Params: { profile: string } }>("/api/profiles/:profile/sessions", async (request, reply) => {
+    server.get<{ Params: { profile: string }; Querystring: { includePulseSessions?: string; includePulseExecutions?: string } }>("/api/profiles/:profile/sessions", async (request, reply) => {
       if (!guard(request, reply)) return;
-      return { sessions: await api.listSessions(profileName(request)) };
+      return { sessions: await api.listSessions(profileName(request), request.query.includePulseSessions === "true" || request.query.includePulseExecutions === "true") };
     });
     server.post<{ Params: { profile: string } }>("/api/profiles/:profile/sessions", async (request, reply) => {
       if (!guard(request, reply)) return;
@@ -823,6 +936,13 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       try { return { runs: api.pulses.runs(profile, request.params.name, start, end, limit) }; }
       catch (error) { throw Object.assign(error instanceof Error ? error : new Error(String(error)), { status: 404 }); }
     });
+    server.post<{ Params: { profile: string; name: string; runId: string } }>("/api/profiles/:profile/pulses/:name/runs/:runId/finalize", async (request, reply) => {
+      if (!guard(request, reply)) return;
+      const status = objectBody(request.body).status;
+      if (status !== "success" && status !== "error") throw Object.assign(new Error("The 'status' field must be 'success' or 'error'."), { status: 400 });
+      try { return { run: api.pulses.finalizeRunning(request.params.name, profileName(request), request.params.runId, status) }; }
+      catch (error) { throw Object.assign(error instanceof Error ? error : new Error(String(error)), { status: 409 }); }
+    });
     server.get<{ Params: { profile: string } }>("/api/profiles/:profile/pulses/history", async (request, reply) => {
       if (!guard(request, reply)) return;
       await api.profiles.readSettings(profileName(request));
@@ -835,7 +955,7 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       for (const field of fields) if (typeof body[field] !== "string" || !String(body[field]).trim()) throw Object.assign(new Error(`The '${field}' field must be a non-empty string.`), { status: 400 });
       const sessionId = typeof body.thread_session_id === "string" ? body.thread_session_id : "";
       if (sessionId && !(await api.listSessions(profileName(request))).some((session) => session.id === sessionId)) throw Object.assign(new Error("The thread_session_id session was not found."), { status: 404 });
-      try { return reply.code(201).send({ pulse: api.pulses.create({ name: body.name as string, description: body.description as string, schedule: body.schedule as string, prompt: body.prompt as string, thread_session_id: sessionId, insertIntoApiSession: body.insertIntoApiSession === true, profile: profileName(request) }) }); }
+      try { return reply.code(201).send({ pulse: api.pulses.create({ name: body.name as string, description: body.description as string, schedule: body.schedule as string, prompt: body.prompt as string, thread_session_id: sessionId, insertIntoApiSession: body.insertIntoApiSession !== false, profile: profileName(request) }) }); }
       catch (error) { throw Object.assign(error instanceof Error ? error : new Error(String(error)), { status: 400 }); }
     });
     server.patch<{ Params: { profile: string; name: string } }>("/api/profiles/:profile/pulses/:name", async (request, reply) => {
@@ -845,11 +965,15 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     });
     server.put<{ Params: { profile: string; name: string } }>("/api/profiles/:profile/pulses/:name", async (request, reply) => {
       if (!guard(request, reply)) return;
-      const body = objectBody(request.body), fields = ["description", "schedule", "prompt"] as const;
+      const body = objectBody(request.body), fields = ["name", "description", "schedule", "prompt"] as const;
       for (const field of fields) if (typeof body[field] !== "string" || !String(body[field]).trim()) throw Object.assign(new Error(`The '${field}' field must be a non-empty string.`), { status: 400 });
       const sessionId = typeof body.thread_session_id === "string" ? body.thread_session_id : "";
       if (sessionId && !(await api.listSessions(profileName(request))).some((session) => session.id === sessionId)) throw Object.assign(new Error("The thread_session_id session was not found."), { status: 404 });
-      try { return { pulse: api.pulses.update(request.params.name, profileName(request), { description: body.description as string, schedule: body.schedule as string, prompt: body.prompt as string, thread_session_id: sessionId, insertIntoApiSession: body.insertIntoApiSession === true }) }; }
+      try {
+        const profile = profileName(request), current = api.pulses.get(request.params.name, profile);
+        if (!current) throw new Error("Pulse not found.");
+        return { pulse: api.pulses.update(request.params.name, profile, { name: body.name as string, description: body.description as string, schedule: body.schedule as string, prompt: body.prompt as string, thread_session_id: sessionId, insertIntoApiSession: typeof body.insertIntoApiSession === "boolean" ? body.insertIntoApiSession : current.insertIntoApiSession }) };
+      }
       catch (error) { throw Object.assign(error instanceof Error ? error : new Error(String(error)), { status: 400 }); }
     });
     server.delete<{ Params: { profile: string; name: string } }>("/api/profiles/:profile/pulses/:name", async (request, reply) => {
@@ -865,7 +989,7 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     server.get<{ Params: { identifier: string } }>("/api/skill-sources/:identifier/skills", async (request, reply) => { if (!guard(request, reply)) return; return { skills:api.skillSources.skills(request.params.identifier) }; });
     server.get<{ Params: { identifier: string; name: string } }>("/api/skill-sources/:identifier/skills/:name/document", async (request, reply) => { if (!guard(request, reply)) return; return api.skillSources.document(request.params.identifier, request.params.name); });
     server.post<{ Params: { profile: string; identifier: string; name: string } }>("/api/profiles/:profile/skills/from-source/:identifier/:name", async (request, reply) => { if (!guard(request, reply)) return; const profile=profileName(request); await api.profiles.readSettings(profile); const destination=api.profiles.skillImportDirectory(profile); const skill=await api.skillSources.install(request.params.identifier,request.params.name,destination,profile); await api.profiles.refreshSkills(profile); return reply.code(201).send({ skill, destination }); });
-    server.post<{ Params: { profile: string; name: string }; Querystring: { source?: string } }>("/api/profiles/:profile/skills/:name/publish", async (request, reply) => { if (!guard(request, reply)) return; const profile=profileName(request), body=objectBody(request.body), source=skillSource(request.query.source); if (typeof body.identifier !== "string" || !body.identifier) throw Object.assign(new Error("A Skill Source is required."), { status: 400 }); const skill=await api.profiles.resource(profile, "skills", request.params.name, source); if (!skill.path) throw Object.assign(new Error("Skill path is not available."), { status: 404 }); if (source === "shared" && profile !== "default") throw Object.assign(new Error("Shared Skills can only be published by the default profile."), { status: 403 }); const publication=await api.skillSources.publish(body.identifier, profile, request.params.name, skill.path); await api.profiles.refreshSkills(profile); return reply.code(publication.action === "created" ? 201 : 200).send({ publication }); });
+    server.post<{ Params: { profile: string; name: string }; Querystring: { source?: string } }>("/api/profiles/:profile/skills/:name/publish", async (request, reply) => { if (!guard(request, reply)) return; const profile=profileName(request), body=objectBody(request.body), source=skillSource(request.query.source); if (typeof body.identifier !== "string" || !body.identifier) throw Object.assign(new Error("A Skill Source is required."), { status: 400 }); const skill=await api.profiles.resource(profile, "skills", request.params.name, source); if (!skill.path) throw Object.assign(new Error("Skill path is not available."), { status: 404 }); if (source === "shared" && profile !== "default") throw Object.assign(new Error("Shared Skills can only be published by the default profile."), { status: 403 }); const publication=await api.skillSources.publish(body.identifier, profile, request.params.name, skill.path, body.confirmOverwrite === true); if (publication.action !== "confirmation_required") await api.profiles.refreshSkills(profile); return reply.code(publication.action === "created" ? 201 : 200).send({ publication }); });
     server.post<{ Params: { profile: string; name: string }; Querystring: { source?: string } }>("/api/profiles/:profile/skills/:name/sync", async (request, reply) => { if (!guard(request, reply)) return; const profile=profileName(request), source=skillSource(request.query.source), skill=await api.profiles.resource(profile, "skills", request.params.name, source); if (!skill.path) throw Object.assign(new Error("Skill path is not available."), { status: 404 }); const synchronization=await api.skillSources.syncInstallation(profile, request.params.name, skill.path); await api.profiles.refreshSkills(profile); return { synchronization }; });
 
     const skillSource = (value: unknown): "shared" | "profile" | "package" | undefined => {
@@ -964,7 +1088,7 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     server.post("/api/applications", async (request, reply) => {
       if (!guard(request, reply)) return; const body = objectBody(request.body);
       if (typeof body.name !== "string" || typeof body.slug !== "string") throw Object.assign(new Error("name and slug are required."), { status: 400 });
-      const responseMode = body.responseMode === "result" ? "result" : "ack"; const defaults: ApplicationSettings = { responseMode, inboundHandler: "inbound", transformHandlers: [] }; const record = applicationStore.create({ name: body.name, slug: body.slug, enabled: body.enabled !== false, responseMode, defaultProfile: typeof body.defaultProfile === "string" && body.defaultProfile ? body.defaultProfile : null, routingPolicy: body.routingPolicy === "drop" ? "drop" : "default_as_fallback", settings: body.settings && typeof body.settings === "object" && !Array.isArray(body.settings) ? body.settings as Record<string, unknown> : defaults });
+      const responseMode = body.responseMode === "result" ? "result" : "ack"; const defaults: ApplicationSettings = { responseMode, inboundHandler: "inbound", transformHandlers: [], directMode: { enabled: true } }; const record = applicationStore.create({ name: body.name, slug: body.slug, enabled: body.enabled !== false, responseMode, defaultProfile: typeof body.defaultProfile === "string" && body.defaultProfile ? body.defaultProfile : null, routingPolicy: body.routingPolicy === "drop" ? "drop" : "default_as_fallback", settings: body.settings && typeof body.settings === "object" && !Array.isArray(body.settings) ? body.settings as Record<string, unknown> : defaults });
       await loadApplication(record); return reply.code(201).send({ application: record });
     });
     server.get<{ Params: { slug: string } }>("/api/applications/:slug", async (request, reply) => { if (!guard(request, reply)) return; return { application: registeredApplication(request.params.slug).record }; });
@@ -1011,9 +1135,22 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
     server.post("/api/terminal/ticket", async (request, reply) => { if (!guard(request, reply)) return; if (!terminalEnabled) throw Object.assign(new Error("Console terminal is disabled."), { status: 403 }); const ticket = randomUUID(); terminalTickets.set(ticket, { expiresAt: Date.now() + 30_000 }); return { url: terminalUrl(ticket), cwd: terminalCwd }; });
     server.get("/api/terminal/stream", { websocket: true }, (socket, request) => { const ticket = (request.query as { ticket?: string }).ticket; const value = ticket && terminalTickets.get(ticket); if (!terminalEnabled || !value || value.expiresAt < Date.now()) return socket.close(1008, "Invalid ticket"); terminalTickets.delete(ticket!); let child: pty.IPty; try { child = pty.spawn(terminalShell, ["-l"], { name: "xterm-256color", cols: 80, rows: 24, cwd: terminalCwd, env: process.env }); } catch (error) { socket.send(JSON.stringify({ type: "error", data: (error as Error).message })); return socket.close(1011); } const send = (type: string, data: string) => { if (socket.readyState === socket.OPEN) socket.send(JSON.stringify({ type, data })); }; child.onData((data) => send("output", data)); child.onExit(() => socket.close()); socket.on("message", (raw) => { try { const message = JSON.parse(raw.toString()) as { type?: string; data?: string; cols?: number; rows?: number }; if (message.type === "input" && typeof message.data === "string") child.write(message.data); if (message.type === "resize" && Number.isInteger(message.cols) && Number.isInteger(message.rows) && message.cols! > 0 && message.rows! > 0) child.resize(message.cols!, message.rows!); } catch { /* ignore malformed terminal messages */ } }); socket.on("close", () => child.kill()); });
     server.post<{ Params: { slug: string } }>("/api/applications/:slug/session-rollover", async (request, reply) => { if (!guard(request, reply)) return; return reply.code(201).send(await registeredApplication(request.params.slug).runtime.rollover(request.body)); });
-    server.post<{ Params: { slug: string } }>("/api/message/app/:slug", async (request, reply) => {
+    server.post<{ Params: { slug: string } }>("/api/message/app/:slug", { bodyLimit: MAX_APPLICATION_BODY_BYTES }, async (request, reply) => {
       const application = registeredApplication(request.params.slug); if (!application.record.enabled) return apiError(reply, 404, "NOT_FOUND", "Application is disabled.");
       const headers = Object.fromEntries(Object.entries(request.headers).map(([key, value]) => [key, Array.isArray(value) ? value.join(", ") : value ?? ""])); const query = request.query && typeof request.query === "object" ? request.query as Record<string, unknown> : {};
+      if (application.runtime.isDirectRequest(request.body)) {
+        const direct = await application.runtime.prepareDirectRequest(request.body);
+        if (application.record.responseMode === "ack") {
+          void application.runtime.process(request.body, headers, query, direct).then(async (value) => {
+            const result = value as { profile: string; sessionId: string; response: string };
+            const response = await fetch(direct.responseWebhookUrl!, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ application: application.record.slug, identityKey: direct.identityKey, profile: result.profile, sessionId: result.sessionId, response: result.response }), signal: AbortSignal.timeout(15_000) });
+            if (!response.ok) throw new Error(`Response webhook returned HTTP ${response.status}.`);
+          }).catch((error) => console.error(`[application:${application.record.slug}] Direct Mode response webhook failed:`, error));
+          return reply.code(202).send({ ok: true, accepted: true });
+        }
+        // In wait mode responseWebhookUrl is intentionally ignored.
+        return application.runtime.process(request.body, headers, query, direct);
+      }
       if (application.record.responseMode === "ack") { void application.runtime.process(request.body, headers, query).catch((error) => console.error(`[application:${application.record.slug}]`, error)); return reply.code(202).send({ ok: true, accepted: true }); }
       return application.runtime.process(request.body, headers, query);
     });
@@ -1023,7 +1160,7 @@ export async function startApiServer(options: ServerOptions): Promise<FastifyIns
       return apiError(reply, 404, "NOT_FOUND", "Route not found.");
     });
     server.setErrorHandler(async (error, _request, reply) => {
-      if (error.code === "FST_ERR_CTP_BODY_TOO_LARGE") return apiError(reply, 413, "BAD_REQUEST", "payload exceeds 1 MiB");
+      if (error.code === "FST_ERR_CTP_BODY_TOO_LARGE") return apiError(reply, 413, "BAD_REQUEST", "payload exceeds the allowed request size limit.");
       const typed = error as Error & { status?: number };
       if (typed.status) return apiError(reply, typed.status, "BAD_REQUEST", typed.message);
       console.error("[pi-api]", error);