pi-runline 0.4.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 Code mode for [pi](https://github.com/mariozechner/pi).
 
-An extension that plugs [runline](https://www.npmjs.com/package/runline) into coding agents. The agent gets two native tools, a fuzzy picker for choosing which of the 188 built-in plugins to expose, and a guided credential prompt for the ones it hasn't seen before.
+An extension that plugs [runline](https://www.npmjs.com/package/runline) into coding agents. The agent gets one native tool, in-sandbox action discovery, a fuzzy picker for choosing which of the 188 built-in plugins to expose, and a guided credential prompt for the ones it hasn't seen before.
 
 ## Install
 
@@ -10,13 +10,32 @@ An extension that plugs [runline](https://www.npmjs.com/package/runline) into co
 pi install pi-runline
 ```
 
-## Tools
+## How the agent uses it
 
-On session start, if the current working directory has a `.runline/` (or one is configured globally — see below), the extension registers two tools and injects the selected plugin catalog into the agent's context:
+On session start, if the current working directory has a `.runline/` (or one is configured globally — see below), the extension registers a single tool and injects a short primer naming the enabled plugins:
 
-- **`list_runline_actions`** — enumerate available actions with input schemas. Optional `plugin` filter.
 - **`execute_runline`** — run JavaScript in runline's QuickJS sandbox. Every enabled plugin is a top-level global; `return` surfaces the result; logs are captured.
 
+Discovery happens **inside the sandbox**, not as a separate tool. The agent uses an `actions` object to explore the catalog without paying for a full schema dump in its system prompt:
+
+```js
+actions.list()                  // every "plugin.action" path
+actions.list("github")          // filter to one plugin
+actions.find("create issue")    // ranked fuzzy search (MiniSearch)
+actions.describe("github.issue.create")
+// → { path, plugin, action, description, signature, inputs }
+actions.check("github.issue.create", { owner: "a" })
+// → { ok, missing, unknown, typeErrors, signature }   (does NOT call the action)
+```
+
+Unknown paths throw with did-you-mean suggestions, so typos are self-correcting. Recommended flow: `find` → `describe` → `check` → call.
+
+Calling actions is unchanged — plugin globals and `actions.<plugin>.<action>(...)` are the same call:
+
+```js
+return await github.issue.create({ owner: "acme", repo: "api", title: "Bug" });
+```
+
 ## `/runline-plugins` — the picker
 
 Typing `/runline-plugins` in a pi session opens a fuzzy multi-select over all 188 built-in plugins.
@@ -66,6 +85,6 @@ Fallback used when the current cwd has no `.runline/` anywhere up the tree. Usef
 
 ## How plugin allow-listing works
 
-The extension deliberately exposes nothing by default. That's on purpose — 2,410 actions is a lot of context budget. You pick the plugins that matter for a given project, commit the allowlist to `.runline/config.json`, and the agent only ever sees (and can only discover via `list_runline_actions`) the ones you enabled.
+The extension deliberately exposes nothing by default. That's on purpose — 2,410 actions is a lot of context budget. You pick the plugins that matter for a given project, commit the allowlist to `.runline/config.json`, and the agent only ever sees the ones you enabled in its primer.
 
-Note that the QuickJS sandbox itself still registers every runline plugin as a global, so in principle an agent could guess and call a disabled plugin. In practice the catalog injection and `list_runline_actions` output are the only surface the agent knows about, and unconfigured plugins error out at first action call anyway. Plumbing the allowlist into the sandbox globals is on the roadmap.
+Note that the QuickJS sandbox itself still registers every runline plugin as a global (and `actions.list()` will surface them all), so in principle an agent could guess and call a disabled plugin. In practice the primer only advertises the allowlisted ones, and unconfigured plugins error out at first action call anyway. Plumbing the allowlist into the sandbox registry is on the roadmap.

package/extensions/runline-context/index.ts

@@ -10,16 +10,6 @@ import {
   savePiPlugins,
 } from "../runline-resolve.js";
 
-type ActionEntry = {
-  plugin: string;
-  action: string;
-  description?: string;
-  inputSchema?: Record<
-    string,
-    { type: string; required?: boolean; description?: string }
-  >;
-};
-
 function filterByAllowlist<T extends { name?: string; plugin?: string }>(
   items: T[],
   allow: string[] | undefined,
@@ -29,34 +19,6 @@ function filterByAllowlist<T extends { name?: string; plugin?: string }>(
   return items.filter((i) => set.has((i.name ?? i.plugin) as string));
 }
 
-function formatActions(actions: ActionEntry[]): string {
-  const grouped = new Map<string, ActionEntry[]>();
-  for (const a of actions) {
-    const list = grouped.get(a.plugin) ?? [];
-    list.push(a);
-    grouped.set(a.plugin, list);
-  }
-
-  const lines: string[] = [];
-  for (const [plugin, entries] of grouped) {
-    lines.push(`### ${plugin}`);
-    for (const a of entries) {
-      const inputs = a.inputSchema
-        ? Object.entries(a.inputSchema)
-            .map(([k, v]) => `${k}: ${v.type}${v.required ? "" : "?"}`)
-            .join(", ")
-        : "";
-      const sig = inputs
-        ? `\`${plugin}.${a.action}({ ${inputs} })\``
-        : `\`${plugin}.${a.action}()\``;
-      const desc = a.description ? ` — ${a.description}` : "";
-      lines.push(`- ${sig}${desc}`);
-    }
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-
 const runlineCache = new Map<string, Promise<Runline>>();
 
 async function getRunline(cwd: string): Promise<Runline> {
@@ -157,21 +119,39 @@ export default function (pi: ExtensionAPI) {
       );
 
     if (!alreadyInjected) {
-      const header =
-        "## Runline actions\n\n" +
-        "This project has runline installed. You have two tools:\n" +
-        "- `list_runline_actions` — show the full action catalog with input schemas\n" +
-        "- `execute_runline` — run JavaScript in a sandbox where each plugin is a top-level global. " +
+      const pluginList = plugins
+        .map((p) => `\`${p.name}\` (${p.actions.length})`)
+        .join(", ");
+
+      const content =
+        "## Runline\n\n" +
+        `This project has runline installed with **${plugins.length} plugins, ${actions.length} actions**. ` +
+        "Use the `execute_runline` tool to run JavaScript in a sandbox where each plugin is a top-level global. " +
         "Chain actions, await results, return a value.\n\n" +
-        `**${plugins.length} plugins, ${actions.length} actions available.**\n\n` +
-        "Example:\n" +
+        `**Enabled plugins:** ${pluginList}\n\n` +
+        "### Discovering actions\n\n" +
+        "Inside the sandbox, an `actions` object lets you explore the catalog without leaving `execute_runline`. " +
+        "Prefer this over guessing — it's how you find the right action and verify call shapes before invoking.\n\n" +
+        "```js\n" +
+        'actions.list()                  // every "plugin.action" path\n' +
+        'actions.list("github")          // just one plugin\n' +
+        'actions.find("create issue")    // ranked fuzzy search — [{path, description, score}]\n' +
+        'actions.describe("github.issue.create")\n' +
+        "// → { path, plugin, action, description, signature, inputs }\n" +
+        'actions.check("github.issue.create", { owner: "a" })\n' +
+        "// → { ok, missing, unknown, typeErrors, signature }   (does NOT call the action)\n" +
+        "```\n\n" +
+        "Unknown paths throw with did-you-mean suggestions, so typos are self-correcting. " +
+        "Recommended flow: `find` → `describe` → `check` → call.\n\n" +
+        "### Calling actions\n\n" +
         "```js\n" +
         'return await github.issue.create({ owner: "acme", repo: "api", title: "Bug" })\n' +
-        "```\n\n";
+        "```\n\n" +
+        "Plugin globals (`github`, `slack`, ...) and `actions.<plugin>.<action>(...)` both work — same call.\n";
 
       pi.sendMessage({
         customType: "runline-context",
-        content: header + formatActions(actions),
+        content,
         display: true,
       });
     }
@@ -205,9 +185,10 @@ export default function (pi: ExtensionAPI) {
       const rl = await getRunline(ctx.cwd);
       // Note: the sandbox currently exposes every registered plugin as a
       // global. The allowlist drives what the agent is told about in its
-      // injected context and list_runline_actions output, which is the only
-      // practical route for the agent to know what exists. Plumbing the
-      // allowlist through to the sandbox globals is a future improvement.
+      // injected context (and what `actions.list()` surfaces in practice,
+      // since the agent only knows to look for what was advertised).
+      // Plumbing the allowlist through to the sandbox registry is a
+      // future improvement.
       const result = await rl.execute(params.code);
 
       const logs = result.logs?.length
@@ -234,38 +215,6 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  pi.registerTool({
-    name: "list_runline_actions",
-    label: "Runline Actions",
-    description:
-      "List every available runline action with its plugin, description, and input schema.",
-    promptSnippet:
-      "Discover runline plugin actions and their input shapes before calling execute_runline",
-    parameters: Type.Object({
-      plugin: Type.Optional(
-        Type.String({
-          description: "Filter to a single plugin (e.g. 'github')",
-        }),
-      ),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const rl = await getRunline(ctx.cwd);
-      const runlineDir = findRunlineDir(ctx.cwd);
-      const allow = runlineDir
-        ? loadExtConfig(runlineDir).piPlugins
-        : undefined;
-      let actions = filterByAllowlist(rl.actions(), allow);
-      if (params.plugin) {
-        actions = actions.filter((a) => a.plugin === params.plugin);
-      }
-      const text = formatActions(actions);
-      return {
-        content: [{ type: "text", text: text || "No actions enabled." }],
-        details: { actions },
-      };
-    },
-  });
-
   // ── Commands ────────────────────────────────────────────────────
 
   pi.registerCommand("runline-plugins", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-runline",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Code mode for pi",
   "type": "commonjs",
   "keywords": [
@@ -22,7 +22,7 @@
     "lint:fix": "biome check --write extensions/"
   },
   "dependencies": {
-    "runline": "^0.4.0"
+    "runline": "^0.5.1"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",