@nestjs-adk/core 0.0.3 → 1.0.0

package/README.md

@@ -183,6 +183,45 @@ Pass a `sessionId` to `ask()` and the conversation becomes persistent. The agent
 
 Storage goes through the `SessionStore` contract. The default implementation keeps everything in memory, which is perfect for development. For production you implement the contract with your own database and pass the class to `forRoot({ session })`. The store is the single source of truth: engines read from it and write to it, and never keep a private copy of the history.
 
+## Validating the session state
+
+The session state is a shared bag. Your code writes to it, tools write to it, and it can arrive from outside through a stored session. By default nothing checks those values, so a malformed value can travel all the way into your database layer. If you want a guarantee, declare a schema on the agent:
+
+```ts
+const reportState = z.object({ tenantId: z.string().min(1), count: z.number() });
+
+@Agent({ name: "reporter", description: "Builds reports.", state: reportState, ... })
+class ReporterAgent extends AdkAgent {}
+```
+
+From that moment the framework validates the declared keys at every border. When a run starts, the state coming from `ask()` and from the stored session is checked before any call to the model, so an invalid value fails fast with an `AgentStateInvalidError` and costs zero tokens. When a tool writes with `ctx.state.set`, the write is checked at that moment. Keys that the schema does not declare keep flowing freely, which matters for pipelines where one agent writes its output for the next one.
+
+Inside a tool you can also demand a value instead of hoping it is there:
+
+```ts
+execute(input, ctx: ToolContext<z.infer<typeof reportState>>) {
+	const tenantId = ctx.state.require("tenantId"); // typed as string, throws AgentStateMissingError if absent
+}
+```
+
+The generic on `ToolContext` is an annotation you choose, because the same tool can serve many agents. Typing it gives you autocomplete and typed reads. If a tool serves two agents, annotate it with the union of the two state types and TypeScript will only let you touch the keys both agents share.
+
+One note about errors: `AgentStateInvalidError` exposes the raw Zod issues in `error.issues`. Decide what your application logs, because in Zod v4 the issues can include the rejected value.
+
+## Capping the loop
+
+A lost model can call tools forever, and a broken tool can fail forever while the model retries. Both burn tokens. The framework ships two optional caps:
+
+```ts
+@Agent({ name: "reporter", maxIterations: 16, maxConsecutiveToolFailures: 2, ... })
+```
+
+`maxIterations` limits the model and tool round trips in a single run. Passing the cap aborts the run with an `AgentMaxIterationsError` that carries the aggregated token usage and the last requested tool, so you know what the loop cost before it died. `maxConsecutiveToolFailures` is a circuit breaker per tool: when the same tool fails that many times in a row the run aborts with a `ToolRepeatedFailureError`, without waiting for the bigger cap. A success resets the count.
+
+Both are off unless you set them. You can define module wide defaults with `forRoot({ defaults: { maxIterations: 16 } })`, override them per agent in the decorator, and override both per call in `ask()`. The call wins over the agent, and the agent wins over the module. Because the per call override wins, build your `RunInput` in your own code and never from a raw external payload.
+
+These caps protect runs that go through `ask()`, `stream()` and the runner. The `adk web` playground resolves agents through a different path and does not count iterations, which is fine because it is a development tool.
+
 ## Keeping the context small
 
 Long conversations and big tool results eat your context window. The framework handles both cases for you.
@@ -247,7 +286,7 @@ Modes are `sequential`, `parallel` and `loop`. A workflow is also an agent: you
 
 `stream()` yields a normalized event loop: `run_start`, `tool_call`, `tool_result`, `llm_response`, `model_rerouted`, `approval_required` and `final`. Every event carries a `raw` field with the original payload from the provider, so no information is lost. `ask()` consumes the same loop and aggregates it into a `RunResult` with `text`, `usage`, `events`, `status` and, when declared, `output`.
 
-Errors are not events. They throw as typed classes that extend `AdkError` and carry a `code`. Configuration problems throw at startup and point at the class that caused them. Runtime problems throw classes like `AiEmptyResponseError`, `OutputValidationError`, `ToolExecutionError` and `ModelsExhaustedError`, so you can catch exactly what you care about.
+Errors are not events. They throw as typed classes that extend `AdkError` and carry a `code`. Configuration problems throw at startup and point at the class that caused them. Runtime problems throw classes like `AiEmptyResponseError`, `OutputValidationError`, `ToolExecutionError`, `ModelsExhaustedError`, `AgentStateInvalidError` and `AgentMaxIterationsError`, so you can catch exactly what you care about.
 
 ## Logs
 

package/dist/index.cjs

@@ -159,6 +159,42 @@ class OutputValidationError extends AdkError {
         this.code = "OUTPUT_VALIDATION_FAILED";
     }
 }
+class AgentStateInvalidError extends AdkError {
+    constructor(agent, issues, key) {
+        super(key
+            ? `Agent "${agent}" received a value for state key "${key}" that does not match its declared state schema.`
+            : `Agent "${agent}" received state that does not match its declared state schema.`);
+        this.issues = issues;
+        this.key = key;
+        this.code = "AGENT_STATE_INVALID";
+    }
+}
+class AgentStateMissingError extends AdkError {
+    constructor(agent, key) {
+        super(`Agent "${agent}" requires state key "${key}" but it is absent.`);
+        this.key = key;
+        this.code = "AGENT_STATE_MISSING";
+    }
+}
+class AgentMaxIterationsError extends AdkError {
+    constructor(agent, limit, usage, lastTool) {
+        super(`Agent "${agent}" exceeded maxIterations (${limit}) — the run was aborted.${lastTool ? ` Last requested tool: "${lastTool}".` : ""}`);
+        this.limit = limit;
+        this.usage = usage;
+        this.lastTool = lastTool;
+        this.code = "AGENT_MAX_ITERATIONS";
+    }
+}
+class ToolRepeatedFailureError extends AdkError {
+    constructor(agent, tool, failures, cause) {
+        super(`Tool "${tool}" failed ${failures} consecutive times on agent "${agent}" — the run was aborted.`, {
+            cause,
+        });
+        this.tool = tool;
+        this.failures = failures;
+        this.code = "TOOL_REPEATED_FAILURE";
+    }
+}
 class McpConnectionError extends AdkError {
     constructor(server, cause) {
         super(`MCP server "${server}" connection failed.`, { cause });
@@ -827,6 +863,13 @@ class RunLogger {
                     this.logger.verbose(json(event));
         }
     }
+    abort(error, usage) {
+        this.logger.warn(`run aborted after ${Date.now() - this.startedAt}ms: ${error.message}${usageSuffix(usage)}`);
+    }
+    toolFailure(tool, count, limit) {
+        if (this.enabled("debug"))
+            this.logger.debug(`tool "${tool}" failed (${count}/${limit ?? "∞"} consecutive)`);
+    }
     enabled(level) {
         return LEVEL_WEIGHT[level] <= LEVEL_WEIGHT[this.level];
     }
@@ -852,9 +895,17 @@ function json(value) {
 }
 
 class DeltaStateBag {
-    constructor(initial) {
+    constructor(initial, guard = {}) {
         this.initial = initial;
+        this.guard = guard;
         this.changes = new Map();
+        const schema = guard.schema;
+        if (!schema)
+            return;
+        for (const key of Object.keys(schema.shape)) {
+            if (initial[key] !== undefined)
+                this.validate(key, initial[key]);
+        }
     }
     get(key) {
         if (this.changes.has(key))
@@ -862,11 +913,28 @@ class DeltaStateBag {
         return this.initial[key];
     }
     set(key, value) {
+        this.validate(key, value);
         this.changes.set(key, value);
     }
+    require(key) {
+        const value = this.get(key);
+        if (value === undefined)
+            throw new AgentStateMissingError(this.guard.agent ?? "unknown", key);
+        return value;
+    }
     delta() {
         return Object.fromEntries(this.changes);
     }
+    validate(key, value) {
+        const shape = this.guard.schema?.shape;
+        if (!shape || !Object.hasOwn(shape, key))
+            return;
+        const field = shape[key];
+        const result = field.safeParse(value);
+        if (!result.success) {
+            throw new AgentStateInvalidError(this.guard.agent ?? "unknown", result.error?.issues, key);
+        }
+    }
 }
 
 const EMPTY_USAGE = { promptTokens: 0, outputTokens: 0, totalTokens: 0 };
@@ -885,23 +953,54 @@ exports.AgentRunner = class AgentRunner {
         const log = RunLogger.create(this.options.logging, definition.name);
         log?.start(input);
         const session = await this.openSession(input);
-        const state = new DeltaStateBag({ ...(session?.state ?? {}), ...(input.state ?? {}) });
-        const runtime = { scope: input.sessionId ?? node_crypto.randomUUID(), pendings: [] };
-        const ctx = this.createToolContext(definition, input, state);
+        const state = this.stateBagFor(definition, { ...(session?.state ?? {}), ...(input.state ?? {}) });
+        const controller = new AbortController();
+        const signal = input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal;
+        const runtime = this.createRuntime(definition, input, controller, log);
+        const ctx = this.createToolContext(definition, input, state, signal);
         const resolved = await this.resolveAgent(definition, ctx, runtime);
-        const engineInput = { ...input, history: session?.events };
+        const engineInput = { ...input, signal, history: session?.events };
         if (session)
             await this.persist(session.id, "user", "message", { text: input.message });
-        for await (const event of this.engine.run(resolved, engineInput)) {
-            log?.event(event);
-            if (session)
-                await this.persistAgentEvent(session.id, event);
-            if (event.type === "final" && definition.output && definition.outputKey) {
-                const parsed = definition.output.safeParse(tryParseJson(event.text));
-                if (parsed.success)
-                    state.set(definition.outputKey, parsed.data);
+        let iterations = 0;
+        let usage = EMPTY_USAGE;
+        let lastEventType;
+        try {
+            for await (const event of this.engine.run(resolved, engineInput)) {
+                if (runtime.fatal)
+                    break;
+                if (event.type === "llm_response" && event.usage)
+                    usage = addUsage(usage, event.usage);
+                if (event.type === "tool_call" && lastEventType !== "tool_call") {
+                    iterations += 1;
+                    const limit = runtime.limits.maxIterations;
+                    if (limit !== undefined && iterations > limit) {
+                        runtime.abort(new AgentMaxIterationsError(definition.name, limit, usage, event.tool));
+                        break;
+                    }
+                }
+                lastEventType = event.type;
+                log?.event(event);
+                if (session)
+                    await this.persistAgentEvent(session.id, event);
+                if (event.type === "final" && definition.output && definition.outputKey) {
+                    const parsed = definition.output.safeParse(tryParseJson(event.text));
+                    if (parsed.success)
+                        state.set(definition.outputKey, parsed.data);
+                }
+                yield event;
+            }
+        }
+        catch (error) {
+            if (runtime.fatal) {
+                log?.abort(runtime.fatal, usage);
+                throw runtime.fatal;
             }
-            yield event;
+            throw error;
+        }
+        if (runtime.fatal) {
+            log?.abort(runtime.fatal, usage);
+            throw runtime.fatal;
         }
         for (const pending of runtime.pendings) {
             const approval = {
@@ -960,7 +1059,7 @@ exports.AgentRunner = class AgentRunner {
         const binding = definition.tools.find((candidate) => candidate.options.name === entry.tool);
         if (!binding)
             throw new ApprovalNotFoundError(params.callId, params.sessionId);
-        const state = new DeltaStateBag(session.state);
+        const state = this.stateBagFor(definition, session.state);
         const ctx = this.createToolContext(definition, { message: "", sessionId: session.id, userId: session.userId }, state);
         const result = await this.executeBinding(definition, binding, entry.args, ctx);
         await this.persist(session.id, "tool", "tool_result", { callId: entry.callId, tool: entry.tool, result });
@@ -978,11 +1077,9 @@ exports.AgentRunner = class AgentRunner {
     }
     resolve(agentType, input = { message: "" }) {
         const definition = this.definitionOf(agentType);
-        const state = new DeltaStateBag({ ...(input.state ?? {}) });
-        return this.resolveAgent(definition, this.createToolContext(definition, input, state), {
-            scope: input.sessionId ?? node_crypto.randomUUID(),
-            pendings: [],
-        });
+        const state = this.stateBagFor(definition, { ...(input.state ?? {}) });
+        const runtime = this.createRuntime(definition, input);
+        return this.resolveAgent(definition, this.createToolContext(definition, input, state), runtime);
     }
     definitionOf(agentType) {
         return typeof agentType === "string" ? this.registry.get(agentType) : this.registry.getByType(agentType);
@@ -1005,17 +1102,42 @@ exports.AgentRunner = class AgentRunner {
             throw new ApprovalNotFoundError(callId, sessionId);
         return { session, entry, rest: pendings.filter((candidate) => candidate.callId !== callId) };
     }
-    createToolContext(definition, input, state) {
+    createToolContext(definition, input, state, signal) {
         return {
             agentName: definition.name,
             sessionId: input.sessionId,
             userId: input.userId,
             state,
             attributes: input.attributes ?? {},
-            signal: input.signal ?? new AbortController().signal,
+            signal: signal ?? input.signal ?? new AbortController().signal,
             actions: { endRun: () => undefined },
         };
     }
+    stateBagFor(definition, initial) {
+        return new DeltaStateBag(initial, { schema: definition.options?.state, agent: definition.name });
+    }
+    createRuntime(definition, input, controller, log) {
+        const runtime = {
+            scope: input.sessionId ?? node_crypto.randomUUID(),
+            pendings: [],
+            failures: new Map(),
+            limits: this.limitsFor(definition, input),
+            log,
+            abort: (error) => {
+                runtime.fatal ??= error;
+                controller?.abort();
+            },
+        };
+        return runtime;
+    }
+    limitsFor(definition, input) {
+        return {
+            maxIterations: input.maxIterations ?? definition.options?.maxIterations ?? this.options.defaults?.maxIterations,
+            maxConsecutiveToolFailures: input.maxConsecutiveToolFailures ??
+                definition.options?.maxConsecutiveToolFailures ??
+                this.options.defaults?.maxConsecutiveToolFailures,
+        };
+    }
     policyOf(definition) {
         return definition.options?.context ?? this.options.context;
     }
@@ -1044,7 +1166,7 @@ exports.AgentRunner = class AgentRunner {
                         note: `Action "${pending.tool}" requires user approval and was NOT executed. Let the user know it is awaiting approval.`,
                     };
                 }
-                const raw = await this.executeBinding(definition, binding, input, ctx);
+                const raw = await this.executeGuarded(definition, binding, input, ctx, runtime);
                 if (!offloadEnabled || binding.options.offload === false)
                     return raw;
                 return this.maybeOffload(raw, binding.options.name ?? "", threshold, runtime.scope);
@@ -1102,6 +1224,26 @@ exports.AgentRunner = class AgentRunner {
         const self = binding.kind === "class" ? binding.instance : definition.instance;
         return requirement.call(self, input, ctx);
     }
+    async executeGuarded(definition, binding, input, ctx, runtime) {
+        const tool = binding.options.name ?? "";
+        try {
+            const raw = await this.executeBinding(definition, binding, input, ctx);
+            runtime.failures.delete(tool);
+            return raw;
+        }
+        catch (error) {
+            const count = (runtime.failures.get(tool) ?? 0) + 1;
+            runtime.failures.set(tool, count);
+            const limit = runtime.limits.maxConsecutiveToolFailures;
+            runtime.log?.toolFailure(tool, count, limit);
+            if (limit !== undefined && count >= limit) {
+                const fatal = new ToolRepeatedFailureError(definition.name, tool, count, error);
+                runtime.abort(fatal);
+                throw fatal;
+            }
+            throw error;
+        }
+    }
     async executeBinding(definition, binding, input, ctx) {
         try {
             if (binding.kind === "class")
@@ -1197,6 +1339,13 @@ exports.AgentRunner = __decorate([
         SessionStore,
         ArtifactStore, Object, ToolsetResolver])
 ], exports.AgentRunner);
+function addUsage(total, delta) {
+    return {
+        promptTokens: total.promptTokens + delta.promptTokens,
+        outputTokens: total.outputTokens + delta.outputTokens,
+        totalTokens: total.totalTokens + delta.totalTokens,
+    };
+}
 function tryParseJson(text) {
     try {
         return JSON.parse(text);
@@ -1404,8 +1553,11 @@ exports.AdkTool = AdkTool;
 exports.AdkWorkflow = AdkWorkflow;
 exports.Agent = Agent;
 exports.AgentDefinition = AgentDefinition;
+exports.AgentMaxIterationsError = AgentMaxIterationsError;
 exports.AgentNotFoundError = AgentNotFoundError;
 exports.AgentRef = AgentRef;
+exports.AgentStateInvalidError = AgentStateInvalidError;
+exports.AgentStateMissingError = AgentStateMissingError;
 exports.AiEmptyResponseError = AiEmptyResponseError;
 exports.ApprovalNotFoundError = ApprovalNotFoundError;
 exports.ArtifactStore = ArtifactStore;
@@ -1433,6 +1585,7 @@ exports.Skill = Skill;
 exports.SkillNotFoundError = SkillNotFoundError;
 exports.Tool = Tool;
 exports.ToolExecutionError = ToolExecutionError;
+exports.ToolRepeatedFailureError = ToolRepeatedFailureError;
 exports.ToolsetResolver = ToolsetResolver;
 exports.UnregisteredPromptError = UnregisteredPromptError;
 exports.UnregisteredSkillError = UnregisteredSkillError;

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { AgentRunner } from "./lib/runner/agent-runner";
 export { RunLogger } from "./lib/runner/run-logger";
 export type { LoggingOption } from "./lib/runner/run-logger";
 export { DeltaStateBag } from "./lib/runner/state-bag";
+export type { StateGuard } from "./lib/runner/state-bag";
 export { buildInstruction, skillContent } from "./lib/runner/instruction-builder";
 export { Gemini, ModelRouter, OpenAiLike, isModelSpec } from "./lib/models/model-specs";
 export { DEFAULT_OFFLOAD_THRESHOLD, contextPolicy } from "./lib/models/context-policy";
@@ -40,7 +41,7 @@ export type { SkillBinding, ToolBinding } from "./lib/registry/agent-definition"
 export { AgentRef } from "./lib/registry/agent-ref";
 export { AgentRegistry } from "./lib/registry/agent-registry";
 export { AdkBootError, AdkError, DuplicateAgentNameError, ConflictingPromptError, InvalidWorkflowError, MissingModelError, ReservedMethodError, UnregisteredPromptError, UnregisteredSkillError, UnregisteredSubAgentError, UnregisteredToolError, UnresolvedToolsetError, } from "./lib/errors";
-export { AgentNotFoundError, AiEmptyResponseError, ApprovalNotFoundError, EmbedderNotConfiguredError, McpConnectionError, ModelsExhaustedError, OutputValidationError, SessionNotFoundError, SkillNotFoundError, ToolExecutionError, } from "./lib/errors/runtime.errors";
+export { AgentMaxIterationsError, AgentNotFoundError, AgentStateInvalidError, AgentStateMissingError, AiEmptyResponseError, ApprovalNotFoundError, EmbedderNotConfiguredError, McpConnectionError, ModelsExhaustedError, OutputValidationError, SessionNotFoundError, SkillNotFoundError, ToolExecutionError, ToolRepeatedFailureError, } from "./lib/errors/runtime.errors";
 export type { AgentEvent, ArtifactPart, ArtifactRef, PendingApproval, RawRef, RunInput, RunResult, Session, SessionEvent, SessionInit, TokenUsage, } from "./lib/types/events";
 export type { AgentOptions, AnyZodObject, ModelInput, SkillMode, SkillOptions, ToolOptions, WorkflowMode, WorkflowOptions, } from "./lib/types/options";
 export type { StateBag, ToolContext } from "./lib/types/tool-context";

package/dist/index.mjs

@@ -157,6 +157,42 @@ class OutputValidationError extends AdkError {
         this.code = "OUTPUT_VALIDATION_FAILED";
     }
 }
+class AgentStateInvalidError extends AdkError {
+    constructor(agent, issues, key) {
+        super(key
+            ? `Agent "${agent}" received a value for state key "${key}" that does not match its declared state schema.`
+            : `Agent "${agent}" received state that does not match its declared state schema.`);
+        this.issues = issues;
+        this.key = key;
+        this.code = "AGENT_STATE_INVALID";
+    }
+}
+class AgentStateMissingError extends AdkError {
+    constructor(agent, key) {
+        super(`Agent "${agent}" requires state key "${key}" but it is absent.`);
+        this.key = key;
+        this.code = "AGENT_STATE_MISSING";
+    }
+}
+class AgentMaxIterationsError extends AdkError {
+    constructor(agent, limit, usage, lastTool) {
+        super(`Agent "${agent}" exceeded maxIterations (${limit}) — the run was aborted.${lastTool ? ` Last requested tool: "${lastTool}".` : ""}`);
+        this.limit = limit;
+        this.usage = usage;
+        this.lastTool = lastTool;
+        this.code = "AGENT_MAX_ITERATIONS";
+    }
+}
+class ToolRepeatedFailureError extends AdkError {
+    constructor(agent, tool, failures, cause) {
+        super(`Tool "${tool}" failed ${failures} consecutive times on agent "${agent}" — the run was aborted.`, {
+            cause,
+        });
+        this.tool = tool;
+        this.failures = failures;
+        this.code = "TOOL_REPEATED_FAILURE";
+    }
+}
 class McpConnectionError extends AdkError {
     constructor(server, cause) {
         super(`MCP server "${server}" connection failed.`, { cause });
@@ -825,6 +861,13 @@ class RunLogger {
                     this.logger.verbose(json(event));
         }
     }
+    abort(error, usage) {
+        this.logger.warn(`run aborted after ${Date.now() - this.startedAt}ms: ${error.message}${usageSuffix(usage)}`);
+    }
+    toolFailure(tool, count, limit) {
+        if (this.enabled("debug"))
+            this.logger.debug(`tool "${tool}" failed (${count}/${limit ?? "∞"} consecutive)`);
+    }
     enabled(level) {
         return LEVEL_WEIGHT[level] <= LEVEL_WEIGHT[this.level];
     }
@@ -850,9 +893,17 @@ function json(value) {
 }
 
 class DeltaStateBag {
-    constructor(initial) {
+    constructor(initial, guard = {}) {
         this.initial = initial;
+        this.guard = guard;
         this.changes = new Map();
+        const schema = guard.schema;
+        if (!schema)
+            return;
+        for (const key of Object.keys(schema.shape)) {
+            if (initial[key] !== undefined)
+                this.validate(key, initial[key]);
+        }
     }
     get(key) {
         if (this.changes.has(key))
@@ -860,11 +911,28 @@ class DeltaStateBag {
         return this.initial[key];
     }
     set(key, value) {
+        this.validate(key, value);
         this.changes.set(key, value);
     }
+    require(key) {
+        const value = this.get(key);
+        if (value === undefined)
+            throw new AgentStateMissingError(this.guard.agent ?? "unknown", key);
+        return value;
+    }
     delta() {
         return Object.fromEntries(this.changes);
     }
+    validate(key, value) {
+        const shape = this.guard.schema?.shape;
+        if (!shape || !Object.hasOwn(shape, key))
+            return;
+        const field = shape[key];
+        const result = field.safeParse(value);
+        if (!result.success) {
+            throw new AgentStateInvalidError(this.guard.agent ?? "unknown", result.error?.issues, key);
+        }
+    }
 }
 
 const EMPTY_USAGE = { promptTokens: 0, outputTokens: 0, totalTokens: 0 };
@@ -883,23 +951,54 @@ let AgentRunner = class AgentRunner {
         const log = RunLogger.create(this.options.logging, definition.name);
         log?.start(input);
         const session = await this.openSession(input);
-        const state = new DeltaStateBag({ ...(session?.state ?? {}), ...(input.state ?? {}) });
-        const runtime = { scope: input.sessionId ?? randomUUID(), pendings: [] };
-        const ctx = this.createToolContext(definition, input, state);
+        const state = this.stateBagFor(definition, { ...(session?.state ?? {}), ...(input.state ?? {}) });
+        const controller = new AbortController();
+        const signal = input.signal ? AbortSignal.any([input.signal, controller.signal]) : controller.signal;
+        const runtime = this.createRuntime(definition, input, controller, log);
+        const ctx = this.createToolContext(definition, input, state, signal);
         const resolved = await this.resolveAgent(definition, ctx, runtime);
-        const engineInput = { ...input, history: session?.events };
+        const engineInput = { ...input, signal, history: session?.events };
         if (session)
             await this.persist(session.id, "user", "message", { text: input.message });
-        for await (const event of this.engine.run(resolved, engineInput)) {
-            log?.event(event);
-            if (session)
-                await this.persistAgentEvent(session.id, event);
-            if (event.type === "final" && definition.output && definition.outputKey) {
-                const parsed = definition.output.safeParse(tryParseJson(event.text));
-                if (parsed.success)
-                    state.set(definition.outputKey, parsed.data);
+        let iterations = 0;
+        let usage = EMPTY_USAGE;
+        let lastEventType;
+        try {
+            for await (const event of this.engine.run(resolved, engineInput)) {
+                if (runtime.fatal)
+                    break;
+                if (event.type === "llm_response" && event.usage)
+                    usage = addUsage(usage, event.usage);
+                if (event.type === "tool_call" && lastEventType !== "tool_call") {
+                    iterations += 1;
+                    const limit = runtime.limits.maxIterations;
+                    if (limit !== undefined && iterations > limit) {
+                        runtime.abort(new AgentMaxIterationsError(definition.name, limit, usage, event.tool));
+                        break;
+                    }
+                }
+                lastEventType = event.type;
+                log?.event(event);
+                if (session)
+                    await this.persistAgentEvent(session.id, event);
+                if (event.type === "final" && definition.output && definition.outputKey) {
+                    const parsed = definition.output.safeParse(tryParseJson(event.text));
+                    if (parsed.success)
+                        state.set(definition.outputKey, parsed.data);
+                }
+                yield event;
+            }
+        }
+        catch (error) {
+            if (runtime.fatal) {
+                log?.abort(runtime.fatal, usage);
+                throw runtime.fatal;
             }
-            yield event;
+            throw error;
+        }
+        if (runtime.fatal) {
+            log?.abort(runtime.fatal, usage);
+            throw runtime.fatal;
         }
         for (const pending of runtime.pendings) {
             const approval = {
@@ -958,7 +1057,7 @@ let AgentRunner = class AgentRunner {
         const binding = definition.tools.find((candidate) => candidate.options.name === entry.tool);
         if (!binding)
             throw new ApprovalNotFoundError(params.callId, params.sessionId);
-        const state = new DeltaStateBag(session.state);
+        const state = this.stateBagFor(definition, session.state);
         const ctx = this.createToolContext(definition, { message: "", sessionId: session.id, userId: session.userId }, state);
         const result = await this.executeBinding(definition, binding, entry.args, ctx);
         await this.persist(session.id, "tool", "tool_result", { callId: entry.callId, tool: entry.tool, result });
@@ -976,11 +1075,9 @@ let AgentRunner = class AgentRunner {
     }
     resolve(agentType, input = { message: "" }) {
         const definition = this.definitionOf(agentType);
-        const state = new DeltaStateBag({ ...(input.state ?? {}) });
-        return this.resolveAgent(definition, this.createToolContext(definition, input, state), {
-            scope: input.sessionId ?? randomUUID(),
-            pendings: [],
-        });
+        const state = this.stateBagFor(definition, { ...(input.state ?? {}) });
+        const runtime = this.createRuntime(definition, input);
+        return this.resolveAgent(definition, this.createToolContext(definition, input, state), runtime);
     }
     definitionOf(agentType) {
         return typeof agentType === "string" ? this.registry.get(agentType) : this.registry.getByType(agentType);
@@ -1003,17 +1100,42 @@ let AgentRunner = class AgentRunner {
             throw new ApprovalNotFoundError(callId, sessionId);
         return { session, entry, rest: pendings.filter((candidate) => candidate.callId !== callId) };
     }
-    createToolContext(definition, input, state) {
+    createToolContext(definition, input, state, signal) {
         return {
             agentName: definition.name,
             sessionId: input.sessionId,
             userId: input.userId,
             state,
             attributes: input.attributes ?? {},
-            signal: input.signal ?? new AbortController().signal,
+            signal: signal ?? input.signal ?? new AbortController().signal,
             actions: { endRun: () => undefined },
         };
     }
+    stateBagFor(definition, initial) {
+        return new DeltaStateBag(initial, { schema: definition.options?.state, agent: definition.name });
+    }
+    createRuntime(definition, input, controller, log) {
+        const runtime = {
+            scope: input.sessionId ?? randomUUID(),
+            pendings: [],
+            failures: new Map(),
+            limits: this.limitsFor(definition, input),
+            log,
+            abort: (error) => {
+                runtime.fatal ??= error;
+                controller?.abort();
+            },
+        };
+        return runtime;
+    }
+    limitsFor(definition, input) {
+        return {
+            maxIterations: input.maxIterations ?? definition.options?.maxIterations ?? this.options.defaults?.maxIterations,
+            maxConsecutiveToolFailures: input.maxConsecutiveToolFailures ??
+                definition.options?.maxConsecutiveToolFailures ??
+                this.options.defaults?.maxConsecutiveToolFailures,
+        };
+    }
     policyOf(definition) {
         return definition.options?.context ?? this.options.context;
     }
@@ -1042,7 +1164,7 @@ let AgentRunner = class AgentRunner {
                         note: `Action "${pending.tool}" requires user approval and was NOT executed. Let the user know it is awaiting approval.`,
                     };
                 }
-                const raw = await this.executeBinding(definition, binding, input, ctx);
+                const raw = await this.executeGuarded(definition, binding, input, ctx, runtime);
                 if (!offloadEnabled || binding.options.offload === false)
                     return raw;
                 return this.maybeOffload(raw, binding.options.name ?? "", threshold, runtime.scope);
@@ -1100,6 +1222,26 @@ let AgentRunner = class AgentRunner {
         const self = binding.kind === "class" ? binding.instance : definition.instance;
         return requirement.call(self, input, ctx);
     }
+    async executeGuarded(definition, binding, input, ctx, runtime) {
+        const tool = binding.options.name ?? "";
+        try {
+            const raw = await this.executeBinding(definition, binding, input, ctx);
+            runtime.failures.delete(tool);
+            return raw;
+        }
+        catch (error) {
+            const count = (runtime.failures.get(tool) ?? 0) + 1;
+            runtime.failures.set(tool, count);
+            const limit = runtime.limits.maxConsecutiveToolFailures;
+            runtime.log?.toolFailure(tool, count, limit);
+            if (limit !== undefined && count >= limit) {
+                const fatal = new ToolRepeatedFailureError(definition.name, tool, count, error);
+                runtime.abort(fatal);
+                throw fatal;
+            }
+            throw error;
+        }
+    }
     async executeBinding(definition, binding, input, ctx) {
         try {
             if (binding.kind === "class")
@@ -1195,6 +1337,13 @@ AgentRunner = __decorate([
         SessionStore,
         ArtifactStore, Object, ToolsetResolver])
 ], AgentRunner);
+function addUsage(total, delta) {
+    return {
+        promptTokens: total.promptTokens + delta.promptTokens,
+        outputTokens: total.outputTokens + delta.outputTokens,
+        totalTokens: total.totalTokens + delta.totalTokens,
+    };
+}
 function tryParseJson(text) {
     try {
         return JSON.parse(text);
@@ -1391,4 +1540,4 @@ function isScriptedModel(model) {
     return typeof model === "object" && model !== null && "__adkScriptedModel" in model;
 }
 
-export { ADK_OPTIONS, AdkAgent, AdkBootError, AdkEngine, AdkError, AdkModule, AdkPrompt, AdkSkill, AdkTool, AdkWorkflow, Agent, AgentDefinition, AgentNotFoundError, AgentRef, AgentRegistry, AgentRunner, AgentSessions, AiEmptyResponseError, ApprovalNotFoundError, ArtifactStore, ConflictingPromptError, DEFAULT_OFFLOAD_THRESHOLD, DeltaStateBag, DuplicateAgentNameError, Embedder, EmbedderNotConfiguredError, Gemini, InMemoryArtifactStore, InMemorySessionStore, InvalidWorkflowError, McpConnectionError, MemoryStore, MissingModelError, ModelRouter, ModelsExhaustedError, OpenAiLike, OutputValidationError, PromptFiles, ReservedMethodError, RunLogger, ScriptedEngine, ScriptedModel, SessionNotFoundError, SessionStore, Similarity, Skill, SkillNotFoundError, Tool, ToolExecutionError, ToolsetResolver, UnregisteredPromptError, UnregisteredSkillError, UnregisteredSubAgentError, UnregisteredToolError, UnresolvedToolsetError, WorkflowAgent, buildInstruction, callTool, contextPolicy, fail, isModelSpec, isScriptedModel, isToolsetRef, skillContent, text, toolset };
+export { ADK_OPTIONS, AdkAgent, AdkBootError, AdkEngine, AdkError, AdkModule, AdkPrompt, AdkSkill, AdkTool, AdkWorkflow, Agent, AgentDefinition, AgentMaxIterationsError, AgentNotFoundError, AgentRef, AgentRegistry, AgentRunner, AgentSessions, AgentStateInvalidError, AgentStateMissingError, AiEmptyResponseError, ApprovalNotFoundError, ArtifactStore, ConflictingPromptError, DEFAULT_OFFLOAD_THRESHOLD, DeltaStateBag, DuplicateAgentNameError, Embedder, EmbedderNotConfiguredError, Gemini, InMemoryArtifactStore, InMemorySessionStore, InvalidWorkflowError, McpConnectionError, MemoryStore, MissingModelError, ModelRouter, ModelsExhaustedError, OpenAiLike, OutputValidationError, PromptFiles, ReservedMethodError, RunLogger, ScriptedEngine, ScriptedModel, SessionNotFoundError, SessionStore, Similarity, Skill, SkillNotFoundError, Tool, ToolExecutionError, ToolRepeatedFailureError, ToolsetResolver, UnregisteredPromptError, UnregisteredSkillError, UnregisteredSubAgentError, UnregisteredToolError, UnresolvedToolsetError, WorkflowAgent, buildInstruction, callTool, contextPolicy, fail, isModelSpec, isScriptedModel, isToolsetRef, skillContent, text, toolset };

package/dist/lib/errors/index.d.ts

@@ -1,3 +1,3 @@
 export { AdkError } from "./adk.error";
 export { AdkBootError, DuplicateAgentNameError, ConflictingPromptError, InvalidWorkflowError, MissingModelError, ReservedMethodError, UnregisteredPromptError, UnregisteredSkillError, UnregisteredSubAgentError, UnregisteredToolError, UnresolvedToolsetError, } from "./boot.errors";
-export { AgentNotFoundError, ApprovalNotFoundError, EmbedderNotConfiguredError, AiEmptyResponseError, McpConnectionError, ModelsExhaustedError, OutputValidationError, SessionNotFoundError, SkillNotFoundError, ToolExecutionError, } from "./runtime.errors";
+export { AgentMaxIterationsError, AgentNotFoundError, AgentStateInvalidError, AgentStateMissingError, ApprovalNotFoundError, EmbedderNotConfiguredError, AiEmptyResponseError, McpConnectionError, ModelsExhaustedError, OutputValidationError, SessionNotFoundError, SkillNotFoundError, ToolExecutionError, ToolRepeatedFailureError, } from "./runtime.errors";

package/dist/lib/errors/runtime.errors.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from "../types/events";
 import { AdkError } from "./adk.error";
 export declare class AiEmptyResponseError extends AdkError {
     readonly code = "AI_EMPTY_RESPONSE";
@@ -41,6 +42,30 @@ export declare class OutputValidationError extends AdkError {
     readonly code = "OUTPUT_VALIDATION_FAILED";
     constructor(agent: string, rawOutput: unknown, issues: unknown);
 }
+export declare class AgentStateInvalidError extends AdkError {
+    readonly issues: unknown;
+    readonly key?: string | undefined;
+    readonly code = "AGENT_STATE_INVALID";
+    constructor(agent: string, issues: unknown, key?: string | undefined);
+}
+export declare class AgentStateMissingError extends AdkError {
+    readonly key: string;
+    readonly code = "AGENT_STATE_MISSING";
+    constructor(agent: string, key: string);
+}
+export declare class AgentMaxIterationsError extends AdkError {
+    readonly limit: number;
+    readonly usage: TokenUsage;
+    readonly lastTool?: string | undefined;
+    readonly code = "AGENT_MAX_ITERATIONS";
+    constructor(agent: string, limit: number, usage: TokenUsage, lastTool?: string | undefined);
+}
+export declare class ToolRepeatedFailureError extends AdkError {
+    readonly tool: string;
+    readonly failures: number;
+    readonly code = "TOOL_REPEATED_FAILURE";
+    constructor(agent: string, tool: string, failures: number, cause: unknown);
+}
 export declare class McpConnectionError extends AdkError {
     readonly code = "MCP_CONNECTION_FAILED";
     constructor(server: string, cause: unknown);

package/dist/lib/module/adk-options.d.ts

@@ -16,6 +16,10 @@ export interface AdkModuleOptions {
     };
     logging?: import("../runner/run-logger").LoggingOption;
     context?: import("../models/context-policy").ContextPolicy;
+    defaults?: {
+        maxIterations?: number;
+        maxConsecutiveToolFailures?: number;
+    };
 }
 export interface AdkModuleAsyncOptions extends Pick<ModuleMetadata, "imports"> {
     engine: Type<AdkEngine>;

package/dist/lib/runner/agent-runner.d.ts

@@ -32,9 +32,13 @@ export declare class AgentRunner {
     private openSession;
     private takePending;
     private createToolContext;
+    private stateBagFor;
+    private createRuntime;
+    private limitsFor;
     private policyOf;
     private resolveAgent;
     private needsApproval;
+    private executeGuarded;
     private executeBinding;
     private maybeOffload;
     private createReadArtifactTool;

package/dist/lib/runner/run-logger.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, RunInput } from "../types/events";
+import type { AgentEvent, RunInput, TokenUsage } from "../types/events";
 export type LoggingOption = boolean | "info" | "debug" | "verbose" | undefined;
 export declare class RunLogger {
     private readonly level;
@@ -8,6 +8,8 @@ export declare class RunLogger {
     private constructor();
     start(input: RunInput): void;
     event(event: AgentEvent): void;
+    abort(error: Error, usage: TokenUsage): void;
+    toolFailure(tool: string, count: number, limit: number | undefined): void;
     private enabled;
     private preview;
 }

package/dist/lib/runner/state-bag.d.ts

@@ -1,9 +1,17 @@
+import type { AnyZodObject } from "../types/options";
 import type { StateBag } from "../types/tool-context";
+export interface StateGuard {
+    schema?: AnyZodObject;
+    agent?: string;
+}
 export declare class DeltaStateBag implements StateBag {
     private readonly initial;
+    private readonly guard;
     private readonly changes;
-    constructor(initial: Record<string, unknown>);
+    constructor(initial: Record<string, unknown>, guard?: StateGuard);
     get<T = unknown>(key: string): T | undefined;
     set(key: string, value: unknown): void;
+    require<T = unknown>(key: string): T;
     delta(): Record<string, unknown>;
+    private validate;
 }

package/dist/lib/types/events.d.ts

@@ -66,6 +66,8 @@ export interface RunInput {
     attributes?: Record<string, unknown>;
     labels?: Record<string, string>;
     signal?: AbortSignal;
+    maxIterations?: number;
+    maxConsecutiveToolFailures?: number;
     history?: SessionEvent[];
 }
 export interface PendingApproval {

package/dist/lib/types/options.d.ts

@@ -20,6 +20,9 @@ export interface AgentOptions {
     output?: ZodObject<ZodRawShape>;
     outputKey?: string;
     context?: import("../models/context-policy").ContextPolicy;
+    state?: AnyZodObject;
+    maxIterations?: number;
+    maxConsecutiveToolFailures?: number;
 }
 export interface ToolOptions<S extends AnyZodObject = AnyZodObject> {
     name?: string;

package/dist/lib/types/tool-context.d.ts

@@ -1,15 +1,18 @@
-export interface ToolContext {
+export interface ToolContext<TState extends Record<string, unknown> = Record<string, unknown>> {
     agentName: string;
     sessionId?: string;
     userId?: string;
-    state: StateBag;
+    state: StateBag<TState>;
     attributes: Record<string, unknown>;
     signal: AbortSignal;
     actions: {
         endRun(): void;
     };
 }
-export interface StateBag {
+export interface StateBag<TState extends Record<string, unknown> = Record<string, unknown>> {
+    get<K extends keyof TState & string, V extends TState[K]>(key: K): V | undefined;
     get<T = unknown>(key: string): T | undefined;
-    set(key: string, value: unknown): void;
+    set<K extends keyof TState & string>(key: K, value: TState[K]): void;
+    require<K extends keyof TState & string, V extends TState[K]>(key: K): V;
+    require<T = unknown>(key: string): T;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nestjs-adk/core",
-	"version": "0.0.3",
+	"version": "1.0.0",
 	"description": "NestJS-native agent framework: decorators, DI and abstract contracts over pluggable AI agent engines (Google ADK first).",
 	"license": "MIT",
 	"sideEffects": false,