@uniqbit/mate-opencode-plugin 0.17.0-canary.8 → 0.17.1

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@uniqbit/mate-opencode-plugin",
-  "version": "0.17.0-canary.8",
+  "version": "0.17.1",
   "description": "OpenCode plugin integration for Mate.",
   "license": "MIT",
   "files": [
+    "server.ts",
+    "tui.tsx",
     "src/",
     "!src/**/*.test.ts"
   ],
@@ -24,15 +26,30 @@
     "format:check": "oxfmt src/ --check"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.18.3",
-    "@opentui/core": "^0.4.5",
-    "@opentui/keymap": "^0.4.5",
-    "@opentui/solid": "^0.4.5",
-    "@uniqbit/mate-core": "0.17.0-canary.8"
+    "@opencode/plugin": "^2.0.23",
+    "@uniqbit/mate-core": "0.17.1"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "context-mode": "1.0.169"
+    "@opentui/core": "^0.5.14",
+    "@opentui/keymap": "^0.5.14",
+    "@opentui/solid": "^0.5.14",
+    "@types/bun": "^1.3.14"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.14",
+    "@opentui/keymap": ">=0.5.14",
+    "@opentui/solid": ">=0.5.14"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/keymap": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=24"

package/server.ts

@@ -0,0 +1,5 @@
+/**
+ * Root entry for a plugin bound by directory path: OpenCode resolves `<dir>/server`
+ * there and never reads `exports`, which serves only package-name references.
+ */
+export { default } from "./src/server";

package/src/add-dir.ts

@@ -1,17 +1,15 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 
-import type { Config, Hooks, Plugin } from "@opencode-ai/plugin";
-import { readCompanionRuntimeContext } from "@uniqbit/mate-core/runtime";
+import type { Context } from "@opencode/plugin/promise/plugin";
 
-// OpenCode accepts a per-path rule map for external_directory at runtime even
-// though the published Config type narrows it to a single rule value.
-type ExternalDirectoryRules = Record<string, "allow" | "ask" | "deny" | undefined>;
-type ConfigHook = NonNullable<Hooks["config"]>;
-type SkillConfig = { skills?: { paths?: string[] } };
-
-function companionPathRules(companionPath: string): string[] {
-  return [companionPath, `${companionPath}/**`];
-}
+type CompanionSkill = {
+  id: string;
+  name: string;
+  description?: string;
+  path: string;
+  content: string;
+};
 
 function companionSkillPaths(companionPath: string): string[] {
   return [
@@ -20,50 +18,101 @@ function companionSkillPaths(companionPath: string): string[] {
   ];
 }
 
-function externalDirectoryRules(config: Config): ExternalDirectoryRules {
-  const permission = (config.permission ??= {}) as { external_directory?: unknown };
-  permission.external_directory ??= {};
-  return permission.external_directory as ExternalDirectoryRules;
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function skillPaths(config: Config): string[] {
-  const skillConfig = config as Config & SkillConfig;
-  skillConfig.skills ??= {};
-  skillConfig.skills.paths ??= [];
-  return skillConfig.skills.paths;
+function parseFrontmatter(content: string): { name?: string; description?: string } {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return {};
+
+  const scalar = (key: string) => {
+    const value = match[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim();
+    return value?.replace(
+      /^(?:"([\s\S]*)"|'([\s\S]*)')$/,
+      (_all, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted,
+    );
+  };
+
+  return { name: scalar("name"), description: scalar("description") };
 }
 
-/**
- * Resolves through the composed reader — launch environment first, Projection
- * Root second — so a wrapped Working Repository allow-lists its companion in a
- * session Mate did not start. No variable name is spelled here.
- */
-export const AddDirPlugin: Plugin = async () => {
-  const companionPath = readCompanionRuntimeContext().companionPath.trim();
-  if (!companionPath) {
-    return {};
+async function findSkillFiles(directory: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const files = entries
+      .filter((entry) => entry.isFile() && entry.name === "SKILL.md")
+      .map((entry) => path.join(directory, entry.name));
+    const nested = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => findSkillFiles(path.join(directory, entry.name))),
+    );
+    return [...files, ...nested.flat()];
+  } catch {
+    return [];
   }
+}
 
-  const resolvedCompanionPath = path.resolve(companionPath);
-
-  return {
-    config: (async (cfg) => {
-      const externalDirectory = externalDirectoryRules(cfg);
+function skillID(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "mate-skill"
+  );
+}
 
-      for (const rule of companionPathRules(resolvedCompanionPath)) {
-        if (externalDirectory[rule] === undefined) {
-          externalDirectory[rule] = "allow";
-        }
+async function loadCompanionSkills(companionPath: string): Promise<CompanionSkill[]> {
+  const files = (await Promise.all(companionSkillPaths(companionPath).map(findSkillFiles))).flat();
+  const skills = await Promise.all(
+    files.map(async (filePath): Promise<CompanionSkill | null> => {
+      try {
+        const content = await fs.readFile(filePath, "utf8");
+        const metadata = parseFrontmatter(content);
+        const name = metadata.name || path.basename(path.dirname(filePath));
+        return {
+          id: skillID(name),
+          name,
+          ...(metadata.description ? { description: metadata.description } : {}),
+          path: filePath,
+          content,
+        };
+      } catch {
+        /** An unreadable companion skill must not prevent the session from loading. */
+        return null;
       }
+    }),
+  );
+  return skills.filter((skill) => skill !== null);
+}
 
-      const paths = skillPaths(cfg);
-      for (const skillPath of companionSkillPaths(resolvedCompanionPath)) {
-        if (!paths.includes(skillPath)) {
-          paths.push(skillPath);
-        }
-      }
-    }) satisfies ConfigHook,
-  };
-};
+/**
+ * Grants the session access to the companion and registers its skills. The
+ * permission hook only widens access for companion resources; every other
+ * evaluation keeps OpenCode's own verdict.
+ */
+export async function registerCompanionAccess(api: Context, companionPath: string): Promise<void> {
+  const permissionRoot = path.resolve(companionPath);
+
+  await api.permission.hook("evaluate", (event) => {
+    if (event.resources.some((resource) => isWithin(permissionRoot, resource))) {
+      event.effect = "allow";
+      delete event.message;
+    }
+  });
+
+  const skills = await loadCompanionSkills(permissionRoot);
+  if (skills.length === 0) return;
 
-export default AddDirPlugin;
+  await api.skill.transform((editor) => {
+    for (const skill of skills) {
+      if (editor.get(skill.id)) {
+        editor.update(skill.id, (current) => Object.assign(current, skill));
+      } else {
+        editor.add(skill as never);
+      }
+    }
+  });
+}

package/src/companion.ts

@@ -1,24 +1,23 @@
 import path from "node:path";
 
-import type { Plugin } from "@opencode-ai/plugin";
-import { tool } from "@opencode-ai/plugin";
+import type { Context } from "@opencode/plugin/promise/plugin";
 import {
   COMPANION_POLICY_MARKER,
   MATE_ENV,
   type MateGuidanceFile,
 } from "@uniqbit/mate-core/runtime";
 
-import {
-  readContext,
-  resolveOpenCodeGuidance,
-  type CompanionContext,
-} from "@uniqbit/mate-core/opencode";
+import { resolveOpenCodeGuidance, type CompanionContext } from "@uniqbit/mate-core/opencode";
 
 function prependPathEntry(pathValue: string | undefined, entry: string): string {
   const entries = (pathValue ?? "").split(path.delimiter).filter(Boolean);
   return [entry, ...entries.filter((value) => value !== entry)].join(path.delimiter);
 }
 
+function resolveWrapperBinPath(): string {
+  return process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+}
+
 function buildStartupError(details: string[]): Error {
   return new Error(
     [
@@ -34,14 +33,14 @@ function buildStartupError(details: string[]): Error {
  * an Unmanaged Session in a wrapped repository builds the same payload from the
  * companion the projection names, with the Capability names read live.
  */
-function loadGuidance(): MateGuidanceFile | null {
-  const { guidance, errors } = resolveOpenCodeGuidance();
+function loadGuidance(directory: string): MateGuidanceFile | null {
+  const { guidance, errors } = resolveOpenCodeGuidance(process.env, directory);
   if (errors.length > 0) throw buildStartupError(errors);
   return guidance;
 }
 
 function materializeCompanionGuidance(guidance: string, context: CompanionContext): string {
-  const wrapperBinPath = process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+  const wrapperBinPath = resolveWrapperBinPath();
   return guidance
     .replaceAll("$MATE_REPO_PATH", context.repositoryPath)
     .replaceAll("$MATE_ARTIFACT_PATH", context.companionPath)
@@ -63,95 +62,117 @@ function buildSystemPrompt(context: CompanionContext, guidance: MateGuidanceFile
   return lines;
 }
 
-export const CompanionPlugin: Plugin = async () => {
-  const context = readContext();
-  if (!context.companionPath) {
-    return {};
-  }
-
-  const guidance = loadGuidance();
-  if (!guidance) return {};
+function readSystemText(part: unknown): string {
+  if (typeof part === "string") return part;
+  if (typeof part !== "object" || part === null || !("text" in part)) return "";
+  return typeof part.text === "string" ? part.text : "";
+}
 
-  const wrapperBinPath = process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+/** Session-scoped variables a spawned shell sees; mutates `env` in place. */
+function applyCompanionShellEnv(
+  context: CompanionContext,
+  env: Record<string, string | undefined>,
+): void {
+  const wrapperBinPath = resolveWrapperBinPath();
+  env.MATE_NAME = context.frameworkName;
+  env.MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
+  env.MATE_ARTIFACT_PATH = context.companionPath;
+  env.MATE_WRAPPER_BIN_PATH = wrapperBinPath;
+  if (context.repositoryPath) {
+    env.MATE_REPO_PATH = context.repositoryPath;
+    env.MATE_REPO_ID = context.repositoryId;
+  } else {
+    delete env.MATE_REPO_PATH;
+    delete env.MATE_REPO_ID;
+  }
+  env.MATE_POLICY_JSON = context.policyJson;
+  env.MATE_GRAPHIFY_ENABLED = context.graphifyEnabled ? "1" : "0";
+  env.MATE_GIT_AUTO_MODE = context.gitAutoModeEnabled ? "1" : "0";
+  /**
+   * Session-scoped payload consumed at plugin startup: masked so the multi-KB
+   * guidance JSON never leaks into spawned shells (and a nested `mate` launch
+   * can never inherit a stale copy).
+   */
+  env[MATE_ENV.guidanceJson] = "";
+  env.PATH = prependPathEntry(process.env.PATH, wrapperBinPath);
+}
 
+function companionPathsResult(context: CompanionContext) {
+  const wrapperBinPath = resolveWrapperBinPath();
   return {
-    tool: {
-      companion_paths: tool({
-        description: `Return active ${context.frameworkName} companion framework and working repository paths.`,
-        args: {},
-        async execute() {
-          return {
-            output: JSON.stringify(
-              {
-                companionFrameworkPath: context.companionPath,
-                wrapperBinPath,
-                ...(context.repositoryPath
-                  ? { repositoryPath: context.repositoryPath, repositoryId: context.repositoryId }
-                  : {}),
-                policy: JSON.parse(context.policyJson || "{}"),
-              },
-              null,
-              2,
-            ),
-            metadata: {
-              companionPath: context.companionPath,
-              wrapperBinPath,
-              ...(context.repositoryPath ? { repositoryPath: context.repositoryPath } : {}),
-            },
-          };
-        },
-      }),
-    },
-    "experimental.chat.system.transform": async (_input: any, output: { system: string[] }) => {
-      // A wrapped repository lists this plugin in its own project config, so a
-      // managed launch — whose OPENCODE_CONFIG_DIR names the companion, which
-      // lists it too — loads it twice. The marker is what makes the second load
-      // inert instead of appending the companion block a second time.
-      if (output.system.some((part) => part.includes(COMPANION_POLICY_MARKER))) return;
-
-      // Collapse the whole system prompt into a single entry. opencode expands
-      // each `system[]` element into its own `role:"system"` wire message, and
-      // some self-hosted chat templates (e.g. Qwen served via vLLM) reject any
-      // system message that is not the very first message. Merging opencode's
-      // own parts with the mate companion block guarantees exactly one leading
-      // system message.
-      const companion = buildSystemPrompt(context, guidance).join("\n");
-      const merged = [...output.system, companion]
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0)
-        .join("\n\n");
-      output.system.length = 0;
-      if (merged.length > 0) {
-        output.system.push(merged);
-      }
-    },
-    "experimental.session.compacting": async (_input: any, output: { context: string[] }) => {
-      if (output.context.some((part) => part.includes(COMPANION_POLICY_MARKER))) return;
-      output.context.push(buildSystemPrompt(context, guidance).join("\n"));
-    },
-    "shell.env": async (_input: any, output: { env: Record<string, string> }) => {
-      output.env.MATE_NAME = context.frameworkName;
-      output.env.MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
-      output.env.MATE_ARTIFACT_PATH = context.companionPath;
-      output.env.MATE_WRAPPER_BIN_PATH = wrapperBinPath;
-      if (context.repositoryPath) {
-        output.env.MATE_REPO_PATH = context.repositoryPath;
-        output.env.MATE_REPO_ID = context.repositoryId;
-      } else {
-        delete output.env.MATE_REPO_PATH;
-        delete output.env.MATE_REPO_ID;
-      }
-      output.env.MATE_POLICY_JSON = context.policyJson;
-      output.env.MATE_GRAPHIFY_ENABLED = context.graphifyEnabled ? "1" : "0";
-      output.env.MATE_GIT_AUTO_MODE = context.gitAutoModeEnabled ? "1" : "0";
-      // Session-scoped payload consumed above at plugin startup: mask it so
-      // the multi-KB guidance JSON never leaks into spawned shells (and a
-      // nested `mate` launch can never inherit a stale copy).
-      output.env[MATE_ENV.guidanceJson] = "";
-
-      output.env.PATH = prependPathEntry(process.env.PATH, wrapperBinPath);
+    content: JSON.stringify(
+      {
+        companionFrameworkPath: context.companionPath,
+        wrapperBinPath,
+        ...(context.repositoryPath
+          ? { repositoryPath: context.repositoryPath, repositoryId: context.repositoryId }
+          : {}),
+        policy: JSON.parse(context.policyJson || "{}"),
+      },
+      null,
+      2,
+    ),
+    metadata: {
+      companionPath: context.companionPath,
+      wrapperBinPath,
+      ...(context.repositoryPath ? { repositoryPath: context.repositoryPath } : {}),
     },
   };
-};
+}
+
+/**
+ * Collapses the whole system prompt into a single entry. OpenCode sends each
+ * `system[]` element as its own system message, and some self-hosted chat
+ * templates (e.g. Qwen served via vLLM) reject any system message that is not
+ * the very first one.
+ */
+function mergeCompanionSystem(system: unknown[], companion: string): string[] {
+  const texts = system.map(readSystemText);
+  /**
+   * A wrapped repository lists this plugin in its own project config, so a
+   * managed launch loads it twice; the marker keeps the second load inert.
+   */
+  if (texts.some((text) => text.includes(COMPANION_POLICY_MARKER))) return texts;
+  const merged = [...texts, companion]
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0)
+    .join("\n\n");
+  return merged.length > 0 ? [merged] : [];
+}
 
-export default CompanionPlugin;
+/** Registers guidance, compaction context, shell env, and `companion_paths`. */
+export async function registerCompanion(api: Context, context: CompanionContext): Promise<void> {
+  const guidance = loadGuidance(api.location.directory);
+  if (!guidance) return;
+
+  const companion = buildSystemPrompt(context, guidance).join("\n");
+
+  await api.session.hook("context", (event) => {
+    const merged = mergeCompanionSystem(event.system, companion);
+    event.system.splice(
+      0,
+      event.system.length,
+      ...merged.map((text) => ({ type: "text" as const, text }) as never),
+    );
+  });
+
+  await api.session.hook("compaction", (event) => {
+    if (event.system.some((part) => readSystemText(part).includes(COMPANION_POLICY_MARKER))) return;
+    event.system.push({ type: "text", text: companion } as never);
+  });
+
+  await api.shell.hook("create.before", (event) => {
+    applyCompanionShellEnv(context, event.env);
+  });
+
+  await api.tool.transform((editor) => {
+    editor.add({
+      name: "companion_paths",
+      description: `Return active ${context.frameworkName} companion framework and working repository paths.`,
+      input: { type: "object", properties: {}, additionalProperties: false },
+      async execute() {
+        return companionPathsResult(context);
+      },
+    });
+  });
+}

package/src/server.ts

@@ -1,54 +1,25 @@
-// oxlint-disable no-await-in-loop -- modules must initialize in their fixed execution order
-import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
+import { Plugin } from "@opencode/plugin";
+import { readContext, registerCompanionHooks } from "@uniqbit/mate-core/opencode";
 
-import { AddDirPlugin } from "./add-dir";
-import { CompanionHooksPlugin } from "@uniqbit/mate-core/opencode";
-import { CompanionPlugin } from "./companion";
-
-// Compose the implementation modules in the execution order the previously
-// copied plugin files were discovered in (alphabetical file order:
-// mate-add-dir, mate-companion-hooks, mate-companion).
-const MODULES: Plugin[] = [AddDirPlugin, CompanionHooksPlugin, CompanionPlugin];
-
-type HookValue = Hooks[keyof Hooks];
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function chainHooks(first: HookValue, second: HookValue): HookValue {
-  if (typeof first === "function" && typeof second === "function") {
-    return (async (...args: unknown[]) => {
-      await (first as (...values: unknown[]) => Promise<unknown>)(...args);
-      await (second as (...values: unknown[]) => Promise<unknown>)(...args);
-    }) as HookValue;
-  }
-
-  if (isRecord(first) && isRecord(second)) {
-    return { ...first, ...second } as HookValue;
-  }
-
-  return second;
-}
+import { registerCompanionAccess } from "./add-dir";
+import { registerCompanion } from "./companion";
 
 /**
- * Aggregate regular Mate OpenCode plugin. Loaded through the package's
- * `./server` export; stays inert when the session is not Mate-managed
- * because every composed module checks the Mate launch environment itself.
+ * Mate OpenCode server plugin (OpenCode 2.x). Loaded through the package's
+ * `./server` export; stays inert when no companion resolves from the launch
+ * environment or a Projection Root above the session directory.
  */
-export const MateOpenCodePlugin: Plugin = async (input: PluginInput) => {
-  const merged: Record<string, HookValue> = {};
-
-  for (const module of MODULES) {
-    const hooks = await module(input);
-    for (const [name, value] of Object.entries(hooks) as Array<[string, HookValue]>) {
-      if (value === undefined) continue;
-      const existing = merged[name];
-      merged[name] = existing === undefined ? value : chainHooks(existing, value);
-    }
-  }
-
-  return merged as Hooks;
-};
+export const MateOpenCodePlugin = Plugin.define({
+  id: "mate-opencode-plugin",
+  async setup(api) {
+    const context = readContext(process.env, api.location.directory);
+    if (!context.companionPath) return;
+
+    await registerCompanionAccess(api, context.companionPath);
+    const cleanup = await registerCompanionHooks(api, context);
+    await registerCompanion(api, context);
+    return cleanup;
+  },
+});
 
 export default MateOpenCodePlugin;

package/src/tui.tsx

@@ -1 +1 @@
-export { tuiPlugin as default } from "@uniqbit/mate-core/opencode";
+export { default } from "@uniqbit/mate-core/opencode/tui";

package/tui.tsx

@@ -0,0 +1,2 @@
+/** Root entry for a plugin bound by directory path; see `server.ts`. */
+export { default } from "./src/tui";