@oas-framework/pi 0.4.0 → 0.6.0

package/extension/core-loader.mjs

@@ -55,9 +55,7 @@ if (!OAS_PKG_ROOT) {
 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,
+  appendLogEntry, PACKAGED_SKILLS_DIR, workspaceConfigSkillDirs, isOasWorkspace,
 } = core;
 
 /** Kernel package version (for skew diagnostics against the adapter). */

package/extension/index.ts

@@ -1,23 +1,19 @@
 /**
- * oas (Open Agent Specialization) — launch specialized agents from the closest agents/ directory (a2am-style souls & instances).
+ * oas pi adapter — pi-specific glue over the globally installed OAS kernel.
  *
- * 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
+ * Everything agents DO goes through the universal `oas` CLI (status, spawn,
+ * retire, create, doctor, integration commands) from the bash tool. This
+ * extension only handles what a runtime must integrate natively:
  *
- * Tools: spawn_agent, agents_status, retire_agent.  Command: /agents.
+ *   - skill discovery (resources_discover): the global getting-started skill,
+ *     the OAS skill bundle inside OAS contexts, workspace skills above the
+ *     repo boundary, and config-cascade skill dirs
+ *   - instance memory automation: compaction journaling + STATE.md steers,
+ *     and the resume nudge on session start
  */
-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 type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-  appendLogEntry, createAgent, defaultRepo, ensureRoot, findAgent, findRoot, listAgentDefs, listAgents,
-  listInstances, retireInstance, spawnInstance, upsertTmpAgent, workspaceOf, writeSoul, PACKAGED_SKILLS_DIR,
-  workspaceConfigSkillDirs, isOasWorkspace, resolveOasConfig, runLifecycleHooks,
+  appendLogEntry, isOasWorkspace, workspaceConfigSkillDirs, PACKAGED_SKILLS_DIR,
 } from "./core-loader.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -46,59 +42,20 @@ function workspaceSkillDirs(cwd: string): string[] {
   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)
+  // (PI_AGENT_HOME is set by the kernel'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)
+  // ---------- OAS skills ----------
+  // getting-started is GLOBAL (it bootstraps — must be discoverable before any OAS
+  // workspace exists). The rest of the bundle is gated to OAS contexts (instance
+  // home, or a workspace/repo with an oas-config / agents root). Workspace and
+  // config skills stay trust-gated.
   pi.on("resources_discover", async (event, ctx) => {
     const paths: string[] = [];
+    const gettingStarted = join(PACKAGED_SKILLS_DIR, "oas-getting-started");
+    if (existsSync(gettingStarted)) paths.push(gettingStarted);
     const inOas = isInstance || isOasWorkspace(event.cwd);
     if (inOas && existsSync(PACKAGED_SKILLS_DIR)) paths.push(PACKAGED_SKILLS_DIR);
     if (ctx.isProjectTrusted()) {
@@ -110,7 +67,6 @@ export default function (pi: ExtensionAPI) {
   });
 
   // ---------- 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;
@@ -135,26 +91,6 @@ export default function (pi: ExtensionAPI) {
       }, { 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) => {
@@ -171,267 +107,4 @@ export default function (pi: ExtensionAPI) {
       }, { 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

@@ -1,6 +1,6 @@
 {
   "name": "@oas-framework/pi",
-  "version": "0.4.0",
+  "version": "0.6.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",