pim-agent 0.10.0 → 0.12.0

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 };

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

@@ -3,7 +3,7 @@ import type {
   ExtensionAPI,
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { validateToolArguments } from "@earendil-works/pi-ai";
+import { validateToolArguments, type JsonObject } from "@earendil-works/pi-ai";
 import type { Static, TSchema } from "typebox";
 import { Levenshtein } from "./Levenshtein";
 import { Renderer } from "./Renderer";
@@ -169,7 +169,7 @@ function wrap<TParams extends TSchema, TDetails = unknown, TState = unknown>(
             type: "toolCall",
             id: "",
             name: def.name,
-            arguments: cleaned as Record<string, unknown>,
+            arguments: cleaned as JsonObject,
           }
         ) as Static<TParams>;
       } catch (err) {
@@ -461,7 +461,7 @@ function revalidateBranch(branch: JsonSchema, value: unknown): Issue[] {
         type: "toolCall",
         id: "",
         name: "_branch",
-        arguments: (value ?? {}) as Record<string, unknown>,
+        arguments: (value ?? {}) as JsonObject,
       }
     );
     return [];

package/packages/protocol/src/Command.ts

@@ -118,8 +118,19 @@ export type Command =
     }
   /** 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" }
+  /** The extensions this server can switch on and off, read against the connection's cwd when it has one. */
+  | { readonly id: string; readonly type: "list_extensions" }
+  /** Switch one extension on or off; the sessions built from here pick it up as each rebuilds its agent. */
+  | {
+      readonly id: string;
+      readonly type: "set_extension";
+      readonly extensionId: string;
+      readonly value: boolean;
+    }
   /** 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 }
+  /** Makes the directory `path` names, one level inside an existing one; answers empty, and the caller re-lists. */
+  | { readonly id: string; readonly type: "create_dir"; 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;
@@ -195,7 +206,17 @@ export type Command =
       readonly callId: string;
     }
   /** Update this install and restart it unconditionally; refused while any session is mid-turn unless `force`. */
-  | { readonly id: string; readonly type: "reload"; readonly force?: boolean };
+  | { readonly id: string; readonly type: "reload"; readonly force?: boolean }
+  /** Answers one `ui_request`; dismissal is `cancelled`, and a late answer to a settled request is refused. */
+  | {
+      readonly id: string;
+      readonly type: "ui_response";
+      readonly sessionId: string;
+      readonly requestId: string;
+      readonly value?: string;
+      readonly confirmed?: boolean;
+      readonly cancelled?: boolean;
+    };
 
 export type CommandType = Command["type"];
 

package/packages/protocol/src/ServerEvent.ts

@@ -1,6 +1,7 @@
 import type { DirectoryListing } from "#core/shared/Directories";
 import type { CommitResult, GitBranch } from "#core/shared/Git";
 import type { PickerItem } from "#core/picker/PickerItem";
+import type { ExtensionEntry } from "#core/shared/PiExtensions";
 import type { SearchRange, SearchSnippet } from "#core/session/SearchIndex";
 import type { LeaseFrontend } from "#core/session/SessionLease";
 import type { UpdateSkip } from "#core/shared/Updater";
@@ -154,6 +155,29 @@ export type EphemeralEvent =
       readonly events: readonly StreamEvent[];
     }
   | { readonly type: "turn_end"; readonly stats: TurnStats }
+  /** Something an extension said, in Markdown; shown and then forgotten, never written to the session. */
+  | {
+      readonly type: "ui_notice";
+      readonly id: string;
+      readonly severity: NoticeSeverity;
+      readonly text: string;
+      /** The command being dispatched when it was said, like `/login`; absent means nobody asked for it. */
+      readonly command?: string;
+    }
+  /** An extension is waiting on a human; the first `ui_response` wins and the rest are refused. */
+  | {
+      readonly type: "ui_request";
+      readonly requestId: string;
+      readonly method: "select" | "confirm" | "input";
+      readonly title: string;
+      readonly message?: string;
+      readonly options?: readonly string[];
+      readonly placeholder?: string;
+      /** The command that asked, like `/login`; absent where an extension asked unprompted. */
+      readonly command?: string;
+    }
+  /** The request is settled, by whoever answered it or by the server answering for them; drop its control. */
+  | { readonly type: "ui_request_done"; readonly requestId: string }
   /** Sent to every connection, not just those attached; only sessions this server holds open are reported. */
   | {
       readonly type: "session_activity";
@@ -188,6 +212,8 @@ export type EphemeralEvent =
   | { readonly type: "pins_changed"; readonly order: readonly string[] }
   /** Sent to every connection: the sessions on disk changed, so any listing a client holds is stale. */
   | { readonly type: "sessions_changed" }
+  /** Sent to every connection: an extension was switched, so any roster a client holds is stale. */
+  | { readonly type: "extensions_changed" }
   /** Sent to every connection; the restart it ends in drops every socket. */
   | UpdateStateEvent
   | {
@@ -327,6 +353,8 @@ export type ResponseEvent = {
   readonly models?: readonly ModelView[];
   /** What the *current* model supports, on the same answer. */
   readonly thinkingLevels?: readonly string[];
+  /** The extension roster, for `list_extensions`. */
+  readonly extensions?: readonly ExtensionEntry[];
   /** One directory's subdirectories, for `list_dirs`. */
   readonly directory?: DirectoryListing;
   /** The cwd's local branches, for `list_branches`. */
@@ -341,6 +369,8 @@ export type ResponseEvent = {
   readonly fileLines?: FileLines;
   /** For `cancel` and `dequeue`: queued messages pi gave back, now owned by the client that asked. */
   readonly restored?: readonly string[];
+  /** For `user_message`: it named an extension command, so no turn started and no entry was written. */
+  readonly dispatched?: boolean;
 };
 
 export type ServerEvent = DurableEvent | EphemeralEvent | ResponseEvent;
@@ -382,6 +412,9 @@ export function isAttachScoped(event: ServerEvent): boolean {
     case "subagent_events":
     case "turn_end":
     case "session_state":
+    case "ui_notice":
+    case "ui_request":
+    case "ui_request_done":
     // Names a cwd, but only ever reaches a client down the session stream it
     // is attached to, so the old session's is the only one that can arrive
     // mid-attach — and re-querying for it would warm the wrong cache.
@@ -393,6 +426,7 @@ export function isAttachScoped(event: ServerEvent): boolean {
     case "project_meta":
     case "pins_changed":
     case "sessions_changed":
+    case "extensions_changed":
     case "update_state":
     // Sent for a frame the server could not read at all, which is likeliest
     // before an attach has settled: gating it swallows the diagnostic.

package/packages/server/src/ProbeClient.ts

@@ -2,6 +2,7 @@ import { basename } from "node:path";
 
 import type { PickerItem } from "#core/picker/PickerItem";
 import { RemoteFilePickerSuggestionEngine } from "#core/picker/RemoteFilePickerSuggestionEngine";
+import type { ExtensionEntry } from "#core/shared/PiExtensions";
 import type {
   AttachmentRef,
   CommandDraft,
@@ -265,6 +266,26 @@ export class ProbeClient {
     };
   }
 
+  /** Every extension this server can switch, scoped to the attached session's cwd. */
+  public async listExtensions(): Promise<readonly ExtensionEntry[]> {
+    const response = await this.send({ type: "list_extensions" });
+    if (!response.success) {
+      throw new Error(response.error ?? "list_extensions failed");
+    }
+    return response.extensions ?? [];
+  }
+
+  public async setExtension(id: string, value: boolean): Promise<void> {
+    const response = await this.send({
+      type: "set_extension",
+      extensionId: id,
+      value,
+    });
+    if (!response.success) {
+      throw new Error(response.error ?? "set_extension failed");
+    }
+  }
+
   /** 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);