@a1hvdy/cc-openclaw 0.7.1 → 0.9.0

package/dist/src/types/runtime-config.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Cluster A — Type the seams.
+ *
+ * Single typed runtime configuration parsed from `process.env` at boot.
+ * Replaces the 12+ scattered env-flag readers in `src/lib/config.ts` with
+ * one zod-validated immutable object.
+ *
+ * Pre-existing latent bugs documented at `src/lib/config.ts:39-42` and
+ * `src/lib/config.ts:195-197` (two readers per env var with opposite
+ * defaults) are resolved by FIELD-SPLITTING rather than choosing one
+ * default. This preserves both current call-site behaviors verbatim.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ * Cluster A migration order (per PRP §14) wires this in incrementally
+ * with `src/lib/config.ts` getters delegating during the shim window.
+ */
+import { z } from 'zod';
+/**
+ * Three-state activation mode derived from the two LISTENERS / ACTIVE flags.
+ * Replaces the implicit two-flag matrix at `src/lib/route-flag.ts`.
+ *
+ * - PASSIVE          — listeners NOT wired; no engine routing.
+ * - LISTENERS_ONLY   — listeners wired, but engine routing returns 'claude-local'.
+ * - ACTIVE_ROUTING   — listeners wired AND engine routing returns 'cc-openclaw'.
+ */
+export declare enum RuntimeMode {
+    PASSIVE = "PASSIVE",
+    LISTENERS_ONLY = "LISTENERS_ONLY",
+    ACTIVE_ROUTING = "ACTIVE_ROUTING"
+}
+/**
+ * Derive RuntimeMode from raw env. Honors deprecated alias
+ * `OPENCLAW_USE_CC_OPENCLAW` only when the primary `OPENCLAW_CC_OPENCLAW_ACTIVE`
+ * is unset. Alias retained through v0.9.x; removed at v1.0.0.
+ */
+export declare function deriveMode(env: NodeJS.ProcessEnv): RuntimeMode;
+export declare const RuntimeConfigSchema: z.ZodObject<{
+    mode: z.ZodNativeEnum<typeof RuntimeMode>;
+    listenersEnabled: z.ZodDefault<z.ZodBoolean>;
+    activeRouting: z.ZodDefault<z.ZodBoolean>;
+    toolStream: z.ZodDefault<z.ZodBoolean>;
+    allowBuiltins: z.ZodDefault<z.ZodBoolean>;
+    toolsPerMessage: z.ZodDefault<z.ZodBoolean>;
+    cacheParityModuleEnabled: z.ZodDefault<z.ZodBoolean>;
+    cacheParityTrackB: z.ZodDefault<z.ZodBoolean>;
+    newConvoHeuristic: z.ZodDefault<z.ZodBoolean>;
+    aggressiveStripEnabled: z.ZodDefault<z.ZodBoolean>;
+    debug: z.ZodDefault<z.ZodBoolean>;
+    registerDebug: z.ZodDefault<z.ZodBoolean>;
+    tokenTelemetryRouteGate: z.ZodDefault<z.ZodBoolean>;
+    tokenTelemetryWriter: z.ZodDefault<z.ZodBoolean>;
+    syspromptDump: z.ZodDefault<z.ZodBoolean>;
+    trajectoryEnabled: z.ZodDefault<z.ZodBoolean>;
+    statusUrl: z.ZodOptional<z.ZodString>;
+    surfaceThinking: z.ZodDefault<z.ZodBoolean>;
+    thinkingExcerpt: z.ZodDefault<z.ZodBoolean>;
+    maxConcurrentSessions: z.ZodDefault<z.ZodNumber>;
+    sessionTtlMinutes: z.ZodDefault<z.ZodNumber>;
+    serverHost: z.ZodDefault<z.ZodString>;
+    rateLimit: z.ZodDefault<z.ZodNumber>;
+    serverToken: z.ZodOptional<z.ZodString>;
+    corsAllowAll: z.ZodDefault<z.ZodBoolean>;
+    claudeBin: z.ZodOptional<z.ZodString>;
+    geminiBin: z.ZodOptional<z.ZodString>;
+    codexBin: z.ZodOptional<z.ZodString>;
+    cursorBin: z.ZodOptional<z.ZodString>;
+    driftAlertsEnabled: z.ZodDefault<z.ZodBoolean>;
+    autoRecoveryEnabled: z.ZodDefault<z.ZodBoolean>;
+    quotaPausePct: z.ZodDefault<z.ZodNumber>;
+    testMode: z.ZodDefault<z.ZodBoolean>;
+    heartbeatWorkaroundDisabled: z.ZodDefault<z.ZodBoolean>;
+    savvyLiveCardEnabled: z.ZodDefault<z.ZodBoolean>;
+    /** True if mode was derived from the deprecated alias path. Logged at boot. */
+    usedDeprecatedAlias: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    mode: RuntimeMode;
+    listenersEnabled: boolean;
+    activeRouting: boolean;
+    toolStream: boolean;
+    allowBuiltins: boolean;
+    toolsPerMessage: boolean;
+    cacheParityModuleEnabled: boolean;
+    cacheParityTrackB: boolean;
+    newConvoHeuristic: boolean;
+    aggressiveStripEnabled: boolean;
+    debug: boolean;
+    registerDebug: boolean;
+    tokenTelemetryRouteGate: boolean;
+    tokenTelemetryWriter: boolean;
+    syspromptDump: boolean;
+    trajectoryEnabled: boolean;
+    surfaceThinking: boolean;
+    thinkingExcerpt: boolean;
+    maxConcurrentSessions: number;
+    sessionTtlMinutes: number;
+    serverHost: string;
+    rateLimit: number;
+    corsAllowAll: boolean;
+    driftAlertsEnabled: boolean;
+    autoRecoveryEnabled: boolean;
+    quotaPausePct: number;
+    testMode: boolean;
+    heartbeatWorkaroundDisabled: boolean;
+    savvyLiveCardEnabled: boolean;
+    usedDeprecatedAlias: boolean;
+    statusUrl?: string | undefined;
+    serverToken?: string | undefined;
+    claudeBin?: string | undefined;
+    geminiBin?: string | undefined;
+    codexBin?: string | undefined;
+    cursorBin?: string | undefined;
+}, {
+    mode: RuntimeMode;
+    listenersEnabled?: boolean | undefined;
+    activeRouting?: boolean | undefined;
+    toolStream?: boolean | undefined;
+    allowBuiltins?: boolean | undefined;
+    toolsPerMessage?: boolean | undefined;
+    cacheParityModuleEnabled?: boolean | undefined;
+    cacheParityTrackB?: boolean | undefined;
+    newConvoHeuristic?: boolean | undefined;
+    aggressiveStripEnabled?: boolean | undefined;
+    debug?: boolean | undefined;
+    registerDebug?: boolean | undefined;
+    tokenTelemetryRouteGate?: boolean | undefined;
+    tokenTelemetryWriter?: boolean | undefined;
+    syspromptDump?: boolean | undefined;
+    trajectoryEnabled?: boolean | undefined;
+    statusUrl?: string | undefined;
+    surfaceThinking?: boolean | undefined;
+    thinkingExcerpt?: boolean | undefined;
+    maxConcurrentSessions?: number | undefined;
+    sessionTtlMinutes?: number | undefined;
+    serverHost?: string | undefined;
+    rateLimit?: number | undefined;
+    serverToken?: string | undefined;
+    corsAllowAll?: boolean | undefined;
+    claudeBin?: string | undefined;
+    geminiBin?: string | undefined;
+    codexBin?: string | undefined;
+    cursorBin?: string | undefined;
+    driftAlertsEnabled?: boolean | undefined;
+    autoRecoveryEnabled?: boolean | undefined;
+    quotaPausePct?: number | undefined;
+    testMode?: boolean | undefined;
+    heartbeatWorkaroundDisabled?: boolean | undefined;
+    savvyLiveCardEnabled?: boolean | undefined;
+    usedDeprecatedAlias?: boolean | undefined;
+}>;
+export type RuntimeConfig = z.infer<typeof RuntimeConfigSchema>;
+export declare class ConfigError extends Error {
+    readonly issues: ReadonlyArray<z.ZodIssue>;
+    constructor(issues: z.ZodIssue[]);
+}
+export type ParseEnvResult = {
+    readonly ok: true;
+    readonly config: Readonly<RuntimeConfig>;
+} | {
+    readonly ok: false;
+    readonly error: ConfigError;
+};

package/dist/src/types/runtime-config.js

@@ -0,0 +1,118 @@
+/**
+ * Cluster A — Type the seams.
+ *
+ * Single typed runtime configuration parsed from `process.env` at boot.
+ * Replaces the 12+ scattered env-flag readers in `src/lib/config.ts` with
+ * one zod-validated immutable object.
+ *
+ * Pre-existing latent bugs documented at `src/lib/config.ts:39-42` and
+ * `src/lib/config.ts:195-197` (two readers per env var with opposite
+ * defaults) are resolved by FIELD-SPLITTING rather than choosing one
+ * default. This preserves both current call-site behaviors verbatim.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ * Cluster A migration order (per PRP §14) wires this in incrementally
+ * with `src/lib/config.ts` getters delegating during the shim window.
+ */
+import { z } from 'zod';
+// ── Mode derivation ──────────────────────────────────────────────────────────
+/**
+ * Three-state activation mode derived from the two LISTENERS / ACTIVE flags.
+ * Replaces the implicit two-flag matrix at `src/lib/route-flag.ts`.
+ *
+ * - PASSIVE          — listeners NOT wired; no engine routing.
+ * - LISTENERS_ONLY   — listeners wired, but engine routing returns 'claude-local'.
+ * - ACTIVE_ROUTING   — listeners wired AND engine routing returns 'cc-openclaw'.
+ */
+export var RuntimeMode;
+(function (RuntimeMode) {
+    RuntimeMode["PASSIVE"] = "PASSIVE";
+    RuntimeMode["LISTENERS_ONLY"] = "LISTENERS_ONLY";
+    RuntimeMode["ACTIVE_ROUTING"] = "ACTIVE_ROUTING";
+})(RuntimeMode || (RuntimeMode = {}));
+const flag = (v) => v === '1' || v?.toLowerCase() === 'true' || v?.toLowerCase() === 'on';
+/**
+ * Derive RuntimeMode from raw env. Honors deprecated alias
+ * `OPENCLAW_USE_CC_OPENCLAW` only when the primary `OPENCLAW_CC_OPENCLAW_ACTIVE`
+ * is unset. Alias retained through v0.9.x; removed at v1.0.0.
+ */
+export function deriveMode(env) {
+    const listeners = flag(env.OPENCLAW_CC_OPENCLAW_LISTENERS);
+    const active = env.OPENCLAW_CC_OPENCLAW_ACTIVE !== undefined
+        ? flag(env.OPENCLAW_CC_OPENCLAW_ACTIVE)
+        : flag(env.OPENCLAW_USE_CC_OPENCLAW); // deprecated alias
+    if (!listeners)
+        return RuntimeMode.PASSIVE;
+    if (!active)
+        return RuntimeMode.LISTENERS_ONLY;
+    return RuntimeMode.ACTIVE_ROUTING;
+}
+// ── Schema ───────────────────────────────────────────────────────────────────
+export const RuntimeConfigSchema = z.object({
+    // Derived — not read directly from a single env var.
+    mode: z.nativeEnum(RuntimeMode),
+    // ── Activation ────────────────────────────────────────────────────────────
+    listenersEnabled: z.boolean().default(false),
+    activeRouting: z.boolean().default(false),
+    // ── Tooling ───────────────────────────────────────────────────────────────
+    toolStream: z.boolean().default(false),
+    allowBuiltins: z.boolean().default(false),
+    toolsPerMessage: z.boolean().default(false),
+    // ── Caching & state ───────────────────────────────────────────────────────
+    // Dual-default split for OPENCLAW_CACHE_PARITY (see file header):
+    //   moduleEnabled: default TRUE — broad enable, only OFF if env in {0,false,off}
+    //   trackB:        default FALSE — strict opt-in, only ON if env === '1'
+    cacheParityModuleEnabled: z.boolean().default(true),
+    cacheParityTrackB: z.boolean().default(false),
+    newConvoHeuristic: z.boolean().default(false),
+    aggressiveStripEnabled: z.boolean().default(true),
+    // ── Observability ─────────────────────────────────────────────────────────
+    debug: z.boolean().default(false),
+    registerDebug: z.boolean().default(false),
+    // Dual-default split for OPENCLAW_TOKEN_TELEMETRY (see file header):
+    //   routeGate: default FALSE — cwd-patch gate, strict `=== '1'`
+    //   writer:    default TRUE  — telemetry.ts writer, only OFF on `=== '0'`
+    tokenTelemetryRouteGate: z.boolean().default(false),
+    tokenTelemetryWriter: z.boolean().default(true),
+    syspromptDump: z.boolean().default(false),
+    trajectoryEnabled: z.boolean().default(false),
+    // statusUrl is intentionally `string`, NOT `string().url()` — current code
+    // (src/lib/config.ts:236-239) does zero validation; tightening would change
+    // behavior. Audit the live corpus before promoting to URL validation.
+    statusUrl: z.string().optional(),
+    surfaceThinking: z.boolean().default(false),
+    thinkingExcerpt: z.boolean().default(false),
+    // ── Session caps ──────────────────────────────────────────────────────────
+    maxConcurrentSessions: z.number().int().positive().default(32),
+    sessionTtlMinutes: z.number().int().positive().default(1440),
+    // ── Embedded HTTP server ──────────────────────────────────────────────────
+    serverHost: z.string().default('127.0.0.1'),
+    rateLimit: z.number().int().positive().default(100),
+    serverToken: z.string().optional(),
+    corsAllowAll: z.boolean().default(false),
+    // ── Runtime binaries ──────────────────────────────────────────────────────
+    claudeBin: z.string().optional(),
+    geminiBin: z.string().optional(),
+    codexBin: z.string().optional(),
+    cursorBin: z.string().optional(),
+    // ── Misc ──────────────────────────────────────────────────────────────────
+    driftAlertsEnabled: z.boolean().default(true),
+    autoRecoveryEnabled: z.boolean().default(true),
+    quotaPausePct: z.number().min(0).max(100).default(95),
+    testMode: z.boolean().default(false),
+    heartbeatWorkaroundDisabled: z.boolean().default(false),
+    savvyLiveCardEnabled: z.boolean().default(false),
+    // ── Deprecation tracking ──────────────────────────────────────────────────
+    /** True if mode was derived from the deprecated alias path. Logged at boot. */
+    usedDeprecatedAlias: z.boolean().default(false),
+});
+// ── Error type ───────────────────────────────────────────────────────────────
+export class ConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super(`RuntimeConfig validation failed: ${issues.map((i) => i.message).join('; ')}`);
+        this.name = 'ConfigError';
+        this.issues = Object.freeze(issues.slice());
+    }
+}
+//# sourceMappingURL=runtime-config.js.map

package/dist/src/types/runtime-config.js.map

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

package/dist/src/types/session.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cluster A — Session boundary types.
+ *
+ * Re-exports the session vocabulary already established in the root
+ * `src/types.ts` module. New aliases (`SessionStartConfig`, `SessionMeta`)
+ * preview Cluster B's `SessionService` boundary without yet introducing
+ * a new shape — they're typed wrappers over today's `SessionConfig` /
+ * `ActiveSession`.
+ *
+ * `SessionName` is the branded type that Cluster D's `SessionRegistry`
+ * will use to enforce the `'openai-'` prefix routing discriminant
+ * (cwd-patch.ts:489 gates CWD redirect, tools restoration, CLAUDE.md
+ * injection on this prefix).
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+export type { SessionConfig as SessionStartConfig, SessionStats, ActiveSession, SessionInfo, SessionSendOptions, StreamCallbacks, StreamEvent, SendResult, SendOptions, TurnResult, CostBreakdown, ISession, EngineType, PermissionMode, EffortLevel, PluginConfig, HookConfig, CustomEngineConfig, } from '../types.js';
+/**
+ * Branded session-name type. Prevents raw string from being passed where
+ * the `'openai-'` prefix is load-bearing. Use the constructors below to
+ * mint or strip the prefix — never construct directly.
+ */
+export type SessionName = string & {
+    readonly __brand: 'SessionName';
+};
+export declare const sessionNameFromKey: (key: string) => SessionName;
+export declare const isOpenAiBridgeName: (name: SessionName) => boolean;
+export declare const stripOpenAiPrefix: (name: SessionName) => string;
+/**
+ * Cluster B/D will fold this into `SessionRegistry.SessionEntry`. For
+ * Cluster A it's a typed preview — the shape Cluster D will persist,
+ * declared here so other clusters can compile against the contract.
+ */
+export interface SessionMeta {
+    readonly name: SessionName;
+    readonly claudeSessionId: string | null;
+    readonly pid: number | null;
+    readonly cachedSysPromptHash: string;
+    readonly skipPersistence: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/**
+ * Input shape Cluster B's `SessionService.send()` accepts.
+ * Today's call sites pass either a string or an array of content blocks;
+ * this interface preserves both without yet committing to a tighter shape.
+ */
+export type SendInput = string | ReadonlyArray<unknown>;

package/dist/src/types/session.js

@@ -0,0 +1,20 @@
+/**
+ * Cluster A — Session boundary types.
+ *
+ * Re-exports the session vocabulary already established in the root
+ * `src/types.ts` module. New aliases (`SessionStartConfig`, `SessionMeta`)
+ * preview Cluster B's `SessionService` boundary without yet introducing
+ * a new shape — they're typed wrappers over today's `SessionConfig` /
+ * `ActiveSession`.
+ *
+ * `SessionName` is the branded type that Cluster D's `SessionRegistry`
+ * will use to enforce the `'openai-'` prefix routing discriminant
+ * (cwd-patch.ts:489 gates CWD redirect, tools restoration, CLAUDE.md
+ * injection on this prefix).
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+export const sessionNameFromKey = (key) => `openai-${key}`;
+export const isOpenAiBridgeName = (name) => name.startsWith('openai-');
+export const stripOpenAiPrefix = (name) => name.replace(/^openai-/, '');
+//# sourceMappingURL=session.js.map

package/dist/src/types/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/types/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA8BH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAe,EAAE,CAC7D,UAAU,GAAG,EAAiB,CAAC;AAEjC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAiB,EAAW,EAAE,CAC/D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAE7B,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAiB,EAAU,EAAE,CAC7D,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC"}

package/dist/src/types/sse.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cluster A — SSE wire-format types.
+ *
+ * Re-exports the SSE types currently inline in `openai-compat.ts` and the
+ * Anthropic event types from `cli-stream-parser.ts` under a single import
+ * surface. Cluster B's `sse-translator.ts` already lives at
+ * `src/openai-compat/sse-translator.ts` — this module is its typed contract.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+export type { OpenAIChatCompletionChunk as SseChunk, OpenAIToolCall, } from '../openai-compat/openai-compat.js';
+export type { AnthropicEvent, AnthropicMessage, MessageUsage, MessageDeltaBody, ContentBlockStart, ContentBlockDelta, ParsedEvent, CliStreamParser, } from '../openai-compat/cli-stream-parser.js';
+/**
+ * OpenAI `finish_reason` values cc-openclaw emits after mapping from
+ * Anthropic `stop_reason`:
+ *   end_turn / stop_sequence → 'stop'
+ *   tool_use                 → 'tool_calls'
+ *   max_tokens               → 'length'
+ *   (cancelled / abort)      → null  (no finish_reason chunk)
+ */
+export type FinishReason = 'stop' | 'tool_calls' | 'length' | null;
+/**
+ * One delta in an OpenAI streaming chunk. Cluster B will tighten this when
+ * `sse-translator.ts` is extracted into the typed boundary.
+ */
+export interface OpenAIDelta {
+    readonly role?: 'assistant' | 'system' | 'user' | 'tool';
+    readonly content?: string;
+    readonly tool_calls?: ReadonlyArray<{
+        readonly index: number;
+        readonly id?: string;
+        readonly type?: 'function';
+        readonly function?: {
+            readonly name?: string;
+            readonly arguments?: string;
+        };
+    }>;
+}

package/dist/src/types/sse.js

@@ -0,0 +1,12 @@
+/**
+ * Cluster A — SSE wire-format types.
+ *
+ * Re-exports the SSE types currently inline in `openai-compat.ts` and the
+ * Anthropic event types from `cli-stream-parser.ts` under a single import
+ * surface. Cluster B's `sse-translator.ts` already lives at
+ * `src/openai-compat/sse-translator.ts` — this module is its typed contract.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+export {};
+//# sourceMappingURL=sse.js.map

package/dist/src/types/sse.js.map

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

package/dist/src/types/tool-bridge.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cluster A — Tool bridge contract.
+ *
+ * Declares the interface Cluster B's three tool-mode strategies will
+ * implement (`EmbeddedToolsBridge`, `PerMessageToolsBridge`,
+ * `NativeToolStreamBridge`). Lives in `src/types/` — pure type
+ * declaration, no runtime code, zero implementation yet.
+ *
+ * The mode → bridge selection in Cluster B is one-way: `bridges/factory.ts`
+ * imports from this module; `system-prompt-builder.ts` (the other
+ * potentially-circular dependency) accepts a `ToolMode` arg from the
+ * bridge rather than importing the factory. See PRP §11 Decision Log.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+import type { OpenAIToolCall } from './route.js';
+import type { OpenAIDelta } from './sse.js';
+/**
+ * Three tool-handling modes documented in ARCHITECTURE.md §5.3:
+ *
+ * - Embedded     — default. Tools embedded in session system prompt at
+ *                  create-time; NOT re-injected per turn; cacheable.
+ * - PerMessage   — legacy `OPENAI_COMPAT_TOOLS_PER_MESSAGE=1`. Tool block
+ *                  prepended to every user message; defeats prompt caching;
+ *                  allows mutating tool list mid-session.
+ * - NativeStream — `CC_OPENCLAW_TOOL_STREAM=1`. Tools forwarded as
+ *                  `--tools` allowlist; native `tool_use` events flow
+ *                  through; SSE translator emits inline `delta.tool_calls`.
+ */
+export declare enum ToolMode {
+    Embedded = "embedded",
+    PerMessage = "per-message",
+    NativeStream = "native-stream"
+}
+/**
+ * The tool definition shape OpenClaw's `createOpenClawCodingTools` produces
+ * and that callers send in `request.tools`. Shape mirrors the OpenAI tool
+ * definition. Cluster B will tighten when bridge implementations land.
+ */
+export interface ToolDefinition {
+    readonly type: 'function';
+    readonly function: {
+        readonly name: string;
+        readonly description?: string;
+        readonly parameters?: Record<string, unknown>;
+    };
+}
+/**
+ * Result of translating a single Anthropic `tool_use` event from the
+ * Claude CLI stream into an OpenAI streaming chunk delta. `null` means
+ * the bridge consumed the event but emitted nothing (e.g. mid-block
+ * input_json_delta accumulation).
+ */
+export type TranslatedToolUseDelta = OpenAIDelta | null;
+/**
+ * The contract every tool-mode bridge must satisfy. Cluster B's three
+ * strategy classes live at `src/openai-compat/bridges/{embedded-tools,
+ * per-message,native-stream}.ts`. Each is constructed once per route
+ * request and discarded after the response is written.
+ */
+export interface IToolBridge {
+    readonly mode: ToolMode;
+    /**
+     * Build the system-prompt fragment that advertises the tool list to
+     * the model. Pure function — no I/O. Empty string when the bridge
+     * does not embed tools in the prompt (NativeStream).
+     */
+    buildToolPreamble(tools: ReadonlyArray<ToolDefinition> | undefined): string;
+    /**
+     * Translate one parsed Anthropic event into an OpenAI delta if it
+     * represents a tool_use boundary. Returns `null` for events the
+     * bridge does not surface as tool_calls deltas.
+     */
+    translateToolUse(event: unknown): TranslatedToolUseDelta;
+    /**
+     * Serialize an OpenAI tool_call result back into the format the
+     * bridge sends to Claude CLI on the next turn. Embedded + PerMessage
+     * use `<tool_result>` XML; NativeStream uses native blocks.
+     */
+    serializeToolResult(call: OpenAIToolCall, result: string): string;
+}

package/dist/src/types/tool-bridge.js

@@ -0,0 +1,34 @@
+/**
+ * Cluster A — Tool bridge contract.
+ *
+ * Declares the interface Cluster B's three tool-mode strategies will
+ * implement (`EmbeddedToolsBridge`, `PerMessageToolsBridge`,
+ * `NativeToolStreamBridge`). Lives in `src/types/` — pure type
+ * declaration, no runtime code, zero implementation yet.
+ *
+ * The mode → bridge selection in Cluster B is one-way: `bridges/factory.ts`
+ * imports from this module; `system-prompt-builder.ts` (the other
+ * potentially-circular dependency) accepts a `ToolMode` arg from the
+ * bridge rather than importing the factory. See PRP §11 Decision Log.
+ *
+ * NOT consumed yet — Cluster A first commit establishes the vocabulary.
+ */
+/**
+ * Three tool-handling modes documented in ARCHITECTURE.md §5.3:
+ *
+ * - Embedded     — default. Tools embedded in session system prompt at
+ *                  create-time; NOT re-injected per turn; cacheable.
+ * - PerMessage   — legacy `OPENAI_COMPAT_TOOLS_PER_MESSAGE=1`. Tool block
+ *                  prepended to every user message; defeats prompt caching;
+ *                  allows mutating tool list mid-session.
+ * - NativeStream — `CC_OPENCLAW_TOOL_STREAM=1`. Tools forwarded as
+ *                  `--tools` allowlist; native `tool_use` events flow
+ *                  through; SSE translator emits inline `delta.tool_calls`.
+ */
+export var ToolMode;
+(function (ToolMode) {
+    ToolMode["Embedded"] = "embedded";
+    ToolMode["PerMessage"] = "per-message";
+    ToolMode["NativeStream"] = "native-stream";
+})(ToolMode || (ToolMode = {}));
+//# sourceMappingURL=tool-bridge.js.map

package/dist/src/types/tool-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bridge.js","sourceRoot":"","sources":["../../../src/types/tool-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,QAIX;AAJD,WAAY,QAAQ;IAClB,iCAAqB,CAAA;IACrB,sCAA0B,CAAA;IAC1B,0CAA8B,CAAA;AAChC,CAAC,EAJW,QAAQ,KAAR,QAAQ,QAInB"}