@piagent/platform 1.5.1 → 1.5.3

package/packages/piagent-webui/dist/client/index.html

@@ -7,7 +7,7 @@
     <meta name="csp-nonce" content="__PIAGENT_CSP_NONCE__" />
     <meta name="piagent-webui-mode" content="__PIAGENT_WEBUI_MODE__" />
     <title>Piagent WebUI</title>
-    <script type="module" crossorigin src="/assets/index-MBZq8XLV.js"></script>
+    <script type="module" crossorigin src="/assets/index-DZg979Ht.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BV-_03yl.css">
   </head>
   <body>

package/packages/piagent-webui/gateway/gateway-service.ts

@@ -23,6 +23,7 @@ import { SessionLeaseStore } from "./session-lease-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
 import { SessionCommandStore } from "./session-command-store.ts";
 import { SessionCommandController } from "./session-command-controller.ts";
+import { RuntimeCommandController } from "./runtime-command-controller.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionInspectionRegistry } from "./session-inspection-registry.ts";
 import { SessionAttachmentRegistry } from "./session-attachment-registry.ts";
@@ -175,6 +176,7 @@ export async function startPiagentGateway(options: {
         if (!attachments) throw new Error("session-attachment-unavailable");
         return attachments.reserveForPrompt(sessionRef, refs, messageRequestId, text);
       } });
+    const runtimeCommands = new RuntimeCommandController({ catalog: readCatalog, runtimes, events });
     const protocol = new GatewayProtocolService({ capabilities: () => capabilities(gatewayInstanceRef, true), catalog: readCatalog,
       events, command: commands });
     const inspections = new SessionInspectionRegistry({ gatewayInstanceRef, host, key, packageRoot: options.packageRoot, agentDir: state.agentDir,
@@ -194,6 +196,7 @@ export async function startPiagentGateway(options: {
       readSessionModel: (sessionRef) => inspections.provider(sessionRef),
       readSessionConnections: (sessionRef) => inspections.connections(sessionRef),
       executeSessionConnection: (command) => inspections.executeConnectionCommand(command),
+      executeRuntimeCommand: (command) => runtimeCommands.execute(command),
       executeSessionAttachment: (sessionRef, command) => attachments.execute(sessionRef, command),
       executeApproval: (approvalRef, decision) => runtimes!.decideApproval(approvalRef, decision),
       readMcpAuthJob: (jobRef) => mcpAuth!.read(jobRef),

package/packages/piagent-webui/gateway/runtime-command-controller.ts

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+
+import {
+  WEBUI_RUNTIME_ACTIONS,
+  buildWebUiRuntimeCommand,
+  isWebUiRuntimeActionId
+} from "../../piagent-core/runtime/workflows/webui-runtime-command.ts";
+import type { Catalog } from "../contracts/generated/session-catalog-v1.ts";
+import type { Action, Command, Receipt } from "../contracts/generated/runtime-command-v1.ts";
+import { GatewayEventStore } from "./gateway-events.ts";
+import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const MAX_REPLAYS = 200;
+
+type Replay = { digest: string; receipt: Receipt };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseCommand(value: unknown): Command | null {
+  if (!record(value)) return null;
+  const expected = ["schemaVersion", "version", "messageType", "requestId", "sessionRef", "expectedSessionRevision", "action", "argument", "confirmed"];
+  const keys = Object.keys(value);
+  if (keys.length !== expected.length || !keys.every((key) => expected.includes(key))) return null;
+  if (value.schemaVersion !== 1 || value.version !== "piagent-runtime-command-v1" || value.messageType !== "command"
+    || typeof value.requestId !== "string" || !REF.test(value.requestId)
+    || typeof value.sessionRef !== "string" || !REF.test(value.sessionRef)
+    || typeof value.expectedSessionRevision !== "string" || !REVISION.test(value.expectedSessionRevision)
+    || !isWebUiRuntimeActionId(value.action)
+    || !(value.argument === null || typeof value.argument === "string" && value.argument.length <= 2_048 && !value.argument.includes("\0"))
+    || typeof value.confirmed !== "boolean") return null;
+  return value as unknown as Command;
+}
+
+function commandDigest(command: Command): string {
+  return createHash("sha256").update(JSON.stringify({ sessionRef: command.sessionRef,
+    expectedSessionRevision: command.expectedSessionRevision, action: command.action,
+    argument: command.argument, confirmed: command.confirmed })).digest("hex");
+}
+
+export class RuntimeCommandController {
+  readonly #catalog: () => Promise<Catalog>;
+  readonly #runtimes: SessionRuntimeSupervisor;
+  readonly #events: GatewayEventStore;
+  readonly #replays = new Map<string, Replay>();
+  readonly #chains = new Map<string, Promise<unknown>>();
+
+  constructor(options: { catalog(): Promise<Catalog>; runtimes: SessionRuntimeSupervisor; events: GatewayEventStore }) {
+    this.#catalog = options.catalog;
+    this.#runtimes = options.runtimes;
+    this.#events = options.events;
+  }
+
+  execute(input: unknown): Promise<Receipt> {
+    const command = parseCommand(input);
+    if (!command) return Promise.reject(new Error("runtime-command-invalid"));
+    const prior = this.#chains.get(command.sessionRef) ?? Promise.resolve();
+    const run = prior.then(() => this.#execute(command), () => this.#execute(command));
+    const tail = run.catch(() => undefined);
+    this.#chains.set(command.sessionRef, tail);
+    return run.finally(() => { if (this.#chains.get(command.sessionRef) === tail) this.#chains.delete(command.sessionRef); });
+  }
+
+  async #execute(command: Command): Promise<Receipt> {
+    const digest = commandDigest(command), replay = this.#replays.get(command.requestId);
+    if (replay) {
+      if (replay.digest !== digest) return this.#receipt(command, "rejected", "invalid-command", "idempotency-payload-mismatch");
+      return replay.receipt;
+    }
+    const catalog = await this.#readyCatalog();
+    const row = catalog.sessions.find((session) => session.sessionRef === command.sessionRef);
+    if (!row || row.archived) return this.#settle(command, digest,
+      this.#receipt(command, "rejected", "unavailable", row ? "session-archived" : "session-not-found"));
+    if (row.sessionRevision !== command.expectedSessionRevision) return this.#settle(command, digest,
+      this.#receipt(command, "rejected", "stale-revision", "session-revision-stale", row.sessionRevision));
+
+    let built: ReturnType<typeof buildWebUiRuntimeCommand>;
+    try { built = buildWebUiRuntimeCommand({ action: command.action, argument: command.argument, confirmed: command.confirmed }); }
+    catch (error) {
+      const reason = error instanceof Error ? error.message : "runtime-command-invalid";
+      return this.#settle(command, digest, this.#receipt(command, "rejected",
+        reason === "runtime-command-confirmation-required" ? "confirmation-required" : "invalid-command", reason, row.sessionRevision));
+    }
+
+    try {
+      const result = await this.#runtimes.runRuntimeCommand(command.sessionRef, built.command);
+      const after = await this.#readyCatalog();
+      const afterRow = after.sessions.find((session) => session.sessionRef === command.sessionRef);
+      const zeroTurnViolation = built.spec.effect === "read-only" && result.modelCallObserved;
+      const receipt = this.#receipt(command, zeroTurnViolation ? "uncertain" : "settled",
+        zeroTurnViolation ? "effect-unknown" : "completed",
+        zeroTurnViolation ? "read-only-command-started-model-call" : null,
+        afterRow?.sessionRevision ?? null, result.modelCallObserved, result.outputs as Receipt["outputs"]);
+      this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow ?? row });
+      return this.#settle(command, digest, receipt);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : "runtime-command-unavailable";
+      const resultCode = reason.includes("busy") ? "runtime-busy" : "unavailable";
+      return this.#settle(command, digest,
+        this.#receipt(command, "rejected", resultCode, reason, row.sessionRevision));
+    }
+  }
+
+  async #readyCatalog(): Promise<Catalog> {
+    const catalog = await this.#catalog();
+    if (catalog.state !== "ready" || !catalog.catalogRevision) throw new Error(catalog.reasonCode ?? "catalog-unavailable");
+    return catalog;
+  }
+
+  #receipt(command: Command, state: Receipt["state"], resultCode: Receipt["resultCode"], reasonCode: string | null,
+    sessionRevisionAfter: string | null = null, modelCallObserved = false, outputs: Receipt["outputs"] = []): Receipt {
+    const spec = WEBUI_RUNTIME_ACTIONS.find((item) => item.id === command.action)!;
+    return { schemaVersion: 1, version: "piagent-runtime-receipt-v1", messageType: "receipt",
+      requestId: command.requestId, sessionRef: command.sessionRef, action: command.action as Action,
+      state, resultCode, effect: spec.effect, modelCallObserved, outputs, sessionRevisionAfter, reasonCode };
+  }
+
+  #settle(command: Command, digest: string, receipt: Receipt): Receipt {
+    this.#replays.set(command.requestId, { digest, receipt });
+    while (this.#replays.size > MAX_REPLAYS) this.#replays.delete(this.#replays.keys().next().value as string);
+    return receipt;
+  }
+}

package/packages/piagent-webui/gateway/runtime-session-controls.ts

@@ -0,0 +1,29 @@
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+
+export async function executePermissionCommand(session: any,
+  permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<void> {
+  const before = Array.isArray(session.messages) ? session.messages.length : 0;
+  await session.prompt(`/permission ${permissionMode}`);
+  const messages = Array.isArray(session.messages) ? session.messages.slice(before) : [];
+  const observed = messages.reverse().find((message: any) => message?.role === "custom"
+    && message.customType === "piagent-permission-profile");
+  const profile = observed?.details?.permissionProfile;
+  if (!profile || profile.mode !== permissionMode || profile.warning) throw new Error("session-permission-unavailable");
+}
+
+export async function executeRuntimeCommand(session: any, command: string): Promise<{
+  outputs: Array<{ customType: string; content: string; truncated: boolean; redacted: boolean }>;
+  modelCallObserved: boolean;
+}> {
+  const before = Array.isArray(session.messages) ? session.messages.length : 0;
+  await session.prompt(command);
+  const added = Array.isArray(session.messages) ? session.messages.slice(before) : [];
+  const outputs = added.filter((message: any) => message?.role === "custom").slice(-8).map((message: any) => {
+    const source = typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? "");
+    const bounded = source.slice(0, 12_000), redacted = redactSensitiveText(bounded);
+    const rawType = String(message.customType ?? "runtime-output");
+    return { customType: /^[A-Za-z0-9._-]{1,120}$/.test(rawType) ? rawType : "runtime-output", content: redacted.text,
+      truncated: source.length > bounded.length, redacted: redacted.redacted };
+  });
+  return { outputs, modelCallObserved: added.some((message: any) => message?.role === "assistant") };
+}

package/packages/piagent-webui/gateway/session-command-controller.ts

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 
 import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
 import type { Receipt } from "../contracts/generated/session-command-v1.ts";
+import { buildWebUiWorkflowCommand, isWebUiWorkflowId, type WebUiWorkflowId } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import { GatewayEventStore } from "./gateway-events.ts";
 import { SessionCommandStore, type SessionAction, type SessionCommandIdentity } from "./session-command-store.ts";
 import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
@@ -27,6 +28,10 @@ function record(value: unknown): value is Record<string, unknown> { return Boole
 function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
   const found = Object.keys(value); return found.length === keys.length && found.every((key) => keys.includes(key));
 }
+function requiredOptionalKeys(value: Record<string, unknown>, required: string[], optional: string[]): boolean {
+  const found = Object.keys(value), allowed = new Set([...required, ...optional]);
+  return required.every((key) => found.includes(key)) && found.every((key) => allowed.has(key));
+}
 function exactTimestamp(value: unknown): value is string {
   return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
     && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
@@ -35,13 +40,15 @@ function nullableRef(value: unknown): value is string | null { return value ===
 
 function validPayload(action: SessionAction, payload: Record<string, unknown>): boolean {
   if (["session.archive", "session.unarchive", "session.acquire", "session.release"].includes(action)) return exactKeys(payload, []);
-  if (action === "session.send") return exactKeys(payload, ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"])
+  if (action === "session.send") return requiredOptionalKeys(payload,
+    ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"], ["workflow"])
     && Array.isArray(payload.attachmentRefs) && payload.attachmentRefs.length <= 4
     && new Set(payload.attachmentRefs as unknown[]).size === payload.attachmentRefs.length
     && (payload.attachmentRefs as unknown[]).every((item) => typeof item === "string" && REF.test(item))
     && ["new-operation", "follow-up", "steer"].includes(String(payload.delivery)) && typeof payload.message === "string"
     && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0") && REF.test(String(payload.messageRequestId))
-    && nullableRef(payload.expectedOperationRef) && (payload.delivery === "new-operation" ? payload.expectedOperationRef === null : payload.expectedOperationRef !== null);
+    && nullableRef(payload.expectedOperationRef) && (payload.delivery === "new-operation" ? payload.expectedOperationRef === null : payload.expectedOperationRef !== null)
+    && (payload.workflow === undefined || payload.delivery === "new-operation" && isWebUiWorkflowId(payload.workflow));
   if (action === "session.abort") return exactKeys(payload, ["operationRef", "clearQueued"])
     && REF.test(String(payload.operationRef)) && typeof payload.clearQueued === "boolean";
   if (action === "session.set-model") return exactKeys(payload, ["modelRef"]) && REF.test(String(payload.modelRef));
@@ -56,11 +63,13 @@ function validPayload(action: SessionAction, payload: Record<string, unknown>):
     && (payload.title === null || typeof payload.title === "string" && payload.title.length >= 1 && payload.title.length <= 500
       && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(payload.title));
   const createKeys = ["projectRef", "placeRef", "modelRef", "thinkingLevel", "message", "messageRequestId"];
-  return (exactKeys(payload, createKeys) || exactKeys(payload, [...createKeys, "deferInitialMessage"]))
+  return requiredOptionalKeys(payload, createKeys, ["deferInitialMessage", "permissionMode", "workflow"])
     && REF.test(String(payload.projectRef)) && REF.test(String(payload.placeRef)) && nullableRef(payload.modelRef)
     && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel))
     && typeof payload.message === "string" && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0")
-    && REF.test(String(payload.messageRequestId)) && (payload.deferInitialMessage === undefined || typeof payload.deferInitialMessage === "boolean");
+    && REF.test(String(payload.messageRequestId)) && (payload.deferInitialMessage === undefined || typeof payload.deferInitialMessage === "boolean")
+    && (payload.permissionMode === undefined || ["read-only", "workspace-write", "trusted-full-access"].includes(String(payload.permissionMode)))
+    && (payload.workflow === undefined || isWebUiWorkflowId(payload.workflow));
 }
 
 function parseCommand(value: unknown): SessionCommand | null {
@@ -147,11 +156,17 @@ export class SessionCommandController {
       if (command.action === "session.create") {
         targetSessionRef = await this.#runtimes.create(String(command.payload.projectRef), String(command.payload.placeRef),
           command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
+        if (command.payload.permissionMode !== undefined) {
+          await this.#runtimes.setPermission(targetSessionRef, String(command.payload.permissionMode) as
+            "read-only" | "workspace-write" | "trusted-full-access");
+        }
         const created = await this.#readyCatalog(), createdRow = created.sessions.find((item) => item.sessionRef === targetSessionRef);
         if (!createdRow) throw new Error("session-catalog-refresh-failed");
         if (command.payload.deferInitialMessage === true) resultCode = "created";
         else {
-          const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message: String(command.payload.message),
+          const message = buildWebUiWorkflowCommand((command.payload.workflow as WebUiWorkflowId | undefined) ?? null,
+            String(command.payload.message));
+          const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message,
             expectedOperationRef: null }, createdRow.sessionRevision);
           resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
         }
@@ -162,7 +177,7 @@ export class SessionCommandController {
         const acquired = await this.#readyCatalog(), acquiredRow = acquired.sessions.find((item) => item.sessionRef === command.sessionRef);
         if (!acquiredRow) throw new Error("session-catalog-refresh-failed");
         const payload = command.payload as { delivery: "new-operation" | "follow-up" | "steer"; message: string;
-          expectedOperationRef: string | null; messageRequestId: string; attachmentRefs: string[] };
+          expectedOperationRef: string | null; messageRequestId: string; attachmentRefs: string[]; workflow?: WebUiWorkflowId };
         // Staged refs are claimed once, here, before the runtime is asked to
         // dispatch. Documents were turned into text at staging so they join the
         // message; images travel on the host's own channel.
@@ -172,7 +187,8 @@ export class SessionCommandController {
         attachmentReservation = prepared;
         if (!this.#prepareAttachments && payload.attachmentRefs.length > 0) throw new Error("session-attachment-unavailable");
         sendAttempted = true;
-        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message: prepared.text, images: prepared.images },
+        const message = buildWebUiWorkflowCommand(payload.workflow ?? null, prepared.text);
+        const sent = await this.#runtimes.send(command.sessionRef!, { ...payload, message, images: prepared.images },
           acquiredRow.sessionRevision);
         prepared.commit();
         resultCode = sent.resultCode; operationRef = sent.operationRef;

package/packages/piagent-webui/gateway/session-inspection-registry.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import fs from "node:fs";
 import path from "node:path";
 
 import { readContextTelemetry } from "../../piagent-core/extensions/context-engine.js";
@@ -9,6 +10,8 @@ import { webUiModelRef } from "../../piagent-core/runtime/inspection/webui-snaps
 import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
 import { piApprovalBroker } from "../../piagent-core/runtime/inspection/approval-broker.ts";
 import { attachmentCapability } from "../../piagent-core/runtime/input/attachment-store.ts";
+import { WEBUI_WORKFLOW_OPTIONS } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
+import { WEBUI_RUNTIME_ACTIONS } from "../../piagent-core/runtime/workflows/webui-runtime-command.ts";
 import { CoreInspectionProvider } from "../server/core-inspection-provider.ts";
 import { ReadModelNotFound, type WebUiReadModelProvider } from "../server/read-model-provider.ts";
 import { isUserConversationSession, projectRefForCwd, sessionRefForPath, type PiSessionInfo } from "./session-catalog.ts";
@@ -189,6 +192,16 @@ export class SessionInspectionRegistry {
       if (!projects.has(project.projectRef)) projects.set(project.projectRef, project);
     }
     const availableModels = (this.#models?.getAvailableSnapshot() ?? []).slice(0, 300);
+    const profiles = safeRead(() => fs.readdirSync(path.join(this.#packageRoot, "adapters")).flatMap((entry) => {
+      if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(entry)) return [];
+      const file = path.join(this.#packageRoot, "adapters", entry, "profile.json");
+      const stat = fs.lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) return [];
+      const value = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+      return [{ id: entry, displayName: safeName(value.displayName ?? entry),
+        permissionMode: ["read-only", "workspace-write", "trusted-full-access"].includes(String(value.permissionProfile))
+          ? String(value.permissionProfile) : null }];
+    }).slice(0, 100), []);
     const models = availableModels.flatMap((value) => {
       const provider = safeModelId(value.provider);
       const modelId = safeModelId(value.id);
@@ -201,8 +214,16 @@ export class SessionInspectionRegistry {
       return [{ modelRef: webUiModelRef(provider, modelId), provider, modelId, displayName: safeName(value.name ?? modelId),
         reasoning: value.reasoning, imageInput: inputs ? inputs.includes("image") : null, thinkingLevels }];
     });
+    // Keep the WebUI new-session baseline deterministic and visible. If the
+    // preferred model is not authenticated, the host's own default remains the
+    // safe fallback instead of silently substituting another catalog entry.
+    const defaultModel = models.find((value) => value.provider === "openai-codex" && value.modelId === "gpt-5.6-sol");
     return { schemaVersion: 1, version: "piagent-session-creation-options-v1", generatedAt: new Date().toISOString(),
-      projects: [...projects.values()].slice(0, 200), models, webSearch: inspectWebSearchCapability({ agentDir: this.#agentDir, models: availableModels }),
+      projects: [...projects.values()].slice(0, 200), models,
+      defaultModelRef: defaultModel?.modelRef ?? null, defaultThinkingLevel: defaultModel ? "high" : null,
+      profiles, workflows: WEBUI_WORKFLOW_OPTIONS,
+      runtimeActions: WEBUI_RUNTIME_ACTIONS,
+      webSearch: inspectWebSearchCapability({ agentDir: this.#agentDir, models: availableModels }),
       projectImport: nativeProjectPickerAvailable() ? { status: "available", reasonCode: null }
         : { status: "unavailable", reasonCode: "native-project-picker-unavailable" },
       reasonCode: projects.size ? null : "no-known-project" };

package/packages/piagent-webui/gateway/session-runtime-supervisor.ts

@@ -13,6 +13,7 @@ import { GatewayEventStore } from "./gateway-events.ts";
 import { GatewaySessionStream } from "./gateway-session-stream.ts";
 import { GATEWAY_RUNTIME_UI_MARKER } from "../ownership/gateway-runtime-context.ts";
 import { preferAuthoritativePiagentGuard } from "./extension-authority.ts";
+import { executePermissionCommand, executeRuntimeCommand } from "./runtime-session-controls.ts";
 
 const MAX_WARM_RUNTIMES = 10;
 
@@ -22,6 +23,7 @@ type ActiveRuntime = { runtime: RuntimeHandle; lease: SessionLeaseSnapshot; info
   unsubscribe: (() => void) | null; completion: Promise<void> | null; settling: boolean; approvalWaiting: boolean;
   unbindApproval: (() => void) | null; unsubscribeApproval: (() => void) | null; sessionManager: any | null };
 type Projection = { sessionRevision: string; liveState: "offline" | "idle" | "running" | "paused" | "waiting-approval" | "uncertain" };
+type RuntimeCommandResult = Awaited<ReturnType<typeof executeRuntimeCommand>>;
 
 function rpcUiContext(): object {
   const plain = (text: unknown): string => String(text ?? "");
@@ -389,23 +391,23 @@ export class SessionRuntimeSupervisor {
     return "thinking-changed";
   }
 
-  async setPermission(sessionRef: string, permissionMode: "read-only" | "workspace-write" | "trusted-full-access"):
-    Promise<"permission-changed"> {
+  async setPermission(sessionRef: string, permissionMode: "read-only" | "workspace-write" | "trusted-full-access"): Promise<"permission-changed"> {
     await this.acquire(sessionRef);
     const active = this.#active.get(sessionRef), session = active?.runtime.session;
     if (!active || !session) throw new Error("session-runtime-unavailable");
     if (active.operationRef || !session.isIdle) throw new Error("session-runtime-busy");
-    const before = Array.isArray(session.messages) ? session.messages.length : 0;
-    await session.prompt(`/permission ${permissionMode}`);
-    const messages = Array.isArray(session.messages) ? session.messages.slice(before) : [];
-    const observed = messages.reverse().find((message: any) => message?.role === "custom"
-      && message.customType === "piagent-permission-profile");
-    const profile = observed?.details?.permissionProfile;
-    if (!profile || profile.mode !== permissionMode || profile.warning) throw new Error("session-permission-unavailable");
+    await executePermissionCommand(session, permissionMode);
     this.#touchCreated(sessionRef);
     return "permission-changed";
   }
 
+  async runRuntimeCommand(sessionRef: string, command: string): Promise<RuntimeCommandResult> {
+    await this.acquire(sessionRef);
+    const active = this.#active.get(sessionRef), session = active?.runtime.session;
+    if (!active || !session) throw new Error("session-runtime-unavailable");
+    if (active.operationRef || active.settling || !session.isIdle) throw new Error("session-runtime-busy");
+    const result = await executeRuntimeCommand(session, command); this.#touchCreated(sessionRef); return result;
+  }
   approvalProjection(sessionRef: string): { revision: string | null; summary: Record<string, unknown> } {
     const active = this.#active.get(sessionRef);
     if (!active) return { revision: null, summary: { state: "unknown", pending: [], recent: [],

package/packages/piagent-webui/package.json

@@ -8,7 +8,8 @@
     "check:contracts": "node scripts/generate-contracts.mjs --check",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "npm run check:contracts && vite build",
-    "benchmark": "node benchmark/benchmark.mjs"
+    "benchmark": "node benchmark/benchmark.mjs",
+    "benchmark:parity": "node benchmark/parity-benchmark.mjs"
   },
   "dependencies": {
     "@emotion/cache": "^11.14.0",

package/packages/piagent-webui/server/loopback-server.ts

@@ -61,6 +61,7 @@ export async function startLoopbackServer(options: {
   executeSessionAttachment?: (sessionRef: string, command: unknown) => unknown | Promise<unknown>;
   readSessionConnections?: (sessionRef: string) => unknown | Promise<unknown>;
   executeSessionConnection?: (command: unknown) => unknown | Promise<unknown>;
+  executeRuntimeCommand?: (command: unknown) => unknown | Promise<unknown>;
   readMcpAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
   cancelMcpAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
   readProviderAuthCatalog?: () => unknown | Promise<unknown>;
@@ -205,6 +206,22 @@ export async function startLoopbackServer(options: {
       }
     }
 
+    if (request.method === "POST" && url.pathname === "/api/v1/runtime-commands" && options.executeRuntimeCommand) {
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      const mutationSession = auth.authorizeMutation(request);
+      if (!mutationSession) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!consumeControl(mutationSession.id, now)) return errorResponse(response, 429, "control-rate-limit");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-runtime-command"); }
+      try { return jsonResponse(response, 200, await options.executeRuntimeCommand(command)); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "runtime-command-unavailable";
+        return errorResponse(response, code.includes("invalid") ? 400 : 503, code);
+      }
+    }
+
     if (request.method === "POST" && url.pathname.startsWith("/api/v1/mcp-auth/jobs/") && url.pathname.endsWith("/cancel") && options.cancelMcpAuthJob) {
       if (requestOrigin !== origin) return errorResponse(response, 403, "mutation-authority-rejected");
       const mutationSession = auth.authorizeMutation(request);

package/schemas/piagent-webui/catalog-v1.json

@@ -227,6 +227,15 @@
       "supported": true,
       "current": true
     },
+    {
+      "name": "runtime-command-v1",
+      "file": "runtime-command-v1.schema.json",
+      "id": "https://piagent.io.vn/schemas/piagent-webui/runtime-command-v1.schema.json",
+      "documentVersion": 1,
+      "role": "command",
+      "supported": true,
+      "current": true
+    },
     {
       "name": "gateway-capabilities-v1",
       "file": "gateway-capabilities-v1.schema.json",

package/schemas/piagent-webui/runtime-command-v1.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://piagent.io.vn/schemas/piagent-webui/runtime-command-v1.schema.json",
+  "title": "Piagent WebUI typed runtime command and receipt v1",
+  "oneOf": [
+    { "$ref": "#/$defs/command" },
+    { "$ref": "#/$defs/receipt" }
+  ],
+  "$defs": {
+    "action": {
+      "enum": [
+        "runtime.status", "runtime.inspector", "runtime.commands", "orchestration.status",
+        "usage.live", "usage.history", "usage.logs", "usage.efficiency", "usage.preflight",
+        "onboarding.status", "onboarding.profile", "onboarding.tech",
+        "profile.status", "profile.options", "profile.tech-options", "profile.apply", "profile.auto",
+        "context.status", "context.rebuild", "context.search", "context.pack", "context.impact", "context.efficiency", "context.preflight", "context.compact",
+        "memory.status",
+        "mcp.status", "mcp.doctor", "mcp.detail", "mcp.approve", "mcp.reject", "mcp.reset"
+      ]
+    },
+    "effect": { "enum": ["read-only", "workspace-write", "model-assisted"] },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["customType", "content", "truncated", "redacted"],
+      "properties": {
+        "customType": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[A-Za-z0-9._-]+$" },
+        "content": { "type": "string", "maxLength": 12000, "pattern": "^[^\\u0000]*$" },
+        "truncated": { "type": "boolean" },
+        "redacted": { "type": "boolean" }
+      }
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "requestId", "sessionRef", "expectedSessionRevision", "action", "argument", "confirmed"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-runtime-command-v1" },
+        "messageType": { "const": "command" },
+        "requestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "expectedSessionRevision": { "$ref": "common-v1.schema.json#/$defs/revisionToken" },
+        "action": { "$ref": "#/$defs/action" },
+        "argument": { "type": ["string", "null"], "maxLength": 2048, "pattern": "^[^\\u0000]*$" },
+        "confirmed": { "type": "boolean" }
+      }
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "version", "messageType", "requestId", "sessionRef", "action", "state", "resultCode", "effect", "modelCallObserved", "outputs", "sessionRevisionAfter", "reasonCode"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "version": { "const": "piagent-runtime-receipt-v1" },
+        "messageType": { "const": "receipt" },
+        "requestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "sessionRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
+        "action": { "$ref": "#/$defs/action" },
+        "state": { "enum": ["settled", "rejected", "uncertain"] },
+        "resultCode": { "enum": ["completed", "stale-revision", "confirmation-required", "runtime-busy", "invalid-command", "effect-unknown", "unavailable"] },
+        "effect": { "$ref": "#/$defs/effect" },
+        "modelCallObserved": { "type": "boolean" },
+        "outputs": { "type": "array", "maxItems": 8, "items": { "$ref": "#/$defs/output" } },
+        "sessionRevisionAfter": { "$ref": "common-v1.schema.json#/$defs/nullableRevisionToken" },
+        "reasonCode": { "$ref": "common-v1.schema.json#/$defs/nullableReasonCode" }
+      }
+    }
+  }
+}

package/schemas/piagent-webui/session-command-v1.schema.json

@@ -15,6 +15,7 @@
     },
     "thinkingLevel": { "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"] },
     "permissionMode": { "enum": ["read-only", "workspace-write", "trusted-full-access"] },
+    "workflow": { "enum": ["task", "scout", "be-to-fe", "discuss", "plan", "review", "commit", "pr", "onboard", "platform-improve"] },
     "baseCommandProperties": {
       "type": "object",
       "additionalProperties": false,
@@ -55,6 +56,8 @@
                 "placeRef": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "modelRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
                 "thinkingLevel": { "$ref": "#/$defs/thinkingLevel" },
+                "permissionMode": { "$ref": "#/$defs/permissionMode" },
+                "workflow": { "$ref": "#/$defs/workflow" },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
                 "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "deferInitialMessage": {
@@ -82,6 +85,7 @@
               "required": ["delivery", "message", "messageRequestId", "expectedOperationRef", "attachmentRefs"],
               "properties": {
                 "delivery": { "enum": ["new-operation", "follow-up", "steer"] },
+                "workflow": { "$ref": "#/$defs/workflow" },
                 "message": { "type": "string", "minLength": 1, "maxLength": 32768, "pattern": "^[^\\u0000]*$" },
                 "messageRequestId": { "$ref": "common-v1.schema.json#/$defs/opaqueRef" },
                 "expectedOperationRef": { "$ref": "common-v1.schema.json#/$defs/nullableOpaqueRef" },
@@ -101,6 +105,10 @@
                 {
                   "if": { "properties": { "delivery": { "const": "new-operation" } }, "required": ["delivery"] },
                   "then": { "properties": { "expectedOperationRef": { "type": "null" } } }
+                },
+                {
+                  "if": { "properties": { "workflow": { "$ref": "#/$defs/workflow" } }, "required": ["workflow"] },
+                  "then": { "properties": { "delivery": { "const": "new-operation" } } }
                 }
               ]
             }