@piagent/platform 1.5.5 → 1.6.1

package/packages/piagent-webui/gateway/session-operation-lifecycle.ts

@@ -0,0 +1,237 @@
+import { hasVisibleText } from "../shared/text-visibility.ts";
+
+export type SessionOperationPhase = "pending" | "running" | "retry" | "compaction" | "settled";
+
+export type SessionOperationRetryPolicy = Readonly<{
+  maximumAttempts: number;
+  maximumDelayMs: number;
+}>;
+
+export type SessionOperationRetryPolicyOptions = Partial<SessionOperationRetryPolicy>;
+
+export type SessionOperationObservation = Readonly<{
+  accepted: boolean;
+  phase: SessionOperationPhase;
+  retry: "none" | "allowed" | "abort";
+  reasonCode: string | null;
+}>;
+
+const DEFAULT_RETRY_POLICY: SessionOperationRetryPolicy = Object.freeze({
+  // Pi's provider retry is useful before a response exists, but a long retry
+  // chain burns quota and keeps the browser in Working. One automatic retry
+  // absorbs an ordinary transient failure without replaying a persistent one.
+  maximumAttempts: 1,
+  maximumDelayMs: 8_000
+});
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+    throw new Error("session-operation-retry-policy-invalid");
+  }
+  return Number(value);
+}
+
+export function sessionOperationRetryPolicy(
+  options: SessionOperationRetryPolicyOptions = {}
+): SessionOperationRetryPolicy {
+  return Object.freeze({
+    maximumAttempts: boundedInteger(options.maximumAttempts, DEFAULT_RETRY_POLICY.maximumAttempts, 0, 10),
+    maximumDelayMs: boundedInteger(options.maximumDelayMs, DEFAULT_RETRY_POLICY.maximumDelayMs, 0, 300_000)
+  });
+}
+
+function correlationRef(event: any): string | null {
+  for (const key of ["operationRef", "agentOperationId", "operationId"]) {
+    if (typeof event?.[key] === "string" && event[key]) return event[key];
+  }
+  return null;
+}
+
+function visibleAssistantContent(message: any): boolean {
+  if (typeof message?.content === "string") return hasVisibleText(message.content);
+  if (!Array.isArray(message?.content)) return false;
+  return message.content.some((item: any) => {
+    if (item?.type === "text") return hasVisibleText(item.text);
+    // Images and every model-emitted tool/server-tool block are observable
+    // output even when they do not contain user-visible text.
+    return ["image", "image_url", "toolCall", "tool_call", "tool_use", "server_tool_use"]
+      .includes(String(item?.type ?? ""));
+  });
+}
+
+function attempt(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 1 ? Number(value) : null;
+}
+
+function delay(value: unknown): number | null {
+  return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+
+/**
+ * Operation-local authority for provider retry, compaction and settlement.
+ *
+ * Pi's pinned host owns the actual provider retry. This state machine owns the
+ * stricter Piagent admission decision and is shared by the Gateway stream and
+ * runtime supervisor. It never treats compaction as a provider retry, and it
+ * fails closed once assistant output or a tool call makes replay unsafe.
+ */
+export class SessionOperationLifecycle {
+  readonly operationRef: string;
+  readonly retryPolicy: SessionOperationRetryPolicy;
+  #phase: SessionOperationPhase = "pending";
+  #started = false;
+  #hostSettled = false;
+  #terminal = false;
+  #visibleAssistantOutput = false;
+  #toolCallObserved = false;
+  #lastRetryAttempt = 0;
+  #activeRetryAttempt: number | null = null;
+  #retryAbortRequired = false;
+
+  constructor(options: {
+    operationRef: string;
+    retryPolicy?: SessionOperationRetryPolicyOptions | SessionOperationRetryPolicy;
+  }) {
+    this.operationRef = options.operationRef;
+    this.retryPolicy = sessionOperationRetryPolicy(options.retryPolicy);
+  }
+
+  get phase(): SessionOperationPhase { return this.#phase; }
+  get started(): boolean { return this.#started; }
+  get hostSettled(): boolean { return this.#hostSettled; }
+  get terminal(): boolean { return this.#terminal; }
+  get replayUnsafe(): boolean { return this.#visibleAssistantOutput || this.#toolCallObserved; }
+  get retryAbortRequired(): boolean { return this.#retryAbortRequired; }
+
+  forceHostSettlement(): void {
+    this.#started = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+  }
+
+  markTerminal(): boolean {
+    if (this.#terminal) return false;
+    this.#terminal = true;
+    this.#hostSettled = true;
+    this.#phase = "settled";
+    return true;
+  }
+
+  observe(event: any): SessionOperationObservation {
+    if (this.#terminal || this.#hostSettled) return this.#ignored("operation-event-after-settlement");
+    const correlated = correlationRef(event);
+    if (correlated && correlated !== this.operationRef) return this.#ignored("operation-correlation-mismatch");
+    const type = String(event?.type ?? "");
+
+    if (type === "agent_start") {
+      this.#started = true;
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (type === "agent_settled") {
+      this.#started = true;
+      this.#hostSettled = true;
+      this.#phase = "settled";
+      return this.#accepted();
+    }
+
+    // Direct stream fixtures and some deferred command hosts begin with a
+    // message/tool event. Treat that as an observed start while still refusing
+    // uncorrelated retry/compaction lifecycle events before any operation work.
+    if (["message_start", "message_update", "message_end", "tool_execution_start",
+      "tool_execution_update", "tool_execution_end", "turn_start", "turn_end"].includes(type)) {
+      this.#started = true;
+      if (this.#phase === "pending") this.#phase = "running";
+    }
+
+    if (type === "message_update") {
+      const update = event?.assistantMessageEvent;
+      if (update?.type === "text_delta" && hasVisibleText(update.delta)) this.#visibleAssistantOutput = true;
+      if (visibleAssistantContent(event?.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "message_end" && event?.message?.role === "assistant") {
+      if (visibleAssistantContent(event.message)) this.#visibleAssistantOutput = true;
+      return this.#accepted();
+    }
+    if (type === "tool_execution_start") {
+      this.#toolCallObserved = true;
+      return this.#accepted();
+    }
+
+    if (type === "agent_end" && event?.willRetry === true && this.replayUnsafe) {
+      return this.#abortRetry("automatic-retry-replay-unsafe");
+    }
+    if (type === "auto_retry_start") return this.#retryStarted(event);
+    if (type === "auto_retry_end") return this.#retryEnded(event);
+
+    // Summarization retries belong to compaction and never consume or inherit
+    // the provider-turn retry budget.
+    if (type === "compaction_start") {
+      if (!this.#started) return this.#ignored("operation-event-before-start");
+      if (this.#phase === "retry") this.#retryAbortRequired = true;
+      this.#phase = "compaction";
+      return this.#retryAbortRequired
+        ? this.#abortRetry("automatic-retry-compaction-overlap")
+        : this.#accepted();
+    }
+    if (type === "compaction_end") {
+      if (this.#phase !== "compaction") return this.#ignored("compaction-event-stale");
+      this.#phase = "running";
+      return this.#accepted();
+    }
+    if (["summarization_retry_scheduled", "summarization_retry_attempt_start",
+      "summarization_retry_finished"].includes(type)) {
+      return this.#phase === "compaction" ? this.#accepted() : this.#ignored("compaction-event-stale");
+    }
+    return this.#accepted();
+  }
+
+  #retryStarted(event: any): SessionOperationObservation {
+    if (!this.#started) return this.#ignored("operation-event-before-start");
+    const currentAttempt = attempt(event?.attempt), currentDelay = delay(event?.delayMs);
+    if (currentAttempt === null || currentDelay === null) return this.#abortRetry("automatic-retry-metadata-invalid");
+    if (currentAttempt === this.#lastRetryAttempt) return this.#ignored("automatic-retry-event-duplicate");
+    if (currentAttempt !== this.#lastRetryAttempt + 1) {
+      this.#activeRetryAttempt = currentAttempt;
+      this.#phase = "retry";
+      return this.#abortRetry("automatic-retry-attempt-stale");
+    }
+    this.#lastRetryAttempt = currentAttempt;
+    this.#activeRetryAttempt = currentAttempt;
+    if (this.#phase === "compaction") return this.#abortRetry("automatic-retry-compaction-overlap");
+    this.#phase = "retry";
+    if (this.replayUnsafe) return this.#abortRetry("automatic-retry-replay-unsafe");
+    if (currentAttempt > this.retryPolicy.maximumAttempts) return this.#abortRetry("automatic-retry-attempt-limit");
+    if (currentDelay > this.retryPolicy.maximumDelayMs) return this.#abortRetry("automatic-retry-delay-limit");
+    return { accepted: true, phase: this.#phase, retry: "allowed", reasonCode: null };
+  }
+
+  #retryEnded(event: any): SessionOperationObservation {
+    const currentAttempt = attempt(event?.attempt);
+    if (currentAttempt === null || currentAttempt !== this.#activeRetryAttempt) {
+      return this.#ignored("automatic-retry-event-stale");
+    }
+    this.#activeRetryAttempt = null;
+    // Keep the highest attempt for the whole logical operation so hosts that
+    // emit retry_end between attempts still have a monotonic sequence. Keep an
+    // abort latched too: retry_end can arrive synchronously before the
+    // supervisor's cancellation microtask observes the host AbortController.
+    if (this.#phase === "retry") this.#phase = "running";
+    return this.#accepted();
+  }
+
+  #abortRetry(reasonCode: string): SessionOperationObservation {
+    this.#retryAbortRequired = true;
+    return { accepted: true, phase: this.#phase, retry: "abort", reasonCode };
+  }
+
+  #accepted(): SessionOperationObservation {
+    return { accepted: true, phase: this.#phase, retry: "none", reasonCode: null };
+  }
+
+  #ignored(reasonCode: string): SessionOperationObservation {
+    return { accepted: false, phase: this.#phase, retry: "none", reasonCode };
+  }
+}

package/packages/piagent-webui/gateway/session-operation-retry-control.ts

@@ -0,0 +1,38 @@
+type RetryObservation = { retry?: unknown } | null | undefined;
+
+function invoke(action: (() => unknown) | null): void {
+  if (!action) return;
+  try {
+    const result = action();
+    if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+      void Promise.resolve(result).catch(() => undefined);
+    }
+  } catch { /* the operation watchdog remains the terminal authority */ }
+}
+
+/**
+ * Cancels a host-owned provider retry without replaying the prompt. Pinned Pi
+ * creates its retry AbortController immediately after auto_retry_start is
+ * emitted, so the microtask always runs before even a zero-millisecond timer.
+ */
+export class SessionOperationRetryCancellation {
+  readonly #session: any;
+  #fallbackIssued = false;
+
+  constructor(session: any) { this.#session = session; }
+
+  observe(observation: RetryObservation): void {
+    if (observation?.retry !== "abort") return;
+    if (typeof this.#session?.abortRetry === "function") {
+      const cancel = () => invoke(() => this.#session.abortRetry());
+      cancel();
+      queueMicrotask(cancel);
+      return;
+    }
+    // Unknown hosts fail closed once. Replaying a tool-capable turn is more
+    // dangerous than ending the logical operation with an explicit error.
+    if (this.#fallbackIssued || typeof this.#session?.abort !== "function") return;
+    this.#fallbackIssued = true;
+    invoke(() => this.#session.abort());
+  }
+}

package/packages/piagent-webui/gateway/session-operation-start.ts

@@ -12,7 +12,10 @@ export async function waitForOperationStart(
     prompt.then(() => ({ state: "prompt-resolved" as const }),
       (error: unknown) => ({ state: "prompt-rejected" as const, error }))
   ]);
-  if (first.state === "started") return "prompt-owned";
+  if (first.state === "started") {
+    if (stream.lifecycleTerminationReasonCode) throw new Error(stream.lifecycleTerminationReasonCode);
+    return "prompt-owned";
+  }
   if (first.state === "prompt-rejected") throw first.error;
 
   // Extension commands such as `/workflow` launch their agent turn through
@@ -27,6 +30,7 @@ export async function waitForOperationStart(
           DEFERRED_OPERATION_START_GRACE_MS);
       })
     ]);
+    if (stream.lifecycleTerminationReasonCode) throw new Error(stream.lifecycleTerminationReasonCode);
     return "deferred";
   } finally {
     if (timer) clearTimeout(timer);

package/packages/piagent-webui/gateway/session-operation-watchdog.ts

@@ -0,0 +1,165 @@
+import { SessionOperationRetryCancellation } from "./session-operation-retry-control.ts";
+
+export type SessionOperationDeadlineReason = "operation-inactivity-timeout" | "operation-deadline-exceeded";
+
+export type SessionOperationDeadlinePolicy = Readonly<{
+  inactivityTimeoutMs: number;
+  maximumDurationMs: number;
+  terminationTimeoutMs: number;
+  projectionTimeoutMs: number;
+}>;
+
+export type SessionOperationWatchdogOptions = Partial<SessionOperationDeadlinePolicy>;
+export type BoundedResult<T> = { state: "settled"; value: T } | { state: "rejected"; error: unknown } | { state: "timeout" };
+export type SessionOperationTerminationResult = { state: "settled" } | { state: "quarantine"; reasonCode: string };
+
+export function bestEffortUnsubscribe(unsubscribe: (() => void) | null): void {
+  try { unsubscribe?.(); } catch { /* broken host cleanup cannot retain operation authority */ }
+}
+
+// A silent tool/provider gets 15 minutes. Any observed host event refreshes that
+// allowance, while the six-hour ceiling prevents an endless stream of progress
+// events from retaining runtime authority forever. Cleanup itself is separately
+// bounded so Stop and watchdog recovery cannot inherit the original hang.
+const DEFAULT_POLICY: SessionOperationDeadlinePolicy = Object.freeze({
+  inactivityTimeoutMs: 15 * 60_000,
+  maximumDurationMs: 6 * 60 * 60_000,
+  terminationTimeoutMs: 5_000,
+  projectionTimeoutMs: 2_500
+});
+const MAX_TIMEOUT_MS = 24 * 60 * 60_000;
+const TERMINATION_CLEANUP_FAILED = "operation-termination-cleanup-failed";
+
+function duration(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > MAX_TIMEOUT_MS) {
+    throw new Error("session-operation-watchdog-config-invalid");
+  }
+  return Number(value);
+}
+
+export function sessionOperationDeadlinePolicy(options: SessionOperationWatchdogOptions = {}): SessionOperationDeadlinePolicy {
+  const policy = {
+    inactivityTimeoutMs: duration(options.inactivityTimeoutMs, DEFAULT_POLICY.inactivityTimeoutMs),
+    maximumDurationMs: duration(options.maximumDurationMs, DEFAULT_POLICY.maximumDurationMs),
+    terminationTimeoutMs: duration(options.terminationTimeoutMs, DEFAULT_POLICY.terminationTimeoutMs),
+    projectionTimeoutMs: duration(options.projectionTimeoutMs, DEFAULT_POLICY.projectionTimeoutMs)
+  };
+  if (policy.projectionTimeoutMs > policy.terminationTimeoutMs) throw new Error("session-operation-watchdog-config-invalid");
+  return Object.freeze(policy);
+}
+
+export async function boundedResult<T>(promise: PromiseLike<T>, timeoutMs: number): Promise<BoundedResult<T>> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve(promise).then((value) => ({ state: "settled" as const, value }),
+        (error: unknown) => ({ state: "rejected" as const, error })),
+      new Promise<{ state: "timeout" }>((resolve) => { timer = setTimeout(() => resolve({ state: "timeout" }), timeoutMs); })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export class SessionOperationWatchdog {
+  readonly policy: SessionOperationDeadlinePolicy;
+  #idleTimer: ReturnType<typeof setTimeout> | null = null;
+  #maximumTimer: ReturnType<typeof setTimeout> | null = null;
+  #expire: ((reason: SessionOperationDeadlineReason) => void) | null = null;
+  #closed = false;
+  #termination: Promise<unknown> | null = null;
+
+  constructor(policy: SessionOperationDeadlinePolicy) { this.policy = policy; }
+  get terminating(): boolean { return this.#termination !== null; }
+
+  start(expire: (reason: SessionOperationDeadlineReason) => void): void {
+    if (this.#expire || this.#closed) throw new Error("session-operation-watchdog-state-invalid");
+    this.#expire = expire;
+    this.#armIdle();
+    this.#maximumTimer = setTimeout(() => this.#deadline("operation-deadline-exceeded"), this.policy.maximumDurationMs);
+    // An accepted operation owns live runtime work until it settles. Keep both
+    // deadline timers referenced so a headless Gateway cannot let Node exit
+    // while the provider promise is pending and silently skip recovery.
+  }
+
+  progress(): void {
+    if (this.#closed || !this.#expire) return;
+    this.#armIdle();
+  }
+
+  close(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#idleTimer) clearTimeout(this.#idleTimer);
+    if (this.#maximumTimer) clearTimeout(this.#maximumTimer);
+    this.#idleTimer = null; this.#maximumTimer = null; this.#expire = null;
+  }
+
+  terminate<T>(run: () => Promise<T>): Promise<T> {
+    if (!this.#termination) { this.close(); this.#termination = Promise.resolve().then(run); }
+    return this.#termination as Promise<T>;
+  }
+
+  #armIdle(): void {
+    if (this.#idleTimer) clearTimeout(this.#idleTimer);
+    this.#idleTimer = setTimeout(() => this.#deadline("operation-inactivity-timeout"), this.policy.inactivityTimeoutMs);
+  }
+
+  #deadline(reason: SessionOperationDeadlineReason): void {
+    if (this.#closed) return;
+    const expire = this.#expire; this.close(); expire?.(reason);
+  }
+}
+
+export function armSessionOperationWatchdog(options: {
+  watchdog: SessionOperationWatchdog;
+  subscribe(listener: (event: unknown) => void): unknown;
+  observe(event: unknown): unknown;
+  retrySession?: any;
+  expire(reason: SessionOperationDeadlineReason): void;
+}): () => void {
+  const retry = new SessionOperationRetryCancellation(options.retrySession);
+  const unsubscribe = options.subscribe((event) => {
+    options.watchdog.progress();
+    retry.observe(options.observe(event) as { retry?: unknown } | null | undefined);
+  });
+  if (typeof unsubscribe !== "function") throw new Error("session-operation-subscribe-invalid");
+  try { options.watchdog.start(options.expire); }
+  catch (error) { try { unsubscribe(); } catch { /* authority is quarantined by the caller */ } throw error; }
+  return () => { unsubscribe(); };
+}
+
+export async function terminateWatchedSessionOperation(options: {
+  watchdog: SessionOperationWatchdog;
+  settlement: "aborted" | "error";
+  reasonCode: string;
+  forcedReasonCode: string;
+  stream: { markAborted(reasonCode: string): void; markError(reasonCode: string): void;
+    forceLifecycleTermination(reasonCode: string): void };
+  completion(): Promise<void> | null;
+  settledCleanly(): boolean;
+  cancelApproval(reasonCode: string): void;
+  abortHost(): unknown;
+  clearQueue?(): void;
+}): Promise<SessionOperationTerminationResult> {
+  return await options.watchdog.terminate(async () => {
+    const mark = (reasonCode: string) => options.settlement === "aborted"
+      ? options.stream.markAborted(reasonCode) : options.stream.markError(reasonCode);
+    let cleanupFailed = false;
+    try { options.cancelApproval(options.reasonCode); } catch { cleanupFailed = true; }
+    try { options.clearQueue?.(); } catch { cleanupFailed = true; }
+    const terminalReason = cleanupFailed ? TERMINATION_CLEANUP_FAILED : options.reasonCode;
+    mark(terminalReason);
+    void Promise.resolve().then(options.abortHost).catch(() => undefined);
+    const completion = options.completion();
+    const completed = completion ? await boundedResult(completion, options.watchdog.policy.terminationTimeoutMs)
+      : { state: "timeout" as const };
+    if (!cleanupFailed && completed.state === "settled" && options.settledCleanly()) return { state: "settled" as const };
+    const quarantineReason = cleanupFailed ? TERMINATION_CLEANUP_FAILED : options.forcedReasonCode;
+    mark(quarantineReason); options.stream.forceLifecycleTermination(quarantineReason);
+    const forcedCompletion = options.completion();
+    if (forcedCompletion) await boundedResult(forcedCompletion, options.watchdog.policy.projectionTimeoutMs);
+    return { state: "quarantine" as const, reasonCode: quarantineReason };
+  });
+}

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

@@ -0,0 +1,45 @@
+import path from "node:path";
+
+import type { PiSessionInfo } from "./session-catalog.ts";
+import { preferAuthoritativePiagentGuard } from "./extension-authority.ts";
+import { rpcUiContext } from "./rpc-ui-context.ts";
+
+export type RuntimeHandle = { dispose(): Promise<void>; session?: any };
+export type RuntimeFactory = (info: PiSessionInfo, runtimeInstanceRef: string,
+  sessionManager?: any) => Promise<RuntimeHandle>;
+
+export function createProductionRuntimeFactory(options: {
+  host: any;
+  agentDir: string;
+  packageRoot: string;
+  modelRuntime?: any;
+}): RuntimeFactory {
+  return async (info, _runtimeInstanceRef, sessionManager) => {
+    const guard = path.join(options.packageRoot, "packages", "piagent-core", "extensions", "piagent-guard.ts");
+    const createRuntime = async ({ cwd, agentDir, sessionManager, sessionStartEvent }: any) => {
+      const services = await options.host.createAgentSessionServices({
+        cwd, agentDir, modelRuntime: options.modelRuntime,
+        resourceLoaderOptions: {
+          additionalExtensionPaths: [guard],
+          extensionsOverride: preferAuthoritativePiagentGuard(guard)
+        }
+      });
+      const extensionErrors = services.resourceLoader.getExtensions().errors;
+      if (extensionErrors.length) throw new Error("session-runtime-extension-load-failed");
+      const created = await options.host.createAgentSessionFromServices({ services, sessionManager, sessionStartEvent });
+      return { ...created, services, diagnostics: services.diagnostics };
+    };
+    const manager = sessionManager ?? options.host.SessionManager.open(info.path);
+    const runtime = await options.host.createAgentSessionRuntime(createRuntime, {
+      cwd: info.cwd,
+      agentDir: options.agentDir,
+      sessionManager: manager,
+      sessionStartEvent: { type: "session_start", reason: "resume", previousSessionFile: info.path }
+    });
+    const bind = async (session: any) => session.bindExtensions({ mode: "rpc", uiContext: rpcUiContext() });
+    runtime.setRebindSession(bind);
+    try { await bind(runtime.session); }
+    catch (error) { await runtime.dispose().catch(() => undefined); throw error; }
+    return runtime;
+  };
+}