pim-agent 0.0.1 → 0.10.0

package/packages/server/src/ProbeClient.ts

@@ -0,0 +1,374 @@
+import { basename } from "node:path";
+
+import type { PickerItem } from "#core/picker/PickerItem";
+import { RemoteFilePickerSuggestionEngine } from "#core/picker/RemoteFilePickerSuggestionEngine";
+import type {
+  AttachmentRef,
+  CommandDraft,
+  SearchScope,
+  SessionScope,
+} from "#protocol/Command";
+import {
+  isDurableEvent,
+  type ModelView,
+  type ResponseEvent,
+  type ServerEvent,
+  type SessionListing,
+  type SessionSearch,
+} from "#protocol/ServerEvent";
+
+export type ProbeOptions = {
+  readonly url: string;
+  /** Omit to have the server create a session; the id comes back on attach. */
+  readonly sessionId?: string;
+  readonly cwd?: string;
+  readonly fromSeq?: number;
+  /** Sent on the attach frame; false is a client that is connected but not looking. */
+  readonly attentive?: boolean;
+  /** Called for every frame, in arrival order. */
+  readonly onEvent?: (event: ServerEvent) => void;
+  /** Keystroke debounce for `files`; 0 makes tests deterministic. */
+  readonly debounceMs?: number;
+};
+
+/** What `POST /upload` answers with, all of it server-side. */
+export type UploadedFile = {
+  readonly id: string;
+  readonly path: string;
+  /** Where the bytes can be read back, relative to the server's origin. */
+  readonly url: string;
+  readonly mimeType: string;
+  readonly isImage: boolean;
+};
+
+type Pending = {
+  readonly resolve: (response: ResponseEvent) => void;
+  readonly reject: (err: Error) => void;
+};
+
+/** The reference client: speaks the whole protocol, renders nothing. */
+export class ProbeClient {
+  public sessionId: string | undefined;
+  public seq: number;
+  public readonly events: ServerEvent[] = [];
+  /** The `@` picker, answered by the server one query at a time. */
+  public readonly files: RemoteFilePickerSuggestionEngine;
+  private readonly options: ProbeOptions;
+  private readonly pending = new Map<string, Pending>();
+  private readonly waiters = new Set<{
+    readonly test: (event: ServerEvent) => boolean;
+    readonly resolve: (event: ServerEvent) => void;
+  }>();
+  private socket: WebSocket | undefined;
+  private nextId = 0;
+
+  public constructor(options: ProbeOptions) {
+    this.options = options;
+    this.sessionId = options.sessionId;
+    this.seq = options.fromSeq ?? 0;
+    this.files = new RemoteFilePickerSuggestionEngine(
+      (query, limit) => this.pickFiles(query, limit),
+      options.debounceMs
+    );
+  }
+
+  /** Connects and completes the resume handshake; resolves once replay ends. */
+  public async connect(): Promise<ResponseEvent> {
+    const socket = new WebSocket(this.options.url);
+    this.socket = socket;
+    socket.addEventListener("message", (event) => {
+      this.receive(String(event.data));
+    });
+    socket.addEventListener("close", (event) => {
+      for (const { reject } of this.pending.values()) {
+        reject(new Error(`socket closed: ${event.code} ${event.reason}`));
+      }
+      this.pending.clear();
+    });
+    await new Promise<void>((resolve, reject) => {
+      socket.addEventListener("open", () => {
+        resolve();
+      });
+      socket.addEventListener("error", () => {
+        reject(new Error(`could not connect to ${this.options.url}`));
+      });
+    });
+    return await this.send({
+      type: "attach",
+      ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+      ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+      ...(this.options.attentive === undefined
+        ? {}
+        : { attentive: this.options.attentive }),
+      fromSeq: this.seq,
+    });
+  }
+
+  /** Says whether this client's reader is present; regaining it reads the session. */
+  public attention(value: boolean): Promise<ResponseEvent> {
+    return this.send({ type: "attention", value });
+  }
+
+  public send(command: CommandDraft): Promise<ResponseEvent> {
+    const socket = this.socket;
+    if (!socket) {
+      return Promise.reject(new Error("probe is not connected"));
+    }
+    const id = `probe-${++this.nextId}`;
+    const frame = { ...command, id };
+    return new Promise<ResponseEvent>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      socket.send(JSON.stringify(frame));
+    });
+  }
+
+  public prompt(text: string): Promise<ResponseEvent> {
+    return this.send({
+      type: "user_message",
+      sessionId: this.sessionId ?? "",
+      text,
+    });
+  }
+
+  public async pickFiles(
+    query: string,
+    limit = 50
+  ): Promise<readonly PickerItem[]> {
+    const response = await this.send({
+      type: "pick_files",
+      sessionId: this.sessionId ?? "",
+      query,
+      limit,
+    });
+    return itemsOf(response);
+  }
+
+  public async pickCommands(
+    query: string,
+    limit?: number
+  ): Promise<readonly PickerItem[]> {
+    const response = await this.send({
+      type: "pick_commands",
+      sessionId: this.sessionId ?? "",
+      query,
+      ...(limit === undefined ? {} : { limit }),
+    });
+    return itemsOf(response);
+  }
+
+  /** Reads one subagent's transcript; its events stay enveloped in `events`. */
+  public watchSubagent(callId: string, fromSeq = 0): Promise<ResponseEvent> {
+    return this.send({
+      type: "watch_subagent",
+      sessionId: this.sessionId ?? "",
+      callId,
+      fromSeq,
+    });
+  }
+
+  public unwatchSubagent(callId: string): Promise<ResponseEvent> {
+    return this.send({ type: "unwatch_subagent", callId });
+  }
+
+  /** Pi's session catalogue; answers whether or not this probe is attached. */
+  public async listSessions(
+    scope: SessionScope = {}
+  ): Promise<SessionListing["sessions"]> {
+    return (await this.catalogue(scope)).sessions;
+  }
+
+  /** The listing whole: the rows the page kept and the projects they came from. */
+  public async catalogue(scope: SessionScope = {}): Promise<SessionListing> {
+    const response = await this.send({ type: "list_sessions", ...scope });
+    if (!response.success) {
+      throw new Error(response.error ?? "list_sessions failed");
+    }
+    return {
+      sessions: response.sessions ?? [],
+      projects: response.projects ?? [],
+    };
+  }
+
+  /** Searches every session on disk; an empty query warms the index and answers with no hits. */
+  public async search(
+    query: string,
+    scope: SearchScope = {}
+  ): Promise<SessionSearch> {
+    const response = await this.send({
+      type: "search_sessions",
+      query,
+      ...scope,
+    });
+    if (!response.success) {
+      throw new Error(response.error ?? "search_sessions failed");
+    }
+    return {
+      hits: response.hits ?? [],
+      dropped: response.dropped ?? [],
+      scanned: response.scanned ?? 0,
+    };
+  }
+
+  /** Names a session through pi's own name; `null` clears it back to its opening message. */
+  public rename(
+    sessionId: string,
+    value: string | null
+  ): Promise<ResponseEvent> {
+    return this.send({ type: "set_session_name", sessionId, value });
+  }
+
+  /** Puts a session out of the live listing, or brings it back. */
+  public setArchived(
+    sessionId: string,
+    value: boolean
+  ): Promise<ResponseEvent> {
+    return this.send({ type: "set_session_archived", sessionId, value });
+  }
+
+  /** Holds a session unread until something reads it; survives a listing and a re-attach. */
+  public markUnread(sessionId: string, value: boolean): Promise<ResponseEvent> {
+    return this.send({ type: "set_session_unread", sessionId, value });
+  }
+
+  /** Pins a working directory, not a session. */
+  public setPinned(cwd: string, value: boolean): Promise<ResponseEvent> {
+    return this.send({ type: "set_project_pinned", cwd, value });
+  }
+
+  /** Re-orders the pinned directories; the whole order, pinned ones only. */
+  public setPinOrder(order: readonly string[]): Promise<ResponseEvent> {
+    return this.send({ type: "set_pin_order", order });
+  }
+
+  /** Unfolds a working directory's sidebar group, or folds it. */
+  public setExpanded(cwd: string, value: boolean): Promise<ResponseEvent> {
+    return this.send({ type: "set_project_expanded", cwd, value });
+  }
+
+  /** Names a working directory for the listings; `null` puts it back to its base name. */
+  public setLabel(cwd: string, value: string | null): Promise<ResponseEvent> {
+    return this.send({ type: "set_project_label", cwd, value });
+  }
+
+  /** The model catalogue, plus this session's thinking levels; empty when unattached. */
+  public async listModels(): Promise<{
+    readonly models: readonly ModelView[];
+    readonly thinkingLevels: readonly string[];
+  }> {
+    const response = await this.send({ type: "list_models" });
+    if (!response.success) {
+      throw new Error(response.error ?? "list_models failed");
+    }
+    return {
+      models: response.models ?? [],
+      thinkingLevels: response.thinkingLevels ?? [],
+    };
+  }
+
+  /** Transfers a client-local file into the server's world; only the bytes and bare filename are sent. */
+  public async upload(localPath: string): Promise<UploadedFile> {
+    const file = Bun.file(localPath);
+    const form = new FormData();
+    form.append("file", file, basename(localPath));
+    const response = await fetch(
+      `${this.httpUrl}/upload?session=${encodeURIComponent(this.sessionId ?? "")}`,
+      { method: "POST", body: form }
+    );
+    const body = (await response.json()) as UploadedFile & {
+      readonly error?: string;
+    };
+    if (!response.ok) {
+      throw new Error(`upload failed: ${body.error ?? response.status}`);
+    }
+    return body;
+  }
+
+  public promptWith(
+    text: string,
+    attachments: readonly AttachmentRef[]
+  ): Promise<ResponseEvent> {
+    return this.send({
+      type: "user_message",
+      sessionId: this.sessionId ?? "",
+      text,
+      attachments,
+    });
+  }
+
+  public get httpUrl(): string {
+    return this.options.url.replace(/^ws/, "http");
+  }
+
+  /** `from` skips frames already received, so a repeated state can be awaited. */
+  public waitFor(
+    test: (event: ServerEvent) => boolean,
+    opts?: { readonly timeoutMs?: number; readonly from?: number }
+  ): Promise<ServerEvent> {
+    const timeoutMs = opts?.timeoutMs ?? 30_000;
+    const hit = this.events.slice(opts?.from ?? 0).find(test);
+    if (hit) {
+      return Promise.resolve(hit);
+    }
+    return new Promise<ServerEvent>((resolve, reject) => {
+      const waiter = { test, resolve };
+      this.waiters.add(waiter);
+      const timer = setTimeout(() => {
+        this.waiters.delete(waiter);
+        reject(
+          new Error(`timed out waiting for an event after ${timeoutMs}ms`)
+        );
+      }, timeoutMs);
+      timer.unref?.();
+    });
+  }
+
+  /** Drops the socket without a close frame, the way a killed client would. */
+  public kill(): void {
+    this.socket?.close(4000, "probe killed");
+    this.socket = undefined;
+  }
+
+  public close(): void {
+    this.socket?.close();
+    this.socket = undefined;
+  }
+
+  private receive(raw: string): void {
+    const frame = JSON.parse(raw) as ServerEvent;
+    if (frame.type === "replay") {
+      for (const event of frame.events) {
+        this.dispatch(event);
+      }
+      return;
+    }
+    this.dispatch(frame);
+  }
+
+  private dispatch(event: ServerEvent): void {
+    this.events.push(event);
+    if (isDurableEvent(event)) {
+      this.seq = Math.max(this.seq, event.seq);
+    } else if (event.type === "attached") {
+      this.sessionId = event.sessionId;
+    } else if (event.type === "picker_invalidate") {
+      void this.files.refreshRelative();
+    } else if (event.type === "response") {
+      this.pending.get(event.id)?.resolve(event);
+      this.pending.delete(event.id);
+    }
+    this.options.onEvent?.(event);
+    for (const waiter of this.waiters) {
+      if (waiter.test(event)) {
+        this.waiters.delete(waiter);
+        waiter.resolve(event);
+      }
+    }
+  }
+}
+
+function itemsOf(response: ResponseEvent): readonly PickerItem[] {
+  if (!response.success) {
+    throw new Error(response.error ?? "picker query failed");
+  }
+  return response.items ?? [];
+}

package/packages/server/src/Reloader.ts

@@ -0,0 +1,93 @@
+import { DaemonUnit } from "#core/shared/DaemonUnit";
+import { Supervisor } from "#core/shared/Supervisor";
+import { Updater, type UpdateOutcome } from "#core/shared/Updater";
+import type { ServerEvent } from "#protocol/ServerEvent";
+
+export type ReloaderDeps = {
+  /** To every connection: the restart takes all of them down together. */
+  readonly announce: (event: ServerEvent) => void;
+  /** Runs the update, reporting each step as it starts. */
+  readonly update?: (onStep: (label: string) => void) => Promise<UpdateOutcome>;
+  /** Takes this process down so the supervisor puts the new code up in its place. */
+  readonly shutdown?: () => Promise<void>;
+};
+
+// Re-raise SIGTERM rather than exiting: the handler stops the gateway and flushes the read cursors.
+async function restartAndExit(): Promise<void> {
+  await Supervisor.restartSiblings(DaemonUnit);
+  process.kill(process.pid, "SIGTERM");
+}
+
+/** Runs the update-restart-return an operator asked for, announcing each phase. */
+export class Reloader {
+  private readonly announce: (event: ServerEvent) => void;
+  private readonly update: (
+    onStep: (label: string) => void
+  ) => Promise<UpdateOutcome>;
+  private readonly shutdown: () => Promise<void>;
+  private running: Promise<void> | undefined;
+
+  public constructor(deps: ReloaderDeps) {
+    this.announce = deps.announce;
+    this.update = deps.update ?? ((onStep) => Updater.run({ onStep }));
+    this.shutdown = deps.shutdown ?? restartAndExit;
+    this.running = undefined;
+  }
+
+  /** The run already in flight, or a new one; two callers share one install. */
+  public start(): Promise<void> {
+    this.running ??= this.run().finally(() => {
+      this.running = undefined;
+    });
+    return this.running;
+  }
+
+  private async run(): Promise<void> {
+    let outcome: UpdateOutcome;
+    try {
+      outcome = await this.update((label) => {
+        this.announce({ type: "update_state", phase: "step", label });
+      });
+    } catch (err) {
+      this.failed(messageOf(err));
+      return;
+    }
+    if (!outcome.ok) {
+      this.failed(outcome.error ?? "the update failed");
+      return;
+    }
+    const { from, to, skipped } = outcome;
+    // Unsupervised, exiting would end this process rather than replace it.
+    if (!Supervisor.isSupervised()) {
+      this.announce({
+        type: "update_state",
+        phase: "stranded",
+        from,
+        to,
+        skipped,
+      });
+      return;
+    }
+    this.announce({
+      type: "update_state",
+      phase: "restarting",
+      from,
+      to,
+      skipped,
+    });
+    try {
+      await this.shutdown();
+    } catch (err) {
+      // Must follow the `restarting` frame: it corrects a client already told to expect the drop.
+      this.failed(messageOf(err));
+    }
+  }
+
+  private failed(error: string): void {
+    this.announce({ type: "update_state", phase: "failed", error });
+  }
+}
+
+function messageOf(err: unknown): string {
+  return (err as Error).message ?? String(err);
+}

package/packages/server/src/SendFileTool.ts

@@ -0,0 +1,88 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import { type Static, Type } from "typebox";
+
+import type { AttachmentStore } from "#core/attachments/AttachmentStore";
+import { Paths } from "#core/shared/Paths";
+import { SendFile } from "#core/shared/SendFile";
+import type { PimToolDefinition } from "#core/shared/Tools";
+import type { ToolView } from "#core/view/ViewBlock";
+import { attachmentUrl } from "./AttachmentEndpoint";
+
+const sendFileSchema = Type.Object({
+  path: Type.String({
+    minLength: 1,
+    description: "Absolute or relative path to file (resolved against cwd).",
+  }),
+});
+
+type SendFileInput = Static<typeof sendFileSchema>;
+
+type SendFileDetails = {
+  readonly name: string;
+  readonly url: string;
+  readonly isImage: boolean;
+};
+
+export type SendFileDeps = {
+  readonly store: AttachmentStore;
+  readonly cwd: string;
+  /** Pi's session uuid, read at call time. */
+  readonly sessionId: () => string | undefined;
+};
+
+function build(
+  deps: SendFileDeps
+): PimToolDefinition<typeof sendFileSchema, SendFileDetails> {
+  return {
+    ...defineTool({
+      name: "send_file",
+      label: "send_file",
+      description: `Send a local file to the user's web browser. Images appear inline. Max ${SendFile.MAX_BYTES / (1024 * 1024)} MB.`,
+      parameters: sendFileSchema,
+      async execute(_id, params) {
+        const { path: rawPath } = params as SendFileInput;
+        const { path, size } = await SendFile.validate(rawPath, deps.cwd);
+        const scope = deps.sessionId();
+        if (!scope) {
+          throw new Error("This session cannot send files yet.");
+        }
+        const stored = await deps.store.storeFile(scope, path);
+        const details: SendFileDetails = {
+          name: basename(path),
+          url: attachmentUrl(stored.path),
+          isImage: stored.mimeType.startsWith("image/"),
+        };
+        return {
+          // Never the URL: an address the model can repeat is a second, dead copy of this delivery.
+          content: [{ type: "text", text: `Sent ${details.name} (${size} B)` }],
+          details,
+        };
+      },
+    }),
+    effect: { kind: "readOnly" },
+    toViewModel: ({ args, result, cwd }): ToolView => {
+      const details = result?.details;
+      return {
+        label: "Send File",
+        icon: "upload",
+        title: [
+          {
+            kind: "file",
+            path: Paths.titleOr(
+              (args as Partial<SendFileInput> | undefined)?.path,
+              cwd
+            ),
+          },
+        ],
+        ...(details === undefined
+          ? {}
+          : {
+              summary: [{ kind: "attachment", ...details }],
+            }),
+      };
+    },
+  };
+}
+
+export const SendFileTool = { build };