@pellux/goodvibes-sdk 0.24.0 → 0.25.0

package/dist/_internal/platform/runtime/tasks/manager.js

@@ -16,6 +16,7 @@ import { createDomainDispatch } from '../store/index.js';
 import { TaskRegistry } from './registry.js';
 import { canTransition } from './lifecycle.js';
 import { emitTaskCreated, emitTaskStarted, emitTaskBlocked, emitTaskCompleted, emitTaskFailed, emitTaskCancelled, } from '../emitters/tasks.js';
+import { isFeatureGateEnabled, requireFeatureGate } from '../feature-flags/index.js';
 // ---------------------------------------------------------------------------
 // Error types
 // ---------------------------------------------------------------------------
@@ -65,19 +66,28 @@ export class UnifiedTaskManager {
     _bus;
     /** Session ID for emitter context. */
     _sessionId;
+    _featureFlags;
     /**
      * @param store - The Zustand runtime store to dispatch state updates to.
      * @param bus - The RuntimeEventBus to emit task lifecycle events on.
      * @param sessionId - The current session identifier for emitter context.
      */
-    constructor(store, bus, sessionId) {
+    constructor(store, bus, sessionId, featureFlags) {
         this._store = store;
         this._dispatch = createDomainDispatch(store);
         this._bus = bus;
         this._sessionId = sessionId;
+        this._featureFlags = featureFlags ?? null;
+    }
+    _isEnabled() {
+        return isFeatureGateEnabled(this._featureFlags, 'unified-runtime-task');
+    }
+    _requireEnabled(operation) {
+        requireFeatureGate(this._featureFlags, 'unified-runtime-task', operation);
     }
     // ── TaskManager interface ────────────────────────────────────────────────
     createTask(params) {
+        this._requireEnabled('create runtime task');
         const now = Date.now();
         const id = crypto.randomUUID();
         const task = {
@@ -112,6 +122,7 @@ export class UnifiedTaskManager {
         return task;
     }
     startTask(taskId) {
+        this._requireEnabled('start runtime task');
         const task = this._requireTask(taskId);
         this._requireTransition(task, 'running');
         const updated = this._applyTransition(task, 'running', {
@@ -121,6 +132,7 @@ export class UnifiedTaskManager {
         return updated;
     }
     blockTask(taskId, reason) {
+        this._requireEnabled('block runtime task');
         const task = this._requireTask(taskId);
         this._requireTransition(task, 'blocked');
         const updated = this._applyTransition(task, 'blocked', {});
@@ -128,6 +140,7 @@ export class UnifiedTaskManager {
         return updated;
     }
     completeTask(taskId, result) {
+        this._requireEnabled('complete runtime task');
         const task = this._requireTask(taskId);
         this._requireTransition(task, 'completed');
         const now = Date.now();
@@ -140,6 +153,7 @@ export class UnifiedTaskManager {
         return updated;
     }
     failTask(taskId, params) {
+        this._requireEnabled('fail runtime task');
         const task = this._requireTask(taskId);
         this._requireTransition(task, 'failed');
         const now = Date.now();
@@ -188,6 +202,7 @@ export class UnifiedTaskManager {
         return updated;
     }
     cancelTask(taskId, params) {
+        this._requireEnabled('cancel runtime task');
         const task = this._requireTask(taskId);
         if (!task.cancellable) {
             throw new TaskNotCancellableError(taskId);
@@ -204,6 +219,7 @@ export class UnifiedTaskManager {
         return updated;
     }
     updateTask(taskId, params) {
+        this._requireEnabled('update runtime task');
         const task = this._requireTask(taskId);
         const updated = {
             ...task,
@@ -217,24 +233,37 @@ export class UnifiedTaskManager {
         return updated;
     }
     getTask(taskId) {
+        if (!this._isEnabled())
+            return undefined;
         return this._registry.get(taskId);
     }
     getTasksByKind(kind) {
+        if (!this._isEnabled())
+            return [];
         return this._registry.getByKind(kind);
     }
     getRunningTasks() {
+        if (!this._isEnabled())
+            return [];
         return this._registry.getRunning();
     }
     getRunningCount(kind) {
+        if (!this._isEnabled())
+            return 0;
         return this._registry.getByKind(kind).filter((t) => t.status === 'running').length;
     }
     getChildTasks(parentTaskId) {
+        if (!this._isEnabled())
+            return [];
         return this._registry.getChildren(parentTaskId);
     }
     getTaskStatus(taskId) {
+        if (!this._isEnabled())
+            return undefined;
         return this._registry.get(taskId)?.status;
     }
     retryTask(taskId) {
+        this._requireEnabled('retry runtime task');
         const task = this._requireTask(taskId);
         if (task.status !== 'failed' && task.status !== 'cancelled') {
             throw new TaskTransitionError(task.id, task.status, 'queued');

package/dist/_internal/platform/runtime/telemetry/index.d.ts

@@ -22,6 +22,8 @@
 import { RuntimeTracer } from './tracer.js';
 import { RuntimeMeter } from './meter.js';
 import type { TelemetryProviderConfig } from './types.js';
+import type { FeatureFlagManager } from '../feature-flags/index.js';
+import type { OtlpConfig } from './exporters/index.js';
 export type { AttributeValue, SpanAttributes, SpanContext, SpanEvent, SpanKind, SpanStatus, SpanStatusCode, ReadableSpan, Span, SpanExporter, Counter, Histogram, HistogramSnapshot, Gauge, MetricLabels, TracerConfig, MeterConfig, TelemetryProviderConfig, } from './types.js';
 export { SpanStatusCode as SpanStatusCodes, SpanKind as SpanKinds } from './types.js';
 export { RuntimeTracer } from './tracer.js';
@@ -30,12 +32,16 @@ export type { TelemetrySeverity, TelemetryViewMode, TelemetryFilter, TelemetryRe
 export { TelemetryApiService } from './api.js';
 export type { TurnSpanContext, TurnSpanEndContext, ToolSpanContext, ToolSpanEndContext, ToolPhase, LlmSpanContext, LlmSpanEndContext, LlmTokenUsage, PluginSpanContext, PluginSpanEndContext, PluginPhase, McpSpanContext, McpSpanEndContext, McpPhase, TransportSpanContext, TransportSpanEndContext, TransportPhase, TaskSpanContext, TaskSpanEndContext, TaskPhase, AgentSpanContext, AgentSpanEndContext, AgentPhase, PermissionSpanContext, PermissionSpanEndContext, PermissionPhase, SessionSpanContext, SessionSpanEndContext, SessionPhase, CompactionSpanContext, CompactionSpanEndContext, CompactionPhase, HealthCascadeSpanContext, } from './spans/index.js';
 export { startTurnSpan, endTurnSpan, startToolSpan, recordToolPhase, endToolSpan, startLlmSpan, recordLlmStreamStart, endLlmSpan, startPluginSpan, recordPluginPhase, endPluginSpan, startMcpSpan, recordMcpPhase, endMcpSpan, startTransportSpan, recordTransportPhase, endTransportSpan, startTaskSpan, recordTaskPhase, endTaskSpan, startAgentSpan, recordAgentPhase, endAgentSpan, startPermissionSpan, recordPermissionPhase, endPermissionSpan, startSessionSpan, recordSessionPhase, endSessionSpan, startCompactionSpan, recordCompactionPhase, endCompactionSpan, recordHealthCascadeSpan, } from './spans/index.js';
-export type { LocalLedgerConfig, ConsoleVerbosity, ConsoleExporterConfig } from './exporters/index.js';
-export { LocalLedgerExporter, ConsoleExporter } from './exporters/index.js';
+export type { LocalLedgerConfig, ConsoleVerbosity, ConsoleExporterConfig, OtlpConfig } from './exporters/index.js';
+export { LocalLedgerExporter, ConsoleExporter, OtlpExporter } from './exporters/index.js';
 export type { InstrumentationHandle } from './instrumentation/index.js';
 export { DomainBridge, createInstrumentation } from './instrumentation/index.js';
 /** Alias for TelemetryProviderConfig to match the factory parameter name. */
 export type TelemetryConfig = TelemetryProviderConfig;
+export interface TelemetryProviderOptions {
+    readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null;
+    readonly otlp?: OtlpConfig;
+}
 /**
  * Create a telemetry provider — a paired RuntimeTracer and RuntimeMeter.
  *
@@ -46,7 +52,7 @@ export type TelemetryConfig = TelemetryProviderConfig;
  * @param config - Optional telemetry provider configuration.
  * @returns An object with `tracer` and `meter` instances.
  */
-export declare function createTelemetryProvider(config?: TelemetryConfig): {
+export declare function createTelemetryProvider(config?: TelemetryConfig, options?: TelemetryProviderOptions): {
     tracer: RuntimeTracer;
     meter: RuntimeMeter;
 };

package/dist/_internal/platform/runtime/telemetry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D,YAAY,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,QAAQ,EACR,UAAU,EACV,cAAc,EACd,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,IAAI,eAAe,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAGtF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAG/C,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5E,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEjF,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG;IACjE,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;CACrB,CAgBA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/telemetry/index.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/runtime/telemetry/index.js

@@ -21,13 +21,14 @@
  */
 import { RuntimeTracer } from './tracer.js';
 import { RuntimeMeter } from './meter.js';
+import { OtlpExporter } from './exporters/index.js';
 export { SpanStatusCode as SpanStatusCodes, SpanKind as SpanKinds } from './types.js';
 // Re-export tracer and meter classes
 export { RuntimeTracer } from './tracer.js';
 export { RuntimeMeter } from './meter.js';
 export { TelemetryApiService } from './api.js';
 export { startTurnSpan, endTurnSpan, startToolSpan, recordToolPhase, endToolSpan, startLlmSpan, recordLlmStreamStart, endLlmSpan, startPluginSpan, recordPluginPhase, endPluginSpan, startMcpSpan, recordMcpPhase, endMcpSpan, startTransportSpan, recordTransportPhase, endTransportSpan, startTaskSpan, recordTaskPhase, endTaskSpan, startAgentSpan, recordAgentPhase, endAgentSpan, startPermissionSpan, recordPermissionPhase, endPermissionSpan, startSessionSpan, recordSessionPhase, endSessionSpan, startCompactionSpan, recordCompactionPhase, endCompactionSpan, recordHealthCascadeSpan, } from './spans/index.js';
-export { LocalLedgerExporter, ConsoleExporter } from './exporters/index.js';
+export { LocalLedgerExporter, ConsoleExporter, OtlpExporter } from './exporters/index.js';
 export { DomainBridge, createInstrumentation } from './instrumentation/index.js';
 /**
  * Create a telemetry provider — a paired RuntimeTracer and RuntimeMeter.
@@ -39,11 +40,13 @@ export { DomainBridge, createInstrumentation } from './instrumentation/index.js'
  * @param config - Optional telemetry provider configuration.
  * @returns An object with `tracer` and `meter` instances.
  */
-export function createTelemetryProvider(config) {
+export function createTelemetryProvider(config, options = {}) {
+    const foundationEnabled = options.featureFlags?.isEnabled('otel-foundation') ?? false;
+    const remoteExportEnabled = foundationEnabled && (options.featureFlags?.isEnabled('otel-remote-export') ?? false);
     const tracer = new RuntimeTracer(config?.tracer ?? {
         scope: 'goodvibes-sdk',
-        enabled: false,
-        exporters: [],
+        enabled: foundationEnabled,
+        exporters: remoteExportEnabled && options.otlp ? [new OtlpExporter(options.otlp)] : [],
     });
     const meter = new RuntimeMeter(config?.meter ?? {
         scope: 'goodvibes-sdk',

package/dist/_internal/platform/runtime/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACvG,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AASjD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAEzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACvG,YAAY,EACV,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AASjD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAMzF"}

package/dist/_internal/platform/runtime/tools/index.js

@@ -17,5 +17,8 @@ const DEFAULTS = {
  * @returns A fully configured PhasedToolExecutor instance.
  */
 export function createPhasedExecutor(config) {
-    return new PhasedToolExecutor({ ...DEFAULTS, ...config });
+    const enableBudgetEnforcement = config?.enableBudgetEnforcement
+        ?? config?.featureFlags?.isEnabled('runtime-tools-budget-enforcement')
+        ?? false;
+    return new PhasedToolExecutor({ ...DEFAULTS, ...config, enableBudgetEnforcement });
 }

package/dist/_internal/platform/runtime/tools/types.d.ts

@@ -1,4 +1,5 @@
 import type { ToolResult } from '../../types/tools.js';
+import type { FeatureFlagManager } from '../feature-flags/index.js';
 /**
  * BudgetExceedReason — typed discriminant for budget breach events.
  *
@@ -102,6 +103,11 @@ export interface ExecutorConfig {
      * ignored. Controlled by the `runtime-tools-budget-enforcement` feature flag.
      */
     enableBudgetEnforcement?: boolean;
+    /**
+     * Optional feature-flag manager used by createPhasedExecutor() to derive
+     * runtime-backed defaults. Explicit ExecutorConfig booleans still win.
+     */
+    featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null;
     /**
      * Optional idempotency store.
      *

package/dist/_internal/platform/runtime/tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,wBAAwB,GACxB,sBAAsB,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,WAAW,GACX,WAAW,GACX,cAAc,GACd,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,WAAW,GACX,cAAc,GACd,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,gCAAgC,EAAE,gBAAgB,CAAC;CAC1E;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,4EAA4E;IAC5E,YAAY,EAAE,kBAAkB,CAAC;IACjC,iHAAiH;IACjH,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,yBAAyB,EAAE,gBAAgB,CAAC;CACvE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,wBAAwB,GACxB,sBAAsB,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,WAAW,GACX,WAAW,GACX,cAAc,GACd,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,WAAW,GACX,cAAc,GACd,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,gCAAgC,EAAE,gBAAgB,CAAC;CAC1E;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,4EAA4E;IAC5E,YAAY,EAAE,kBAAkB,CAAC;IACjC,iHAAiH;IACjH,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,iBAAiB,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;IAC5D;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,yBAAyB,EAAE,gBAAgB,CAAC;CACvE"}

package/dist/_internal/platform/security/token-audit.d.ts

@@ -12,6 +12,7 @@
  * In advisory mode, violations are reported but not blocked.
  */
 import type { SecurityEvent } from '../runtime/events/security.js';
+import type { FeatureFlagReader } from '../runtime/feature-flags/index.js';
 /** Default rotation cadence: 90 days in ms. */
 export declare const DEFAULT_ROTATION_CADENCE_MS: number;
 /** Default warning threshold: 14 days before rotation deadline. */
@@ -116,6 +117,11 @@ export interface TokenAuditorConfig {
      * When false, violations are reported but tokens remain usable.
      */
     managed: boolean;
+    /**
+     * Feature flags gate managed blocking when supplied by SDK runtime services.
+     * Audits still report violations while disabled.
+     */
+    featureFlags?: FeatureFlagReader;
 }
 /**
  * Callback invoked after each token is audited in `auditAll()`.
@@ -153,6 +159,7 @@ export declare class ApiTokenAuditor {
     constructor(config?: TokenAuditorConfig, options?: {
         emitter?: SecurityEventEmitter;
     });
+    private _managedBlockingEnabled;
     /**
      * Register a scope policy. Policies must be registered before tokens that
      * reference them.

package/dist/_internal/platform/security/token-audit.d.ts.map

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

package/dist/_internal/platform/security/token-audit.js

@@ -12,6 +12,7 @@
  * In advisory mode, violations are reported but not blocked.
  */
 import { logger } from '../utils/logger.js';
+import { isFeatureGateEnabled } from '../runtime/feature-flags/index.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -53,6 +54,9 @@ export class ApiTokenAuditor {
         this._config = config;
         this._emitter = options?.emitter ?? ((_event) => { });
     }
+    _managedBlockingEnabled() {
+        return isFeatureGateEnabled(this._config.featureFlags, 'token-scope-rotation-audit');
+    }
     // -------------------------------------------------------------------------
     // Registry
     // -------------------------------------------------------------------------
@@ -185,7 +189,7 @@ export class ApiTokenAuditor {
             const isOverdue = rotation.outcome === 'overdue';
             const isWarning = rotation.outcome === 'warning';
             // In managed mode: block tokens with scope violations or overdue rotation
-            const isBlocked = this._config.managed && (hasViolation || isOverdue);
+            const isBlocked = this._config.managed && this._managedBlockingEnabled() && (hasViolation || isOverdue);
             const result = {
                 tokenId,
                 label: metadata.label,
@@ -256,7 +260,7 @@ export class ApiTokenAuditor {
      * Returns false when not in managed mode or when the token is not registered.
      */
     isBlocked(tokenId, now = Date.now()) {
-        if (!this._config.managed)
+        if (!this._config.managed || !this._managedBlockingEnabled())
             return false;
         const scope = this.auditScope(tokenId);
         if (!scope)

package/dist/_internal/platform/state/mode-manager.d.ts

@@ -1,4 +1,5 @@
 import type { DomainVerbosity } from '../runtime/notifications/types.js';
+import type { FeatureFlagReader } from '../runtime/feature-flags/index.js';
 export type ModePreset = 'default' | 'vibecoding' | 'justvibes' | (string & Record<never, never>);
 export interface VerbosityDefaults {
     write: string;
@@ -28,8 +29,14 @@ export declare const HITL_OPERATOR: HITLModeDefinition;
 export declare class ModeManager {
     private currentMode;
     private modes;
+    private readonly featureFlags;
     private hitlMode;
     private domainOverrides;
+    constructor(options?: {
+        readonly featureFlags?: FeatureFlagReader;
+    });
+    private hitlEnabled;
+    private requireHitlEnabled;
     getMode(): ModePreset;
     getModeDefinition(): ModeDefinition;
     setMode(mode: ModePreset): void;

package/dist/_internal/platform/state/mode-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mode-manager.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/state/mode-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMzE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAElG,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9C,WAAW,EAAE,QAAQ,GAAG,UAAU,CAAC;CACpC;AA6CD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,eAAe,CAAC;IACxC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,UAAU,EAAE,kBAMxB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,kBAM3B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,kBAM3B,CAAC;AAQF,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,KAAK,CAAyC;IAEtD,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAA2C;IAMlE,OAAO,IAAI,UAAU;IAIrB,iBAAiB,IAAI,cAAc;IAInC,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAS/B,SAAS,IAAI,cAAc,EAAE;IAI7B,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IASvC,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQlD,WAAW,IAAI,QAAQ;IAIvB,aAAa,IAAI,kBAAkB;IAInC;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAUjC,eAAe,IAAI,kBAAkB,EAAE;IAIvC,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI;IAIpE,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAInD,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAIrD,aAAa,CAAC,MAAM,EAAE;QACpB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QAC5C,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,yBAAyB,CAAC,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;QAC7D,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;KACtE,GAAG,IAAI;CAST"}
+{"version":3,"file":"mode-manager.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/state/mode-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAO3E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAElG,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9C,WAAW,EAAE,QAAQ,GAAG,UAAU,CAAC;CACpC;AA6CD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,eAAe,CAAC;IACxC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,UAAU,EAAE,kBAMxB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,kBAM3B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,kBAM3B,CAAC;AAQF,qBAAa,WAAW;IACtB,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IAEjD,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,eAAe,CAA2C;gBAEtD,OAAO,GAAE;QAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAA;KAAO;IAIvE,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,IAAI,UAAU;IAIrB,iBAAiB,IAAI,cAAc;IAInC,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAS/B,SAAS,IAAI,cAAc,EAAE;IAI7B,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IASvC,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQlD,WAAW,IAAI,QAAQ;IAKvB,aAAa,IAAI,kBAAkB;IAKnC;;;;;;;OAOG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAWjC,eAAe,IAAI,kBAAkB,EAAE;IAKvC,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI;IAKpE,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe;IAKnD,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IAKrD,aAAa,CAAC,MAAM,EAAE;QACpB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;QAC5C,gBAAgB,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,yBAAyB,CAAC,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;QAC7D,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;KACtE,GAAG,IAAI;CAUT"}

package/dist/_internal/platform/state/mode-manager.js

@@ -1,3 +1,4 @@
+import { isFeatureGateEnabled, requireFeatureGate } from '../runtime/feature-flags/index.js';
 const DEFAULT_VERBOSITY = {
     write: 'standard',
     edit: 'with_diff',
@@ -62,8 +63,18 @@ const HITL_PRESETS = [HITL_QUIET, HITL_BALANCED, HITL_OPERATOR];
 export class ModeManager {
     currentMode = 'default';
     modes = [...BUILT_IN_MODES];
+    featureFlags;
     hitlMode = 'balanced';
     domainOverrides = new Map();
+    constructor(options = {}) {
+        this.featureFlags = options.featureFlags ?? null;
+    }
+    hitlEnabled() {
+        return isFeatureGateEnabled(this.featureFlags, 'hitl-ux-modes');
+    }
+    requireHitlEnabled(operation) {
+        requireFeatureGate(this.featureFlags, 'hitl-ux-modes', operation);
+    }
     // -------------------------------------------------------------------------
     // Precision tool verbosity mode API
     // -------------------------------------------------------------------------
@@ -100,9 +111,13 @@ export class ModeManager {
     // HITL UX mode API.
     // -------------------------------------------------------------------------
     getHITLMode() {
+        if (!this.hitlEnabled())
+            return 'balanced';
         return this.hitlMode;
     }
     getHITLPreset() {
+        if (!this.hitlEnabled())
+            return HITL_BALANCED;
         return HITL_PRESETS.find((p) => p.name === this.hitlMode) ?? HITL_BALANCED;
     }
     /**
@@ -114,6 +129,7 @@ export class ModeManager {
      * any domain-specific overrides.
      */
     setHITLMode(mode) {
+        this.requireHitlEnabled('set HITL UX mode');
         const found = HITL_PRESETS.find((p) => p.name === mode);
         if (!found) {
             const available = HITL_PRESETS.map((p) => `"${p.name}"`).join(', ');
@@ -123,18 +139,27 @@ export class ModeManager {
         this.domainOverrides.clear();
     }
     listHITLPresets() {
+        if (!this.hitlEnabled())
+            return [];
         return [...HITL_PRESETS];
     }
     setDomainVerbosity(domain, verbosity) {
+        this.requireHitlEnabled('set HITL domain verbosity');
         this.domainOverrides.set(domain, verbosity);
     }
     getDomainVerbosity(domain) {
+        if (!this.hitlEnabled())
+            return HITL_BALANCED.defaultDomainVerbosity;
         return this.domainOverrides.get(domain) ?? this.getHITLPreset().defaultDomainVerbosity;
     }
     getDomainOverrides() {
+        if (!this.hitlEnabled())
+            return {};
         return Object.fromEntries(this.domainOverrides);
     }
     applyToRouter(router) {
+        if (!this.hitlEnabled())
+            return;
         const preset = this.getHITLPreset();
         router.setQuietWhileTyping(preset.quietWhileTyping);
         router.setBatchWindowMs?.(preset.batchWindowMs);

package/dist/_internal/platform/tools/index.d.ts

@@ -1,4 +1,5 @@
 import { ToolRegistry } from './registry.js';
+import type { Tool } from '../types/tools.js';
 import { FileStateCache } from '../state/file-cache.js';
 import { ProjectIndex } from '../state/project-index.js';
 import { ModeManager } from '../state/mode-manager.js';
@@ -21,6 +22,8 @@ import type { ServiceRegistry } from '../config/service-registry.js';
 import { OverflowHandler } from './shared/overflow.js';
 import type { SessionChangeTracker } from '../sessions/change-tracker.js';
 import type { ArchetypeLoader } from '../agents/archetypes.js';
+type ToolContractFeatureFlags = Pick<FeatureFlagManager, 'isEnabled'>;
+export declare function registerToolWithContractGate(registry: ToolRegistry, tool: Tool, featureFlags?: ToolContractFeatureFlags | null): void;
 /**
  * Register all built-in tools into the given registry.
  * Creates shared FileStateCache and ProjectIndex instances so read/write/edit
@@ -56,4 +59,5 @@ export declare function registerAllTools(registry: ToolRegistry, deps?: {
     fileCache: FileStateCache;
     projectIndex: ProjectIndex;
 };
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/tools/index.d.ts.map

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

package/dist/_internal/platform/tools/index.js

@@ -33,6 +33,17 @@ import { ProcessManager } from './shared/process-manager.js';
 import { AgentMessageBus } from '../agents/message-bus.js';
 import { CrossSessionTaskRegistry } from '../sessions/orchestration/index.js';
 import { OverflowHandler } from './shared/overflow.js';
+export function registerToolWithContractGate(registry, tool, featureFlags) {
+    const verifyContracts = featureFlags?.isEnabled('tool-contract-verification') ?? true;
+    if (!verifyContracts) {
+        registry.register(tool);
+        return;
+    }
+    registry.registerWithContract(tool, {
+        strictIdempotency: false,
+        strictPermissionClass: false,
+    });
+}
 /**
  * Register all built-in tools into the given registry.
  * Creates shared FileStateCache and ProjectIndex instances so read/write/edit
@@ -79,8 +90,11 @@ export function registerAllTools(registry, deps) {
         throw new Error('registerAllTools requires surfaceRoot');
     }
     const projectIndex = deps?.projectIndex ?? new ProjectIndex(workingDirectory);
-    registry.register(new ReadTool(projectIndex, fileCache));
-    registry.register(createWriteTool({
+    const registerTool = (tool) => {
+        registerToolWithContractGate(registry, tool, deps.featureFlags);
+    };
+    registerTool(new ReadTool(projectIndex, fileCache));
+    registerTool(createWriteTool({
         projectRoot: workingDirectory,
         fileCache,
         projectIndex,
@@ -89,20 +103,20 @@ export function registerAllTools(registry, deps) {
         toolLLM: deps.toolLLM,
         changeTracker: deps?.changeTracker,
     }));
-    registry.register(createEditTool(fileCache, {
+    registerTool(createEditTool(fileCache, {
         fileUndoManager,
         configManager: deps.configManager,
         toolLLM: deps.toolLLM,
         changeTracker: deps?.changeTracker,
     }));
-    registry.register(createFindTool(workingDirectory, deps.featureFlags));
-    registry.register(createExecTool(processManager, {
+    registerTool(createFindTool(workingDirectory, deps.featureFlags));
+    registerTool(createExecTool(processManager, {
         featureFlags: deps.featureFlags,
         overflowHandler: deps.overflowHandler,
     }));
-    registry.register(createAnalyzeTool(deps.toolLLM, deps.featureFlags, workingDirectory));
-    registry.register(new InspectTool(deps.featureFlags, workingDirectory));
-    registry.register(createAgentTool({
+    registerTool(createAnalyzeTool(deps.toolLLM, deps.featureFlags, workingDirectory));
+    registerTool(new InspectTool(deps.featureFlags, workingDirectory));
+    registerTool(createAgentTool({
         manager: agentManager,
         messageBus: agentMessageBus,
         configManager: deps.configManager,
@@ -111,38 +125,38 @@ export function registerAllTools(registry, deps) {
     }));
     const kvState = new KVState(undefined, workingDirectory);
     const hookDispatcher = new HookDispatcher();
-    registry.register(createStateTool(kvState, projectIndex, {
+    registerTool(createStateTool(kvState, projectIndex, {
         memoryDir: join(workingDirectory, '.goodvibes', 'memory'),
         hookDispatcher,
         modeManager,
     }));
-    registry.register(createWorkflowTool(workflowServices));
-    registry.register(createFetchTool({
+    registerTool(createWorkflowTool(workflowServices));
+    registerTool(createFetchTool({
         serviceRegistry: deps.serviceRegistry,
         featureFlags: deps.featureFlags,
     }));
     if (webSearchService) {
-        registry.register(createWebSearchTool(webSearchService));
+        registerTool(createWebSearchTool(webSearchService));
     }
-    registry.register(createRegistryTool(registry, {
+    registerTool(createRegistryTool(registry, {
         workingDirectory,
         homeDirectory: deps.configManager.getHomeDirectory() ?? undefined,
     }));
-    registry.register(createTaskTool(sessionOrchestration));
-    registry.register(createTeamTool({ surfaceRoot: deps.surfaceRoot }));
-    registry.register(createWorklistTool({ surfaceRoot: deps.surfaceRoot }));
+    registerTool(createTaskTool(sessionOrchestration));
+    registerTool(createTeamTool({ surfaceRoot: deps.surfaceRoot }));
+    registerTool(createWorklistTool({ surfaceRoot: deps.surfaceRoot }));
     if (mcpRegistry) {
-        registry.register(createMcpTool(mcpRegistry));
+        registerTool(createMcpTool(mcpRegistry));
     }
-    registry.register(createPacketTool({ workingDirectory, surfaceRoot: deps.surfaceRoot }));
-    registry.register(createQueryTool({ workingDirectory, surfaceRoot: deps.surfaceRoot }));
+    registerTool(createPacketTool({ workingDirectory, surfaceRoot: deps.surfaceRoot }));
+    registerTool(createQueryTool({ workingDirectory, surfaceRoot: deps.surfaceRoot }));
     if (remoteRunnerRegistry) {
-        registry.register(createRemoteTool(remoteRunnerRegistry));
+        registerTool(createRemoteTool(remoteRunnerRegistry));
     }
-    registry.register(createReplTool(deps.configManager, deps.sandboxSessionRegistry, {
+    registerTool(createReplTool(deps.configManager, deps.sandboxSessionRegistry, {
         surfaceRoot: deps.surfaceRoot,
     }));
-    registry.register(controlTool);
-    registry.register(createChannelTool(channelRegistry));
+    registerTool(controlTool);
+    registerTool(createChannelTool(channelRegistry));
     return { fileCache, projectIndex };
 }

package/dist/_internal/platform/tools/shared/overflow.d.ts

@@ -1,3 +1,4 @@
+import type { FeatureFlagReader } from '../../runtime/feature-flags/index.js';
 export declare const DEFAULT_MAX_CHARS = 50000;
 /**
  * RetentionPolicyConfig — limits enforced during cleanup for a spill backend.
@@ -111,6 +112,8 @@ export interface OverflowHandlerConfig {
     retention?: RetentionPolicyConfig;
     /** Inject a custom backend directly (takes precedence over spillBackend). */
     backend?: SpillBackend;
+    /** Feature flags gate alternate spill backends when supplied by SDK runtime services. */
+    featureFlags?: FeatureFlagReader;
 }
 /**
  * Handles large tool output by delegating overflow content to a pluggable

package/dist/_internal/platform/tools/shared/overflow.d.ts.map

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