@moxxy/sdk 0.1.0

package/dist/token-accounting.js

@@ -0,0 +1,129 @@
+/**
+ * Token accounting derived from the event log. The single source of truth is
+ * the stream of `provider_response` events (each carries the provider-reported
+ * usage for one call); cumulative session totals are just a fold over them, so
+ * there is no separate mutable counter to keep in sync.
+ *
+ * Anthropic usage semantics (which this models): `inputTokens` is the
+ * NON-cached portion of the prompt; cache reads and cache writes are reported
+ * separately and are NOT included in `inputTokens`. So the full prompt size of
+ * a call is `input + cacheRead + cacheCreation`.
+ */
+// Relative price multipliers vs. an uncached input token (Anthropic ephemeral
+// cache pricing). Kept here so the savings math is explicit and tweakable.
+const CACHE_READ_MULT = 0.1;
+const CACHE_WRITE_MULT = 1.25;
+/** Partial `provider_response` fields for a given usage; `{}` when usage is absent. */
+export function usageEventFields(usage) {
+    if (!usage)
+        return {};
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        ...(usage.cacheReadTokens !== undefined ? { cacheReadTokens: usage.cacheReadTokens } : {}),
+        ...(usage.cacheCreationTokens !== undefined
+            ? { cacheCreationTokens: usage.cacheCreationTokens }
+            : {}),
+    };
+}
+/** Fold `provider_response` events into cumulative per-session token totals. */
+export function summarizeSessionTokens(log) {
+    return foldResponses(log.ofType('provider_response'));
+}
+/**
+ * Same as {@link summarizeSessionTokens} but over a raw event array — for
+ * channels (e.g. the TUI) that hold the materialized event stream rather than
+ * an `EventLogReader`.
+ */
+export function summarizeSessionTokensFromEvents(events) {
+    return foldResponses(events.filter((e) => e.type === 'provider_response'));
+}
+const ZERO_TOTALS = {
+    calls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+};
+/** Add two {@link ModelUsageTotals} field-wise (for merging session deltas into the aggregate). */
+export function addModelTotals(a, b) {
+    return {
+        calls: a.calls + b.calls,
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+    };
+}
+/** A `provider_response` reported usage iff any token field is present. */
+function hasUsage(e) {
+    return (e.inputTokens !== undefined ||
+        e.outputTokens !== undefined ||
+        e.cacheReadTokens !== undefined ||
+        e.cacheCreationTokens !== undefined);
+}
+/**
+ * Fold `provider_response` events into per-model token totals, keyed by
+ * `"<provider>/<model>"` (the same model id can be served by more than one
+ * provider, so both pin the key). Used by the usage-stats plugin to compute a
+ * session's contribution and by the `/usage` panel to render the lifetime
+ * breakdown.
+ */
+export function summarizeTokensByModel(events) {
+    const byModel = {};
+    for (const e of events) {
+        if (e.type !== 'provider_response')
+            continue;
+        if (!hasUsage(e))
+            continue;
+        const key = `${e.provider}/${e.model}`;
+        byModel[key] = addModelTotals(byModel[key] ?? ZERO_TOTALS, {
+            calls: 1,
+            inputTokens: e.inputTokens ?? 0,
+            outputTokens: e.outputTokens ?? 0,
+            cacheReadTokens: e.cacheReadTokens ?? 0,
+            cacheCreationTokens: e.cacheCreationTokens ?? 0,
+        });
+    }
+    return byModel;
+}
+function foldResponses(responses) {
+    let calls = 0;
+    let totalInput = 0;
+    let totalCacheRead = 0;
+    let totalCacheCreation = 0;
+    let totalOutput = 0;
+    for (const e of responses) {
+        // Count a call only when it reported any token data.
+        if (e.inputTokens === undefined &&
+            e.outputTokens === undefined &&
+            e.cacheReadTokens === undefined &&
+            e.cacheCreationTokens === undefined) {
+            continue;
+        }
+        calls += 1;
+        totalInput += e.inputTokens ?? 0;
+        totalCacheRead += e.cacheReadTokens ?? 0;
+        totalCacheCreation += e.cacheCreationTokens ?? 0;
+        totalOutput += e.outputTokens ?? 0;
+    }
+    const totalPrompt = totalInput + totalCacheRead + totalCacheCreation;
+    const billedInputEq = totalInput + totalCacheRead * CACHE_READ_MULT + totalCacheCreation * CACHE_WRITE_MULT;
+    const uncachedInputEq = totalPrompt;
+    const cacheHitRate = totalPrompt > 0 ? totalCacheRead / totalPrompt : 0;
+    return {
+        calls,
+        totalInput,
+        totalCacheRead,
+        totalCacheCreation,
+        totalOutput,
+        totalPrompt,
+        cacheHitRate,
+        billedInputEq,
+        uncachedInputEq,
+        savedRatio: uncachedInputEq > 0 ? 1 - billedInputEq / uncachedInputEq : 0,
+        // Broken = writing cache but not reading it back, over enough calls.
+        cacheEffective: !(calls >= 5 && totalCacheCreation > 0 && cacheHitRate < 0.05),
+    };
+}
+//# sourceMappingURL=token-accounting.js.map

package/dist/token-accounting.js.map

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

package/dist/tool-dispatch.d.ts

@@ -0,0 +1,19 @@
+import type { MoxxyEvent } from './events.js';
+import type { ModeContext } from './mode.js';
+import type { CollectedToolUse } from './mode-helpers.js';
+/**
+ * Execute a single tool-use end-to-end: dispatch `dispatchToolCall` hooks, run
+ * the permission check, invoke the tool, and emit the approved/denied/result
+ * events. An async generator so a loop strategy can `yield*` it; callers that
+ * don't need the events can drain it (`for await (const _ of …) {}`) — either
+ * way the events reach the log via `ctx.emit`.
+ *
+ * Shared by every loop strategy (tool-use, plan-execute, developer, bmad) so
+ * the defensive outer try/catch below lives in ONE place. Without it, a throw
+ * from a hook handler / permission resolver / the emit itself escapes the
+ * generator and leaves this (and any later) call as an orphan
+ * `tool_call_requested` with no matching `tool_result` — which the provider
+ * then rejects on the next turn.
+ */
+export declare function dispatchToolCall(ctx: ModeContext, t: CollectedToolUse, iteration: number): AsyncGenerator<MoxxyEvent, void, unknown>;
+//# sourceMappingURL=tool-dispatch.d.ts.map

package/dist/tool-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dispatch.d.ts","sourceRoot":"","sources":["../src/tool-dispatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAuB,gBAAgB,CACrC,GAAG,EAAE,WAAW,EAChB,CAAC,EAAE,gBAAgB,EACnB,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAkF3C"}

package/dist/tool-dispatch.js

@@ -0,0 +1,118 @@
+import { asToolCallId } from './ids.js';
+/**
+ * Execute a single tool-use end-to-end: dispatch `dispatchToolCall` hooks, run
+ * the permission check, invoke the tool, and emit the approved/denied/result
+ * events. An async generator so a loop strategy can `yield*` it; callers that
+ * don't need the events can drain it (`for await (const _ of …) {}`) — either
+ * way the events reach the log via `ctx.emit`.
+ *
+ * Shared by every loop strategy (tool-use, plan-execute, developer, bmad) so
+ * the defensive outer try/catch below lives in ONE place. Without it, a throw
+ * from a hook handler / permission resolver / the emit itself escapes the
+ * generator and leaves this (and any later) call as an orphan
+ * `tool_call_requested` with no matching `tool_result` — which the provider
+ * then rejects on the next turn.
+ */
+export async function* dispatchToolCall(ctx, t, iteration) {
+    try {
+        const verdict = await ctx.hooks.dispatchToolCall({
+            sessionId: ctx.sessionId,
+            cwd: '',
+            log: ctx.log,
+            env: {},
+            turnId: ctx.turnId,
+            iteration,
+            call: { callId: asToolCallId(t.id), name: t.name, input: t.input },
+        });
+        const actualInput = verdict.action === 'rewrite' ? verdict.input : t.input;
+        const denyReason = hookDeny(verdict);
+        if (denyReason) {
+            yield* emitDenied(ctx, t, denyReason, 'hook');
+            return;
+        }
+        const decision = await ctx.permissions.check({ callId: asToolCallId(t.id), name: t.name, input: actualInput }, { sessionId: String(ctx.sessionId), toolDescription: ctx.tools.get(t.name)?.description });
+        if (decision.mode === 'deny') {
+            yield* emitDenied(ctx, t, decision.reason ?? 'denied by resolver', 'resolver');
+            return;
+        }
+        yield await ctx.emit({
+            type: 'tool_call_approved',
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            source: 'system',
+            callId: asToolCallId(t.id),
+            decidedBy: 'resolver',
+            mode: decision.mode,
+        });
+        try {
+            const output = await ctx.tools.execute(t.name, actualInput, ctx.signal, {
+                callId: t.id,
+                sessionId: String(ctx.sessionId),
+                turnId: String(ctx.turnId),
+                log: ctx.log,
+                ...(ctx.subagents ? { subagents: ctx.subagents } : {}),
+            });
+            yield await ctx.emit({
+                type: 'tool_result',
+                sessionId: ctx.sessionId,
+                turnId: ctx.turnId,
+                source: 'tool',
+                callId: asToolCallId(t.id),
+                ok: true,
+                output,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const kind = ctx.signal.aborted ? 'aborted' : 'threw';
+            yield await ctx.emit({
+                type: 'tool_result',
+                sessionId: ctx.sessionId,
+                turnId: ctx.turnId,
+                source: 'tool',
+                callId: asToolCallId(t.id),
+                ok: false,
+                error: { kind, message },
+            });
+        }
+    }
+    catch (err) {
+        // Defensive: a hook handler, permission resolver, or the emit itself threw
+        // before we could produce a tool_result. Synthesize a failed result so the
+        // event log stays well-formed (no orphan tool_call_requested).
+        const message = err instanceof Error ? err.message : String(err);
+        yield await ctx.emit({
+            type: 'tool_result',
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            source: 'tool',
+            callId: asToolCallId(t.id),
+            ok: false,
+            error: { kind: 'threw', message: `pre-execute failure: ${message}` },
+        });
+    }
+}
+function hookDeny(verdict) {
+    return verdict.action === 'deny' ? verdict.reason : null;
+}
+async function* emitDenied(ctx, t, reason, by) {
+    yield await ctx.emit({
+        type: 'tool_call_denied',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        callId: asToolCallId(t.id),
+        decidedBy: by,
+        reason,
+    });
+    yield await ctx.emit({
+        type: 'tool_result',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'tool',
+        callId: asToolCallId(t.id),
+        ok: false,
+        error: { kind: 'denied', message: reason },
+    });
+}
+//# sourceMappingURL=tool-dispatch.js.map

package/dist/tool-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-dispatch.js","sourceRoot":"","sources":["../src/tool-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAMxC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,gBAAgB,CACrC,GAAgB,EAChB,CAAmB,EACnB,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC;YAC/C,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,GAAG,EAAE,EAAE;YACP,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,GAAG,EAAE,EAAE;YACP,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS;YACT,IAAI,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE;SACnE,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAE3E,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,KAAK,CAC1C,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAChE,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAC1F,CAAC;QACF,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7B,KAAK,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,MAAM,IAAI,oBAAoB,EAAE,UAAU,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,oBAAoB;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1B,SAAS,EAAE,UAAU;YACrB,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE;gBACtE,MAAM,EAAE,CAAC,CAAC,EAAE;gBACZ,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;gBAChC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC1B,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvD,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;gBACnB,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1B,EAAE,EAAE,IAAI;gBACR,MAAM;aACP,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,IAAI,GAAwB,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;YAC3E,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;gBACnB,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1B,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,2EAA2E;QAC3E,2EAA2E;QAC3E,+DAA+D;QAC/D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1B,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,OAAO,EAAE,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,OAAwB;IACxC,OAAO,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED,KAAK,SAAS,CAAC,CAAC,UAAU,CACxB,GAAgB,EAChB,CAAmB,EACnB,MAAc,EACd,EAAkC;IAElC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;QACnB,IAAI,EAAE,kBAAkB;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,QAAQ;QAChB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1B,SAAS,EAAE,EAAE;QACb,MAAM;KACP,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC;QACnB,IAAI,EAAE,aAAa;QACnB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1B,EAAE,EAAE,KAAK;QACT,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;KAC3C,CAAC,CAAC;AACL,CAAC"}

package/dist/tool-gating.d.ts

@@ -0,0 +1,32 @@
+import type { EventLogReader } from './log.js';
+import type { ProviderMessage } from './provider.js';
+import type { ToolDef } from './tool.js';
+/**
+ * Lazy tool loading (request-scoped tool selection). Mirrors the skill
+ * lazy-load idiom: instead of sending every tool schema on every call, send a
+ * small always-on core plus whatever the model has explicitly loaded, and put
+ * a compact one-line index of the rest in the system prompt. The model calls
+ * `load_tool({ name })` to pull a schema in before using it.
+ *
+ * "Loaded" state is derived from the log (the `load_tool` calls), not a
+ * separate mutable store — so projection stays a pure function of the log, the
+ * same property that makes elision and caching deterministic.
+ */
+/** Core tools always sent in full — the agent's baseline capability + the
+ * loaders themselves. Everything else is lazy-loadable when gating is on. */
+export declare const ALWAYS_ON_TOOLS: ReadonlySet<string>;
+/** Tool names the model has loaded this session (from `load_tool` calls). */
+export declare function loadedToolNames(log: EventLogReader): ReadonlySet<string>;
+/** Compact index (name + 1-line description) of not-yet-loaded tools. */
+export declare function buildToolIndex(hidden: ReadonlyArray<ToolDef>): string;
+export interface GatedTools {
+    readonly messages: ReadonlyArray<ProviderMessage>;
+    readonly tools: ReadonlyArray<ToolDef>;
+}
+/**
+ * Apply lazy tool gating: keep always-on + loaded tools in the request, move
+ * the rest into a system-prompt index. No-op (returns inputs) when nothing is
+ * gated, so the system prompt stays byte-stable on turns that load nothing.
+ */
+export declare function applyLazyTools(messages: ReadonlyArray<ProviderMessage>, tools: ReadonlyArray<ToolDef>, log: EventLogReader): GatedTools;
+//# sourceMappingURL=tool-gating.d.ts.map

package/dist/tool-gating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-gating.d.ts","sourceRoot":"","sources":["../src/tool-gating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;GAUG;AAEH;6EAC6E;AAC7E,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAW9C,CAAC;AAEH,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,WAAW,CAAC,MAAM,CAAC,CAUxE;AAUD,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,MAAM,CAUrE;AAuBD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,EACxC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAC7B,GAAG,EAAE,cAAc,GAClB,UAAU,CAMZ"}

package/dist/tool-gating.js

@@ -0,0 +1,83 @@
+/**
+ * Lazy tool loading (request-scoped tool selection). Mirrors the skill
+ * lazy-load idiom: instead of sending every tool schema on every call, send a
+ * small always-on core plus whatever the model has explicitly loaded, and put
+ * a compact one-line index of the rest in the system prompt. The model calls
+ * `load_tool({ name })` to pull a schema in before using it.
+ *
+ * "Loaded" state is derived from the log (the `load_tool` calls), not a
+ * separate mutable store — so projection stays a pure function of the log, the
+ * same property that makes elision and caching deterministic.
+ */
+/** Core tools always sent in full — the agent's baseline capability + the
+ * loaders themselves. Everything else is lazy-loadable when gating is on. */
+export const ALWAYS_ON_TOOLS = new Set([
+    'Read',
+    'Write',
+    'Edit',
+    'Bash',
+    'Grep',
+    'Glob',
+    'recall',
+    'load_skill',
+    'load_tool',
+    'dispatch_agent',
+]);
+/** Tool names the model has loaded this session (from `load_tool` calls). */
+export function loadedToolNames(log) {
+    const names = new Set();
+    for (const e of log.ofType('tool_call_requested')) {
+        if (e.name !== 'load_tool')
+            continue;
+        const input = e.input;
+        if (input && typeof input === 'object' && typeof input.name === 'string') {
+            names.add(input.name);
+        }
+    }
+    return names;
+}
+function oneLine(s) {
+    return s.replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}
+/** Compact index (name + 1-line description) of not-yet-loaded tools. */
+export function buildToolIndex(hidden) {
+    const lines = hidden
+        .map((t) => `- **${t.name}** — ${truncate(oneLine(t.description ?? ''), 100)}`)
+        .join('\n');
+    return (`## Loadable tools\n\n` +
+        `These tools exist but their full schemas are not loaded right now. When a ` +
+        `task needs one, call \`load_tool({ name: "<tool-name>" })\` first, then call ` +
+        `the tool on the next turn.\n\n${lines}`);
+}
+function injectIntoSystem(messages, index) {
+    const out = messages.map((m) => m);
+    const sysIdx = out.findIndex((m) => m.role === 'system');
+    if (sysIdx >= 0) {
+        const sys = out[sysIdx];
+        const content = sys.content.map((b) => b.type === 'text' ? { ...b, text: `${b.text}\n\n${index}` } : b);
+        // If there was no text block, append one.
+        if (!sys.content.some((b) => b.type === 'text')) {
+            content.push({ type: 'text', text: index });
+        }
+        out[sysIdx] = { role: 'system', content };
+        return out;
+    }
+    return [{ role: 'system', content: [{ type: 'text', text: index }] }, ...out];
+}
+/**
+ * Apply lazy tool gating: keep always-on + loaded tools in the request, move
+ * the rest into a system-prompt index. No-op (returns inputs) when nothing is
+ * gated, so the system prompt stays byte-stable on turns that load nothing.
+ */
+export function applyLazyTools(messages, tools, log) {
+    const loaded = loadedToolNames(log);
+    const hidden = tools.filter((t) => !ALWAYS_ON_TOOLS.has(t.name) && !loaded.has(t.name));
+    if (hidden.length === 0)
+        return { messages, tools };
+    const visible = tools.filter((t) => ALWAYS_ON_TOOLS.has(t.name) || loaded.has(t.name));
+    return { messages: injectIntoSystem(messages, buildToolIndex(hidden)), tools: visible };
+}
+//# sourceMappingURL=tool-gating.js.map

package/dist/tool-gating.js.map

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

package/dist/tool.d.ts

@@ -0,0 +1,166 @@
+import type { z } from 'zod';
+import type { EventLogReader } from './log.js';
+import type { PermissionRule } from './permission.js';
+import type { SessionId, ToolCallId, TurnId } from './ids.js';
+import type { SubagentSpawner } from './subagent.js';
+import type { ToolIsolationSpec } from './isolation.js';
+/**
+ * Capability-mediated filesystem operations injected by isolators that
+ * support brokering. Handlers can opt in by checking `ctx.fs` at runtime
+ * and using these instead of `node:fs`; the broker validates each call
+ * against the tool's declared `caps.fs` spec on the parent side before
+ * executing.
+ *
+ * When `ctx.fs` is undefined (the `none`/`inproc` paths today, or any
+ * isolator that hasn't implemented a broker yet), handlers fall back to
+ * unmediated direct fs access.
+ */
+export interface BrokeredFs {
+    /** Read a UTF-8 file. Throws if the path is outside `caps.fs.read`. */
+    readFile(filePath: string, opts?: {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    /** Write a UTF-8 file (creates parent dirs). Throws if outside `caps.fs.write`. */
+    writeFile(filePath: string, data: string): Promise<void>;
+    /** List entries in a directory. Throws if outside `caps.fs.read`. */
+    readdir(dirPath: string): Promise<ReadonlyArray<string>>;
+    /** Stat a path. Throws if outside `caps.fs.read`. */
+    stat(filePath: string): Promise<BrokeredStat>;
+}
+export interface BrokeredStat {
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+}
+/**
+ * Capability-mediated `fetch`. Same shape as the global, but validated
+ * against `caps.net` on the parent side before the socket is opened.
+ *
+ * Returns a plain JSON-serializable response shape rather than the
+ * standard `Response` object — that's the price of crossing a process
+ * boundary cleanly.
+ */
+export interface BrokeredFetch {
+    (url: string, init?: BrokeredFetchInit): Promise<BrokeredFetchResponse>;
+}
+export interface BrokeredFetchInit {
+    readonly method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+export interface BrokeredFetchResponse {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/**
+ * Capability-mediated subprocess `exec`. Validated against `caps.subprocess`
+ * (must be true) and optional `caps.commands` allowlist on the parent side.
+ * Collects stdout/stderr and the exit code; for streaming use cases the
+ * broker layer will grow a separate streaming variant later.
+ */
+export interface BrokeredExec {
+    (command: string, args?: ReadonlyArray<string>, opts?: BrokeredExecOpts): Promise<BrokeredExecResult>;
+}
+export interface BrokeredExecOpts {
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly timeoutMs?: number;
+}
+export interface BrokeredExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+}
+export interface ToolContext {
+    readonly sessionId: SessionId;
+    readonly turnId: TurnId;
+    readonly callId: ToolCallId;
+    readonly cwd: string;
+    readonly signal: AbortSignal;
+    readonly log: EventLogReader;
+    readonly logger: {
+        debug(msg: string, meta?: Record<string, unknown>): void;
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+    /**
+     * Spawner for child agents — present when the tool was invoked inside
+     * a run-turn loop (the normal case). Tools that fan work out (e.g.
+     * `dispatch_agent`) call `subagents.spawn(...)` to start a focused
+     * child loop and stream its events back to the parent log.
+     */
+    readonly subagents?: SubagentSpawner;
+    /**
+     * Capability-mediated filesystem ops. Present only when the active
+     * isolator implements a broker (currently `@moxxy/isolator-worker`).
+     * Handlers that use this get their fs access checked against
+     * `caps.fs` at every call, regardless of whether the path appeared
+     * in the validated input. Absent → handler is on its own for fs
+     * access (today's behavior).
+     */
+    readonly fs?: BrokeredFs;
+    /**
+     * Capability-mediated network. Present only when the active
+     * isolator implements a broker. Validates every URL against
+     * `caps.net` on the parent side. Returns a serializable response
+     * shape so the same value crosses a process boundary intact.
+     */
+    readonly fetch?: BrokeredFetch;
+    /**
+     * Capability-mediated subprocess execution. Present only when the
+     * active isolator implements a broker. Validated against
+     * `caps.subprocess` + optional `caps.commands` allowlist.
+     */
+    readonly exec?: BrokeredExec;
+}
+/**
+ * Optional presentation hint for compact rendering in TUI/chat surfaces.
+ * When present, the channel may aggregate consecutive calls of this tool
+ * into one "live block" with a verb+count summary, rather than rendering
+ * each call separately. Opting in is per-tool: noisy small-output tools
+ * (Read, Grep, Glob, Edit) benefit; tools with rich output (Bash,
+ * dispatch_agent) generally don't.
+ *
+ * Channels MAY ignore this hint — it's purely presentational. The event
+ * log and provider serialization don't see it.
+ */
+export interface ToolCompactPresentation {
+    /** Present-participle verb used in summary, e.g. "Reading", "Searching for". */
+    readonly verb: string;
+    /** Noun for the count, pluralized e.g. `{ one: 'file', other: 'files' }`. */
+    readonly noun: {
+        readonly one: string;
+        readonly other: string;
+    };
+    /** Input field whose value previews the latest call (the line under the summary).
+     *  e.g. `"file_path"` for Read so the preview shows the file just read. */
+    readonly previewKey?: string;
+}
+export interface ToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodTypeAny;
+    /**
+     * Optional native JSON Schema. When present, providers serializing tools to
+     * their API should use this instead of converting `inputSchema` via zod.
+     * Useful for tools originating from external systems (e.g., MCP) that already
+     * carry a JSON Schema and where zod conversion would be lossy.
+     */
+    readonly inputJsonSchema?: unknown;
+    readonly outputSchema?: z.ZodTypeAny;
+    readonly permission?: PermissionRule;
+    readonly handler: (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown;
+    /** Opt-in presentation hint. See `ToolCompactPresentation`. */
+    readonly compact?: ToolCompactPresentation;
+    /**
+     * Optional capability declaration. Advisory unless the user enables
+     * `@moxxy/plugin-security`, at which point the active `Isolator`
+     * enforces these bounds at every call. See `ToolIsolationSpec`.
+     */
+    readonly isolation?: ToolIsolationSpec;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

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

package/dist/tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":""}