@almadar/agent 2.0.0 → 2.0.1

package/dist/tools/sandbox-executor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SandboxExecutor — V8 isolate-based sandboxed code execution.
+ *
+ * Uses `isolated-vm` to run untrusted code in a separate V8 context
+ * with configurable memory and time limits. Stronger isolation than
+ * Node.js `vm` module (separate heap, no shared references).
+ *
+ * This is an Almadar-specific addition to the IC-AGI security layer.
+ * It will be contributed to almadar-io/ic-agi as an optional module.
+ */
+export interface SandboxOptions {
+    /** Execution timeout in milliseconds. Default: 5000 */
+    timeoutMs?: number;
+    /** Memory limit for the isolate in MB. Default: 32 */
+    memoryLimitMb?: number;
+}
+export interface SandboxResult {
+    success: boolean;
+    value?: unknown;
+    error?: string;
+    timedOut?: boolean;
+}
+/**
+ * Execute a JavaScript code string inside a V8 isolate.
+ *
+ * The `inputs` object is copied into the isolate as a global `inputs` variable.
+ * The code should return a value or assign to a global `result` variable.
+ *
+ * Falls back gracefully if `isolated-vm` is not available in the environment.
+ */
+export declare function executeSandboxed(code: string, inputs?: Record<string, unknown>, options?: SandboxOptions): Promise<SandboxResult>;

package/dist/tools/schema-chunking.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Schema Chunking Tools
+ *
+ * Tools for extracting and merging chunks of large orbital schemas.
+ * Enables LLM-driven schema updates without hitting token limits.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+export declare function createQuerySchemaStructureTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    file: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+}, {
+    file: string;
+}>, {
+    file: string;
+}, {
+    file: string;
+}, string, "query_schema_structure">;
+export declare function createExtractChunkTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    file: z.ZodString;
+    type: z.ZodEnum<["orbital", "trait", "inline-trait"]>;
+    name: z.ZodString;
+    parentOrbital: z.ZodOptional<z.ZodString>;
+    includeTraits: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "orbital" | "trait" | "inline-trait";
+    name: string;
+    file: string;
+    includeTraits: boolean;
+    parentOrbital?: string | undefined;
+}, {
+    type: "orbital" | "trait" | "inline-trait";
+    name: string;
+    file: string;
+    parentOrbital?: string | undefined;
+    includeTraits?: boolean | undefined;
+}>, {
+    type: "orbital" | "trait" | "inline-trait";
+    name: string;
+    file: string;
+    includeTraits: boolean;
+    parentOrbital?: string | undefined;
+}, {
+    type: "orbital" | "trait" | "inline-trait";
+    name: string;
+    file: string;
+    parentOrbital?: string | undefined;
+    includeTraits?: boolean | undefined;
+}, string, "extract_chunk">;
+export declare function createApplyChunkTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    chunkId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    chunkId: string;
+}, {
+    chunkId: string;
+}>, {
+    chunkId: string;
+}, {
+    chunkId: string;
+}, string, "apply_chunk">;
+export declare function createSchemaChunkingTools(workDir: string): {
+    querySchemaStructure: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        file: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+    }, {
+        file: string;
+    }>, {
+        file: string;
+    }, {
+        file: string;
+    }, string, "query_schema_structure">;
+    extractChunk: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        file: z.ZodString;
+        type: z.ZodEnum<["orbital", "trait", "inline-trait"]>;
+        name: z.ZodString;
+        parentOrbital: z.ZodOptional<z.ZodString>;
+        includeTraits: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "orbital" | "trait" | "inline-trait";
+        name: string;
+        file: string;
+        includeTraits: boolean;
+        parentOrbital?: string | undefined;
+    }, {
+        type: "orbital" | "trait" | "inline-trait";
+        name: string;
+        file: string;
+        parentOrbital?: string | undefined;
+        includeTraits?: boolean | undefined;
+    }>, {
+        type: "orbital" | "trait" | "inline-trait";
+        name: string;
+        file: string;
+        includeTraits: boolean;
+        parentOrbital?: string | undefined;
+    }, {
+        type: "orbital" | "trait" | "inline-trait";
+        name: string;
+        file: string;
+        parentOrbital?: string | undefined;
+        includeTraits?: boolean | undefined;
+    }, string, "extract_chunk">;
+    applyChunk: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        chunkId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        chunkId: string;
+    }, {
+        chunkId: string;
+    }>, {
+        chunkId: string;
+    }, {
+        chunkId: string;
+    }, string, "apply_chunk">;
+};

package/dist/tools/trait-subagent.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Trait Subagent Tool
+ *
+ * Generates custom trait definitions for orbital schemas.
+ * Uses @almadar/llm LLMClient directly.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import type { Trait } from '@almadar/core/types';
+import type { SSEEventType } from '../api-types.js';
+export type TraitEventCallback = (traitName: string, traitIndex: number, totalTraits: number, event: {
+    type: Exclude<SSEEventType, 'subagent_event'>;
+    data: Record<string, unknown>;
+    timestamp: number;
+}) => void;
+export type TraitCompleteCallback = (trait: Trait, traitName: string, traitIndex: number, totalTraits: number) => void | Promise<void>;
+export interface TraitSubagentToolOptions {
+    onTraitEvent?: TraitEventCallback;
+    onTraitComplete?: TraitCompleteCallback;
+}
+export interface TraitSpec {
+    name: string;
+    description: string;
+    category?: string;
+    states?: string[];
+    events?: string[];
+    requiredFields?: Array<{
+        name: string;
+        type: string;
+        description?: string;
+    }>;
+    needsTicks?: boolean;
+    needsEmit?: boolean;
+    needsListens?: boolean;
+}
+/**
+ * Create a tool for generating custom traits.
+ * Uses @almadar/llm LLMClient directly.
+ */
+export declare function createTraitSubagentTool(options?: TraitSubagentToolOptions): {
+    tool: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        traitSpec: z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            category: z.ZodOptional<z.ZodString>;
+            states: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            requiredFields: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }, {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }>, "many">>;
+            needsTicks: z.ZodOptional<z.ZodBoolean>;
+            needsEmit: z.ZodOptional<z.ZodBoolean>;
+            needsListens: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        }, {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        }>;
+        traitIndex: z.ZodOptional<z.ZodNumber>;
+        totalTraits: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        traitSpec: {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        };
+        traitIndex?: number | undefined;
+        totalTraits?: number | undefined;
+    }, {
+        traitSpec: {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        };
+        traitIndex?: number | undefined;
+        totalTraits?: number | undefined;
+    }>, {
+        traitSpec: {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        };
+        traitIndex?: number | undefined;
+        totalTraits?: number | undefined;
+    }, {
+        traitSpec: {
+            name: string;
+            description: string;
+            states?: string[] | undefined;
+            events?: string[] | undefined;
+            category?: string | undefined;
+            requiredFields?: {
+                type: string;
+                name: string;
+                description?: string | undefined;
+            }[] | undefined;
+            needsTicks?: boolean | undefined;
+            needsEmit?: boolean | undefined;
+            needsListens?: boolean | undefined;
+        };
+        traitIndex?: number | undefined;
+        totalTraits?: number | undefined;
+    }, string, "generate_custom_trait">;
+    setEventCallback: (callback: TraitEventCallback) => void;
+    setTraitCompleteCallback: (callback: TraitCompleteCallback) => void;
+};
+/**
+ * Create a helper to wrap trait events into SSE format.
+ */
+export declare function createTraitEventWrapper(writeEvent: (event: {
+    type: string;
+    timestamp: number;
+    data: unknown;
+}) => void): TraitEventCallback;

package/dist/tools/validate-schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema Validation Tool
+ *
+ * Validates orbital schemas using the @almadar/cli npm package.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Create a validate_schema tool that validates schema.orb in the workspace.
+ *
+ * Uses `npx @almadar/cli validate --json` for comprehensive Rust-based validation.
+ *
+ * Has a built-in cap of MAX_VALIDATION_ATTEMPTS to prevent
+ * infinite validation-fix loops.
+ */
+export declare function createValidateSchemaTool(workDir: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, {}, {}, string, "validate_schema">;

package/dist/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @almadar/agent Types
+ *
+ * Core types for the agent package.
+ *
+ * LLM access is provided by @almadar/llm (imported directly).
+ * Skill prompts are provided by @almadar/skills (imported directly).
+ *
+ * Only builder-specific modules that don't exist as almadar packages
+ * use dependency injection via AgentDependencies.
+ *
+ * @packageDocumentation
+ */
+import type { OrbitalSchema, OrbitalDefinition } from '@almadar/core/types';
+import type { FullOrbitalUnit } from '@almadar/core/types';
+import type { LLMClient } from '@almadar/llm';
+/**
+ * Options for combining orbitals into a schema.
+ */
+export interface CombinerOptions {
+    name: string;
+    description?: string;
+    version?: string;
+    theme?: string;
+    defaultRoute?: string;
+    validate?: boolean;
+}
+/**
+ * Result from combining orbitals.
+ */
+export interface CombinerResult {
+    success: boolean;
+    schema?: OrbitalSchema;
+    error?: string;
+    stats?: {
+        totalOrbitals: number;
+        totalEntities: number;
+        totalPages: number;
+        totalTraits: number;
+    };
+    validation?: {
+        valid: boolean;
+        errors: Array<{
+            code: string;
+            path: string;
+            message: string;
+        }>;
+        warnings: Array<{
+            code: string;
+            path: string;
+            message: string;
+        }>;
+    };
+}
+/**
+ * Function signature for combining orbitals.
+ */
+export type CombineOrbitalsFn = (orbitals: FullOrbitalUnit[], options: CombinerOptions) => CombinerResult;
+/**
+ * Result from converting domain language to schema.
+ */
+export interface DomainConversionResult {
+    success: boolean;
+    schema?: OrbitalSchema;
+    errors?: Array<{
+        message: string;
+    }>;
+}
+/**
+ * Function signature for converting domain text to schema.
+ */
+export type ConvertDomainToSchemaFn = (domainText: string, baseSchema: {
+    name: string;
+    orbitals: unknown[];
+}) => DomainConversionResult;
+/**
+ * Log entry from orbital generation.
+ */
+export interface GenerationLog {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Result from orbital generation.
+ */
+export interface OrbitalGenerationResult {
+    orbital: unknown;
+    fingerprint?: string;
+    usedTemplate?: boolean;
+    usage?: {
+        totalTokens: number;
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    validation?: {
+        valid: boolean;
+        errors?: Array<{
+            code: string;
+            path: string;
+            message: string;
+        }>;
+    };
+}
+/**
+ * Options for orbital generation.
+ */
+export interface OrbitalGenerationOptions {
+    validate?: boolean;
+    requirements?: {
+        entities?: string[];
+        states?: string[];
+        events?: string[];
+        guards?: string[];
+        pages?: string[];
+        effects?: string[];
+        rawRequirements?: string[];
+    };
+    onLog?: (log: GenerationLog) => void;
+}
+/**
+ * Function signature for generating a full orbital.
+ * Accepts LLMClient from @almadar/llm directly.
+ */
+export type GenerateFullOrbitalFn = (client: LLMClient, orbital: OrbitalDefinition, options?: OrbitalGenerationOptions) => Promise<OrbitalGenerationResult>;
+/**
+ * @deprecated AgentDependencies is no longer needed. All functions are now
+ * internal to @almadar/agent. Import them directly:
+ * - combineOrbitals from '@almadar/agent'
+ * - convertDomainToSchema from '@almadar/agent'
+ * - generateFullOrbital from '@almadar/agent'
+ *
+ * @example Old (deprecated):
+ * ```typescript
+ * const deps: AgentDependencies = { ... };
+ * const tools = createAgentTools('/workspace', deps);
+ * ```
+ *
+ * @example New:
+ * ```typescript
+ * import { createAgentTools } from '@almadar/agent';
+ * const tools = createAgentTools('/workspace');
+ * ```
+ */
+export interface AgentDependencies {
+    /**
+     * @deprecated Use combineOrbitals from '@almadar/agent' instead
+     */
+    combineOrbitals: CombineOrbitalsFn;
+    /**
+     * @deprecated Use convertDomainToSchema from '@almadar/agent' instead
+     */
+    convertDomainToSchema: ConvertDomainToSchemaFn;
+    /**
+     * @deprecated Use generateFullOrbital from '@almadar/agent' instead
+     */
+    generateFullOrbital: GenerateFullOrbitalFn;
+}
+/**
+ * Subagent configuration.
+ * Compatible with the deepagents library SubAgent type.
+ */
+export interface SubAgent {
+    name: string;
+    description: string;
+    systemPrompt: string;
+}

package/dist/utils/safety/capability-token.d.ts

@@ -0,0 +1,50 @@
+/**
+ * CapabilityToken — HMAC-SHA256 signed scoped token with budget + TTL.
+ *
+ * TypeScript port of saezbaldo/ic-agi `ic_agi/control_plane.py`.
+ * See: https://github.com/saezbaldo/ic-agi
+ *
+ * TLA+ properties verified in CapabilityTokens.tla:
+ *   P5 AntiReplay:         uses <= budget (invariant)
+ *   P6 TTLEnforcement:     expired tokens produce no log entries
+ *   P7 RevocationFinality: revoked = true => uses frozen forever
+ *   P8 BudgetMonotonicity: uses never decreases
+ *   P9 ForgeryResistance:  invalid signature => uses never incremented
+ */
+export interface CapabilityToken {
+    tokenId: string;
+    issuedTo: string;
+    /** Sorted alphabetically for determinism. */
+    scope: string[];
+    /** Unix epoch seconds. */
+    issuedAt: number;
+    /** Unix epoch seconds. */
+    expiresAt: number;
+    budget: number;
+    uses: number;
+    revoked: boolean;
+    metadata: Record<string, unknown>;
+    /** HMAC-SHA256 hex digest over the immutable fields. */
+    signature: string;
+}
+export interface TokenParams {
+    issuedTo: string;
+    scope: string[];
+    ttlSeconds?: number;
+    budget?: number;
+    criticality?: 'low' | 'medium' | 'high' | 'critical';
+    metadata?: Record<string, unknown>;
+}
+/** Issue a new signed capability token. TTL and budget are policy-capped. */
+export declare function issueToken(params: TokenParams, signingKey: Buffer): CapabilityToken;
+/** Verify the token's HMAC signature. Uses constant-time comparison (P9). */
+export declare function verifyToken(token: CapabilityToken, signingKey: Buffer): boolean;
+/** Check if the token can be used (not revoked, not expired, has remaining budget). */
+export declare function isTokenValid(token: CapabilityToken): boolean;
+/**
+ * Consume one use from the token.
+ * Returns false without mutating if the token is invalid (P5, P8).
+ */
+export declare function consumeToken(token: CapabilityToken): boolean;
+/** Permanently revoke a token. Immutable once set (P7). */
+export declare function revokeToken(token: CapabilityToken): void;

package/dist/utils/safety/circuit-breaker.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CircuitBreaker — Fault isolation state machine per worker/session.
+ *
+ * TypeScript port of saezbaldo/ic-agi `ic_agi/circuit_breaker.py`.
+ * See: https://github.com/saezbaldo/ic-agi
+ *
+ * State machine:
+ *   CLOSED → OPEN         when consecutive failures >= threshold OR error rate >= 50%
+ *   OPEN   → HALF_OPEN    after recovery timeout (probe request allowed through)
+ *   HALF_OPEN → CLOSED    when consecutive successes >= success threshold
+ *   HALF_OPEN → OPEN      on any failure (immediate trip)
+ *
+ * Error rate guard only fires when totalRequests >= 5 to prevent
+ * tripping on a single noisy startup failure.
+ */
+import type { AuditLog } from '../../security/audit-log.js';
+export declare enum CircuitState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerConfig {
+    /** Consecutive failures before tripping. Default: 3 */
+    failureThreshold?: number;
+    /** Consecutive successes in HALF_OPEN before closing. Default: 2 */
+    successThreshold?: number;
+    /** Seconds in OPEN before allowing a probe request. Default: 30 */
+    recoveryTimeoutSeconds?: number;
+    /** Window in seconds for error-rate calculation. Default: 120 */
+    errorRateWindow?: number;
+    /** Error rate threshold (0–1) to trigger OPEN. Default: 0.5 */
+    errorRateThreshold?: number;
+}
+interface WorkerCircuit {
+    workerId: string;
+    state: CircuitState;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    totalRequests: number;
+    totalFailures: number;
+    lastFailureTime: number;
+    openedAt: number;
+    lastTransitionTime: number;
+    /** Sliding window of (timestamp, success) pairs. */
+    recent: Array<{
+        timestamp: number;
+        success: boolean;
+    }>;
+}
+export declare class CircuitBreaker {
+    private readonly circuits;
+    private readonly config;
+    private readonly auditLog?;
+    constructor(config?: CircuitBreakerConfig, auditLog?: AuditLog);
+    private getOrCreate;
+    /** Compute error rate for the worker within the configured window. Prunes stale entries. */
+    private errorRate;
+    private transition;
+    /**
+     * Check whether the worker is allowed to proceed.
+     * - CLOSED: always allowed
+     * - OPEN:   blocked until recovery timeout, then transitions to HALF_OPEN
+     * - HALF_OPEN: probe allowed through
+     */
+    allow(workerId: string): boolean;
+    recordSuccess(workerId: string): void;
+    recordFailure(workerId: string): void;
+    getState(workerId: string): CircuitState;
+    getStats(workerId: string): Pick<WorkerCircuit, 'state' | 'consecutiveFailures' | 'totalRequests' | 'totalFailures'>;
+}
+export {};

package/dist/utils/safety/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Safety Utilities — IC-AGI TypeScript ports
+ *
+ * Extracted from the original `src/security/` module.
+ * These are standalone safety primitives (circuit breaker, rate limiter,
+ * threshold authorization, capability tokens) with no agent-specific deps.
+ *
+ * See: https://github.com/saezbaldo/ic-agi
+ */
+export { AuditLog } from '../../security/audit-log.js';
+export type { AuditEntry } from '../../security/audit-log.js';
+export { issueToken, verifyToken, isTokenValid, consumeToken, revokeToken, } from './capability-token.js';
+export type { CapabilityToken, TokenParams, } from './capability-token.js';
+export { ThresholdAuthorizer } from './threshold-auth.js';
+export type { ApprovalRequest, VoteResult, } from './threshold-auth.js';
+export { RateLimiter } from './rate-limiter.js';
+export type { RateLimitConfig, } from './rate-limiter.js';
+export { CircuitBreaker, CircuitState } from './circuit-breaker.js';
+export type { CircuitBreakerConfig, } from './circuit-breaker.js';

package/dist/utils/safety/rate-limiter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RateLimiter — Sliding window per-entity rate limiting.
+ *
+ * TypeScript port of saezbaldo/ic-agi `ic_agi/rate_limiter.py`.
+ * See: https://github.com/saezbaldo/ic-agi
+ *
+ * Two-layer design:
+ *   1. Global counter (10x per-entity limit) — system-wide protection
+ *   2. Per-(entity, scope) counter — fine-grained per-caller limits
+ *
+ * Cooldown note: when a per-entity counter is exceeded, a cooldown
+ * period is applied. The global counter does not apply cooldown.
+ */
+import type { AuditLog } from '../../security/audit-log.js';
+export interface RateLimitConfig {
+    /** Maximum requests per window. Default: 20 */
+    maxRequests?: number;
+    /** Sliding window duration in seconds. Default: 60 */
+    windowSeconds?: number;
+    /** Cooldown duration in seconds after limit exceeded. Default: 30 */
+    cooldownSeconds?: number;
+}
+export declare class RateLimiter {
+    private readonly counters;
+    private readonly global;
+    private readonly config;
+    private readonly auditLog?;
+    constructor(config?: RateLimitConfig, auditLog?: AuditLog);
+    /**
+     * Check whether the (entity, scope) pair is allowed to proceed.
+     * Checks the global counter first, then the per-entity counter.
+     */
+    allow(entity: string, scope?: string): boolean;
+    remaining(entity: string, scope?: string): number;
+    inCooldown(entity: string, scope?: string): boolean;
+    reset(entity: string, scope?: string): void;
+    /** Reset all counters including global (test utility). */
+    resetAll(): void;
+}