@awebai/oats-pi 0.22.0

package/README.md

@@ -0,0 +1,33 @@
+# @awebai/oats-pi
+
+Pi runtime bridge for [OATS](https://github.com/awebai/oats).
+
+The runtime-neutral kernel and universal `oats` CLI live in
+`@awebai/oats`. Publishes in lockstep with the kernel (same version
+from the same release tag). This bridge registers no operational tools. It only:
+
+- exposes `oats-getting-started` before an OATS workspace exists (the
+  acquisition funnel);
+- contributes the instance-local `.agents/skills` set inside a spawned
+  instance;
+- journals compaction summaries and sends resume nudges when the active
+  knowledge capability created `STATE.md`/`log.md` — the OKF session
+  protocol enforced at runtime.
+
+Skill resolution itself is owned by the kernel: spawn materializes the exact
+kernel + soul + active-capability set into each instance's `.agents/skills`
+and launches pi with that directory as an explicit skill path. Ambient
+skills (user-level, packages, work tree) coexist with the OATS-composed set.
+
+```bash
+npm install -g @awebai/oats
+pi install npm:@awebai/oats-pi
+```
+
+OATS
+publishes both packages from the same version tag. Reload pi after an adapter
+install or upgrade.
+
+All lifecycle/config/package operations use the shell-visible CLI: `oats
+status`, `oats spawn`, `oats doctor`, `oats install`, `oats trust`, `oats use`, and
+`oats retire`.

package/extension/core-loader.mjs

@@ -0,0 +1,62 @@
+/**
+ * core-loader.mjs — locate the globally installed @awebai/oats kernel and
+ * re-export its lib/core.mjs. The pi package is a thin adapter: it never ships
+ * the kernel, skills, injects, or capabilities — those live in the global CLI
+ * package (npm i -g @awebai/oats), the single source of truth that the
+ * future Claude plugin shares.
+ *
+ * Resolution order:
+ *   1. $OATS_PKG_ROOT (explicit override, e.g. a dev clone)
+ *   2. the `oats` binary on PATH → realpath → its package root
+ *   3. `npm root -g`/@awebai/oats (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 = "@awebai/oats";
+
+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.OATS_PKG_ROOT && isKernelRoot(process.env.OATS_PKG_ROOT)) return process.env.OATS_PKG_ROOT;
+  try {
+    const bin = execSync("command -v oats", { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    if (bin) {
+      let d = dirname(realpathSync(bin)); // <pkg>/bin/oats.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 OATS_PKG_ROOT = findKernelRoot();
+if (!OATS_PKG_ROOT) {
+  throw new Error(
+    "OATS kernel not found — the pi adapter needs the oats CLI installed globally.\n" +
+    "  Install it:  npm install -g @awebai/oats\n" +
+    "  (or point OATS_PKG_ROOT at a checkout of the awebai/oats repo)",
+  );
+}
+
+const core = await import(pathToFileURL(join(OATS_PKG_ROOT, "lib", "core.mjs")).href);
+
+export const { appendLogEntry, PACKAGED_SKILLS_DIR } = core;
+
+/** Kernel package version (for skew diagnostics against the adapter). */
+export function kernelVersion() {
+  try { return JSON.parse(readFileSync(join(OATS_PKG_ROOT, "package.json"), "utf8")).version; } catch { return "unknown"; }
+}

package/extension/index.ts

@@ -0,0 +1,59 @@
+/**
+ * OATS pi runtime bridge — minimal glue.
+ *
+ * The kernel materializes every spawned instance's exact set in
+ * .agents/skills; this bridge contributes it inside an instance, plus the
+ * pre-workspace oats-getting-started bootstrap outside one, and drives the
+ * memory session events. Ambient skills coexist with the OATS-composed set.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendLogEntry, PACKAGED_SKILLS_DIR } from "./core-loader.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export default function (pi: ExtensionAPI) {
+  const agentHome = process.env.PI_AGENT_HOME;
+  const isInstance = !!agentHome && existsSync(join(agentHome, "instance.json"));
+
+  pi.on("resources_discover", async () => {
+    if (isInstance) {
+      const local = join(agentHome!, ".agents", "skills");
+      return existsSync(local) ? { skillPaths: [local] } : undefined;
+    }
+    const gettingStarted = join(PACKAGED_SKILLS_DIR, "oats-getting-started");
+    return existsSync(gettingStarted) ? { skillPaths: [gettingStarted] } : undefined;
+  });
+
+  if (isInstance) {
+    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 { /* memory automation must never break a session */ }
+      pi.sendMessage({
+        customType: "oats-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" });
+    });
+
+    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;
+      pi.sendMessage({
+        customType: "oats-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 });
+    });
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@awebai/oats-pi",
+  "version": "0.22.0",
+  "description": "OATS pi runtime bridge — memory session events and pre-workspace bootstrap over the runtime-neutral @awebai/oats kernel",
+  "keywords": [
+    "pi-package",
+    "agents",
+    "oats"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/awebai/oats",
+    "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": "*"
+  }
+}