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

package/package.json

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

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 {