cascade-ai 0.13.2 → 0.15.0

package/dist/index.d.cts

@@ -387,6 +387,10 @@ interface CascadeConfig {
     enableToolCreation?: boolean;
     /** Persist runtime-generated tools and reload them on startup (untrusted). Default: true. */
     persistDynamicTools?: boolean;
+    /** Project knowledge (world state) settings. */
+    knowledge?: {
+        factsExtraction?: boolean;
+    };
     plugins?: string[];
     localConcurrency?: number;
     localInferenceTimeoutMs?: number;
@@ -478,6 +482,12 @@ interface ToolsConfig {
     mcpTrusted?: string[];
     /** Web search backends — at least one should be configured for best results */
     webSearch?: WebSearchConfig;
+    /**
+     * Sandbox runtime for LLM-authored dynamic tools. 'isolate' = hard V8 isolate
+     * (isolated-vm, capability-confined), 'worker' = node:worker_threads,
+     * 'auto' (default) = isolate when available else worker.
+     */
+    dynamicToolSandbox?: 'isolate' | 'worker' | 'auto';
 }
 interface HooksConfig {
     preToolUse?: HookDefinition[];
@@ -818,7 +828,9 @@ declare class TaskAnalyzer {
      * Scores tier-eligible models using cost efficiency + historical performance.
      * Falls back to the priority-list default when no candidates have history.
      */
-    selectModel(prompt: string, tier: TierRole, selector: ModelSelector): Promise<ModelInfo | null>;
+    selectModel(prompt: string, tier: TierRole, selector: ModelSelector, opts?: {
+        requiresToolUse?: boolean;
+    }): Promise<ModelInfo | null>;
     /**
      * Record the outcome of a completed run across all tiers that were selected
      * during this session and persist stats to disk.
@@ -862,6 +874,20 @@ declare class MemoryStore {
     addMessage(message: StoredMessage): void;
     getSessionMessages(sessionId: string): StoredMessage[];
     searchMessages(query: string, limit?: number): StoredMessage[];
+    /** Full sessions (with messages) for the given ids, or ALL sessions. */
+    exportSessions(ids?: string[]): Session[];
+    /**
+     * Import sessions from a bundle. Returns the created `{id, title}` rows so
+     * the caller can mirror them into the runtime session list (the sidebar
+     * reads runtime_sessions, not sessions). Malformed entries are skipped.
+     */
+    importSessions(sessions: Session[]): Array<{
+        id: string;
+        title: string;
+    }>;
+    /** Import identities/personas, deduped by (case-insensitive) name — an
+     *  existing name is skipped, never replaced. Imports are never the default. */
+    importIdentities(identities: Identity[]): number;
     createIdentity(identity: Identity): void;
     updateIdentity(id: string, updates: Partial<Identity>): void;
     getIdentity(id: string): Identity | null;
@@ -884,6 +910,15 @@ declare class MemoryStore {
     getCacheAge(): number;
     saveModelProfile(modelId: string, provider: ProviderType, specializations: string[]): void;
     getModelProfile(modelId: string, provider: ProviderType): ModelInfo | undefined;
+    /**
+     * Persist a probed capability verdict (currently: native tool support) into
+     * the model's cached profile, merging with whatever is already recorded.
+     * Read back via getModelProfile — so a model is probed once ever, not once
+     * per run.
+     */
+    saveModelCapability(modelId: string, provider: ProviderType, caps: {
+        supportsToolUse?: boolean;
+    }): void;
     getProfiledModelIds(): string[];
     private toolResultCache;
     private static CACHEABLE_TOOLS;
@@ -923,6 +958,16 @@ interface PriceEntry {
     input: number;
     output: number;
 }
+/**
+ * Per-model capability facts from the same OpenRouter catalog the pricing fetch
+ * already downloads: context window, native tool support, and input modalities.
+ * Previously discarded — provider listModels() stubs guessed/hardcoded these.
+ */
+interface CapabilityEntry {
+    contextWindow?: number;
+    supportsTools?: boolean;
+    inputModalities?: string[];
+}
 interface LiveDataOptions {
     /** Master switch for live quality fetch. Default: true. */
     live?: boolean;
@@ -938,6 +983,7 @@ interface LiveDataOptions {
 declare class LiveDataProvider {
     private snapshot;
     private prices;
+    private capabilities;
     private source;
     private fetchedAt;
     private loaded;
@@ -953,7 +999,13 @@ declare class LiveDataProvider {
     refresh(force?: boolean): Promise<void>;
     private doRefresh;
     private fetchSnapshot;
-    private fetchPrices;
+    /**
+     * One fetch of the OpenRouter catalog yields BOTH pricing and capability
+     * facts (context window, native tool support, input modalities) — the
+     * capability fields used to be discarded while providers guessed/hardcoded
+     * them in their listModels() stubs.
+     */
+    private fetchCatalog;
     private saveCache;
     /** Quality profile for a model family, or null when we have no live/cached data. */
     getQualityProfile(family: string): BenchmarkProfile | null;
@@ -964,10 +1016,20 @@ declare class LiveDataProvider {
      * leaving the original untouched (so the shared catalog is never mutated).
      */
     applyLivePricing(models: ModelInfo[]): ModelInfo[];
+    /** Current capability facts for a model id, or null when unknown. */
+    getCapability(modelId: string): CapabilityEntry | null;
+    /**
+     * Returns capability-corrected copies of each model (originals untouched):
+     * real context windows replace the providers' hardcoded guesses, native
+     * tool support replaces the assume-by-provider default, and vision is set
+     * from the declared input modalities.
+     */
+    applyLiveCapabilities(models: ModelInfo[]): ModelInfo[];
     /** Where the active quality data came from — for /why and `cascade models`. */
     getDataSource(): DataSource;
     getGeneratedAt(): string | null;
     hasLivePricing(): boolean;
+    hasCapabilities(): boolean;
 }
 
 interface WorldStateEntry {
@@ -976,6 +1038,19 @@ interface WorldStateEntry {
     summary: string;
     workerId: string;
 }
+/**
+ * A single queryable fact in the project knowledge graph (world-state v2):
+ * an `(entity, relation) → value` triple with provenance. Facts are upserted on
+ * `(entity, relation)`, so a newer observation supersedes an older one instead of
+ * appending — T1/T2 query relevant facts by entity rather than replaying the log.
+ */
+interface WorldFact {
+    entity: string;
+    relation: string;
+    value: string;
+    sourceWorker: string;
+    timestamp: string;
+}
 declare class WorldStateDB {
     private workspacePath;
     private debugMode;
@@ -990,6 +1065,58 @@ declare class WorldStateDB {
     addEntry(workerId: string, summary: string): string;
     getAllEntries(): WorldStateEntry[];
     getFormattedState(): string;
+    /**
+     * Upsert a fact. `(entity, relation)` is normalized so casing/whitespace don't
+     * fragment the key; an existing pair is superseded (value + provenance updated)
+     * rather than duplicated. Empty entity/relation/value are ignored.
+     */
+    upsertFact(entity: string, relation: string, value: string, sourceWorker: string, timestamp?: string): void;
+    private rowToFact;
+    /** All facts whose entity matches one of the (normalized) query entities. */
+    getFactsForEntities(entities: string[]): WorldFact[];
+    /** Every fact (used for tests / debug / whole-graph views). */
+    getAllFacts(): WorldFact[];
+    /**
+     * A compact, human/LLM-readable fact block for T1/T2 planning. When `entities`
+     * is given, only facts about those entities are included; otherwise all facts.
+     * Returns '' when there are none so callers can fall back to the linear log.
+     */
+    getFormattedFacts(entities?: string[]): string;
+    /**
+     * A compact knowledge block for T1/T2 planning. When `prompt` is given, facts
+     * whose entity/relation/value mention a prompt token are preferred (relevance
+     * filter); otherwise, or when nothing matches, all facts are used (capped at
+     * `limit`). Returns '' when there are no facts, so the caller can fall back to
+     * the raw linear log — this replaces replaying the whole log during planning.
+     */
+    getFormattedKnowledge(prompt?: string, limit?: number): string;
+    exportKnowledge(): {
+        facts: WorldFact[];
+        worldLog: WorldStateEntry[];
+    };
+    /**
+     * Merge imported knowledge. Facts upsert on (entity, relation) with
+     * newer-timestamp-wins (a local fact newer than the imported one is kept);
+     * log entries append with fresh ids, skipping exact duplicates
+     * (worker + timestamp + summary). Returns counts of what actually landed.
+     */
+    importKnowledge(data: {
+        facts?: Array<{
+            entity?: string;
+            relation?: string;
+            value?: string;
+            sourceWorker?: string;
+            timestamp?: string;
+        }>;
+        worldLog?: Array<{
+            workerId?: string;
+            summary?: string;
+            timestamp?: string;
+        }>;
+    }): {
+        facts: number;
+        logEntries: number;
+    };
     private dumpDebugIfNeeded;
     close(): void;
 }
@@ -1095,6 +1222,18 @@ declare class CascadeRouter extends EventEmitter {
      * No-op if store is not provided.
      */
     profileModels(store: MemoryStore): Promise<void>;
+    /**
+     * One-time native tool-call probe for local/compat models with NO capability
+     * metadata. llama.cpp / LM Studio "/models" endpoints return ids only, so
+     * `supportsToolUse` stays undefined and the T3 tool gate ASSUMES native
+     * support — wrong for many local builds, which then fumble tool-format
+     * output. Each unknown model is probed once with a trivial tool; the verdict
+     * persists in the MemoryStore's model_cache (via the previously-dormant
+     * getModelProfile read-back), so a model is probed once EVER, not per run.
+     * Cloud providers are never probed — their metadata is authoritative.
+     */
+    probeLocalToolSupport(store: MemoryStore): Promise<void>;
+    private probeNativeToolCall;
     /**
      * Cascade Auto live data: discover/validate real model ids from each cloud
      * provider, then fetch current public quality scores + per-token prices and
@@ -1111,8 +1250,10 @@ declare class CascadeRouter extends EventEmitter {
      */
     private discoverProviderModels;
     /**
-     * Replace available models with live-priced copies and refresh the already
-     * resolved tier models so shared-tier cost accounting uses current prices.
+     * Replace available models with live-priced AND capability-corrected copies
+     * (real context windows, native tool support, vision from modalities), then
+     * refresh the already resolved tier models so shared-tier cost accounting and
+     * the tool-use gate both see current data.
      */
     private applyLivePricing;
     generate(tier: TierRole, options: GenerateOptions, onChunk?: (chunk: StreamChunk) => void, requireVision?: boolean): Promise<GenerateResult>;
@@ -1127,6 +1268,10 @@ declare class CascadeRouter extends EventEmitter {
         enabled: boolean;
         maxPerSection: number;
     };
+    /** Project-knowledge settings (config.knowledge). Facts extraction on by default. */
+    getKnowledgeConfig(): {
+        factsExtraction: boolean;
+    };
     /**
      * Resolved T3 wave execution mode. 'auto' becomes 'sequential' when the T3
      * tier resolves to a LOCAL model (the single-GPU queue serializes anyway, so
@@ -1169,7 +1314,9 @@ declare class CascadeRouter extends EventEmitter {
      * null when Cascade Auto is off (callers then use the shared tier model).
      * Pure heuristic — no extra LLM call.
      */
-    selectModelForSubtask(tier: TierRole, text: string): Promise<ModelInfo | null>;
+    selectModelForSubtask(tier: TierRole, text: string, opts?: {
+        requiresToolUse?: boolean;
+    }): Promise<ModelInfo | null>;
     getStats(): RouterStats;
     /**
      * What did delegation save? Compares actual spend against the
@@ -1468,6 +1615,7 @@ declare class PermissionEscalator extends EventEmitter {
     cancelAllPending(): void;
 }
 
+type SandboxMode = 'isolate' | 'worker' | 'auto';
 interface GeneratedToolSpec {
     name: string;
     description: string;
@@ -1489,12 +1637,14 @@ declare class ToolCreator {
     private workspacePath?;
     /** When false, persisted tools are neither loaded nor written. */
     private persistEnabled;
+    /** Sandbox runtime for generated tools; passed to each DynamicTool. */
+    private sandboxMode;
     private logger?;
     /** name → spec, for persistence, broadcast, and re-registration. */
     private specs;
     /** capability fingerprint → tool name, so the same need isn't re-generated. */
     private capabilityIndex;
-    constructor(router: CascadeRouter, registry: ToolRegistry, workspacePath?: string, persistEnabled?: boolean);
+    constructor(router: CascadeRouter, registry: ToolRegistry, workspacePath?: string, persistEnabled?: boolean, sandboxMode?: SandboxMode);
     setPermissionEscalator(escalator: PermissionEscalator): void;
     /** Route diagnostics through the host (Cascade) so they survive the Ink TUI. */
     setLogger(fn: (msg: string) => void): void;
@@ -2011,6 +2161,14 @@ declare class T3Worker extends BaseTier {
      */
     private reflectAndImprove;
     private selfTest;
+    /**
+     * world-state v2: distill a completed subtask's output into durable
+     * `(entity, relation, value)` facts and upsert them into the knowledge graph.
+     * A bounded, cheap T3-tier call; entirely best-effort — any failure is swallowed
+     * so it never blocks or fails the subtask. Respects the subtask's privacy tier
+     * (a local-only subtask extracts on a local model too, never leaking to cloud).
+     */
+    private extractAndStoreFacts;
     private correctOutput;
     private buildSystemPrompt;
     private buildInitialPrompt;

package/dist/index.d.ts

@@ -387,6 +387,10 @@ interface CascadeConfig {
     enableToolCreation?: boolean;
     /** Persist runtime-generated tools and reload them on startup (untrusted). Default: true. */
     persistDynamicTools?: boolean;
+    /** Project knowledge (world state) settings. */
+    knowledge?: {
+        factsExtraction?: boolean;
+    };
     plugins?: string[];
     localConcurrency?: number;
     localInferenceTimeoutMs?: number;
@@ -478,6 +482,12 @@ interface ToolsConfig {
     mcpTrusted?: string[];
     /** Web search backends — at least one should be configured for best results */
     webSearch?: WebSearchConfig;
+    /**
+     * Sandbox runtime for LLM-authored dynamic tools. 'isolate' = hard V8 isolate
+     * (isolated-vm, capability-confined), 'worker' = node:worker_threads,
+     * 'auto' (default) = isolate when available else worker.
+     */
+    dynamicToolSandbox?: 'isolate' | 'worker' | 'auto';
 }
 interface HooksConfig {
     preToolUse?: HookDefinition[];
@@ -818,7 +828,9 @@ declare class TaskAnalyzer {
      * Scores tier-eligible models using cost efficiency + historical performance.
      * Falls back to the priority-list default when no candidates have history.
      */
-    selectModel(prompt: string, tier: TierRole, selector: ModelSelector): Promise<ModelInfo | null>;
+    selectModel(prompt: string, tier: TierRole, selector: ModelSelector, opts?: {
+        requiresToolUse?: boolean;
+    }): Promise<ModelInfo | null>;
     /**
      * Record the outcome of a completed run across all tiers that were selected
      * during this session and persist stats to disk.
@@ -862,6 +874,20 @@ declare class MemoryStore {
     addMessage(message: StoredMessage): void;
     getSessionMessages(sessionId: string): StoredMessage[];
     searchMessages(query: string, limit?: number): StoredMessage[];
+    /** Full sessions (with messages) for the given ids, or ALL sessions. */
+    exportSessions(ids?: string[]): Session[];
+    /**
+     * Import sessions from a bundle. Returns the created `{id, title}` rows so
+     * the caller can mirror them into the runtime session list (the sidebar
+     * reads runtime_sessions, not sessions). Malformed entries are skipped.
+     */
+    importSessions(sessions: Session[]): Array<{
+        id: string;
+        title: string;
+    }>;
+    /** Import identities/personas, deduped by (case-insensitive) name — an
+     *  existing name is skipped, never replaced. Imports are never the default. */
+    importIdentities(identities: Identity[]): number;
     createIdentity(identity: Identity): void;
     updateIdentity(id: string, updates: Partial<Identity>): void;
     getIdentity(id: string): Identity | null;
@@ -884,6 +910,15 @@ declare class MemoryStore {
     getCacheAge(): number;
     saveModelProfile(modelId: string, provider: ProviderType, specializations: string[]): void;
     getModelProfile(modelId: string, provider: ProviderType): ModelInfo | undefined;
+    /**
+     * Persist a probed capability verdict (currently: native tool support) into
+     * the model's cached profile, merging with whatever is already recorded.
+     * Read back via getModelProfile — so a model is probed once ever, not once
+     * per run.
+     */
+    saveModelCapability(modelId: string, provider: ProviderType, caps: {
+        supportsToolUse?: boolean;
+    }): void;
     getProfiledModelIds(): string[];
     private toolResultCache;
     private static CACHEABLE_TOOLS;
@@ -923,6 +958,16 @@ interface PriceEntry {
     input: number;
     output: number;
 }
+/**
+ * Per-model capability facts from the same OpenRouter catalog the pricing fetch
+ * already downloads: context window, native tool support, and input modalities.
+ * Previously discarded — provider listModels() stubs guessed/hardcoded these.
+ */
+interface CapabilityEntry {
+    contextWindow?: number;
+    supportsTools?: boolean;
+    inputModalities?: string[];
+}
 interface LiveDataOptions {
     /** Master switch for live quality fetch. Default: true. */
     live?: boolean;
@@ -938,6 +983,7 @@ interface LiveDataOptions {
 declare class LiveDataProvider {
     private snapshot;
     private prices;
+    private capabilities;
     private source;
     private fetchedAt;
     private loaded;
@@ -953,7 +999,13 @@ declare class LiveDataProvider {
     refresh(force?: boolean): Promise<void>;
     private doRefresh;
     private fetchSnapshot;
-    private fetchPrices;
+    /**
+     * One fetch of the OpenRouter catalog yields BOTH pricing and capability
+     * facts (context window, native tool support, input modalities) — the
+     * capability fields used to be discarded while providers guessed/hardcoded
+     * them in their listModels() stubs.
+     */
+    private fetchCatalog;
     private saveCache;
     /** Quality profile for a model family, or null when we have no live/cached data. */
     getQualityProfile(family: string): BenchmarkProfile | null;
@@ -964,10 +1016,20 @@ declare class LiveDataProvider {
      * leaving the original untouched (so the shared catalog is never mutated).
      */
     applyLivePricing(models: ModelInfo[]): ModelInfo[];
+    /** Current capability facts for a model id, or null when unknown. */
+    getCapability(modelId: string): CapabilityEntry | null;
+    /**
+     * Returns capability-corrected copies of each model (originals untouched):
+     * real context windows replace the providers' hardcoded guesses, native
+     * tool support replaces the assume-by-provider default, and vision is set
+     * from the declared input modalities.
+     */
+    applyLiveCapabilities(models: ModelInfo[]): ModelInfo[];
     /** Where the active quality data came from — for /why and `cascade models`. */
     getDataSource(): DataSource;
     getGeneratedAt(): string | null;
     hasLivePricing(): boolean;
+    hasCapabilities(): boolean;
 }
 
 interface WorldStateEntry {
@@ -976,6 +1038,19 @@ interface WorldStateEntry {
     summary: string;
     workerId: string;
 }
+/**
+ * A single queryable fact in the project knowledge graph (world-state v2):
+ * an `(entity, relation) → value` triple with provenance. Facts are upserted on
+ * `(entity, relation)`, so a newer observation supersedes an older one instead of
+ * appending — T1/T2 query relevant facts by entity rather than replaying the log.
+ */
+interface WorldFact {
+    entity: string;
+    relation: string;
+    value: string;
+    sourceWorker: string;
+    timestamp: string;
+}
 declare class WorldStateDB {
     private workspacePath;
     private debugMode;
@@ -990,6 +1065,58 @@ declare class WorldStateDB {
     addEntry(workerId: string, summary: string): string;
     getAllEntries(): WorldStateEntry[];
     getFormattedState(): string;
+    /**
+     * Upsert a fact. `(entity, relation)` is normalized so casing/whitespace don't
+     * fragment the key; an existing pair is superseded (value + provenance updated)
+     * rather than duplicated. Empty entity/relation/value are ignored.
+     */
+    upsertFact(entity: string, relation: string, value: string, sourceWorker: string, timestamp?: string): void;
+    private rowToFact;
+    /** All facts whose entity matches one of the (normalized) query entities. */
+    getFactsForEntities(entities: string[]): WorldFact[];
+    /** Every fact (used for tests / debug / whole-graph views). */
+    getAllFacts(): WorldFact[];
+    /**
+     * A compact, human/LLM-readable fact block for T1/T2 planning. When `entities`
+     * is given, only facts about those entities are included; otherwise all facts.
+     * Returns '' when there are none so callers can fall back to the linear log.
+     */
+    getFormattedFacts(entities?: string[]): string;
+    /**
+     * A compact knowledge block for T1/T2 planning. When `prompt` is given, facts
+     * whose entity/relation/value mention a prompt token are preferred (relevance
+     * filter); otherwise, or when nothing matches, all facts are used (capped at
+     * `limit`). Returns '' when there are no facts, so the caller can fall back to
+     * the raw linear log — this replaces replaying the whole log during planning.
+     */
+    getFormattedKnowledge(prompt?: string, limit?: number): string;
+    exportKnowledge(): {
+        facts: WorldFact[];
+        worldLog: WorldStateEntry[];
+    };
+    /**
+     * Merge imported knowledge. Facts upsert on (entity, relation) with
+     * newer-timestamp-wins (a local fact newer than the imported one is kept);
+     * log entries append with fresh ids, skipping exact duplicates
+     * (worker + timestamp + summary). Returns counts of what actually landed.
+     */
+    importKnowledge(data: {
+        facts?: Array<{
+            entity?: string;
+            relation?: string;
+            value?: string;
+            sourceWorker?: string;
+            timestamp?: string;
+        }>;
+        worldLog?: Array<{
+            workerId?: string;
+            summary?: string;
+            timestamp?: string;
+        }>;
+    }): {
+        facts: number;
+        logEntries: number;
+    };
     private dumpDebugIfNeeded;
     close(): void;
 }
@@ -1095,6 +1222,18 @@ declare class CascadeRouter extends EventEmitter {
      * No-op if store is not provided.
      */
     profileModels(store: MemoryStore): Promise<void>;
+    /**
+     * One-time native tool-call probe for local/compat models with NO capability
+     * metadata. llama.cpp / LM Studio "/models" endpoints return ids only, so
+     * `supportsToolUse` stays undefined and the T3 tool gate ASSUMES native
+     * support — wrong for many local builds, which then fumble tool-format
+     * output. Each unknown model is probed once with a trivial tool; the verdict
+     * persists in the MemoryStore's model_cache (via the previously-dormant
+     * getModelProfile read-back), so a model is probed once EVER, not per run.
+     * Cloud providers are never probed — their metadata is authoritative.
+     */
+    probeLocalToolSupport(store: MemoryStore): Promise<void>;
+    private probeNativeToolCall;
     /**
      * Cascade Auto live data: discover/validate real model ids from each cloud
      * provider, then fetch current public quality scores + per-token prices and
@@ -1111,8 +1250,10 @@ declare class CascadeRouter extends EventEmitter {
      */
     private discoverProviderModels;
     /**
-     * Replace available models with live-priced copies and refresh the already
-     * resolved tier models so shared-tier cost accounting uses current prices.
+     * Replace available models with live-priced AND capability-corrected copies
+     * (real context windows, native tool support, vision from modalities), then
+     * refresh the already resolved tier models so shared-tier cost accounting and
+     * the tool-use gate both see current data.
      */
     private applyLivePricing;
     generate(tier: TierRole, options: GenerateOptions, onChunk?: (chunk: StreamChunk) => void, requireVision?: boolean): Promise<GenerateResult>;
@@ -1127,6 +1268,10 @@ declare class CascadeRouter extends EventEmitter {
         enabled: boolean;
         maxPerSection: number;
     };
+    /** Project-knowledge settings (config.knowledge). Facts extraction on by default. */
+    getKnowledgeConfig(): {
+        factsExtraction: boolean;
+    };
     /**
      * Resolved T3 wave execution mode. 'auto' becomes 'sequential' when the T3
      * tier resolves to a LOCAL model (the single-GPU queue serializes anyway, so
@@ -1169,7 +1314,9 @@ declare class CascadeRouter extends EventEmitter {
      * null when Cascade Auto is off (callers then use the shared tier model).
      * Pure heuristic — no extra LLM call.
      */
-    selectModelForSubtask(tier: TierRole, text: string): Promise<ModelInfo | null>;
+    selectModelForSubtask(tier: TierRole, text: string, opts?: {
+        requiresToolUse?: boolean;
+    }): Promise<ModelInfo | null>;
     getStats(): RouterStats;
     /**
      * What did delegation save? Compares actual spend against the
@@ -1468,6 +1615,7 @@ declare class PermissionEscalator extends EventEmitter {
     cancelAllPending(): void;
 }
 
+type SandboxMode = 'isolate' | 'worker' | 'auto';
 interface GeneratedToolSpec {
     name: string;
     description: string;
@@ -1489,12 +1637,14 @@ declare class ToolCreator {
     private workspacePath?;
     /** When false, persisted tools are neither loaded nor written. */
     private persistEnabled;
+    /** Sandbox runtime for generated tools; passed to each DynamicTool. */
+    private sandboxMode;
     private logger?;
     /** name → spec, for persistence, broadcast, and re-registration. */
     private specs;
     /** capability fingerprint → tool name, so the same need isn't re-generated. */
     private capabilityIndex;
-    constructor(router: CascadeRouter, registry: ToolRegistry, workspacePath?: string, persistEnabled?: boolean);
+    constructor(router: CascadeRouter, registry: ToolRegistry, workspacePath?: string, persistEnabled?: boolean, sandboxMode?: SandboxMode);
     setPermissionEscalator(escalator: PermissionEscalator): void;
     /** Route diagnostics through the host (Cascade) so they survive the Ink TUI. */
     setLogger(fn: (msg: string) => void): void;
@@ -2011,6 +2161,14 @@ declare class T3Worker extends BaseTier {
      */
     private reflectAndImprove;
     private selfTest;
+    /**
+     * world-state v2: distill a completed subtask's output into durable
+     * `(entity, relation, value)` facts and upsert them into the knowledge graph.
+     * A bounded, cheap T3-tier call; entirely best-effort — any failure is swallowed
+     * so it never blocks or fails the subtask. Respects the subtask's privacy tier
+     * (a local-only subtask extracts on a local model too, never leaking to cloud).
+     */
+    private extractAndStoreFacts;
     private correctOutput;
     private buildSystemPrompt;
     private buildInitialPrompt;