@happyvertical/smrt-agents 0.38.19 → 0.38.21

package/AGENTS.md

@@ -114,11 +114,27 @@ class InvoiceAgent extends Agent {
 - **Seams to override**: `learningScope()`, `recallForRun(memory)`, `captureForRun(memory, outcome)`, `getLearningSemanticSearch()`. Helpers for `run()`: `stageLearning(episode)`, `reportLearningOutcome(outcome)`, `getLearningMemory()`, and the `recalledMemories` field.
 - **Config**: `static learning: boolean | AgentLearningConfig` — `{ enabled?, scope?, minConfidence?, successConfidence?, failureConfidence?, reinforcement?, decayHalfLifeMs? }`. `LearningMemory` and its types are re-exported from `@happyvertical/smrt-core`.
 
+## Multi-Instance Agents (issue #1890) — opt-in
+
+`static multiInstance = false` by default: a class is a **singleton** (the N=1 case) and is byte-for-byte unchanged — one dispatch subscriber keyed by the agent type, one memory scope, class-wide interests. Set `static multiInstance = true` to run N durable instances (personas, from `@happyvertical/smrt-personas`) of one class per tenant, each independent.
+
+The framework provides only the per-instance **identity**; a package scopes its own dispatch/interests to the instance's config by overriding the seams.
+
+- **`AgentOptions.instanceKey`** — the durable per-instance key (typically the persona id). Honored **only** when `multiInstance` is true, so passing it to a non-opted agent is a no-op.
+- **`getInstanceKey()`** → the key, or `null` for a singleton (opt-in off, or no key).
+- **`getDispatchSubscriber()`** → `` `${agentType}#${key}` `` for a multi-instance agent, the bare `agentType` for a singleton. Used everywhere the agent subscribes/seeds/processes, so each instance has its own subscription rows and pending-dispatch queue — two instances never compete for or double-process each other's dispatches. Composed by the exported `instanceScopedSubscriber(agentType, key)`.
+- **`learningScope()`** — suffixed with `#<key>` for a multi-instance agent, so instances learn independently (singleton scope unchanged).
+- **Seams to override** (both default to singleton behavior):
+  - `resolveSignalSubscriptions()` — derive **instance-scoped** signal types from the instance config so an emit meant for one instance only matches its subscription.
+  - `instanceInterestFilter()` — an `ObjectFilter` AND-merged (as the base layer) into every `interesting()` query so instances partition the objects they process.
+
+The **`default` persona reuses the singleton identity** (a `null` key), which is what makes the singleton→multi upgrade non-destructive — see `@happyvertical/smrt-personas` (`personaInstanceKey`, `upgradeSingletonToDefaultPersona`).
+
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config, opt-in learning trait |
+| `src/agent.ts` | Base Agent class — lifecycle, dispatch, interests, config, opt-in learning trait, multi-instance identity |
 | `src/learning.ts` | `AgentLearningConfig` + `resolveAgentLearning()` declaration normalisation |
 | `src/schedule.ts` | AgentSchedule model — cron, execution tracking |
 | `src/tenant-agent.ts` | TenantAgent — junction table, hierarchical resolution |

package/dist/agent.d.ts

@@ -1,7 +1,7 @@
 import { Logger } from '@happyvertical/logger';
 import { ConfigResolver, DispatchBus, DispatchMetadata, LearningEpisode, LearningMemory, LearningMemoryRecord, LearningOutcome, LearningSemanticSearch, SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
 import { AgentAIOptions } from './ai-config.js';
-import { AgentWithInterestsOptions, InterestOptions, InterestResult } from './interests.js';
+import { AgentWithInterestsOptions, InterestOptions, InterestResult, ObjectFilter } from './interests.js';
 import { AgentLearningDeclaration } from './learning.js';
 import { AgentStatusType } from './types.js';
 import { AgentAdminRoute, AgentUISlots } from './ui.js';
@@ -30,6 +30,18 @@ export interface AgentOptions extends SmrtObjectOptions, AgentWithInterestsOptio
      * shutdown itself; the first handler to finish exits the process.
      */
     manageProcessSignals?: boolean;
+    /**
+     * Durable per-instance key for multi-instance agents (#1890).
+     *
+     * Only honored when the agent class opts into multi-instance
+     * (`static multiInstance = true`); a singleton agent (the default) ignores it,
+     * so passing a key can never change a non-opted agent's behavior. When honored
+     * it becomes the per-instance dispatch subscriber suffix and memory partition
+     * (see {@link Agent.getDispatchSubscriber} / {@link Agent.learningScope}) so N
+     * instances of one class run independently. Typically the persona id from
+     * `@happyvertical/smrt-personas` (a persona is a durable instance).
+     */
+    instanceKey?: string | null;
 }
 /**
  * Base Agent class for building autonomous actors in the SMRT ecosystem
@@ -221,6 +233,26 @@ export declare abstract class Agent extends SmrtObject {
      * ```
      */
     static learning: AgentLearningDeclaration;
+    /**
+     * Opt into multiple durable instances of this agent class per tenant (#1890).
+     *
+     * **Off by default** — a non-opted class is a **singleton** (the N=1 case) and
+     * behaves byte-for-byte as it does today: one dispatch subscriber keyed by the
+     * agent type, one memory scope, class-wide interests. Setting this to `true`
+     * lets N configured instances (personas, from `@happyvertical/smrt-personas`)
+     * run independently: each is constructed with its own {@link AgentOptions.instanceKey},
+     * which the framework folds into a per-instance dispatch subscriber
+     * ({@link getDispatchSubscriber}), memory partition ({@link learningScope}),
+     * and interest/subscription scoping seams ({@link instanceInterestFilter} /
+     * {@link resolveSignalSubscriptions}) so two instances never double-process
+     * each other's dispatches or interests.
+     *
+     * The framework provides the per-instance *identity*; a package scopes its own
+     * dispatch/interests to the instance's config by overriding the seams. The
+     * `default` persona reuses the singleton identity (null key), which makes the
+     * singleton→multi upgrade non-destructive.
+     */
+    static multiInstance: boolean;
     /**
      * Current agent status
      */
@@ -298,6 +330,55 @@ export declare abstract class Agent extends SmrtObject {
      * Human-readable class name for logs and UI.
      */
     protected getAgentClassName(): string;
+    /**
+     * Whether this agent class opted into multiple durable instances per tenant.
+     */
+    protected isMultiInstance(): boolean;
+    /**
+     * The durable per-instance key for this agent, or `null` for a singleton.
+     *
+     * Returns `null` unless the class opts in (`static multiInstance = true`) AND a
+     * non-empty {@link AgentOptions.instanceKey} was supplied — so a non-opted
+     * agent is always singleton-identified even if a key is passed. This is the
+     * anchor the framework folds into the dispatch subscriber, memory scope, and
+     * scoping seams below.
+     */
+    getInstanceKey(): string | null;
+    /**
+     * Canonical dispatch subscriber identity for this agent.
+     *
+     * A singleton (no instance key) is the bare agent type — **unchanged** from the
+     * class-keyed behavior. A multi-instance agent is `` `${agentType}#${key}` ``,
+     * giving each instance its own subscription rows and its own pending-dispatch
+     * queue so instances don't compete for or double-process each other's
+     * dispatches. Used everywhere the agent subscribes, seeds, and processes.
+     */
+    getDispatchSubscriber(): string;
+    /**
+     * The signal types this instance should seed as dispatch subscriptions.
+     *
+     * Defaults to the class's static {@link Agent.signalSubscriptions} unchanged.
+     * A multi-instance package overrides this to derive **instance-scoped** signal
+     * types from the persona/instance config (e.g. append the instance key or a
+     * routing dimension), so an emit meant for one instance only matches that
+     * instance's subscription and the other never processes it.
+     */
+    protected resolveSignalSubscriptions(): string[];
+    /**
+     * An optional filter AND-merged (as the base layer) into every
+     * {@link interesting} query for this instance.
+     *
+     * `undefined` by default (no scoping — singleton behavior unchanged). A
+     * multi-instance package overrides it to return an instance-discriminating
+     * filter derived from the persona/instance config, so two instances of one
+     * class partition the objects they process and never double-handle the same
+     * row. Global and per-object interest filters layer on top (and win on key
+     * collision), so choose a dedicated discriminator key here.
+     *
+     * Applies to the standard filter path; custom `query` interest filters own
+     * their SQL and should incorporate {@link getInstanceKey} themselves.
+     */
+    protected instanceInterestFilter(): ObjectFilter | undefined;
     /**
      * Get UI slot definitions for this agent instance
      *

package/dist/agent.d.ts.map

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

package/dist/chunks/{config-C73buv9Y.js → config-BRQLhsFp.js}

@@ -11,6 +11,9 @@ function getAgentClassName(name) {
 function getAgentTypeAliases(name) {
 	return Array.from(new Set([getAgentTypeName(name), getAgentClassName(name)].filter(Boolean)));
 }
+function instanceScopedSubscriber(agentType, instanceKey) {
+	return instanceKey ? `${agentType}#${instanceKey}` : agentType;
+}
 //#endregion
 //#region src/config.ts
 var __defProp = Object.defineProperty;
@@ -164,6 +167,6 @@ var AgentConfigCollection = class extends SmrtCollection {
 	}
 };
 //#endregion
-export { getAgentTypeName as a, getAgentTypeAliases as i, AgentConfigCollection as n, getAgentClassName as r, AgentConfig as t };
+export { getAgentTypeName as a, getAgentTypeAliases as i, AgentConfigCollection as n, instanceScopedSubscriber as o, getAgentClassName as r, AgentConfig as t };
 
-//# sourceMappingURL=config-C73buv9Y.js.map
+//# sourceMappingURL=config-BRQLhsFp.js.map

package/dist/chunks/config-BRQLhsFp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-BRQLhsFp.js","names":["tenantId"],"sources":["../../src/identity.ts","../../src/config.ts"],"sourcesContent":["import { getClassName, ObjectRegistry } from '@happyvertical/smrt-core';\n\n/**\n * Return the canonical agent type identifier for storage and dispatch routing.\n *\n * Uses the registry's qualified name when available and falls back to the input\n * name for dynamically defined or unregistered classes.\n */\nexport function getAgentTypeName(name: string): string {\n  const registered = ObjectRegistry.getClass(name);\n  return registered?.qualifiedName || registered?.name || name;\n}\n\n/**\n * Return the human-readable class name for UI and logs.\n */\nexport function getAgentClassName(name: string): string {\n  const registered = ObjectRegistry.getClass(name);\n  return registered?.name || getClassName(name);\n}\n\n/**\n * Return all meaningful aliases for an agent type.\n *\n * The qualified name is first so persistence lookups prefer canonical rows,\n * while the simple class name keeps legacy rows discoverable during migration.\n */\nexport function getAgentTypeAliases(name: string): string[] {\n  return Array.from(\n    new Set([getAgentTypeName(name), getAgentClassName(name)].filter(Boolean)),\n  );\n}\n\n/**\n * Compose a per-instance dispatch subscriber identity from an agent type and an\n * optional instance key (#1890).\n *\n * Multiple durable instances of one agent class each need their own subscriber\n * name so their dispatch subscriptions and pending dispatches never collide —\n * that is what keeps two instances from double-processing each other's work.\n *\n * Returns the bare `agentType` when `instanceKey` is nullish/empty, so a\n * **singleton** agent's subscriber is byte-for-byte unchanged (the N=1 default).\n * When a key is present the identity is `` `${agentType}#${instanceKey}` `` — a\n * stable, reversible composition (the type never contains `#`).\n */\nexport function instanceScopedSubscriber(\n  agentType: string,\n  instanceKey?: string | null,\n): string {\n  return instanceKey ? `${agentType}#${instanceKey}` : agentType;\n}\n","/**\n * AgentConfig - Persistent configuration storage for agents\n *\n * This module provides database-backed configuration for agents,\n * enabling consuming apps to persist agent settings.\n *\n * @module\n */\n\nimport {\n  field,\n  type SmrtClassOptions,\n  SmrtCollection,\n  SmrtObject,\n  smrt,\n} from '@happyvertical/smrt-core';\nimport {\n  queryGlobal,\n  queryWithGlobals,\n  TenantScoped,\n  tenantId,\n} from '@happyvertical/smrt-tenancy';\nimport { getAgentTypeName } from './identity.js';\n\n/**\n * AgentConfig stores agent configuration in the database\n *\n * Each config record maps to a UI slot for an agent instance:\n * - agentId: The agent instance's ID\n * - agentClass: The canonical agent type (qualified name when available)\n * - slotId: The configuration slot (e.g., 'sources', 'settings')\n * - configData: JSON object containing the configuration\n *\n * @example\n * ```typescript\n * // Save config for an agent slot\n * const config = new AgentConfig({\n *   agentId: agent.id,\n *   agentClass: 'Praeco',\n *   slotId: 'sources',\n *   configData: { scrapers: ['civicweb', 'govstack'] },\n *   db: options.db\n * });\n * await config.initialize();\n * await config.save();\n * ```\n */\n@TenantScoped({ mode: 'optional' })\n@smrt({\n  tableName: 'agent_configs',\n  api: { include: ['list', 'get', 'create', 'update', 'delete'] },\n  mcp: { include: ['list', 'get'] },\n  cli: true,\n})\nexport class AgentConfig extends SmrtObject {\n  /**\n   * Tenant ID for multi-tenant isolation\n   * Nullable to support both tenant-scoped and global agent configs\n   */\n  @tenantId({ nullable: true })\n  tenantId: string | null = null;\n\n  /**\n   * ID of the agent instance this config belongs to\n   */\n  @field({ type: 'text' })\n  agentId: string = '';\n\n  /**\n   * Canonical agent type for this config (qualified name when available)\n   */\n  @field({ type: 'text' })\n  agentClass: string = '';\n\n  /**\n   * UI slot ID (e.g., 'sources', 'settings', 'reports')\n   */\n  @field({ type: 'text' })\n  slotId: string = '';\n\n  /**\n   * Configuration data stored as JSON\n   *\n   * Sensitive (#1540): agent config blobs routinely carry API keys/credentials,\n   * so this is excluded from generated API/MCP responses and rejected as a\n   * `where` filter key.\n   */\n  @field({ type: 'json', sensitive: true })\n  configData: Record<string, unknown> = {};\n\n  /**\n   * Schema version for future migrations\n   */\n  @field({ type: 'integer' })\n  schemaVersion: number = 1;\n\n  /**\n   * Load all configs for a specific agent\n   *\n   * @param agentId - Agent instance ID\n   * @param options - Database options\n   * @returns Map of slotId → configData\n   */\n  static async forAgent(\n    agentId: string,\n    options: SmrtClassOptions,\n  ): Promise<Map<string, Record<string, unknown>>> {\n    const configsByAgent = await AgentConfig.forAgents([agentId], options);\n    return configsByAgent.get(agentId) ?? new Map();\n  }\n\n  /**\n   * Load configs for multiple agents in a single query.\n   *\n   * @param agentIds - Agent instance IDs\n   * @param options - Database options\n   * @returns Map of agentId -> (slotId -> configData)\n   */\n  static async forAgents(\n    agentIds: string[],\n    options: SmrtClassOptions,\n  ): Promise<Map<string, Map<string, Record<string, unknown>>>> {\n    const configsByAgent = new Map<\n      string,\n      Map<string, Record<string, unknown>>\n    >();\n    if (agentIds.length === 0) {\n      return configsByAgent;\n    }\n\n    const collection = await AgentConfigCollection.create(options);\n    const configs = await collection.list({\n      where: { 'agentId in': agentIds },\n    });\n\n    for (const config of configs) {\n      if (!configsByAgent.has(config.agentId)) {\n        configsByAgent.set(config.agentId, new Map());\n      }\n      configsByAgent.get(config.agentId)?.set(config.slotId, config.configData);\n    }\n\n    return configsByAgent;\n  }\n\n  /**\n   * Load config for a specific agent and slot\n   *\n   * @param agentId - Agent instance ID\n   * @param slotId - UI slot ID\n   * @param options - Database options\n   * @returns Config data or undefined if not found\n   */\n  static async forSlot(\n    agentId: string,\n    slotId: string,\n    options: SmrtClassOptions,\n  ): Promise<Record<string, unknown> | undefined> {\n    const collection = await AgentConfigCollection.create(options);\n    const configs = await collection.list({\n      where: { agentId, slotId },\n      limit: 1,\n    });\n    return configs[0]?.configData;\n  }\n\n  /**\n   * Save or update config for an agent slot\n   *\n   * @param data - Config data including agentId, agentClass, slotId, configData\n   * @param options - Database options\n   * @returns Saved AgentConfig instance\n   */\n  static async saveSlot(\n    data: {\n      agentId: string;\n      agentClass: string;\n      slotId: string;\n      configData: Record<string, unknown>;\n    },\n    options: SmrtClassOptions,\n  ): Promise<AgentConfig> {\n    const normalizedAgentClass = getAgentTypeName(data.agentClass);\n    const collection = await AgentConfigCollection.create(options);\n\n    // Check for existing config using list with where clause\n    const existingConfigs = await collection.list({\n      where: { agentId: data.agentId, slotId: data.slotId },\n      limit: 1,\n    });\n\n    if (existingConfigs.length > 0) {\n      // Update existing\n      const existing = existingConfigs[0];\n      existing.configData = data.configData;\n      existing.agentClass = normalizedAgentClass;\n      await existing.save();\n      return existing;\n    }\n\n    // Create new\n    const config = await collection.create({\n      agentId: data.agentId,\n      agentClass: normalizedAgentClass,\n      slotId: data.slotId,\n      configData: data.configData,\n      slug: `${data.agentId}-${data.slotId}`,\n    });\n    await config.save();\n    return config;\n  }\n}\n\n/**\n * Collection for AgentConfig objects\n */\nexport class AgentConfigCollection extends SmrtCollection<AgentConfig> {\n  static readonly _itemClass = AgentConfig;\n\n  /**\n   * Find all configs for a specific tenant\n   * @param tenantId - Tenant ID to filter by\n   * @returns Array of AgentConfig objects for the tenant\n   */\n  async findByTenant(tenantId: string): Promise<AgentConfig[]> {\n    return this.list({ where: { tenantId } });\n  }\n\n  /**\n   * Find all global configs (not associated with any tenant).\n   *\n   * Routes through the shared tenant-global helper so it does not throw under\n   * an active tenant context (an explicit `tenant_id IS NULL` filter would be\n   * flagged as an isolation violation). (#1600)\n   *\n   * @returns Array of global AgentConfig objects\n   */\n  async findGlobal(): Promise<AgentConfig[]> {\n    return queryGlobal<AgentConfig>(this);\n  }\n\n  /**\n   * Find configs for a tenant including global configs.\n   *\n   * Fails closed if an active tenant context requests a different tenant's\n   * rows; the admin/system path keeps the cross-tenant capability. (#1600)\n   *\n   * @param tenantId - Tenant ID to include\n   * @returns Array of AgentConfig objects for the tenant and global configs\n   */\n  async findWithGlobals(tenantId: string): Promise<AgentConfig[]> {\n    return queryWithGlobals<AgentConfig>(\n      this,\n      tenantId,\n      'AgentConfig.findWithGlobals',\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/execute-as-principal.d.ts

@@ -0,0 +1,158 @@
+import { Logger } from '@happyvertical/logger';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { OperationPermissionCollectionInput, OperationPermissionDecision, PermissionResolver, SessionPermissionRuntimeContext } from '@happyvertical/smrt-users';
+/**
+ * The bound principal an agent runs as. A resolved persona structurally
+ * satisfies this once its optional `runAsUserId` has been narrowed to a
+ * concrete id — `allowedTools` on a `ResolvedPersona` is already the persona's
+ * tools intersected with the `TenantAgent` capability ceiling.
+ */
+export interface PrincipalBinding {
+    /** The user whose live permissions bound this execution. Required. */
+    runAsUserId: string;
+    /** Tenant the principal acts within. */
+    tenantId: string | null;
+    /**
+     * The persona's tool allow-list (already capped by the agent-class ceiling).
+     * This is a **fail-closed** whitelist, mirroring
+     * `@happyvertical/smrt-chat`'s `AgentSession.isToolAllowed()` (S5 #1392): an
+     * absent (`undefined`) or empty allow-list permits **NO** tools, never all of
+     * them, so forgetting to pass it can only tighten authority. Resolved personas
+     * always provide a concrete `string[]`.
+     */
+    allowedTools?: string[];
+    /** Optional acting `Bot` profile id, recorded in the audit entry. */
+    actsAsProfileId?: string | null;
+}
+/**
+ * A single audit record describing an agent action performed by the bound
+ * principal (`actorUserId`) on behalf of the originating user
+ * (`onBehalfOfUserId`).
+ */
+export interface PrincipalAuditEntry {
+    /** Action label, e.g. `'agent.run'`. */
+    action: string;
+    /** The persona's bound user the work ran as. */
+    actorUserId: string;
+    /** The user who triggered the agent, if known. */
+    onBehalfOfUserId: string | null;
+    /** Tenant the action ran within. */
+    tenantId: string | null;
+    /** Canonical agent class, when the caller supplies it. */
+    agentClass?: string;
+    /** Acting profile id, when the persona sets one. */
+    actsAsProfileId?: string | null;
+    /** Free-form additional context. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Sink that records a {@link PrincipalAuditEntry}. Provide one to persist audit
+ * rows (e.g. via `AuditLog.record`); when omitted, the entry is emitted as a
+ * structured log line.
+ */
+export type PrincipalAuditSink = (entry: PrincipalAuditEntry) => void | Promise<void>;
+/**
+ * Options for {@link executeAsPrincipal}.
+ */
+export interface ExecuteAsPrincipalOptions extends SmrtClassOptions {
+    /** The bound principal to run as. */
+    principal: PrincipalBinding;
+    /** The originating user the action is performed on behalf of (for audit). */
+    onBehalfOfUserId?: string | null;
+    /** Canonical agent class, recorded in the audit entry. */
+    agentClass?: string;
+    /** Audit action label. Defaults to `'agent.run'`. */
+    action?: string;
+    /** Extra audit metadata merged into the emitted entry. */
+    auditMetadata?: Record<string, unknown>;
+    /**
+     * Pre-resolved permission slugs. When omitted, the principal's permissions
+     * are resolved live so role changes reflect on the next execution.
+     */
+    permissions?: string[];
+    /** Reuse an initialized resolver across executions. */
+    resolver?: PermissionResolver;
+    /** Opt into Postgres RLS transaction wrapping (defaults to package config). */
+    postgresRls?: boolean;
+    /**
+     * Enter tenant context so tenant auto-filtering applies on every adapter.
+     * Defaults to `true` whenever the principal has a tenant.
+     */
+    enterTenantContext?: boolean;
+    /** Audit sink. Defaults to a structured log line. */
+    audit?: PrincipalAuditSink;
+    /** Logger used for the default audit sink. */
+    logger?: Logger;
+}
+/**
+ * Thrown when the persona attempts a tool outside its `allowedTools`.
+ */
+export declare class PrincipalToolNotAllowedError extends Error {
+    readonly tool: string;
+    readonly status = 403;
+    constructor(tool: string);
+}
+/**
+ * The handle passed to the {@link executeAsPrincipal} body. Its
+ * session-permission {@link context} is already published for the principal, so
+ * data operations are bounded by RLS on Postgres. The assertions enforce the
+ * remaining two authority dimensions.
+ */
+export interface PrincipalRun {
+    /** The published session-permission runtime context for the principal. */
+    context: SessionPermissionRuntimeContext;
+    /** The principal's published (snapshot) permission slugs. */
+    permissions: string[];
+    /**
+     * The effective, fail-closed tool allow-list — always a concrete array (an
+     * absent binding allow-list normalizes to `[]`, i.e. no tools).
+     */
+    allowedTools: string[];
+    /**
+     * Whether `tool` is within the fail-closed allow-list. An empty allow-list,
+     * or an empty/non-string tool name, permits nothing.
+     */
+    isToolAllowed(tool: string): boolean;
+    /** Throw {@link PrincipalToolNotAllowedError} unless `tool` is allowed. */
+    assertToolAllowed(tool: string): void;
+    /**
+     * Assert the principal holds the catalog permission for `(collection,
+     * action)`, authorizing against the **published** principal set
+     * (`context.permissionSet`) — the same snapshot the RLS session enforces — so
+     * the bound is adapter-independent. This is the door-agnostic teeth for the
+     * RLS-off adapters; under Postgres RLS it is a redundant (but harmless)
+     * second gate. Throws `OperationPermissionError` on denial.
+     */
+    assertOperation(collection: OperationPermissionCollectionInput, action: string, extraOptions?: SmrtClassOptions): Promise<OperationPermissionDecision>;
+}
+/**
+ * Run `fn` AS the persona's bound principal.
+ *
+ * Resolves the bound user's live permissions, publishes them onto the DB
+ * session (so Postgres RLS bounds every query per-`(table, action)`), emits an
+ * on-behalf-of audit entry, and hands `fn` a {@link PrincipalRun} whose
+ * assertions enforce the persona tool ceiling and the RLS-off catalog gate.
+ *
+ * @example
+ * ```typescript
+ * await executeAsPrincipal(
+ *   {
+ *     db,
+ *     principal: {
+ *       runAsUserId: persona.runAsUserId,
+ *       tenantId: persona.tenantId,
+ *       allowedTools: persona.allowedTools,
+ *     },
+ *     onBehalfOfUserId: triggeringUserId,
+ *     agentClass: persona.agentClass,
+ *   },
+ *   async (run) => {
+ *     run.assertToolAllowed('articles.publish');
+ *     await run.assertOperation('articles', 'update');
+ *     await agent.run();
+ *   },
+ * );
+ * ```
+ */
+export declare function executeAsPrincipal<T>(options: ExecuteAsPrincipalOptions, fn: (run: PrincipalRun) => Promise<T>): Promise<T>;
+//# sourceMappingURL=execute-as-principal.d.ts.map

package/dist/execute-as-principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-as-principal.d.ts","sourceRoot":"","sources":["../src/execute-as-principal.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -16,4 +16,18 @@ export declare function getAgentClassName(name: string): string;
  * while the simple class name keeps legacy rows discoverable during migration.
  */
 export declare function getAgentTypeAliases(name: string): string[];
+/**
+ * Compose a per-instance dispatch subscriber identity from an agent type and an
+ * optional instance key (#1890).
+ *
+ * Multiple durable instances of one agent class each need their own subscriber
+ * name so their dispatch subscriptions and pending dispatches never collide —
+ * that is what keeps two instances from double-processing each other's work.
+ *
+ * Returns the bare `agentType` when `instanceKey` is nullish/empty, so a
+ * **singleton** agent's subscriber is byte-for-byte unchanged (the N=1 default).
+ * When a key is present the identity is `` `${agentType}#${instanceKey}` `` — a
+ * stable, reversible composition (the type never contains `#`).
+ */
+export declare function instanceScopedSubscriber(agentType: string, instanceKey?: string | null): string;
 //# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,MAAM,CAER"}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { getClassConfigResolvers, getConfigResolver, isLazyConfigSentinel, listC
 export { Agent, type AgentOptions } from './agent.js';
 export { type AgentAIOptions, type AgentAISecretFallback, resolveAgentAIOptions, } from './ai-config.js';
 export { AgentConfig, AgentConfigCollection } from './config.js';
+export { type ExecuteAsPrincipalOptions, executeAsPrincipal, type PrincipalAuditEntry, type PrincipalAuditSink, type PrincipalBinding, type PrincipalRun, PrincipalToolNotAllowedError, } from './execute-as-principal.js';
+export { instanceScopedSubscriber } from './identity.js';
 export type { AgentWithInterestsOptions, AsyncQualifierFn, InterestFilter, InterestHandlerFn, InterestOptions, InterestResult, ObjectFilter, ObjectInterestConfig, QueryFn, } from './interests.js';
 export { mergeFilters, normalizeSort } from './interests.js';
 export { type AgentLearningConfig, type AgentLearningDeclaration, type ResolvedAgentLearning, resolveAgentLearning, } from './learning.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAKH,OAAO,wBAAwB,CAAC;AAIhC,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,OAAO,GACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG7D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,yBAAyB,EAC9B,WAAW,EACX,qBAAqB,EACrB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAKH,OAAO,wBAAwB,CAAC;AAIhC,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,KAAK,yBAAyB,EAC9B,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,OAAO,GACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG7D,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,yBAAyB,EAC9B,WAAW,EACX,qBAAqB,EACrB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,gBAAgB,GACjB,MAAM,SAAS,CAAC"}