pim-agent 0.0.1 → 0.9.0

package/packages/server/src/ProbeClient.ts

@@ -0,0 +1,312 @@
+import { basename } from "node:path";
+
+import type { PickerItem } from "#core/picker/PickerItem";
+import { RemoteFilePickerSuggestionEngine } from "#core/picker/RemoteFilePickerSuggestionEngine";
+import type { AttachmentRef, CommandDraft } from "#protocol/Command";
+import { PROTOCOL_VERSION } from "#protocol/Protocol";
+import {
+  isDurableEvent,
+  type ModelView,
+  type ResponseEvent,
+  type ServerEvent,
+  type SessionSummaryView,
+} 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;
+  /** Called for every frame, in arrival order. */
+  readonly onEvent?: (event: ServerEvent) => void;
+  /** Sent instead of the real one, to exercise version rejection. */
+  readonly protocolVersion?: number;
+  /** 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;
+  private closeInfo:
+    | { readonly code: number; readonly reason: string }
+    | undefined;
+
+  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) => {
+      this.closeInfo = { code: event.code, reason: event.reason };
+      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",
+      protocolVersion: (this.options.protocolVersion ??
+        PROTOCOL_VERSION) as typeof PROTOCOL_VERSION,
+      ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+      ...(this.options.cwd === undefined ? {} : { cwd: this.options.cwd }),
+      fromSeq: this.seq,
+    });
+  }
+
+  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(
+    cwd?: string
+  ): Promise<readonly SessionSummaryView[]> {
+    const response = await this.send({
+      type: "list_sessions",
+      ...(cwd === undefined ? {} : { cwd }),
+    });
+    if (!response.success) {
+      throw new Error(response.error ?? "list_sessions failed");
+    }
+    return response.sessions ?? [];
+  }
+
+  /** 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?.();
+    });
+  }
+
+  /** Resolves when the socket closes, e.g. after a protocol rejection. */
+  public async closed(): Promise<{
+    readonly code: number;
+    readonly reason: string;
+  }> {
+    while (!this.closeInfo) {
+      await Bun.sleep(5);
+    }
+    return this.closeInfo;
+  }
+
+  /** 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 };

package/packages/server/src/SessionCatalogue.ts

@@ -0,0 +1,202 @@
+import { EventLog } from "#core/session/EventLog";
+import type { SessionDigest } from "#core/session/EventLog";
+import type { ReadCursors } from "#core/session/ReadCursors";
+import type { SessionRegistry } from "#core/session/SessionRegistry";
+import { FileWatch } from "#core/shared/FileWatch";
+import type { Command } from "#protocol/Command";
+import type {
+  ServerEvent,
+  SessionStatus,
+  SessionSummaryView,
+} from "#protocol/ServerEvent";
+
+export type SessionCatalogueDeps = {
+  readonly registry: SessionRegistry;
+  /** Which sessions have been read, shared by every client. */
+  readonly cursors: ReadCursors;
+  readonly liveStatus: (sessionId: string) => SessionStatus | undefined;
+  readonly liveSessionIds: () => Iterable<string>;
+  readonly isBeingRead: (sessionId: string) => boolean;
+  readonly announce: (event: ServerEvent) => void;
+};
+
+const DEFAULT_SESSION_LIMIT = 50;
+
+/** Long enough that a turn's entries are one announcement, short enough that a new session appears while the user is still looking. */
+const ANNOUNCE_MS = 500;
+
+type CachedDigest = SessionDigest & { readonly modifiedAt: number };
+
+export class SessionCatalogue {
+  private readonly deps: SessionCatalogueDeps;
+  private readonly digests = new Map<string, CachedDigest>();
+  private readonly activity = new Map<string, SessionStatus>();
+  private readonly settled = new Map<string, number>();
+  private readonly watches = new Map<string, () => void>();
+  private watching = false;
+  private announcing: ReturnType<typeof setTimeout> | undefined;
+
+  public constructor(deps: SessionCatalogueDeps) {
+    this.deps = deps;
+  }
+
+  /**
+   * Follow the sessions tree while anyone is connected. A session the terminal
+   * or a vanilla `pi` starts is a file this process never hears about
+   * otherwise, and a list nobody asked to re-fetch is a list that never learns
+   * about it.
+   */
+  public watch(active: boolean): void {
+    if (active === this.watching) {
+      return;
+    }
+    this.watching = active;
+    if (!active) {
+      for (const stop of this.watches.values()) {
+        stop();
+      }
+      this.watches.clear();
+      clearTimeout(this.announcing);
+      this.announcing = undefined;
+      return;
+    }
+    this.follow();
+  }
+
+  public async list(
+    command: Command & { readonly type: "list_sessions" }
+  ): Promise<readonly SessionSummaryView[]> {
+    const summaries = await this.deps.registry.list(command.cwd);
+    // Prune only on an unfiltered listing: a cwd-filtered one would forget every other directory.
+    if (command.cwd === undefined) {
+      await this.deps.cursors.prune(
+        new Set([
+          ...summaries.map((summary) => summary.sessionId),
+          ...this.deps.liveSessionIds(),
+        ])
+      );
+    }
+    // Cut by modified time and digest only the page: ordering by settle time would read every session on disk.
+    const page = await Promise.all(
+      summaries
+        .slice(0, command.limit ?? DEFAULT_SESSION_LIMIT)
+        .map(async ({ sessionId, cwd, path, createdAt, modifiedAt }) => {
+          const { title, settledAt } = await this.digestOf(path, modifiedAt);
+          const status = this.deps.liveStatus(sessionId);
+          const answeredAt = this.answerTime(sessionId, status, settledAt);
+          const unread = await this.deps.cursors.isUnread(
+            sessionId,
+            answeredAt
+          );
+          return {
+            sessionId,
+            cwd,
+            createdAt,
+            settledAt: answeredAt ?? settledAt ?? createdAt,
+            ...(title === undefined ? {} : { title }),
+            ...(status === undefined || status === "idle" ? {} : { status }),
+            ...(unread ? { unread: true } : {}),
+          };
+        })
+    );
+    return page.sort((a, b) => b.settledAt - a.settledAt);
+  }
+
+  /** Announces a status edge to every client; the announcement must precede the read mark. */
+  public onStatus(sessionId: string, status: SessionStatus): void {
+    if (this.activity.get(sessionId) === status) {
+      return;
+    }
+    this.activity.set(sessionId, status);
+    this.deps.announce({ type: "session_activity", sessionId, status });
+    if (status === "idle" && this.deps.isBeingRead(sessionId)) {
+      void this.markRead(sessionId);
+    }
+  }
+
+  public track(sessionId: string, status: SessionStatus): void {
+    this.activity.set(sessionId, status);
+  }
+
+  /** Moves a session's read cursor to now and says so to every client. */
+  public async markRead(sessionId: string): Promise<void> {
+    await this.deps.cursors.mark(sessionId);
+    this.deps.announce({ type: "session_read", sessionId });
+  }
+
+  public flush(): Promise<void> {
+    return this.deps.cursors.flush();
+  }
+
+  public clear(): void {
+    this.digests.clear();
+    this.activity.clear();
+    this.settled.clear();
+  }
+
+  // One watch per directory, never a recursive one: `fs.watch` recursion is unsupported on some platforms and silent on others.
+  private follow(): void {
+    const root = this.deps.registry.sessionsRoot;
+    const wanted = new Set([root, ...FileWatch.subdirectories(root)]);
+    for (const [path, stop] of this.watches) {
+      if (!wanted.has(path)) {
+        stop();
+        this.watches.delete(path);
+      }
+    }
+    for (const path of wanted) {
+      if (!this.watches.has(path)) {
+        this.watches.set(
+          path,
+          FileWatch.directory(path, () => {
+            this.onTreeChange();
+          })
+        );
+      }
+    }
+  }
+
+  // Debounced: a turn writes a dozen entries, and re-listing is a read of every session header.
+  private onTreeChange(): void {
+    if (this.announcing !== undefined || !this.watching) {
+      return;
+    }
+    this.announcing = setTimeout(() => {
+      this.announcing = undefined;
+      this.follow();
+      this.deps.announce({ type: "sessions_changed" });
+    }, ANNOUNCE_MS);
+    this.announcing.unref?.();
+  }
+
+  // A running session must be answered for by its last idle reading: mid-turn the file's time is the line just written.
+  private answerTime(
+    sessionId: string,
+    status: SessionStatus | undefined,
+    fromFile: number | undefined
+  ): number | undefined {
+    if (status === undefined) {
+      return fromFile;
+    }
+    if (status !== "idle") {
+      return this.settled.get(sessionId);
+    }
+    if (fromFile !== undefined) {
+      this.settled.set(sessionId, fromFile);
+    }
+    return fromFile;
+  }
+
+  private async digestOf(
+    path: string,
+    modifiedAt: number
+  ): Promise<SessionDigest> {
+    const cached = this.digests.get(path);
+    if (cached?.modifiedAt === modifiedAt) {
+      return cached;
+    }
+    const digest = await new EventLog(path).digest();
+    this.digests.set(path, { ...digest, modifiedAt });
+    return digest;
+  }
+}