pim-agent 0.9.0 → 0.10.0

package/packages/core/src/shared/Surface.ts

@@ -0,0 +1,2 @@
+/** Where the human on the other end is reading; absent for a subagent, which has no human. */
+export type Surface = "terminal" | "web browser" | "Telegram";

package/packages/core/src/shared/Updater.ts

@@ -43,6 +43,8 @@ export type UpdateFacts = {
   readonly packageName: string;
   /** A dev checkout with no uncommitted changes; irrelevant to a prod install. */
   readonly cleanTree: boolean;
+  /** The dev checkout's branch tracks a remote one, so a pull has somewhere to pull from; irrelevant to a prod install. */
+  readonly tracked: boolean;
   /** The newest published release, or undefined when the registry was silent. */
   readonly latest: string | undefined;
 };
@@ -81,13 +83,24 @@ async function swapClient(packageRoot: string): Promise<void> {
   await rename(dirs.staging, dirs.client);
 }
 
+/** Why this checkout cannot be pulled, or undefined when it can. */
+function pullBlocker(facts: UpdateFacts): string | undefined {
+  if (!facts.tracked) {
+    return "this branch has no upstream to pull from";
+  }
+  return facts.cleanTree
+    ? undefined
+    : "the working tree has uncommitted changes";
+}
+
 function plan(facts: UpdateFacts): UpdatePlan {
   const steps: UpdateStep[] = [];
   const skipped: UpdateSkip[] = [];
-  const { at, packageName, cleanTree, latest } = facts;
+  const { at, packageName, latest } = facts;
 
   if (at.kind === "dev") {
-    if (cleanTree) {
+    const blocked = pullBlocker(facts);
+    if (blocked === undefined) {
       steps.push({
         label: "git pull",
         command: ["git", "pull", "--ff-only"],
@@ -96,7 +109,7 @@ function plan(facts: UpdateFacts): UpdatePlan {
     } else {
       skipped.push({
         label: "git pull",
-        reason: "the working tree has uncommitted changes",
+        reason: blocked,
         blocking: false,
       });
     }
@@ -137,14 +150,17 @@ function plan(facts: UpdateFacts): UpdatePlan {
 
 async function gather(): Promise<UpdateFacts> {
   const at = await Supervisor.detectInstall();
-  const [packageName, cleanTree, latest] = await Promise.all([
+  const [packageName, cleanTree, tracked, latest] = await Promise.all([
     PimVersion.name(),
     at.kind === "dev"
       ? Git.fetchStatus(at.packageRoot).then((git) => git.dirtyCount === 0)
       : Promise.resolve(true),
+    at.kind === "dev"
+      ? Git.upstreamOf(at.packageRoot).then((at) => at !== undefined)
+      : Promise.resolve(true),
     at.kind === "prod" ? PimVersion.latest() : Promise.resolve(undefined),
   ]);
-  return { at, packageName, cleanTree, latest };
+  return { at, packageName, cleanTree, tracked, latest };
 }
 
 /** Never restarts or exits: the caller owns that. */

package/packages/core/src/view/DiffExpand.ts

@@ -0,0 +1,214 @@
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
+import type { LineSpan } from "../shared/RepoDiff";
+
+/**
+ * A stretch of a file neither side changed and no hunk shows, numbered on the
+ * new side. `above` and `below` say which ends of it sit against a hunk, which
+ * is where a reader asking for more of it is given it.
+ */
+export type DiffGap = {
+  readonly start: number;
+  readonly end: number;
+  readonly count: number;
+  readonly above: boolean;
+  readonly below: boolean;
+};
+
+/** What a diff is painted from, top to bottom: hunks and the gaps between them. */
+export type DiffPart =
+  | { readonly hunk: ToolDiffHunk }
+  | { readonly gap: DiffGap };
+
+/** Lines one click reveals at each end of a gap. */
+const STEP = 25;
+
+/** A remainder this small is taken with the click rather than left as a row of its own. */
+const MIN_REMAINDER = 10;
+
+function newEnd(hunk: ToolDiffHunk): number {
+  return hunk.newStart + hunk.newLines - 1;
+}
+
+function oldEnd(hunk: ToolDiffHunk): number {
+  return hunk.oldStart + hunk.oldLines - 1;
+}
+
+function gapOf(
+  start: number,
+  end: number,
+  above: boolean,
+  below: boolean
+): readonly DiffGap[] {
+  return end < start
+    ? []
+    : [{ start, end, count: end - start + 1, above, below }];
+}
+
+/**
+ * Every gap in one file's hunks: before the first, between each pair, and
+ * after the last once `total` says where the file ends. A file with no new
+ * side to number has none of them.
+ */
+function gaps(
+  hunks: readonly ToolDiffHunk[],
+  total?: number
+): readonly DiffGap[] {
+  const first = hunks[0];
+  const last = hunks.at(-1);
+  if (first === undefined || last === undefined) {
+    return [];
+  }
+
+  return [
+    ...gapOf(1, first.newStart - 1, false, true),
+    ...hunks.flatMap((hunk, index) => {
+      const next = hunks[index + 1];
+      return next === undefined
+        ? []
+        : gapOf(newEnd(hunk) + 1, next.newStart - 1, true, true);
+    }),
+    ...(total === undefined ? [] : gapOf(newEnd(last) + 1, total, true, false)),
+  ];
+}
+
+/**
+ * What to ask the server for when a reader opens a gap: a step against each
+ * hunk it touches, or the whole gap when what would be left of it is a sliver.
+ */
+function spans(gap: DiffGap): readonly LineSpan[] {
+  const edges = (gap.above ? 1 : 0) + (gap.below ? 1 : 0);
+  if (gap.count <= edges * STEP + MIN_REMAINDER) {
+    return [{ start: gap.start, end: gap.end }];
+  }
+  return [
+    ...(gap.above ? [{ start: gap.start, end: gap.start + STEP - 1 }] : []),
+    ...(gap.below ? [{ start: gap.end - STEP + 1, end: gap.end }] : []),
+  ];
+}
+
+/** How many lines opening a gap would put on the page. */
+function revealed(gap: DiffGap): number {
+  return spans(gap).reduce(
+    (total, span) => total + span.end - span.start + 1,
+    0
+  );
+}
+
+/** The hunks with each gap in its place among them. */
+function parts(
+  hunks: readonly ToolDiffHunk[],
+  total?: number
+): readonly DiffPart[] {
+  const found = gaps(hunks, total);
+  const tail = found.find((gap) => !gap.below);
+  // Keyed by the line a gap ends on, which is the line before the hunk it
+  // leads into: one lookup per hunk rather than a scan of every gap.
+  const leading = new Map(found.map((gap) => [gap.end, gap]));
+  return [
+    ...hunks.flatMap((hunk) => {
+      const gap = leading.get(hunk.newStart - 1);
+      return gap === undefined ? [{ hunk }] : [{ gap }, { hunk }];
+    }),
+    ...(tail === undefined ? [] : [{ gap: tail }]),
+  ];
+}
+
+type Run = {
+  readonly oldStart: number;
+  readonly newStart: number;
+  readonly lines: ToolDiffLine[];
+  /** Lines of the run that stand on the new side, counted as they are added. */
+  newCount: number;
+};
+
+function context(line: number, offset: number, text: string): ToolDiffLine {
+  return { kind: "context", oldLine: line + offset, newLine: line, text };
+}
+
+function newLinesOf(lines: readonly ToolDiffLine[]): number {
+  return lines.filter((line) => line.kind !== "removed").length;
+}
+
+function hunkOf(run: Run): ToolDiffHunk {
+  return {
+    oldStart: run.oldStart,
+    newStart: run.newStart,
+    oldLines: run.lines.filter((line) => line.kind !== "added").length,
+    newLines: run.newCount,
+    lines: run.lines,
+  };
+}
+
+/**
+ * The hunks with every line a reader has since been given spliced back into
+ * the gaps around them, and hunks that now touch merged into one. Only lines
+ * running from a hunk's own edge are taken: an island in the middle of a gap
+ * is not a thing this ever asks for.
+ */
+function expand(
+  hunks: readonly ToolDiffHunk[],
+  known: ReadonlyMap<number, string>
+): readonly ToolDiffHunk[] {
+  if (known.size === 0) {
+    return hunks;
+  }
+
+  const runs: Run[] = [];
+
+  const reached = (): number => {
+    const last = runs.at(-1);
+    return last === undefined ? 0 : last.newStart + last.newCount - 1;
+  };
+
+  const add = (run: Run): void => {
+    const last = runs.at(-1);
+    if (last !== undefined && reached() + 1 === run.newStart) {
+      last.lines.push(...run.lines);
+      last.newCount += run.newCount;
+      return;
+    }
+    runs.push(run);
+  };
+
+  for (const [index, hunk] of hunks.entries()) {
+    const before: ToolDiffLine[] = [];
+    const floor = reached();
+    for (let line = hunk.newStart - 1; line > floor; line -= 1) {
+      const text = known.get(line);
+      if (text === undefined) {
+        break;
+      }
+      before.push(context(line, hunk.oldStart - hunk.newStart, text));
+    }
+    before.reverse();
+    const lines = [...before, ...hunk.lines];
+    add({
+      oldStart: hunk.oldStart - before.length,
+      newStart: hunk.newStart - before.length,
+      lines,
+      newCount: before.length + newLinesOf(hunk.lines),
+    });
+
+    const after: ToolDiffLine[] = [];
+    const ceiling = hunks[index + 1]?.newStart ?? Infinity;
+    for (let line = newEnd(hunk) + 1; line < ceiling; line += 1) {
+      const text = known.get(line);
+      if (text === undefined) {
+        break;
+      }
+      after.push(context(line, oldEnd(hunk) - newEnd(hunk), text));
+    }
+    if (after.length > 0) {
+      add({
+        oldStart: oldEnd(hunk) + 1,
+        newStart: newEnd(hunk) + 1,
+        lines: after,
+        newCount: after.length,
+      });
+    }
+  }
+
+  return runs.map(hunkOf);
+}
+
+export const DiffExpand = { gaps, parts, spans, revealed, expand };

package/packages/core/src/view/DiffLayout.ts

@@ -1,4 +1,4 @@
-import type { ToolDiffHunk } from "../shared/DiffLines";
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
 
 const TAB = "   ";
 
@@ -8,7 +8,7 @@ function detab(text: string): string {
 
 // Highlight each side as one block, never line by line, or multi-line strings and comments mis-tokenise.
 function mapSides<T>(
-  hunk: ToolDiffHunk,
+  lines: readonly ToolDiffLine[],
   highlight: (block: string) => readonly T[]
 ): readonly (T | undefined)[] {
   const oldIndices: (number | undefined)[] = [];
@@ -16,7 +16,7 @@ function mapSides<T>(
   const oldBlock: string[] = [];
   const newBlock: string[] = [];
 
-  for (const line of hunk.lines) {
+  for (const line of lines) {
     // A context line must hold a slot in both blocks to keep tokeniser state aligned.
     if (line.kind !== "added") {
       oldIndices.push(oldBlock.length);
@@ -33,11 +33,11 @@ function mapSides<T>(
     }
   }
 
-  const oldLines = oldBlock.length === 0 ? [] : highlight(oldBlock.join("\n"));
-  const newLines = newBlock.length === 0 ? [] : highlight(newBlock.join("\n"));
+  const oldText = oldBlock.length === 0 ? [] : highlight(oldBlock.join("\n"));
+  const newText = newBlock.length === 0 ? [] : highlight(newBlock.join("\n"));
 
-  return hunk.lines.map((line, index) => {
-    const side = line.kind === "removed" ? oldLines : newLines;
+  return lines.map((line, index) => {
+    const side = line.kind === "removed" ? oldText : newText;
     const at = line.kind === "removed" ? oldIndices[index] : newIndices[index];
     return at === undefined ? undefined : side[at];
   });

package/packages/core/src/view/DiffPairs.ts

@@ -0,0 +1,47 @@
+import type { ToolDiffHunk, ToolDiffLine } from "../shared/DiffLines";
+
+/** One row of a split view: the old side, the new side, or both. */
+export type DiffPair = {
+  readonly left?: ToolDiffLine;
+  readonly right?: ToolDiffLine;
+};
+
+function pair(hunk: ToolDiffHunk): readonly DiffPair[] {
+  const pairs: DiffPair[] = [];
+  let removed: ToolDiffLine[] = [];
+  let added: ToolDiffLine[] = [];
+
+  const zip = (): void => {
+    const rows = Math.max(removed.length, added.length);
+    for (let index = 0; index < rows; index += 1) {
+      pairs.push({ left: removed[index], right: added[index] });
+    }
+    removed = [];
+    added = [];
+  };
+
+  for (const line of hunk.lines) {
+    if (line.kind === "context") {
+      zip();
+      pairs.push({ left: line, right: line });
+      continue;
+    }
+
+    if (line.kind === "added") {
+      added.push(line);
+      continue;
+    }
+
+    // A removal after an addition starts a new replacement rather than joining the last.
+    if (added.length > 0) {
+      zip();
+    }
+    removed.push(line);
+  }
+
+  zip();
+
+  return pairs;
+}
+
+export const DiffPairs = { pair };

package/packages/core/src/view/MovePath.ts

@@ -0,0 +1,70 @@
+/**
+ * A file that moved, read as one path rather than two. Everything the old and
+ * new paths agree on is said once, and only the segments that actually changed
+ * are named on both sides — `packages/{web ➝ tui}/src/App.tsx` rather than two
+ * near-identical paths a reader has to diff by eye.
+ */
+export type MoveParts = {
+  /** The leading directories both paths share, with its trailing `/`. */
+  readonly prefix: string;
+  /** What those segments used to be. */
+  readonly from: string;
+  /** What they are now. */
+  readonly to: string;
+  /** The trailing segments both paths share, with its leading `/`. */
+  readonly suffix: string;
+};
+
+/** The arrow every surface draws a move with. */
+const ARROW = "➝";
+
+/**
+ * The shared head and tail of a move, or `undefined` when there is nothing
+ * worth folding: two paths that share no segment read better whole, since a
+ * brace around the entire path only adds punctuation. Two bare filenames are
+ * the exception — `{old.ts ➝ new.ts}` shares no segment but is still one name.
+ */
+function fold(oldPath: string, newPath: string): MoveParts | undefined {
+  const oldParts = oldPath.split("/");
+  const newParts = newPath.split("/");
+
+  let head = 0;
+  while (
+    head < oldParts.length &&
+    head < newParts.length &&
+    oldParts[head] === newParts[head]
+  ) {
+    head += 1;
+  }
+
+  let tail = 0;
+  while (
+    tail < oldParts.length - head &&
+    tail < newParts.length - head &&
+    oldParts[oldParts.length - tail - 1] ===
+      newParts[newParts.length - tail - 1]
+  ) {
+    tail += 1;
+  }
+
+  const from = oldParts.slice(head, oldParts.length - tail);
+  const to = newParts.slice(head, newParts.length - tail);
+  const bareNames = oldParts.length === 1 && newParts.length === 1;
+
+  if (
+    from.length === 0 ||
+    to.length === 0 ||
+    (head === 0 && tail === 0 && !bareNames)
+  ) {
+    return undefined;
+  }
+
+  return {
+    prefix: head > 0 ? `${oldParts.slice(0, head).join("/")}/` : "",
+    from: from.join("/"),
+    to: to.join("/"),
+    suffix: tail > 0 ? `/${oldParts.slice(-tail).join("/")}` : "",
+  };
+}
+
+export const MovePath = { ARROW, fold };

package/packages/daemon/src/WebSurface.ts

@@ -25,8 +25,7 @@ function create(args: ReadonlyArray<string>, runtime: AgentRuntime): Surface {
             SendFileTool.build({ store, cwd, sessionId })
           ) as ToolDefinition,
         ],
-        systemInstruction: async () =>
-          "The user is interacting with you via a web browser.",
+        surface: "web browser",
       });
       await registry.init();
 

package/packages/protocol/src/Command.ts

@@ -1,4 +1,4 @@
-import type { ProtocolVersion } from "./Protocol";
+import type { DiffBase, LineSpan } from "./Diff";
 
 /** A file already uploaded via `POST /upload`, by the id that endpoint answered with; never a client-local path. */
 export type AttachmentRef = {
@@ -11,13 +11,16 @@ export type Command =
   | {
       readonly id: string;
       readonly type: "attach";
-      readonly protocolVersion: ProtocolVersion;
       readonly sessionId?: string;
       readonly cwd?: string;
       /** Copy model, thinking level and cwd from this session; ignored when `sessionId` is set or the session is not held open. */
       readonly like?: string;
       readonly fromSeq: number;
+      /** Whether the client is looking at this session right now; absent means yes. */
+      readonly attentive?: boolean;
     }
+  /** Whether this connection's reader is present: an inattentive one never consumes a turn as read. */
+  | { readonly id: string; readonly type: "attention"; readonly value: boolean }
   /** Sent into a running turn it steers that turn, landing before the next model call. */
   | {
       readonly id: string;
@@ -60,11 +63,123 @@ export type Command =
       /** Restrict to one working directory; omit for every session on disk. */
       readonly cwd?: string;
       readonly limit?: number;
+      /** Keep at most this many sessions per working directory, so one busy project cannot fill the page. */
+      readonly perProject?: number;
+      /** List the archived sessions instead of the live ones. */
+      readonly archived?: boolean;
+    }
+  /** Ranked search over every session on disk, titles and what was said; an empty `query` warms the index and answers with no hits. */
+  | {
+      readonly id: string;
+      readonly type: "search_sessions";
+      readonly query: string;
+      readonly limit?: number;
+      /** Restrict to one working directory; omit for every session on disk. */
+      readonly cwd?: string;
+      /** Omitted, the archived are searched too and their hits say so; `false` leaves them out, `true` searches only them. */
+      readonly archived?: boolean;
+    }
+  /** Names a session through pi's own `session_info`, so its terminal picker shows the name too; `null` clears it. */
+  | {
+      readonly id: string;
+      readonly type: "set_session_name";
+      readonly sessionId: string;
+      readonly value: string | null;
+    }
+  /** pim's own overrides on a session: out of the default listing, or held unread until it is answered. */
+  | {
+      readonly id: string;
+      readonly type: "set_session_archived" | "set_session_unread";
+      readonly sessionId: string;
+      readonly value: boolean;
+    }
+  /**
+   * pim's own overrides on a working directory rather than a session: pinned
+   * sorts it above every other, expanded stands its sidebar group unfolded.
+   */
+  | {
+      readonly id: string;
+      readonly type: "set_project_pinned" | "set_project_expanded";
+      readonly cwd: string;
+      readonly value: boolean;
+    }
+  /** Names a working directory for the listings; `null` puts it back to its base name, and the directory is never renamed. */
+  | {
+      readonly id: string;
+      readonly type: "set_project_label";
+      readonly cwd: string;
+      readonly value: string | null;
+    }
+  /** Re-orders the pinned projects. The whole order, never a move: two surfaces settle on the last one sent. */
+  | {
+      readonly id: string;
+      readonly type: "set_pin_order";
+      readonly order: readonly string[];
     }
   /** The models this server can switch to, plus the current model's thinking levels; answers without a session. */
   | { readonly id: string; readonly type: "list_models" }
   /** Subdirectories of `path` on the server's filesystem; errors rather than answering empty when it is not a readable directory. */
   | { readonly id: string; readonly type: "list_dirs"; readonly path: string }
+  /** Re-read the cwd's git state now; `fetch` asks the remote first, which is the only thing that moves ahead and behind. */
+  | {
+      readonly id: string;
+      readonly type: "refresh_git";
+      readonly sessionId: string;
+      readonly fetch?: boolean;
+    }
+  /** The cwd's local branches, trunk first and the rest by how recently they were worked on. */
+  | {
+      readonly id: string;
+      readonly type: "list_branches";
+      readonly sessionId: string;
+    }
+  /** Every changed file of one diff base, without a hunk of any of them; read-only, so never refused. */
+  | {
+      readonly id: string;
+      readonly type: "list_changes";
+      readonly sessionId: string;
+      readonly base: DiffBase;
+    }
+  /** One file's hunks, computed only once a reader expands it; `context` defaults to 3. */
+  | {
+      readonly id: string;
+      readonly type: "file_diff";
+      readonly sessionId: string;
+      readonly base: DiffBase;
+      readonly path: string;
+      readonly context?: number;
+    }
+  /** The file's own lines behind a gap between hunks, asked for when a reader opens one. */
+  | {
+      readonly id: string;
+      readonly type: "read_lines";
+      readonly sessionId: string;
+      readonly base: DiffBase;
+      readonly path: string;
+      readonly spans: readonly LineSpan[];
+    }
+  /** Refused while any session in the same directory is mid-turn: the agent may be halfway through an edit. */
+  | {
+      readonly id: string;
+      readonly type: "checkout";
+      readonly sessionId: string;
+      readonly branch: string;
+    }
+  /** `pull` is fast-forward only; `push` adopts an upstream the first time a branch is published. */
+  | {
+      readonly id: string;
+      readonly type: "pull" | "push";
+      readonly sessionId: string;
+    }
+  /** Path-limited: exactly `paths` are staged and committed, everything else changed stays dirty. Refused mid-turn, like `checkout`. */
+  | {
+      readonly id: string;
+      readonly type: "commit";
+      readonly sessionId: string;
+      readonly message: string;
+      /** A renamed file contributes both of its names, or its old one is left behind. */
+      readonly paths: readonly string[];
+    }
   /** Read-only view of a subagent's transcript; `callId` is the parent's tool call and `sessionId` must be this connection's session. */
   | {
       readonly id: string;
@@ -90,3 +205,15 @@ export type CommandDraft = Command extends infer T
     ? Omit<T, "id">
     : never
   : never;
+
+/** Which sessions a listing is asking for: the `list_sessions` payload, named so a client can pass it around. */
+export type SessionScope = Omit<
+  Extract<CommandDraft, { readonly type: "list_sessions" }>,
+  "type"
+>;
+
+/** Which sessions a search may reach: the `search_sessions` payload without the query it is asked with. */
+export type SearchScope = Omit<
+  Extract<CommandDraft, { readonly type: "search_sessions" }>,
+  "type" | "query"
+>;

package/packages/protocol/src/Diff.ts

@@ -0,0 +1,15 @@
+/**
+ * The diff wire shape. Declared beside the git that produces it, the way
+ * `GitBranch` and `ToolView` are, and named here so the two commands that
+ * carry it read as protocol.
+ */
+export type {
+  ChangeList,
+  ChangeStatus,
+  ChangeSummary,
+  DiffBase,
+  FileLines,
+  FileDiff,
+  LineRun,
+  LineSpan,
+} from "#core/shared/RepoDiff";