@oas-framework/pi 0.6.2 → 0.7.0

package/README.md

@@ -1,31 +1,30 @@
 # @oas-framework/pi
 
-The OAS pi adapter for [pi](https://github.com/earendil-works/pi). It
-handles the pi-specific glue over the globally installed OAS kernel:
+Minimal pi adapter for [OAS](https://github.com/josep-reyero/oas-framework).
 
-- **Skill discovery** — the global `oas-getting-started` skill, the OAS
-  skill bundle inside OAS workspaces, and workspace skills above the git
-  repo boundary.
-- **Instance memory automation** — compaction journaling and STATE.md
-  resume nudges for spawned agent instances.
+The runtime-neutral kernel and universal `oas` CLI live in
+`@oas-framework/oas`. This adapter registers no operational tools. It only:
 
-It registers **no tools**: all agent operations (status, create, spawn,
-retire) and configuration run through the universal `oas` CLI, which agents
-invoke with the bash tool — identically in pi, Claude Code, or a plain
-shell. 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.
+- exposes `oas-getting-started` before an OAS workspace exists;
+- points spawned sessions at their exact instance-local `.agents/skills` set;
+- journals compaction summaries and sends resume nudges when the active
+  knowledge capability created `STATE.md`/`log.md`.
 
-## Install
+The kernel launches pi with `--no-skills --skill <instance>/.agents/skills`,
+so user, project, settings, ancestor, and pi-package skill discovery cannot
+pollute one soul's selected runtime surface.
 
 ```bash
-npm install -g @oas-framework/oas   # the kernel + oas CLI (required)
-pi install npm:@oas-framework/pi    # this adapter
+npm install -g @oas-framework/oas
+pi install npm:@oas-framework/pi
 ```
 
-The adapter locates the kernel via the `oas` binary on PATH (override with
-`OAS_PKG_ROOT`, e.g. to point at a dev clone).
+Install matching versions and upgrade both packages together. Exact isolation
+needs the new kernel launch flags and this adapter's instance-only discovery.
+An older adapter still contributes workspace and package skill roots. OAS
+publishes both packages from the same version tag. Reload pi after an adapter
+install or upgrade.
 
-See the [oas-framework repo](https://github.com/josep-reyero/oas-framework)
-for the full documentation.
+All lifecycle/config/package operations use the shell-visible CLI: `oas
+status`, `oas spawn`, `oas doctor`, `oas install`, `oas trust`, `oas use`, and
+`oas retire`.

package/extension/core-loader.mjs

@@ -1,7 +1,7 @@
 /**
  * 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
+ * the kernel, skills, injects, or capabilities — those live in the global CLI
  * package (npm i -g @oas-framework/oas), the single source of truth that the
  * future Claude plugin shares.
  *
@@ -54,9 +54,7 @@ if (!OAS_PKG_ROOT) {
 
 const core = await import(pathToFileURL(join(OAS_PKG_ROOT, "lib", "core.mjs")).href);
 
-export const {
-  appendLogEntry, PACKAGED_SKILLS_DIR, workspaceConfigSkillDirs, isOasWorkspace,
-} = core;
+export const { appendLogEntry, PACKAGED_SKILLS_DIR } = core;
 
 /** Kernel package version (for skew diagnostics against the adapter). */
 export function kernelVersion() {

package/extension/index.ts

@@ -1,79 +1,29 @@
 /**
- * oas pi adapter — pi-specific glue over the globally installed OAS kernel.
+ * OAS pi adapter — minimal runtime glue.
  *
- * 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:
- *
- *   - 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
+ * Skill visibility is deliberately instance-local. Outside an instance, only
+ * oas-getting-started is contributed as pre-workspace bootstrap. The kernel
+ * materializes every spawned instance's exact set in .agents/skills.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  appendLogEntry, isOasWorkspace, workspaceConfigSkillDirs, PACKAGED_SKILLS_DIR,
-} from "./core-loader.mjs";
+import { appendLogEntry, PACKAGED_SKILLS_DIR } 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;
-}
+import { join } from "node:path";
 
 export default function (pi: ExtensionAPI) {
-  // (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"));
+  const isInstance = !!agentHome && existsSync(join(agentHome, "instance.json"));
 
-  // ---------- 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()) {
-      paths.push(...workspaceSkillDirs(event.cwd));
-      for (const p of workspaceConfigSkillDirs(event.cwd)) if (!paths.includes(p)) paths.push(p);
+  pi.on("resources_discover", async () => {
+    if (isInstance) {
+      const local = join(agentHome!, ".agents", "skills");
+      return existsSync(local) ? { skillPaths: [local] } : undefined;
     }
-    if (paths.length === 0) return;
-    return { skillPaths: paths };
+    const gettingStarted = join(PACKAGED_SKILLS_DIR, "oas-getting-started");
+    return existsSync(gettingStarted) ? { skillPaths: [gettingStarted] } : undefined;
   });
 
-  // ---------- 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 {
@@ -83,7 +33,7 @@ export default function (pi: ExtensionAPI) {
           `**Compaction** (${event.reason}): ${summary.slice(0, 400)}${summary.length > 400 ? "…" : ""}`,
           "Instance Log",
         );
-      } catch { /* never break the session over journaling */ }
+      } catch { /* memory automation must never break a session */ }
       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.",
@@ -91,15 +41,13 @@ export default function (pi: ExtensionAPI) {
       }, { deliverAs: "steer" });
     });
 
-    // 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
+      if (event.reason === "startup" && !touched) return;
       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.`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oas-framework/pi",
-  "version": "0.6.2",
-  "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",
+  "version": "0.7.0",
+  "description": "Minimal OAS pi adapter — instance-local skill discovery and memory session events over the runtime-neutral @oas-framework/oas kernel",
   "keywords": [
     "pi-package",
     "agents",