pim-agent 0.10.0 → 0.12.0

package/packages/server/src/SessionStream.ts

@@ -4,10 +4,12 @@ import { PickerService } from "#core/picker/PickerService";
 import { MessageText } from "#core/session/MessageText";
 import type { LeaseState, SessionHost } from "#core/session/SessionHost";
 import { SessionLease, type LeaseRecord } from "#core/session/SessionLease";
+import type { SessionUi, UiAsk } from "#core/session/SessionUi";
 import { FileWatch } from "#core/shared/FileWatch";
 import { GitMonitor } from "#core/shared/GitMonitor";
 import { Tools } from "#core/shared/Tools";
-import type { ToolView } from "#core/view/ViewBlock";
+import type { NoticeSeverity, ToolView } from "#core/view/ViewBlock";
+import type { Command } from "#protocol/Command";
 import type {
   EphemeralEvent,
   ServerEvent,
@@ -17,6 +19,21 @@ import { SessionProjection } from "./SessionProjection";
 
 export type StreamListener = (event: ServerEvent) => void;
 
+/** What one client sent back for a `ui_request`; a dismissal is `cancelled`. */
+export type UiAnswer = Omit<
+  Extract<Command, { readonly type: "ui_response" }>,
+  "id" | "type" | "sessionId" | "requestId"
+>;
+
+type PendingRequest = {
+  /** Kept whole: a client that reattaches inside the grace is shown the dialog again. */
+  readonly asked: Extract<EphemeralEvent, { readonly type: "ui_request" }>;
+  /** Answers the waiting extension; only the first call of the first caller lands. */
+  readonly settle: (answer: UiAnswer | undefined, because?: string) => void;
+  readonly expiry: ReturnType<typeof setTimeout>;
+  grace: ReturnType<typeof setTimeout> | undefined;
+};
+
 type LiveTool = {
   readonly callId: string;
   readonly name: string;
@@ -46,8 +63,18 @@ export type SessionStreamDeps = {
    * reports nothing rather than guessing from itself.
    */
   readonly repoBusy?: () => boolean;
+  /** Longest a dialog may hold an extension waiting; defaults to `REQUEST_CEILING_MS`. */
+  readonly requestCeilingMs?: number;
+  /** How long a pending dialog outlives its last reader; defaults to `DETACH_GRACE_MS`. */
+  readonly detachGraceMs?: number;
 };
 
+/** No extension may be parked on a human forever, whatever it asked for; `opts.timeout` still wins when shorter. */
+const REQUEST_CEILING_MS = 180_000;
+
+/** A reload, a tunnel blip and a phone unlock all read as a detach, and all three are back inside this. */
+const DETACH_GRACE_MS = 15_000;
+
 function sameLease(a: LeaseState, b: LeaseState): boolean {
   return (
     a.writable === b.writable &&
@@ -57,16 +84,20 @@ function sameLease(a: LeaseState, b: LeaseState): boolean {
 }
 
 /** One session's view of the world, shared by every client attached to it and kept running when none are. */
-export class SessionStream {
+export class SessionStream implements SessionUi {
   public readonly sessionId: string;
   public readonly host: SessionHost;
   public readonly picker: PickerService;
   private readonly sessionPath: string;
   private readonly projection: SessionProjection;
   private readonly listeners = new Set<StreamListener>();
+  private readonly observers = new Set<StreamListener>();
   private readonly pollMs: number | undefined;
   private readonly git: GitMonitor;
   private readonly repoBusy: (() => boolean) | undefined;
+  private readonly requestCeilingMs: number;
+  private readonly detachGraceMs: number;
+  private readonly pending = new Map<string, PendingRequest>();
   private liveTurn: LiveMessage[] = [];
   private unsubscribe: (() => void) | undefined;
   private unsubscribeLease: (() => void) | undefined;
@@ -78,6 +109,8 @@ export class SessionStream {
   private drainQueued = false;
   private sentSeq = 0;
   private liveMessageId = 0;
+  private uiSeq = 0;
+  private readonly dispatching: string[] = [];
   private turnStartedAt = 0;
   private gitCwd: string | undefined;
   private gitStop: (() => void) | undefined;
@@ -95,6 +128,8 @@ export class SessionStream {
     this.pollMs = deps.pollMs;
     this.git = deps.git ?? new GitMonitor();
     this.repoBusy = deps.repoBusy;
+    this.requestCeilingMs = deps.requestCeilingMs ?? REQUEST_CEILING_MS;
+    this.detachGraceMs = deps.detachGraceMs ?? DETACH_GRACE_MS;
     this.projection = new SessionProjection(sessionPath, () => host.cwd);
     this.picker = new PickerService({
       cwd: () => host.cwd,
@@ -194,11 +229,187 @@ export class SessionStream {
 
   public subscribe(listener: StreamListener): () => void {
     this.listeners.add(listener);
+    this.holdRequests();
     return () => {
       this.listeners.delete(listener);
+      this.holdRequests();
+    };
+  }
+
+  /**
+   * Hears everything a client hears without counting as one: the server's own
+   * bookkeeping must not make a session nobody is reading look attended, or
+   * the rules below park an extension on a dialog with no eyes on it.
+   */
+  public observe(listener: StreamListener): () => void {
+    this.observers.add(listener);
+    return () => {
+      this.observers.delete(listener);
     };
   }
 
+  /**
+   * Runs `run` as the answer to something the user typed, so anything it says
+   * or asks reaches the client under `command`'s name. A stack rather than a
+   * name: one command handler may prompt another, and the innermost is the
+   * one speaking.
+   */
+  public async dispatch<T>(command: string, run: () => Promise<T>): Promise<T> {
+    this.dispatching.push(command);
+    try {
+      return await run();
+    } finally {
+      this.dispatching.pop();
+    }
+  }
+
+  /** Fire-and-forget: with nobody attached the notice is dropped rather than held. */
+  public notify(text: string, severity: NoticeSeverity): void {
+    this.emit({
+      type: "ui_notice",
+      id: this.nextUiId("notice"),
+      severity,
+      text,
+      ...this.asked(),
+    });
+  }
+
+  /** Whose words these are: the command being dispatched, if any is. */
+  private asked(): { readonly command?: string } {
+    const command = this.dispatching.at(-1);
+    return command === undefined ? {} : { command };
+  }
+
+  public async select(
+    title: string,
+    options: readonly string[],
+    opts?: UiAsk
+  ): Promise<string | undefined> {
+    return (
+      await this.ask({ method: "select", title, options: [...options] }, opts)
+    )?.value;
+  }
+
+  public async confirm(
+    title: string,
+    message: string,
+    opts?: UiAsk
+  ): Promise<boolean> {
+    return (
+      (await this.ask({ method: "confirm", title, message }, opts))
+        ?.confirmed === true
+    );
+  }
+
+  public async input(
+    title: string,
+    placeholder?: string,
+    opts?: UiAsk
+  ): Promise<string | undefined> {
+    return (
+      await this.ask(
+        {
+          method: "input",
+          title,
+          ...(placeholder === undefined ? {} : { placeholder }),
+        },
+        opts
+      )
+    )?.value;
+  }
+
+  /** Whether the answer was taken; a second one for the same request is refused. */
+  public answer(requestId: string, answer: UiAnswer): boolean {
+    const request = this.pending.get(requestId);
+    if (request === undefined) {
+      return false;
+    }
+    request.settle(answer);
+    return true;
+  }
+
+  /** The answer as the client sent it, or `undefined` where it was cancelled, timed out or never asked. */
+  private ask(
+    request: Omit<
+      Extract<ServerEvent, { readonly type: "ui_request" }>,
+      "type" | "requestId" | "command"
+    >,
+    opts: UiAsk | undefined
+  ): Promise<UiAnswer | undefined> {
+    // A headless session may not park an extension on a dialog nobody can see.
+    if (this.listeners.size === 0) {
+      this.answered(request.title, "nobody was attached");
+      return Promise.resolve(undefined);
+    }
+    const requestId = this.nextUiId("request");
+    const waitMs = Math.min(this.requestCeilingMs, opts?.timeout ?? Infinity);
+    const asked = {
+      ...request,
+      ...this.asked(),
+      type: "ui_request",
+      requestId,
+    } as const;
+    return new Promise<UiAnswer | undefined>((resolve) => {
+      const settle = (answer: UiAnswer | undefined, because?: string): void => {
+        const entry = this.pending.get(requestId);
+        if (entry === undefined) {
+          return;
+        }
+        this.pending.delete(requestId);
+        clearTimeout(entry.expiry);
+        clearTimeout(entry.grace);
+        opts?.signal?.removeEventListener("abort", abort);
+        this.emit({ type: "ui_request_done", requestId });
+        if (because !== undefined) {
+          this.answered(asked.title, because);
+        }
+        resolve(answer?.cancelled === true ? undefined : answer);
+      };
+      const abort = (): void => {
+        settle(undefined, "the extension withdrew it");
+      };
+      this.pending.set(requestId, {
+        asked,
+        settle,
+        expiry: setTimeout(() => {
+          settle(undefined, "it timed out");
+        }, waitMs),
+        grace: undefined,
+      });
+      opts?.signal?.addEventListener("abort", abort, { once: true });
+      this.emit(asked);
+      // A listener is never called for a signal that was already spent.
+      if (opts?.signal?.aborted === true) {
+        abort();
+      }
+    });
+  }
+
+  /** A dialog answered by the server is never silent: the human is told what was decided for them. */
+  private answered(title: string, why: string): void {
+    this.notify(`Answered “${title}” for you: ${why}.`, "warn");
+  }
+
+  /** The last reader leaving starts the grace; one arriving inside it calls the whole thing off. */
+  private holdRequests(): void {
+    const detached = this.listeners.size === 0;
+    for (const [requestId, request] of this.pending) {
+      if (!detached) {
+        clearTimeout(request.grace);
+        request.grace = undefined;
+        continue;
+      }
+      request.grace ??= setTimeout(() => {
+        this.pending.get(requestId)?.settle(undefined, "everyone had left");
+      }, this.detachGraceMs);
+    }
+  }
+
+  private nextUiId(kind: "notice" | "request"): string {
+    this.uiSeq += 1;
+    return `${this.sessionId}:${kind}:${this.uiSeq}`;
+  }
+
   /** Whether `callId` names a tool this session is still running, log written or not. */
   public isRunning(callId: string): boolean {
     return this.findTool(callId)?.done === false;
@@ -243,6 +454,11 @@ export class SessionStream {
         }
       }
     }
+    // A dialog is only ever answered by whoever is attached now, so a client
+    // arriving mid-question is handed it rather than left waiting on a grace.
+    for (const request of this.pending.values()) {
+      events.push(request.asked);
+    }
     events.push(this.sessionState());
     return events;
   }
@@ -346,7 +562,12 @@ export class SessionStream {
     this.unsubscribeForeign?.();
     this.unsubscribeForeign = undefined;
     this.watchFiles(false);
+    // Deleting the entry each settle clears is what a Map iterator is allowed to outlive.
+    for (const request of this.pending.values()) {
+      request.settle(undefined, "the session stopped");
+    }
     this.listeners.clear();
+    this.observers.clear();
   }
 
   private onAgentEvent(event: AgentSessionEvent): void {
@@ -620,6 +841,11 @@ export class SessionStream {
   }
 
   private emit(event: ServerEvent): void {
+    // Observers first: the bookkeeping one does may broadcast server-wide, and
+    // that belongs ahead of the frame that caused it on every socket.
+    for (const observer of this.observers) {
+      observer(event);
+    }
     for (const listener of this.listeners) {
       listener(event);
     }

package/packages/server/src/WsGateway.ts

@@ -9,6 +9,11 @@ import { Directories } from "#core/shared/Directories";
 import type { DirectoryListing } from "#core/shared/Directories";
 import { Git, type GitBranch } from "#core/shared/Git";
 import { GitMonitor, type GitRun } from "#core/shared/GitMonitor";
+import {
+  PiExtensions,
+  type ExtensionEntry,
+  type ExtensionScope,
+} from "#core/shared/PiExtensions";
 import { RepoDiff } from "#core/shared/RepoDiff";
 import { ReadCursors } from "#core/session/ReadCursors";
 import type { SessionHost } from "#core/session/SessionHost";
@@ -51,6 +56,10 @@ export type WsGatewayDeps = {
   readonly sessionMetaPath?: string;
   /** How often a session file is polled where `fs.watch` says nothing; the default is a second. */
   readonly pollMs?: number;
+  /** Longest a dialog may hold an extension waiting; the default is `SessionStream`'s three minutes. */
+  readonly requestCeilingMs?: number;
+  /** How long a pending dialog outlives its last reader; the default is `SessionStream`'s fifteen seconds. */
+  readonly detachGraceMs?: number;
   /** The built web client; defaults to the bundle shipped beside this package. */
   readonly clientDir?: string;
   /** Runs the update a `reload` asks for, reporting each step as it starts. */
@@ -69,6 +78,7 @@ type Outcome = {
   readonly scanned?: number;
   readonly models?: readonly ModelView[];
   readonly thinkingLevels?: readonly string[];
+  readonly extensions?: readonly ExtensionEntry[];
   readonly directory?: DirectoryListing;
   readonly branches?: readonly GitBranch[];
   readonly commit?: { readonly sha: string };
@@ -76,6 +86,8 @@ type Outcome = {
   readonly fileDiff?: FileDiff;
   readonly fileLines?: FileLines;
   readonly restored?: readonly string[];
+  /** The message was dispatched as an extension command: no turn started, no entry written. */
+  readonly dispatched?: boolean;
   readonly after?: () => void;
 };
 
@@ -92,6 +104,15 @@ export const DEFAULT_HOSTNAME = "127.0.0.1";
 // Bun 1.3.14 never frees the slot of a server-closed socket, so an unbounded `Server.stop(true)` hangs.
 const STOP_GRACE_MS = 250;
 
+/**
+ * Pi's own dispatch parse, three lines of `_tryExecuteExtensionCommand`
+ * (`agent-session.js:954`); a pi upgrade re-verifies it.
+ */
+function commandNameOf(text: string): string {
+  const spaceIndex = text.indexOf(" ");
+  return spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+}
+
 /** The transport half of pim-server: a WebSocket endpoint over the session runtime in `core`. */
 export class WsGateway {
   private readonly registry: SessionRegistry;
@@ -111,15 +132,26 @@ export class WsGateway {
   private readonly reloader: Reloader;
   private readonly git = new GitMonitor();
   private readonly pollMs: number | undefined;
+  private readonly requestCeilingMs: number | undefined;
+  private readonly detachGraceMs: number | undefined;
   private readonly busyRepos = new Set<string>();
   private versionsRead: Promise<readonly [string, string]> | undefined;
   private server: Server<undefined> | undefined;
 
   public constructor(deps: WsGatewayDeps) {
     this.registry = deps.registry;
+    // `SessionStream` is the sink, so the whole routing is a lookup: a host
+    // outlives the stream that speaks for it, and pi asks per call.
+    this.registry.setUi((host) =>
+      host.sessionId === undefined
+        ? undefined
+        : this.streams.get(host.sessionId)
+    );
     this.hostname = deps.hostname ?? DEFAULT_HOSTNAME;
     this.requestedPort = deps.port ?? DEFAULT_PORT;
     this.pollMs = deps.pollMs;
+    this.requestCeilingMs = deps.requestCeilingMs;
+    this.detachGraceMs = deps.detachGraceMs;
     this.uploads = new AttachmentEndpoint(
       deps.attachmentsRoot === undefined ? {} : { root: deps.attachmentsRoot }
     );
@@ -362,8 +394,26 @@ export class WsGateway {
           thinkingLevels:
             this.streamFor(connection)?.host.supportedThinkingLevels ?? [],
         };
+      case "list_extensions":
+        return {
+          extensions: await PiExtensions.list(this.scopeFor(connection)),
+        };
+      case "set_extension":
+        await PiExtensions.setEnabled(
+          command.extensionId,
+          command.value,
+          this.scopeFor(connection)
+        );
+        return {
+          after: () => {
+            this.rebuildAgents();
+          },
+        };
       case "list_dirs":
         return { directory: await Directories.list(command.path) };
+      case "create_dir":
+        await Directories.create(command.path);
+        return {};
       case "refresh_git": {
         const stream = this.requireStream(connection);
         await stream.refreshGit(command.fetch === true);
@@ -425,8 +475,16 @@ export class WsGateway {
       case "reload":
         return this.reload(command.force === true);
       case "user_message":
-        this.promptWithAttachments(this.requireStream(connection), command);
-        return {};
+        return await this.promptWithAttachments(
+          this.requireStream(connection),
+          command
+        );
+      case "ui_response": {
+        const stream = this.requireStream(connection);
+        return stream.answer(command.requestId, command)
+          ? {}
+          : { error: `no request ${command.requestId} is waiting` };
+      }
       case "cancel": {
         const { cancelled, restored } =
           await this.requireStream(connection).host.cancel();
@@ -492,6 +550,27 @@ export class WsGateway {
     return sessionId ? this.streams.get(sessionId) : undefined;
   }
 
+  /** A session's directory decides which project extensions are listed; a connection without one reads this process's. */
+  private scopeFor(connection: ClientConnection): ExtensionScope {
+    return {
+      cwd: this.streamFor(connection)?.host.cwd ?? process.cwd(),
+      agentDir: this.registry.agentDir,
+    };
+  }
+
+  private rebuildAgents(): void {
+    for (const stream of this.streams.values()) {
+      const { host } = stream;
+      // Through the turn queue: detaching the agent under a running turn kills it.
+      void host
+        .serialize(() => host.invalidate())
+        .catch((err: unknown) => {
+          this.failed(stream, err, "extension reload");
+        });
+    }
+    this.broadcast({ type: "extensions_changed" });
+  }
+
   private requireStream(connection: ClientConnection): SessionStream {
     const stream = this.streamFor(connection);
     if (!stream) {
@@ -732,10 +811,14 @@ export class WsGateway {
       git: this.git,
       repoBusy: () => this.repoBusy(host.cwd),
       pollMs: this.pollMs,
+      requestCeilingMs: this.requestCeilingMs,
+      detachGraceMs: this.detachGraceMs,
     });
     stream.start();
     this.catalogue.track(id, host.status);
-    stream.subscribe((event) => {
+    // Observed rather than subscribed: this never leaves, and a reader that
+    // never leaves is a session that is never detached.
+    stream.observe((event) => {
       if (event.type === "session_state") {
         this.catalogue.onStatus(id, event.status);
         this.syncRepoBusy(stream.host.cwd, id);
@@ -745,17 +828,70 @@ export class WsGateway {
     return stream;
   }
 
-  private promptWithAttachments(
+  private async promptWithAttachments(
     stream: SessionStream,
     command: Command & { readonly type: "user_message" }
-  ): void {
+  ): Promise<Outcome> {
+    // Trimmed once, here: pi dispatches on the text it is handed after the
+    // fallthrough trims it, so a client that does not trim would otherwise
+    // slip a command past this check and into pi's own.
+    const text = command.text.trim();
+    // Read before anything is rendered: what a command is, is its own text.
+    const dispatched = await this.dispatchCommand(stream, text);
     const taken = this.uploads.take(
       stream.sessionId,
       (command.attachments ?? []).map((ref) => ref.id)
     );
+    // A slash command carries no pictures; the uploads are still taken, so the
+    // endpoint stops holding their bytes for the rest of the session.
+    if (dispatched) {
+      return { dispatched: true };
+    }
     const { lines, images } = Attachments.render(taken);
-    const text = [command.text, ...lines].filter(Boolean).join("\n\n").trim();
-    this.prompt(stream, text, images);
+    this.prompt(stream, [text, ...lines].filter(Boolean).join("\n\n"), images);
+    return {};
+  }
+
+  /**
+   * Whether `text` names an extension command, having started it if it does.
+   * Only the decision is awaited: the handler runs on beyond the ack, exactly
+   * as a turn does.
+   */
+  private async dispatchCommand(
+    stream: SessionStream,
+    text: string
+  ): Promise<boolean> {
+    const host = stream.host;
+    if (!text.startsWith("/")) {
+      return false;
+    }
+    // The picker offers extension commands only once an agent exists, so this
+    // is someone typing from memory; cold is idle, so nothing is queued behind it.
+    const agent = host.agentSession ?? (await host.ensureAgent());
+    const name = commandNameOf(text);
+    if (agent.extensionRunner.getCommand(name) === undefined) {
+      return false;
+    }
+    void stream
+      .dispatch(`/${name}`, async () => {
+        // Prompted whole, never merged into the queue: a merged string starts
+        // with the earlier message, and pi reads the leading `/` before it
+        // looks at `isStreaming` — so the turn we are holding dispatches it.
+        if (host.isStreaming) {
+          await agent.prompt(text, {
+            streamingBehavior: "steer",
+            source: "rpc",
+          });
+          return;
+        }
+        await host.run(async (session) => {
+          await session.prompt(text, { source: "rpc" });
+        });
+      })
+      .catch((err: unknown) => {
+        this.failed(stream, err, "command");
+      });
+    return true;
   }
 
   // Merge into the queued message: pi holds at most one, so a second queued send would be unreachable.
@@ -767,13 +903,6 @@ export class WsGateway {
     const attached = images.length === 0 ? {} : { images: [...images] };
     const host = stream.host;
     const agent = host.agentSession;
-    const failed = (err: unknown, what: string): void => {
-      console.error(`[gateway] ${what} failed:`, err);
-      stream.push({
-        type: "error",
-        message: (err as Error).message || String(err),
-      });
-    };
     if (agent && host.isStreaming) {
       const queued = [...host.takeBack(), text].join("\n\n");
       void agent
@@ -783,7 +912,7 @@ export class WsGateway {
           ...attached,
         })
         .catch((err: unknown) => {
-          failed(err, "steer");
+          this.failed(stream, err, "steer");
         });
       return;
     }
@@ -792,7 +921,15 @@ export class WsGateway {
         await session.prompt(text, { source: "rpc", ...attached });
       })
       .catch((err: unknown) => {
-        failed(err, "turn");
+        this.failed(stream, err, "turn");
       });
   }
+
+  private failed(stream: SessionStream, err: unknown, what: string): void {
+    console.error(`[gateway] ${what} failed:`, err);
+    stream.push({
+      type: "error",
+      message: (err as Error).message || String(err),
+    });
+  }
 }

package/packages/server/src/probe.ts

@@ -33,6 +33,8 @@ const USAGE = `pim probe — CLI client for pim-server, dumps every frame as JSO
   --pin <path>             pin a working directory, so its sessions sort first
   --unpin <path>           unpin it again
   --list-models            print the models this server can switch to
+  --list-extensions        print the extensions this server can switch
+  --set-extension <id>     switch one extension off, or on with --on
   --upload <path>          transfer a local file to the server, attach it to
                            --prompt (repeatable)
   --cancel                 cancel the current turn
@@ -61,6 +63,9 @@ const { values } = parseArgs({
     pin: { type: "string" },
     unpin: { type: "string" },
     "list-models": { type: "boolean", default: false },
+    "list-extensions": { type: "boolean", default: false },
+    "set-extension": { type: "string" },
+    on: { type: "boolean", default: false },
     upload: { type: "string", multiple: true },
     cancel: { type: "boolean", default: false },
     dequeue: { type: "boolean", default: false },
@@ -129,6 +134,17 @@ if (values["list-sessions"]) {
 if (values["list-models"]) {
   process.stdout.write(`${JSON.stringify(await probe.listModels())}\n`);
 }
+if (values["list-extensions"]) {
+  for (const entry of await probe.listExtensions()) {
+    process.stdout.write(`${JSON.stringify(entry)}\n`);
+  }
+}
+if (values["set-extension"] !== undefined) {
+  await probe.setExtension(values["set-extension"], values.on);
+  process.stderr.write(
+    `set-extension: ${values["set-extension"]} ${values.on ? "on" : "off"}\n`
+  );
+}
 if (values["pick-commands"] !== undefined) {
   const items = await probe.pickCommands(values["pick-commands"]);
   process.stderr.write(`pick-commands: ${items.length} rows\n`);