@tt-a1i/openpi 0.1.0 → 0.2.0

package/extensions/setup/index.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import {
@@ -6,8 +9,21 @@ import {
   type SubagentRoleModel,
   type SubagentRoleModels,
 } from "../shared/subagent-roles.ts";
+import { sanitizeTerminalText } from "../shared/terminal-text.ts";
+import {
+  OPENPI_SETUP_EPISODE_CHANNEL,
+  type OpenPiSetupEpisodeState,
+} from "../shared/setup-episode-state.ts";
+import { patchOwnedTools } from "../shared/tool-surface.ts";
+import {
+  formatPiIntercomStatus,
+  inspectPiIntercom,
+  installPiIntercom,
+  type PiIntercomStatus,
+} from "./intercom.ts";
 import {
   applyFooterConfig,
+  CAPABILITY_DISCOVERY_MODES,
   DETAIL_DISPLAYS,
   FOOTER_ITEMS,
   FOOTER_LAYOUT_ITEMS,
@@ -23,6 +39,7 @@ import {
   REASONING_LEVELS,
   SETUP_CONFIG_CHANGED_CHANNEL,
   type FooterLayoutItem,
+  type CapabilityDiscoveryMode,
   type FooterPreset,
   type FooterStyle,
   type MyPiSetupConfig,
@@ -92,16 +109,16 @@ export function buildInteractiveSetupPrompt(options: {
 }) {
   const configurationState = options.savedConfigExists
     ? [
-        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Next-action suggestions, Workflow limits, UI/Footer, result detail display, Post-edit, Agent role models, or review everything.",
+        "This package has already been configured. Explain the current settings in the user's language, then ask whether they want to keep them or change Capability discovery, Next-action suggestions, Workflow limits, UI/Footer, result detail display, Post-edit, Agent role models, or review everything.",
         "If the user keeps the current settings, do not call configure_my_pi_setup. If they choose a category, ask only the follow-up needed for that category.",
       ]
     : [
         "This is the first setup. Explain the available choices and their impact in the user's language, then collect the initial preferences.",
-        "Prefer one ask_user call with up to three independent questions covering Next-action suggestions, Workflow limits, and UI/Footer/result display. Explain that Post-edit defaults off; keep it off unless the user opts in, then ask only for the command. Explain that built-in Agent roles used by subagent_spawn and workflow agent_type inherit the parent model unless the user assigns an available model to a role.",
+        "Prefer one ask_user call with up to three independent questions covering Capability discovery plus Workflow limits, Next-action suggestions, and UI/Footer/result display. Explain that Post-edit defaults off; keep it off unless the user opts in, then ask only for the command. Explain that built-in Agent roles used by subagent_spawn and workflow agent_type inherit the parent model unless the user assigns an available model to a role.",
       ];
 
   return [
-    "Guide me through configuring the installed my-pi-setup package interactively.",
+    "Guide me through configuring the installed OpenPI package interactively.",
     "",
     "Current configuration:",
     options.currentConfiguration,
@@ -112,6 +129,7 @@ export function buildInteractiveSetupPrompt(options: {
     ...configurationState,
     "",
     "Before asking, briefly explain what can be configured and the practical impact:",
+    "- Capability discovery: explicit is the safe default and keeps OpenPI model tools absent until the user asks for a capability. adaptive is opt-in and keeps only the small openpi_load_tools gateway visible, allowing the model to load Subagents, Workflows, background terminals, structured search, or Session tracking when it judges them useful. Loaded groups remain session-stable, and normal permission, concurrency, and workflow limits still apply.",
     "- Next-action suggestions: disabled, or model-generated after a fully settled main-agent run. A suggestion appears as dim inline text on the first row of an empty editor; reserved cells at the row end keep CJK IME preedit from overwriting it. Right accepts it without submitting, and any other editor input dismisses it. Enabling requires an available provider/model and reasoning level and adds one small model call per settled run.",
     "- Workflow fan-out: concurrency controls simultaneous agents and resource pressure; max agent calls controls the total capacity of one workflow. Valid ranges are 1-64 and 1-1024.",
     "- UI: the large header costs vertical space; the custom footer is a declarative dashboard. Presets: powerline (default one-line ANSI256 blocks), powerline-mono (one-line high-contrast gray powerline), and compact (one-line plain text). Style can also be set independently: plain, powerline, powerline-mono. Custom lines are a 2D layout of cwd/model/thinking/context/cache/cost/throughput/git/pr plus at most one flex per line for left/right alignment. Nerd Font only affects powerline separator glyphs; text stays readable without it. Changes apply immediately in the active TUI session.",
@@ -119,8 +137,11 @@ export function buildInteractiveSetupPrompt(options: {
     "- Post-edit command: one optional shell command (maximum 500 characters) run in the background after a turn with successful Write/Edit operations (e.g. `npm run format`). Off by default, interactive TUI sessions only, failures surface as a notification. This is a single command, not an event-hook system.",
     "- Result detail display: Subagent results, Bash operations, and Write/Edit operations can each default to full (always expanded) or compact (Claude Code-style folded preview with a hidden-line count). Compact output can still be temporarily expanded with the configured app.tools.expand key (Ctrl+O by default). Bash and Write/Edit default to compact. Recommend compact for users who do not usually inspect implementation details.",
     "- Agent role models: built-in explorer, implementer, reviewer, and advisor roles are shared by subagent_spawn and workflow agent_type, and inherit the parent model by default. Assign only an available registry model to an individual role when needed; clearing that role returns it to inheritance. Custom agent-type files still override a built-in role's complete definition.",
+    "- Intercom: optional cross-session messaging is installed only after a native setup confirmation. It stays parent-only; Direct/Workflow children and Replay cannot use it. The status above is informational for this model-guided step—do not install packages or edit its config yourself.",
     "",
     "Natural-language configuration examples the user might ask for:",
+    '- "let the model discover OpenPI capabilities when useful" → capability_discovery=adaptive',
+    '- "only use OpenPI capabilities when I ask" → capability_discovery=explicit',
     '- "switch footer to powerline" → ui_footer_preset=powerline',
     '- "use mono powerline" → ui_footer_preset=powerline-mono',
     '- "compact footer" → ui_footer_preset=compact',
@@ -134,13 +155,168 @@ export function buildInteractiveSetupPrompt(options: {
   ];
 }
 
-export default function myPiSetup(pi: ExtensionAPI) {
+const safeSetupNotice = (value: unknown, maximum = 500) =>
+  sanitizeTerminalText(value instanceof Error ? value.message : String(value))
+    .replace(/\s+/gu, " ")
+    .trim()
+    .slice(0, maximum);
+
+export function buildSetupSuccessText(
+  currentConfiguration: string,
+  normalizationNote = "",
+) {
+  return [
+    `Updated OpenPI setup. ${currentConfiguration}${normalizationNote}`,
+    "This setup episode is complete; configure_my_pi_setup is now hidden. Do not call it again. Do not edit configuration files directly. If the user requests another configuration change, tell them to run /openpi-setup <request> to start a new setup episode.",
+  ].join(" ");
+}
+
+export function shouldOfferPiIntercom(options: {
+  readonly request: string;
+  readonly status: PiIntercomStatus;
+  readonly mode: ExtensionCommandContext["mode"];
+  readonly idle: boolean;
+}) {
+  return (
+    !options.request &&
+    !options.status.active &&
+    !options.status.installed &&
+    !options.status.diagnostic &&
+    options.mode === "tui" &&
+    options.idle
+  );
+}
+
+async function maybeOfferPiIntercom(
+  ctx: ExtensionCommandContext,
+  status: PiIntercomStatus,
+  request: string,
+) {
+  if (
+    !shouldOfferPiIntercom({
+      request,
+      status,
+      mode: ctx.mode,
+      idle: ctx.isIdle(),
+    })
+  ) {
+    return status;
+  }
+
+  const accepted = await ctx.ui.confirm(
+    status.configured
+      ? "Repair optional pi-intercom integration?"
+      : "Install optional pi-intercom integration?",
+    [
+      "pi-intercom enables cross-session messaging through a local IPC broker.",
+      "Like every Pi package, it runs with full system access.",
+      "OpenPI will install npm:pi-intercom globally. A new private config gets safe defaults; an existing preference file is never rewritten and must already define both fields:",
+      "• confirmSend: true",
+      '• inboundTrigger: "replies"',
+      "It remains parent-only and activates after /reload.",
+    ].join("\n"),
+  );
+  if (!accepted) return status;
+
+  ctx.ui.setWorkingMessage("Installing optional pi-intercom integration...");
+  try {
+    await installPiIntercom({
+      cwd: ctx.cwd,
+      onProgress: (event) =>
+        ctx.ui.setWorkingMessage(
+          safeSetupNotice(
+            event.message ?? "Installing optional pi-intercom integration...",
+            200,
+          ),
+        ),
+    });
+    const installed = inspectPiIntercom({
+      cwd: ctx.cwd,
+      active: false,
+    });
+    const next = { ...installed, reloadRequired: true };
+    ctx.ui.notify(
+      "pi-intercom installed with existing preferences preserved or a new safe config created. Run /reload after setup to activate it.",
+      "info",
+    );
+    return next;
+  } catch (error) {
+    ctx.ui.notify(
+      `pi-intercom was not enabled: ${safeSetupNotice(error)}`,
+      "error",
+    );
+    return inspectPiIntercom({ cwd: ctx.cwd, active: false });
+  } finally {
+    ctx.ui.setWorkingMessage();
+  }
+}
+
+export const CONFIGURE_MY_PI_SETUP_TOOL_NAME = "configure_my_pi_setup";
+
+type SetupEpisode = "idle" | "armed" | "active";
+
+function showConfigureTool(pi: ExtensionAPI) {
+  patchOwnedTools(pi, "setup", {
+    enable: [CONFIGURE_MY_PI_SETUP_TOOL_NAME],
+  });
+}
+
+function hideConfigureTool(pi: ExtensionAPI) {
+  patchOwnedTools(pi, "setup", {
+    disable: [CONFIGURE_MY_PI_SETUP_TOOL_NAME],
+  });
+}
+
+export default function openPiSetup(pi: ExtensionAPI) {
+  let episode: SetupEpisode = "idle";
+  const publishEpisode = () =>
+    pi.events.emit(OPENPI_SETUP_EPISODE_CHANNEL, {
+      active: episode !== "idle",
+    } satisfies OpenPiSetupEpisodeState);
+
+  const endEpisode = () => {
+    episode = "idle";
+    hideConfigureTool(pi);
+    publishEpisode();
+  };
+
+  pi.on("session_start", () => {
+    endEpisode();
+  });
+
+  pi.on("agent_start", () => {
+    if (episode === "armed") {
+      episode = "active";
+      publishEpisode();
+    }
+  });
+
+  pi.on("tool_execution_end", (event) => {
+    if (
+      episode === "active" &&
+      event.toolName === CONFIGURE_MY_PI_SETUP_TOOL_NAME &&
+      !event.isError
+    ) {
+      endEpisode();
+    }
+  });
+
+  pi.on("agent_settled", () => {
+    if (episode === "active") endEpisode();
+  });
+
   pi.registerTool({
     name: "configure_my_pi_setup",
-    label: "Configure My Pi Setup",
+    label: "Configure OpenPI",
     description:
-      "Apply a user-requested configuration change for this Pi setup. Configures next-action suggestions, workflow fan-out, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to an active TUI footer.",
+      "Apply a user-requested configuration change for this Pi setup. Configures capability discovery (explicit or opt-in adaptive), next-action suggestions, workflow fan-out, UI/Footer (presets, style, multi-line layout), result detail display, optional Post-edit, and built-in Agent-role model assignments shared by subagent_spawn and workflow agent_type. Role models must be available in the Pi registry; null clears a role back to parent-model inheritance. Footer examples: powerline preset, powerline-mono, compact, or custom ui_footer_lines with flex. Preserve current values for settings the user did not ask to change. Changes apply immediately to the capability gateway and active TUI footer.",
     parameters: Type.Object({
+      capability_discovery: Type.Optional(
+        StringEnum(CAPABILITY_DISCOVERY_MODES, {
+          description:
+            "Capability adoption policy. explicit keeps OpenPI tools absent until the user asks for a capability; adaptive keeps only the small openpi_load_tools gateway visible so the model may load a useful group on its own. Adaptive can start expensive work such as Subagents or Workflows, so it is opt-in. Omit to preserve the current value.",
+        }),
+      ),
       suggestions_enabled: Type.Optional(
         Type.Boolean({
           description:
@@ -309,6 +485,12 @@ export default function myPiSetup(pi: ExtensionAPI) {
         );
 
         const config: MyPiSetupConfig = {
+          capabilities: {
+            discovery:
+              (params.capability_discovery as
+                | CapabilityDiscoveryMode
+                | undefined) ?? current.capabilities.discovery,
+          },
           suggestions: {
             enabled: suggestionsEnabled,
             ...(model ? { model } : {}),
@@ -360,49 +542,63 @@ export default function myPiSetup(pi: ExtensionAPI) {
           : "";
       if (ctx.hasUI) ctx.ui.notify(`${text}${note}`, "info");
       return {
-        content: [
-          { type: "text", text: `Updated my Pi setup. ${text}${note}` },
-        ],
+        content: [{ type: "text", text: buildSetupSuccessText(text, note) }],
         details: config,
       };
     },
   });
 
+  const setupHandler = async (args: string, ctx: ExtensionCommandContext) => {
+    const request = args.trim();
+    let intercomStatus = inspectPiIntercom({
+      cwd: ctx.cwd,
+      active: pi.getAllTools().some(({ name }) => name === "intercom"),
+    });
+    intercomStatus = await maybeOfferPiIntercom(ctx, intercomStatus, request);
+
+    const currentConfiguration = formatSetupConfig(loadSetupConfig(), [
+      formatPiIntercomStatus(intercomStatus),
+    ]);
+    const savedConfigExists = hasSavedSetupConfig();
+    const currentModel = ctx.model
+      ? `${ctx.model.provider}/${ctx.model.id}`
+      : "unavailable";
+    const currentThinking = pi.getThinkingLevel();
+
+    const prompt = request
+      ? [
+          "Configure the installed OpenPI package according to this request:",
+          request,
+          "",
+          "Current configuration:",
+          currentConfiguration,
+          "",
+          "Capability discovery is explicit by default; adaptive is an opt-in that keeps only openpi_load_tools visible so the model may load useful groups. Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. Nerd Font only affects powerline separator glyphs. Changes apply immediately in the active TUI session. Intercom installation is handled only by the native setup confirmation; do not install packages or edit its config yourself.",
+          "",
+          "Use configure_my_pi_setup to apply only the requested OpenPI-owned changes and preserve everything else. Interpret model names from the available Pi registry. Do not edit configuration files directly.",
+        ]
+      : buildInteractiveSetupPrompt({
+          currentConfiguration,
+          currentModel,
+          currentThinking,
+          savedConfigExists,
+        });
+
+    episode = "armed";
+    showConfigureTool(pi);
+    publishEpisode();
+    pi.sendUserMessage(
+      prompt.join("\n"),
+      ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+    );
+  };
+
+  pi.registerCommand("openpi-setup", {
+    description: "View or change OpenPI configuration in natural language",
+    handler: setupHandler,
+  });
   pi.registerCommand("my-pi-setup", {
-    description:
-      "View or change this package's configuration in natural language",
-    handler: async (args, ctx) => {
-      const request = args.trim();
-      const currentConfiguration = formatSetupConfig(loadSetupConfig());
-      const savedConfigExists = hasSavedSetupConfig();
-      const currentModel = ctx.model
-        ? `${ctx.model.provider}/${ctx.model.id}`
-        : "unavailable";
-      const currentThinking = pi.getThinkingLevel();
-
-      const prompt = request
-        ? [
-            "Configure the installed my-pi-setup package according to this request:",
-            request,
-            "",
-            "Current configuration:",
-            currentConfiguration,
-            "",
-            "Footer tips: presets are powerline, powerline-mono, compact; style is plain/powerline/powerline-mono; custom layouts use ui_footer_lines (2D enum arrays with optional flex). Do not use ui_footer_items together with ui_footer_lines. Built-in Agent role models (explorer, implementer, reviewer, advisor) are shared by subagent_spawn and workflow agent_type; they inherit the parent unless assigned an available registry model, and clearing an assignment restores inheritance. Custom agent-type files still override built-in role definitions. Nerd Font only affects powerline separator glyphs. Changes apply immediately in the active TUI session.",
-            "",
-            "Use configure_my_pi_setup to apply only the requested changes and preserve everything else. Interpret model names from the available Pi registry. Do not edit configuration files directly.",
-          ]
-        : buildInteractiveSetupPrompt({
-            currentConfiguration,
-            currentModel,
-            currentThinking,
-            savedConfigExists,
-          });
-
-      pi.sendUserMessage(
-        prompt.join("\n"),
-        ctx.isIdle() ? undefined : { deliverAs: "followUp" },
-      );
-    },
+    description: "Legacy alias — use /openpi-setup",
+    handler: setupHandler,
   });
 }

package/extensions/setup/intercom-fs-helper.cjs

@@ -0,0 +1,130 @@
+const { randomUUID } = require("node:crypto");
+const {
+  constants,
+  closeSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} = require("node:fs");
+
+const [operation, expectedDev, expectedIno, name, encoded] =
+  process.argv.slice(2);
+const allowedNames = new Set([
+  "config.json",
+  "config.json.openpi-install.lock",
+]);
+const fail = (code, message) => {
+  process.stderr.write(`OPENPI:${code}:${message}\n`);
+  process.exit(1);
+};
+const identityMatches = () => {
+  const current = statSync(".", { bigint: true });
+  return (
+    current.isDirectory() &&
+    String(current.dev) === expectedDev &&
+    String(current.ino) === expectedIno
+  );
+};
+
+if (!allowedNames.has(name)) fail("INPUT", "unsupported file name");
+if (!identityMatches()) fail("IDENTITY", "directory identity mismatch");
+
+const payload = Buffer.from(encoded ?? "", "base64");
+if (payload.length > 8_192) fail("INPUT", "payload too large");
+
+if (operation === "create") {
+  let fd;
+  try {
+    fd = openSync(
+      name,
+      constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+  } catch (error) {
+    if (error && error.code === "EEXIST") fail("EEXIST", "file exists");
+    fail("IO", error instanceof Error ? error.message : String(error));
+  }
+  try {
+    const metadata = fstatSync(fd);
+    if (!metadata.isFile()) fail("TYPE", "created path is not a regular file");
+    writeFileSync(fd, payload);
+  } finally {
+    closeSync(fd);
+  }
+  if (!identityMatches()) fail("IDENTITY", "directory identity changed");
+  process.exit(0);
+}
+
+if (operation === "remove-owned") {
+  // Atomically move the current lock to a unique claim before inspecting it.
+  // A replacement lock can then appear at `name`, but cleanup never unlinks
+  // that pathname: it removes only inode-pinned, randomly named claims.
+  const claim = `.${name}.release.${process.pid}.${randomUUID()}`;
+  const markerClaim = `${claim}.marker`;
+  const releaseToken = Buffer.from(`release:${process.pid}:${randomUUID()}\n`);
+  try {
+    renameSync(name, claim);
+  } catch (error) {
+    fail("IO", error instanceof Error ? error.message : String(error));
+  }
+
+  let markerCreated = false;
+  let markerFd;
+  try {
+    markerFd = openSync(
+      name,
+      constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        (constants.O_NOFOLLOW ?? 0),
+      0o600,
+    );
+    writeFileSync(markerFd, releaseToken);
+    markerCreated = true;
+  } catch (error) {
+    if (!error || error.code !== "EEXIST") {
+      fail("IO", error instanceof Error ? error.message : String(error));
+    }
+  } finally {
+    if (markerFd !== undefined) closeSync(markerFd);
+  }
+
+  let claimFd;
+  try {
+    claimFd = openSync(claim, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    if (!fstatSync(claimFd).isFile())
+      fail("TYPE", "claim is not a regular file");
+    if (!readFileSync(claimFd).equals(payload))
+      fail("OWNER", "owner token mismatch");
+  } finally {
+    if (claimFd !== undefined) closeSync(claimFd);
+  }
+  unlinkSync(claim);
+
+  if (markerCreated) {
+    renameSync(name, markerClaim);
+    let releaseFd;
+    try {
+      releaseFd = openSync(
+        markerClaim,
+        constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+      );
+      if (!readFileSync(releaseFd).equals(releaseToken))
+        fail("OWNER", "release marker ownership mismatch");
+    } finally {
+      if (releaseFd !== undefined) closeSync(releaseFd);
+    }
+    unlinkSync(markerClaim);
+  }
+  if (!identityMatches()) fail("IDENTITY", "directory identity changed");
+  process.exit(0);
+}
+
+fail("INPUT", "unsupported operation");