Diagnostic codes

Every type-checker error and warning carries a stable AG#### code, and every agency lint finding carries a stable AL#### code. Look one up with agency explain <code> (e.g. agency explain AG2005), or suppress a type-checker one on the next line with // @tc-ignore AG####.

Types and aliases

Code	Message
AG1001	Type parameter '{param}' (no default) must come before parameters that have defaults in '{alias}'.
AG1002	Type '{alias}' is not a value-parameterized type but was given {count} value {argumentWord} (referenced in '{context}').
AG1003	{alias} expects at most {max} value {argumentWord}, got {count} (referenced in '{context}').
AG1004	'{alias}' is a value-parameterized type and requires value arguments — write '{alias}({formals})' (referenced in '{context}').
AG1005	{alias} requires at least {min} value {argumentWord} (referenced in '{context}').
AG1006	Type alias '{alias}' is not defined (referenced in '{context}').
AG1007	Generic type '{alias}' requires type arguments (referenced in '{context}').
AG1008	{alias} expects {expected} type {argumentWord}, got {count} (referenced in '{context}').
AG1009	Unknown generic type '{alias}' (referenced in '{context}').
AG1010	Type '{alias}' is not a generic type (referenced in '{context}').
AG1011	{alias} expects at most {max} type {argumentWord}, got {count} (referenced in '{context}').
AG1012	{alias} requires at least {min} type {argumentWord} (referenced in '{context}').
AG1013	{name} is not a type; {hint}

Assignability and checking

Code	Message
AG2001	Type '{actual}' is not assignable to type '{expected}' ({context}).
AG2002	Type '{actual}' is not assignable to type 'boolean' (condition).
AG2003	Unknown property '{key}' on type '{expected}' ({context}).
AG2004	Variable '{name}' has no type annotation (strict mode).
AG2005	Type '{actual}' is not assignable to type '{expected}'.
AG2006	For-loop iterable must be an array or Record, got '{actual}'.
AG2007	{kind} '{name}' has validated parameters but its return type is not a Result type. Validated parameters can short-circuit with a failure, so the return type must be 'Result<...>'.
AG2008	Property '{field}' is not available on every member of '{union}'; narrow the value (e.g. with a guard) before accessing it.
AG2009	'.{field}' is only available on a {branch} Result; guard with 'if (isSuccess(r))' / 'if (isFailure(r))', use 'r catch …', or 'match (r) { … }'.
AG2010	Cannot {op} values of different dimensions ({leftDim} and {rightDim}): '{left}' and '{right}'.
AG2011	Property '{property}' does not exist on type '{type}'.
AG2012	Not all code paths return a value in '{fn}'.

Interrupts, effects, and handlers

Code	Message
AG3001	The '!' validation syntax is not allowed on handler parameters. Validate the data inside the handler body if needed.
AG3002	Effect '{effect}' is declared more than once in the same file.
AG3003	Conflicting payload types for effect '{effect}'. All declarations of an effect must agree on its payload.
AG3004	Named arguments are not allowed on 'raise'/'interrupt'. Pass the data positionally.
AG3005	Effect '{effect}' expects data {payload}, but none was supplied.
AG3006	Effect '{effect}' data field '{field}' is missing.
AG3007	Effect '{effect}' data field '{field}' has the wrong type.
AG3008	Effect '{effect}' data does not match the declared {payload}.
AG3009	Function '{fn}' may throw interrupts [{effects}] but is not inside a handler.
AG3011	interrupt is not allowed inside a callback body (callback registered on '{hook}' may raise [{effects}]). Callbacks fire as side effects; their body cannot pause execution to ask the user a question. Move the interrupt into the calling node/function instead, or use a runtime guard if you wanted budget enforcement.
AG3012	'raises {ref}' is not an effect set. Declare '{ref}' with 'effectSet' (not 'type'), or use an inline set like '<...>'.
AG3013	{kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. Add '{effect}' to the clause.
AG3014	{who} may raise any effect (its type has no 'raises' clause), which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add a 'raises' clause to the value's type.
AG3015	{who} raises effect '{effect}', which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add '{effect}' to the clause, or use a target type that allows it.
AG3016	'{callee}' can interrupt, and a finalize block cannot contain interrupts. A finalize runs while its scope shuts down, so there is nothing to resume.
AG3017	Cannot use {kind} at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait — move it inside a node or a function.
AG3018	A handler cannot be registered at the top level of a file. Handlers must be inside a node or a function, where there is execution for them to guard.

Names, scope, and reserved words

Code	Message
AG4001	'{name}' shadows an imported function.
AG4002	'{name}' is a reserved built-in; cannot be redefined.
AG4003	'{name}' is a reserved built-in type; cannot be redefined.
AG4004	Function '{name}' is not defined.
AG4005	Cannot reassign to constant '{name}'.
AG4006	{keyword} is a reserved block keyword. Write {keyword} { ... } or {keyword}(args) { ... } directly — the as keyword is not supported on {keyword} blocks (there's nothing to bind).
AG4007	Variable '{name}' is not defined.
AG4008	'{name}' is not defined in '{module}'.
AG4009	Cannot find module '{module}'.
AG4010	'{name}' is defined in '{module}' but is not exported. Add the 'export' keyword to its definition.

Match and narrowing

Code	Message
AG5002	match is not exhaustive: missing {missing}.
AG5003	{name} here binds the value; it does not test the type. Did you mean p: {name} or is {name}?

Calls, tools, and LLM usage

Code	Message
AG6001	'regex' cannot appear in an llm() structured-output type ({context}); LLMs can't return regex values through JSON.
AG6002	Cannot interpolate parameter '{param}' in doc string — parameter values are not known when the tool description is sent to the LLM. Use a global variable instead.
AG6003	.partial() requires named arguments, e.g. fn.partial(a: 5).
AG6004	Unknown parameter '{name}' in .partial() call. '{fn}' has parameters: {params}.
AG6005	Argument type '{actual}' is not assignable to parameter type '{expected}' in .partial() call to '{fn}'.
AG6006	Named arguments are not supported on built-in method '.{method}()'.
AG6007	Method '.{method}()' expects {expected} argument(s), got {count}.
AG6008	Method '.{method}()' expects at least {min} argument(s), got {count}.
AG6009	Method '.{method}()' expects {min}–{max} argument(s), got {count}.
AG6010	Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '.{method}()'.
AG6011	Named arguments can only be used with Agency-defined functions, not '{fn}'.
AG6012	'{fn}' does not accept the named argument '{name}'. Allowed: {allowed}.
AG6013	Duplicate named argument '{name}' in call to '{fn}'.
AG6014	Named argument '{name}' on '{fn}' expects type '{expected}', got '{actual}'.
AG6015	'{fn}' does not accept a block argument.
AG6016	Expected {expected} argument(s) for '{fn}', but got {count}.
AG6017	Expected at least {min} argument(s) for '{fn}', but got {count}.
AG6018	Expected {min}-{max} argument(s) for '{fn}', but got {count}.
AG6019	Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'.
AG6020	Splat argument must be an array, got '{actual}' in call to '{fn}'.
AG6021	Splat element type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'.
AG6022	Type '{actual}' is not assignable to pipe slot of type '{expected}'.
AG6023	Splat argument cannot follow a named argument in call to '{fn}'.
AG6024	Positional argument cannot follow a named argument in call to '{fn}'.
AG6025	Unknown named argument '{name}' in call to '{fn}'.
AG6026	Named argument '{name}' conflicts with positional argument at position {position} in call to '{fn}'.
AG6027	Positional argument cannot feed variadic parameter '{param}' when it is also bound by name in call to '{fn}'.
AG6028	Tool '{tool}' has required function-typed parameter '{param}' is unbound. Bind it with .partial({param}: <value>) before passing as a tool.
AG6029	Tool '{tool}' has required function-typed parameter '{param}' is unbound ({type}). Bind it with .partial({param}: <value>) before passing as a tool.
AG6030	Tool '{tool}' will be exposed to the LLM without optional function-typed parameter(s): {params}. The function body must be prepared to run with the declared default for each.
AG6031	saveDraft() cannot be called at module top level — there is no enclosing function, node, or block scope to save a draft for.
AG6032	A scope can declare at most one finalize block. Combine the logic into one block.
AG6033	A finalize block cannot go inside {construct}. Declare it at the top level of the function or block body. A finalize is always active, so nesting it in control flow has no meaning.
AG6034	saveDraft() has no effect inside a finalize block. The value the finalize returns is already the partial result. Return the value instead.
AG6035	A finalize block cannot go in a node body. Nothing above a node consumes a partial result yet. Put the finalize in a function or a guard block instead.
AG6036	This scope has a finalize block, so a return expression cannot bury a call inside a bigger expression. If the call were stopped, the expression would consume its partial result before the finalize could run. Assign the call to a local first, then return the local.
AG6037	finalize binder '{name}' collides with a variable that already exists in this scope. Pick a fresh name. The finalize body reads the scope's locals directly, so a colliding binder would silently shadow the local.
AG6038	finalize yields a single value — the scope's saved draft. Use one binder: finalize as {name} { ... }.
AG6039	Parameter '{name}' on '{fn}' has no default but comes after a defaulted parameter. Put defaulted parameters last, so an omitted argument is always a trailing one.

Static init, config, and imports

Code	Message
AG7001	Only 'static const' declarations can be exported. Use 'export static const {name} = ...' instead.
AG7002	{contextLabel} cannot call {builtin}(...) — {reason}, but static initializers run once at process startup before any per-run state exists. Move this call into a node or a function called from a node.
AG7003	{contextLabel} cannot interrupt(...) — interrupts pause the per-run execution stack, but static initializers run once at process startup before any agent run has begun. Move this into a node body.
AG7004	Cannot reassign static {name} at module top level — statics are immutable after initialization. Use a global (const/let without static) if you need a mutable value.
AG7005	Cannot mutate static {name} via .{method}(...) at module top level — statics are deep-frozen after initialization. Use a global (const/let without static) if you need a mutable value.
AG7006	Function '{name}' cannot be both destructive and idempotent — those markers are contradictory. Pick one.

Code templates and holes

Code	Message
AG8001	This file is a template with unfilled holes ({names}) and cannot be run directly. Load it with loadTemplate and fill it first.
AG8002	The hole #{name} is in a position that gives it no expected type. Annotate it, for example #{name}: string.
AG8003	Generator '{name}' may raise {effects}, so it cannot run at compile time. Compilation installs no interrupt handlers, so those operations could not complete anyway. Move the effectful work out of the generator.
AG8004	Generator '{name}' cannot be checked for effects: {reason}. An empty effect list from an incomplete reading means nothing, so it is refused rather than run.
AG8005	{name} must be imported from another file to be used in a splice. A generator cannot be defined in the file that splices it, because it has to be compiled first.
AG8006	The generator {name} reaches non-Agency code through {importPath}. Compile-time generators may import only std:: modules and relative .agency files, because JavaScript raises no interrupts and cannot be checked. Set allowNonAgencyGenerators in your config to permit it.
AG8007	The generator {name} returned a {actual} fragment, but this splice is in {position} position and needs a {expected} fragment.
AG8008	The generator {name} failed while running: {reason}
AG8009	A generator module cannot itself contain a splice. Move the inner generation into a separate module.
AG8010	Generated code refers to {name}, which it neither declares nor imports. Generated code may use only names it declares itself and names it imports.
AG8011	The splice argument {name} is declared in this file, so it does not exist yet when the generator runs. Splice arguments may be literals, code literals, or imported names.
AG8012	The generator {name} declares {declared}, which this file already declares. Generated declarations may not replace existing ones.
AG8013	The generator {name} produced an exported declaration ({declared}). Generated declarations cannot be exported yet, because other files resolve imports without running generators. Remove the export.
AG8014	The generator {name} returned {kind}, which cannot sit at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait.
AG8015	{name} is not defined in this template. A template can only use names it declares or imports itself, because a hole hides whatever fills it. Move the code that defines {name} into this template, or move the code that uses it into the fragment that defines it.

Lint

Code	Message
AL0001	'{name}' is imported but never used.
AL0002	'{name}' is exported but has no docstring.
AL0003	'{name}' is already available without an import.