Class EmergentToolRegistry

Manages the lifecycle of emergent tools across three trust tiers.

The registry stores session-tier tools in an in-memory Map (keyed by tool ID) and mirrors them to SQLite when available for audit/inspection. Agent/shared tier tools live in the persisted map and are written to SQLite (when a storage adapter is provided) or kept in-memory as fallback.

Key responsibilities:

  • Registration: Accept new tools at a given tier, enforcing config limits.
  • Lookup: Retrieve tools by ID or filter by tier with optional scope.
  • Usage tracking: Record invocations and update rolling statistics.
  • Promotion / demotion: Move tools between tiers with audit logging.
  • Session cleanup: Bulk-remove all session-scoped tools for a given session.
  • Audit trail: Log every state change for observability and debugging.

Example

const registry = new EmergentToolRegistry({ ...DEFAULT_EMERGENT_CONFIG, enabled: true });
registry.register(tool, 'session');
registry.recordUse(tool.id, { x: 1 }, { y: 2 }, true, 42);
const stats = registry.getUsageStats(tool.id);

Constructors

constructor

Methods

ensureSchemaReady ensureSchema register get upsert remove getByTier recordUse getUsageStats promote demote cleanupSession getAuditLog

Constructors

constructor

Methods

ensureSchemaReady

  • ensureSchemaReady(): Promise<void>

  • Idempotent schema readiness guard.

    Ensures ensureSchema() is called exactly once and all subsequent callers await the same in-flight promise. This prevents the race condition where concurrent DB operations start before DDL statements finish.

    Returns Promise<void>

    A promise that resolves when the schema is ready.

ensureSchema

  • ensureSchema(): Promise<void>

  • Initialize the database schema for emergent tool persistence.

    Creates the agentos_emergent_tools and agentos_emergent_audit_log tables along with their indexes. Safe to call multiple times — all statements use CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS.

    This method is a no-op when no storage adapter was provided.

    Returns Promise<void>

    Throws

    If the storage adapter's exec or run method rejects.

register

  • register(tool, tier): void

  • Register a new emergent tool at the given tier.

    Session-tier tools are stored in the in-memory session map and mirrored to SQLite when available. Agent and shared tier tools are stored in the persisted map (and written to SQLite when a storage adapter is available).

    Parameters

    • tool: EmergentTool

      The emergent tool to register. Must have a unique id.

    • tier: ToolTier

      The tier to register the tool at. The tool's tier property is updated to match.

    Returns void

    Throws

    If the maximum tool count for the target tier is exceeded (checked against maxSessionTools or maxAgentTools from config).

    Throws

    If a tool with the same ID is already registered.

get

  • get(toolId): undefined | EmergentTool

  • Retrieve a tool by its unique identifier.

    Searches all tiers (session first, then persisted agent/shared).

    Parameters

    • toolId: string

      The tool ID to look up.

    Returns undefined | EmergentTool

    The tool if found, or undefined if no tool with that ID exists.

upsert

  • upsert(tool): void

  • Upsert a tool into the registry, replacing any prior in-memory copy.

    Used to hydrate persisted/shared tools back into a live runtime so they can become executable again after process restart or admin promotion.

    Parameters

    Returns void

remove

  • remove(toolId): boolean

  • Remove a tool from the registry entirely.

    Used to roll back newly forged tools when downstream activation fails.

    Parameters

    • toolId: string

    Returns boolean

getByTier

  • getByTier(tier, scope?): EmergentTool[]

  • Get all tools registered at a specific tier, optionally filtered by scope.

    Parameters

    • tier: ToolTier

      The tier to query ('session', 'agent', or 'shared').

    • Optional scope: {
          sessionId?: string;
          agentId?: string;
      }

      Optional scope filter. When provided, results are narrowed:

      • sessionId: Match tools whose source string contains the session ID.
      • agentId: Match tools whose createdBy equals the agent ID.
      • Optional sessionId?: string
      • Optional agentId?: string

    Returns EmergentTool[]

    An array of matching tools (may be empty).

recordUse

  • recordUse(toolId, _input, _output, success, executionTimeMs): void

  • Record a tool invocation, updating rolling usage statistics.

    Updates the tool's ToolUsageStats in place:

    • Increments totalUses.
    • Increments successCount or failureCount based on the success flag.
    • Recalculates avgExecutionTimeMs as a running average.
    • Recalculates confidenceScore as successCount / totalUses.
    • Sets lastUsedAt to the current ISO-8601 timestamp.

    Parameters

    • toolId: string

      The ID of the tool that was invoked.

    • _input: unknown

      The input arguments passed to the tool (logged for audit).

    • _output: unknown

      The output returned by the tool (logged for audit).

    • success: boolean

      Whether the invocation completed successfully.

    • executionTimeMs: number

      Wall-clock execution time in milliseconds.

    Returns void

    Throws

    If no tool with the given ID is registered.

getUsageStats

promote

  • promote(toolId, targetTier, approvedBy?): Promise<void>

  • Promote a tool to a higher lifecycle tier.

    Moves the tool from its current tier to targetTier. If the tool was at session tier, it is removed from the session map and added to the persisted map. If a storage adapter is available and the target tier is agent or shared, the tool is persisted to the database.

    Parameters

    • toolId: string

      The ID of the tool to promote.

    • targetTier: ToolTier

      The target tier to promote to. Must be strictly higher than the tool's current tier.

    • Optional approvedBy: string

      Optional identifier of the human or system entity that approved the promotion.

    Returns Promise<void>

    Throws

    If the tool is not found.

    Throws

    If targetTier is not higher than the tool's current tier.

demote

  • demote(toolId, reason): void

  • Demote or deactivate a tool.

    Marks the tool as inactive by setting a sentinel on its usage stats (confidenceScore set to 0) and logs the demotion event with a reason.

    Inactive tools are still retrievable via get() but should be filtered out by callers when building tool lists for the LLM.

    Parameters

    • toolId: string

      The ID of the tool to demote.

    • reason: string

      Human-readable explanation for why the tool is being demoted.

    Returns void

    Throws

    If the tool is not found.

cleanupSession

  • cleanupSession(sessionId): number

  • Remove all session-tier tools associated with a specific session.

    Iterates the session map and deletes every tool whose source string contains the given session ID. Logs a cleanup audit event for each removed tool.

    Parameters

    • sessionId: string

      The session identifier to match against tool source strings.

    Returns number

    The number of tools removed.

getAuditLog

Settings

Member Visibility

Theme

On This Page

constructorensureSchemaReadyensureSchemaregistergetupsertremovegetByTierrecordUsegetUsageStatspromotedemotecleanupSessiongetAuditLog