pi-runline 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# pi-runline
+
+A [pi](https://github.com/mariozechner/pi) extension that gives coding agents first-class access to runline.
+
+## What it does
+
+On session start, if the current project has a `.runline/` directory (or one is configured globally via `~/.pi/agent/runline.json`), the extension:
+
+1. **Injects a context message** listing every installed plugin, its actions, and their input schemas.
+2. **Sets a status bar line** — `⚡ runline: N plugins, M actions`.
+3. **Registers two tools** the agent can call:
+   - `list_runline_actions` — enumerate the action catalog (optionally filtered to one plugin).
+   - `execute_runline` — run JavaScript against the runline sandbox. Plugins are globals; `return` surfaces the result.
+
+## Configuration
+
+### Per-project — `.runline/config.json`
+
+```json
+{ "showStatus": false }
+```
+
+Silences the status bar for this project.
+
+### Global — `~/.pi/agent/runline.json`
+
+```json
+{ "project": "~/Projects/my-runline-project" }
+```
+
+Fall-back used when the current working directory has no `.runline/` in its ancestry. Useful when you want the runline tools available in every pi session without putting `.runline/` everywhere.
+
+## Install
+
+Published as `pi-runline` on npm. The package declares itself via `pi.extensions` and `pi.skills` in `package.json`, so pi picks it up automatically once installed.

package/extensions/connection-setup.ts

@@ -0,0 +1,162 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+type ConnectionSchemaField = {
+  type: string;
+  required?: boolean;
+  description?: string;
+  default?: unknown;
+  env?: string;
+};
+
+type PluginSummary = {
+  name: string;
+  connectionConfigSchema?: Record<string, ConnectionSchemaField>;
+};
+
+type Connection = {
+  name: string;
+  plugin: string;
+  config: Record<string, unknown>;
+};
+
+function readConfig(runlineDir: string): Record<string, unknown> {
+  const configPath = path.join(runlineDir, "config.json");
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(
+  runlineDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = path.join(runlineDir, "config.json");
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function getConnections(config: Record<string, unknown>): Connection[] {
+  const raw = config.connections;
+  return Array.isArray(raw) ? (raw as Connection[]) : [];
+}
+
+function connectionFor(
+  connections: Connection[],
+  plugin: string,
+): Connection | undefined {
+  return connections.find((c) => c.plugin === plugin);
+}
+
+function isSchemaEmpty(schema: PluginSummary["connectionConfigSchema"]): boolean {
+  return !schema || Object.keys(schema).length === 0;
+}
+
+function envOrSchemaDefault(
+  field: ConnectionSchemaField,
+): string | undefined {
+  if (field.env && process.env[field.env]) return process.env[field.env];
+  if (field.default !== undefined) return String(field.default);
+  return undefined;
+}
+
+/**
+ * Walk through newly-enabled plugins and prompt for any credentials that
+ * don't already have a connection (and aren't already resolvable via env).
+ * Skips plugins with no connection schema.
+ *
+ * Returns the list of plugin names that ended up with a saved connection.
+ */
+export async function promptForCredentials(
+  ctx: ExtensionCommandContext,
+  runlineDir: string,
+  plugins: PluginSummary[],
+  newlyEnabled: string[],
+): Promise<string[]> {
+  const config = readConfig(runlineDir);
+  const connections = getConnections(config);
+  const saved: string[] = [];
+
+  for (const name of newlyEnabled) {
+    const plugin = plugins.find((p) => p.name === name);
+    if (!plugin) continue;
+
+    const schema = plugin.connectionConfigSchema;
+    if (isSchemaEmpty(schema)) continue; // no creds needed
+
+    if (connectionFor(connections, name)) continue; // already configured
+
+    // Check env — if every required field has an env var set, skip the prompt.
+    const requiredFields = Object.entries(schema!).filter(
+      ([, f]) => f.required,
+    );
+    const allFromEnv = requiredFields.every(
+      ([, f]) => f.env && process.env[f.env],
+    );
+    if (requiredFields.length > 0 && allFromEnv) continue;
+
+    const wantSetup = await ctx.ui.confirm(
+      `Set up ${name}?`,
+      `${name} needs credentials. Configure now?`,
+    );
+    if (!wantSetup) continue;
+
+    const values: Record<string, unknown> = {};
+    let cancelled = false;
+    for (const [key, field] of Object.entries(schema!)) {
+      const placeholder = field.env
+        ? `${field.description ?? key} (env: ${field.env})`
+        : (field.description ?? key);
+      const existing = envOrSchemaDefault(field);
+      const prompt = existing
+        ? `${key} [${existing.slice(0, 8)}…]`
+        : `${key}${field.required ? " *" : ""}`;
+
+      const answer = await ctx.ui.input(prompt, placeholder);
+      if (answer === undefined) {
+        cancelled = true;
+        break;
+      }
+      const trimmed = answer.trim();
+      if (trimmed) {
+        values[key] = coerce(trimmed, field.type);
+      } else if (field.required && !existing) {
+        ctx.ui.notify(`${key} is required — skipping ${name}`, "warning");
+        cancelled = true;
+        break;
+      }
+    }
+
+    if (cancelled) continue;
+
+    const conn: Connection = {
+      name,
+      plugin: name,
+      config: values,
+    };
+    connections.push(conn);
+    saved.push(name);
+  }
+
+  if (saved.length > 0) {
+    config.connections = connections;
+    writeConfig(runlineDir, config);
+  }
+
+  return saved;
+}
+
+function coerce(value: string, type: string): unknown {
+  if (type === "number") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : value;
+  }
+  if (type === "boolean") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  }
+  return value;
+}

package/extensions/plugin-picker.ts

@@ -0,0 +1,227 @@
+import type { Component, TUI } from "@mariozechner/pi-tui";
+import { fuzzyFilter, Input, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+
+export interface PluginPickerItem {
+  name: string;
+  actionCount: number;
+}
+
+export interface PluginPickerResult {
+  /** undefined = cancelled */
+  selected?: string[];
+}
+
+/**
+ * Multi-select fuzzy picker for runline plugin names.
+ *
+ * Keys:
+ *   ↑ / ↓       — move highlight
+ *   space       — toggle current item
+ *   Ctrl-A      — toggle all (filtered view)
+ *   enter       — save and close
+ *   esc / C-c   — cancel
+ *   type        — fuzzy filter
+ */
+export class PluginPicker implements Component {
+  private readonly items: PluginPickerItem[];
+  private readonly selected: Set<string>;
+  private readonly input: Input;
+  private readonly theme: Theme;
+  private readonly onDone: (result: PluginPickerResult) => void;
+  private filtered: PluginPickerItem[];
+  private cursor = 0;
+  private readonly maxRows = 18;
+
+  constructor(
+    items: PluginPickerItem[],
+    initiallySelected: Iterable<string>,
+    theme: Theme,
+    onDone: (result: PluginPickerResult) => void,
+  ) {
+    this.items = [...items].sort((a, b) => a.name.localeCompare(b.name));
+    this.selected = new Set(initiallySelected);
+    this.filtered = this.items;
+    this.theme = theme;
+    this.onDone = onDone;
+
+    this.input = new Input();
+    this.input.focused = true;
+    this.input.onSubmit = () => this.confirm();
+    this.input.onEscape = () => this.cancel();
+  }
+
+  invalidate(): void {
+    this.input.invalidate();
+  }
+
+  render(width: number): string[] {
+    const theme = this.theme;
+    // Reserve two columns for the border and one space of padding on each side.
+    const inner = Math.max(10, width - 4);
+    const body: string[] = [];
+
+    body.push(
+      theme.fg(
+        "mdHeading",
+        `runline plugins · ${this.selected.size}/${this.items.length} enabled`,
+      ),
+    );
+    body.push(
+      theme.fg(
+        "dim",
+        "type to filter · space toggle · ^A toggle all · enter save · esc cancel",
+      ),
+    );
+    body.push("");
+
+    // Search input
+    const searchPrefix = theme.fg("dim", "filter ❯ ");
+    const inputLines = this.input.render(Math.max(10, inner - 10));
+    body.push(searchPrefix + (inputLines[0] ?? ""));
+    body.push("");
+
+    // List — always render exactly maxRows item rows plus one status row so the
+    // overlay's height is stable while the filter narrows results.
+    const total = this.filtered.length;
+    const start =
+      total <= this.maxRows
+        ? 0
+        : Math.max(
+            0,
+            Math.min(
+              this.cursor - Math.floor(this.maxRows / 2),
+              total - this.maxRows,
+            ),
+          );
+    const end = Math.min(start + this.maxRows, total);
+
+    for (let i = start; i < end; i++) {
+      const item = this.filtered[i];
+      if (!item) continue;
+      const isSel = this.selected.has(item.name);
+      const isCur = i === this.cursor;
+      const box = isSel ? "◉" : "◯";
+      const boxColored = isSel
+        ? theme.fg("success", box)
+        : theme.fg("dim", box);
+      const name = isCur ? theme.bold(item.name) : item.name;
+      const count = theme.fg("dim", `  ${item.actionCount} actions`);
+      const arrow = isCur ? theme.fg("accent", "❯ ") : "  ";
+      body.push(`${arrow}${boxColored} ${name}${count}`);
+    }
+    for (let i = end - start; i < this.maxRows; i++) body.push("");
+
+    body.push(
+      total === 0
+        ? theme.fg("dim", "  no matches")
+        : theme.fg("dim", `  ${this.cursor + 1}/${total}`),
+    );
+
+    return this.drawBorder(body, width);
+  }
+
+  /**
+   * Wrap body lines in a Unicode box border with 1-column horizontal padding.
+   * The width of every line is normalized to inner+2 so the right border aligns.
+   */
+  private drawBorder(body: string[], width: number): string[] {
+    const theme = this.theme;
+    const inner = Math.max(10, width - 4);
+    const top = theme.fg("dim", `╭${"─".repeat(inner + 2)}╮`);
+    const bot = theme.fg("dim", `╰${"─".repeat(inner + 2)}╯`);
+    const side = theme.fg("dim", "│");
+    const out: string[] = [top];
+    for (const raw of body) {
+      const visible = visibleWidth(raw);
+      const pad = Math.max(0, inner - visible);
+      out.push(`${side} ${raw}${" ".repeat(pad)} ${side}`);
+    }
+    out.push(bot);
+    return out;
+  }
+
+  handleInput(data: string): void {
+    // Navigation + toggle keys — check before routing to the text input,
+    // otherwise arrow keys and space would just type characters.
+    if (data === "\x1b[A" || data === "\x1b[Z") {
+      // up / shift-tab
+      if (this.filtered.length > 0) {
+        this.cursor =
+          this.cursor === 0 ? this.filtered.length - 1 : this.cursor - 1;
+      }
+      return;
+    }
+    if (data === "\x1b[B" || data === "\t") {
+      // down / tab
+      if (this.filtered.length > 0) {
+        this.cursor =
+          this.cursor === this.filtered.length - 1 ? 0 : this.cursor + 1;
+      }
+      return;
+    }
+    if (data === " ") {
+      const item = this.filtered[this.cursor];
+      if (item) {
+        if (this.selected.has(item.name)) this.selected.delete(item.name);
+        else this.selected.add(item.name);
+      }
+      return;
+    }
+    if (data === "\x01") {
+      // Ctrl-A — toggle all visible
+      const allSelected = this.filtered.every((i) => this.selected.has(i.name));
+      for (const i of this.filtered) {
+        if (allSelected) this.selected.delete(i.name);
+        else this.selected.add(i.name);
+      }
+      return;
+    }
+    if (data === "\r" || data === "\n") {
+      this.confirm();
+      return;
+    }
+    if (data === "\x1b" || data === "\x03") {
+      this.cancel();
+      return;
+    }
+
+    // Everything else → text input (typing filters)
+    const before = this.input.getValue();
+    this.input.handleInput(data);
+    const after = this.input.getValue();
+    if (before !== after) {
+      this.applyFilter(after);
+    }
+  }
+
+  private applyFilter(query: string): void {
+    this.filtered = query
+      ? fuzzyFilter(this.items, query, (i) => i.name)
+      : this.items;
+    this.cursor = 0;
+  }
+
+  private confirm(): void {
+    this.onDone({ selected: [...this.selected].sort() });
+  }
+
+  private cancel(): void {
+    this.onDone({});
+  }
+}
+
+/** Factory wrapper that matches the ctx.ui.custom signature. */
+export function createPluginPickerFactory(
+  items: PluginPickerItem[],
+  initiallySelected: Iterable<string>,
+) {
+  return (
+    _tui: TUI,
+    theme: Theme,
+    _keybindings: unknown,
+    done: (result: PluginPickerResult) => void,
+  ): Component => {
+    return new PluginPicker(items, initiallySelected, theme, done);
+  };
+}

package/extensions/runline-context/index.ts

@@ -0,0 +1,334 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Markdown, Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { Runline } from "runline";
+import { promptForCredentials } from "../connection-setup.js";
+import { createPluginPickerFactory } from "../plugin-picker.js";
+import {
+  findRunlineDir,
+  loadExtConfig,
+  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,
+): T[] {
+  if (!allow) return [];
+  const set = new Set(allow);
+  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> {
+  let pending = runlineCache.get(cwd);
+  if (!pending) {
+    pending = Runline.fromProject(cwd).then((rl) => {
+      if (!rl) throw new Error("No .runline/ found — run `runline init` first");
+      return rl;
+    });
+    // Drop failed loads so the next call retries instead of caching the error.
+    pending.catch(() => runlineCache.delete(cwd));
+    runlineCache.set(cwd, pending);
+  }
+  return pending;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerMessageRenderer(
+    "runline-context",
+    (message, { expanded }, theme) => {
+      if (!expanded) {
+        const label = theme.fg("customMessageLabel", "⚡ runline actions");
+        const hint = theme.fg("dim", " — Ctrl+O to expand");
+        return new Text(label + hint, 1, 0);
+      }
+      const content =
+        typeof message.content === "string"
+          ? message.content
+          : message.content
+              .filter((c): c is { type: "text"; text: string } => c.type === "text")
+              .map((c) => c.text)
+              .join("\n");
+      return new Markdown(
+        content,
+        1,
+        0,
+        {
+          heading: (t) => theme.fg("mdHeading", t),
+          link: (t) => theme.fg("mdLink", t),
+          linkUrl: (t) => theme.fg("mdLinkUrl", t),
+          code: (t) => theme.fg("mdCode", t),
+          codeBlock: (t) => theme.fg("mdCodeBlock", t),
+          codeBlockBorder: (t) => theme.fg("mdCodeBlockBorder", t),
+          quote: (t) => theme.fg("mdQuote", t),
+          quoteBorder: (t) => theme.fg("mdQuoteBorder", t),
+          hr: (t) => theme.fg("mdHr", t),
+          listBullet: (t) => theme.fg("mdListBullet", t),
+          bold: (t) => theme.bold(t),
+          italic: (t) => theme.italic(t),
+          strikethrough: (t) => theme.strikethrough(t),
+          underline: (t) => theme.underline(t),
+        },
+        { color: (t) => theme.fg("customMessageText", t) },
+      );
+    },
+  );
+
+  pi.on("session_start", async (_event, ctx) => {
+    const runlineDir = findRunlineDir(ctx.cwd);
+    if (!runlineDir) return;
+
+    const { showStatus } = loadExtConfig(runlineDir);
+
+    let rl: Runline;
+    try {
+      rl = await getRunline(ctx.cwd);
+    } catch {
+      if (ctx.hasUI && showStatus) {
+        ctx.ui.setStatus(
+          "runline",
+          ctx.ui.theme.fg("dim", "runline: load failed"),
+        );
+      }
+      return;
+    }
+
+    const { piPlugins } = loadExtConfig(runlineDir);
+    const actions = filterByAllowlist(rl.actions(), piPlugins);
+    const plugins = filterByAllowlist(rl.plugins(), piPlugins);
+
+    if (plugins.length === 0) {
+      if (ctx.hasUI && showStatus) {
+        const hint = piPlugins
+          ? "runline: no plugins enabled"
+          : "runline: /runline-plugins to enable";
+        ctx.ui.setStatus("runline", ctx.ui.theme.fg("dim", hint));
+      }
+      return;
+    }
+
+    const alreadyInjected = ctx.sessionManager
+      .getEntries()
+      .some(
+        (e) =>
+          e.type === "custom_message" && e.customType === "runline-context",
+      );
+
+    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. " +
+        "Chain actions, await results, return a value.\n\n" +
+        `**${plugins.length} plugins, ${actions.length} actions available.**\n\n` +
+        "Example:\n" +
+        "```js\n" +
+        'return await github.issue.create({ owner: "acme", repo: "api", title: "Bug" })\n' +
+        "```\n\n";
+
+      pi.sendMessage({
+        customType: "runline-context",
+        content: header + formatActions(actions),
+        display: true,
+      });
+    }
+
+    if (ctx.hasUI && showStatus) {
+      const theme = ctx.ui.theme;
+      ctx.ui.setStatus(
+        "runline",
+        `⚡${theme.fg("dim", ` runline: ${plugins.length} plugins, ${actions.length} actions`)}`,
+      );
+    }
+  });
+
+  // ── Tools ───────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "execute_runline",
+    label: "Runline Exec",
+    description:
+      "Execute JavaScript in the runline sandbox. Each installed plugin is a top-level global " +
+      "(e.g. `github`, `slack`). Use `return` to surface the result. Async/await supported.",
+    promptSnippet:
+      "Run JS against runline plugins — chain actions, transform data, return a value",
+    parameters: Type.Object({
+      code: Type.String({
+        description:
+          "JavaScript code to execute. Plugins are globals. Use `return` for the final value.",
+      }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      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.
+      const result = await rl.execute(params.code);
+
+      const logs = result.logs?.length
+        ? `\n\nLogs:\n${result.logs.join("\n")}`
+        : "";
+
+      if (result.error) {
+        return {
+          content: [{ type: "text", text: `Error: ${result.error}${logs}` }],
+          isError: true,
+          details: result,
+        };
+      }
+
+      const value =
+        typeof result.result === "string"
+          ? result.result
+          : JSON.stringify(result.result, null, 2);
+
+      return {
+        content: [{ type: "text", text: value + logs }],
+        details: result,
+      };
+    },
+  });
+
+  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", {
+    description: "Pick which runline plugins the agent can use",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+
+      const runlineDir = findRunlineDir(ctx.cwd);
+      if (!runlineDir) {
+        ctx.ui.notify("no .runline/ directory — run `runline init`", "error");
+        return;
+      }
+
+      let rl: Runline;
+      try {
+        rl = await getRunline(ctx.cwd);
+      } catch (err) {
+        ctx.ui.notify(
+          `runline failed to load: ${(err as Error).message}`,
+          "error",
+        );
+        return;
+      }
+
+      const items = rl.plugins().map((p) => ({
+        name: p.name,
+        actionCount: p.actions.length,
+      }));
+      const { piPlugins } = loadExtConfig(runlineDir);
+      const initial = piPlugins ?? [];
+
+      const result = await ctx.ui.custom(
+        createPluginPickerFactory(items, initial),
+        { overlay: true, overlayOptions: { width: "80%", maxHeight: "80%" } },
+      );
+
+      if (!result.selected) {
+        ctx.ui.notify("plugin selection cancelled", "info");
+        return;
+      }
+
+      savePiPlugins(runlineDir, result.selected);
+
+      const previous = new Set(initial);
+      const newlyEnabled = result.selected.filter((n) => !previous.has(n));
+
+      ctx.ui.notify(
+        `saved — ${result.selected.length} plugin(s) enabled`,
+        "info",
+      );
+
+      if (newlyEnabled.length > 0) {
+        const saved = await promptForCredentials(
+          ctx,
+          runlineDir,
+          rl.plugins(),
+          newlyEnabled,
+        );
+        if (saved.length > 0) {
+          ctx.ui.notify(
+            `credentials saved for ${saved.length} plugin(s)`,
+            "info",
+          );
+        }
+      }
+    },
+  });
+}

package/extensions/runline-resolve.ts

@@ -0,0 +1,78 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * Find the .runline/ config directory.
+ *
+ * Resolution order:
+ * 1. Walk up from cwd looking for a project-local `.runline/`
+ * 2. Fall back to the global project configured in ~/.pi/agent/runline.json
+ */
+export function findRunlineDir(cwd: string): string | null {
+  let dir = cwd;
+  while (dir !== path.dirname(dir)) {
+    const runlineDir = path.join(dir, ".runline");
+    if (fs.existsSync(runlineDir)) return runlineDir;
+    dir = path.dirname(dir);
+  }
+  return getGlobalRunlineDir();
+}
+
+function getGlobalRunlineDir(): string | null {
+  const homeDir = os.homedir();
+  const configPath = path.join(homeDir, ".pi", "agent", "runline.json");
+  if (!fs.existsSync(configPath)) return null;
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (!raw.project) return null;
+
+    const projectPath: string = raw.project.startsWith("~")
+      ? path.join(homeDir, raw.project.slice(1))
+      : path.resolve(raw.project);
+
+    const runlineDir = path.join(projectPath, ".runline");
+    if (fs.existsSync(runlineDir)) return runlineDir;
+  } catch {
+    // invalid config
+  }
+  return null;
+}
+
+export interface RunlineExtConfig {
+  showStatus: boolean;
+  /** Allowlist of plugin names exposed to the agent. undefined = none. */
+  piPlugins?: string[];
+}
+
+export function loadExtConfig(runlineDir: string): RunlineExtConfig {
+  const configPath = path.join(runlineDir, "config.json");
+  if (!fs.existsSync(configPath)) return { showStatus: true };
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return {
+      showStatus: raw.showStatus !== false,
+      piPlugins: Array.isArray(raw.piPlugins) ? raw.piPlugins : undefined,
+    };
+  } catch {
+    return { showStatus: true };
+  }
+}
+
+export function savePiPlugins(
+  runlineDir: string,
+  piPlugins: string[],
+): void {
+  const configPath = path.join(runlineDir, "config.json");
+  let raw: Record<string, unknown> = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch {
+      raw = {};
+    }
+  }
+  raw.piPlugins = [...piPlugins].sort();
+  fs.writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pi-runline",
+  "version": "0.1.0",
+  "description": "Code mode for pi",
+  "type": "commonjs",
+  "keywords": ["pi-package"],
+  "files": ["extensions", "README.md"],
+  "pi": {
+    "extensions": ["extensions/runline-context"]
+  },
+  "scripts": {
+    "build": "echo 'no build'",
+    "test": "echo 'no tests'",
+    "lint": "biome check extensions/",
+    "lint:fix": "biome check --write extensions/"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*",
+    "runline": ">=0.2.0"
+  },
+  "author": "michaelliv",
+  "license": "MIT"
+}