@uniqbit/mate-core 0.17.1 → 0.17.2-canary.1

package/package.json

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

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 allowed by `MATE_ALLOWED_PLUGINS`, 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/verify.ts

@@ -17,6 +17,12 @@ export interface PluginVerificationFailure {
   reason: string;
 }
 
+export interface PluginInspection {
+  failures: PluginVerificationFailure[];
+  /** IDs of the capabilities the loaded, allowlisted plugins provide. */
+  capabilities: string[];
+}
+
 /**
  * Strict, installation-free check of every declared plugin: allowed, installed
  * and loadable with the effective environment. Unlike hydration it fails
@@ -27,14 +33,22 @@ 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[] = [];
+  const capabilities: string[] = [];
   let policy: ReturnType<typeof readPluginPolicy>;
   try {
     policy = readPluginPolicy(env);
   } catch (error) {
     if (!(error instanceof PluginPolicyError)) throw error;
-    return [{ package: "(allowlist)", reason: error.message }];
+    return { failures: [{ package: "(allowlist)", reason: error.message }], capabilities };
   }
 
   const declarations: PluginDeclaration[] = [];
@@ -65,6 +79,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 };
 }