pim-agent 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pim-agent",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A batteries-included distro of Pi, accessible in your terminal, browser and Telegram.",
   "license": "MIT",
   "type": "module",
@@ -56,7 +56,6 @@
     "web:dev": "cd packages/web && vite"
   },
   "devDependencies": {
-    "@fontsource/commit-mono": "^5.3.0",
     "@happy-dom/global-registrator": "^20.14.0",
     "@iconify-json/griddy-icons": "^1.2.0",
     "@iconify-json/solar": "^1.2.10",

package/packages/core/src/extensions/bash/index.ts

@@ -42,7 +42,8 @@ export default function (pi: ExtensionAPI): void {
     name: "bash",
     label: "bash",
     description:
-      "Execute a bash command in the cwd. " +
+      "Execute a bash command in the cwd from <environment>. " +
+      "Never prefix `cd <cwd> &&`; pass paths relative to cwd or absolute. " +
       "Returns exit code, signal (if any), and stdout/stderr captured separately. " +
       "Stdout that is a png/jpeg/gif/webp is returned as a picture. " +
       "Prefer commands that emit only what you need; keep output as small as possible.",

package/packages/core/src/extensions/bash/run.ts

@@ -14,6 +14,12 @@ type Reader = ReadableStreamDefaultReader<Uint8Array>;
 
 const activePids = new Set<number>();
 
+const COMMAND_VAR = "PIM_BASH_COMMAND";
+// argv is what `pkill -f`/`pgrep -f` match, so a command naming its own target would
+// signal this shell before its target. The env hands it over out of argv's reach, and
+// the unset keeps it out of every child's environment too.
+const RUNNER = `__pim_command=$${COMMAND_VAR}; unset ${COMMAND_VAR}; eval "$__pim_command"`;
+
 export function killAllActiveBashGroups(sig: NodeJS.Signals = "SIGTERM"): void {
   for (const pid of activePids) {
     killGroup(pid, sig);
@@ -97,11 +103,11 @@ export async function runBashCommand(
 
   // setsid gives the tree its own process group (pgid == proc.pid) so the whole tree can be signalled.
   const proc = Bun.spawn({
-    cmd: ["setsid", "bash", "-lc", command],
+    cmd: ["setsid", "bash", "-lc", RUNNER],
     cwd,
     stdout: "pipe",
     stderr: "pipe",
-    env: { ...process.env },
+    env: { ...process.env, [COMMAND_VAR]: command },
   });
   if (proc.pid !== undefined) {
     activePids.add(proc.pid);

package/packages/core/src/extensions/system-prompt/index.ts

@@ -5,10 +5,25 @@ import type {
 import { formatSkillsForPrompt } from "@earendil-works/pi-coding-agent";
 
 import type { Surface } from "../../shared/Surface";
-import { buildSystemPrompt } from "./prompt";
+import { buildSystemPrompt, formatDatetime } from "./prompt";
+
+const DATETIME_MESSAGE_TYPE = "pim-datetime";
 
 export default function (surface?: Surface): ExtensionFactory {
   return (pi: ExtensionAPI): void => {
+    // On submit rather than in `before_agent_start`, which can only append
+    // behind the user's message.
+    pi.on("input", () => {
+      pi.sendMessage(
+        {
+          customType: DATETIME_MESSAGE_TYPE,
+          content: `<datetime>${formatDatetime(new Date())}</datetime>`,
+          display: false,
+        },
+        { triggerTurn: false }
+      );
+      return { action: "continue" };
+    });
     pi.on("before_agent_start", (event, ctx) => {
       const {
         cwd,

package/packages/core/src/extensions/system-prompt/prompt.ts

@@ -61,7 +61,6 @@ export function buildSystemPrompt(opts: BuildOptions): string {
       `- os: ${opts.os ?? describeOs()}`,
       `- model: ${model}`,
       ...(opts.surface ? [`- surface: ${opts.surface}`] : []),
-      `- datetime: ${formatDatetime(new Date())}`,
       "</environment>",
     ].join("\n")
   );
@@ -210,7 +209,7 @@ function unquoteValue(value: string): string {
   return quote === "'" ? unquoted : unquoted.replace(/\\(["\\$`])/g, "$1");
 }
 
-function formatDatetime(d: Date): string {
+export function formatDatetime(d: Date): string {
   const pad = (n: number): string => String(n).padStart(2, "0");
   const offsetMinutes = -d.getTimezoneOffset();
   const sign = offsetMinutes >= 0 ? "+" : "-";

package/packages/core/src/session/SessionHost.ts

@@ -15,6 +15,7 @@ import {
   SettingsManager,
   type AgentSessionEvent,
   type CompactionResult,
+  type ExtensionError,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { unlink } from "node:fs/promises";
@@ -30,6 +31,7 @@ import {
   type LeaseRecord,
 } from "./SessionLease";
 import { SessionName } from "./SessionName";
+import { adaptSessionUi, type SessionUi } from "./SessionUi";
 import { WriteMark } from "./WriteMark";
 
 /** What the agent is doing right now. */
@@ -102,6 +104,13 @@ export type SessionHostDeps = {
   ) => readonly ToolDefinition[];
   /** Runs after the agent is disposed, before the session file is forgotten. */
   readonly onRetire?: (sessionPath: string) => Promise<void>;
+  /**
+   * Where this host's extensions say things, resolved per call so an agent
+   * rebuilt under the host follows its live target. Omit to leave pi's no-op
+   * UI in place: pi freezes the mode at `bindExtensions`, so this is a dep
+   * rather than something a caller can turn on once a session exists.
+   */
+  readonly ui?: () => SessionUi | undefined;
 };
 
 /** What a frontend's own tools are built against. */
@@ -770,16 +779,33 @@ export class SessionHost {
       ],
     });
 
-    // Emits session_start; without it extension tools are registered but never usable.
-    await agent.bindExtensions({
-      mode: "print",
-      onError: (err) => {
-        console.warn(
-          `[${this.label}] extension ${err.extensionPath} (${err.event}):`,
-          err.error
+    const onError = (err: ExtensionError) => {
+      console.warn(
+        `[${this.label}] extension ${err.extensionPath} (${err.event}):`,
+        err.error
+      );
+      // Pi answers a command handler that threw as if it had succeeded, so
+      // without this the user's message vanishes and only stderr says why.
+      this.deps
+        .ui?.()
+        ?.notify(
+          `${err.extensionPath} (${err.event}) failed: ${err.error}`,
+          "error"
         );
-      },
-    });
+    };
+    const ui = this.deps.ui;
+    // Emits session_start; without it extension tools are registered but never usable.
+    await agent.bindExtensions(
+      ui
+        ? // Any context at all makes pi's `hasUI()` true (`uiContext !== noOpUIContext`,
+          // runner.js:318); "rpc" is its own name for dialog-capable but not a terminal.
+          {
+            uiContext: adaptSessionUi(ui),
+            mode: "rpc",
+            onError,
+          }
+        : { mode: "print", onError }
+    );
 
     return { agent, cwd };
   }

package/packages/core/src/session/SessionRegistry.ts

@@ -18,6 +18,7 @@ import {
 } from "./SessionHost";
 import { SessionLease } from "./SessionLease";
 import { SessionName } from "./SessionName";
+import type { SessionUi } from "./SessionUi";
 
 /** A session as pi stores it: one JSONL file under a cwd-encoded directory. */
 export type SessionSummary = {
@@ -58,6 +59,7 @@ export class SessionRegistry {
   private readonly deps: SessionRegistryDeps;
   private readonly runtime: AgentRuntime;
   private readonly hosts: SessionCache<SessionHost>;
+  private ui: ((host: SessionHost) => SessionUi | undefined) | undefined;
 
   public constructor(deps: SessionRegistryDeps) {
     this.deps = deps;
@@ -65,10 +67,24 @@ export class SessionRegistry {
     this.hosts = new SessionCache(deps.capacity);
   }
 
+  /**
+   * Where the extensions of every host built from here speak. It belongs to the
+   * registry rather than each caller because `create` binds an agent eagerly,
+   * and pi freezes a session's UI mode at that bind. Resolved per call: a
+   * host outlives the stream that speaks for it.
+   */
+  public setUi(ui: (host: SessionHost) => SessionUi | undefined): void {
+    this.ui = ui;
+  }
+
   public get sessionsRoot(): string {
     return join(this.runtime.agentDir, "sessions");
   }
 
+  public get agentDir(): string {
+    return this.runtime.agentDir;
+  }
+
   public async init(): Promise<void> {
     await this.runtime.init();
   }
@@ -207,7 +223,10 @@ export class SessionRegistry {
   }
 
   private buildHost(label: string, settings: HostSettings): SessionHost {
-    return new SessionHost({
+    const ui = this.ui;
+    // Named so the sink can reach back for the host it belongs to; the closure
+    // only ever runs once construction has returned.
+    const host: SessionHost = new SessionHost({
       label: `session ${label}`,
       settings,
       defaults: this.deps.defaults,
@@ -225,7 +244,9 @@ export class SessionRegistry {
       ...(this.deps.surface === undefined
         ? {}
         : { surface: this.deps.surface }),
+      ...(ui === undefined ? {} : { ui: () => ui(host) }),
     });
+    return host;
   }
 }
 

package/packages/core/src/session/SessionUi.ts

@@ -0,0 +1,127 @@
+import type {
+  ExtensionUIContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+
+import type { NoticeSeverity } from "../view/ViewBlock";
+
+/** The slice of pi's dialog options a surface without a terminal can honour; the rest is countdown chrome. */
+export type UiAsk = {
+  readonly timeout?: number;
+  readonly signal?: AbortSignal;
+};
+
+/** Where an extension's own words go. Four of pi's thirty methods: the ones that address a human rather than a terminal. */
+export type SessionUi = {
+  readonly notify: (text: string, severity: NoticeSeverity) => void;
+  readonly select: (
+    title: string,
+    options: readonly string[],
+    opts?: UiAsk
+  ) => Promise<string | undefined>;
+  readonly confirm: (
+    title: string,
+    message: string,
+    opts?: UiAsk
+  ) => Promise<boolean>;
+  readonly input: (
+    title: string,
+    placeholder?: string,
+    opts?: UiAsk
+  ) => Promise<string | undefined>;
+};
+
+/** Everything off the terminal paints with; also what pi's border getters hand back. */
+const IDENTITY = (text: string): string => text;
+
+/**
+ * pi keeps its own `theme` instance to itself, and nothing off the terminal has
+ * colours to paint with. `satisfies` covers the whole public surface — `keyof`
+ * skips the private fields the cast is for — so a method pi adds is a type
+ * error here rather than a throw inside somebody's event handler.
+ */
+const PLAIN_THEME = {
+  fg: (_color: string, text: string) => text,
+  bg: (_color: string, text: string) => text,
+  bold: IDENTITY,
+  italic: IDENTITY,
+  underline: IDENTITY,
+  inverse: IDENTITY,
+  strikethrough: IDENTITY,
+  getFgAnsi: () => "",
+  getBgAnsi: () => "",
+  getColorMode: () => "truecolor",
+  getThinkingBorderColor: () => IDENTITY,
+  getBashModeBorderColor: () => IDENTITY,
+} satisfies { [K in keyof Theme]: Theme[K] } as unknown as Theme;
+
+function severityOf(
+  kind: Parameters<ExtensionUIContext["notify"]>[1]
+): NoticeSeverity {
+  return kind === "warning" ? "warn" : (kind ?? "info");
+}
+
+/** A dialog an extension awaits goes unanswered rather than ever throwing at it. */
+async function settle<T>(
+  ask: () => Promise<T> | undefined
+): Promise<T | undefined> {
+  try {
+    return await ask();
+  } catch (err) {
+    console.warn("[SessionUi] dialog sink failed:", err);
+    return undefined;
+  }
+}
+
+/**
+ * Widens the sink onto pi's `ExtensionUIContext`, no-opping everything a
+ * terminal owns exactly as pi's own RPC mode does. `sink` is read per call, so
+ * an agent rebuilt under a host keeps whatever its host was last handed.
+ *
+ * Every method has to be an *own* property: pi re-wraps what it is given with
+ * `{ ...ui }` (`runner.js:274`), which copies own enumerable keys only. A class
+ * instance would arrive with `notify` and the rest of the prototype missing.
+ */
+export function adaptSessionUi(
+  sink: () => SessionUi | undefined
+): ExtensionUIContext {
+  return {
+    select: (title, options, opts) =>
+      settle(() => sink()?.select(title, options, opts)),
+    confirm: async (title, message, opts) =>
+      (await settle(() => sink()?.confirm(title, message, opts))) === true,
+    input: (title, placeholder, opts) =>
+      settle(() => sink()?.input(title, placeholder, opts)),
+    notify: (message, kind) => {
+      try {
+        sink()?.notify(message, severityOf(kind));
+      } catch (err) {
+        console.warn("[SessionUi] notify sink failed:", err);
+      }
+    },
+    onTerminalInput: () => () => {},
+    setStatus: () => {},
+    setWorkingMessage: () => {},
+    setWorkingVisible: () => {},
+    setWorkingIndicator: () => {},
+    setHiddenThinkingLabel: () => {},
+    setWidget: () => {},
+    setFooter: () => {},
+    setHeader: () => {},
+    setTitle: () => {},
+    custom: async <T>() => undefined as T,
+    pasteToEditor: () => {},
+    setEditorText: () => {},
+    getEditorText: () => "",
+    editor: async () => undefined,
+    addAutocompleteProvider: () => {},
+    setEditorComponent: () => {},
+    getEditorComponent: () => undefined,
+    theme: PLAIN_THEME,
+    getAllThemes: () => [],
+    getTheme: () => undefined,
+    setTheme: () => ({ success: false, error: "UI not available" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded: () => {},
+  };
+}

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

@@ -1,5 +1,5 @@
-import { readdir, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { mkdir, readdir, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
 import { FsErrors } from "./FsErrors";
 import { Paths } from "./Paths";
@@ -29,12 +29,16 @@ async function check(path: string): Promise<string | undefined> {
   }
 }
 
-async function list(path: string): Promise<DirectoryListing> {
+function rooted(path: string): string {
   const expanded = Paths.expandHome(path);
   if (!isAbsolute(expanded)) {
     throw new Error(`not an absolute path: ${path}`);
   }
-  const resolved = resolve(expanded);
+  return resolve(expanded);
+}
+
+async function list(path: string): Promise<DirectoryListing> {
+  const resolved = rooted(path);
   const reason = await check(resolved);
   if (reason !== undefined) {
     throw new Error(reason);
@@ -58,4 +62,34 @@ async function list(path: string): Promise<DirectoryListing> {
   };
 }
 
-export const Directories = { check, list };
+function refusal(error: unknown, path: string): string {
+  switch (FsErrors.code(error)) {
+    case "ENOENT":
+      return `path does not exist: ${dirname(path)}`;
+    case "EEXIST":
+      return `already exists: ${path}`;
+    case "ENOTDIR":
+      return `not a directory: ${dirname(path)}`;
+    case "EACCES":
+    case "EPERM":
+      return `permission denied: ${path}`;
+    default:
+      return `mkdir failed: ${(error as Error).message}`;
+  }
+}
+
+/** Makes one directory inside an existing one. Never recursive: a parent that is missing is said so, not invented. */
+async function create(path: string): Promise<void> {
+  const name = basename(Paths.expandHome(path));
+  if (name === "" || name === "." || name === "..") {
+    throw new Error(`not a directory to create: ${path}`);
+  }
+  const resolved = rooted(path);
+  try {
+    await mkdir(resolved);
+  } catch (error) {
+    throw new Error(refusal(error, resolved));
+  }
+}
+
+export const Directories = { check, list, create };

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

@@ -34,6 +34,13 @@ const DEFAULT_DISABLED: readonly PimExtensionName[] = ["todo", "tps"];
 
 const REQUIRED: readonly PimExtensionName[] = ["_init", "pim", "session-lease"];
 
+// Hardcoded, never derived: the browser switches these and nothing else, under
+// the label it gives them — the terminal menu names them by key, this does not.
+const WEB = [{ name: "todo", label: "Todo Tool" }] as const satisfies readonly {
+  name: PimExtensionName;
+  label: string;
+}[];
+
 function isRequired(name: string): boolean {
   return (REQUIRED as readonly string[]).includes(name);
 }
@@ -119,6 +126,7 @@ function enabled(
 export const ExtensionToggles = {
   REQUIRED,
   NAMES,
+  WEB,
   isRequired,
   isKnown,
   describe,

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

@@ -0,0 +1,228 @@
+import {
+  DefaultPackageManager,
+  type PackageSource,
+  type ResolvedResource,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { basename, dirname, extname, relative } from "node:path";
+
+import { ExtensionToggles } from "./ExtensionToggles";
+import { Fs } from "./Fs";
+import { Paths } from "./Paths";
+
+/**
+ * Every origin an entry comes from, in the order a reader meets them: the
+ * roster is sorted by it, and a pane groups what it is handed without
+ * restating it.
+ */
+const EXTENSION_GROUPS = ["pim", "package", "user", "project"] as const;
+
+export type ExtensionGroup = (typeof EXTENSION_GROUPS)[number];
+
+export type ExtensionEntry = {
+  readonly id: string;
+  readonly label: string;
+  readonly group: ExtensionGroup;
+  readonly enabled: boolean;
+  /** Whether this process will write the toggle; a project-scoped entry is listed but not switched. */
+  readonly writable: boolean;
+};
+
+export type ExtensionScope = {
+  readonly cwd: string;
+  readonly agentDir: string;
+};
+
+type Resolution = {
+  readonly extensions: readonly ResolvedResource[];
+  readonly settingsManager: SettingsManager;
+};
+
+type PackageFilter = Exclude<PackageSource, string>;
+
+const FILTER_KEYS = ["extensions", "skills", "prompts", "themes"] as const;
+
+const writes = Fs.serialised();
+
+async function list(scope: ExtensionScope): Promise<readonly ExtensionEntry[]> {
+  const [off, { extensions }] = await Promise.all([
+    ExtensionToggles.disabled(),
+    resolve(scope),
+  ]);
+  const disabled = new Set(off);
+  const pim = ExtensionToggles.WEB.map((allowed) =>
+    pimEntry(allowed, !disabled.has(allowed.name))
+  );
+  const pi = extensions
+    .filter((resource) => resource.metadata.scope !== "temporary")
+    .map(piEntry)
+    .sort(byGroupThenLabel);
+  return [...pim, ...pi];
+}
+
+async function setEnabled(
+  id: string,
+  enabled: boolean,
+  scope: ExtensionScope
+): Promise<void> {
+  const pim = ExtensionToggles.WEB.find((entry) => `pim:${entry.name}` === id);
+  if (pim) {
+    await ExtensionToggles.setDisabled(pim.name, !enabled);
+    return;
+  }
+  if (!id.startsWith("pi:")) {
+    throw new Error(`Unknown extension "${id}"`);
+  }
+  await writes.run(() => writePiToggle(id.slice("pi:".length), enabled, scope));
+}
+
+// A fresh SettingsManager per write: `setExtensionPaths` persists its in-memory
+// copy, which another process may have superseded since we last read it.
+async function writePiToggle(
+  path: string,
+  enabled: boolean,
+  scope: ExtensionScope
+): Promise<void> {
+  const { extensions, settingsManager } = await resolve(scope);
+  const resource = extensions.find((candidate) => candidate.path === path);
+  if (!resource) {
+    throw new Error(`Unknown extension "pi:${path}"`);
+  }
+  const { metadata } = resource;
+  if (metadata.scope !== "user") {
+    throw new Error(
+      `"${path}" is ${metadata.scope}-scoped and cannot be switched from here`
+    );
+  }
+  if (metadata.origin === "package") {
+    togglePackage(
+      settingsManager,
+      metadata.source,
+      relative(metadata.baseDir ?? dirname(path), path),
+      enabled
+    );
+  } else {
+    toggleTopLevel(
+      settingsManager,
+      relative(metadata.baseDir ?? scope.agentDir, path),
+      enabled
+    );
+  }
+  await settingsManager.flush();
+  const failure = settingsManager.drainErrors()[0];
+  if (failure) {
+    throw new Error(`Failed to write pi settings: ${failure.error.message}`);
+  }
+}
+
+function toggleTopLevel(
+  settingsManager: SettingsManager,
+  pattern: string,
+  enabled: boolean
+): void {
+  const current = settingsManager.getGlobalSettings().extensions ?? [];
+  settingsManager.setExtensionPaths(withPattern(current, pattern, enabled));
+}
+
+function togglePackage(
+  settingsManager: SettingsManager,
+  source: string,
+  pattern: string,
+  enabled: boolean
+): void {
+  const packages = [...(settingsManager.getGlobalSettings().packages ?? [])];
+  const index = packages.findIndex((entry) => sourceOf(entry) === source);
+  const entry = packages[index];
+  if (entry === undefined) {
+    throw new Error(`No configured package provides "${source}"`);
+  }
+  const pkg: PackageFilter =
+    typeof entry === "string" ? { source: entry } : { ...entry };
+  const updated = withPattern(pkg.extensions ?? [], pattern, enabled);
+  pkg.extensions = updated.length > 0 ? updated : undefined;
+  packages[index] = FILTER_KEYS.some((key) => pkg[key] !== undefined)
+    ? pkg
+    : pkg.source;
+  settingsManager.setPackages(packages);
+}
+
+function withPattern(
+  current: readonly string[],
+  pattern: string,
+  enabled: boolean
+): string[] {
+  const kept = current.filter((entry) => stripMarker(entry) !== pattern);
+  return [...kept, `${enabled ? "+" : "-"}${pattern}`];
+}
+
+function stripMarker(entry: string): string {
+  return /^[!+-]/.test(entry) ? entry.slice(1) : entry;
+}
+
+function sourceOf(entry: PackageSource): string {
+  return typeof entry === "string" ? entry : entry.source;
+}
+
+async function resolve(scope: ExtensionScope): Promise<Resolution> {
+  const { cwd, agentDir } = scope;
+  const settingsManager = SettingsManager.create(cwd, agentDir);
+  const manager = new DefaultPackageManager({
+    cwd,
+    agentDir,
+    settingsManager,
+  });
+  // Without an answer, pi npm-installs every missing or drifted package, so a
+  // bare listing request would fire off an install.
+  const resolved = await manager.resolve(async () => "skip");
+  return { extensions: resolved.extensions, settingsManager };
+}
+
+function pimEntry(
+  allowed: (typeof ExtensionToggles.WEB)[number],
+  enabled: boolean
+): ExtensionEntry {
+  return {
+    id: `pim:${allowed.name}`,
+    label: allowed.label,
+    group: "pim",
+    enabled,
+    writable: true,
+  };
+}
+
+function piEntry(resource: ResolvedResource): ExtensionEntry {
+  const { path, metadata } = resource;
+  const fromPackage = metadata.origin === "package";
+  const group = fromPackage
+    ? "package"
+    : metadata.scope === "project"
+      ? "project"
+      : "user";
+  return {
+    id: `pi:${path}`,
+    label: fromPackage
+      ? metadata.source.replace(/^(?:npm|git):/, "")
+      : fileLabel(path),
+    group,
+    enabled: resource.enabled,
+    // Scope, not group: a package a project configures is written to the repo's
+    // settings, which a browser toggle never touches.
+    writable: metadata.scope === "user",
+  };
+}
+
+function fileLabel(path: string): string {
+  const base = basename(path, extname(path));
+  return base === "index" ? basename(dirname(path)) : base;
+}
+
+function byGroupThenLabel(left: ExtensionEntry, right: ExtensionEntry): number {
+  const byGroup =
+    EXTENSION_GROUPS.indexOf(left.group) -
+    EXTENSION_GROUPS.indexOf(right.group);
+  return byGroup === 0
+    ? Paths.compare(left.label.toLowerCase(), right.label.toLowerCase())
+    : byGroup;
+}
+
+export const PiExtensions = { list, setEnabled };