mu-harness 0.17.1 → 0.17.3

package/esm/agents/index.d.ts

@@ -2,3 +2,4 @@ export type { Agent, GrantValue, ToolDecision, ToolGrants } from './types.js';
 export { type AgentRegistry, createAgentRegistry, grantArg, toolDecision, toolNames } from './registry.js';
 export { parseAgent } from './parser.js';
 export { loadAgents } from './loader.js';
+export { createAgentWriterTool } from './writer.js';

package/esm/agents/index.js

@@ -1,3 +1,4 @@
 export { createAgentRegistry, grantArg, toolDecision, toolNames } from './registry.js';
 export { parseAgent } from './parser.js';
 export { loadAgents } from './loader.js';
+export { createAgentWriterTool } from './writer.js';

package/esm/agents/registry.d.ts

@@ -2,6 +2,13 @@ import type { Agent, ToolDecision } from './types.js';
 export interface AgentRegistry {
     list(): Agent[];
     get(name: string): Agent | undefined;
+    /**
+     * Register (or replace) an agent at runtime — mirrors {@link SkillRegistry.add}.
+     * Lets tools like `create_agent` make a freshly-authored agent immediately
+     * delegatable without a restart. Agents that `extends` the added one are
+     * re-resolved so they pick up the change.
+     */
+    add(agent: Agent): void;
 }
 export declare const grantArg: (tool: string, input: unknown) => string | undefined;
 export declare const toolDecision: (agent: Agent, tool: string, arg?: string) => ToolDecision;

package/esm/agents/registry.js

@@ -84,5 +84,12 @@ export const createAgentRegistry = (agents = []) => {
     return {
         list: () => [...byName.values()],
         get: (name) => byName.get(name),
+        add: (agent) => {
+            raw.set(agent.name, agent);
+            byName.set(agent.name, resolve(agent.name, new Set()));
+            for (const [name, a] of raw)
+                if (a.extends === agent.name)
+                    byName.set(name, resolve(name, new Set()));
+        },
     };
 };

package/esm/agents/writer.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from 'mu-core';
+import type { Scope } from '../common/index.js';
+import type { AgentRegistry } from './registry.js';
+/**
+ * `create_agent` — authors a reusable agent definition (`.md` with frontmatter)
+ * and registers it live via {@link AgentRegistry.add}, so it can be delegated to
+ * through `subagent` without a restart. Mirrors {@link createSkillWriterTool}:
+ * the `scope` selects the save location, or a configured `forceScope` pins it.
+ */
+export declare const createAgentWriterTool: (deps: {
+    dirs: Record<Scope, string>;
+    registry: AgentRegistry;
+    forceScope?: Scope;
+}) => Tool;

package/esm/agents/writer.js

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify as stringifyYaml } from '../deps/jsr.io/@std/yaml/1.1.0/mod.js';
+import { parseAgent } from './parser.js';
+const slug = (name) => name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+/**
+ * `create_agent` — authors a reusable agent definition (`.md` with frontmatter)
+ * and registers it live via {@link AgentRegistry.add}, so it can be delegated to
+ * through `subagent` without a restart. Mirrors {@link createSkillWriterTool}:
+ * the `scope` selects the save location, or a configured `forceScope` pins it.
+ */
+export const createAgentWriterTool = (deps) => {
+    const { forceScope } = deps;
+    const scopeProp = forceScope ? {} : {
+        scope: {
+            type: 'string',
+            enum: ['local', 'config'],
+            description: 'Where to save it: "local" = this project (repo-first), "config" = global config dir. Defaults to "local".',
+        },
+    };
+    return {
+        name: 'create_agent',
+        description: forceScope
+            ? `Define a reusable agent (name, description, system prompt, optional per-tool grants) that can be delegated to via \`subagent\`. Always saved to the "${forceScope}" agents directory.`
+            : 'Define a reusable agent (name, description, system prompt, optional per-tool grants) that can be delegated to via `subagent`. `scope: "local"` saves it to this project, `scope: "config"` makes it available across all projects.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Short agent name (kebab-case); also the filename.' },
+                description: { type: 'string', description: 'One line describing what this agent is for.' },
+                prompt: { type: 'string', description: 'The system prompt that defines the agent.' },
+                tools: {
+                    type: 'object',
+                    description: 'Optional per-tool grants: map a tool name to "allow" | "ask" | "deny" (or a nested {glob: decision} map). Omitted tools are denied — be explicit about what it may use.',
+                    additionalProperties: true,
+                },
+                model: { type: 'string', description: 'Optional model ref override.' },
+                color: { type: 'string', description: 'Optional hex color for the UI.' },
+                ...scopeProp,
+            },
+            required: ['name', 'description', 'prompt'],
+            additionalProperties: false,
+        },
+        run: async (input) => {
+            const { name, description, prompt, tools, model, color, scope } = (input ?? {});
+            if (!name || !description || !prompt) {
+                return [{ type: 'text', text: 'Error: create_agent requires `name`, `description`, and `prompt`.' }];
+            }
+            // A configured forceScope wins over whatever the model passed.
+            const resolved = forceScope ?? scope ?? 'local';
+            const base = deps.dirs[resolved];
+            if (!base)
+                return [{ type: 'text', text: `Error: unknown scope "${scope}".` }];
+            const id = slug(name);
+            if (!id)
+                return [{ type: 'text', text: `Error: invalid agent name "${name}".` }];
+            if (deps.registry.get(id)) {
+                return [{ type: 'text', text: `Error: an agent named "${id}" already exists.` }];
+            }
+            const file = join(base, `${id}.md`);
+            if (existsSync(file))
+                return [{ type: 'text', text: `Error: ${file} already exists.` }];
+            const frontmatter = { name: id, description };
+            if (model)
+                frontmatter.model = model;
+            if (color)
+                frontmatter.color = color;
+            if (tools && typeof tools === 'object')
+                frontmatter.tools = tools;
+            const source = `---\n${stringifyYaml(frontmatter).trimEnd()}\n---\n\n${prompt.trim()}\n`;
+            await mkdir(base, { recursive: true });
+            await writeFile(file, source, 'utf-8');
+            deps.registry.add(parseAgent(source, id));
+            return [{
+                    type: 'text',
+                    text: `Created agent "${id}" at ${file}. It can now be delegated to via the \`subagent\` tool.`,
+                }];
+        },
+    };
+};

package/esm/common/index.d.ts

@@ -1,2 +1,3 @@
 export { createEmitter, type Emitter, strList } from './utils.js';
 export { type Frontmatter, parseFrontmatter, str } from './frontmatter.js';
+export type { Scope } from './scope.js';

package/esm/common/scope.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where a host saves agent-authored definitions (skills, sub-agents, …):
+ * - `local`  → the current project (repo-first, e.g. `<cwd>/skills`).
+ * - `config` → the global config dir, shared across every project.
+ *
+ * Generic across definition kinds so every writer tool speaks the same vocabulary.
+ */
+export type Scope = 'local' | 'config';

package/esm/common/scope.js

@@ -0,0 +1 @@
+export {};

package/esm/harness/create.js

@@ -1,6 +1,7 @@
+import os from 'node:os';
 import { join } from 'node:path';
 import process from 'node:process';
-import { createAgentRegistry, grantArg, loadAgents, toolDecision, toolNames } from '../agents/index.js';
+import { createAgentRegistry, createAgentWriterTool, grantArg, loadAgents, toolDecision, toolNames } from '../agents/index.js';
 import { createAgentsCommand, createCommandRegistry, createHelpCommand, createSessionsCommand, createSkillsCommand, } from '../commands/index.js';
 import { createHarnessConfig } from '../config/index.js';
 import { mergeHooks } from '../hooks/index.js';
@@ -10,6 +11,7 @@ import { createScheduler, createScheduleTaskTool, createTasksCommand, createTask
 import { createAgentSession, createSessionCatalog, createSessionManager, createSessionStore, persistTo, runTitler, } from '../session/index.js';
 import { createRunSkillTool, createSkillRegistry, createSkillTool, createSkillWriterTool, loadSkills, runSkill, } from '../skills/index.js';
 import { createSubAgentRegistry, createSubAgentTool, runSubAgent } from '../subAgents/index.js';
+import { environmentBlock } from './environment.js';
 import { createModelRegistry } from './models.js';
 const TITLE_AGENT = {
     name: 'title',
@@ -18,17 +20,33 @@ const TITLE_AGENT = {
     tools: [],
 };
 export const createHarness = async (options) => {
-    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], skillScope, title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
+    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], skillScope, agentScope, agentDirs, title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
     const cwd = options.cwd ?? process.cwd();
     const config = createHarnessConfig({ hostName, xdg });
     const models = createModelRegistry({ providers, default: model });
-    const plugins = createPluginStore({ dir: join(config.configDir, 'plugins') });
+    const pluginsDir = join(config.configDir, 'plugins');
+    const agentsDir = agentDirs?.config ?? join(config.configDir, 'agents');
+    const localAgentsDir = agentDirs?.local ?? join(cwd, 'agents');
+    const plugins = createPluginStore({ dir: pluginsDir });
     const newId = () => crypto.randomUUID();
     const pluginAgents = (sessionDefaults.plugins ?? []).flatMap((plugin) => plugin.agents ?? []);
-    const diskAgents = await loadAgents(join(config.configDir, 'agents'));
-    const agents = createAgentRegistry([...hostAgents, ...pluginAgents, ...diskAgents]);
+    const localAgents = await loadAgents(localAgentsDir);
+    const diskAgents = await loadAgents(agentsDir);
+    const agents = createAgentRegistry([...hostAgents, ...pluginAgents, ...localAgents, ...diskAgents]);
     const skillsDir = join(config.configDir, 'skills');
     const cwdSkillsDir = join(cwd, 'skills');
+    const envBlock = environmentBlock({
+        os: `${os.platform()} ${os.release()} (${os.arch()})`,
+        configDir: config.configDir,
+        pluginsDir,
+        skillsDir,
+        agentsDir,
+        hostName,
+        hostSourceUrl: options.sourceUrl,
+    });
+    const envHook = {
+        prepareRequest: ({ system }) => ({ system: system ? `${system}\n\n${envBlock}` : envBlock }),
+    };
     const pluginSkills = (sessionDefaults.plugins ?? []).flatMap((plugin) => plugin.skills ?? []);
     const cwdSkills = await loadSkills(cwdSkillsDir);
     const diskSkills = await loadSkills(skillsDir);
@@ -38,6 +56,11 @@ export const createHarness = async (options) => {
         registry: skills,
         forceScope: skillScope,
     });
+    const agentWriterTool = createAgentWriterTool({
+        dirs: { local: localAgentsDir, config: agentsDir },
+        registry: agents,
+        forceScope: agentScope,
+    });
     const scopeSkills = (agent) => {
         if (!agent)
             return skills;
@@ -52,6 +75,7 @@ export const createHarness = async (options) => {
         ...extra,
         createSkillTool(scopeSkills(agent)),
         skillWriterTool,
+        agentWriterTool,
         ...schedulerTools,
     ];
     const approvalHook = (getAgent) => approvals
@@ -77,7 +101,7 @@ export const createHarness = async (options) => {
     });
     const spawn = (agent) => persistTo(store, persona(agent, {
         tools: sessionTools(agent),
-        hooks: mergeHooks([sessionDefaults.hooks, allowList(toolNames(agent)), approvalHook(() => agent)]),
+        hooks: mergeHooks([sessionDefaults.hooks, allowList(toolNames(agent)), approvalHook(() => agent), envHook]),
     }));
     const scheduler = enableScheduler && tasks
         ? createScheduler({
@@ -125,7 +149,7 @@ export const createHarness = async (options) => {
         },
         revive: ({ id, model: ref, messages }) => createAgentSession({
             ...sessionDefaults,
-            hooks: mergeHooks([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent())]),
+            hooks: mergeHooks([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent()), envHook]),
             tools: sessionTools(undefined, [createSubAgentTool({ registry: agents, spawn, runs, parentId: id })]),
             ...models.resolve(ref),
             id,

package/esm/harness/environment.d.ts

@@ -0,0 +1,10 @@
+export interface EnvironmentInfo {
+    os: string;
+    configDir: string;
+    pluginsDir: string;
+    skillsDir: string;
+    agentsDir: string;
+    hostName: string;
+    hostSourceUrl?: string;
+}
+export declare function environmentBlock(info: EnvironmentInfo): string;

package/esm/harness/environment.js

@@ -0,0 +1,14 @@
+const HARNESS_SOURCE_URL = 'https://github.com/gaetan-puleo/mu-ai';
+export function environmentBlock(info) {
+    const lines = [
+        `Operating system: ${info.os}`,
+        `Config directory: ${info.configDir}`,
+        `Plugins directory: ${info.pluginsDir}`,
+        `Skills directory: ${info.skillsDir}`,
+        `Sub-agents directory: ${info.agentsDir}`,
+        `Harness (mu) source code: ${HARNESS_SOURCE_URL}`,
+    ];
+    if (info.hostSourceUrl)
+        lines.push(`${info.hostName} source code: ${info.hostSourceUrl}`);
+    return `<env>\n${lines.join('\n')}\n</env>`;
+}

package/esm/harness/types.d.ts

@@ -1,12 +1,13 @@
 import type { Provider } from 'mu-core';
 import type { Agent, AgentRegistry, ToolDecision } from '../agents/index.js';
 import type { CommandRegistry } from '../commands/index.js';
+import type { Scope } from '../common/index.js';
 import type { HarnessConfig, HarnessConfigOptions } from '../config/index.js';
 import type { ApprovalManager } from '../permissions/index.js';
 import type { PluginStore } from '../plugin/index.js';
 import type { Scheduler, TaskStore } from '../scheduler/index.js';
 import type { AgentSessionConfig, SessionManager } from '../session/index.js';
-import type { Skill, SkillRegistry, SkillScope } from '../skills/index.js';
+import type { Skill, SkillRegistry } from '../skills/index.js';
 import type { SubAgentRegistry, SubAgentResult } from '../subAgents/index.js';
 import type { ModelRegistry } from './models.js';
 export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'provider' | 'model' | 'id' | 'messages'> & {
@@ -19,10 +20,24 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
      * argument is overridden (and dropped from the tool schema). Unset → the
      * model chooses, defaulting to 'local'.
      */
-    skillScope?: SkillScope;
+    skillScope?: Scope;
+    /**
+     * Forces the save location of `create_agent`. Same semantics as
+     * {@link skillScope}: set to pin the scope, leave unset to let the model choose.
+     */
+    agentScope?: Scope;
+    /**
+     * Overrides where `create_agent` writes (and which dirs are loaded at boot).
+     * Defaults to `{ local: <cwd>/agents, config: <configDir>/agents }`.
+     */
+    agentDirs?: {
+        local?: string;
+        config?: string;
+    };
     title?: boolean;
     titleModel?: string;
     cwd?: string;
+    sourceUrl?: string;
     scheduler?: boolean;
     approvals?: {
         manager: ApprovalManager;

package/esm/skills/index.d.ts

@@ -4,5 +4,5 @@ export { parseSkill } from './parser.js';
 export { loadSkills } from './loader.js';
 export { skillMatchesPlatform } from './platform.js';
 export { createSkillTool } from './tool.js';
-export { createSkillWriterTool, type SkillScope } from './writer.js';
+export { createSkillWriterTool } from './writer.js';
 export { createRunSkillTool, runSkill, type RunSkillDeps } from './run.js';

package/esm/skills/writer.d.ts

@@ -1,8 +1,8 @@
 import type { Tool } from 'mu-core';
+import type { Scope } from '../common/index.js';
 import type { SkillRegistry } from './registry.js';
-export type SkillScope = 'local' | 'config';
 export declare const createSkillWriterTool: (deps: {
-    dirs: Record<SkillScope, string>;
+    dirs: Record<Scope, string>;
     registry: SkillRegistry;
-    forceScope?: SkillScope;
+    forceScope?: Scope;
 }) => Tool;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mu-harness",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "Agent harness: createHarness wires mu-core into a host — XDG paths, model registry, plugins, disk-loaded agents & skills, sub-agents, sessions (JSONL + SQLite catalog), slash commands, permission/approval hooks, an optional scheduler, and a composable TUI chat app",
   "license": "MIT",
   "main": "./script/index.js",
@@ -23,8 +23,8 @@
     "@swc/wasm-typescript": "^1.15.0",
     "cli-highlight": "^2.1.11",
     "croner": "^9.0.0",
-    "mu-core": "^0.17.1",
-    "mu-tui": "^0.17.1"
+    "mu-core": "^0.17.3",
+    "mu-tui": "^0.17.3"
   },
   "_generatedBy": "dnt@dev",
   "types": "./esm/index.d.ts"

package/script/agents/index.d.ts

@@ -2,3 +2,4 @@ export type { Agent, GrantValue, ToolDecision, ToolGrants } from './types.js';
 export { type AgentRegistry, createAgentRegistry, grantArg, toolDecision, toolNames } from './registry.js';
 export { parseAgent } from './parser.js';
 export { loadAgents } from './loader.js';
+export { createAgentWriterTool } from './writer.js';

package/script/agents/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadAgents = exports.parseAgent = exports.toolNames = exports.toolDecision = exports.grantArg = exports.createAgentRegistry = void 0;
+exports.createAgentWriterTool = exports.loadAgents = exports.parseAgent = exports.toolNames = exports.toolDecision = exports.grantArg = exports.createAgentRegistry = void 0;
 var registry_js_1 = require("./registry.js");
 Object.defineProperty(exports, "createAgentRegistry", { enumerable: true, get: function () { return registry_js_1.createAgentRegistry; } });
 Object.defineProperty(exports, "grantArg", { enumerable: true, get: function () { return registry_js_1.grantArg; } });
@@ -10,3 +10,5 @@ var parser_js_1 = require("./parser.js");
 Object.defineProperty(exports, "parseAgent", { enumerable: true, get: function () { return parser_js_1.parseAgent; } });
 var loader_js_1 = require("./loader.js");
 Object.defineProperty(exports, "loadAgents", { enumerable: true, get: function () { return loader_js_1.loadAgents; } });
+var writer_js_1 = require("./writer.js");
+Object.defineProperty(exports, "createAgentWriterTool", { enumerable: true, get: function () { return writer_js_1.createAgentWriterTool; } });

package/script/agents/registry.d.ts

@@ -2,6 +2,13 @@ import type { Agent, ToolDecision } from './types.js';
 export interface AgentRegistry {
     list(): Agent[];
     get(name: string): Agent | undefined;
+    /**
+     * Register (or replace) an agent at runtime — mirrors {@link SkillRegistry.add}.
+     * Lets tools like `create_agent` make a freshly-authored agent immediately
+     * delegatable without a restart. Agents that `extends` the added one are
+     * re-resolved so they pick up the change.
+     */
+    add(agent: Agent): void;
 }
 export declare const grantArg: (tool: string, input: unknown) => string | undefined;
 export declare const toolDecision: (agent: Agent, tool: string, arg?: string) => ToolDecision;

package/script/agents/registry.js

@@ -90,6 +90,13 @@ const createAgentRegistry = (agents = []) => {
     return {
         list: () => [...byName.values()],
         get: (name) => byName.get(name),
+        add: (agent) => {
+            raw.set(agent.name, agent);
+            byName.set(agent.name, resolve(agent.name, new Set()));
+            for (const [name, a] of raw)
+                if (a.extends === agent.name)
+                    byName.set(name, resolve(name, new Set()));
+        },
     };
 };
 exports.createAgentRegistry = createAgentRegistry;

package/script/agents/writer.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from 'mu-core';
+import type { Scope } from '../common/index.js';
+import type { AgentRegistry } from './registry.js';
+/**
+ * `create_agent` — authors a reusable agent definition (`.md` with frontmatter)
+ * and registers it live via {@link AgentRegistry.add}, so it can be delegated to
+ * through `subagent` without a restart. Mirrors {@link createSkillWriterTool}:
+ * the `scope` selects the save location, or a configured `forceScope` pins it.
+ */
+export declare const createAgentWriterTool: (deps: {
+    dirs: Record<Scope, string>;
+    registry: AgentRegistry;
+    forceScope?: Scope;
+}) => Tool;

package/script/agents/writer.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentWriterTool = void 0;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const mod_js_1 = require("../deps/jsr.io/@std/yaml/1.1.0/mod.js");
+const parser_js_1 = require("./parser.js");
+const slug = (name) => name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+/**
+ * `create_agent` — authors a reusable agent definition (`.md` with frontmatter)
+ * and registers it live via {@link AgentRegistry.add}, so it can be delegated to
+ * through `subagent` without a restart. Mirrors {@link createSkillWriterTool}:
+ * the `scope` selects the save location, or a configured `forceScope` pins it.
+ */
+const createAgentWriterTool = (deps) => {
+    const { forceScope } = deps;
+    const scopeProp = forceScope ? {} : {
+        scope: {
+            type: 'string',
+            enum: ['local', 'config'],
+            description: 'Where to save it: "local" = this project (repo-first), "config" = global config dir. Defaults to "local".',
+        },
+    };
+    return {
+        name: 'create_agent',
+        description: forceScope
+            ? `Define a reusable agent (name, description, system prompt, optional per-tool grants) that can be delegated to via \`subagent\`. Always saved to the "${forceScope}" agents directory.`
+            : 'Define a reusable agent (name, description, system prompt, optional per-tool grants) that can be delegated to via `subagent`. `scope: "local"` saves it to this project, `scope: "config"` makes it available across all projects.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Short agent name (kebab-case); also the filename.' },
+                description: { type: 'string', description: 'One line describing what this agent is for.' },
+                prompt: { type: 'string', description: 'The system prompt that defines the agent.' },
+                tools: {
+                    type: 'object',
+                    description: 'Optional per-tool grants: map a tool name to "allow" | "ask" | "deny" (or a nested {glob: decision} map). Omitted tools are denied — be explicit about what it may use.',
+                    additionalProperties: true,
+                },
+                model: { type: 'string', description: 'Optional model ref override.' },
+                color: { type: 'string', description: 'Optional hex color for the UI.' },
+                ...scopeProp,
+            },
+            required: ['name', 'description', 'prompt'],
+            additionalProperties: false,
+        },
+        run: async (input) => {
+            const { name, description, prompt, tools, model, color, scope } = (input ?? {});
+            if (!name || !description || !prompt) {
+                return [{ type: 'text', text: 'Error: create_agent requires `name`, `description`, and `prompt`.' }];
+            }
+            // A configured forceScope wins over whatever the model passed.
+            const resolved = forceScope ?? scope ?? 'local';
+            const base = deps.dirs[resolved];
+            if (!base)
+                return [{ type: 'text', text: `Error: unknown scope "${scope}".` }];
+            const id = slug(name);
+            if (!id)
+                return [{ type: 'text', text: `Error: invalid agent name "${name}".` }];
+            if (deps.registry.get(id)) {
+                return [{ type: 'text', text: `Error: an agent named "${id}" already exists.` }];
+            }
+            const file = (0, node_path_1.join)(base, `${id}.md`);
+            if ((0, node_fs_1.existsSync)(file))
+                return [{ type: 'text', text: `Error: ${file} already exists.` }];
+            const frontmatter = { name: id, description };
+            if (model)
+                frontmatter.model = model;
+            if (color)
+                frontmatter.color = color;
+            if (tools && typeof tools === 'object')
+                frontmatter.tools = tools;
+            const source = `---\n${(0, mod_js_1.stringify)(frontmatter).trimEnd()}\n---\n\n${prompt.trim()}\n`;
+            await (0, promises_1.mkdir)(base, { recursive: true });
+            await (0, promises_1.writeFile)(file, source, 'utf-8');
+            deps.registry.add((0, parser_js_1.parseAgent)(source, id));
+            return [{
+                    type: 'text',
+                    text: `Created agent "${id}" at ${file}. It can now be delegated to via the \`subagent\` tool.`,
+                }];
+        },
+    };
+};
+exports.createAgentWriterTool = createAgentWriterTool;

package/script/common/index.d.ts

@@ -1,2 +1,3 @@
 export { createEmitter, type Emitter, strList } from './utils.js';
 export { type Frontmatter, parseFrontmatter, str } from './frontmatter.js';
+export type { Scope } from './scope.js';

package/script/common/scope.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where a host saves agent-authored definitions (skills, sub-agents, …):
+ * - `local`  → the current project (repo-first, e.g. `<cwd>/skills`).
+ * - `config` → the global config dir, shared across every project.
+ *
+ * Generic across definition kinds so every writer tool speaks the same vocabulary.
+ */
+export type Scope = 'local' | 'config';

package/script/common/scope.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/harness/create.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHarness = void 0;
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = require("node:path");
 const node_process_1 = __importDefault(require("node:process"));
 const index_js_1 = require("../agents/index.js");
@@ -16,6 +17,7 @@ const index_js_7 = require("../scheduler/index.js");
 const index_js_8 = require("../session/index.js");
 const index_js_9 = require("../skills/index.js");
 const index_js_10 = require("../subAgents/index.js");
+const environment_js_1 = require("./environment.js");
 const models_js_1 = require("./models.js");
 const TITLE_AGENT = {
     name: 'title',
@@ -24,17 +26,33 @@ const TITLE_AGENT = {
     tools: [],
 };
 const createHarness = async (options) => {
-    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], skillScope, title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
+    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], skillScope, agentScope, agentDirs, title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
     const cwd = options.cwd ?? node_process_1.default.cwd();
     const config = (0, index_js_3.createHarnessConfig)({ hostName, xdg });
     const models = (0, models_js_1.createModelRegistry)({ providers, default: model });
-    const plugins = (0, index_js_6.createPluginStore)({ dir: (0, node_path_1.join)(config.configDir, 'plugins') });
+    const pluginsDir = (0, node_path_1.join)(config.configDir, 'plugins');
+    const agentsDir = agentDirs?.config ?? (0, node_path_1.join)(config.configDir, 'agents');
+    const localAgentsDir = agentDirs?.local ?? (0, node_path_1.join)(cwd, 'agents');
+    const plugins = (0, index_js_6.createPluginStore)({ dir: pluginsDir });
     const newId = () => crypto.randomUUID();
     const pluginAgents = (sessionDefaults.plugins ?? []).flatMap((plugin) => plugin.agents ?? []);
-    const diskAgents = await (0, index_js_1.loadAgents)((0, node_path_1.join)(config.configDir, 'agents'));
-    const agents = (0, index_js_1.createAgentRegistry)([...hostAgents, ...pluginAgents, ...diskAgents]);
+    const localAgents = await (0, index_js_1.loadAgents)(localAgentsDir);
+    const diskAgents = await (0, index_js_1.loadAgents)(agentsDir);
+    const agents = (0, index_js_1.createAgentRegistry)([...hostAgents, ...pluginAgents, ...localAgents, ...diskAgents]);
     const skillsDir = (0, node_path_1.join)(config.configDir, 'skills');
     const cwdSkillsDir = (0, node_path_1.join)(cwd, 'skills');
+    const envBlock = (0, environment_js_1.environmentBlock)({
+        os: `${node_os_1.default.platform()} ${node_os_1.default.release()} (${node_os_1.default.arch()})`,
+        configDir: config.configDir,
+        pluginsDir,
+        skillsDir,
+        agentsDir,
+        hostName,
+        hostSourceUrl: options.sourceUrl,
+    });
+    const envHook = {
+        prepareRequest: ({ system }) => ({ system: system ? `${system}\n\n${envBlock}` : envBlock }),
+    };
     const pluginSkills = (sessionDefaults.plugins ?? []).flatMap((plugin) => plugin.skills ?? []);
     const cwdSkills = await (0, index_js_9.loadSkills)(cwdSkillsDir);
     const diskSkills = await (0, index_js_9.loadSkills)(skillsDir);
@@ -44,6 +62,11 @@ const createHarness = async (options) => {
         registry: skills,
         forceScope: skillScope,
     });
+    const agentWriterTool = (0, index_js_1.createAgentWriterTool)({
+        dirs: { local: localAgentsDir, config: agentsDir },
+        registry: agents,
+        forceScope: agentScope,
+    });
     const scopeSkills = (agent) => {
         if (!agent)
             return skills;
@@ -58,6 +81,7 @@ const createHarness = async (options) => {
         ...extra,
         (0, index_js_9.createSkillTool)(scopeSkills(agent)),
         skillWriterTool,
+        agentWriterTool,
         ...schedulerTools,
     ];
     const approvalHook = (getAgent) => approvals
@@ -83,7 +107,7 @@ const createHarness = async (options) => {
     });
     const spawn = (agent) => (0, index_js_8.persistTo)(store, persona(agent, {
         tools: sessionTools(agent),
-        hooks: (0, index_js_4.mergeHooks)([sessionDefaults.hooks, (0, index_js_5.allowList)((0, index_js_1.toolNames)(agent)), approvalHook(() => agent)]),
+        hooks: (0, index_js_4.mergeHooks)([sessionDefaults.hooks, (0, index_js_5.allowList)((0, index_js_1.toolNames)(agent)), approvalHook(() => agent), envHook]),
     }));
     const scheduler = enableScheduler && tasks
         ? (0, index_js_7.createScheduler)({
@@ -131,7 +155,7 @@ const createHarness = async (options) => {
         },
         revive: ({ id, model: ref, messages }) => (0, index_js_8.createAgentSession)({
             ...sessionDefaults,
-            hooks: (0, index_js_4.mergeHooks)([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent())]),
+            hooks: (0, index_js_4.mergeHooks)([sessionDefaults.hooks, approvalHook(() => approvals?.activeAgent()), envHook]),
             tools: sessionTools(undefined, [(0, index_js_10.createSubAgentTool)({ registry: agents, spawn, runs, parentId: id })]),
             ...models.resolve(ref),
             id,

package/script/harness/environment.d.ts

@@ -0,0 +1,10 @@
+export interface EnvironmentInfo {
+    os: string;
+    configDir: string;
+    pluginsDir: string;
+    skillsDir: string;
+    agentsDir: string;
+    hostName: string;
+    hostSourceUrl?: string;
+}
+export declare function environmentBlock(info: EnvironmentInfo): string;

package/script/harness/environment.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.environmentBlock = environmentBlock;
+const HARNESS_SOURCE_URL = 'https://github.com/gaetan-puleo/mu-ai';
+function environmentBlock(info) {
+    const lines = [
+        `Operating system: ${info.os}`,
+        `Config directory: ${info.configDir}`,
+        `Plugins directory: ${info.pluginsDir}`,
+        `Skills directory: ${info.skillsDir}`,
+        `Sub-agents directory: ${info.agentsDir}`,
+        `Harness (mu) source code: ${HARNESS_SOURCE_URL}`,
+    ];
+    if (info.hostSourceUrl)
+        lines.push(`${info.hostName} source code: ${info.hostSourceUrl}`);
+    return `<env>\n${lines.join('\n')}\n</env>`;
+}

package/script/harness/types.d.ts

@@ -1,12 +1,13 @@
 import type { Provider } from 'mu-core';
 import type { Agent, AgentRegistry, ToolDecision } from '../agents/index.js';
 import type { CommandRegistry } from '../commands/index.js';
+import type { Scope } from '../common/index.js';
 import type { HarnessConfig, HarnessConfigOptions } from '../config/index.js';
 import type { ApprovalManager } from '../permissions/index.js';
 import type { PluginStore } from '../plugin/index.js';
 import type { Scheduler, TaskStore } from '../scheduler/index.js';
 import type { AgentSessionConfig, SessionManager } from '../session/index.js';
-import type { Skill, SkillRegistry, SkillScope } from '../skills/index.js';
+import type { Skill, SkillRegistry } from '../skills/index.js';
 import type { SubAgentRegistry, SubAgentResult } from '../subAgents/index.js';
 import type { ModelRegistry } from './models.js';
 export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'provider' | 'model' | 'id' | 'messages'> & {
@@ -19,10 +20,24 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
      * argument is overridden (and dropped from the tool schema). Unset → the
      * model chooses, defaulting to 'local'.
      */
-    skillScope?: SkillScope;
+    skillScope?: Scope;
+    /**
+     * Forces the save location of `create_agent`. Same semantics as
+     * {@link skillScope}: set to pin the scope, leave unset to let the model choose.
+     */
+    agentScope?: Scope;
+    /**
+     * Overrides where `create_agent` writes (and which dirs are loaded at boot).
+     * Defaults to `{ local: <cwd>/agents, config: <configDir>/agents }`.
+     */
+    agentDirs?: {
+        local?: string;
+        config?: string;
+    };
     title?: boolean;
     titleModel?: string;
     cwd?: string;
+    sourceUrl?: string;
     scheduler?: boolean;
     approvals?: {
         manager: ApprovalManager;

package/script/skills/index.d.ts

@@ -4,5 +4,5 @@ export { parseSkill } from './parser.js';
 export { loadSkills } from './loader.js';
 export { skillMatchesPlatform } from './platform.js';
 export { createSkillTool } from './tool.js';
-export { createSkillWriterTool, type SkillScope } from './writer.js';
+export { createSkillWriterTool } from './writer.js';
 export { createRunSkillTool, runSkill, type RunSkillDeps } from './run.js';

package/script/skills/writer.d.ts

@@ -1,8 +1,8 @@
 import type { Tool } from 'mu-core';
+import type { Scope } from '../common/index.js';
 import type { SkillRegistry } from './registry.js';
-export type SkillScope = 'local' | 'config';
 export declare const createSkillWriterTool: (deps: {
-    dirs: Record<SkillScope, string>;
+    dirs: Record<Scope, string>;
     registry: SkillRegistry;
-    forceScope?: SkillScope;
+    forceScope?: Scope;
 }) => Tool;