mu-harness 0.16.14 → 0.16.16

package/esm/{harness/npm/src/common → common}/index.d.ts

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

package/esm/{harness/npm/src/common → common}/index.js

@@ -1,2 +1,2 @@
-export { createEmitter } from './utils.js';
+export { createEmitter, strList } from './utils.js';
 export { parseFrontmatter, str } from './frontmatter.js';

package/{script/harness/npm/src → esm}/common/utils.d.ts

@@ -3,3 +3,5 @@ export interface Emitter<T> {
     subscribe(listener: (event: T) => void): () => void;
 }
 export declare const createEmitter: <T>() => Emitter<T>;
+/** Normalize a YAML value that may be a string[] or a comma-separated string into a trimmed string[]. */
+export declare const strList: (value: unknown) => string[];

package/esm/common/utils.js

@@ -0,0 +1,22 @@
+export const createEmitter = () => {
+    const listeners = new Set();
+    return {
+        emit: (event) => {
+            for (const listener of listeners)
+                listener(event);
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+};
+/** Normalize a YAML value that may be a string[] or a comma-separated string into a trimmed string[]. */
+export const strList = (value) => {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === 'string').map((v) => v.trim()).filter(Boolean);
+    }
+    if (typeof value === 'string')
+        return value.split(',').map((v) => v.trim()).filter(Boolean);
+    return [];
+};

package/esm/harness/{npm/src/harness/create.js → create.js}

@@ -18,7 +18,7 @@ const TITLE_AGENT = {
     tools: [],
 };
 export const createHarness = async (options) => {
-    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], title, titleModel, scheduler: enableScheduler = false, approvals, ...sessionDefaults } = options;
+    const { hostName, xdg, providers, model, agents: hostAgents = [], skills: hostSkills = [], skillScope, 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 });
@@ -36,6 +36,7 @@ export const createHarness = async (options) => {
     const skillWriterTool = createSkillWriterTool({
         dirs: { local: cwdSkillsDir, config: skillsDir },
         registry: skills,
+        forceScope: skillScope,
     });
     const scopeSkills = (agent) => {
         if (!agent)

package/esm/harness/{npm/src/harness/types.d.ts → types.d.ts}

@@ -6,7 +6,7 @@ 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 } from '../skills/index.js';
+import type { Skill, SkillRegistry, SkillScope } 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'> & {
@@ -14,6 +14,12 @@ export type HarnessOptions = HarnessConfigOptions & Omit<AgentSessionConfig, 'pr
     model: string;
     agents?: Agent[];
     skills?: Skill[];
+    /**
+     * Forces the save location of `create_skill`. When set, the model's `scope`
+     * argument is overridden (and dropped from the tool schema). Unset → the
+     * model chooses, defaulting to 'local'.
+     */
+    skillScope?: SkillScope;
     title?: boolean;
     titleModel?: string;
     cwd?: string;

package/esm/{harness/npm/src/skills → skills}/index.d.ts

@@ -2,6 +2,7 @@ export type { Skill } from './types.js';
 export { createSkillRegistry, type SkillRegistry } from './registry.js';
 export { parseSkill } from './parser.js';
 export { loadSkills } from './loader.js';
+export { skillMatchesPlatform } from './platform.js';
 export { createSkillTool } from './tool.js';
-export { createSkillWriterTool } from './writer.js';
+export { createSkillWriterTool, type SkillScope } from './writer.js';
 export { createRunSkillTool, runSkill, type RunSkillDeps } from './run.js';

package/esm/{harness/npm/src/skills → skills}/index.js

@@ -1,6 +1,7 @@
 export { createSkillRegistry } from './registry.js';
 export { parseSkill } from './parser.js';
 export { loadSkills } from './loader.js';
+export { skillMatchesPlatform } from './platform.js';
 export { createSkillTool } from './tool.js';
 export { createSkillWriterTool } from './writer.js';
 export { createRunSkillTool, runSkill } from './run.js';

package/esm/skills/loader.d.ts

@@ -0,0 +1,10 @@
+import type { Skill } from './types.js';
+/**
+ * Loads skills from `dir`, supporting Hermes/agentskills.io layout:
+ * - flat `dir/<skill>/SKILL.md`
+ * - one level of category nesting `dir/<category>/<skill>/SKILL.md`
+ * Hidden dirs (.git/.github/.hub) are skipped. Skills whose `platforms` does not
+ * include the current OS are filtered out (so the registry never sees them).
+ * `current` is injectable for testing; defaults to `process.platform`.
+ */
+export declare const loadSkills: (dir: string, current?: string) => Promise<Skill[]>;

package/esm/skills/loader.js

@@ -0,0 +1,59 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { parseSkill } from './parser.js';
+import { skillMatchesPlatform } from './platform.js';
+const isHidden = (name) => name.startsWith('.'); // .git, .github, .hub, dotfiles
+const readDirSorted = async (dir) => {
+    try {
+        return (await readdir(dir)).filter((e) => !isHidden(e)).sort();
+    }
+    catch {
+        return [];
+    }
+};
+const isDir = async (path) => {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Loads skills from `dir`, supporting Hermes/agentskills.io layout:
+ * - flat `dir/<skill>/SKILL.md`
+ * - one level of category nesting `dir/<category>/<skill>/SKILL.md`
+ * Hidden dirs (.git/.github/.hub) are skipped. Skills whose `platforms` does not
+ * include the current OS are filtered out (so the registry never sees them).
+ * `current` is injectable for testing; defaults to `process.platform`.
+ */
+export const loadSkills = async (dir, current = process.platform) => {
+    const skills = [];
+    // Load the skill at `skillDir` if it has a SKILL.md. Returns true when it WAS a skill dir.
+    const tryLoad = async (skillDir) => {
+        let source;
+        try {
+            source = await readFile(join(skillDir, 'SKILL.md'), 'utf-8');
+        }
+        catch {
+            return false;
+        }
+        const skill = parseSkill(source, basename(skillDir), skillDir);
+        if (skillMatchesPlatform(skill.platforms, current))
+            skills.push(skill);
+        return true;
+    };
+    for (const entry of await readDirSorted(dir)) {
+        const entryDir = join(dir, entry);
+        if (!(await isDir(entryDir)))
+            continue;
+        if (await tryLoad(entryDir))
+            continue; // flat: dir/<skill>/SKILL.md
+        for (const child of await readDirSorted(entryDir)) { // category: dir/<category>/<skill>/SKILL.md
+            const childDir = join(entryDir, child);
+            if (await isDir(childDir))
+                await tryLoad(childDir);
+        }
+    }
+    return skills;
+};

package/esm/skills/parser.js

@@ -0,0 +1,16 @@
+import { parseFrontmatter, str, strList } from '../common/index.js';
+export const parseSkill = (source, fallbackName, dir) => {
+    const { fields, body } = parseFrontmatter(source);
+    const platforms = strList(fields.platforms);
+    const skill = {
+        name: str(fields.name) ?? fallbackName,
+        description: str(fields.description) ?? '',
+        prompt: body,
+    };
+    // Emit optional keys only when present — strict-equality tests rely on no `undefined`-valued keys.
+    if (dir !== undefined)
+        skill.dir = dir;
+    if (platforms.length)
+        skill.platforms = platforms;
+    return skill;
+};

package/esm/skills/platform.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mirror of Hermes' `skill_matches_platform`. Returns true when a skill is compatible
+ * with the current OS. Empty/absent `platforms` matches every OS. `current` is a
+ * `process.platform` value ('darwin' | 'linux' | 'win32'); injectable for testing.
+ */
+export declare const skillMatchesPlatform: (platforms: string[] | undefined, current?: string) => boolean;

package/esm/skills/platform.js

@@ -0,0 +1,14 @@
+const PLATFORM_MAP = { macos: 'darwin', linux: 'linux', windows: 'win32' };
+/**
+ * Mirror of Hermes' `skill_matches_platform`. Returns true when a skill is compatible
+ * with the current OS. Empty/absent `platforms` matches every OS. `current` is a
+ * `process.platform` value ('darwin' | 'linux' | 'win32'); injectable for testing.
+ */
+export const skillMatchesPlatform = (platforms, current = process.platform) => {
+    if (!platforms || platforms.length === 0)
+        return true;
+    return platforms.some((p) => {
+        const mapped = PLATFORM_MAP[p.trim().toLowerCase()];
+        return mapped !== undefined && current.startsWith(mapped);
+    });
+};

package/esm/skills/types.d.ts

@@ -0,0 +1,8 @@
+export interface Skill {
+    name: string;
+    description: string;
+    prompt: string;
+    dir?: string;
+    /** OS allow-list (Hermes/agentskills.io `platforms`): macos | linux | windows. Empty/absent = all. */
+    platforms?: string[];
+}

package/esm/{harness/npm/src/skills → skills}/writer.d.ts

@@ -4,4 +4,5 @@ export type SkillScope = 'local' | 'config';
 export declare const createSkillWriterTool: (deps: {
     dirs: Record<SkillScope, string>;
     registry: SkillRegistry;
+    forceScope?: SkillScope;
 }) => Tool;

package/esm/skills/writer.js

@@ -0,0 +1,55 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseSkill } from './parser.js';
+const slug = (name) => name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+export const createSkillWriterTool = (deps) => {
+    const { forceScope } = deps;
+    const scopeProp = forceScope ? {} : {
+        scope: {
+            type: 'string',
+            enum: ['local', 'config'],
+            description: 'Where to save it: "local" = this project (<cwd>/skills), "config" = global config dir. Defaults to "local".',
+        },
+    };
+    return {
+        name: 'create_skill',
+        description: forceScope
+            ? `Create a reusable skill (name, description, instructions) the agent can load on demand later — capture a reusable workflow worth keeping. Always saved to the global "${forceScope}" skills directory; load it later via \`skill\`.`
+            : 'Create a reusable skill (name, description, instructions) the agent can load on demand later — capture a reusable workflow worth keeping. `scope: "local"` saves it to this project, `scope: "config"` makes it available across all projects; load it later via `skill`.',
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Short skill name (kebab-case).' },
+                description: { type: 'string', description: 'One line describing when this skill should be used.' },
+                instructions: {
+                    type: 'string',
+                    description: 'The skill body: the instructions to follow when it is invoked.',
+                },
+                ...scopeProp,
+            },
+            required: ['name', 'description', 'instructions'],
+            additionalProperties: false,
+        },
+        run: async (input) => {
+            const { name, description, instructions, scope } = (input ?? {});
+            if (!name || !description || !instructions) {
+                return [{ type: 'text', text: 'Error: create_skill requires `name`, `description`, and `instructions`.' }];
+            }
+            // 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 skill name "${name}".` }];
+            const skillDir = join(base, id);
+            const file = join(skillDir, 'SKILL.md');
+            const source = `---\nname: ${id}\ndescription: ${JSON.stringify(description)}\n---\n\n${instructions.trim()}\n`;
+            await mkdir(skillDir, { recursive: true });
+            await writeFile(file, source, 'utf-8');
+            deps.registry.add(parseSkill(source, id, skillDir));
+            return [{ type: 'text', text: `Created skill "${id}" at ${file}. It is now available via the \`skill\` tool.` }];
+        },
+    };
+};

package/esm/tui/chat/ChatApp.d.ts

@@ -0,0 +1,188 @@
+import type { AgentSession, SessionRecord } from '../../session/index.js';
+import type { ApprovalManager } from '../../permissions/index.js';
+import type { SubAgentRegistry, SubAgentResult } from '../../subAgents/index.js';
+export interface ModelInfo {
+    id: string;
+    ownedBy?: string;
+}
+/** Toggles for optional chat affordances. Each defaults to enabled (true). */
+export interface ChatFeatures {
+    /** Tool-approval modal driven by the approval manager. */
+    approvals?: boolean;
+    /** Sub-agent panel, @mention dispatch, and the agent picker. */
+    subAgents?: boolean;
+    /** `/sessions` + `/new` session switching. */
+    sessionPicker?: boolean;
+    /** `/model` model switching. */
+    modelPicker?: boolean;
+}
+export interface ChatHost {
+    /**
+     * The initial session. Optional: when omitted, the session is created lazily
+     * via {@link ChatHost.createSession} on the first user message — nothing is
+     * persisted until the user actually sends something.
+     */
+    session?: AgentSession;
+    approvals: ApprovalManager;
+    cwd: string;
+    createSession(): AgentSession;
+    forkSession(id: string, upToIndex: number): Promise<AgentSession>;
+    listSessions(): Promise<SessionRecord[]>;
+    openSession(id: string): Promise<AgentSession>;
+    selectModel(ref: string): void;
+    modelRef(): string;
+    listModels(): Promise<ModelInfo[]>;
+    agentRef(): string;
+    agentColor(): string | undefined;
+    cycleAgent(): string;
+    agentNames(): string[];
+    subAgents: SubAgentRegistry;
+    dispatchSubAgent(agent: string, task: string, parentId: string): Promise<SubAgentResult>;
+    initialTheme: string;
+    saveTheme(name: string): void;
+    initialThinking: boolean;
+    saveThinking(visible: boolean): void;
+    /** Input-line history persistence. Optional; in-memory only when omitted. */
+    history?: {
+        load(): string[];
+        append(text: string): void;
+    };
+    features?: ChatFeatures;
+    /**
+     * ASCII art shown centered in the empty transcript, before the first message
+     * (a splash). Cleared once the conversation starts.
+     */
+    banner?: string;
+    onExit(code: number): void;
+}
+export declare class ChatApp {
+    private readonly host;
+    private readonly tui;
+    private readonly terminal;
+    private readonly editor;
+    private readonly scroll;
+    private readonly transcript;
+    private readonly subScroll;
+    private readonly subTranscript;
+    private readonly themeProvider;
+    private readonly commands;
+    private session;
+    private readonly features;
+    private readonly banner;
+    private unsubscribe;
+    private unsubscribeTheme;
+    private unsubscribeSubAgents;
+    private readonly runUnsubs;
+    private readonly activeRuns;
+    private mentionAc;
+    private readonly status;
+    private running;
+    private readonly queue;
+    private readonly pendingShell;
+    private models;
+    private paletteCursor;
+    private paletteDismissedFor;
+    private pickerMention;
+    private pickerRanked;
+    private pickerCursor;
+    private history;
+    private historyIndex;
+    private historyDraft;
+    private spinnerTimer;
+    private lastEsc;
+    private modelPickerOpen;
+    private modelHandle;
+    private sessionPickerOpen;
+    private sessionHandle;
+    private approvalQueue;
+    private approvalCursor;
+    private unsubscribeApproval;
+    private errorText;
+    private errorTimer;
+    private stopped;
+    constructor(host: ChatHost);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private theme;
+    private commandHost;
+    private openSessionPicker;
+    private buildSessionPicker;
+    private bindSession;
+    private feature;
+    /** Returns the active session, creating it lazily on first use. */
+    private ensureSession;
+    private clearRuns;
+    private abortRuns;
+    private onSubAgentRun;
+    private tryDispatch;
+    private dispatchMention;
+    private swapSession;
+    private handleEvent;
+    private applyUsage;
+    private onTurnComplete;
+    private stripFileMentions;
+    private send;
+    private flushShellContext;
+    private submit;
+    private enqueueFromInput;
+    private onInputChange;
+    private intercept;
+    private cycleAgent;
+    private onEscape;
+    private cancelGeneration;
+    private paletteItems;
+    private paletteMove;
+    private paletteComplete;
+    private paletteRun;
+    private runCommand;
+    private pickerVisible;
+    private pickerMove;
+    private pickerAccept;
+    private deleteMention;
+    private pushHistory;
+    private navigateHistory;
+    private newSession;
+    private openModelPicker;
+    private buildModelPicker;
+    private moveApproval;
+    private resolveApproval;
+    private approvalView;
+    private switchModel;
+    private exportContext;
+    private toggleExpand;
+    private toggleThinking;
+    private toggleTheme;
+    private onCtrlC;
+    private recordShell;
+    private runShell;
+    private setStatus;
+    private showError;
+    private clearError;
+    private startSpinner;
+    private stopSpinner;
+    private loadModels;
+    /** Plain model id (+ provider) shown in the status bar. */
+    private modelText;
+    private updateSpeaker;
+    private promptGlyph;
+    private inputPanel;
+    private editorInner;
+    private errorView;
+    private waitingView;
+    /** The input area: error/palette/picker/waiting affordances + the input panel (no status bar). */
+    private inputGroup;
+    private statusBar;
+    private dock;
+    private jumpToBottom;
+    private jumpToBottomHint;
+    private stickyHeaderView;
+    private governingUser;
+    private focusedSub;
+    private subAgentHeader;
+    private subAgentView;
+    /** Wraps a child to a max width, horizontally centered (keeps its natural height). */
+    private centered;
+    /** The ASCII banner rendered at its natural height, centered as a block. */
+    private bannerBlock;
+    private root;
+}