@moxxy/core 0.3.0

package/dist/subagents/run-child.js

@@ -0,0 +1,276 @@
+/**
+ * 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 { EventLog } from '../events/log.js';
+import { newSessionId, newTurnId } from '../events/factory.js';
+import { emitSubagentCompleted, emitSubagentStart, emitSubagentWarning, streamChildEventToParent, } from './events.js';
+import { buildFilteredToolRegistry } from './tools.js';
+import { getRetainedChild, registerRetainedChild, releaseRetainedChild, } from './registry.js';
+export async function runChildTurn(args) {
+    const { rt, spec, retainSession } = args;
+    const { parentSession, parentTurnId } = rt;
+    const childSessionId = newSessionId();
+    const childTurnId = newTurnId();
+    const label = spec.label ?? `subagent-${String(childSessionId).slice(-6)}`;
+    const requestedStrategy = spec.mode ?? 'default';
+    const resolved = await resolveStrategy(parentSession, parentTurnId, label, childSessionId, spec, requestedStrategy);
+    if ('failure' in resolved)
+        return resolved.failure;
+    const { strategy, strategyName } = resolved;
+    const toolRegistry = spec.allowedTools && spec.allowedTools.length > 0
+        ? buildFilteredToolRegistry(parentSession.tools, new Set(spec.allowedTools))
+        : parentSession.tools;
+    const childModel = await resolveChildModel(rt, spec, label, childSessionId);
+    const childLog = new EventLog();
+    // The nested spawner's parentModel must be the CHILD's effective model —
+    // building it from the original rt would make grandchildren silently
+    // revert to the grandparent's model.
+    const spawner = createSubagentSpawner({ ...rt, parentModel: childModel });
+    const childCtx = buildChildContext(rt, spec, childModel, childSessionId, childTurnId, toolRegistry, childLog, spawner);
+    const capture = await executeChildLoop({
+        rt,
+        spec,
+        label,
+        childSessionId,
+        childTurnId,
+        childLog,
+        childCtx,
+        strategy,
+        strategyName,
+        emitCompleted: !retainSession,
+    });
+    if (retainSession) {
+        registerRetainedChild({
+            label,
+            childSessionId,
+            childTurnId,
+            childLog,
+            childCtx,
+            spec,
+            strategy,
+            strategyName,
+            parentSession,
+            parentTurnId,
+        });
+    }
+    return capture.result;
+}
+export async function continueChildTurn(args) {
+    const retained = getRetainedChild(args.childSessionId);
+    if (!retained) {
+        throw new Error(`no retained subagent session for "${String(args.childSessionId)}"`);
+    }
+    await retained.childLog.append({
+        type: 'user_prompt',
+        sessionId: retained.childSessionId,
+        turnId: retained.childTurnId,
+        source: 'user',
+        text: args.prompt,
+    });
+    const rt = {
+        parentSession: retained.parentSession,
+        parentTurnId: retained.parentTurnId,
+        parentSignal: retained.childCtx.signal,
+        parentModel: retained.childCtx.model,
+    };
+    const capture = await executeChildLoop({
+        rt,
+        spec: retained.spec,
+        label: args.label ?? retained.label,
+        childSessionId: retained.childSessionId,
+        childTurnId: retained.childTurnId,
+        childLog: retained.childLog,
+        childCtx: retained.childCtx,
+        strategy: retained.strategy,
+        strategyName: retained.strategyName,
+        emitCompleted: true,
+        skipStartEvent: true,
+    });
+    releaseRetainedChild(args.childSessionId);
+    return capture.result;
+}
+async function executeChildLoop(args) {
+    const { rt, spec, label, childSessionId, childTurnId, childLog, childCtx, strategy, strategyName, emitCompleted, skipStartEvent, } = args;
+    const { parentSession, parentTurnId } = rt;
+    const capture = {
+        text: '',
+        stopReason: 'end_turn',
+        error: null,
+        tokensUsed: 0,
+    };
+    const unsubCapture = childLog.subscribe((e) => {
+        if (e.type === 'assistant_message') {
+            if (e.content)
+                capture.text = e.content;
+            if (e.stopReason)
+                capture.stopReason = e.stopReason;
+        }
+        else if (e.type === 'provider_response') {
+            // Sum every provider call's tokens so the parent can show how much this
+            // child consumed (input + output, matching a context-meter reading).
+            capture.tokensUsed += (e.inputTokens ?? 0) + (e.outputTokens ?? 0);
+        }
+        else if (e.type === 'error' && e.kind === 'fatal') {
+            capture.error = e.message;
+        }
+    });
+    const unsubStream = childLog.subscribe((childEvt) => streamChildEventToParent(parentSession, parentTurnId, label, childSessionId, childEvt));
+    if (!skipStartEvent) {
+        await emitSubagentStart(parentSession, parentTurnId, label, childSessionId, spec, strategyName);
+        // Seed the child's log with its user_prompt so projection works for
+        // tool-use-style strategies (which read user_prompt events from the log).
+        await childLog.append({
+            type: 'user_prompt',
+            sessionId: childSessionId,
+            turnId: childTurnId,
+            source: 'user',
+            text: spec.prompt,
+        });
+    }
+    try {
+        for await (const _ of strategy.run(childCtx)) {
+            void _;
+        }
+    }
+    catch (err) {
+        capture.error = err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        unsubStream();
+        unsubCapture();
+    }
+    const result = {
+        label,
+        childSessionId,
+        text: capture.text,
+        stopReason: capture.error ? 'error' : capture.stopReason,
+        ...(capture.error ? { error: { message: capture.error } } : {}),
+    };
+    if (emitCompleted) {
+        await emitSubagentCompleted(parentSession, parentTurnId, label, childSessionId, capture.text, result.stopReason, capture.error, spec.agentType ?? 'default', capture.tokensUsed);
+    }
+    return { result };
+}
+async function resolveStrategy(parentSession, parentTurnId, label, childSessionId, spec, requestedStrategy) {
+    // Look up the requested strategy in the parent's loop registry. The
+    // registry only exposes list() / getActive(), so we scan.
+    const exact = parentSession.modes.list().find((s) => s.name === requestedStrategy);
+    if (exact)
+        return { strategy: exact, strategyName: requestedStrategy };
+    // Fall back to the default mode if the model invented a name
+    // (e.g. "react"). Failing the child outright wastes the user's turn —
+    // any reasonable agent task can run on the default mode. We surface the
+    // fallback as a non-fatal warning event so the operator sees it.
+    const fallback = parentSession.modes.list().find((s) => s.name === 'default');
+    if (fallback) {
+        await emitSubagentWarning(parentSession, parentTurnId, label, childSessionId, `unknown mode "${requestedStrategy}" — falling back to "default"`);
+        return { strategy: fallback, strategyName: 'default' };
+    }
+    // No default mode either — that's a config error, not a model mistake.
+    await emitSubagentStart(parentSession, parentTurnId, label, childSessionId, spec, requestedStrategy);
+    const errorMsg = `Subagent failed: unknown mode "${requestedStrategy}" and no fallback available`;
+    await emitSubagentCompleted(parentSession, parentTurnId, label, childSessionId, '', 'error', errorMsg, spec.agentType ?? 'default', 0);
+    return {
+        failure: {
+            label,
+            childSessionId,
+            text: '',
+            stopReason: 'error',
+            error: { message: errorMsg },
+        },
+    };
+}
+/**
+ * Resolve the child's effective model. A `spec.model` usually comes from the
+ * calling LLM (dispatch_agent's free-form string field), which sometimes
+ * hallucinates training-era ids ("claude-3-5-sonnet", "gpt-4o") — running the
+ * child on those would 404 or silently land on a different vendor model. When
+ * the active provider publishes a models list and the requested id isn't in
+ * it, fall back to the parent's model with a warning (mirroring the
+ * unknown-mode fallback above) instead of hard-erroring. Providers with an
+ * EMPTY models list (sparse admin-registered vendors — see the
+ * resolveModelContext caveat in @moxxy/sdk) skip validation entirely: we
+ * can't tell a typo from a legitimate unlisted id there.
+ */
+async function resolveChildModel(rt, spec, label, childSessionId) {
+    const { parentSession, parentTurnId, parentModel } = rt;
+    const requested = spec.model;
+    if (requested === undefined || requested === parentModel)
+        return parentModel;
+    const models = parentSession.providers.getActive().models;
+    if (models.length > 0 && !models.some((m) => m.id === requested)) {
+        await emitSubagentWarning(parentSession, parentTurnId, label, childSessionId, `unknown model "${requested}" — falling back to parent model "${parentModel}"`);
+        return parentModel;
+    }
+    return requested;
+}
+function buildChildContext(rt, spec, model, childSessionId, childTurnId, toolRegistry, childLog, spawner) {
+    const { parentSession, parentSignal } = rt;
+    // Children share the parent's working dir + environment — mirror them onto
+    // the child ModeContext so its tool dispatcher hands onToolCall hooks the
+    // real cwd/env (matching the parent turn) rather than empty placeholders.
+    const parentAppCtx = parentSession.appContext();
+    return {
+        sessionId: childSessionId,
+        turnId: childTurnId,
+        cwd: parentAppCtx.cwd,
+        env: parentAppCtx.env,
+        model,
+        ...(spec.systemPrompt !== undefined ? { systemPrompt: spec.systemPrompt } : {}),
+        provider: parentSession.providers.getActive(),
+        tools: toolRegistry,
+        skills: parentSession.skills,
+        log: childLog,
+        compactor: parentSession.compactors.getActive(),
+        cacheStrategy: parentSession.cacheStrategies.getActive(),
+        ...(parentSession.elisionSettings ? { elision: parentSession.elisionSettings } : {}),
+        ...(parentSession.lazyTools ? { lazyTools: true } : {}),
+        permissions: parentSession.resolver,
+        // Intentionally no `approval` — fanning approval gates out to N
+        // children in parallel would prompt the user N times. Strategies
+        // that absolutely need approval can be invoked at the parent level.
+        hooks: parentSession.dispatcher,
+        pluginHost: parentSession.pluginHost,
+        signal: parentSignal, // child cancels when parent cancels
+        maxIterations: spec.maxIterations ?? 50,
+        subagents: spawner,
+        emit: (event) => childLog.append(event),
+    };
+}
+export function createSubagentSpawner(rt) {
+    return {
+        async spawn(spec) {
+            return runChildTurn({ rt, spec, retainSession: spec.retainSession === true });
+        },
+        async spawnAll(specs) {
+            return Promise.all(specs.map((s) => runChildTurn({ rt, spec: s, retainSession: s.retainSession === true })));
+        },
+        async continue(args) {
+            return continueChildTurn(args);
+        },
+        release(childSessionId) {
+            releaseRetainedChild(childSessionId);
+        },
+    };
+}
+//# sourceMappingURL=run-child.js.map

package/dist/subagents/run-child.js.map

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

package/dist/subagents/spawn.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Back-compat entry point for the subagent runtime. The implementation lives
+ * in `run-child.ts` (which adds retained-session `continue()`/`release()` for
+ * the workflow `awaitInput` pause/resume flow); this module just re-exports it
+ * so existing `subagents/spawn.js` importers keep working.
+ */
+export { createSubagentSpawner, runChildTurn, continueChildTurn, type SubagentRuntime, } from './run-child.js';
+//# sourceMappingURL=spawn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/subagents/spawn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/subagents/spawn.js

@@ -0,0 +1,8 @@
+/**
+ * Back-compat entry point for the subagent runtime. The implementation lives
+ * in `run-child.ts` (which adds retained-session `continue()`/`release()` for
+ * the workflow `awaitInput` pause/resume flow); this module just re-exports it
+ * so existing `subagents/spawn.js` importers keep working.
+ */
+export { createSubagentSpawner, runChildTurn, continueChildTurn, } from './run-child.js';
+//# sourceMappingURL=spawn.js.map

package/dist/subagents/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/subagents/spawn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,GAElB,MAAM,gBAAgB,CAAC"}

package/dist/subagents/tools.d.ts

@@ -0,0 +1,4 @@
+import type { ToolRegistry } from '@moxxy/sdk';
+import type { ToolRegistry as CoreToolRegistry } from '../registries/tools.js';
+export declare function buildFilteredToolRegistry(parent: CoreToolRegistry, allowed: Set<string>): ToolRegistry;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/subagents/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GACnB,YAAY,CAYd"}

package/dist/subagents/tools.js

@@ -0,0 +1,13 @@
+export function buildFilteredToolRegistry(parent, allowed) {
+    return {
+        list: () => parent.list().filter((t) => allowed.has(t.name)),
+        get: (name) => allowed.has(name) ? parent.get(name) : undefined,
+        execute: (name, input, signal, opts) => {
+            if (!allowed.has(name)) {
+                return Promise.reject(new Error(`Tool ${name} not allowed in this subagent`));
+            }
+            return parent.execute(name, input, signal, opts);
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/subagents/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/subagents/tools.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,yBAAyB,CACvC,MAAwB,EACxB,OAAoB;IAEpB,OAAO;QACL,IAAI,EAAE,GAA2B,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpF,GAAG,EAAE,CAAC,IAAY,EAAuB,EAAE,CACzC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAClD,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;YACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,+BAA+B,CAAC,CAAC,CAAC;YAChF,CAAC;YACD,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/subagents.d.ts

@@ -0,0 +1,3 @@
+export { createSubagentSpawner, type SubagentRuntime } from './subagents/spawn.js';
+export { clearRetainedChildren } from './subagents/registry.js';
+//# sourceMappingURL=subagents.d.ts.map

package/dist/subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.d.ts","sourceRoot":"","sources":["../src/subagents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/subagents.js

@@ -0,0 +1,3 @@
+export { createSubagentSpawner } from './subagents/spawn.js';
+export { clearRetainedChildren } from './subagents/registry.js';
+//# sourceMappingURL=subagents.js.map

package/dist/subagents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.js","sourceRoot":"","sources":["../src/subagents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAwB,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/surfaces/host.d.ts

@@ -0,0 +1,53 @@
+import type { OpenSurfaceResult, SurfaceContext, SurfaceDataMessage, SurfaceHost, SurfaceInfo, SurfaceInputMessage, SurfaceKind, SurfaceSize } from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
+import type { SurfaceRegistryImpl } from '../registries/surfaces.js';
+/**
+ * Manages the live, open {@link SurfaceInstance}s for a Session and multiplexes
+ * every instance's output through a single {@link onData} fan-out. The runner
+ * subscribes once and rebroadcasts each frame as a `surface.data` notification;
+ * the agent's tools reach the SAME underlying resource (PTY, page) through their
+ * plugin's module state, so a `terminal`/`browser_session` tool call appears in
+ * the very pane the user is watching.
+ *
+ * Opening a kind is idempotent: a second `open` returns the instance the first
+ * created (surfaces are shared), so a late-joining viewer attaches to the
+ * existing resource and gets its {@link SurfaceInstance.snapshot}.
+ */
+export declare class SurfaceHostImpl implements SurfaceHost {
+    private readonly registry;
+    private readonly ctx;
+    private readonly logger?;
+    /** Open instances, keyed by kind (one shared instance per kind). */
+    private readonly instances;
+    /** Per-instance unsubscribe from its onData, dropped on close. */
+    private readonly unsubs;
+    private readonly dataListeners;
+    /** In-flight opens, so concurrent `open(kind)` calls share one instance. */
+    private readonly opening;
+    /**
+     * Viewer attach count per kind. A surface is SHARED (the agent's tool + every
+     * attached viewer drive the same PTY/page), so `open` retains and `close`
+     * releases; the instance is only torn down when the last viewer detaches.
+     * Without this, a single viewer's `close` would destroy the resource out from
+     * under the others — and React StrictMode (dev) makes that routine: it
+     * mounts → unmounts → remounts, so the first mount's late-resolving `open`
+     * closes the very instance the remount just attached to, leaving `input`/
+     * `resize` to hit a now-missing instance (output still flows from the
+     * snapshot, but keystrokes/navigation silently vanish).
+     */
+    private readonly refs;
+    constructor(registry: SurfaceRegistryImpl, ctx: SurfaceContext, logger?: Logger | undefined);
+    list(): Promise<ReadonlyArray<SurfaceInfo>>;
+    open(kind: SurfaceKind): Promise<OpenSurfaceResult>;
+    input(surfaceId: string, msg: SurfaceInputMessage): Promise<void>;
+    resize(surfaceId: string, size: SurfaceSize): Promise<void>;
+    close(surfaceId: string): Promise<void>;
+    /** Bump the viewer attach count for an already-open kind. */
+    private retain;
+    private describe;
+    onData(cb: (msg: SurfaceDataMessage) => void): () => void;
+    closeAll(): Promise<void>;
+    private byId;
+    private emit;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/surfaces/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/surfaces/host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,mBAAmB,EAEnB,WAAW,EACX,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAsB/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAvB1B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IACrE,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgD;IAC9E,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsD;IAC9E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;gBAGpC,QAAQ,EAAE,mBAAmB,EAC7B,GAAG,EAAE,cAAc,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA;IAG5B,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IAyB3C,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoCnD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB7C,6DAA6D;IAC7D,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,QAAQ;IAQhB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKnD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAO/B,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,IAAI;CASb"}

package/dist/surfaces/host.js

@@ -0,0 +1,177 @@
+/**
+ * Manages the live, open {@link SurfaceInstance}s for a Session and multiplexes
+ * every instance's output through a single {@link onData} fan-out. The runner
+ * subscribes once and rebroadcasts each frame as a `surface.data` notification;
+ * the agent's tools reach the SAME underlying resource (PTY, page) through their
+ * plugin's module state, so a `terminal`/`browser_session` tool call appears in
+ * the very pane the user is watching.
+ *
+ * Opening a kind is idempotent: a second `open` returns the instance the first
+ * created (surfaces are shared), so a late-joining viewer attaches to the
+ * existing resource and gets its {@link SurfaceInstance.snapshot}.
+ */
+export class SurfaceHostImpl {
+    registry;
+    ctx;
+    logger;
+    /** Open instances, keyed by kind (one shared instance per kind). */
+    instances = new Map();
+    /** Per-instance unsubscribe from its onData, dropped on close. */
+    unsubs = new Map();
+    dataListeners = new Set();
+    /** In-flight opens, so concurrent `open(kind)` calls share one instance. */
+    opening = new Map();
+    /**
+     * Viewer attach count per kind. A surface is SHARED (the agent's tool + every
+     * attached viewer drive the same PTY/page), so `open` retains and `close`
+     * releases; the instance is only torn down when the last viewer detaches.
+     * Without this, a single viewer's `close` would destroy the resource out from
+     * under the others — and React StrictMode (dev) makes that routine: it
+     * mounts → unmounts → remounts, so the first mount's late-resolving `open`
+     * closes the very instance the remount just attached to, leaving `input`/
+     * `resize` to hit a now-missing instance (output still flows from the
+     * snapshot, but keystrokes/navigation silently vanish).
+     */
+    refs = new Map();
+    constructor(registry, ctx, logger) {
+        this.registry = registry;
+        this.ctx = ctx;
+        this.logger = logger;
+    }
+    async list() {
+        const out = [];
+        for (const def of this.registry.list()) {
+            let available = true;
+            let reason;
+            if (def.isAvailable) {
+                try {
+                    const a = await def.isAvailable(this.ctx);
+                    available = a.ok;
+                    reason = a.reason;
+                }
+                catch (err) {
+                    available = false;
+                    reason = err instanceof Error ? err.message : String(err);
+                }
+            }
+            out.push({
+                kind: def.kind,
+                ...(def.description ? { description: def.description } : {}),
+                available,
+                ...(reason ? { reason } : {}),
+            });
+        }
+        return out;
+    }
+    async open(kind) {
+        const existing = this.instances.get(kind);
+        if (existing) {
+            this.retain(kind);
+            return this.describe(existing);
+        }
+        const pending = this.opening.get(kind);
+        if (pending) {
+            // Ride the in-flight create, but still count this viewer's attach.
+            const res = await pending;
+            this.retain(kind);
+            return res;
+        }
+        const def = this.registry.get(kind);
+        if (!def)
+            throw new Error(`No surface registered for kind: ${kind}`);
+        const promise = (async () => {
+            const instance = await def.open(this.ctx);
+            this.instances.set(kind, instance);
+            this.refs.set(kind, 1);
+            // Re-emit this instance's frames as multiplexed SurfaceDataMessages.
+            const unsub = instance.onData((payload) => this.emit({ surfaceId: instance.id, kind: instance.kind, payload }));
+            this.unsubs.set(instance.id, unsub);
+            return this.describe(instance);
+        })();
+        this.opening.set(kind, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.opening.delete(kind);
+        }
+    }
+    async input(surfaceId, msg) {
+        const instance = this.byId(surfaceId);
+        if (!instance)
+            return;
+        await instance.input(msg);
+    }
+    async resize(surfaceId, size) {
+        const instance = this.byId(surfaceId);
+        if (!instance?.resize)
+            return;
+        await instance.resize(size);
+    }
+    async close(surfaceId) {
+        const instance = this.byId(surfaceId);
+        if (!instance)
+            return;
+        const kind = instance.kind;
+        // Release this viewer; keep the shared instance alive while others hold it.
+        const remaining = (this.refs.get(kind) ?? 1) - 1;
+        if (remaining > 0) {
+            this.refs.set(kind, remaining);
+            return;
+        }
+        this.refs.delete(kind);
+        this.unsubs.get(surfaceId)?.();
+        this.unsubs.delete(surfaceId);
+        this.instances.delete(kind);
+        try {
+            await instance.close();
+        }
+        catch (err) {
+            this.logger?.warn?.('SurfaceHost: close failed', {
+                surfaceId,
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Bump the viewer attach count for an already-open kind. */
+    retain(kind) {
+        this.refs.set(kind, (this.refs.get(kind) ?? 0) + 1);
+    }
+    describe(instance) {
+        return {
+            surfaceId: instance.id,
+            kind: instance.kind,
+            ...(instance.snapshot ? { snapshot: instance.snapshot() } : {}),
+        };
+    }
+    onData(cb) {
+        this.dataListeners.add(cb);
+        return () => this.dataListeners.delete(cb);
+    }
+    async closeAll() {
+        // Session shutdown: tear every instance down regardless of viewer refs.
+        for (const kind of [...this.instances.keys()])
+            this.refs.set(kind, 1);
+        const ids = [...this.unsubs.keys()];
+        for (const id of ids)
+            await this.close(id);
+    }
+    byId(surfaceId) {
+        for (const instance of this.instances.values()) {
+            if (instance.id === surfaceId)
+                return instance;
+        }
+        return undefined;
+    }
+    emit(msg) {
+        for (const fn of this.dataListeners) {
+            try {
+                fn(msg);
+            }
+            catch {
+                /* a bad listener must not break the stream */
+            }
+        }
+    }
+}
+//# sourceMappingURL=host.js.map

package/dist/surfaces/host.js.map

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

package/dist/tunnel/localhost.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The default tunnel provider: no tunnel at all, just the local URL. Used when
+ * the surface and the user share a machine (TUI), or when no real tunnel
+ * (cloudflared) is configured/installed.
+ */
+export declare const localhostTunnel: import("@moxxy/sdk").TunnelProviderDef;
+//# sourceMappingURL=localhost.d.ts.map

package/dist/tunnel/localhost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localhost.d.ts","sourceRoot":"","sources":["../../src/tunnel/localhost.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,eAAe,wCAa1B,CAAC"}

package/dist/tunnel/localhost.js

@@ -0,0 +1,21 @@
+import { defineTunnelProvider } from '@moxxy/sdk';
+/**
+ * The default tunnel provider: no tunnel at all, just the local URL. Used when
+ * the surface and the user share a machine (TUI), or when no real tunnel
+ * (cloudflared) is configured/installed.
+ */
+export const localhostTunnel = defineTunnelProvider({
+    name: 'localhost',
+    open: (opts) => {
+        // Bracket an IPv6 literal host (e.g. `::1` → `[::1]`) so the `:port`
+        // delimiter is unambiguous and the result is a valid URL. A bare IPv6
+        // host (`http://::1:4040`) is rejected by most URL parsers.
+        const host = opts.host.includes(':') ? `[${opts.host}]` : opts.host;
+        return Promise.resolve({
+            url: `http://${host}:${opts.port}`,
+            close: () => Promise.resolve(),
+        });
+    },
+    isAvailable: () => Promise.resolve(true),
+});
+//# sourceMappingURL=localhost.js.map

package/dist/tunnel/localhost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localhost.js","sourceRoot":"","sources":["../../src/tunnel/localhost.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;IAClD,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QACb,qEAAqE;QACrE,sEAAsE;QACtE,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACpE,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,GAAG,EAAE,UAAU,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE;YAClC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IACD,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;CACzC,CAAC,CAAC"}