pi-amq 0.1.1

package/integration/fleet-view.ts

@@ -0,0 +1,286 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Structural interaction pattern adapted from ZiChuanLan/pi-subagents-lite,
+ * itself forked from @tintinweb/pi-subagents v0.14.2.
+ * Copyright (c) 2026 tintinweb
+ * Copyright (c) 2026 lan
+ * Modified for pi-amq: render-only authoritative projection; no AgentManager.
+ */
+
+export type FleetLifecycle = "idle" | "busy" | "paused" | "offline" | "ambiguous";
+
+export interface FleetAgentRecord {
+  readonly id: string;
+  readonly handle: string;
+  readonly role: string;
+  readonly model: string;
+  readonly state: FleetLifecycle;
+  readonly spend: number | null;
+  readonly lastActivity: string;
+  readonly mode: "main" | "rpc" | "json";
+  readonly generation?: string;
+  readonly conversation?: readonly string[];
+}
+
+export interface FleetProjectionSource {
+  snapshot(): readonly FleetAgentRecord[];
+  subscribe(listener: () => void): () => void;
+}
+
+export class MutableFleetProjectionSource implements FleetProjectionSource {
+  #records: readonly FleetAgentRecord[];
+  readonly #listeners = new Set<() => void>();
+
+  constructor(initial: readonly FleetAgentRecord[]) {
+    this.#records = [...initial];
+  }
+
+  snapshot(): readonly FleetAgentRecord[] {
+    return this.#records.map((record) => ({ ...record }));
+  }
+
+  update(records: readonly FleetAgentRecord[]): void {
+    this.#records = [...records];
+    for (const listener of this.#listeners) listener();
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+}
+
+export class FleetListModel {
+  readonly #source: FleetProjectionSource;
+  #selected = 0;
+  #open = false;
+  #invalidations = 0;
+  readonly #unsubscribe: () => void;
+
+  constructor(source: FleetProjectionSource, invalidate: () => void) {
+    this.#source = source;
+    this.#unsubscribe = source.subscribe(() => {
+      const last = Math.max(0, this.#source.snapshot().length - 1);
+      this.#selected = Math.min(this.#selected, last);
+      this.#invalidations += 1;
+      invalidate();
+    });
+  }
+
+  get invalidations(): number {
+    return this.#invalidations;
+  }
+
+  get selected(): FleetAgentRecord | undefined {
+    return this.#source.snapshot()[this.#selected];
+  }
+
+  get open(): boolean {
+    return this.#open;
+  }
+
+  focus(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  move(delta: -1 | 1): void {
+    const count = this.#source.snapshot().length;
+    if (count === 0) return;
+    this.#selected = Math.max(0, Math.min(count - 1, this.#selected + delta));
+  }
+
+  render(): string[] {
+    const records = this.#source.snapshot();
+    if (records.length === 0) return ["Fleet: no active sessions"];
+    return [
+      "Fleet",
+      ...records.map((record, index) => {
+        const marker = this.#open && index === this.#selected ? ">" : " ";
+        const spend = record.spend === null ? "-" : `$${record.spend.toFixed(4)}`;
+        return `${marker} ${record.handle}/${record.role} ${record.model} ${record.state} ${spend} ${record.lastActivity}`;
+      }),
+    ];
+  }
+
+  dispose(): void {
+    this.#unsubscribe();
+  }
+}
+
+export type FleetInputAction =
+  | { readonly consume: false }
+  | { readonly consume: true; readonly action: "focus" | "move" | "detail" | "close" };
+
+export function handleFleetInput(options: {
+  readonly data: string;
+  readonly editorText: string;
+  readonly list: FleetListModel;
+}): FleetInputAction {
+  if (options.editorText !== "") return { consume: false };
+  const { data, list } = options;
+  if (!list.open && isDown(data)) {
+    list.focus();
+    return { consume: true, action: "focus" };
+  }
+  if (!list.open) return { consume: false };
+  if (isDown(data)) {
+    list.move(1);
+    return { consume: true, action: "move" };
+  }
+  if (isUp(data)) {
+    list.move(-1);
+    return { consume: true, action: "move" };
+  }
+  if (data === "\r" || data === "\n") return { consume: true, action: "detail" };
+  if (data === "\u001b") {
+    list.close();
+    return { consume: true, action: "close" };
+  }
+  return { consume: false };
+}
+
+export function renderFleetDetail(record: FleetAgentRecord): string[] {
+  return [
+    `${record.handle}/${record.role} (${record.state})`,
+    `model=${record.model} activity=${record.lastActivity}`,
+    ...(record.mode === "json" ? ["one-shot worker, cannot steer"] : []),
+    "",
+    ...(record.conversation ?? ["No conversation projection available."]),
+  ];
+}
+
+export function canSteerFleetRecord(
+  record: FleetAgentRecord,
+  currentGeneration: string | undefined,
+): boolean {
+  return record.mode === "rpc"
+    && record.generation !== undefined
+    && record.generation === currentGeneration;
+}
+
+export type FleetControlStatus = "idle" | "composing" | "requested" | "observed" | "indeterminate";
+
+export class FleetDetailController {
+  readonly #recordId: string;
+  readonly #generation: string | undefined;
+  readonly #resolve: () => FleetAgentRecord | undefined;
+  readonly #steer: (recordId: string, generation: string, message: string) => Promise<void>;
+  readonly #cancel: (recordId: string, generation: string) => Promise<void>;
+  #composer = "";
+  #status: FleetControlStatus = "idle";
+  #diagnostic = "";
+  #xArmed = false;
+
+  constructor(options: {
+    readonly record: FleetAgentRecord;
+    readonly resolve: () => FleetAgentRecord | undefined;
+    readonly steer: (recordId: string, generation: string, message: string) => Promise<void>;
+    readonly cancel: (recordId: string, generation: string) => Promise<void>;
+  }) {
+    this.#recordId = options.record.id;
+    this.#generation = options.record.generation;
+    this.#resolve = options.resolve;
+    this.#steer = options.steer;
+    this.#cancel = options.cancel;
+  }
+
+  get status(): FleetControlStatus {
+    return this.#status;
+  }
+
+  render(): string[] {
+    const record = this.#resolve();
+    if (!record) return ["Worker projection disappeared.", "control=indeterminate"];
+    const controls = record.mode === "rpc"
+      ? ["Enter: compose steer · x,x: stop · Esc: close"]
+      : ["one-shot worker, cannot steer", "x,x: stop · Esc: close"];
+    return [
+      ...renderFleetDetail(record),
+      "",
+      ...controls,
+      ...(this.#status === "composing" ? [`steer> ${this.#composer}`] : []),
+      ...(this.#status === "idle" ? [] : [`control=${this.#status}${this.#diagnostic ? `: ${this.#diagnostic}` : ""}`]),
+    ];
+  }
+
+  handleInput(data: string): { readonly close: boolean; readonly consumed: boolean } {
+    if (data === "\u001b") {
+      if (this.#status === "composing") {
+        this.#composer = "";
+        this.#status = "idle";
+        return { close: false, consumed: true };
+      }
+      return { close: true, consumed: true };
+    }
+    if (this.#status === "composing") {
+      if (data === "\r" || data === "\n") {
+        const message = this.#composer.trim();
+        this.#composer = "";
+        if (message) void this.#request("steer", message);
+        else this.#status = "idle";
+        return { close: false, consumed: true };
+      }
+      if (data === "\u007f") this.#composer = this.#composer.slice(0, -1);
+      else if (!data.startsWith("\u001b")) this.#composer += data;
+      return { close: false, consumed: true };
+    }
+    if (data === "\r" || data === "\n") {
+      const record = this.#resolve();
+      if (record?.mode === "rpc" && this.#isGenerationCurrent(record)) {
+        this.#status = "composing";
+      } else {
+        this.#status = "indeterminate";
+        this.#diagnostic = record?.mode === "json"
+          ? "one-shot worker, cannot steer"
+          : "worker generation changed";
+      }
+      return { close: false, consumed: true };
+    }
+    if (data === "x") {
+      if (this.#xArmed) {
+        this.#xArmed = false;
+        void this.#request("cancel");
+      } else {
+        this.#xArmed = true;
+      }
+      return { close: false, consumed: true };
+    }
+    this.#xArmed = false;
+    return { close: false, consumed: false };
+  }
+
+  #isGenerationCurrent(record: FleetAgentRecord): record is FleetAgentRecord & { generation: string } {
+    return this.#generation !== undefined && record.generation === this.#generation;
+  }
+
+  async #request(kind: "steer" | "cancel", message?: string): Promise<void> {
+    const record = this.#resolve();
+    if (!record || !this.#isGenerationCurrent(record)) {
+      this.#status = "indeterminate";
+      this.#diagnostic = "worker generation changed";
+      return;
+    }
+    this.#status = "requested";
+    this.#diagnostic = kind;
+    try {
+      if (kind === "steer") await this.#steer(this.#recordId, record.generation, message!);
+      else await this.#cancel(this.#recordId, record.generation);
+      this.#status = "observed";
+    } catch (error) {
+      this.#status = "indeterminate";
+      this.#diagnostic = error instanceof Error ? error.message : String(error);
+    }
+  }
+}
+
+function isDown(data: string): boolean {
+  return data === "\u001b[B";
+}
+
+function isUp(data: string): boolean {
+  return data === "\u001b[A";
+}

package/integration/fresh-session-dispatcher.ts

@@ -0,0 +1,166 @@
+import type { AmqMessage } from "../transport/amq-message.js";
+
+export interface FreshSessionProjectionEvidence {
+  readonly messageId: string;
+  readonly sessionId: string;
+  readonly diskVisible: boolean;
+}
+
+export interface FreshSessionCapabilityProbe {
+  probe(): Promise<
+    | { readonly capable: true }
+    | { readonly capable: false; readonly reason: string; readonly dependencies: readonly string[] }
+  >;
+  dispatch(
+    message: AmqMessage,
+    signal?: AbortSignal,
+    canReplaceSession?: (signal?: AbortSignal) => Promise<boolean>,
+  ): Promise<FreshSessionProjectionEvidence>;
+}
+
+export interface FreshSessionReplacementPort {
+  waitForIdle(signal?: AbortSignal): Promise<void>;
+  replace(
+    message: AmqMessage,
+    signal?: AbortSignal,
+  ): Promise<{
+    readonly cancelled: boolean;
+    readonly projection?: FreshSessionProjectionEvidence;
+  }>;
+}
+
+export class FreshSessionInterlockError extends Error {
+  constructor() {
+    super("worker_runtime_active");
+    this.name = "FreshSessionInterlockError";
+  }
+}
+
+/** Full capable path; a real adapter must bind replace() to replacement-context-only session control. */
+export class CommandContextFreshSessionCapability implements FreshSessionCapabilityProbe {
+  readonly #port: FreshSessionReplacementPort;
+
+  constructor(port: FreshSessionReplacementPort) {
+    this.#port = port;
+  }
+
+  async probe(): Promise<{ readonly capable: true }> {
+    return { capable: true };
+  }
+
+  async dispatch(
+    message: AmqMessage,
+    signal?: AbortSignal,
+    canReplaceSession: (signal?: AbortSignal) => Promise<boolean> = async () => true,
+  ): Promise<FreshSessionProjectionEvidence> {
+    if (!await canReplaceSession(signal)) throw new FreshSessionInterlockError();
+    await this.#port.waitForIdle(signal);
+    throwIfAborted(signal);
+    if (!await canReplaceSession(signal)) throw new FreshSessionInterlockError();
+    const replaced = await this.#port.replace(message, signal);
+    if (replaced.cancelled) throw new Error("Fresh-session replacement was cancelled");
+    // diskVisible may legitimately be false here: pi persists a fresh session's file lazily
+    // (only once its first assistant entry arrives), so an in-memory-only projection is a
+    // valid deferred state, not a failure. The journal keeps the record pending with its
+    // target session set until reconciliation later observes the disk-visible projection.
+    if (!replaced.projection || replaced.projection.messageId !== message.header.id) {
+      throw new Error("Fresh-session replacement lacks a matching AMQ projection");
+    }
+    return replaced.projection;
+  }
+}
+
+export interface FreshSessionPolicy {
+  readonly trustedProject: boolean;
+  readonly allowlisted: (sender: string, project: string) => boolean;
+  readonly confirm?: (message: AmqMessage, signal?: AbortSignal) => Promise<boolean>;
+  readonly canReplaceSession: (signal?: AbortSignal) => Promise<boolean>;
+  readonly notifyOnce?: (message: string) => void;
+}
+
+export type FreshSessionDecision =
+  | { readonly kind: "ordinary" }
+  | { readonly kind: "refused"; readonly reason: "not-authorized" | "worker-runtime-active" }
+  | { readonly kind: "pending"; readonly reason: string; readonly action: "/amq ingest" }
+  | { readonly kind: "dispatched"; readonly projection: FreshSessionProjectionEvidence };
+
+/** Serializes privileged session replacement behind explicit policy and capability ports. */
+export class FreshSessionDispatcher {
+  readonly #capability: FreshSessionCapabilityProbe;
+  readonly #policy: FreshSessionPolicy;
+  #tail: Promise<void> = Promise.resolve();
+  #notifiedIncapable = false;
+
+  constructor(options: {
+    readonly capability: FreshSessionCapabilityProbe;
+    readonly policy: FreshSessionPolicy;
+  }) {
+    this.#capability = options.capability;
+    this.#policy = options.policy;
+  }
+
+  dispatch(message: AmqMessage, signal?: AbortSignal): Promise<FreshSessionDecision> {
+    const task = this.#tail.then(() => this.#dispatch(message, signal));
+    this.#tail = task.then(() => undefined, () => undefined);
+    return task;
+  }
+
+  async #dispatch(message: AmqMessage, signal?: AbortSignal): Promise<FreshSessionDecision> {
+    if (!requestsFreshSession(message)) return { kind: "ordinary" };
+    throwIfAborted(signal);
+
+    const allowlisted = this.#policy.trustedProject
+      && this.#policy.allowlisted(message.header.from, message.header.fromProject);
+    const confirmed = allowlisted
+      ? true
+      : this.#policy.confirm
+        ? await this.#policy.confirm(message, signal)
+        : false;
+    if (!confirmed) return { kind: "refused", reason: "not-authorized" };
+    if (!await this.#policy.canReplaceSession(signal)) {
+      return { kind: "refused", reason: "worker-runtime-active" };
+    }
+
+    const capability = await this.#capability.probe();
+    if (!capability.capable) {
+      const reason = `${capability.reason}; requires ${capability.dependencies.join(" and ")}`;
+      if (!this.#notifiedIncapable) {
+        this.#notifiedIncapable = true;
+        this.#policy.notifyOnce?.(`Fresh-session delivery is pending: ${reason}. Use /amq ingest.`);
+      }
+      return { kind: "pending", reason, action: "/amq ingest" };
+    }
+
+    try {
+      const projection = await this.#capability.dispatch(
+        message,
+        signal,
+        this.#policy.canReplaceSession,
+      );
+      if (projection.messageId !== message.header.id) {
+        throw new Error("Fresh-session capability returned an unrelated projection evidence");
+      }
+      return { kind: "dispatched", projection };
+    } catch (error) {
+      if (error instanceof FreshSessionInterlockError) {
+        return { kind: "refused", reason: "worker-runtime-active" };
+      }
+      throw error;
+    }
+  }
+}
+
+export function requestsFreshSession(message: AmqMessage): boolean {
+  const piAmq = message.header.context.pi_amq;
+  return Boolean(
+    piAmq
+    && typeof piAmq === "object"
+    && !Array.isArray(piAmq)
+    && (piAmq as Record<string, unknown>).delivery === "fresh-session",
+  );
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Fresh-session dispatch was cancelled");
+}