@moxxy/core 0.4.0 → 0.5.1

package/src/skills/synthesize.test.ts

@@ -126,6 +126,65 @@ describe('synthesizeSkill', () => {
     expect(b.path).not.toBe(a.path);
     expect(b.path).toMatch(/-2\.md$/);
   });
+
+  it('does not overwrite a same-slug file already on disk (atomic wx create)', async () => {
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+    const skillsDir = path.join(tmp, 'skills');
+    await fs.mkdir(skillsDir, { recursive: true });
+    // Pre-existing skill file with the slug that this synthesis will produce.
+    const squatted = path.join(skillsDir, 'refactor-component.md');
+    await fs.writeFile(squatted, 'PRE-EXISTING — MUST NOT BE TRUNCATED');
+
+    const result = await synthesizeSkill(session, 'split component up', 'user', {
+      userDir: skillsDir,
+      auditPath: path.join(tmp, 'audit.jsonl'),
+    });
+
+    // The pre-existing file is untouched and the new skill landed on a bumped name.
+    expect(await fs.readFile(squatted, 'utf8')).toBe('PRE-EXISTING — MUST NOT BE TRUNCATED');
+    expect(result.path).toMatch(/-2\.md$/);
+  });
+
+  it('still returns the created skill when the audit append fails (audit is best-effort)', async () => {
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+    // Make the audit path unwritable by planting a FILE where its parent dir
+    // must be — appendAudit's mkdir(dirname) then throws ENOTDIR/EEXIST.
+    const blocker = path.join(tmp, 'blocker');
+    await fs.writeFile(blocker, 'i am a file, not a directory');
+    const auditPath = path.join(blocker, 'created.jsonl');
+
+    const result = await synthesizeSkill(session, 'split component up', 'user', {
+      userDir: path.join(tmp, 'skills'),
+      auditPath,
+    });
+
+    // The skill is the product — it was written, registered, and returned despite
+    // the telemetry write failing.
+    expect(result.skill.frontmatter.name).toBe('refactor-component');
+    expect(await fs.readFile(result.path, 'utf8')).toContain('refactor-component');
+    expect(session.skills.byName('refactor-component')).toBeDefined();
+  });
+
+  it('caps the audit JSONL at MAX_AUDIT_LINES', async () => {
+    const auditPath = path.join(tmp, 'audit.jsonl');
+    // Seed the audit with way more than the cap.
+    const seed = Array.from({ length: 2100 }, (_, i) => JSON.stringify({ n: i })).join('\n') + '\n';
+    await fs.writeFile(auditPath, seed);
+
+    const provider = new InlineProvider([draftReply()]);
+    const session = newSessionWithProvider(provider);
+    await synthesizeSkill(session, 'split component up', 'user', {
+      userDir: path.join(tmp, 'skills'),
+      auditPath,
+    });
+
+    const lines = (await fs.readFile(auditPath, 'utf8')).split('\n').filter((l) => l.length > 0);
+    expect(lines.length).toBeLessThanOrEqual(2000);
+    // The most-recent line is the one we just appended (the skill slug).
+    expect(lines[lines.length - 1]).toContain('refactor-component');
+  });
 });
 
 describe('buildSynthesizeSkillPlugin', () => {

package/src/skills/synthesize.ts

@@ -84,12 +84,11 @@ export async function synthesizeSkill(
   }
   const frontmatter = parsed.data as Skill['frontmatter'];
 
-  const finalPath = await uniqueFilename(baseDir, slugify(frontmatter.name));
-  await fs.writeFile(finalPath, draft.raw, 'utf8');
+  const finalPath = await writeUniqueSkill(baseDir, slugify(frontmatter.name), draft.raw);
 
   // 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`.
+  // even when writeUniqueSkill has just bumped the filename to `<slug>-2.md`.
   const basename = path.basename(finalPath, '.md');
   const skill: Skill = {
     id: asSkillId(`${scope}/${basename}`),
@@ -100,26 +99,46 @@ export async function synthesizeSkill(
   };
   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,
-  });
+  // The skill file on disk + the live registration are the product; the
+  // skill_created event and the audit JSONL line are telemetry. A failure in
+  // either (listener/persistence reject, EACCES on .meta, read-only fs) must
+  // NOT throw after the skill is already written + registered — that would
+  // surface an error the model retries, orphaning the just-created skill and
+  // duplicating it. Make both best-effort and warn instead.
+  try {
+    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,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `moxxy: synthesize_skill could not emit skill_created for "${skill.frontmatter.name}": ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
 
   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,
-  });
+  try {
+    await appendAudit(auditPath, {
+      slug: path.basename(finalPath, '.md'),
+      ts: new Date().toISOString(),
+      sessionId: String(session.id),
+      originatingPrompt: intent,
+      scope,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `moxxy: synthesize_skill audit append failed (${auditPath}): ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
 
   return { skill, path: finalPath, scope };
 }
@@ -132,28 +151,62 @@ function slugify(name: string): string {
     .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;
+/**
+ * Pick a unique `<base>[-N].md` name AND create it atomically with the `wx`
+ * flag (fail if exists). Name selection and creation are one step, so two
+ * concurrent synthesizeSkill calls (workflows / self-improver) racing on the
+ * same slug can't both pick the same candidate and have the later writeFile
+ * truncate the earlier skill — the loser gets EEXIST and bumps the suffix.
+ */
+async function writeUniqueSkill(dir: string, base: string, data: string): Promise<string> {
+  let n = 1;
+  // Bound the search so a directory already saturated with `<base>-*.md` (or a
+  // persistent EEXIST race) can't spin forever — surface a clear error instead.
+  const MAX_ATTEMPTS = 1000;
+  for (;;) {
+    const candidate = path.join(dir, n === 1 ? `${base}.md` : `${base}-${n}.md`);
+    try {
+      await fs.writeFile(candidate, data, { encoding: 'utf8', flag: 'wx' });
+      return candidate;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      n += 1;
+      if (n > MAX_ATTEMPTS) {
+        throw new Error(
+          `synthesize_skill: could not find a free filename for "${base}" after ${MAX_ATTEMPTS} attempts`,
+        );
+      }
+    }
   }
-  return candidate;
 }
 
-async function exists(p: string): Promise<boolean> {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
+/** Cap the audit JSONL so a long-lived/self-synthesizing install can't grow it without bound. */
+const MAX_AUDIT_LINES = 2000;
 
 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');
+  await rotateAuditIfNeeded(filePath);
+}
+
+/**
+ * Keep only the most recent {@link MAX_AUDIT_LINES} lines. Best-effort and
+ * non-atomic by design — this file is pure telemetry that nothing reads back
+ * with a bound, so a crash mid-rewrite at worst loses a few audit lines.
+ */
+async function rotateAuditIfNeeded(filePath: string): Promise<void> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return;
+  }
+  const lines = raw.split('\n');
+  // Account for the trailing empty element from the final newline.
+  const nonEmpty = lines.filter((l) => l.length > 0);
+  if (nonEmpty.length <= MAX_AUDIT_LINES) return;
+  const kept = nonEmpty.slice(nonEmpty.length - MAX_AUDIT_LINES);
+  await fs.writeFile(filePath, kept.join('\n') + '\n', 'utf8');
 }
 
 export function buildSynthesizeSkillPlugin(

package/src/subagents/events.test.ts

@@ -53,4 +53,60 @@ describe('streamChildEventToParent', () => {
     expect(arg.type).toBe('plugin_event');
     expect(arg.subtype).toBe('subagent_tool_call');
   });
+
+  // A child Bash/Read returning a multi-MB blob must NOT be copied verbatim into
+  // the parent log (unbounded amplification): the forwarded output is truncated.
+  it('truncates an oversized child tool_result output before mirroring to the parent', async () => {
+    const append = vi.fn().mockResolvedValue(undefined);
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    const huge = 'x'.repeat(2 * 1024 * 1024); // 2 MiB
+    const bigResult = {
+      type: 'tool_result',
+      seq: 1,
+      id: 'e1',
+      ts: 0,
+      sessionId: asSessionId('child'),
+      turnId: asTurnId('ct'),
+      source: 'model',
+      callId: 'call-2',
+      ok: true,
+      output: huge,
+    } as unknown as MoxxyEvent;
+
+    await streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), bigResult);
+    expect(append).toHaveBeenCalledTimes(1);
+    const arg = append.mock.calls[0]![0] as { payload: { output: string } };
+    expect(arg.payload.output.length).toBeLessThan(huge.length);
+    expect(arg.payload.output.length).toBeLessThan(64 * 1024);
+    expect(arg.payload.output).toContain('elided');
+  });
+
+  it('passes a small child tool_result output through unchanged', async () => {
+    const append = vi.fn().mockResolvedValue(undefined);
+    const parent = {
+      id: asSessionId('parent'),
+      log: { append } as unknown as EventLog,
+    } as unknown as SessionRuntime;
+
+    const smallResult = {
+      type: 'tool_result',
+      seq: 1,
+      id: 'e1',
+      ts: 0,
+      sessionId: asSessionId('child'),
+      turnId: asTurnId('ct'),
+      source: 'model',
+      callId: 'call-3',
+      ok: true,
+      output: 'short output',
+    } as unknown as MoxxyEvent;
+
+    await streamChildEventToParent(parent, asTurnId('pt'), 'researcher', asSessionId('child'), smallResult);
+    const arg = append.mock.calls[0]![0] as { payload: { output: unknown } };
+    expect(arg.payload.output).toBe('short output');
+  });
 });

package/src/subagents/events.ts

@@ -133,6 +133,32 @@ export async function streamChildEventToParent(
   }
 }
 
+/** Max chars of a forwarded child tool output/error mirrored onto the parent log. */
+const MAX_FORWARD_CHARS = 16 * 1024;
+
+/**
+ * Bound an arbitrary child tool result before mirroring it onto the parent log.
+ * Strings are truncated with an elision marker; other values pass through when
+ * their serialized length is small and are replaced with a marker when not (we
+ * avoid re-parsing — the full payload still lives in the child log).
+ */
+function truncateForward(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.length > MAX_FORWARD_CHARS
+      ? `${value.slice(0, MAX_FORWARD_CHARS)}… [${value.length - MAX_FORWARD_CHARS} more chars elided]`
+      : value;
+  }
+  if (value === null || value === undefined || typeof value !== 'object') return value;
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    return '[unserializable subagent output elided]';
+  }
+  if (serialized.length <= MAX_FORWARD_CHARS) return value;
+  return `${serialized.slice(0, MAX_FORWARD_CHARS)}… [${serialized.length - MAX_FORWARD_CHARS} more chars elided]`;
+}
+
 function mapChildEvent(
   label: string,
   childSessionId: SessionId,
@@ -154,8 +180,12 @@ function mapChildEvent(
     case 'tool_result':
       payload.callId = String(childEvt.callId);
       payload.ok = childEvt.ok;
-      if (childEvt.ok) payload.output = childEvt.output;
-      else payload.error = childEvt.error;
+      // Child tool outputs are `unknown` and unbounded (a child Read/Bash can
+      // return multi-MB blobs). Forwarding them verbatim copies the full payload
+      // into the in-memory parent log too — doubling memory/persistence cost and
+      // multiplying it under deep nesting. The TUI only needs a preview, so cap it.
+      if (childEvt.ok) payload.output = truncateForward(childEvt.output);
+      else payload.error = truncateForward(childEvt.error);
       return { subtype: 'subagent_tool_result', payload };
     case 'error':
       payload.kind = childEvt.kind;

package/src/subagents/registry.test.ts

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { asSessionId } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+import {
+  claimRetainedChild,
+  clearRetainedChildren,
+  getRetainedChild,
+  registerRetainedChild,
+  releaseRetainedChild,
+  unclaimRetainedChild,
+  type RetainedChildSession,
+} from './registry.js';
+
+// Minimal retained entry — the registry only reads childSessionId, parentSession.id,
+// and retainedAt; the rest can be cast through `unknown`.
+function makeEntry(id: string, parentId = 'parent'): RetainedChildSession {
+  return {
+    childSessionId: asSessionId(id),
+    parentSession: { id: asSessionId(parentId) } as unknown as SessionRuntime,
+  } as unknown as RetainedChildSession;
+}
+
+afterEach(() => {
+  clearRetainedChildren();
+  vi.useRealTimers();
+});
+
+describe('retained-child registry hardening', () => {
+  it('claim removes the entry and marks it busy so a racing claim cannot double-drive it', () => {
+    const id = asSessionId('c1');
+    registerRetainedChild(makeEntry('c1'));
+
+    const first = claimRetainedChild(id);
+    expect(first).toBeDefined();
+    // Entry is gone from the registry the instant it is claimed.
+    expect(getRetainedChild(id)).toBeUndefined();
+    // A racing claim for the same id finds nothing (and is also blocked by busy).
+    expect(claimRetainedChild(id)).toBeUndefined();
+
+    unclaimRetainedChild(id);
+    expect(claimRetainedChild(id)).toBeUndefined(); // still gone from registry
+  });
+
+  it('release while a claim is in flight drops the busy marker without resurrecting the entry', () => {
+    const id = asSessionId('c2');
+    registerRetainedChild(makeEntry('c2'));
+    expect(claimRetainedChild(id)).toBeDefined();
+    releaseRetainedChild(id); // racing release()
+    // Re-registering then claiming works again (busy was cleared).
+    registerRetainedChild(makeEntry('c2'));
+    expect(claimRetainedChild(id)).toBeDefined();
+  });
+
+  it('caps the number of retained children, evicting the oldest', () => {
+    for (let i = 0; i < 100; i++) registerRetainedChild(makeEntry(`k${i}`));
+    // The earliest entries must have been evicted; the latest survive.
+    expect(getRetainedChild(asSessionId('k0'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('k99'))).toBeDefined();
+    // Bounded: never more than the cap.
+    let live = 0;
+    for (let i = 0; i < 100; i++) if (getRetainedChild(asSessionId(`k${i}`))) live++;
+    expect(live).toBeLessThanOrEqual(64);
+  });
+
+  it('returns the entry evicted under the cap so the caller can warn the operator', () => {
+    // Fill to the cap, then one more — the registering call must hand back the
+    // oldest (k0) it dropped so run-child can emit a subagent_warning for it.
+    for (let i = 0; i < 64; i++) registerRetainedChild(makeEntry(`c${i}`));
+    const evicted = registerRetainedChild(makeEntry('overflow'));
+    expect(evicted.map((e) => String(e.childSessionId))).toContain('c0');
+    expect(getRetainedChild(asSessionId('c0'))).toBeUndefined();
+  });
+
+  it('returns TTL-expired entries it pruned on the next register', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    registerRetainedChild(makeEntry('aged'));
+
+    vi.setSystemTime(31 * 60 * 1000);
+    const evicted = registerRetainedChild(makeEntry('newcomer'));
+    expect(evicted.map((e) => String(e.childSessionId))).toContain('aged');
+    expect(getRetainedChild(asSessionId('aged'))).toBeUndefined();
+  });
+
+  it('evicts a stale paused child after the TTL on the next register', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    registerRetainedChild(makeEntry('stale'));
+    expect(getRetainedChild(asSessionId('stale'))).toBeDefined();
+
+    // Advance past the 30-minute TTL, then register a fresh child — that
+    // triggers pruning of the expired one.
+    vi.setSystemTime(31 * 60 * 1000);
+    registerRetainedChild(makeEntry('fresh'));
+    expect(getRetainedChild(asSessionId('stale'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('fresh'))).toBeDefined();
+  });
+
+  it('clearRetainedChildren scopes to the owning session', () => {
+    registerRetainedChild(makeEntry('a1', 'sessA'));
+    registerRetainedChild(makeEntry('b1', 'sessB'));
+    clearRetainedChildren(asSessionId('sessA'));
+    expect(getRetainedChild(asSessionId('a1'))).toBeUndefined();
+    expect(getRetainedChild(asSessionId('b1'))).toBeDefined();
+  });
+});

package/src/subagents/registry.ts

@@ -28,20 +28,93 @@ export interface RetainedChildSession {
   readonly strategyName: string;
   readonly parentSession: SessionRuntime;
   readonly parentTurnId: TurnId;
+  /** Cumulative provider token cost across this retained session's turns. */
+  tokensUsed?: number;
+  /** Wall-clock ms when the entry was (re)registered — drives TTL eviction. */
+  readonly retainedAt?: number;
 }
 
+/**
+ * Cap the number of live retained children. Each entry pins a full EventLog +
+ * ModeContext (provider, tool registry, plugin host, signal); an `awaitInput`
+ * child whose resume never arrives would otherwise leak for the life of a
+ * long-lived in-process runner. When the cap is exceeded the oldest entry is
+ * evicted (its `continue()` will then fail with "no retained subagent session").
+ */
+const MAX_RETAINED = 64;
+/** Evict a paused child this long after registration if never resumed. */
+const RETAIN_TTL_MS = 30 * 60 * 1000;
+
 const retained = new Map<string, RetainedChildSession>();
+/** Child session ids with a `continue()` currently in flight (claim-then-run). */
+const busy = new Set<string>();
 
-export function registerRetainedChild(session: RetainedChildSession): void {
-  retained.set(String(session.childSessionId), session);
+/** Drop entries past their TTL and return them so the caller can warn. */
+function pruneExpired(now: number): RetainedChildSession[] {
+  const expired: RetainedChildSession[] = [];
+  for (const [id, entry] of retained) {
+    if (entry.retainedAt !== undefined && now - entry.retainedAt >= RETAIN_TTL_MS) {
+      retained.delete(id);
+      expired.push(entry);
+    }
+  }
+  return expired;
+}
+
+/**
+ * Register (or re-register) a retained child. Returns the entries DROPPED by
+ * this call — TTL-expired children plus any evicted to make room under the cap —
+ * so the caller can surface a `subagent_warning` for each (a paused `awaitInput`
+ * child whose `continue()` will now fail with "no retained subagent session").
+ * The registry has no SessionRuntime handle of its own, so it can't emit.
+ */
+export function registerRetainedChild(session: RetainedChildSession): RetainedChildSession[] {
+  const now = Date.now();
+  const evicted = pruneExpired(now);
+  const id = String(session.childSessionId);
+  // Map preserves insertion order, so the first key is the oldest. Evict
+  // oldest until we have room for this one (Map.set on an existing id is an
+  // update, not an insert, so don't count a re-register against the cap).
+  while (retained.size >= MAX_RETAINED && !retained.has(id)) {
+    const [oldestId, oldestEntry] = retained.entries().next().value ?? [];
+    if (oldestId === undefined) break;
+    retained.delete(oldestId);
+    if (oldestEntry) evicted.push(oldestEntry);
+  }
+  retained.set(id, { ...session, retainedAt: now });
+  return evicted;
 }
 
 export function getRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined {
   return retained.get(String(childSessionId));
 }
 
+/**
+ * Atomically claim a retained child for a `continue()` turn: remove it from the
+ * registry and mark it busy, so a racing `continue()`/`release()` for the same
+ * id can't observe the live entry and drive `strategy.run` over the same
+ * childLog/childCtx concurrently. Returns `undefined` if the id is unknown or
+ * already in flight.
+ */
+export function claimRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined {
+  const id = String(childSessionId);
+  if (busy.has(id)) return undefined;
+  const entry = retained.get(id);
+  if (!entry) return undefined;
+  retained.delete(id);
+  busy.add(id);
+  return entry;
+}
+
+/** Release a claim taken by {@link claimRetainedChild} (after the turn settles). */
+export function unclaimRetainedChild(childSessionId: SessionId): void {
+  busy.delete(String(childSessionId));
+}
+
 export function releaseRetainedChild(childSessionId: SessionId): void {
-  retained.delete(String(childSessionId));
+  const id = String(childSessionId);
+  retained.delete(id);
+  busy.delete(id);
 }
 
 /**
@@ -53,6 +126,7 @@ export function releaseRetainedChild(childSessionId: SessionId): void {
 export function clearRetainedChildren(parentSessionId?: SessionId): void {
   if (parentSessionId === undefined) {
     retained.clear();
+    busy.clear();
     return;
   }
   const target = String(parentSessionId);