@moxxy/core 0.3.0

package/src/skills/synthesize.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { LLMProvider, ProviderEvent } from '@moxxy/sdk';
+import { Session } from '../session.js';
+import { asSkillId, asTurnId, defineProvider, definePlugin } from '@moxxy/sdk';
+import { synthesizeSkill, buildSynthesizeSkillPlugin } from './synthesize.js';
+
+const DRAFT_DELTA =
+  '---\nname: refactor-component\ndescription: Split a large React component.\ntriggers: ["refactor", "split"]\nallowed-tools: [Read, Edit]\n---\n# Steps\n\n1. Read the file.\n2. Identify boundaries.\n3. Edit into pieces.\n';
+
+class InlineProvider implements LLMProvider {
+  readonly name = 'inline';
+  readonly models = [{ id: 'inline-1', contextWindow: 100_000, maxOutputTokens: 2000, supportsTools: true, supportsStreaming: true }];
+  private cursor = 0;
+  constructor(private readonly scripts: ReadonlyArray<ReadonlyArray<ProviderEvent>>) {}
+  async *stream(): AsyncIterable<ProviderEvent> {
+    const reply = this.scripts[this.cursor++];
+    if (!reply) throw new Error('InlineProvider: no script left');
+    for (const e of reply) yield e;
+  }
+  async countTokens(): Promise<number> { return 0; }
+}
+
+const draftReply = (): ReadonlyArray<ProviderEvent> => [
+  { type: 'message_start', model: 'inline-1' },
+  { type: 'text_delta', delta: DRAFT_DELTA },
+  { type: 'message_end', stopReason: 'end_turn' },
+];
+
+let tmp: string;
+
+const newSessionWithProvider = (provider: InlineProvider) => {
+  const session = new Session({ cwd: '/tmp', silent: true });
+  const providerPlugin = definePlugin({
+    name: 'shim',
+    providers: [
+      defineProvider({ name: provider.name, models: [...provider.models], createClient: () => provider }),
+    ],
+  });
+  session.pluginHost.registerStatic(providerPlugin);
+  session.providers.setActive(provider.name);
+  return session;
+};
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-synth-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('synthesizeSkill', () => {
+  it('drafts a skill, writes it, registers, and emits SkillCreatedEvent', async () => {
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+
+    const result = await synthesizeSkill(session, 'split component up', 'user', {
+      userDir: path.join(tmp, 'skills'),
+      auditPath: path.join(tmp, 'audit.jsonl'),
+    });
+
+    expect(result.scope).toBe('user');
+    expect(result.skill.frontmatter.name).toBe('refactor-component');
+    expect(result.path).toContain(path.join(tmp, 'skills'));
+
+    const written = await fs.readFile(result.path, 'utf8');
+    expect(written).toContain('refactor-component');
+
+    expect(session.skills.byName('refactor-component')).toBeDefined();
+
+    const createdEvents = session.log.ofType('skill_created');
+    expect(createdEvents).toHaveLength(1);
+    expect(createdEvents[0].name).toBe('refactor-component');
+
+    const audit = await fs.readFile(path.join(tmp, 'audit.jsonl'), 'utf8');
+    expect(audit).toContain('refactor-component');
+  });
+
+  it('stamps skill_created with the active turnId, not a fresh orphan turn', async () => {
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+    const turnId = asTurnId('active-turn-1');
+
+    await synthesizeSkill(
+      session,
+      'split component up',
+      'user',
+      { userDir: path.join(tmp, 'skills'), auditPath: path.join(tmp, 'audit.jsonl') },
+      turnId,
+    );
+
+    const createdEvents = session.log.ofType('skill_created');
+    expect(createdEvents).toHaveLength(1);
+    // Must carry the active turn's id so run-turn's per-turn subscriber filter
+    // (event.turnId !== turnId → drop) doesn't discard it. A fresh startTurn()
+    // id would never match the running turn.
+    expect(createdEvents[0].turnId).toBe(turnId);
+  });
+
+  it('uses project dir when scope=project', async () => {
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+
+    const result = await synthesizeSkill(session, 'do x', 'project', {
+      projectDir: path.join(tmp, 'project/.moxxy/skills'),
+      auditPath: path.join(tmp, 'audit.jsonl'),
+    });
+    expect(result.scope).toBe('project');
+    expect(result.path).toContain(path.join(tmp, 'project/.moxxy/skills'));
+  });
+
+  it('avoids overwriting existing files with -2 suffix', async () => {
+    const provider = new InlineProvider([draftReply(), draftReply()]);
+    const session = newSessionWithProvider(provider);
+
+    const a = await synthesizeSkill(session, 'first', 'user', {
+      userDir: path.join(tmp, 'skills'),
+      auditPath: path.join(tmp, 'audit.jsonl'),
+    });
+    const b = await synthesizeSkill(session, 'second', 'user', {
+      userDir: path.join(tmp, 'skills'),
+      auditPath: path.join(tmp, 'audit.jsonl'),
+    });
+    expect(b.path).not.toBe(a.path);
+    expect(b.path).toMatch(/-2\.md$/);
+  });
+});
+
+describe('buildSynthesizeSkillPlugin', () => {
+  it('registers synthesize_skill and reload_skills tools', () => {
+    const provider = new InlineProvider([]);
+    const session = newSessionWithProvider(provider);
+    const plugin = buildSynthesizeSkillPlugin(session);
+    session.pluginHost.registerStatic(plugin);
+    expect(session.tools.has('synthesize_skill')).toBe(true);
+    expect(session.tools.has('reload_skills')).toBe(true);
+  });
+
+  it('load_skill emits skill_invoked with the active turnId from ctx', async () => {
+    const provider = new InlineProvider([]);
+    const session = newSessionWithProvider(provider);
+    session.pluginHost.registerStatic(buildSynthesizeSkillPlugin(session));
+    // A pre-authored skill load_skill can resolve.
+    session.skills.register({
+      id: asSkillId('user/demo'),
+      path: '/demo.md',
+      scope: 'user',
+      frontmatter: { name: 'demo', description: 'd' },
+      body: 'steps',
+    });
+
+    const turnId = asTurnId('active-turn-2');
+    // Drive the tool through the registry exactly as the loop does: the
+    // ToolContext is built with the running turn's id, so the handler must
+    // stamp skill_invoked with THAT id (not a fresh startTurn() orphan that the
+    // run-turn subscriber filter would drop).
+    await session.tools.execute(
+      'load_skill',
+      { name: 'demo' },
+      session.signal,
+      { turnId: String(turnId), sessionId: String(session.id), callId: 'c1' },
+    );
+
+    const invoked = session.log.ofType('skill_invoked');
+    expect(invoked).toHaveLength(1);
+    expect(invoked[0].turnId).toBe(turnId);
+  });
+});

package/src/skills/synthesize.ts

@@ -0,0 +1,304 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import {
+  asSkillId,
+  definePlugin,
+  defineTool,
+  skillFrontmatterSchema,
+  type Plugin,
+  type Skill,
+  type SkillScope,
+  type TurnId,
+} from '@moxxy/sdk';
+import { z } from 'zod';
+import { defaultProjectSkillsDir, defaultUserSkillsDir } from './loader.js';
+import { draftSkill } from './synthesize-draft.js';
+import type { Session } from '../session.js';
+
+export interface SynthesizeOptions {
+  readonly userDir?: string;
+  readonly projectDir?: string;
+  readonly model?: string;
+  readonly auditPath?: string;
+  /**
+   * Directory holding builtin skills (`@moxxy/skills-builtin`). Threaded
+   * through so `reload_skills` can rescan the same source set as the boot
+   * loader — otherwise reload silently drops the builtins, observed when
+   * a session called `reload_skills` and lost every shipped skill.
+   */
+  readonly builtinDir?: string;
+  /** Extra plugin-supplied skill directories. Same boot-vs-reload story. */
+  readonly pluginDirs?: ReadonlyArray<string>;
+}
+
+export interface SynthesizedSkill {
+  readonly skill: Skill;
+  readonly path: string;
+  readonly scope: SkillScope;
+}
+
+export async function synthesizeSkill(
+  session: Session,
+  intent: string,
+  scope: 'user' | 'project',
+  opts: SynthesizeOptions = {},
+  /**
+   * The active turn's id, threaded from the tool's `ctx.turnId`. The
+   * `skill_created` event MUST carry it so run-turn's per-turn subscriber
+   * (`event.turnId !== turnId → drop`) doesn't filter the event out of the
+   * running turn's stream. Falls back to a fresh turn only for legacy callers
+   * that invoke this outside a turn.
+   */
+  turnId?: TurnId,
+): Promise<SynthesizedSkill> {
+  const provider = session.providers.getActive();
+  // Prefer the model the conversation last ran on over the provider's first
+  // descriptor; 'default' matches run-turn's terminal fallback (never a
+  // hardcoded vendor id that goes stale).
+  const model =
+    opts.model ?? session.lastResolvedModel ?? provider.models[0]?.id ?? 'default';
+  const draft = await draftSkill(provider, model, intent, session.signal);
+
+  const baseDir =
+    scope === 'project'
+      ? opts.projectDir ?? defaultProjectSkillsDir(session.cwd)
+      : opts.userDir ?? defaultUserSkillsDir();
+  await fs.mkdir(baseDir, { recursive: true });
+
+  // Validate the LLM-drafted frontmatter against the published schema BEFORE
+  // we write it to disk or register it. A model that returns sloppy YAML
+  // (missing description, illegal slug, etc.) should fail with a single
+  // readable line — the raw zod issue array was dumping ~30 lines of
+  // angry red JSON into the chat, which is a worse signal than just
+  // saying "the model didn't produce valid frontmatter."
+  const parsed = skillFrontmatterSchema.safeParse(draft.frontmatter);
+  if (!parsed.success) {
+    const missing = parsed.error.issues
+      .map((iss) => iss.path.join('.') || '(root)')
+      .join(', ');
+    throw new Error(
+      `synthesize_skill: the model didn't produce valid skill frontmatter ` +
+        `(missing or invalid: ${missing}). This usually means the model returned ` +
+        `prose or a code block without proper YAML frontmatter. Try a more specific intent.`,
+    );
+  }
+  const frontmatter = parsed.data as Skill['frontmatter'];
+
+  const finalPath = await uniqueFilename(baseDir, slugify(frontmatter.name));
+  await fs.writeFile(finalPath, draft.raw, 'utf8');
+
+  // Derive the skill id from the on-disk filename, not from the LLM-supplied
+  // frontmatter name — otherwise synthesizing the same name twice collides
+  // even when uniqueFilename has just bumped the filename to `<slug>-2.md`.
+  const basename = path.basename(finalPath, '.md');
+  const skill: Skill = {
+    id: asSkillId(`${scope}/${basename}`),
+    path: finalPath,
+    scope,
+    frontmatter,
+    body: draft.body.trimEnd(),
+  };
+  session.skills.register(skill);
+
+  await session.log.append({
+    type: 'skill_created',
+    sessionId: session.id,
+    turnId: turnId ?? session.startTurn().turnId,
+    source: 'system',
+    skillId: skill.id,
+    name: skill.frontmatter.name,
+    path: finalPath,
+    scope,
+    originatingPrompt: intent,
+  });
+
+  const auditPath = opts.auditPath ?? path.join(defaultUserSkillsDir(), '.meta', 'created.jsonl');
+  await appendAudit(auditPath, {
+    slug: path.basename(finalPath, '.md'),
+    ts: new Date().toISOString(),
+    sessionId: String(session.id),
+    originatingPrompt: intent,
+    scope,
+  });
+
+  return { skill, path: finalPath, scope };
+}
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+async function uniqueFilename(dir: string, base: string): Promise<string> {
+  let candidate = path.join(dir, `${base}.md`);
+  let n = 2;
+  while (await exists(candidate)) {
+    candidate = path.join(dir, `${base}-${n}.md`);
+    n += 1;
+  }
+  return candidate;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function appendAudit(filePath: string, entry: Record<string, unknown>): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.appendFile(filePath, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+export function buildSynthesizeSkillPlugin(
+  session: Session,
+  opts: SynthesizeOptions = {},
+): Plugin {
+  return definePlugin({
+    name: '@moxxy/synthesize-skill',
+    version: '0.0.0',
+    tools: [
+      defineTool({
+        name: 'synthesize_skill',
+        description:
+          'Draft and persist a new Markdown skill for the given user intent. ' +
+          'Uses the active provider to generate the skill body. Returns the path of the created skill. ' +
+          'ALWAYS pass scope="user" (the default) unless the user has EXPLICITLY asked to scope ' +
+          'the skill to this project — "user" writes to ~/.moxxy/skills/ and the skill is ' +
+          'available across every project; "project" writes to <cwd>/.moxxy/skills/ and only ' +
+          'applies in this directory. Most skills are general-purpose; pick "project" only when ' +
+          'the user said something like "for this repo only" or "project-specific".',
+        inputSchema: z.object({
+          intent: z.string().min(1).describe('What the user is trying to do. One sentence is enough.'),
+          scope: z
+            .enum(['user', 'project'])
+            .optional()
+            .default('user')
+            .describe(
+              'Where to write the skill. "user" → ~/.moxxy/skills/ (default, recommended). ' +
+                '"project" → <cwd>/.moxxy/skills/ — ONLY when the user explicitly asks for a project-scoped skill.',
+            ),
+        }),
+        permission: { action: 'prompt' },
+        handler: async ({ intent, scope }, ctx) => {
+          const result = await synthesizeSkill(session, intent, scope, opts, ctx.turnId);
+          return {
+            path: result.path,
+            scope: result.scope,
+            name: result.skill.frontmatter.name,
+          };
+        },
+      }),
+      defineTool({
+        name: 'load_skill',
+        description:
+          'Fetch the full body (instructions) of a pre-authored skill by name. ' +
+          'The system prompt lists each skill\'s name, description, and triggers; ' +
+          'call this tool to retrieve the actual workflow when the user\'s intent ' +
+          'matches one of those skills. Returns the markdown body verbatim plus the ' +
+          'frontmatter metadata (allowed-tools, scope, etc.).',
+        inputSchema: z.object({
+          name: z
+            .string()
+            .min(1)
+            .describe('The exact skill name from the "Available skills" list in the system prompt.'),
+        }),
+        handler: async ({ name }, ctx) => {
+          const skill = session.skills.byName(name);
+          if (!skill) {
+            const known = session.skills
+              .list()
+              .map((s) => s.frontmatter.name)
+              .join(', ');
+            throw new Error(
+              `load_skill: no skill named "${name}". ` +
+                `Known skills: ${known || '(none registered)'}.`,
+            );
+          }
+          // Emit a skill_invoked event so the audit log captures which
+          // skills were actually exercised in this turn — useful for
+          // routing analytics and for the self-improver agent later. Use the
+          // active turn's id (ctx.turnId) so run-turn's per-turn subscriber
+          // filter doesn't drop it (a fresh startTurn() id wouldn't match).
+          await session.log.append({
+            type: 'skill_invoked',
+            sessionId: session.id,
+            turnId: ctx.turnId,
+            source: 'model',
+            skillId: skill.id,
+            name: skill.frontmatter.name,
+            reason: 'load_skill_tool',
+          });
+          return {
+            name: skill.frontmatter.name,
+            description: skill.frontmatter.description,
+            scope: skill.scope,
+            allowedTools: skill.frontmatter['allowed-tools'] ?? null,
+            body: skill.body,
+          };
+        },
+      }),
+      defineTool({
+        name: 'reload_skills',
+        description:
+          'Rescan all skill sources (builtin + plugin + ~/.moxxy/skills + ./.moxxy/skills), ' +
+          'registering any new or changed skills.',
+        inputSchema: z.object({}),
+        // Safe, idempotent, local-only rescan — never prompt. Without this the
+        // tool inherits the channel resolver's default, which denies in
+        // headless runs (the skill-author flow couldn't activate a new skill).
+        permission: { action: 'allow' },
+        handler: async () => {
+          const { discoverSkills } = await import('./loader.js');
+          // Discover first, swap second: never empty the registry while
+          // the fs scan is in flight, because concurrent skill lookups
+          // would observe an empty registry mid-reload. Pass the SAME
+          // source set the boot loader used (builtin + pluginDirs +
+          // user + project); a previous version of this handler omitted
+          // builtinDir/pluginDirs and reload silently nuked the builtin
+          // skill set.
+          const discovered = await discoverSkills({
+            projectDir: opts.projectDir ?? defaultProjectSkillsDir(session.cwd),
+            userDir: opts.userDir ?? defaultUserSkillsDir(),
+            ...(opts.builtinDir ? { builtinDir: opts.builtinDir } : {}),
+            ...(opts.pluginDirs ? { pluginDirs: opts.pluginDirs } : {}),
+          });
+          session.skills.replaceAll(discovered);
+          return `loaded ${discovered.length} skill${discovered.length === 1 ? '' : 's'}`;
+        },
+      }),
+      defineTool({
+        name: 'load_tool',
+        description:
+          'Load a tool whose full schema was indexed but not sent (see "Loadable tools" ' +
+          'in the system prompt). Call this with the tool name; the tool becomes callable ' +
+          'on the next turn. Only needed when lazy tool loading is enabled — core tools ' +
+          '(Read/Write/Edit/Bash/Grep/Glob) are always available.',
+        inputSchema: z.object({
+          name: z.string().min(1).describe('Exact tool name from the "Loadable tools" index.'),
+        }),
+        permission: { action: 'allow' },
+        handler: ({ name }) => {
+          // The call itself is recorded in the log; `applyLazyTools` reads that
+          // to include the tool's schema on subsequent requests. Here we just
+          // validate the name and echo the description so the model can proceed.
+          const tool = session.tools.get(name);
+          if (!tool) {
+            const known = session.tools
+              .list()
+              .map((t) => t.name)
+              .join(', ');
+            throw new Error(`load_tool: no tool named "${name}". Known tools: ${known}.`);
+          }
+          return { name: tool.name, description: tool.description, loaded: true };
+        },
+      }),
+    ],
+  });
+}

package/src/subagents/events.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { asSessionId, asTurnId, type MoxxyEvent } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+import type { EventLog } from '../events/log.js';
+import { streamChildEventToParent } from './events.js';
+
+const childTool: MoxxyEvent = {
+  type: 'tool_call_requested',
+  seq: 0,
+  id: 'e0',
+  ts: 0,
+  sessionId: asSessionId('child'),
+  turnId: asTurnId('ct'),
+  source: 'model',
+  callId: 'call-1',
+  name: 'list_dir',
+  input: { path: '.' },
+} as unknown as MoxxyEvent;
+
+describe('streamChildEventToParent', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  // u47-5: a parent-log append failure while forwarding child progress must be
+  // non-fatal (the subagent run continues) AND observable (not silently lost).
+  it('does not throw and surfaces a diagnostic when the parent log append rejects', async () => {
+    const stderr = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    const append = vi.fn().mockRejectedValue(new Error('disk full'));
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    await expect(
+      streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), childTool),
+    ).resolves.toBeUndefined();
+
+    expect(append).toHaveBeenCalledTimes(1);
+    expect(stderr).toHaveBeenCalledTimes(1);
+    expect(String(stderr.mock.calls[0]![0])).toContain('disk full');
+    expect(String(stderr.mock.calls[0]![0])).toContain('subagent_tool_call');
+  });
+
+  it('forwards a mapped child event to the parent log on the happy path', async () => {
+    const append = vi.fn().mockResolvedValue(undefined);
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    await streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), childTool);
+    expect(append).toHaveBeenCalledTimes(1);
+    const arg = append.mock.calls[0]![0] as { type: string; subtype: string };
+    expect(arg.type).toBe('plugin_event');
+    expect(arg.subtype).toBe('subagent_tool_call');
+  });
+});