@uniqbit/mate-core 0.18.0 → 0.18.1-canary.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.0",
+  "version": "0.18.1-canary.0",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/install.ts

@@ -19,7 +19,6 @@ import {
   FrozenInstallError,
   installDeclaredPluginsFrozen,
 } from "../../tools/setup/dynamic-plugins/frozen";
-import { verifyTrackedPluginOutputs } from "../../tools/setup/dynamic-plugins/staging";
 import { verifyDeclaredPlugins } from "../../tools/setup/dynamic-plugins/verify";
 
 export function reportPluginInstallResults(results: PluginInstallResult[]): boolean {
@@ -159,22 +158,7 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
-    if (frozen && plan.context.companionPath) {
-      const { syncCompanionFiles } = await import("../../tools/setup");
-      const drift = await verifyTrackedPluginOutputs(plan.context.companionPath, (staged) =>
-        syncCompanionFiles(staged, plan.context.config),
-      );
-      if (drift.length > 0) {
-        process.stderr.write(
-          `${FRAMEWORK_NAME}: plugin-generated files differ from the committed checkout: ${drift.join(", ")}\n` +
-            `Prepare and commit them in the companion's authoring flow; the checkout was left unchanged.\n`,
-        );
-        process.exitCode = 1;
-        return false;
-      }
-    } else {
-      await reconcileInstalledCompanion(plan);
-    }
+    await reconcileInstalledCompanion(plan);
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(

package/src/cli/commands/plugin/plugin.ts

@@ -11,7 +11,7 @@ export async function runPluginCommand(
       await runPluginInstallCommand(argv);
       return;
     case "verify":
-      await runPluginVerifyCommand();
+      await runPluginVerifyCommand(argv);
       return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);

package/src/cli/commands/plugin/verify.ts

@@ -1,19 +1,22 @@
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveInstallContext } from "../../../lib/install";
-import { verifyDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
+import { inspectDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/verify";
 
 /**
  * @command mate plugin verify
- * @description Strict, installation-free check that every plugin declared by the companion is allowed by `MATE_ALLOWED_PLUGINS`, installed, and loadable with the current environment. Exits non-zero naming each failing package.
+ * @description Strict, installation-free check that every plugin declared by the companion is installed, and loadable with the current environment. Exits non-zero naming each failing package. With `--json`, prints `{"capabilities": [...]}` listing the capability IDs the verified plugins provide.
  */
-export async function runPluginVerifyCommand(cwd = process.cwd()): Promise<boolean> {
+export async function runPluginVerifyCommand(
+  argv: string[] = [],
+  cwd = process.cwd(),
+): Promise<boolean> {
   const context = await resolveInstallContext(cwd);
   if ((context.kind !== "companion" && context.kind !== "hub") || !context.companionPath) {
     process.stderr.write(`${FRAMEWORK_NAME}: \`plugin verify\` requires a companion context.\n`);
     process.exitCode = 1;
     return false;
   }
-  const failures = await verifyDeclaredPlugins(context.companionPath);
+  const { failures, capabilities } = await inspectDeclaredPlugins(context.companionPath);
   for (const failure of failures) {
     process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
@@ -21,5 +24,6 @@ export async function runPluginVerifyCommand(cwd = process.cwd()): Promise<boole
     process.exitCode = 1;
     return false;
   }
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ capabilities })}\n`);
   return true;
 }

package/src/cli/commands/studio/terminal-launch.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
@@ -26,11 +27,56 @@ export async function launchableAgents(
   return TERMINAL_AGENTS.filter((agent) => allowed.includes(agent) && installed(agent));
 }
 
+/** Lowercase letters, digits and hyphens, so a name can never carry shell syntax or a flag. */
+export const AGENT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+const AGENT_DEFINITION_DIRS: Record<TerminalAgent, string> = {
+  claude: path.join(".claude", "agents"),
+  opencode: path.join(".opencode", "agents"),
+};
+
+export interface DefaultAgentOutcome {
+  agentArgs?: string[];
+  notice?: string;
+}
+
+/**
+ * The companion's `studio.terminal.agent` for one provider. Never throws and
+ * never echoes the configured value into the notice.
+ */
+export async function defaultAgentFor(
+  companionPath: string,
+  agent: TerminalAgent,
+): Promise<DefaultAgentOutcome> {
+  const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+  if (!fs.existsSync(configPath)) return {};
+  let name: unknown;
+  try {
+    name = (await new ConfigStore(configPath).load()).studio?.terminal?.agent;
+  } catch {
+    return {};
+  }
+  if (name === undefined || name === null) return {};
+  if (typeof name !== "string" || !AGENT_NAME_PATTERN.test(name)) {
+    return {
+      notice: "Default agent not applied: studio.terminal.agent is not a valid agent name.",
+    };
+  }
+  const definition = path.join(companionPath, AGENT_DEFINITION_DIRS[agent], `${name}.md`);
+  if (!fs.existsSync(definition)) {
+    return {
+      notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
+    };
+  }
+  return { agentArgs: ["--agent", name] };
+}
+
 export interface LaunchResolverOptions {
   collectInventory: () => Promise<StudioInventory>;
   /** Pinned by `serve --companion`; overrides the page selection. */
   launchCompanion?: string | null;
   launchableAgents?: (companionPath: string) => Promise<TerminalAgent[]>;
+  defaultAgent?: (companionPath: string, agent: TerminalAgent) => Promise<DefaultAgentOutcome>;
 }
 
 /** The companion a launch targets: the pinned one, else the page's, both read from the current inventory. */
@@ -50,6 +96,7 @@ export function createLaunchResolver(
   options: LaunchResolverOptions,
 ): (agent: string, digest: string | null) => Promise<TerminalLaunchResolution> {
   const agents = options.launchableAgents ?? launchableAgents;
+  const defaultAgent = options.defaultAgent ?? defaultAgentFor;
   return async (agent, digest) => {
     const companion = await effectiveLaunchCompanion(
       await options.collectInventory(),
@@ -66,6 +113,9 @@ export function createLaunchResolver(
     if (!(await agents(companion.path)).includes(agent as TerminalAgent)) {
       return { reason: `${agent} is not allowed by this companion or is not installed` };
     }
-    return { companionPath: companion.path };
+    return {
+      companionPath: companion.path,
+      ...(await defaultAgent(companion.path, agent as TerminalAgent)),
+    };
   };
 }

package/src/cli/commands/studio/terminal.ts

@@ -177,7 +177,15 @@ export interface TerminalSessionInfo {
   startedAt: number;
 }
 
-export type TerminalLaunchResolution = { companionPath: string } | { reason: string };
+export type TerminalLaunchResolution =
+  | {
+      companionPath: string;
+      /** Extra argv entries for the managed launch; set only by companion configuration. */
+      agentArgs?: string[];
+      /** Written to the terminal before the agent starts. */
+      notice?: string;
+    }
+  | { reason: string };
 
 export interface TerminalRegistryOptions {
   detachMs: number;
@@ -388,7 +396,7 @@ export class TerminalRegistry {
       void this.finish(detached, { type: "ended", reason: "evicted" });
     }
 
-    const session = this.launch(agent, resolved.companionPath, size);
+    const session = this.launch(agent, resolved.companionPath, size, resolved);
     this.attachTo(connection, session, size);
   }
 
@@ -396,6 +404,7 @@ export class TerminalRegistry {
     agent: TerminalAgent,
     companionPath: string,
     size: { cols: number; rows: number },
+    extras: { agentArgs?: string[]; notice?: string } = {},
   ): Session {
     const env: Record<string, string> = {};
     for (const [key, value] of Object.entries(this.options.env ?? process.env)) {
@@ -413,6 +422,7 @@ export class TerminalRegistry {
       "--companion",
       "--yes",
       ...(this.options.noGit ? ["--no-git"] : []),
+      ...(extras.agentArgs ?? []),
     ];
 
     const session = {
@@ -427,6 +437,7 @@ export class TerminalRegistry {
       ending: null,
       exited: false,
     } as Omit<Session, "process"> as Session;
+    if (extras.notice) session.ring.push(new TextEncoder().encode(`${extras.notice}\r\n`));
     session.process = this.spawn({
       argv,
       cwd: companionPath,

package/src/lib/orchestrator/types.ts

@@ -120,6 +120,11 @@ export interface PluginDeclaration {
   config?: unknown;
 }
 
+export interface StudioTerminalConfig {
+  /** Persona selected with `--agent` when Studio's terminal starts a provider. */
+  agent?: string;
+}
+
 export interface FrameworkConfig {
   type?: FrameworkType;
   git?: GitModeProfile;
@@ -131,6 +136,7 @@ export interface FrameworkConfig {
   cliTools?: CliToolConfig[];
   packageManagers?: string[];
   engines?: EngineConstraints;
+  studio?: { terminal?: StudioTerminalConfig };
 }
 
 export interface CompanionRegistryConfig {

package/src/tools/setup/dynamic-plugins/frozen.ts

@@ -5,14 +5,8 @@ import path from "node:path";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { NpmInstallRunner, PluginInstallResult } from "./install";
 import { dynamicPluginsWorkspaceRoot } from "./paths";
-import {
-  disallowedPluginMessage,
-  isPluginAllowed,
-  PluginPolicyError,
-  readPluginPolicy,
-} from "./policy";
-
-/** Raised before anything is installed: policy, manifest or lockfile inputs are unusable. */
+
+/** Raised before anything is installed: manifest or lockfile inputs are unusable. */
 export class FrozenInstallError extends Error {}
 
 export interface FrozenInstallDeps {
@@ -112,8 +106,7 @@ async function treeMismatches(workspaceRoot: string, lock: Lockfile): Promise<st
 
 /**
  * Deployment restore: installs exactly what the committed lockfile records.
- * Inputs are validated before npm runs — the appliance allowlist, the
- * workspace manifest against the declarations, and the lockfile against the
+ * Inputs are validated before npm runs — the workspace manifest against the declarations, and the lockfile against the
  * manifest — and neither tracked file is ever rewritten. An installed tree is
  * reused only when it matches the lockfile's versions and integrity.
  */
@@ -127,20 +120,6 @@ export async function installDeclaredPluginsFrozen(
   const desired: Record<string, string> = {};
   for (const declaration of sorted) desired[declaration.package] = declaration.version;
 
-  let policy: ReturnType<typeof readPluginPolicy>;
-  try {
-    policy = readPluginPolicy(deps.env ?? process.env);
-  } catch (error) {
-    if (error instanceof PluginPolicyError) throw new FrozenInstallError(error.message);
-    throw error;
-  }
-  const refused = sorted.filter((declaration) => !isPluginAllowed(policy, declaration.package));
-  if (refused.length > 0) {
-    throw new FrozenInstallError(
-      refused.map((declaration) => disallowedPluginMessage(declaration.package)).join("\n"),
-    );
-  }
-
   const manifestFile = path.join(workspaceRoot, "package.json");
   const lockFile = path.join(workspaceRoot, "package-lock.json");
   const [manifestText, lockText] = await Promise.all([readText(manifestFile), readText(lockFile)]);

package/src/tools/setup/dynamic-plugins/loader.ts

@@ -14,12 +14,6 @@ import {
   type PluginHost,
 } from "./host";
 import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
-import {
-  disallowedPluginMessage,
-  isPluginAllowed,
-  PluginPolicyError,
-  readPluginPolicy,
-} from "./policy";
 
 interface PluginManifest {
   mate?: { pluginApiVersion?: unknown };
@@ -53,16 +47,6 @@ export async function loadDynamicPlugin(
   const name = declaration.package;
   const packageRoot = pluginPackageRoot(companionPath, name);
 
-  /** Fails closed: a malformed policy allows nothing. Checked before any plugin file is touched. */
-  try {
-    if (!isPluginAllowed(readPluginPolicy(deps.env ?? process.env), name)) {
-      return { ok: false, warning: `${disallowedPluginMessage(name)}; not loaded.` };
-    }
-  } catch (error) {
-    if (!(error instanceof PluginPolicyError)) throw error;
-    return { ok: false, warning: `plugin "${name}" not loaded: ${error.message}` };
-  }
-
   let manifest: PluginManifest;
   try {
     manifest = JSON.parse(

package/src/tools/setup/dynamic-plugins/verify.ts

@@ -5,38 +5,37 @@ import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import { readDeclarations, validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 import { pluginPackageRoot } from "./paths";
-import {
-  disallowedPluginMessage,
-  isPluginAllowed,
-  PluginPolicyError,
-  readPluginPolicy,
-} from "./policy";
 
 export interface PluginVerificationFailure {
   package: string;
   reason: string;
 }
 
+export interface PluginInspection {
+  failures: PluginVerificationFailure[];
+  /** IDs of the capabilities the loaded plugins provide. */
+  capabilities: string[];
+}
+
 /**
- * Strict, installation-free check of every declared plugin: allowed, installed
+ * Strict, installation-free check of every declared plugin: installed
  * and loadable with the effective environment. Unlike hydration it fails
- * closed on the first-class problems ordinary commands only warn about. Only
- * allowlisted packages are imported.
+ * closed on the first-class problems ordinary commands only warn about.
  */
 export async function verifyDeclaredPlugins(
   companionPath: string,
   deps: DynamicPluginLoadDeps = {},
 ): Promise<PluginVerificationFailure[]> {
+  return (await inspectDeclaredPlugins(companionPath, deps)).failures;
+}
+
+export async function inspectDeclaredPlugins(
+  companionPath: string,
+  deps: DynamicPluginLoadDeps = {},
+): Promise<PluginInspection> {
   const env = deps.env ?? process.env;
   const failures: PluginVerificationFailure[] = [];
-  let policy: ReturnType<typeof readPluginPolicy>;
-  try {
-    policy = readPluginPolicy(env);
-  } catch (error) {
-    if (!(error instanceof PluginPolicyError)) throw error;
-    return [{ package: "(allowlist)", reason: error.message }];
-  }
-
+  const capabilities: string[] = [];
   const declarations: PluginDeclaration[] = [];
   for (const entry of await readDeclarations(companionPath)) {
     const { declaration, error } = validateDeclaration(entry);
@@ -46,10 +45,6 @@ export async function verifyDeclaredPlugins(
 
   for (const declaration of declarations) {
     const name = declaration.package;
-    if (!isPluginAllowed(policy, name)) {
-      failures.push({ package: name, reason: disallowedPluginMessage(name) });
-      continue;
-    }
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const installed = await fs
       .access(pluginPackageRoot(companionPath, name))
@@ -65,6 +60,7 @@ export async function verifyDeclaredPlugins(
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const result = await loadDynamicPlugin(companionPath, declaration, { ...deps, env });
     if (!result.ok) failures.push({ package: name, reason: result.warning });
+    else if (result.plugin.kind === "capability") capabilities.push(result.plugin.id);
   }
-  return failures;
+  return { failures, capabilities };
 }

package/src/tools/setup/dynamic-plugins/policy.ts

@@ -1,55 +0,0 @@
-/** Environment variable carrying the appliance's declared-plugin package allowlist. */
-export const ALLOWED_PLUGINS_ENV = "MATE_ALLOWED_PLUGINS";
-
-/**
- * Parsed allowlist: exact package names and scope-wide `@scope/*` patterns.
- * An empty list permits no package; the policy's absence permits all.
- */
-export interface PluginPolicy {
-  exact: string[];
-  scopes: string[];
-}
-
-export class PluginPolicyError extends Error {}
-
-const EXACT_PATTERN = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
-const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9._~-]*\/\*$/;
-
-/**
- * Parses a comma-separated allowlist. `undefined` means no policy; an empty
- * or blank string is an explicit empty policy. Malformed entries throw so a
- * typo can never widen or silently narrow the trust decision.
- */
-export function parseAllowedPlugins(raw: string | undefined): PluginPolicy | null {
-  if (raw === undefined) return null;
-  const policy: PluginPolicy = { exact: [], scopes: [] };
-  if (raw.trim() === "") return policy;
-  for (const part of raw.split(",")) {
-    const entry = part.trim();
-    if (SCOPE_PATTERN.test(entry)) policy.scopes.push(entry.slice(0, entry.indexOf("/") + 1));
-    else if (EXACT_PATTERN.test(entry)) policy.exact.push(entry);
-    else {
-      throw new PluginPolicyError(
-        `${ALLOWED_PLUGINS_ENV}: malformed entry ${JSON.stringify(entry)}; expected an exact package name or a scope pattern such as "@acme/*"`,
-      );
-    }
-  }
-  return policy;
-}
-
-/** Reads the effective policy from an environment; throws on a malformed value. */
-export function readPluginPolicy(
-  env: Record<string, string | undefined> = process.env,
-): PluginPolicy | null {
-  return parseAllowedPlugins(env[ALLOWED_PLUGINS_ENV]);
-}
-
-export function isPluginAllowed(policy: PluginPolicy | null, packageName: string): boolean {
-  if (policy === null) return true;
-  if (policy.exact.includes(packageName)) return true;
-  return policy.scopes.some((scope) => packageName.startsWith(scope));
-}
-
-export function disallowedPluginMessage(packageName: string): string {
-  return `plugin "${packageName}" is not allowed by ${ALLOWED_PLUGINS_ENV}`;
-}

package/src/tools/setup/dynamic-plugins/staging.ts

@@ -1,53 +0,0 @@
-import { spawnSync } from "node:child_process";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-export class TrackedOutputError extends Error {}
-
-export type StagedProjection = (stagingPath: string) => Promise<void>;
-
-function git(cwd: string, args: string[]): string {
-  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
-  if (result.error || result.status !== 0) {
-    throw new TrackedOutputError(
-      `git ${args[0]} failed in ${cwd}: ${result.error?.message ?? result.stderr?.trim() ?? result.status}`,
-    );
-  }
-  return result.stdout;
-}
-
-function changedPaths(cwd: string): string[] {
-  return git(cwd, ["status", "--porcelain", "--untracked-files=all"])
-    .split("\n")
-    .filter((line) => line.trim() !== "")
-    .map((line) => line.slice(3));
-}
-
-/**
- * Checks that what plugins would generate is already committed. The live
- * checkout must have no edits of its own; the projection then runs against a
- * disposable clone of its commit, and any file that differs afterwards is
- * drift. Nothing is written back to the live checkout. Returns the drifting
- * paths (empty when the checkout is complete).
- */
-export async function verifyTrackedPluginOutputs(
-  companionPath: string,
-  project: StagedProjection,
-): Promise<string[]> {
-  const pending = changedPaths(companionPath);
-  if (pending.length > 0) {
-    throw new TrackedOutputError(
-      `the checkout has uncommitted changes, which frozen setup will not overwrite: ${pending.join(", ")}`,
-    );
-  }
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "mate-staging-"));
-  try {
-    const staged = path.join(root, "companion");
-    git(root, ["clone", "--quiet", "--no-hardlinks", companionPath, staged]);
-    await project(staged);
-    return changedPaths(staged);
-  } finally {
-    await fs.rm(root, { recursive: true, force: true });
-  }
-}