@dudousxd/nestjs-agent-core

pnpm add @dudousxd/nestjs-agent-core

-core has no NestJS dependency. It owns runAgentLoop — the model → tools → model cycle — the ToolRegistry, and the SPIs every other package implements or is bound to: a model provider, a store, a governance read-model, an actor resolver, a roles policy, an approval policy, a token sink, a quota provider, and the optional action-proposal stores behind independent approvals.

Implementing an SPI directlyCopy Anchor Link

Most consumers only ever type against -core's interfaces — for example a custom RolesPolicy that replaces the default role-intersection check:

import type { Actor, RolesPolicy, ToolSpec } from '@dudousxd/nestjs-agent-core';

export class BusinessHoursPolicy implements RolesPolicy {
  can(actor: Actor, tool: ToolSpec): boolean {
    const withinHours = new Date().getUTCHours() < 18;
    const hasRole = (tool.roles ?? []).some((role) => actor.roles?.includes(role));
    return tool.kind === 'action' ? hasRole && withinHours : hasRole;
  }
}

runAgentLoop is the one place tool execution happens — a ModelProvider.runTurn performs exactly one model turn and must not execute tools itself, which is what keeps a turn replay-safe under the durable runner. See Concepts → The agent loop for the full turn-by-turn walkthrough.

The SPIsCopy Anchor Link

Every contract a provider, store, or dashboard is built against. Shapes are trimmed to their key members — see the source for full JSDoc.

Core types worth knowingCopy Anchor Link

Also exportedCopy Anchor Link

ToolRegistry, DefaultRolesPolicy / ClosedRolesPolicy / closeEmptyRoles, AgentRegistry, InMemoryAgentStore, createFunctionalTool (a { spec, handler } tool without NestJS), the error classes (ToolForbiddenError, ToolNotFoundError, ToolDisabledError, ToolInputInvalidError, ToolPreflightDeniedError, ToolInputDriftError, QuotaExceededError, RunCancelledError, OutputRejectedError, ProcessorFailedError, StructuredOutputError, ConfirmTokenError, plus agentFailureCode(error) which maps them to a stream error code), the processor plumbing (createFrameBuffer, releaseGatedFrames, decodeStreamEvent) and the structured-output helpers (validateStructured, extractJson, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, repairInstruction), the seedModelPrices(store, prices[]) helper (loops upsertModelPrice over an array — the quick way to seed a pricing table at boot), and the aviary:agent:* diagnostics helpers — re-exported by the umbrella package too, so an app importing @dudousxd/nestjs-agent never needs a direct dependency on -core.

Gating writes: blocking approval, independent proposals, confirmed writesCopy Anchor Link

Three mechanisms, all in -core, for a tool that changes something:

• Blocking approval (default). An action call the ApprovalPolicy marks required parks the turn on awaitApproval until approve/reject (or ttlMs expiry). The tool's preflight runs with phase: 'prepare' before the card — a ready result can supply per-call confirmation wording, persisted and streamed with the card — and again with phase: 'execute' right before the side effect. A remembered approval or policy never skips the execute-phase check.
• Independent proposals (actionApprovalMode: 'independent' on the umbrella). The call is recorded as an action proposal instead of parking: the model gets { proposalId, status: 'pending', executed: false }, the turn ends without another model call, and the thread accepts new messages. A decision (HTTP route, approval port, or a whole-message text command such as yes / reject #ID, or a configured vocabulary such as ptBrActionProposalText) queues the work; ActionProposalWorker executes it under a fenced lease after re-resolving the requester through BackgroundActorResolver, rechecking permissions and re-parsing the original input against the current schema (drift fails with ToolInputDriftError). The outcome is admitted into the thread as an assistant message — no model continuation. Execution is at least once; use ctx.idempotencyKey. See Action proposals.
• Confirmed writes. defineConfirmedTool(options, { prepare, preview, commit }) returns a functional tool (registered as kind: 'read') whose gate lives inside it, so it works where an action has no approval channel (MCP). A call without confirm validates, previews, and returns a confirmToken — an HMAC over tool, actor, tenant, expiry and canonical arguments (secret required, ttlMs default 15 min). The same arguments plus confirm: true and the token commit; the ConfirmTokenStore (store option or AGENT_CONFIRM_TOKEN_STORE) makes the token single use. withConfirmFields(schema) adds confirm / confirmToken to a schema as a SchemaExtension, which -ai-sdk and -mcp-server convert through the inner schema.

Presenting tool outputCopy Anchor Link

ToolHandler.present(output, ctx) returns ComponentPresentations (built with createComponent, table or chart from -core/genui) that are validated and pushed through ctx.emitUi after a successful call; denied or failed calls present nothing, and a presentation error never fails the action. A ComponentRegistry (createComponentRegistry().register(definition, { web, text, … })) renders the same presentation per channel, falling back to its text renderer or the definition's fallbackText. When a client declares uiCapabilities, the server intersects them with the authorized catalog (negotiateCatalog) and turns unsupported emissions into their text representation. See Rendering everywhere.

Recognizing the runner's own errorsCopy Anchor Link

Two predicates let -core tell a durable runtime's signals apart from real failures without depending on either durable package — the inline runner has to work with neither installed:

• isControlFlowSignal(error) — a suspend or continue-as-new, thrown to unwind the turn. Matched by the Symbol.for('aviary:durable:control-flow') property the runtimes stamp on it, not by instanceof: the class differs between the in-process engine and the BullMQ thin worker, and a global-registry symbol is the same symbol in every copy of every module. The loop and invokeWithTransientRetry both check it, so a suspend propagates untouched even when the host supplied no isControlFlowError hook — otherwise the tool catch would write it to the journal as a tool failure.
• isReplayIntegrityError(error) — the checkpoint machinery refusing a position. Matched by class NAME (NonDeterminismError / NondeterminismError, the same contract under two spellings in two packages).

Both must be rethrown untouched from any catch in a workflow body: every recovery path writes more checkpoints, and on a journal that has already diverged each of those asks for a position the history cannot supply — so the recovery raises its own refusal, and that is the error the operator ends up reading.

See Getting Started to wire the loop into a NestJS app, or Concepts → Architecture for how the SPIs above compose into a running turn.