@uniqbit/mate-opencode-plugin 0.15.0-canary.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@uniqbit/mate-opencode-plugin",
+  "version": "0.15.0-canary.0",
+  "description": "Mate OpenCode runtime plugins: aggregate regular plugin (./server) and TUI plugin (./tui).",
+  "license": "MIT",
+  "files": [
+    "src/",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    "./server": "./src/server.ts",
+    "./tui": "./src/tui.tsx"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "CI=1 bun test",
+    "lint": "oxlint src/",
+    "lint:fix": "oxlint src/ --fix",
+    "format": "oxfmt src/",
+    "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.15.0-canary.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/src/add-dir.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+
+import type { Config, Hooks, Plugin } from "@opencode-ai/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"]>;
+
+function companionPathRules(companionPath: string): string[] {
+  return [companionPath, `${companionPath}/**`];
+}
+
+function externalDirectoryRules(config: Config): ExternalDirectoryRules {
+  const permission = (config.permission ??= {}) as { external_directory?: unknown };
+  permission.external_directory ??= {};
+  return permission.external_directory as ExternalDirectoryRules;
+}
+
+export const AddDirPlugin: Plugin = async () => {
+  const companionPath = process.env.MATE_ARTIFACT_PATH?.trim();
+  if (!companionPath) {
+    return {};
+  }
+
+  const resolvedCompanionPath = path.resolve(companionPath);
+
+  return {
+    config: (async (cfg) => {
+      const externalDirectory = externalDirectoryRules(cfg);
+
+      for (const rule of companionPathRules(resolvedCompanionPath)) {
+        if (externalDirectory[rule] === undefined) {
+          externalDirectory[rule] = "allow";
+        }
+      }
+    }) satisfies ConfigHook,
+  };
+};
+
+export default AddDirPlugin;

package/src/companion-hooks.ts

@@ -0,0 +1,370 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
+
+import {
+  buildArtifactError,
+  extractPatchPaths,
+  readContext,
+  shouldBlockArtifactWrite,
+  type CompanionContext,
+} from "./companion-policy";
+
+const ARCHIVE_ENTRY_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
+const ARCHIVE_PATH_PATTERN =
+  /(?:^|[\s/"'`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^/\s"'`,)]+)/;
+
+function readArchiveEntries(archiveDir: string): Set<string> {
+  try {
+    return new Set(
+      fs
+        .readdirSync(archiveDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && ARCHIVE_ENTRY_PATTERN.test(entry.name))
+        .map((entry) => entry.name),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function shellSplit(command: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | null = null;
+  let escaping = false;
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      const next = command[index + 1] ?? "";
+      if (/^[\\\s'"]$/.test(next)) {
+        escaping = true;
+        continue;
+      }
+      current += char;
+      continue;
+    }
+    if ((char === "'" || char === '"') && !quote) {
+      quote = char;
+      continue;
+    }
+    if (quote === char) {
+      quote = null;
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current) parts.push(current);
+  return parts;
+}
+
+function extractArchivedChangeFromPath(value: string): string | null {
+  const normalized = value.replace(/\\/g, "/");
+  const match = normalized.match(ARCHIVE_PATH_PATTERN);
+  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
+}
+
+function extractArchiveCommandChange(command: string): string | null {
+  const parts = shellSplit(command);
+  const archiveIndex = parts.findIndex(
+    (part, index) =>
+      part === "archive" &&
+      index > 0 &&
+      (parts[index - 1] === "openspec" || parts[index - 1].endsWith("/openspec")),
+  );
+  if (archiveIndex < 0) return null;
+
+  for (let index = archiveIndex + 1; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (!part || part === "--") continue;
+    if (part.startsWith("-")) {
+      if (part === "--store") index += 1;
+      continue;
+    }
+    return part;
+  }
+  return null;
+}
+
+function extractMoveArchiveChange(commandText: string): string | null {
+  const parts = shellSplit(commandText);
+  const moveCommands = new Set([
+    "mv",
+    "move",
+    "move-item",
+    "cmd",
+    "cmd.exe",
+    "powershell",
+    "powershell.exe",
+    "pwsh",
+    "pwsh.exe",
+  ]);
+  const isPython = (part: string) =>
+    /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() ?? part);
+
+  for (let index = 0; index < parts.length; index += 1) {
+    const command = parts[index].toLowerCase();
+    if (moveCommands.has(command)) {
+      for (const part of parts.slice(index + 1)) {
+        const change = extractArchivedChangeFromPath(part);
+        if (change) return change;
+      }
+    }
+    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(commandText)) {
+      return extractArchivedChangeFromPath(commandText);
+    }
+  }
+  return null;
+}
+
+function collectCommands(value: unknown): string[] {
+  if (!value || typeof value !== "object") return [];
+  const record = value as Record<string, unknown>;
+  const commands: string[] = [];
+  if (typeof record.command === "string") commands.push(record.command);
+  for (const key of ["args", "tool_input"] as const) {
+    const nested = record[key];
+    if (nested && typeof nested === "object") {
+      const command = (nested as Record<string, unknown>).command;
+      if (typeof command === "string") commands.push(command);
+    }
+  }
+  return commands;
+}
+
+function commandSucceeded(value: unknown): boolean {
+  if (!value || typeof value !== "object") return true;
+  const record = value as Record<string, unknown>;
+  const candidates = [
+    record,
+    record.result,
+    record.output,
+    record.tool_output,
+    record.tool_response,
+  ];
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== "object") continue;
+    const result = candidate as Record<string, unknown>;
+    if (typeof result.success === "boolean") return result.success;
+    for (const key of ["exitCode", "exit_code", "status", "statusCode", "status_code"] as const) {
+      const status = result[key];
+      if (typeof status === "number") return status === 0;
+      if (typeof status === "string" && status.trim()) return Number(status) === 0;
+    }
+  }
+  return true;
+}
+
+function detectCommandArchive(input: unknown, output: unknown): string | null {
+  if (!commandSucceeded(input) || !commandSucceeded(output)) return null;
+  for (const command of [...collectCommands(input), ...collectCommands(output)]) {
+    const change = extractArchiveCommandChange(command) ?? extractMoveArchiveChange(command);
+    if (change) return change;
+  }
+  return null;
+}
+
+function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
+  const current = readArchiveEntries(archiveDir);
+  const newlyArchived = [...current].filter((entry) => !snapshot.has(entry)).toSorted();
+  snapshot.clear();
+  for (const entry of current) snapshot.add(entry);
+  return newlyArchived;
+}
+
+function appendOpenSpecFinishNudge(
+  context: CompanionContext,
+  archiveSnapshot: Set<string>,
+  nudgedCommandChanges: Set<string>,
+  input: { tool?: unknown },
+  output: { output?: string },
+): void {
+  if (!context.gitAutoModeEnabled) return;
+
+  const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
+  const changes = detectNewlyArchivedChanges(archiveDir, archiveSnapshot).map((entry) =>
+    entry.slice("YYYY-MM-DD-".length),
+  );
+  const commandChange =
+    String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
+  if (commandChange && !nudgedCommandChanges.has(commandChange)) {
+    changes.push(commandChange);
+    nudgedCommandChanges.add(commandChange);
+  }
+
+  const uniqueChanges = changes.filter((change, index) => changes.indexOf(change) === index);
+  if (uniqueChanges.length === 0) return;
+  const nudges = uniqueChanges.map(
+    (change) =>
+      `ACTION REQUIRED: An openspec change (${change}) was just archived. ` +
+      `Immediately invoke the mate-openspec-artifact-finish skill to complete the finish pipeline ` +
+      "(invoke the CLI as `mate`, never through a companion-local wrapper path or as `" +
+      "$MATE_COMPANION_BIN_PATH/mate`). " +
+      "`mate artifact finish` resumes from the already-archived change and completes the commit, dated tag, and push itself — " +
+      "do not hand-commit, do not hand-tag, and do not re-apply delta specs manually. " +
+      `Follow the skill's guardrails, completing the non-interactive happy path without asking for confirmation.`,
+  );
+  output.output = [output.output, ...nudges]
+    .map((part) => (part ?? "").trim())
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+const REACT_DOCTOR_VERSION = "0.8.1";
+
+const REACT_DOCTOR_NON_LINT_FAILURES = [
+  /No React dependency found/i,
+  /Could not resolve config/i,
+  /is not a git repository/i,
+];
+
+const REACT_DOCTOR_EDIT_TOOLS = new Set(["write", "edit", "apply_patch"]);
+const REACT_DOCTOR_ARGS = [
+  "--yes",
+  "--verbose",
+  "--scope",
+  "changed",
+  "--base",
+  "HEAD",
+  "--blocking",
+  "warning",
+  "--no-score",
+  "--max-duration",
+  "30",
+];
+
+async function runReactDoctorScan(
+  context: CompanionContext,
+  client: PluginInput["client"],
+  $: PluginInput["$"],
+  sessionID: string,
+  scansInFlight: Set<string>,
+): Promise<void> {
+  const repo = context.repositoryPath;
+  if (!repo || scansInFlight.has(sessionID)) return;
+  scansInFlight.add(sessionID);
+  try {
+    const localBin = path.join(repo, "node_modules", ".bin", "react-doctor");
+    const mateBin = process.env.MATE_REACT_DOCTOR_BIN_PATH;
+    const doctorBin = mateBin && fs.existsSync(mateBin) ? mateBin : localBin;
+
+    const result = fs.existsSync(doctorBin)
+      ? await $`${doctorBin} ${REACT_DOCTOR_ARGS}`.cwd(repo).nothrow().quiet()
+      : await $`npx --yes ${`react-doctor@${REACT_DOCTOR_VERSION}`} ${REACT_DOCTOR_ARGS}`
+          .cwd(repo)
+          .nothrow()
+          .quiet();
+
+    if (result.exitCode === 0) return;
+
+    const output = `${result.stdout?.toString() ?? ""}${result.stderr?.toString() ?? ""}`.trim();
+    if (!output || REACT_DOCTOR_NON_LINT_FAILURES.some((re) => re.test(output))) return;
+
+    await client.tui
+      .showToast({
+        query: { directory: repo },
+        body: {
+          title: "React Doctor",
+          message: "Found issues in the changed files — review before finishing.",
+          variant: "warning",
+        },
+      })
+      .catch(() => {});
+    await client.session
+      .promptAsync({
+        path: { id: sessionID },
+        query: { directory: repo },
+        body: {
+          parts: [
+            {
+              type: "text",
+              synthetic: true,
+              text:
+                "React Doctor found issues in the changed files. Review this output and fix " +
+                "the regressions before finishing. For confirmed issues that cannot be fixed " +
+                "now, create GitHub issues with the rule, file/line, confidence, impact, and " +
+                `proposed fix.\n\n${output}`,
+            },
+          ],
+        },
+      })
+      .catch(() => {});
+  } catch {
+    // Never break the session because a diagnostic scan failed.
+  } finally {
+    scansInFlight.delete(sessionID);
+  }
+}
+
+type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
+type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
+type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
+
+export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
+  const { client, $ } = pluginInput;
+  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  if (!context.companionPath || !context.repositoryPath) return {};
+
+  const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
+  const archiveSnapshot = readArchiveEntries(archiveDir);
+  const nudgedCommandChanges = new Set<string>();
+  const dirtyReactDoctorSessions = new Set<string>();
+  const reactDoctorScansInFlight = new Set<string>();
+
+  return {
+    event: async ({ event }: PluginEventInput) => {
+      if (event.type !== "session.idle") return;
+      const sessionID = event.properties.sessionID;
+      if (
+        !context.reactDoctorEnabled ||
+        reactDoctorScansInFlight.has(sessionID) ||
+        !dirtyReactDoctorSessions.delete(sessionID)
+      ) {
+        return;
+      }
+      await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
+    },
+    "tool.execute.before": async (
+      input: { tool: unknown },
+      output: { args: { filePath?: unknown; patchText?: unknown } | undefined },
+    ) => {
+      const toolName = String(input.tool ?? "");
+      const args = output.args ?? {};
+      if (["write", "edit"].includes(toolName)) {
+        const filePath = String(args.filePath ?? "");
+        if (filePath && shouldBlockArtifactWrite(context, filePath)) {
+          throw new Error(buildArtifactError(context, filePath));
+        }
+      }
+      if (toolName === "apply_patch") {
+        for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
+          if (shouldBlockArtifactWrite(context, filePath)) {
+            throw new Error(buildArtifactError(context, filePath));
+          }
+        }
+      }
+    },
+    "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
+      if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
+        dirtyReactDoctorSessions.add(input.sessionID);
+      }
+      appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
+    },
+  };
+};
+
+export default CompanionHooksPlugin;

package/src/companion-policy.ts

@@ -0,0 +1,177 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { readCompanionRuntimeContext, type CompanionRuntimeContext } from "@uniqbit/mate-core";
+
+export type CompanionContext = CompanionRuntimeContext & {
+  agentsMd: string;
+};
+
+const ARTIFACT_BASENAMES = new Set([
+  "CLAUDE.md",
+  "CONTEXT.md",
+  "design.md",
+  "explore-brief.md",
+  "proposal.md",
+  "spec.md",
+  "tasks.md",
+]);
+const ARTIFACT_SEGMENTS = [
+  "/changes/",
+  "/openspec/",
+  "/specs/",
+  "/docs/adr/",
+  "/docs/adrs/",
+  "/docs/decisions/",
+  "/docs/prd/",
+];
+function normalizedPolicyPath(filePath: string): string {
+  return `/${filePath.replace(/\\/g, "/").replace(/^\/+/, "")}`;
+}
+
+export function isArtifactPath(filePath: string): boolean {
+  const basename = path.basename(filePath);
+  const ext = path.extname(basename).toLowerCase();
+  const normalized = normalizedPolicyPath(filePath);
+
+  if (ARTIFACT_BASENAMES.has(basename)) {
+    return true;
+  }
+
+  if (ARTIFACT_SEGMENTS.some((segment) => normalized.includes(segment))) {
+    return true;
+  }
+
+  if (ext === ".md" && basename !== "README.md") {
+    return true;
+  }
+
+  return false;
+}
+
+export function isProductDocumentationPath(context: CompanionContext, filePath: string): boolean {
+  const normalized = normalizeTargetPath(context, filePath);
+  const relativePath = path.relative(context.repositoryPath, normalized);
+  if (!relativePath || relativePath.startsWith("..")) {
+    return false;
+  }
+
+  const parts = relativePath.split(path.sep);
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    if (part === ".storybook" || part === "storybook") {
+      return true;
+    }
+
+    if (part !== "docs") {
+      continue;
+    }
+
+    const docsRoot = path.join(context.repositoryPath, ...parts.slice(0, index + 1));
+    if (fs.existsSync(path.join(docsRoot, "package.json"))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function normalizeTargetPath(context: CompanionContext, filePath: string): string {
+  if (path.isAbsolute(filePath)) {
+    return path.normalize(filePath);
+  }
+
+  return path.normalize(path.join(context.repositoryPath, filePath));
+}
+
+export function isGitignored(context: CompanionContext, filePath: string): boolean {
+  if (!context.repositoryPath) {
+    return false;
+  }
+
+  const normalized = normalizeTargetPath(context, filePath);
+  if (!normalized.startsWith(path.normalize(context.repositoryPath))) {
+    return false;
+  }
+
+  const relativePath = path.relative(context.repositoryPath, normalized);
+  if (!relativePath || relativePath.startsWith("..")) {
+    return false;
+  }
+
+  const result = spawnSync(
+    "git",
+    ["-C", context.repositoryPath, "check-ignore", "--no-index", "-q", "--", relativePath],
+    {
+      encoding: "utf8",
+      stdio: "ignore",
+    },
+  );
+
+  return result.status === 0;
+}
+
+export function shouldBlockArtifactWrite(context: CompanionContext, filePath: string): boolean {
+  if (!filePath) {
+    return false;
+  }
+
+  if (normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
+    return false;
+  }
+
+  if (isProductDocumentationPath(context, filePath)) {
+    return false;
+  }
+
+  if (!isArtifactPath(filePath)) {
+    return false;
+  }
+
+  return !isGitignored(context, filePath);
+}
+
+const PATCH_FILE_MARKER = /\*\*\* (?:Add|Update|Move to|Delete) File:\s*(.+)$/gm;
+
+export function extractPatchPaths(patchText: string): string[] {
+  const paths: string[] = [];
+  let match;
+  while ((match = PATCH_FILE_MARKER.exec(patchText)) !== null) {
+    const raw = match[1].trim();
+    if (raw) {
+      paths.push(raw);
+    }
+  }
+  return paths;
+}
+
+export function buildArtifactError(context: CompanionContext, filePath: string): string {
+  const rel = path.relative(context.repositoryPath, filePath);
+  const suggested = path.join(context.companionPath, rel);
+
+  return [
+    `${context.frameworkName} guardrail: artifact writes must go to the companion framework path.`,
+    `  target:   ${filePath}`,
+    `  suggested: ${suggested}`,
+    `Rewrite to ${suggested} and retry.`,
+  ].join("\n");
+}
+
+export function readContext(companionPath: string): CompanionContext {
+  const agentsMdPath = path.join(companionPath, "AGENTS.md");
+  let agentsMd = "";
+  try {
+    if (fs.existsSync(agentsMdPath)) {
+      agentsMd = fs.readFileSync(agentsMdPath, "utf8");
+    }
+  } catch {
+    // Ignore read errors; AGENTS.md is optional
+  }
+
+  return {
+    ...readCompanionRuntimeContext(process.env),
+    companionPath,
+    agentsMd,
+  };
+}

package/src/companion.ts

@@ -0,0 +1,141 @@
+import path from "node:path";
+
+import type { Plugin } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { MATE_ENV, parseGuidanceContent, type MateGuidanceFile } from "@uniqbit/mate-core";
+
+import { readContext, type CompanionContext } from "./companion-policy";
+
+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 buildStartupError(details: string[]): Error {
+  return new Error(
+    [
+      "Mate OpenCode companion plugin is incomplete and cannot start.",
+      ...details.map((detail) => `- ${detail}`),
+      "Launch through `mate opencode` so the CLI injects the companion guidance.",
+    ].join("\n"),
+  );
+}
+
+function loadGuidance(): MateGuidanceFile {
+  const raw = process.env[MATE_ENV.guidanceJson];
+  if (!raw || !raw.trim()) {
+    throw buildStartupError([`missing ${MATE_ENV.guidanceJson} in the launch environment`]);
+  }
+
+  const { guidance, errors } = parseGuidanceContent(raw);
+  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";
+  return guidance
+    .replaceAll("$MATE_REPO_PATH", context.repositoryPath)
+    .replaceAll("$MATE_ARTIFACT_PATH", context.companionPath)
+    .replaceAll("$MATE_WRAPPER_BIN_PATH", wrapperBinPath)
+    .replaceAll("$MATE_REPO_ID", context.repositoryId)
+    .replaceAll("$MATE_REPO_PROFILE", context.repositoryProfile);
+}
+
+function buildSystemPrompt(context: CompanionContext, guidance: MateGuidanceFile): string[] {
+  const lines = [materializeCompanionGuidance(guidance.companionGuidance, context)];
+
+  if (guidance.codebaseExplorationGuidance.trim()) {
+    lines.push("", guidance.codebaseExplorationGuidance);
+  }
+
+  if (context.agentsMd.trim()) {
+    lines.push("", `<agents.md>${context.agentsMd.trim()}</agents.md>`);
+  }
+
+  return lines;
+}
+
+export const CompanionPlugin: Plugin = async () => {
+  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  if (!context.companionPath || !context.repositoryPath) {
+    return {};
+  }
+
+  const guidance = loadGuidance();
+
+  const wrapperBinPath = process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+
+  return {
+    tool: {
+      companion_paths: tool({
+        description: `Return active ${context.frameworkName} working repository and companion framework paths.`,
+        args: {},
+        async execute() {
+          return {
+            output: JSON.stringify(
+              {
+                companionFrameworkPath: context.companionPath,
+                wrapperBinPath,
+                repositoryPath: context.repositoryPath,
+                repositoryId: context.repositoryId,
+                repositoryProfile: context.repositoryProfile,
+                policy: JSON.parse(context.policyJson || "{}"),
+              },
+              null,
+              2,
+            ),
+            metadata: {
+              companionPath: context.companionPath,
+              wrapperBinPath,
+              repositoryPath: context.repositoryPath,
+            },
+          };
+        },
+      }),
+    },
+    "experimental.chat.system.transform": async (_input: any, output: { system: string[] }) => {
+      // 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[] }) => {
+      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;
+      output.env.MATE_REPO_PATH = context.repositoryPath;
+      output.env.MATE_REPO_ID = context.repositoryId;
+      output.env.MATE_REPO_PROFILE = context.repositoryProfile;
+      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);
+    },
+  };
+};
+
+export default CompanionPlugin;

package/src/server.ts

@@ -0,0 +1,54 @@
+// oxlint-disable no-await-in-loop -- modules must initialize in their fixed execution order
+import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
+
+import { AddDirPlugin } from "./add-dir";
+import { CompanionHooksPlugin } from "./companion-hooks";
+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;
+}
+
+/**
+ * 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.
+ */
+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 default MateOpenCodePlugin;

package/src/tui.tsx

@@ -0,0 +1,73 @@
+/** @jsxImportSource @opentui/solid */
+/* oxlint-disable react/no-unknown-property, react/react-in-jsx-scope */
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui";
+
+import { readContext } from "./companion-policy";
+
+const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
+const NARROW_TERMINAL_WIDTH = 80;
+const MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
+
+function SessionContext({
+  api,
+  compact = false,
+  sidebar = false,
+}: {
+  api: TuiPluginApi;
+  compact?: boolean;
+  sidebar?: boolean;
+}) {
+  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  const theme = api.theme.current;
+
+  if (compact) {
+    return (
+      <box width="100%" paddingTop={0} flexShrink={0}>
+        <text fg={theme.textMuted}>
+          mate v{MATE_VERSION} | repo: {context.repositoryPath} | mate: {context.companionPath}
+        </text>
+      </box>
+    );
+  }
+
+  return (
+    <box width="100%" maxWidth={75} paddingTop={sidebar ? 0 : 2} paddingBottom={1} flexShrink={0}>
+      <text fg={MIDNIGHT_PURPLE_BRIGHT}>mate v{MATE_VERSION}</text>
+      <text fg={theme.textMuted}>repo: {context.repositoryPath}</text>
+      <text fg={theme.textMuted}>mate: {context.companionPath}</text>
+    </box>
+  );
+}
+
+const tui: TuiPlugin = async (api) => {
+  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  if (!context.companionPath || !context.repositoryPath) {
+    return;
+  }
+
+  api.slots.register({
+    order: 0,
+    slots: {
+      home_bottom() {
+        return <SessionContext api={api} />;
+      },
+      sidebar_content() {
+        return <SessionContext api={api} sidebar />;
+      },
+      app_bottom() {
+        if (api.renderer.width >= NARROW_TERMINAL_WIDTH || api.route.current.name !== "session") {
+          return null;
+        }
+
+        return <SessionContext api={api} compact />;
+      },
+    },
+  });
+};
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "mate-companion-tui",
+  tui,
+};
+
+export default plugin;