@dudousxd/nestjs-agent-core 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent-core",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",

package/dist/tool-DZYLEKnl.d.cts

@@ -1,121 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, o as PageContext } from './stream-events-CbVEowYb.cjs';
-
-/**
- * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
- * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
- * no denormalized copies).
- */
-interface AiToolCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    /**
-     * The id of the tool call this invocation serves. Absent where a tool is invoked outside a turn
-     * (the MCP server, a direct `registry.invoke`).
-     */
-    toolCallId?: string;
-    /**
-     * `<runId>:<toolCallId>` — the same value for every execution of THIS call, and for no other.
-     *
-     * A tool's side effect and the checkpoint that records it are two writes. Under the durable
-     * runner a worker that dies between them leaves a call the journal does not know ran, and the
-     * runtime's recovery runs it again; an in-step transient retry (a deadlock, a lock-wait timeout)
-     * re-invokes it too. The library cannot make your write atomic with its journal — so it hands you
-     * the key that makes the second attempt recognisable: pass it to whatever you call as its
-     * idempotency key (a payment provider's `Idempotency-Key`, a unique column on the row you insert,
-     * a workflow's `id`), and a re-execution lands on the first one's result instead of doing it
-     * twice. Stable across replays and across pods: the run id is the run's own, and the call id
-     * comes out of the journaled model step.
-     *
-     * Absent where a tool is invoked outside a turn (the MCP server, a direct `registry.invoke`).
-     */
-    idempotencyKey?: string;
-    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
-    agentName?: string;
-    /** The persona of {@link agentName} the turn runs under, when it runs under one. */
-    persona?: string;
-    pageContext?: PageContext;
-    /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
-    host?: unknown;
-    /**
-     * Push a component into the assistant message: streamed live as a `ui` frame and persisted on
-     * the message, so a reload shows it where the live stream did. Resolves to the component's id.
-     *
-     * `id` defaults to `<toolCallId>:ui:<n>` (the n-th push without an `id` in this invocation), so a retried or
-     * re-executed call REPLACES what it pushed before instead of adding a second copy; pass your own
-     * `id` to update one component across pushes (streaming rows into a table). `props` must be
-     * JSON; it is snapshotted when pushed.
-     *
-     * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
-     * result, so a replay neither streams nor persists them again.
-     *
-     * Always present. On a surface with no conversation to push into (the MCP server, a direct
-     * `registry.invoke` without one) it is a no-op that still resolves to an id, so a tool calls
-     * `ctx.emitUi(…)` unconditionally.
-     */
-    emitUi(component: string, props: Record<string, unknown>, options?: {
-        id?: string;
-        version?: number;
-    }): Promise<{
-        id: string;
-    }>;
-}
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
-    /**
-     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
-     * policy, so a `false` here means the model is never shown the tool rather than being shown one
-     * it will be refused. Omit → always enabled.
-     *
-     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
-     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
-     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
-     * separate question "may THIS actor use it?", and both still run.
-     *
-     * Prefer this over conditionally registering the provider: registration happens while the
-     * `@Module` metadata is built, which in most apps is before configuration is loaded.
-     */
-    isEnabled?(): boolean | Promise<boolean>;
-    /**
-     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
-     *
-     * The three existing gates all answer the question somewhere else: `roles` is static data,
-     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
-     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
-     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
-     * this actor own the base being queried, is the per-user override in the DB set today.
-     *
-     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
-     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
-     */
-    canUse?(actor: Actor): boolean | Promise<boolean>;
-    /**
-     * What the model is told about this tool for THIS turn — a description and/or input schema that
-     * depend on who is asking (a per-tenant component catalog, a per-plan list of options). Called
-     * when the turn's tool list is built, after every gate has passed; whatever it returns replaces
-     * the registered spec's `description` / `inputSchema` in the definition the model sees. Omit, or
-     * return `undefined`, to use the registered spec as is.
-     *
-     * It shapes what the model is SHOWN only: the registry still validates a call against the
-     * registered `inputSchema`, so a tool whose accepted input varies per turn registers a permissive
-     * schema and validates in `execute`.
-     */
-    describe?(scope: ToolDescribeScope): ToolDescription | undefined | Promise<ToolDescription | undefined>;
-}
-/** Who a turn's tool list is being built for — what {@link ToolHandler.describe} can vary on. */
-interface ToolDescribeScope {
-    actor: Actor;
-    /** Absent where the list is built outside a conversation (the MCP server's `tools/list`). */
-    threadId?: string;
-    agentName?: string;
-}
-/** A per-turn override of a tool's model-facing definition ({@link ToolHandler.describe}). */
-interface ToolDescription {
-    description?: string;
-    inputSchema?: StandardSchemaV1;
-}
-
-export type { AiToolCtx as A, ToolHandler as T, ToolDescribeScope as a, ToolDescription as b };

package/dist/tool-_iq4xRyk.d.ts

@@ -1,121 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, o as PageContext } from './stream-events-CbVEowYb.js';
-
-/**
- * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
- * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
- * no denormalized copies).
- */
-interface AiToolCtx {
-    actor: Actor;
-    threadId: string;
-    runId: string;
-    requestId: string;
-    /**
-     * The id of the tool call this invocation serves. Absent where a tool is invoked outside a turn
-     * (the MCP server, a direct `registry.invoke`).
-     */
-    toolCallId?: string;
-    /**
-     * `<runId>:<toolCallId>` — the same value for every execution of THIS call, and for no other.
-     *
-     * A tool's side effect and the checkpoint that records it are two writes. Under the durable
-     * runner a worker that dies between them leaves a call the journal does not know ran, and the
-     * runtime's recovery runs it again; an in-step transient retry (a deadlock, a lock-wait timeout)
-     * re-invokes it too. The library cannot make your write atomic with its journal — so it hands you
-     * the key that makes the second attempt recognisable: pass it to whatever you call as its
-     * idempotency key (a payment provider's `Idempotency-Key`, a unique column on the row you insert,
-     * a workflow's `id`), and a re-execution lands on the first one's result instead of doing it
-     * twice. Stable across replays and across pods: the run id is the run's own, and the call id
-     * comes out of the journaled model step.
-     *
-     * Absent where a tool is invoked outside a turn (the MCP server, a direct `registry.invoke`).
-     */
-    idempotencyKey?: string;
-    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
-    agentName?: string;
-    /** The persona of {@link agentName} the turn runs under, when it runs under one. */
-    persona?: string;
-    pageContext?: PageContext;
-    /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
-    host?: unknown;
-    /**
-     * Push a component into the assistant message: streamed live as a `ui` frame and persisted on
-     * the message, so a reload shows it where the live stream did. Resolves to the component's id.
-     *
-     * `id` defaults to `<toolCallId>:ui:<n>` (the n-th push without an `id` in this invocation), so a retried or
-     * re-executed call REPLACES what it pushed before instead of adding a second copy; pass your own
-     * `id` to update one component across pushes (streaming rows into a table). `props` must be
-     * JSON; it is snapshotted when pushed.
-     *
-     * Replay-safe under the durable runner: the pushed components ride the tool step's journaled
-     * result, so a replay neither streams nor persists them again.
-     *
-     * Always present. On a surface with no conversation to push into (the MCP server, a direct
-     * `registry.invoke` without one) it is a no-op that still resolves to an id, so a tool calls
-     * `ctx.emitUi(…)` unconditionally.
-     */
-    emitUi(component: string, props: Record<string, unknown>, options?: {
-        id?: string;
-        version?: number;
-    }): Promise<{
-        id: string;
-    }>;
-}
-/** A tool implementation. `I` is the parsed (Zod-validated) input. */
-interface ToolHandler<I = unknown> {
-    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
-    /**
-     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
-     * policy, so a `false` here means the model is never shown the tool rather than being shown one
-     * it will be refused. Omit → always enabled.
-     *
-     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
-     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
-     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
-     * separate question "may THIS actor use it?", and both still run.
-     *
-     * Prefer this over conditionally registering the provider: registration happens while the
-     * `@Module` metadata is built, which in most apps is before configuration is loaded.
-     */
-    isEnabled?(): boolean | Promise<boolean>;
-    /**
-     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
-     *
-     * The three existing gates all answer the question somewhere else: `roles` is static data,
-     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
-     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
-     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
-     * this actor own the base being queried, is the per-user override in the DB set today.
-     *
-     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
-     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
-     */
-    canUse?(actor: Actor): boolean | Promise<boolean>;
-    /**
-     * What the model is told about this tool for THIS turn — a description and/or input schema that
-     * depend on who is asking (a per-tenant component catalog, a per-plan list of options). Called
-     * when the turn's tool list is built, after every gate has passed; whatever it returns replaces
-     * the registered spec's `description` / `inputSchema` in the definition the model sees. Omit, or
-     * return `undefined`, to use the registered spec as is.
-     *
-     * It shapes what the model is SHOWN only: the registry still validates a call against the
-     * registered `inputSchema`, so a tool whose accepted input varies per turn registers a permissive
-     * schema and validates in `execute`.
-     */
-    describe?(scope: ToolDescribeScope): ToolDescription | undefined | Promise<ToolDescription | undefined>;
-}
-/** Who a turn's tool list is being built for — what {@link ToolHandler.describe} can vary on. */
-interface ToolDescribeScope {
-    actor: Actor;
-    /** Absent where the list is built outside a conversation (the MCP server's `tools/list`). */
-    threadId?: string;
-    agentName?: string;
-}
-/** A per-turn override of a tool's model-facing definition ({@link ToolHandler.describe}). */
-interface ToolDescription {
-    description?: string;
-    inputSchema?: StandardSchemaV1;
-}
-
-export type { AiToolCtx as A, ToolHandler as T, ToolDescribeScope as a, ToolDescription as b };