allye-pi 2.5.1 → 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allye Assistant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -83,10 +83,56 @@ Then add the `allye` MCP server as described in [install-pi.md](docs/install-pi.
 export ALLYE_PAT=pat_...                    # Allye → Settings → API
 ./install.sh list --scope team              # approved skills you can see
 ./install.sh install claude team-standards  # claude | codex | opencode | pi | omp
+./install.sh install claude team-standards --reinstall   # replace an edited copy (kept as a backup)
 ./install.sh status                         # offline integrity check
 ```
 
-Each install downloads the skill's approved release, verifies every file and the canonical hash, opens a distribution for this machine, verifies the API-signed execution token, publishes the files into the harness's user skills directory with a provenance sidecar, and records the result on the API. Local edits and directories it did not install are never overwritten. The API decides which runtimes may receive skills and who may distribute them; the installer reports its decision rather than working around it. Use `--team <id>` (or `ALLYE_TEAM_ID`) when you belong to several teams. Requires `bash`, `curl`, `jq` and Node.js 18+.
+Each install downloads the skill's approved release, verifies every file and the canonical hash, opens a distribution for this machine, verifies the API-signed execution token, publishes the files into the harness's user skills directory with a provenance sidecar, and records the result on the API. The API decides which runtimes may receive skills; the installer reports its decision rather than working around it. Requires `bash`, `curl`, `jq` and Node.js 18+. The installer speaks compatibility contract `1.1.0`.
+
+Until the allye-api PROD release that supports contract `1.1.0`, the installer works only against HML (`ALLYE_API_URL` pointing at the HML API). Against PROD it fails with `409 RUNTIME_INCOMPATIBLE` or an execution-context error about a missing signing key, and changes nothing.
+
+### Who can install
+
+Any member with view access to a skill can install it: any tenant member for an organization skill, members of the skill's team for a team skill, the author for a personal skill. Each person's installs are recorded separately. The installer needs no team for the install itself; use `--team <id>` (or `ALLYE_TEAM_ID`) only when a skill slug matches skills in several teams, so the slug can be resolved (or pass the skill id instead). If view access is lost while an install is in progress, the API answers `409`, the installer rolls the swap back and tells you to get access and rerun.
+
+### Where skills go
+
+| Runtime | Skills directory |
+|---|---|
+| `claude` | `~/.claude/skills` |
+| `codex` | `$CODEX_HOME/skills` when `CODEX_HOME` is set, otherwise `~/.codex/skills` |
+| `opencode` | `${XDG_CONFIG_HOME:-~/.config}/opencode/allye-skills` |
+| `pi` | `$PI_CODING_AGENT_DIR/skills` when set, otherwise `~/.pi/agent/skills` |
+| `omp` | `~/.omp/agent/skills` |
+
+`CODEX_HOME` and `PI_CODING_AGENT_DIR` must be absolute paths; only the empty string means unset, a trailing `/` is stripped (`/` itself stays `/`), and a relative value stops that runtime's install before any request (other runtimes are unaffected). An empty or relative `XDG_CONFIG_HOME` is treated as unset. OpenCode does not discover this directory by itself: the `allye-opencode` plugin adds it to `skills.paths` when it is a real directory (not a symlink) owned by you and not group- or world-writable, so restart OpenCode after the first install creates it. The installer refuses to install into an `allye-skills` directory that is a symlink or group/world-writable (fix with `chmod go-w <dir>`); it does not check ownership, so the plugin additionally ignores a directory that is not owned by you. OMP presents itself to the API as runtime `pi`; Pi and OMP skills are installed as plain directories, with no package receipt.
+
+Changing `CODEX_HOME` or `PI_CODING_AGENT_DIR` changes the install target, and the installer does not migrate skills left in the old directory (for example `~/.codex/skills`). Those copies stay where they are; a copy found under the new directory is handled as in the next section.
+
+### Edited, deleted and moved copies
+
+| State of `<skills dir>/<name>` | What the installer does |
+|---|---|
+| Missing (first install or deleted) | Installs it again; the API records a reinstall when it already had an install for this machine |
+| Unchanged copy of the same release | Reports "already installed"; nothing is sent |
+| Unchanged copy of an older release | Updates it |
+| Edited by you | Refuses and changes nothing; rerun with `--reinstall` |
+| Not installed by the installer, or installed from another skill | Never touched, with or without `--reinstall` |
+| Contains a symlink or special file | Refuses and names the entry; with or without `--reinstall` |
+
+`--reinstall` replaces an edited copy with the approved release and keeps your edited folder at `~/.allye/backups/<adapter-id>/<name>.allye.backup.<UTC ts>` (`.<pid>` is appended if that name exists), outside every skills directory so no harness loads it. Backup directories are created with mode 0700, and the installer refuses to keep backups in a `~/.allye`, `backups` or `backups/<id>` that is a symlink, owned by someone else or group/world-writable (it changes nothing; fix the directory and rerun). The installer prints the path; backups are never overwritten or deleted, and `./install.sh status` does not list them. If anything fails before the install is recorded, your edited folder is put back.
+
+A copy records the machine and skills path it was installed for (as a digest; the hostname and path never leave the machine). After a hostname change, a different home or a changed `CODEX_HOME`, `PI_CODING_AGENT_DIR` or `XDG_CONFIG_HOME`, existing copies are "other-target": an unchanged one is reinstalled automatically here with no backup, while an edited one needs `--reinstall`.
+
+If an earlier run could not finish moving your edited folder (a failed restore, a failed backup move, or a killed run), it leaves `<skills dir>/.allye-backup.<name>.<UTC ts>.<pid>`. The installer then refuses to install `<name>`, prints each such path and sends nothing. Move the folder into `~/.allye/backups/<adapter-id>/` to keep it, or delete it, then rerun.
+
+### Errors
+
+- `409 DISTRIBUTION_NOT_AUTHORIZED`: you need view access to the skill (team membership or authorship); get access and rerun.
+- `410 MARKETPLACE_RETIRED`: the skill is a retired, read-only marketplace skill; nothing was installed. Use an organization or team skill.
+- `422 TEAM_SELECTION_REQUIRED`: the slug matches skills in several teams; rerun with `--team <team>` or use the skill id.
+- `409 RUNTIME_INCOMPATIBLE`: the API has no `1.1.0` profile, which is the case on PROD before the allye-api release. Use HML or wait for that release; there is nothing to reset and no admin to ask.
+- `400` mentioning a request field such as `idempotencyKey` or `target`: the API and the installer disagree on the request shape. Upgrade the installer; there is nothing to reset and no admin to ask.
 
 ## Repository layout
 
@@ -125,4 +171,4 @@ Releases are automated by semantic-release on every push to `main` (Conventional
 
 ## License
 
-MIT
+MIT, see [LICENSE](LICENSE).

package/docs/install-omp.md

@@ -22,10 +22,18 @@ OMP has a native MCP client (no `pi-mcp-adapter`). Add the server once, at user
 
 OMP also loads servers from a project `.mcp.json`. Do not add tokens or OAuth client metadata: OMP discovers the OAuth endpoints and opens the browser on first use.
 
-Because OMP's MCP client is not the in-process `pi-mcp-adapter` bridge, the extension does not preload Allye context in OMP. It injects only the git remote and any unverified `.allye/project.json` claim; the bootstrap tells the agent to call `projects.project_resolve` itself. The team follows the project, so no team selection is needed.
+Because OMP's MCP client is not the in-process `pi-mcp-adapter` bridge (as in OMP today), the extension does not resolve the project. It injects only the git remote and any unverified `.allye/project.json` claim; the bootstrap tells the agent to call `projects.project_resolve` itself. The team follows the project, so no team selection is needed.
 
 ## Confirm
 
 Tell the user:
 
 > Allye is installed for OMP: the `allye-pi` extension (bootstrap and Bridge) and the `allye` MCP server. Start a new OMP session and run `/bridge survey` (or another mode).
+
+## Organization skills
+
+`./install.sh install omp <skill>` (see the [README](../README.md#your-organizations-skills)) installs into `~/.omp/agent/skills`. OMP presents itself to the API as runtime `pi`, and the skill is installed as a plain directory, with no package receipt.
+
+- Edited copies: `./install.sh install omp <skill> --reinstall` replaces your edited copy and keeps it at `~/.allye/backups/omp/<skill>.allye.backup.<UTC ts>`. A copy of the same release on the same target is already installed (a no-op); older-release copies are updated, and copies recorded for another target (after a hostname or skills-path change) are reinstalled when unchanged, while an edited one needs `--reinstall`. Foreign or unmanaged folders are never touched.
+- Leftovers: if the installer reports a `.allye-backup.<skill>.*` entry in the skills directory, an earlier run kept your edited folder there. Move it into `~/.allye/backups/omp/` or delete it, then rerun.
+- Any member with view access to a skill can install it. If the installer is too old for the API, upgrade the installer; there is nothing to ask an admin to reset. Until the allye-api PROD release the installer works only against HML. See the [README](../README.md#your-organizations-skills).

package/docs/install-pi.md

@@ -4,7 +4,7 @@ Allye for Pi is the native package `allye-pi`. It:
 
 - exposes the Bridge skill (`/bridge <mode>`) from the package's `skills/` directory;
 - adds the Allye bootstrap (`bootstrap/allye.md`) to the system prompt;
-- preloads Allye context (`initialize`, `intelligence`) when an in-process MCP bridge is available, and identifies the repository's project: it resolves the git remote with `projects.project_resolve` and verifies any `.allye/project.json` claim against it, injecting "this repo = project X / app Y (team Z)", the ambiguous candidates, or the disagreement to ask the user about.
+- identifies the repository's project (it loads no startup or per-prompt memory context): when an in-process MCP bridge is available it resolves the git remote with `projects.project_resolve` and verifies any `.allye/project.json` claim against it, injecting "this repo = project X / app Y (team Z)", the ambiguous candidates, or the disagreement to ask the user about.
 
 It never edits Pi's MCP configuration or reads credentials.
 
@@ -32,11 +32,11 @@ Do not pass headers, bearer tokens or OAuth client ids: Pi discovers the OAuth e
 
 On older Pi versions without `pi mcp`, install `pi-mcp-adapter` (`pi install npm:pi-mcp-adapter`), define one server named `allye` (`{"type": "http", "url": "https://mcp.allye.app/mcp"}` under `mcpServers`) in the effective source shown by `/mcp` — for example `~/.pi/agent/mcp.json` or `~/.config/mcp/mcp.json` — then run `/mcp-auth allye` and `/mcp reconnect allye`.
 
-The extension preloads Allye context only when `pi-mcp-adapter` exposes its in-process bridge. Otherwise it injects only the git remote and any unverified link claim, and the bootstrap tells the agent to call `projects.project_resolve` itself.
+The extension resolves the repository's project only when `pi-mcp-adapter` exposes its in-process bridge. Otherwise it injects only the git remote and any unverified link claim, and the bootstrap tells the agent to call `projects.project_resolve` itself.
 
 ## Teams
 
-The team follows the project: the extension never blocks work on team selection. A default team is needed only to create projects; `/allye-team <name|prefix|id>` sets it through the `team` tool (`team_set_default`). Set `ALLYE_PI_NATIVE_BOOTSTRAP=0` to skip the context preload (the bootstrap text and the Bridge skill stay available), or `ALLYE_PI_MCP=0` to disable MCP calls from the extension.
+The team follows the project: the extension never blocks work on team selection. A default team is needed only to create projects; `/allye-team <name|prefix|id>` sets it through the `team` tool (`team_set_default`). Set `ALLYE_PI_NATIVE_BOOTSTRAP=0` to skip the repository block (the bootstrap text and the Bridge skill stay available), or `ALLYE_PI_MCP=0` to disable MCP calls from the extension.
 
 ## Local development
 
@@ -48,3 +48,11 @@ npm run typecheck
 npm run test:pi
 pi -e ./packages/allye-pi/src/index.ts -p "Which Allye tools and Bridge modes are available?"
 ```
+
+## Organization skills
+
+`./install.sh install pi <skill>` (see the [README](../README.md#your-organizations-skills)) installs into `$PI_CODING_AGENT_DIR/skills` when `PI_CODING_AGENT_DIR` is set, otherwise `~/.pi/agent/skills`. The value must be an absolute path; only the empty string means unset, a trailing `/` is stripped, and a relative value stops the Pi install before any request. Changing it changes the install target; copies left in the old directory are not migrated. The API sees runtime `pi` and the skill is installed as a plain directory, with no package receipt.
+
+- Edited copies: `./install.sh install pi <skill> --reinstall` replaces your edited copy and keeps it at `~/.allye/backups/pi/<skill>.allye.backup.<UTC ts>`. A copy of the same release on the same target is already installed (a no-op); older-release copies are updated, and copies recorded for another target (after a hostname or skills-path change) are reinstalled when unchanged, while an edited one needs `--reinstall`. Foreign or unmanaged folders are never touched.
+- Leftovers: if the installer reports a `.allye-backup.<skill>.*` entry in the skills directory, an earlier run kept your edited folder there. Move it into `~/.allye/backups/pi/` or delete it, then rerun.
+- Any member with view access to a skill can install it. If the installer is too old for the API, upgrade the installer; there is nothing to ask an admin to reset. Until the allye-api PROD release the installer works only against HML. See the [README](../README.md#your-organizations-skills).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Allye extension for Pi and OMP: the Allye bootstrap, the Bridge skill and the repository-to-project link",
   "type": "module",
   "keywords": [
@@ -43,11 +43,12 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p packages/allye-pi/tsconfig.json",
     "test:pi": "node --experimental-strip-types --test packages/allye-pi/src/index.test.ts",
+    "test:opencode": "node --experimental-strip-types --test packages/allye-opencode/src/skills-paths.test.ts",
     "test:installer": "bash install/test-validation.sh && bash install/test-installer.sh",
     "test:bootstrap": "bash test/test-bootstrap.sh && bash hooks/test-session-start.sh",
     "test:agents": "node test/test-agents.mjs",
-    "test:skills": "node test/test-skills-text.mjs && node test/test-ci-proof.mjs",
-    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi"
+    "test:skills": "node test/test-skills-text.mjs && node test/test-ci-proof.mjs && node test/test-ci-workflows.mjs",
+    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi && npm run test:opencode"
   },
   "repository": {
     "type": "git",

package/packages/allye-pi/src/index.ts

@@ -9,14 +9,14 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
  *
  * - Exposes the repository's skills/ directory (Bridge) through resources_discover.
  * - Adds the shared bootstrap (bootstrap/allye.md) to the system prompt.
- * - Preloads Allye context through the configured MCP bridge when one is
- *   available, and identifies the repo's project with `projects.project_resolve`,
- *   verifying any `.allye/project.json` claim against the git remote.
+ * - Identifies the repo's project with `projects.project_resolve` (through the
+ *   configured MCP bridge when one is available), verifying any
+ *   `.allye/project.json` claim against the git remote. It loads no startup or
+ *   per-prompt memory context.
  *   The team follows the project: nothing is gated on team selection.
  */
 
 const MCP_SERVER = "allye";
-const MAX_CONTEXT_CHARS = 12_000;
 const LINK_FILE = ".allye/project.json";
 const PROJECT_KEY = /^[A-Z][A-Z0-9]{1,9}$/;
 const APP_NAME = /^[A-Za-z0-9._-]{1,120}$/;
@@ -25,11 +25,6 @@ const MAX_CANDIDATES = 10;
 const MAX_REPO_CHARS = 4_000;
 
 type McpResult = { content?: Array<{ type?: string; text?: string }> };
-export type StartupContext = {
-  text: string;
-  repo: string;
-  allyeUnavailable: boolean;
-};
 type ActiveMcpToolCaller = (
   serverName: string,
   toolName: string,
@@ -83,7 +78,7 @@ async function callAllye(toolName: string, args: Record<string, unknown>): Promi
   // pi-mcp-adapter may expose an in-process bridge for cooperating extensions.
   // Without it, the agent still reaches Allye through its own MCP tools.
   const bridge = (globalThis as McpBridgeRuntime).__piMcpAdapterActiveToolCaller;
-  if (!bridge) throw new Error("no in-process MCP bridge is available to preload Allye context");
+  if (!bridge) throw new Error("no in-process MCP bridge is available");
   return resultText(await bridge(MCP_SERVER, toolName, args));
 }
 
@@ -300,82 +295,27 @@ async function buildRepoContext(cwd: string, online: boolean): Promise<string> {
   }
 }
 
-export function unavailableStartupContext(reason: string, repo = ""): StartupContext {
-  return {
-    text: `## Allye context not preloaded\n${reason}\nUse the Allye MCP tools directly when the task needs them: call \`initialize\` first.`,
-    repo,
-    allyeUnavailable: true,
-  };
-}
-
-async function loadStartupContext(cwd: string): Promise<StartupContext> {
-  if (!mcpBridgeAvailable()) {
-    return unavailableStartupContext("No in-process MCP bridge is available in this session.", await loadRepoContext(cwd, false));
-  }
-  try {
-    const initialization = await callAllye("initialize", { action: "init", include_user_docs: true });
-    const preferences = await callAllye("intelligence", { action: "memory_preferences" });
-    return {
-      text: [initialization, preferences].filter(Boolean).map((section) => limitText(section, MAX_CONTEXT_CHARS)).join("\n\n"),
-      repo: await loadRepoContext(cwd, true),
-      allyeUnavailable: false,
-    };
-  } catch (error) {
-    return unavailableStartupContext(
-      `Allye context could not be preloaded: ${error instanceof Error ? error.message : String(error)}`,
-      await loadRepoContext(cwd, false),
-    );
-  }
-}
-
-async function loadPromptContext(prompt: string): Promise<string> {
-  try {
-    return limitText(await callAllye("intelligence", {
-      action: "memory_search",
-      query: prompt,
-      limit: 5,
-      return_content: true,
-    }), MAX_CONTEXT_CHARS);
-  } catch {
-    return "";
-  }
-}
-
-export function buildSystemSections(bootstrap: string, startup: StartupContext, firstPrompt: boolean, nativeBootstrap = true): string[] {
+export function buildSystemSections(bootstrap: string, repo: string, nativeBootstrap = true): string[] {
   const sections: string[] = [];
   if (bootstrap) sections.push(`<allye-bootstrap>\n${bootstrap.trim()}\n</allye-bootstrap>`);
-  if (firstPrompt && nativeBootstrap && startup.text) sections.push(`<allye-startup-context>\n${startup.text}\n</allye-startup-context>`);
-  if (nativeBootstrap && startup.repo) sections.push(`<allye-repo>\n${startup.repo}\n</allye-repo>`);
+  if (nativeBootstrap && repo) sections.push(`<allye-repo>\n${repo}\n</allye-repo>`);
   return sections;
 }
 
 export default function allyePiExtension(pi: ExtensionAPI): void {
   const nativeBootstrap = process.env.ALLYE_PI_NATIVE_BOOTSTRAP !== "0";
-  let startupContext = unavailableStartupContext("Allye context has not been loaded yet.");
   let bootstrap = "";
-  let firstPrompt = true;
+  let repo = "";
 
   pi.on("resources_discover", () => ({ skillPaths: [skillsPath()] }));
 
   pi.on("session_start", async (_event, ctx) => {
-    firstPrompt = true;
     bootstrap = loadBootstrap();
-    if (nativeBootstrap) {
-      if (ctx.hasUI) ctx.ui.setStatus("allye", "loading Allye context…");
-      startupContext = await loadStartupContext(ctx.cwd ?? process.cwd());
-      if (ctx.hasUI) ctx.ui.setStatus("allye", startupContext.allyeUnavailable ? "Allye: context not preloaded" : "Allye ready");
-    }
+    if (nativeBootstrap) repo = await loadRepoContext(ctx.cwd ?? process.cwd(), mcpBridgeAvailable());
   });
 
-  pi.on("before_agent_start", async (event) => {
-    const sections = buildSystemSections(bootstrap, startupContext, firstPrompt, nativeBootstrap);
-    if (firstPrompt) {
-      firstPrompt = false;
-      if (nativeBootstrap && !startupContext.allyeUnavailable) {
-        const relevant = await loadPromptContext(event.prompt);
-        if (relevant) sections.push(`<allye-relevant-memory>\n${relevant}\n</allye-relevant-memory>`);
-      }
-    }
+  pi.on("before_agent_start", (event) => {
+    const sections = buildSystemSections(bootstrap, repo, nativeBootstrap);
     return sections.length ? { systemPrompt: `${event.systemPrompt}\n\n${sections.join("\n\n")}` } : undefined;
   });