@uniqbit/mate-core 0.17.2-canary.0 → 0.17.2-canary.2

package/package.json

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

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

@@ -4,7 +4,7 @@ import { inspectDeclaredPlugins } from "../../../tools/setup/dynamic-plugins/ver
 
 /**
  * @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. With `--json`, prints `{"capabilities": [...]}` listing the capability IDs the verified plugins provide.
+ * @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(
   argv: string[] = [],

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,12 +5,6 @@ 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;
@@ -19,15 +13,14 @@ export interface PluginVerificationFailure {
 
 export interface PluginInspection {
   failures: PluginVerificationFailure[];
-  /** IDs of the capabilities the loaded, allowlisted plugins provide. */
+  /** 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,
@@ -43,14 +36,6 @@ export async function inspectDeclaredPlugins(
   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 { failures: [{ package: "(allowlist)", reason: error.message }], capabilities };
-  }
-
   const declarations: PluginDeclaration[] = [];
   for (const entry of await readDeclarations(companionPath)) {
     const { declaration, error } = validateDeclaration(entry);
@@ -60,10 +45,6 @@ export async function inspectDeclaredPlugins(
 
   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))

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}`;
-}