@oas-framework/pi 0.4.0

package/README.md

@@ -0,0 +1,23 @@
+# @oas-framework/pi
+
+The OAS pi adapter. Installs the agent tools (`spawn_agent`, `agents_status`,
+`retire_agent`, `create_agent`), the `/agents` command, and OAS skill
+discovery into [pi](https://github.com/earendil-works/pi).
+
+It is a thin adapter: the kernel, CLI, skills, injects, and bundled
+integrations all live in the globally installed
+[`@oas-framework/oas`](https://www.npmjs.com/package/@oas-framework/oas)
+package — the single source of truth shared by every runtime adapter.
+
+## Install
+
+```bash
+npm install -g @oas-framework/oas   # the kernel + oas CLI (required)
+pi install npm:@oas-framework/pi    # this adapter
+```
+
+The adapter locates the kernel via the `oas` binary on PATH (override with
+`OAS_PKG_ROOT`, e.g. to point at a dev clone).
+
+See the [oas-framework repo](https://github.com/josep-reyero/oas-framework)
+for the full documentation.

package/extension/core-loader.mjs

@@ -0,0 +1,66 @@
+/**
+ * core-loader.mjs — locate the globally installed @oas-framework/oas kernel and
+ * re-export its lib/core.mjs. The pi package is a thin adapter: it never ships
+ * the kernel, skills, injects, or integrations — those live in the global CLI
+ * package (npm i -g @oas-framework/oas), the single source of truth that the
+ * future Claude plugin shares.
+ *
+ * Resolution order:
+ *   1. $OAS_PKG_ROOT (explicit override, e.g. a dev clone)
+ *   2. the `oas` binary on PATH → realpath → its package root
+ *   3. `npm root -g`/@oas-framework/oas (binary not linked but package present)
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const PKG_NAME = "@oas-framework/oas";
+
+function isKernelRoot(dir) {
+  const pj = join(dir, "package.json");
+  if (!existsSync(pj) || !existsSync(join(dir, "lib", "core.mjs"))) return false;
+  try { return JSON.parse(readFileSync(pj, "utf8")).name === PKG_NAME; } catch { return false; }
+}
+
+function findKernelRoot() {
+  if (process.env.OAS_PKG_ROOT && isKernelRoot(process.env.OAS_PKG_ROOT)) return process.env.OAS_PKG_ROOT;
+  try {
+    const bin = execSync("command -v oas", { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    if (bin) {
+      let d = dirname(realpathSync(bin)); // <pkg>/bin/oas.mjs → <pkg>/bin
+      while (d !== dirname(d)) {
+        if (isKernelRoot(d)) return d;
+        d = dirname(d);
+      }
+    }
+  } catch { /* not on PATH */ }
+  try {
+    const g = execSync("npm root -g", { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    const cand = join(g, PKG_NAME);
+    if (isKernelRoot(cand)) return cand;
+  } catch { /* no npm */ }
+  return undefined;
+}
+
+export const OAS_PKG_ROOT = findKernelRoot();
+if (!OAS_PKG_ROOT) {
+  throw new Error(
+    "OAS kernel not found — the pi adapter needs the oas CLI installed globally.\n" +
+    "  Install it:  npm install -g @oas-framework/oas\n" +
+    "  (or point OAS_PKG_ROOT at a checkout of the oas-framework repo)",
+  );
+}
+
+const core = await import(pathToFileURL(join(OAS_PKG_ROOT, "lib", "core.mjs")).href);
+
+export const {
+  appendLogEntry, createAgent, defaultRepo, ensureRoot, findAgent, findRoot, listAgentDefs, listAgents,
+  listInstances, retireInstance, spawnInstance, upsertTmpAgent, workspaceOf, writeSoul, PACKAGED_SKILLS_DIR,
+  workspaceConfigSkillDirs, isOasWorkspace, resolveOasConfig, runLifecycleHooks,
+} = core;
+
+/** Kernel package version (for skew diagnostics against the adapter). */
+export function kernelVersion() {
+  try { return JSON.parse(readFileSync(join(OAS_PKG_ROOT, "package.json"), "utf8")).version; } catch { return "unknown"; }
+}

package/extension/index.ts

@@ -0,0 +1,437 @@
+/**
+ * oas (Open Agent Specialization) — launch specialized agents from the closest agents/ directory (a2am-style souls & instances).
+ *
+ * Global pi extension. From any directory:
+ *   - finds the closest `agents/` root walking up from cwd (or $PI_AGENTS_ROOT)
+ *   - spawns persistent agents (<root>/<name>/soul) or local agents (<root>/local-agents/<name>/soul; legacy tmp-agents/ read)
+ *   - imports single-file defs from .claude/agents/*.md and .agents/agents/*.md as tmp agents
+ *   - work mode per soul: `worktree` (own git worktree + branch) or `checkout` (symlink to repo)
+ *   - sessions run in tmux (session "pi-agents"), model selectable from pi's enabled models
+ *
+ * Tools: spawn_agent, agents_status, retire_agent.  Command: /agents.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+  appendLogEntry, createAgent, defaultRepo, ensureRoot, findAgent, findRoot, listAgentDefs, listAgents,
+  listInstances, retireInstance, spawnInstance, upsertTmpAgent, workspaceOf, writeSoul, PACKAGED_SKILLS_DIR,
+  workspaceConfigSkillDirs, isOasWorkspace, resolveOasConfig, runLifecycleHooks,
+} from "./core-loader.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** .agents/skills dirs in ancestors ABOVE the git repo root — pi's own walk stops at the
+ *  repo root, so workspace-level skills (e.g. <workspace>/.agents/skills) need contributing. */
+function workspaceSkillDirs(cwd: string): string[] {
+  let repoRoot: string | undefined;
+  let d = resolve(cwd);
+  while (true) {
+    if (existsSync(join(d, ".git"))) { repoRoot = d; break; }
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  if (!repoRoot) return []; // not in a repo: pi already walks to the filesystem root
+  const dirs: string[] = [];
+  d = dirname(repoRoot);
+  while (true) {
+    const cand = join(d, ".agents", "skills");
+    if (existsSync(cand)) dirs.push(cand);
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return dirs;
+}
+
+function globToRegex(glob: string): RegExp {
+  const esc = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${esc}$`, "i");
+}
+
+/** Models enabled in pi: settings `enabledModels` patterns (scoped models) expanded
+ *  against the registry; falls back to all auth-configured models if unscoped. */
+function availableModels(ctx: ExtensionContext): string[] {
+  const all = ctx.modelRegistry.getAvailable().map((m) => ({ full: `${m.provider}/${m.id}`, id: m.id }));
+  let patterns: string[] | undefined;
+  try {
+    patterns = SettingsManager.create(ctx.cwd).getEnabledModels();
+  } catch { /* fall through to unscoped */ }
+  if (!patterns || patterns.length === 0) return all.map((m) => m.full);
+
+  const out: string[] = [];
+  for (const raw of patterns) {
+    // strip optional :thinking suffix (e.g. "provider/id:high")
+    const pattern = raw.replace(/:(off|minimal|low|medium|high|xhigh)$/i, "");
+    const isGlob = /[*?[]/.test(pattern);
+    const matches = isGlob
+      ? all.filter((m) => globToRegex(pattern).test(m.full) || globToRegex(pattern).test(m.id))
+      : all.filter((m) => m.full.toLowerCase() === pattern.toLowerCase() || m.id.toLowerCase() === pattern.toLowerCase());
+    for (const m of matches) if (!out.includes(m.full)) out.push(m.full);
+  }
+  return out.length > 0 ? out : all.map((m) => m.full);
+}
+function validateModel(ctx: ExtensionContext, model?: string): string | undefined {
+  if (!model) return undefined;
+  const models = availableModels(ctx);
+  if (models.includes(model)) return model;
+  const matches = models.filter((m) => m.toLowerCase().includes(model.toLowerCase()));
+  if (matches.length === 1) return matches[0];
+  throw new Error(
+    matches.length === 0
+      ? `model "${model}" is not enabled in pi — available: ${models.join(", ")}`
+      : `model "${model}" is ambiguous (${matches.join(", ")}) — be more specific`,
+  );
+}
+function text(s: string) {
+  return { content: [{ type: "text" as const, text: s }] };
+}
+
+export default function (pi: ExtensionAPI) {
+  // (PI_AGENT_HOME is set by spawnInstance's launch command)
+  const agentHome = process.env.PI_AGENT_HOME;
+  const isInstance = !!agentHome && existsSync(join(agentHome ?? "", "instance.json"));
+
+  // ---------- kernel + workspace skills: only inside OAS workspaces ----------
+  // (a workspace/repo with an oas-config, an agents/ root, or an instance home —
+  //  agents elsewhere on the machine do not get OAS skills)
+  pi.on("resources_discover", async (event, ctx) => {
+    const paths: string[] = [];
+    const inOas = isInstance || isOasWorkspace(event.cwd);
+    if (inOas && existsSync(PACKAGED_SKILLS_DIR)) paths.push(PACKAGED_SKILLS_DIR);
+    if (ctx.isProjectTrusted()) {
+      paths.push(...workspaceSkillDirs(event.cwd));
+      for (const p of workspaceConfigSkillDirs(event.cwd)) if (!paths.includes(p)) paths.push(p);
+    }
+    if (paths.length === 0) return;
+    return { skillPaths: paths };
+  });
+
+  // ---------- inside a spawned instance: memory automation ----------
+
+  if (isInstance) {
+    // Memory automation is gated on the knowledge integration having scaffolded
+    // instance memory (STATE.md/log.md are OKF conventions — kernel is agnostic;
+    // an instance without a knowledge integration has neither file, so both
+    // hooks below no-op for it).
+    // Compaction survival: journal every compaction summary to the instance log,
+    // and remind the model to refresh STATE.md — zero agent discipline required.
+    pi.on("session_compact", async (event) => {
+      if (!existsSync(join(agentHome!, "STATE.md"))) return;
+      try {
+        const summary = (event.compactionEntry?.summary ?? "").replace(/\s+/g, " ").trim();
+        appendLogEntry(
+          join(agentHome!, "log.md"),
+          `**Compaction** (${event.reason}): ${summary.slice(0, 400)}${summary.length > 400 ? "…" : ""}`,
+          "Instance Log",
+        );
+      } catch { /* never break the session over journaling */ }
+      pi.sendMessage({
+        customType: "oas-memory",
+        content: "Context was just compacted. Before continuing, update ./STATE.md (Plan/Progress/Next) so a fresh session could resume from files alone.",
+        display: false,
+      }, { deliverAs: "steer" });
+    });
+
+    // Post-commit lifecycle: after a successful `git commit` by this instance, fire
+    // the integrations' post-commit hooks (e.g. oas-okf spawns a knowledge-harvest
+    // agent attached to this instance's work tree). Kernel stays layer-agnostic.
+    pi.on("tool_result", async (event) => {
+      if (event.toolName !== "bash" || event.isError) return;
+      const cmd = String((event.input as { command?: string })?.command ?? "");
+      if (!/\bgit\b[^\n;&|]*\bcommit\b/.test(cmd)) return;
+      try {
+        const meta = JSON.parse(readFileSync(join(agentHome!, "instance.json"), "utf8"));
+        const root = findRoot(agentHome!);
+        if (!root || !meta.repo) return;
+        runLifecycleHooks("post-commit", {
+          home: agentHome!, instance: meta.instance, agentName: meta.agent,
+          soulDir: join(agentHome!, "soul"), contextDir: meta.repo,
+          workspaceDir: workspaceOf(root), rootDir: root,
+          resolved: resolveOasConfig(meta.repo), priorMeta: meta.providerMeta || {},
+        });
+      } catch { /* hooks never break the session */ }
+    });
+
+    // Resume nudge: on any later session in this home (restart, model switch, /new),
+    // point the model at its own memory before it does anything else.
+    pi.on("session_start", async (event) => {
+      if (event.reason !== "startup" && event.reason !== "resume" && event.reason !== "new") return;
+      const statePath = join(agentHome!, "STATE.md");
+      if (!existsSync(statePath)) return;
+      const state = readFileSync(statePath, "utf8");
+      const touched = !/_No task assigned yet/.test(state) || !/_\(the single next action/.test(state);
+      if (event.reason === "startup" && !touched) return; // fresh spawn — TASK.md covers it
+      pi.sendMessage({
+        customType: "oas-memory",
+        content: `You are agent instance home ${agentHome}. Read ./STATE.md and the recent entries of ./log.md now, then continue from STATE.md's "Next" section. Keep STATE.md current as you work.`,
+        display: false,
+      }, { deliverAs: "steer", triggerTurn: false });
+    });
+  }
+
+  // ---------- tools ----------
+  pi.registerTool({
+    name: "spawn_agent",
+    label: "Spawn Agent",
+    description: [
+      "Spawn an agent instance in tmux from the closest agents/ directory (walking up from cwd).",
+      "Modes: spawn an existing agent by name; create a tmp (adhoc) agent by passing `instructions`",
+      "(a full AGENTS.md defining behavior); or import a .claude/agents/.agents/agents def by passing `defFile`.",
+      "Each instance gets a home dir with the soul linked in, a TASK.md briefing, and a work tree:",
+      "`worktree` = own git worktree + branch, `checkout` = symlink to the repo's checked-out branch.",
+      "Returns instance metadata including the tmux window. Model must be one enabled in pi (see agents_status).",
+    ].join(" "),
+    promptSnippet: "Spawn an agent (persistent, adhoc, or from an agent def file) in tmux",
+    promptGuidelines: [
+      "Use spawn_agent when the user asks to launch/spin up an agent, delegate a task to a new agent session, or create a subagent.",
+      "Before spawn_agent with a model the user named loosely, call agents_status to see enabled models.",
+      "For adhoc subagents, write complete standalone instructions — the tmp agent knows nothing about this conversation.",
+    ],
+    parameters: Type.Object({
+      agent: Type.String({ description: "Agent name (existing agent, or name for a new tmp agent)" }),
+      instructions: Type.Optional(Type.String({
+        description: "Full AGENTS.md content for a local/adhoc agent. Creates/updates <root>/local-agents/<agent>/soul.",
+      })),
+      defFile: Type.Optional(Type.String({
+        description: "Path to a single-file agent def (.claude/agents/<x>.md style, frontmatter + body) to import as a tmp agent",
+      })),
+      task: Type.Optional(Type.String({ description: "Task briefing written to the instance's TASK.md and given as the first prompt" })),
+      purpose: Type.Optional(Type.String({ description: "Short kebab slug describing what this instance is for; names the instance <agent>-<purpose>" })),
+      model: Type.Optional(Type.String({ description: "Model as provider/id (must be enabled in pi); defaults to the soul's model or pi's default" })),
+      repo: Type.Optional(Type.String({ description: "Target repo (absolute, or relative to the agents root's parent). Defaults to the soul's repo, else the current git repo" })),
+      work: Type.Optional(StringEnum(["worktree", "checkout"] as const, {
+        description: "worktree = own git worktree + branch; checkout = work directly on the repo's checked-out branch. Defaults to the soul's setting",
+      })),
+      runtime: Type.Optional(StringEnum(["pi", "claude"] as const, { description: "Session runtime (default: soul's setting, else pi)" })),
+      branch: Type.Optional(Type.String({ description: "Branch name for worktree mode (default: agents/<instance>)" })),
+      launch: Type.Optional(Type.Boolean({ description: "Launch in tmux (default true). false = scaffold only and return the launch command" })),
+    }),
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const root = ensureRoot(ctx.cwd);
+      const model = validateModel(ctx, p.model);
+
+      let agent = findAgent(root, p.agent);
+      if (p.instructions !== undefined || p.defFile !== undefined || (!agent && !p.instructions)) {
+        if (!agent && p.instructions === undefined && p.defFile === undefined) {
+          // Maybe it matches a .claude/agents / .agents/agents def by name.
+          const def = listAgentDefs(ctx.cwd).find((d) => d.name === p.agent);
+          if (!def) {
+            const known = [...listAgents(root).map((a) => a.name), ...listAgentDefs(ctx.cwd).map((d) => d.name)];
+            throw new Error(`unknown agent "${p.agent}" — known: ${known.join(", ") || "(none)"}. Pass instructions to create a tmp agent.`);
+          }
+          agent = upsertTmpAgent(root, { name: def.name, file: def.path, repo: p.repo, work: p.work, runtime: p.runtime, model: p.model });
+        } else if (!agent || agent.kind === "tmp") {
+          agent = upsertTmpAgent(root, {
+            name: p.agent, instructions: p.instructions, file: p.defFile,
+            repo: p.repo, work: p.work, runtime: p.runtime, model: p.model,
+          });
+        } else if (p.instructions !== undefined) {
+          throw new Error(`"${p.agent}" is a persistent agent — edit its soul instead of passing instructions`);
+        }
+      }
+
+      const result = spawnInstance(root, agent!, {
+        instance: undefined, purpose: p.purpose, repo: p.repo || agent!.repo || defaultRepo(ctx.cwd),
+        work: p.work, runtime: p.runtime, model, task: p.task, branch: p.branch, launch: p.launch,
+      });
+      return { ...text(JSON.stringify(result, null, 2)), details: result };
+    },
+  });
+
+  pi.registerTool({
+    name: "agents_status",
+    label: "Agents Status",
+    description: [
+      "List the closest agents/ root: agents (persistent + tmp) with their souls and instances (running = has a live tmux window),",
+      "importable single-file defs from .claude/agents and .agents/agents, and the models currently enabled in pi.",
+    ].join(" "),
+    promptSnippet: "List agents, their running instances, importable defs, and enabled models",
+    promptGuidelines: [
+      "Use agents_status to discover what agents exist and which models are enabled before spawning.",
+    ],
+    parameters: Type.Object({}),
+    async execute(_id, _p, _signal, _onUpdate, ctx) {
+      const root = findRoot(ctx.cwd);
+      const details = {
+        root: root ?? null,
+        workspace: root ? workspaceOf(root) : null,
+        agents: root ? listInstances(root) : [],
+        agentDefs: listAgentDefs(ctx.cwd),
+        enabledModels: availableModels(ctx),
+      };
+      return { ...text(JSON.stringify(details, null, 2)), details };
+    },
+  });
+
+  pi.registerTool({
+    name: "retire_agent",
+    label: "Retire Agent",
+    description: "Retire an agent instance: kill its tmux window, remove its git worktree (if any), and delete its instance dir. Optionally delete its branch.",
+    promptSnippet: "Retire an agent instance (tmux window + worktree + instance dir)",
+    parameters: Type.Object({
+      instance: Type.String({ description: "Instance name (see agents_status)" }),
+      deleteBranch: Type.Optional(Type.Boolean({ description: "Also delete the instance's git branch (worktree mode)" })),
+      keepDir: Type.Optional(Type.Boolean({ description: "Keep the instance directory on disk" })),
+    }),
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const root = ensureRoot(ctx.cwd);
+      if (isInstance && p.instance === process.env.PI_AGENT_INSTANCE) {
+        return { ...text(`"${p.instance}" is YOU — use the retire_self tool instead (it harvests your notes and schedules your window kill safely).`), isError: true };
+      }
+      const result = retireInstance(root, p.instance, { deleteBranch: p.deleteBranch, keepDir: p.keepDir });
+      return { ...text(JSON.stringify(result, null, 2)), details: result };
+    },
+  });
+
+  // ---------- retire_self: only registered inside a spawned instance ----------
+  if (isInstance) {
+    pi.registerTool({
+      name: "retire_self",
+      label: "Retire Self",
+      description: "Retire THIS instance: run integration retire hooks (e.g. messaging identity self-delete, knowledge consolidation/harvest), remove the worktree and home dir, then kill this tmux window after a short delay. Irreversible. Use only when your task is complete (or your human told you to retire). Finish your memory FIRST per your knowledge integration's conventions (with okf: STATE.md, log.md, notes/) — retire hooks only take what is on disk when you call this.",
+      promptSnippet: "Retire this instance (harvest + cleanup + delayed window kill)",
+      parameters: Type.Object({
+        confirm: Type.Literal("retire", { description: 'Must be the string "retire" — confirms you mean to permanently retire this instance' }),
+        deleteBranch: Type.Optional(Type.Boolean({ description: "Also delete this instance's git branch (worktree mode)" })),
+      }),
+      async execute(_id, p, _signal, _onUpdate, ctx) {
+        const name = process.env.PI_AGENT_INSTANCE!;
+        const root = ensureRoot(ctx.cwd);
+        const result = retireInstance(root, name, { self: true, deleteBranch: p.deleteBranch });
+        return {
+          ...text(`Retired. Harvested: ${JSON.stringify(result.harvested)}. This window dies in ~8s — say any goodbyes now.`),
+          details: result,
+        };
+      },
+    });
+  }
+
+  // ---------- /agents command ----------
+  pi.registerCommand("agents", {
+    description: "Spawn/list/retire agents from the closest agents/ directory",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) { ctx.ui.notify("/agents needs an interactive UI", "error"); return; }
+      let root = findRoot(ctx.cwd);
+      const arg = (args || "").trim();
+
+      if (arg === "list" || (arg === "" && !root)) {
+        if (!root) { ctx.ui.notify(`No agents/ dir found above ${ctx.cwd} — mkdir agents, or set PI_AGENTS_ROOT`, "warning"); return; }
+      }
+
+      if (!root) return;
+      const agents = listInstances(root);
+      const defs = listAgentDefs(ctx.cwd).filter((d) => !agents.some((a) => a.name === d.name));
+      const running = agents.flatMap((a) => a.instances.filter((i: any) => i.running).map((i: any) => i.instance));
+
+      const items = [
+        ...agents.map((a) => `spawn: ${a.name}${a.kind === "tmp" ? " (tmp)" : ""} — ${a.description || a.repo || ""}`),
+        ...defs.map((d) => `import: ${d.name} — ${d.description || d.source}`),
+        "new adhoc agent…",
+        ...(running.length ? ["retire an instance…"] : []),
+        "status",
+      ];
+      const choice = await ctx.ui.select(`agents @ ${root}`, items);
+      if (!choice) return;
+
+      try {
+        if (choice === "status") {
+          const lines = agents.flatMap((a) => [
+            `${a.kind === "tmp" ? "[tmp] " : ""}${a.name} — repo=${a.repo || "?"} work=${a.work} runtime=${a.runtime}${a.model ? ` model=${a.model}` : ""}`,
+            ...a.instances.map((i: any) => `  ${i.running ? "●" : "○"} ${i.instance}${i.branch ? ` [${i.branch}]` : ""}`),
+          ]);
+          ctx.ui.notify(lines.join("\n") || "no agents", "info");
+          return;
+        }
+
+        if (choice === "retire an instance…") {
+          const inst = await ctx.ui.select("Retire which instance?", running);
+          if (!inst) return;
+          const delBranch = await ctx.ui.confirm("Delete branch?", "Also delete the instance's git branch (if worktree)?");
+          const r = retireInstance(root, inst, { deleteBranch: delBranch });
+          ctx.ui.notify(`Retired ${r.retired}`, "info");
+          return;
+        }
+
+        // Model picker shared by all spawn paths.
+        const pickModel = async (soulModel?: string): Promise<string | undefined> => {
+          const models = availableModels(ctx);
+          const def = soulModel ? `soul default (${soulModel})` : "pi default";
+          const picked = await ctx.ui.select("Model for this instance:", [def, ...models]);
+          if (!picked || picked === def) return soulModel;
+          return picked;
+        };
+        const askTask = async () => (await ctx.ui.editor("Task briefing (TASK.md):", "")) || undefined;
+
+        if (choice === "new adhoc agent…") {
+          const name = await ctx.ui.input("Adhoc agent name:", "e.g. api-doc-writer");
+          if (!name) return;
+          const instructions = await ctx.ui.editor("Agent instructions (its AGENTS.md):", "# Role\n\nYou are ");
+          if (!instructions?.trim()) return;
+          const repo = await ctx.ui.input("Repo (abs or relative to workspace):", defaultRepo(ctx.cwd) || "");
+          const work = await ctx.ui.select("Work mode:", ["checkout (work on the repo's current branch)", "worktree (own worktree + branch)"]);
+          if (!work) return;
+          const model = await pickModel();
+          const agent = upsertTmpAgent(root, {
+            name, instructions, repo: repo || defaultRepo(ctx.cwd) || undefined,
+            work: work.startsWith("worktree") ? "worktree" : "checkout", model,
+          });
+          const r = spawnInstance(root, agent, { task: await askTask(), model });
+          ctx.ui.notify(`Launched ${r.instance} — ${r.attach}`, "info");
+          return;
+        }
+
+        if (choice.startsWith("import: ")) {
+          const name = choice.slice("import: ".length).split(" — ")[0];
+          const def = listAgentDefs(ctx.cwd).find((d) => d.name === name)!;
+          const repo = await ctx.ui.input("Repo (abs or relative to workspace):", defaultRepo(ctx.cwd) || "");
+          const agent = upsertTmpAgent(root, { name: def.name, file: def.path, repo: repo || defaultRepo(ctx.cwd) || undefined });
+          const model = await pickModel(agent.model);
+          const r = spawnInstance(root, agent, { task: await askTask(), model });
+          ctx.ui.notify(`Launched ${r.instance} — ${r.attach}`, "info");
+          return;
+        }
+
+        if (choice.startsWith("spawn: ")) {
+          const name = choice.slice("spawn: ".length).split(" — ")[0].replace(" (tmp)", "");
+          const agent = findAgent(root, name)!;
+          const purpose = await ctx.ui.input("Purpose slug (names the instance):", "e.g. fix-auth");
+          const model = await pickModel(agent.model);
+          const r = spawnInstance(root, agent, { purpose: purpose || undefined, model, task: await askTask() });
+          ctx.ui.notify(`Launched ${r.instance} — ${r.attach}`, "info");
+          return;
+        }
+      } catch (e: any) {
+        ctx.ui.notify(e.message, "error");
+      }
+    },
+  });
+
+  // ---------- convenience: create a persistent agent via tool too ----------
+  pi.registerTool({
+    name: "create_agent",
+    label: "Create Agent",
+    description: "Create a persistent agent soul under the closest agents/ directory (<root>/<name>/soul with soul.yaml + AGENTS.md). Does not spawn an instance.",
+    promptSnippet: "Create a persistent agent soul (soul.yaml + AGENTS.md) under agents/",
+    parameters: Type.Object({
+      name: Type.String(),
+      repo: Type.Optional(Type.String({ description: "Target repo (absolute, or relative to the agents root's parent)" })),
+      work: Type.Optional(StringEnum(["worktree", "checkout"] as const)),
+      runtime: Type.Optional(StringEnum(["pi", "claude"] as const)),
+      model: Type.Optional(Type.String({ description: "Default model as provider/id (must be enabled in pi)" })),
+      description: Type.Optional(Type.String()),
+      instructions: Type.Optional(Type.String({ description: "AGENTS.md content for the soul (default: a starter template)" })),
+    }),
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const root = ensureRoot(ctx.cwd);
+      const model = validateModel(ctx, p.model);
+      const r = createAgent(root, { ...p, model });
+      if (p.instructions) {
+        writeSoul(root, { name: r.agent, kind: "persistent", repo: p.repo, work: p.work, runtime: p.runtime, model, description: p.description, instructions: p.instructions });
+      }
+      return { ...text(`Created soul: ${r.soul}\nEdit ${r.soul}/AGENTS.md to shape the agent, then spawn_agent.`), details: r };
+    },
+  });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oas-framework/pi",
+  "version": "0.4.0",
+  "description": "OAS pi adapter — agent tools (spawn_agent, agents_status, retire_agent) and skill discovery for pi, over the globally installed @oas-framework/oas kernel",
+  "keywords": [
+    "pi-package",
+    "agents",
+    "oas"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/josep-reyero/oas-framework",
+    "directory": "packages/pi"
+  },
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ]
+  },
+  "files": [
+    "extension/",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}