@a1hvdy/cc-openclaw 0.10.4 → 0.12.0

package/dist/src/lifecycle/phase-validate-upstream.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Phase 3 — validate-upstream
+ *
+ * Runs PatchManifest.validate() against the imported upstream namespace.
+ * Re-throws validation failures as DriftError (already typed by PatchManifest).
+ *
+ * Boot refuses and surfaces a drift report if ANY probe fails.
+ * install() is NEVER called from this phase — that is phase 4.
+ */
+import type { PatchManifest } from './patch-manifest.js';
+export declare function validateUpstream(manifest: PatchManifest, _upstreamNs: unknown): Promise<void>;

package/dist/src/lifecycle/phase-validate-upstream.js

@@ -0,0 +1,16 @@
+/**
+ * Phase 3 — validate-upstream
+ *
+ * Runs PatchManifest.validate() against the imported upstream namespace.
+ * Re-throws validation failures as DriftError (already typed by PatchManifest).
+ *
+ * Boot refuses and surfaces a drift report if ANY probe fails.
+ * install() is NEVER called from this phase — that is phase 4.
+ */
+export async function validateUpstream(manifest, _upstreamNs) {
+    // upstreamNs is unused at this layer — each PatchSpec resolves its own
+    // target via PatchSpec.resolve(). The parameter is kept in the signature
+    // for boot.ts wiring symmetry.
+    await manifest.validate();
+}
+//# sourceMappingURL=phase-validate-upstream.js.map

package/dist/src/lifecycle/phase-validate-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-validate-upstream.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-validate-upstream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAuB,EACvB,WAAoB;IAEpB,uEAAuE;IACvE,yEAAyE;IACzE,+BAA+B;IAC/B,MAAM,QAAQ,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/src/lifecycle/phase-wire-handlers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Phase 5 — wire-handlers
+ *
+ * Registers EventBus subscribers BEFORE the server starts accepting traffic
+ * (phase 6). This ordering closes the v0.6.0 subscription-vs-traffic race
+ * where SessionCaptureSubscriber missed early session events.
+ *
+ * Phase E wires the real subscribers (SessionCaptureSubscriber, MetricsSubscriber).
+ * This scaffold calls ObservabilityService.init(bus) which registers stubs.
+ */
+import type { EventBus } from '../observability/event-bus.js';
+export declare function wireHandlers(bus: EventBus): void;

package/dist/src/lifecycle/phase-wire-handlers.js

@@ -0,0 +1,16 @@
+/**
+ * Phase 5 — wire-handlers
+ *
+ * Registers EventBus subscribers BEFORE the server starts accepting traffic
+ * (phase 6). This ordering closes the v0.6.0 subscription-vs-traffic race
+ * where SessionCaptureSubscriber missed early session events.
+ *
+ * Phase E wires the real subscribers (SessionCaptureSubscriber, MetricsSubscriber).
+ * This scaffold calls ObservabilityService.init(bus) which registers stubs.
+ */
+import { ObservabilityService } from '../observability/observability-service.js';
+export function wireHandlers(bus) {
+    const svc = new ObservabilityService();
+    svc.init(bus);
+}
+//# sourceMappingURL=phase-wire-handlers.js.map

package/dist/src/lifecycle/phase-wire-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-wire-handlers.js","sourceRoot":"","sources":["../../../src/lifecycle/phase-wire-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,MAAM,UAAU,YAAY,CAAC,GAAa;IACxC,MAAM,GAAG,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACvC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChB,CAAC"}

package/dist/src/observability/event-bus.d.ts

@@ -0,0 +1,65 @@
+/**
+ * EventBus — typed event emitter replacing all globalThis.__openclaw_* Maps.
+ *
+ * Contract (PRP §3.2 G4):
+ *   - on<K>(event, listener) returns an unsubscribe function (no EventEmitter leak)
+ *   - emit<K>(event, payload) is synchronous; delivery <1ms target
+ *   - Subscribers wired in boot phase 5 BEFORE traffic (phase 6 start-server)
+ *
+ * EventMap keys use dot-notation: "session.started", "boot.ready", etc.
+ * Adding a new event requires only a type entry here — no subclass needed.
+ */
+import type { Config } from '../config/schema.js';
+type SessionName = string & {
+    readonly __brand: 'SessionName';
+};
+export type EventMap = {
+    /** Emitted when a Claude CLI session subprocess starts. `pid` is `null`
+     * when the underlying ISession adapter doesn't expose a process id yet. */
+    'session.started': {
+        name: SessionName;
+        pid: number | null;
+    };
+    /** Emitted when a session subprocess exits cleanly. */
+    'session.completed': {
+        name: SessionName;
+        tokens: number;
+    };
+    /** Emitted on every tool_use event within a session turn. */
+    'session.tool-use': {
+        name: SessionName;
+        tool: string;
+        input: unknown;
+    };
+    /** Emitted after PatchManifest.install() succeeds for a single spec. */
+    'patch.installed': {
+        id: string;
+    };
+    /** Emitted when a PatchSpec probe fails during validate-upstream. */
+    'patch.drift': {
+        id: string;
+        expected: string;
+        actual: string;
+    };
+    /** Emitted at the end of a successful 7-phase boot. */
+    'boot.ready': {
+        config: Config;
+    };
+};
+type Listener<K extends keyof EventMap> = (payload: EventMap[K]) => void;
+export declare class EventBus {
+    private readonly listeners;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     * Calling the returned function is idempotent.
+     */
+    on<K extends keyof EventMap>(event: K, listener: Listener<K>): () => void;
+    /**
+     * Emit an event synchronously. All listeners receive the payload in
+     * registration order. Errors in listeners propagate to the caller.
+     */
+    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
+    /** Number of active listeners across all event keys. */
+    get listenerCount(): number;
+}
+export {};

package/dist/src/observability/event-bus.js

@@ -0,0 +1,52 @@
+/**
+ * EventBus — typed event emitter replacing all globalThis.__openclaw_* Maps.
+ *
+ * Contract (PRP §3.2 G4):
+ *   - on<K>(event, listener) returns an unsubscribe function (no EventEmitter leak)
+ *   - emit<K>(event, payload) is synchronous; delivery <1ms target
+ *   - Subscribers wired in boot phase 5 BEFORE traffic (phase 6 start-server)
+ *
+ * EventMap keys use dot-notation: "session.started", "boot.ready", etc.
+ * Adding a new event requires only a type entry here — no subclass needed.
+ */
+// ── EventBus class ────────────────────────────────────────────────────────────
+export class EventBus {
+    listeners = new Map();
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     * Calling the returned function is idempotent.
+     */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        // Cast: the Set stores Listener<keyof EventMap>; narrowed by K on emit.
+        set.add(listener);
+        return () => {
+            set.delete(listener);
+        };
+    }
+    /**
+     * Emit an event synchronously. All listeners receive the payload in
+     * registration order. Errors in listeners propagate to the caller.
+     */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const listener of set) {
+            listener(payload);
+        }
+    }
+    /** Number of active listeners across all event keys. */
+    get listenerCount() {
+        let total = 0;
+        for (const set of this.listeners.values()) {
+            total += set.size;
+        }
+        return total;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/src/observability/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../src/observability/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA+BH,iFAAiF;AAEjF,MAAM,OAAO,QAAQ;IACF,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;IAEtF;;;OAGG;IACH,EAAE,CAA2B,KAAQ,EAAE,QAAqB;QAC1D,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,wEAAwE;QACvE,GAAwB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAExC,OAAO,GAAG,EAAE;YACT,GAAwB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,IAAI,CAA2B,KAAQ,EAAE,OAAoB;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC1B,QAAwB,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,IAAI,aAAa;QACf,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,KAAK,IAAI,GAAG,CAAC,IAAI,CAAC;QACpB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/src/observability/get-event-bus.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `getEventBus()` — process-wide singleton accessor for the EventBus.
+ *
+ * Phase E#5 (v0.12.0): the EventBus moves from scaffold to hot path. This
+ * module is the bootstrap seam: every hot-path callsite that emits a typed
+ * event imports this accessor instead of constructing its own EventBus.
+ *
+ * The singleton replaces the long-deprecated `globalThis.__openclaw_*` Map
+ * pattern. Listeners must be registered before traffic starts (boot phase 5
+ * per PRP §3.4); subscribers added later still work but may miss events
+ * fired during a race window.
+ *
+ * Test isolation: vitest unit tests can call `__resetEventBusForTests()` to
+ * drop all listeners between cases. Production code never calls it.
+ */
+import { EventBus } from './event-bus.js';
+/**
+ * Returns the singleton EventBus. Lazy-initializes on first call.
+ */
+export declare function getEventBus(): EventBus;
+/**
+ * Test-only helper. Drops the singleton so each test starts with zero
+ * listeners. Never call from production code.
+ */
+export declare function __resetEventBusForTests(): void;

package/dist/src/observability/get-event-bus.js

@@ -0,0 +1,34 @@
+/**
+ * `getEventBus()` — process-wide singleton accessor for the EventBus.
+ *
+ * Phase E#5 (v0.12.0): the EventBus moves from scaffold to hot path. This
+ * module is the bootstrap seam: every hot-path callsite that emits a typed
+ * event imports this accessor instead of constructing its own EventBus.
+ *
+ * The singleton replaces the long-deprecated `globalThis.__openclaw_*` Map
+ * pattern. Listeners must be registered before traffic starts (boot phase 5
+ * per PRP §3.4); subscribers added later still work but may miss events
+ * fired during a race window.
+ *
+ * Test isolation: vitest unit tests can call `__resetEventBusForTests()` to
+ * drop all listeners between cases. Production code never calls it.
+ */
+import { EventBus } from './event-bus.js';
+let _instance = null;
+/**
+ * Returns the singleton EventBus. Lazy-initializes on first call.
+ */
+export function getEventBus() {
+    if (!_instance) {
+        _instance = new EventBus();
+    }
+    return _instance;
+}
+/**
+ * Test-only helper. Drops the singleton so each test starts with zero
+ * listeners. Never call from production code.
+ */
+export function __resetEventBusForTests() {
+    _instance = null;
+}
+//# sourceMappingURL=get-event-bus.js.map

package/dist/src/observability/get-event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-event-bus.js","sourceRoot":"","sources":["../../../src/observability/get-event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,IAAI,SAAS,GAAoB,IAAI,CAAC;AAEtC;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC"}

package/dist/src/observability/observability-service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ObservabilityService — composes EventBus + all subscribers.
+ *
+ * init(bus) is called in boot phase 5 (wire-handlers) before the server
+ * starts accepting traffic. This ordering closes the subscription-vs-traffic
+ * race that existed prior to v0.6.0.
+ *
+ * Phase E wires real subscriber logic; stubs here keep build green.
+ */
+import type { EventBus } from './event-bus.js';
+export declare class ObservabilityService {
+    private readonly sessionCapture;
+    private readonly metrics;
+    /**
+     * Register all subscribers against the provided bus.
+     * Must be called before traffic is accepted (boot phase 5).
+     */
+    init(bus: EventBus): void;
+}

package/dist/src/observability/observability-service.js

@@ -0,0 +1,24 @@
+/**
+ * ObservabilityService — composes EventBus + all subscribers.
+ *
+ * init(bus) is called in boot phase 5 (wire-handlers) before the server
+ * starts accepting traffic. This ordering closes the subscription-vs-traffic
+ * race that existed prior to v0.6.0.
+ *
+ * Phase E wires real subscriber logic; stubs here keep build green.
+ */
+import { SessionCaptureSubscriber } from './subscribers/session-capture.js';
+import { MetricsSubscriber } from './subscribers/metrics.js';
+export class ObservabilityService {
+    sessionCapture = new SessionCaptureSubscriber();
+    metrics = new MetricsSubscriber();
+    /**
+     * Register all subscribers against the provided bus.
+     * Must be called before traffic is accepted (boot phase 5).
+     */
+    init(bus) {
+        this.sessionCapture.register(bus);
+        this.metrics.register(bus);
+    }
+}
+//# sourceMappingURL=observability-service.js.map

package/dist/src/observability/observability-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-service.js","sourceRoot":"","sources":["../../../src/observability/observability-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,OAAO,oBAAoB;IACd,cAAc,GAAG,IAAI,wBAAwB,EAAE,CAAC;IAChD,OAAO,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAEnD;;;OAGG;IACH,IAAI,CAAC,GAAa;QAChB,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/observability/subscribers/metrics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MetricsSubscriber — collects per-session token and timing metrics.
+ *
+ * Replaces globalThis.__openclaw_perfMap (AS2).
+ * Phase E wires real aggregation and exposes metrics via /enhancer/metrics.
+ * Stub body here.
+ */
+import type { EventBus } from '../event-bus.js';
+export declare class MetricsSubscriber {
+    register(bus: EventBus): void;
+}

package/dist/src/observability/subscribers/metrics.js

@@ -0,0 +1,21 @@
+/**
+ * MetricsSubscriber — collects per-session token and timing metrics.
+ *
+ * Replaces globalThis.__openclaw_perfMap (AS2).
+ * Phase E wires real aggregation and exposes metrics via /enhancer/metrics.
+ * Stub body here.
+ */
+export class MetricsSubscriber {
+    register(bus) {
+        bus.on('session.completed', (_payload) => {
+            // Phase E: accumulate token counts, compute latency, update perfMap.
+        });
+        bus.on('patch.installed', (_payload) => {
+            // Phase E: record patch install time for cold-start budget tracking.
+        });
+        bus.on('patch.drift', (_payload) => {
+            // Phase E: emit warning to Telegram live-card or log file.
+        });
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/observability/subscribers/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../../src/observability/subscribers/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,iBAAiB;IAC5B,QAAQ,CAAC,GAAa;QACpB,GAAG,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,EAAE;YACvC,qEAAqE;QACvE,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE;YACrC,qEAAqE;QACvE,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,EAAE;YACjC,2DAA2D;QAC7D,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/observability/subscribers/session-capture.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SessionCaptureSubscriber — replaces the 5s ultrareview poller (LP2).
+ *
+ * Wired in boot phase 5 (wire-handlers) BEFORE traffic starts.
+ * Phase E implements the real capture logic (writing to SessionRegistry WAL,
+ * updating live-card state, etc.). Stub body here.
+ */
+import type { EventBus } from '../event-bus.js';
+export declare class SessionCaptureSubscriber {
+    /**
+     * Register listeners on the bus. Returns nothing; unsubscribe handles
+     * are held internally (Phase E: stored for clean shutdown).
+     */
+    register(bus: EventBus): void;
+}

package/dist/src/observability/subscribers/session-capture.js

@@ -0,0 +1,25 @@
+/**
+ * SessionCaptureSubscriber — replaces the 5s ultrareview poller (LP2).
+ *
+ * Wired in boot phase 5 (wire-handlers) BEFORE traffic starts.
+ * Phase E implements the real capture logic (writing to SessionRegistry WAL,
+ * updating live-card state, etc.). Stub body here.
+ */
+export class SessionCaptureSubscriber {
+    /**
+     * Register listeners on the bus. Returns nothing; unsubscribe handles
+     * are held internally (Phase E: stored for clean shutdown).
+     */
+    register(bus) {
+        bus.on('session.started', (_payload) => {
+            // Phase E: persist session start to SessionRegistry WAL.
+        });
+        bus.on('session.completed', (_payload) => {
+            // Phase E: finalize WAL entry, trigger snapshot if N-minute threshold met.
+        });
+        bus.on('session.tool-use', (_payload) => {
+            // Phase E: update live-card tool tracker, emit metrics.
+        });
+    }
+}
+//# sourceMappingURL=session-capture.js.map

package/dist/src/observability/subscribers/session-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-capture.js","sourceRoot":"","sources":["../../../../src/observability/subscribers/session-capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,wBAAwB;IACnC;;;OAGG;IACH,QAAQ,CAAC,GAAa;QACpB,GAAG,CAAC,EAAE,CAAC,iBAAiB,EAAE,CAAC,QAAQ,EAAE,EAAE;YACrC,yDAAyD;QAC3D,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,EAAE;YACvC,2EAA2E;QAC7E,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC,QAAQ,EAAE,EAAE;YACtC,wDAAwD;QAC1D,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/openai-compat/bridges/allowlist.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenClaw native tool allowList — typed-config-driven (Phase E #1, Q1 resolution).
+ *
+ * Reads from `ConfigService.config.nativeToolsAllowList` when available;
+ * falls back to the v0.11.x hardcoded default when `ConfigService` is unset
+ * (tests, scripts run without a boot path). The hardcoded fallback is
+ * intentionally identical to what shipped at v0.11.0 so existing tests that
+ * import `OPENCLAW_TOOL_ALLOWLIST` keep passing without rewrite.
+ *
+ * Env override: `CC_OPENCLAW_NATIVE_TOOLS_ALLOWLIST="message.voice,message.image,..."`.
+ * Q1 expanded default ships at v1.0.0-rc1 alongside the `CC_OPENCLAW_NATIVE_TOOLS=1` flip.
+ */
+/**
+ * v0.11.x default — kept exported for legacy callers and for the
+ * `ConfigService`-unset fallback path. New code should call `isAllowedTool`.
+ */
+export declare const OPENCLAW_TOOL_ALLOWLIST: ReadonlySet<string>;
+/** Return true when `toolName` is in the active allowList. */
+export declare function isAllowedTool(toolName: string): boolean;

package/dist/src/openai-compat/bridges/allowlist.js

@@ -0,0 +1,28 @@
+/**
+ * OpenClaw native tool allowList — typed-config-driven (Phase E #1, Q1 resolution).
+ *
+ * Reads from `ConfigService.config.nativeToolsAllowList` when available;
+ * falls back to the v0.11.x hardcoded default when `ConfigService` is unset
+ * (tests, scripts run without a boot path). The hardcoded fallback is
+ * intentionally identical to what shipped at v0.11.0 so existing tests that
+ * import `OPENCLAW_TOOL_ALLOWLIST` keep passing without rewrite.
+ *
+ * Env override: `CC_OPENCLAW_NATIVE_TOOLS_ALLOWLIST="message.voice,message.image,..."`.
+ * Q1 expanded default ships at v1.0.0-rc1 alongside the `CC_OPENCLAW_NATIVE_TOOLS=1` flip.
+ */
+import { getConfigService } from '../../lib/config-service.js';
+/**
+ * v0.11.x default — kept exported for legacy callers and for the
+ * `ConfigService`-unset fallback path. New code should call `isAllowedTool`.
+ */
+export const OPENCLAW_TOOL_ALLOWLIST = new Set([
+    'message.voice',
+]);
+/** Return true when `toolName` is in the active allowList. */
+export function isAllowedTool(toolName) {
+    const cfg = getConfigService();
+    if (cfg)
+        return cfg.config.nativeToolsAllowList.includes(toolName);
+    return OPENCLAW_TOOL_ALLOWLIST.has(toolName);
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/src/openai-compat/bridges/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../../../src/openai-compat/bridges/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAClE,eAAe;CAChB,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnE,OAAO,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC"}

package/dist/src/openai-compat/bridges/factory.d.ts

@@ -0,0 +1,30 @@
+/**
+ * factory.ts — Bridge factory: reads env flags and returns the active IToolBridge.
+ *
+ * Mode precedence (highest wins):
+ *   CC_OPENCLAW_NATIVE_TOOLS=1  → OpenClawNative  (v0.11.0, default OFF)
+ *   CC_OPENCLAW_TOOL_STREAM=1   → NativeStream
+ *   OPENAI_COMPAT_TOOLS_PER_MESSAGE=1 → PerMessage
+ *   (default)                   → Embedded
+ *
+ * The three existing modes (Embedded, PerMessage, NativeStream) are NOT
+ * implemented as full IToolBridge classes in this PR — their logic lives
+ * inside openai-compat.ts. The factory stubs them as thin wrappers that
+ * satisfy IToolBridge so callers can type-check against the interface.
+ * Only OpenClawNativeBridge is a real implementation here.
+ *
+ * Coexistence rule: existing flag readers (`isToolsPerMessageModeEnabled`,
+ * `isToolStreamMode`) are not touched — factory reads them via the same
+ * env vars, not via those helpers, to avoid coupling factory → mode-flags.
+ */
+import type { IToolBridge } from '../../types/tool-bridge.js';
+import { ToolMode } from '../../types/tool-bridge.js';
+/**
+ * Return the active IToolBridge based on env flags.
+ *
+ * Call once per request — bridges are lightweight and stateless (except
+ * OpenClawNativeToolsBridge which caches the gateway config read).
+ */
+export declare function makeToolBridge(): IToolBridge;
+/** Read the active mode without constructing a bridge. Useful for logging. */
+export declare function activeToolMode(): ToolMode;

package/dist/src/openai-compat/bridges/factory.js

@@ -0,0 +1,84 @@
+/**
+ * factory.ts — Bridge factory: reads env flags and returns the active IToolBridge.
+ *
+ * Mode precedence (highest wins):
+ *   CC_OPENCLAW_NATIVE_TOOLS=1  → OpenClawNative  (v0.11.0, default OFF)
+ *   CC_OPENCLAW_TOOL_STREAM=1   → NativeStream
+ *   OPENAI_COMPAT_TOOLS_PER_MESSAGE=1 → PerMessage
+ *   (default)                   → Embedded
+ *
+ * The three existing modes (Embedded, PerMessage, NativeStream) are NOT
+ * implemented as full IToolBridge classes in this PR — their logic lives
+ * inside openai-compat.ts. The factory stubs them as thin wrappers that
+ * satisfy IToolBridge so callers can type-check against the interface.
+ * Only OpenClawNativeBridge is a real implementation here.
+ *
+ * Coexistence rule: existing flag readers (`isToolsPerMessageModeEnabled`,
+ * `isToolStreamMode`) are not touched — factory reads them via the same
+ * env vars, not via those helpers, to avoid coupling factory → mode-flags.
+ */
+import { ToolMode } from '../../types/tool-bridge.js';
+import { OpenClawNativeToolsBridge } from './openclaw-native-tools.js';
+// ── Stub bridges for legacy modes ─────────────────────────────────────────
+// These stubs let the factory return typed IToolBridge values for the existing
+// modes. They are NOT functional implementations — the real logic lives in
+// openai-compat.ts / streaming-handler.ts. Their presence here is purely for
+// the mode-selection interface.
+class EmbeddedToolsBridgeStub {
+    mode = ToolMode.Embedded;
+    buildToolPreamble(_tools) { return ''; }
+    translateToolUse(_event) { return null; }
+    serializeToolResult(call, result) {
+        return `<tool_result tool_use_id="${call.id}" name="${call.function.name}">${result}</tool_result>`;
+    }
+}
+class PerMessageToolsBridgeStub {
+    mode = ToolMode.PerMessage;
+    buildToolPreamble(_tools) { return ''; }
+    translateToolUse(_event) { return null; }
+    serializeToolResult(call, result) {
+        return `<tool_result tool_use_id="${call.id}" name="${call.function.name}">${result}</tool_result>`;
+    }
+}
+class NativeStreamToolsBridgeStub {
+    mode = ToolMode.NativeStream;
+    buildToolPreamble(_tools) { return ''; }
+    translateToolUse(_event) { return null; }
+    serializeToolResult(call, result) {
+        return `<tool_result tool_use_id="${call.id}" name="${call.function.name}">${result}</tool_result>`;
+    }
+}
+// ── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Return the active IToolBridge based on env flags.
+ *
+ * Call once per request — bridges are lightweight and stateless (except
+ * OpenClawNativeToolsBridge which caches the gateway config read).
+ */
+export function makeToolBridge() {
+    // OpenClawNative: highest precedence, default OFF for v0.11.0 soak
+    if (process.env.CC_OPENCLAW_NATIVE_TOOLS === '1') {
+        return new OpenClawNativeToolsBridge();
+    }
+    // NativeStream
+    if (process.env.CC_OPENCLAW_TOOL_STREAM === '1') {
+        return new NativeStreamToolsBridgeStub();
+    }
+    // PerMessage (legacy)
+    if (process.env.OPENAI_COMPAT_TOOLS_PER_MESSAGE === '1') {
+        return new PerMessageToolsBridgeStub();
+    }
+    // Default: Embedded
+    return new EmbeddedToolsBridgeStub();
+}
+/** Read the active mode without constructing a bridge. Useful for logging. */
+export function activeToolMode() {
+    if (process.env.CC_OPENCLAW_NATIVE_TOOLS === '1')
+        return ToolMode.OpenClawNative;
+    if (process.env.CC_OPENCLAW_TOOL_STREAM === '1')
+        return ToolMode.NativeStream;
+    if (process.env.OPENAI_COMPAT_TOOLS_PER_MESSAGE === '1')
+        return ToolMode.PerMessage;
+    return ToolMode.Embedded;
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/openai-compat/bridges/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../src/openai-compat/bridges/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAC7E,gCAAgC;AAEhC,MAAM,uBAAuB;IAClB,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAClC,iBAAiB,CAAC,MAAiD,IAAY,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3F,gBAAgB,CAAC,MAAe,IAA4B,OAAO,IAAI,CAAC,CAAC,CAAC;IAC1E,mBAAmB,CAAC,IAAoB,EAAE,MAAc;QACtD,OAAO,6BAA6B,IAAI,CAAC,EAAE,WAAW,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,gBAAgB,CAAC;IACtG,CAAC;CACF;AAED,MAAM,yBAAyB;IACpB,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC;IACpC,iBAAiB,CAAC,MAAiD,IAAY,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3F,gBAAgB,CAAC,MAAe,IAA4B,OAAO,IAAI,CAAC,CAAC,CAAC;IAC1E,mBAAmB,CAAC,IAAoB,EAAE,MAAc;QACtD,OAAO,6BAA6B,IAAI,CAAC,EAAE,WAAW,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,gBAAgB,CAAC;IACtG,CAAC;CACF;AAED,MAAM,2BAA2B;IACtB,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC;IACtC,iBAAiB,CAAC,MAAiD,IAAY,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3F,gBAAgB,CAAC,MAAe,IAA4B,OAAO,IAAI,CAAC,CAAC,CAAC;IAC1E,mBAAmB,CAAC,IAAoB,EAAE,MAAc;QACtD,OAAO,6BAA6B,IAAI,CAAC,EAAE,WAAW,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,gBAAgB,CAAC;IACtG,CAAC;CACF;AAED,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,mEAAmE;IACnE,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,KAAK,GAAG,EAAE,CAAC;QACjD,OAAO,IAAI,yBAAyB,EAAE,CAAC;IACzC,CAAC;IACD,eAAe;IACf,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,EAAE,CAAC;QAChD,OAAO,IAAI,2BAA2B,EAAE,CAAC;IAC3C,CAAC;IACD,sBAAsB;IACtB,IAAI,OAAO,CAAC,GAAG,CAAC,+BAA+B,KAAK,GAAG,EAAE,CAAC;QACxD,OAAO,IAAI,yBAAyB,EAAE,CAAC;IACzC,CAAC;IACD,oBAAoB;IACpB,OAAO,IAAI,uBAAuB,EAAE,CAAC;AACvC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc;IAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,wBAAwB,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC,cAAc,CAAC;IACjF,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC,YAAY,CAAC;IAC9E,IAAI,OAAO,CAAC,GAAG,CAAC,+BAA+B,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC,UAAU,CAAC;IACpF,OAAO,QAAQ,CAAC,QAAQ,CAAC;AAC3B,CAAC"}

package/dist/src/openai-compat/bridges/media-bridge.d.ts

@@ -0,0 +1,34 @@
+/**
+ * media-bridge.ts — Shared contract for media delivery bridges.
+ *
+ * `MediaBridge` is the interface all media-type sub-bridges implement.
+ * `TtsMediaBridge` (tts-media-bridge.ts) is the v0.11.0 concrete impl.
+ * Future: `ImageMediaBridge`, `FileMediaBridge` for v0.12.0.
+ */
+/** Structured result from a media bridge execution. */
+export interface MediaBridgeResult {
+    /** Text to inject into the SSE stream in place of the tool_call. */
+    readonly text: string;
+    /** Whether the bridge produced output via the native channel. */
+    readonly delivered: boolean;
+    /** Delivery channel used. Informational — not load-bearing. */
+    readonly via: string;
+}
+/** Every media sub-bridge must satisfy this contract. */
+export interface MediaBridge {
+    /** Canonical tool name this bridge handles (e.g. `message.voice`). */
+    readonly toolName: string;
+    /**
+     * Execute the media delivery. `args` is the raw JSON-parsed tool arguments
+     * from the model's tool_call. Returns a `MediaBridgeResult` — never throws;
+     * fallback text is always produced on error.
+     */
+    execute(args: Record<string, unknown>): Promise<MediaBridgeResult>;
+}
+/** Thrown by bridge internals for structured error propagation.
+ *  Caught at the `OpenClawNativeToolsBridge` boundary — never escapes to callers. */
+export declare class MediaBridgeError extends Error {
+    readonly toolName: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, toolName: string, cause?: unknown | undefined);
+}

package/dist/src/openai-compat/bridges/media-bridge.js

@@ -0,0 +1,20 @@
+/**
+ * media-bridge.ts — Shared contract for media delivery bridges.
+ *
+ * `MediaBridge` is the interface all media-type sub-bridges implement.
+ * `TtsMediaBridge` (tts-media-bridge.ts) is the v0.11.0 concrete impl.
+ * Future: `ImageMediaBridge`, `FileMediaBridge` for v0.12.0.
+ */
+/** Thrown by bridge internals for structured error propagation.
+ *  Caught at the `OpenClawNativeToolsBridge` boundary — never escapes to callers. */
+export class MediaBridgeError extends Error {
+    toolName;
+    cause;
+    constructor(message, toolName, cause) {
+        super(message);
+        this.toolName = toolName;
+        this.cause = cause;
+        this.name = 'MediaBridgeError';
+    }
+}
+//# sourceMappingURL=media-bridge.js.map

package/dist/src/openai-compat/bridges/media-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-bridge.js","sourceRoot":"","sources":["../../../../src/openai-compat/bridges/media-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyBH;qFACqF;AACrF,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGvB;IACA;IAHlB,YACE,OAAe,EACC,QAAgB,EAChB,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,aAAQ,GAAR,QAAQ,CAAQ;QAChB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}