@moxxy/core 0.3.0

package/dist/skills/synthesize.js

@@ -0,0 +1,241 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { asSkillId, definePlugin, defineTool, skillFrontmatterSchema, } from '@moxxy/sdk';
+import { z } from 'zod';
+import { defaultProjectSkillsDir, defaultUserSkillsDir } from './loader.js';
+import { draftSkill } from './synthesize-draft.js';
+export async function synthesizeSkill(session, intent, scope, opts = {}, 
+/**
+ * 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) {
+    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;
+    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 = {
+        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) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+async function uniqueFilename(dir, base) {
+    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) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function appendAudit(filePath, entry) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, JSON.stringify(entry) + '\n', 'utf8');
+}
+export function buildSynthesizeSkillPlugin(session, opts = {}) {
+    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 };
+                },
+            }),
+        ],
+    });
+}
+//# sourceMappingURL=synthesize.js.map

package/dist/skills/synthesize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesize.js","sourceRoot":"","sources":["../../src/skills/synthesize.ts"],"names":[],"mappings":"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"}

package/dist/subagents/events.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Subagent <-> parent log bridge. Wraps child `MoxxyEvent`s into
+ * `plugin_event` envelopes on the parent log so the TUI / exporters can
+ * render live progress, and emits the start/completed bookend envelopes.
+ */
+import type { MoxxyEvent, SessionId, StopReason, SubagentSpec, TurnId } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+export declare const SUBAGENT_PLUGIN_ID: import("@moxxy/sdk").PluginId;
+export declare function emitSubagentStart(parentSession: SessionRuntime, parentTurnId: TurnId, label: string, childSessionId: SessionId, spec: SubagentSpec, mode: string): Promise<void>;
+export declare function emitSubagentCompleted(parentSession: SessionRuntime, parentTurnId: TurnId, label: string, childSessionId: SessionId, text: string, stopReason: StopReason, errorMessage: string | null, agentType: string, tokensUsed: number): Promise<void>;
+export declare function emitSubagentWarning(parentSession: SessionRuntime, parentTurnId: TurnId, label: string, childSessionId: SessionId, message: string): Promise<void>;
+/**
+ * Map each interesting child event to a parent `plugin_event` so the TUI
+ * can render the subagent's progress in real time. Noisy / book-keeping
+ * events (mode_iteration, provider_request, provider_response,
+ * assistant_message — covered by the explicit `subagent_completed`) are
+ * filtered out to keep the parent log lean.
+ */
+export declare function streamChildEventToParent(parentSession: SessionRuntime, parentTurnId: TurnId, label: string, childSessionId: SessionId, childEvt: MoxxyEvent): Promise<void>;
+//# sourceMappingURL=events.d.ts.map

package/dist/subagents/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/subagents/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,MAAM,EACP,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,eAAO,MAAM,kBAAkB,+BAAiC,CAAC;AAEjE,wBAAsB,iBAAiB,CACrC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,SAAS,EACzB,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,SAAS,EACzB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,aAAa,EAAE,cAAc,EAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,SAAS,EACzB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/subagents/events.js

@@ -0,0 +1,146 @@
+/**
+ * Subagent <-> parent log bridge. Wraps child `MoxxyEvent`s into
+ * `plugin_event` envelopes on the parent log so the TUI / exporters can
+ * render live progress, and emits the start/completed bookend envelopes.
+ */
+import { asPluginId } from '@moxxy/sdk';
+export const SUBAGENT_PLUGIN_ID = asPluginId('@moxxy/subagents');
+export async function emitSubagentStart(parentSession, parentTurnId, label, childSessionId, spec, mode) {
+    await parentSession.log.append({
+        type: 'plugin_event',
+        sessionId: parentSession.id,
+        turnId: parentTurnId,
+        source: 'plugin',
+        pluginId: SUBAGENT_PLUGIN_ID,
+        subtype: 'subagent_started',
+        payload: {
+            label,
+            childSessionId: String(childSessionId),
+            prompt: spec.prompt,
+            mode,
+            agentType: spec.agentType ?? 'default',
+            ...(spec.model ? { model: spec.model } : {}),
+        },
+    });
+}
+export async function emitSubagentCompleted(parentSession, parentTurnId, label, childSessionId, text, stopReason, errorMessage, agentType, tokensUsed) {
+    await parentSession.log.append({
+        type: 'plugin_event',
+        sessionId: parentSession.id,
+        turnId: parentTurnId,
+        source: 'plugin',
+        pluginId: SUBAGENT_PLUGIN_ID,
+        subtype: 'subagent_completed',
+        payload: {
+            label,
+            childSessionId: String(childSessionId),
+            text,
+            stopReason,
+            agentType,
+            tokensUsed,
+            ...(errorMessage ? { error: errorMessage } : {}),
+        },
+    });
+}
+export async function emitSubagentWarning(parentSession, parentTurnId, label, childSessionId, message) {
+    await parentSession.log.append({
+        type: 'plugin_event',
+        sessionId: parentSession.id,
+        turnId: parentTurnId,
+        source: 'plugin',
+        pluginId: SUBAGENT_PLUGIN_ID,
+        subtype: 'subagent_warning',
+        payload: {
+            label,
+            childSessionId: String(childSessionId),
+            message,
+        },
+    });
+}
+/**
+ * Map each interesting child event to a parent `plugin_event` so the TUI
+ * can render the subagent's progress in real time. Noisy / book-keeping
+ * events (mode_iteration, provider_request, provider_response,
+ * assistant_message — covered by the explicit `subagent_completed`) are
+ * filtered out to keep the parent log lean.
+ */
+export async function streamChildEventToParent(parentSession, parentTurnId, label, childSessionId, childEvt) {
+    const mapped = mapChildEvent(label, childSessionId, childEvt);
+    if (!mapped)
+        return;
+    try {
+        await parentSession.log.append({
+            type: 'plugin_event',
+            sessionId: parentSession.id,
+            turnId: parentTurnId,
+            source: 'plugin',
+            pluginId: SUBAGENT_PLUGIN_ID,
+            subtype: mapped.subtype,
+            payload: mapped.payload,
+        });
+    }
+    catch (err) {
+        // Forwarding a child progress event is best-effort: a parent-log append
+        // failure must not abort the subagent run. EventLog.append already swallows
+        // listener errors, so this rejection would otherwise vanish with zero
+        // trace (the surface just stops updating); surface it so a chronic
+        // forwarding failure during a long subagent run is at least diagnosable.
+        process.stderr.write(`moxxy: dropped subagent progress event (${mapped.subtype}) — parent log append failed: ` +
+            `${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+function mapChildEvent(label, childSessionId, childEvt) {
+    const payload = {
+        label,
+        childSessionId: String(childSessionId),
+    };
+    switch (childEvt.type) {
+        case 'assistant_chunk':
+            payload.delta = childEvt.delta;
+            return { subtype: 'subagent_chunk', payload };
+        case 'tool_call_requested':
+            payload.name = childEvt.name;
+            payload.input = childEvt.input;
+            payload.callId = String(childEvt.callId);
+            return { subtype: 'subagent_tool_call', payload };
+        case 'tool_result':
+            payload.callId = String(childEvt.callId);
+            payload.ok = childEvt.ok;
+            if (childEvt.ok)
+                payload.output = childEvt.output;
+            else
+                payload.error = childEvt.error;
+            return { subtype: 'subagent_tool_result', payload };
+        case 'error':
+            payload.kind = childEvt.kind;
+            payload.message = childEvt.message;
+            return { subtype: 'subagent_error', payload };
+        case 'abort':
+            payload.reason = childEvt.reason;
+            return { subtype: 'subagent_abort', payload };
+        case 'plugin_event':
+            return mapNestedPluginEvent(label, payload, childEvt);
+        default:
+            return null;
+    }
+}
+function mapNestedPluginEvent(label, payload, childEvt) {
+    // Bubble nested subagent events too, so a grand-child's progress
+    // surfaces all the way up. We strip the nested label-prefix to
+    // keep things compact; payload retains the chain via the embedded
+    // childSessionId.
+    const nestedSubtype = childEvt.subtype;
+    if (typeof nestedSubtype !== 'string' || !nestedSubtype.startsWith('subagent_'))
+        return null;
+    const nestedPayload = childEvt.payload;
+    if (nestedPayload && typeof nestedPayload === 'object') {
+        for (const [k, v] of Object.entries(nestedPayload)) {
+            if (k !== 'label' && k !== 'childSessionId')
+                payload[k] = v;
+        }
+        // Preserve the chain via a `via` field naming the immediate parent label.
+        payload.via = label;
+    }
+    return { subtype: nestedSubtype, payload };
+}
+//# sourceMappingURL=events.js.map

package/dist/subagents/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/subagents/events.ts"],"names":[],"mappings":"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"}

package/dist/subagents/registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Retained-child session registry — backs the `awaitInput` pause/resume flow.
+ *
+ * A subagent spawned with `retainSession: true` keeps its `EventLog` and
+ * `ModeContext` alive after its first turn so a later `continue()` can append
+ * an operator reply and run it again. The registry is a process-local map
+ * keyed by child session id; entries are dropped on `continue` or `release`.
+ *
+ * Each entry records its `parentSession`, so {@link clearRetainedChildren}
+ * drops only the children belonging to the session that is closing. The map is
+ * process-wide (one per module), but a `Session.close()` must NOT wipe another
+ * live session's paused children — that would break their `continue()` in any
+ * host that runs >1 Session per process (the desktop in-process path, tests).
+ */
+import type { ModeContext, SessionId, SubagentSpec, TurnId } from '@moxxy/sdk';
+import type { EventLog } from '../events/log.js';
+import type { SessionRuntime } from '../session-runtime.js';
+export interface RetainedChildSession {
+    readonly label: string;
+    readonly childSessionId: SessionId;
+    readonly childTurnId: TurnId;
+    readonly childLog: EventLog;
+    readonly childCtx: ModeContext;
+    readonly spec: SubagentSpec;
+    readonly strategy: ReturnType<SessionRuntime['modes']['list']>[number];
+    readonly strategyName: string;
+    readonly parentSession: SessionRuntime;
+    readonly parentTurnId: TurnId;
+}
+export declare function registerRetainedChild(session: RetainedChildSession): void;
+export declare function getRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined;
+export declare function releaseRetainedChild(childSessionId: SessionId): void;
+/**
+ * Drop retained children. With a `parentSessionId`, drop ONLY the children
+ * whose `parentSession` is that session — so one session's `close()` can't wipe
+ * another live session's paused `awaitInput` children. Without an id (legacy /
+ * test-teardown callers), clear everything.
+ */
+export declare function clearRetainedChildren(parentSessionId?: SessionId): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/subagents/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/subagents/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAE5F;AAED,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,SAAS,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,CAAC,EAAE,SAAS,GAAG,IAAI,CASvE"}

package/dist/subagents/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Retained-child session registry — backs the `awaitInput` pause/resume flow.
+ *
+ * A subagent spawned with `retainSession: true` keeps its `EventLog` and
+ * `ModeContext` alive after its first turn so a later `continue()` can append
+ * an operator reply and run it again. The registry is a process-local map
+ * keyed by child session id; entries are dropped on `continue` or `release`.
+ *
+ * Each entry records its `parentSession`, so {@link clearRetainedChildren}
+ * drops only the children belonging to the session that is closing. The map is
+ * process-wide (one per module), but a `Session.close()` must NOT wipe another
+ * live session's paused children — that would break their `continue()` in any
+ * host that runs >1 Session per process (the desktop in-process path, tests).
+ */
+const retained = new Map();
+export function registerRetainedChild(session) {
+    retained.set(String(session.childSessionId), session);
+}
+export function getRetainedChild(childSessionId) {
+    return retained.get(String(childSessionId));
+}
+export function releaseRetainedChild(childSessionId) {
+    retained.delete(String(childSessionId));
+}
+/**
+ * Drop retained children. With a `parentSessionId`, drop ONLY the children
+ * whose `parentSession` is that session — so one session's `close()` can't wipe
+ * another live session's paused `awaitInput` children. Without an id (legacy /
+ * test-teardown callers), clear everything.
+ */
+export function clearRetainedChildren(parentSessionId) {
+    if (parentSessionId === undefined) {
+        retained.clear();
+        return;
+    }
+    const target = String(parentSessionId);
+    for (const [childId, entry] of retained) {
+        if (String(entry.parentSession.id) === target)
+            retained.delete(childId);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/subagents/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/subagents/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmBH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEzD,MAAM,UAAU,qBAAqB,CAAC,OAA6B;IACjE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,cAAyB;IACxD,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,cAAyB;IAC5D,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,eAA2B;IAC/D,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;IACvC,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;QACxC,IAAI,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,MAAM;YAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/subagents/run-child.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Subagent runtime — turns the SDK's `SubagentSpawner` interface into a
+ * working factory that spawns child modes sharing the parent Session's
+ * registries.
+ *
+ * Each child gets:
+ *  - Its own `EventLog` (isolated history, no cross-talk).
+ *  - Its own `sessionId` + `turnId` (so hooks / tool ctxs see distinct ids).
+ *  - The parent's providers, tools (optionally filtered), skills, permissions,
+ *    plugin host, and abort signal.
+ *
+ * As the child runs, this module streams its events into the parent's log
+ * as `plugin_event` records with `subagent_*` subtypes — so the TUI, JSON
+ * exporters, and other subscribers see live progress without waiting for
+ * the child's final message. The captured final assistant message is
+ * returned to the spawner caller via the `SubagentResult`.
+ *
+ * A child spawned with `retainSession: true` keeps its log + context alive in
+ * the {@link RetainedChildSession} registry so `continue()` can append an
+ * operator reply and run it again — the workflow `awaitInput` pause/resume
+ * flow. `subagent_completed` is deferred until that follow-up turn (or a
+ * `release()`).
+ */
+import type { SessionId, SubagentResult, SubagentSpawner, SubagentSpec, TurnId } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+export interface SubagentRuntime {
+    readonly parentSession: SessionRuntime;
+    readonly parentTurnId: TurnId;
+    readonly parentSignal: AbortSignal;
+    readonly parentModel: string;
+}
+export declare function runChildTurn(args: {
+    rt: SubagentRuntime;
+    spec: SubagentSpec;
+    retainSession: boolean;
+}): Promise<SubagentResult>;
+export declare function continueChildTurn(args: {
+    childSessionId: SessionId;
+    prompt: string;
+    label?: string;
+}): Promise<SubagentResult>;
+export declare function createSubagentSpawner(rt: SubagentRuntime): SubagentSpawner;
+//# sourceMappingURL=run-child.d.ts.map

package/dist/subagents/run-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../../src/subagents/run-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAIV,SAAS,EAGT,cAAc,EACd,eAAe,EACf,YAAY,EAEZ,MAAM,EACP,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAe5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAMD,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,EAAE,EAAE,eAAe,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsE1B;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,cAAc,EAAE,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqC1B;AAiOD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,GAAG,eAAe,CAiB1E"}