@nestjs-adk/core 0.0.2 → 1.0.0

package/README.md

@@ -1,28 +1,320 @@
 # @nestjs-adk/core
 
-**NestJS-native** AI agent framework: decorators (`@Agent`, `@Tool`, `@Skill`, `@WorkflowAgent`), DI and abstract contracts over pluggable engines. The agent instance is the execution handle — inject the class and call `ask()` / `stream()` / `approve()` / `reject()`.
+**Build AI agents the NestJS way.**
+
+NestJS developers already know how to build good software: classes, modules, providers and dependency injection. nestjs-adk brings AI agents into that same world. An agent is a class with a decorator. A tool is a provider. Everything is injected, validated and tested like the rest of your app.
+
+This package is the framework itself. It gives you the decorators, the module, the run loop and all the contracts. To actually talk to an LLM you also install an engine, and the first supported engine is the Google ADK:
+
+```bash
+npm i @nestjs-adk/core @nestjs-adk/google
+```
+
+## Your first agent
+
+Start by registering the module once, in your root module. This is where you choose the engine and the default model:
+
+```ts
+import { AdkModule } from "@nestjs-adk/core";
+import { GoogleAdkEngine } from "@nestjs-adk/google";
+
+@Module({
+	imports: [
+		AdkModule.forRoot({
+			engine: GoogleAdkEngine,
+			defaultModel: "gemini-2.5-flash",
+		}),
+	],
+	providers: [SupportAgent, LookupOrderTool, OrdersService, ChatService],
+})
+export class AppModule {}
+```
+
+Now create the agent. It is a class that extends `AdkAgent` and is described by the `@Agent` decorator:
 
 ```ts
+import { Agent, AdkAgent } from "@nestjs-adk/core";
+
 @Agent({
 	name: "support_agent",
 	description: "Customer support.",
-	model: "gemini-2.5-flash",
 	prompt: "You are the store's support agent.",
 	tools: [LookupOrderTool],
 })
 export class SupportAgent extends AdkAgent {}
+```
+
+Notice that the agent went into `providers` like any other class. There is no special registration step. If you forget to register a tool, a prompt class or a sub-agent, the app fails at startup with an error that points at the missing class, so configuration mistakes never reach runtime.
+
+To use the agent, inject it. The instance itself is the handle:
 
-// anywhere in your app — plain Nest DI
-constructor(private readonly support: SupportAgent) {}
-const { text } = await this.support.ask({ sessionId, message: "where is my order?" });
+```ts
+@Injectable()
+export class ChatService {
+	constructor(private readonly support: SupportAgent) {}
+
+	async answer(sessionId: string, message: string) {
+		const { text } = await this.support.ask({ sessionId, message });
+		return text;
+	}
+}
 ```
 
-Includes: fail-fast boot validation, prompts (literal, `.md` files or `AdkPrompt` builder classes), model specs (`OpenAiLike`, `ModelRouter` with failover), sessions with pluggable `SessionStore`, automatic artifact offload, native compaction, HITL approvals, structured output validation, leveled run logs with token usage, and an `Embedder` contract.
+`ask()` runs the agent and returns the final result. `stream()` gives you the events one by one while the agent works. Later in this document you will also meet `approve()` and `reject()`, used for human approval.
 
-Pair it with an engine — [`@nestjs-adk/google`](https://www.npmjs.com/package/@nestjs-adk/google) — and, for tests, [`@nestjs-adk/testing`](https://www.npmjs.com/package/@nestjs-adk/testing).
+That is the whole mental model: configure the module once, register classes as providers, inject the agent and call it.
 
-```bash
-npm i @nestjs-adk/core @nestjs-adk/google
+## Tools
+
+A tool is something the model can decide to call. In nestjs-adk a shared tool is a class that extends `AdkTool`. The Zod schema plays two roles at the same time: it tells the model what arguments exist, and it types the input for you:
+
+```ts
+import { Tool, AdkTool, type ToolContext } from "@nestjs-adk/core";
+import { z } from "zod";
+
+const schema = z.object({ city: z.string().describe("City name") });
+
+@Tool({ name: "get_weather", description: "Current weather.", schema })
+export class GetWeatherTool extends AdkTool<typeof schema> {
+	constructor(private readonly weather: WeatherService) {
+		super();
+	}
+
+	execute(input: z.infer<typeof schema>, ctx: ToolContext) {
+		return this.weather.fetch(input.city);
+	}
+}
+```
+
+The tool is a normal provider, so it can inject services, repositories or anything else. Whatever `execute` returns goes back to the model, as long as it is serializable.
+
+The `execute` method receives two very different things. The `input` comes from the model: it decided the values based on the schema. The `ctx` comes from your application: it carries `userId`, custom `attributes` and the session `state` that you passed to `ask()`. This separation matters for security. Sensitive data like a tenant id should never be part of the schema, because the model could invent it. Pass it through `ctx` instead, where the model cannot touch it.
+
+When a tool belongs to a single agent, you can skip the class and declare it as a method on the agent itself:
+
+```ts
+@Agent({ name: "support_agent", description: "Customer support.", prompt: "..." })
+export class SupportAgent extends AdkAgent {
+	constructor(private readonly orders: OrdersService) {
+		super();
+	}
+
+	@Tool({ description: "Looks up an order by id.", schema: orderSchema })
+	lookupOrder(input: z.infer<typeof orderSchema>) {
+		return this.orders.find(input.orderId);
+	}
+}
+```
+
+## Skills
+
+Skills are blocks of domain knowledge written as text. They exist so your prompt does not grow into one giant string. A skill can be a class that extends `AdkSkill` with the `@Skill` decorator, or a method on the agent.
+
+Each skill has a mode. With `mode: "always"` the content is included in the instruction on every run. The default mode is on demand: the agent only sees a catalog with the skill names and descriptions, plus a `load_skill` tool it can call when it decides it needs the full content. This keeps the context small while still making the knowledge available.
+
+## Prompts
+
+There are two ways to give an agent its instruction, and they are separate fields so the intent is always clear.
+
+The first way is directly on the decorator. Use `prompt` for literal text and `promptFile` for a markdown file:
+
+```ts
+@Agent({ name: "support", prompt: "You are the store's support agent." })
+
+@Agent({ name: "support", promptFile: "agents/support/main.prompt.md" })
+
+@Agent({ name: "support", promptFile: "./prompts/main.prompt.md" })
+```
+
+A plain `promptFile` path is resolved from the prompts directory that you configure in `forRoot({ prompts: { dir } })`. A path that starts with `./` is resolved relative to the agent's own file. Files are read once and cached in memory.
+
+The second way is a builder class, for prompts that need logic or data. Extend `AdkPrompt`, register it as a provider and point the `prompt` field at the class:
+
+```ts
+@Injectable()
+class SupportPrompt extends AdkPrompt {
+	constructor(private readonly config: SupportConfig) {
+		super();
+	}
+
+	build(ctx: PromptContext) {
+		return this.fromFile("agents/support/main.prompt.md", {
+			tone: this.config.tone,
+			plan: ctx.state.get("plan"),
+		});
+	}
+}
+
+@Agent({ name: "support", prompt: SupportPrompt })
+```
+
+The builder has full dependency injection and receives the run context, so it can read the state and the attributes you passed to `ask()`. The `fromFile` helper reads a cached template and fills `{{var}}` placeholders.
+
+Setting both `prompt` and `promptFile` on the same agent is an error at startup. One agent, one source of instruction.
+
+The final instruction is always composed in the same order: the prompt, then the `always` skills, then the on demand catalog. Because the order is stable, the prefix of your requests stays identical between runs, which lets the provider cache it.
+
+## Models
+
+The `model` field on `@Agent` and the `defaultModel` on `forRoot` accept a string or a model spec class. Specs are small objects that only carry configuration. The engine turns them into real clients:
+
+```ts
+model: "gemini-2.5-flash"
+
+model: new Gemini("gemini-2.5-flash", { labels, cache: { content }, config })
+
+model: new OpenAiLike("gpt-4o-mini", { baseUrl, apiKeyEnv })
+
+model: new ModelRouter({
+	targets: {
+		primary: new Gemini("gemini-2.5-flash"),
+		fallback: new OpenAiLike("gpt-4o-mini", { baseUrl: "https://openrouter.ai/api/v1" }),
+	},
+})
+```
+
+`OpenAiLike` covers every provider that speaks the OpenAI API, which includes OpenAI itself, OpenRouter, Ollama and many others. `Gemini` lives in `@nestjs-adk/google` and adds Vertex AI options, billing labels and explicit content caching.
+
+`ModelRouter` gives you failover in one line. When the current target fails before the first chunk of the response, for example with a 429, the router moves to the next target in the declared order. Every switch is reported as a `model_rerouted` event, so failovers are never silent. If you use a router as your `defaultModel`, you get global failover for the whole app.
+
+## Sessions
+
+Pass a `sessionId` to `ask()` and the conversation becomes persistent. The agent remembers previous turns because the framework stores every event and replays the history into the model's context on each run. Without a `sessionId` the session is ephemeral and nothing is kept.
+
+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.
+
+When a tool returns a very large result, above 20 thousand characters, the framework stores the full content as an artifact and gives the model a short summary plus a `read_artifact` tool. The model can read the full content when it really needs it. You can turn this off for a specific tool with `offload: false`.
+
+For long histories there is compaction. Configure a policy and old turns get summarized by an LLM when the history passes a token threshold:
+
+```ts
+context: contextPolicy({
+	compaction: { maxTokens: 50_000, keepRecent: 5 },
+})
 ```
 
-Full documentation: [github.com/gabrieljsilva/nestjs-adk](https://github.com/gabrieljsilva/nestjs-adk)
+You can set the policy globally in `forRoot` and override it per agent.
+
+## Human approval
+
+Some actions should not run without a person saying yes. Mark the tool:
+
+```ts
+@Tool({ name: "refund", description: "Refunds an order.", schema, requiresApproval: true })
+```
+
+`requiresApproval` also accepts a function of the input and the context, so you can require approval only above a value, for example.
+
+When the model calls a tool that requires approval, the tool does not execute. The run pauses and returns `status: "pending_approval"` with the pending call id. Your application shows this to a human, and then:
+
+```ts
+await agent.approve({ sessionId, callId }); // executes the tool and resumes the run
+await agent.reject({ sessionId, callId, reason }); // skips the tool and tells the model why
+```
+
+Both calls return a normal run result, so the conversation continues naturally after the decision.
+
+## Structured output
+
+When you need data instead of prose, declare an output schema:
+
+```ts
+@Agent({ name: "reporter", description: "Builds reports.", output: reportSchema, outputKey: "report" })
+class ReporterAgent extends AdkAgent<typeof reportSchema> {}
+
+const run = await reporter.ask({ message });
+run.output; // typed and validated
+```
+
+The result is parsed and validated with the schema. If the model produces something that does not match, you get an `OutputValidationError` instead of silently wrong data. The optional `outputKey` also writes the validated output into the session state, which is useful to pass data between agents in a pipeline.
+
+## Sub-agents and workflows
+
+An agent can delegate to other agents. With `subAgents: [OtherAgent]` the model itself decides when to transfer the conversation. When you want deterministic control instead, declare a workflow:
+
+```ts
+@WorkflowAgent({ name: "etl", mode: "sequential", agents: [ExtractAgent, SummarizeAgent] })
+class EtlWorkflow extends AdkWorkflow {}
+```
+
+Modes are `sequential`, `parallel` and `loop`. A workflow is also an agent: you inject the class and call `ask()` or `stream()` on the instance, exactly like before.
+
+## Streaming, events and errors
+
+`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`, `ModelsExhaustedError`, `AgentStateInvalidError` and `AgentMaxIterationsError`, so you can catch exactly what you care about.
+
+## Logs
+
+Turn on run logs in the module:
+
+```ts
+AdkModule.forRoot({ engine: GoogleAdkEngine, logging: "debug" })
+```
+
+Logs go through the normal Nest `Logger` with the context `Adk:<agent_name>`. Levels are cumulative. `"info"` (or `true`) logs the start and the end of each run with duration and token usage. `"debug"` adds tool calls and tool results. `"verbose"` adds intermediate model responses and stops truncating payloads. Reroutes and approval pauses are always logged as warnings.
+
+```
+run start session=smoke-1 user=u1 message=What's the status of my order 123?
+tool call lookup_order args={"orderId":"123"}
+tool result lookup_order result={"id":"123","status":"shipped"}
+run done in 1389ms text=Your order 123 has shipped. | tokens in=772 out=41 total=813
+```
+
+Token usage is also available programmatically on every result as `run.usage`.
+
+## Embeddings
+
+The core ships an `Embedder` contract with no default implementation, so you bring the provider you prefer. Configure it once with `forRoot({ embedder })` and inject `Embedder` wherever you need vectors, for semantic search or deduplication. The `Similarity` provider offers cosine similarity, and the testing package uses the same embedder for semantic assertions.
+
+## Testing
+
+Testing deserves its own package. [`@nestjs-adk/testing`](https://www.npmjs.com/package/@nestjs-adk/testing) gives you a scripted fake LLM, stackable mocks over the real agent instance, Vitest matchers and an LLM-as-judge helper. Your test setup stays plain `@nestjs/testing`.
+
+## Learn more
+
+The full project, with a working playground app and real AI smoke tests, lives at [github.com/gabrieljsilva/nestjs-adk](https://github.com/gabrieljsilva/nestjs-adk).

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.2",
+	"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,
@@ -31,5 +31,14 @@
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gabrieljsilva/nestjs-adk.git",
+		"directory": "packages/core"
+	},
+	"homepage": "https://github.com/gabrieljsilva/nestjs-adk#readme",
+	"bugs": {
+		"url": "https://github.com/gabrieljsilva/nestjs-adk/issues"
 	}
 }