loom.ai.errors¶

Agent compilation and run-time error codes.

Two disjoint catalogues, mirroring loom.streaming.compiler._errors:

AgentErrorCode: Compile-time failures. A broken artifact or an unresolvable deployment produces one or more AgentCompilationIssue, and AgentCompilationError aggregates them so a single run reports every problem at once.
AgentRunErrorCode: Execution outcomes. Each code belongs to an AgentRunErrorClass and the retry policy reads the class, never the message (FR-028).

Every code has a dedicated factory function so call-sites stay intention-revealing and free of string formatting.

Issue factories: The factories below share one contract, stated here once rather than repeated on each of them. Every factory returns a single AgentCompilationIssue carrying its own AgentErrorCode. component names the artifact component or configuration path the issue is attributed to — "market", "ai.mcp_servers.data". Every other parameter is interpolated into the human-readable message and is never read for control flow: callers branch on the code, never on the text. Messages never carry secret material — in credential-related issues the offending value is deliberately omitted.

Module Attributes

`INVOKER_MISSING_REASON`	the deps bundle carries no invoker.
`CONVERSATION_LOAD_FAILED_MESSAGE`	Client text of every `CONVERSATION_LOAD_FAILED` error (D8).
`CONVERSATION_LOAD_TIMEOUT_MESSAGE`	Client text of every `CONVERSATION_LOAD_TIMEOUT` error (FR-063).

Functions

`a2a_agent_unknown`(component, agent)	An `a2a` capability names a remote agent that is not configured.
`a2a_agent_unreachable`(agent, reason)	A remote agent's card cannot be retrieved.
`a2a_base_url_invalid`(url, reason)	Report an `ai.a2a.base_url` that is unsafe to publish.
`a2a_expose_empty`()	A2A exposure was enabled without naming a single agent.
`a2a_url_invalid`(component, url, reason)	A remote agent URL is malformed, not `https://`, or carries credentials.
`agent_marker_output_mismatch`(usecase, ...)	A use case's `AgentHandle` annotation disagrees with the named agent's own declared output type.
`agent_marker_unknown`(usecase, parameter, ...)	A use case's `Agent()` marker names an agent no engine compiled.
`agent_name_duplicate`(name, sources)	Two artifacts in the same application declare the same agent name.
`agent_name_invalid`(component, reason)	The agent name does not satisfy the published name pattern.
`agent_specs_conflict`()	Both artifact sources declare agents; there is no implicit precedence.
`agent_specs_missing`()	The `ai:` section is configured but no artifact source declares agents.
`anonymous_with_data_capability`(component, kind)	An unauthenticated agent holds a data or remote capability.
`auth_exclusion_overlaps_agents`(paths)	An authentication exclusion covers an agent or A2A invocation path.
`capability_empty`(component, kind)	A capability entry grants nothing at all.
`capability_kind_unsupported`(component, kind, ...)	The configured engine does not serve this capability kind.
`conversation_input_unsatisfied`(component, ...)	The loader cannot build the use case's Input from the run context.
`conversation_invoker_missing`(agents, *[, reason])	Agents declare a conversation loader but the deployment has no usable use-case invoker.
`conversation_usecase_also_granted`(component, key)	The loader's use case is also granted to the model as a capability.
`conversation_usecase_unknown`(component, key)	The conversation loader names a use-case key absent from the registry.
`endpoint_auth_missing`(component)	An agent opted into HTTP exposure without naming its authentication.
`engine_api_mismatch`(name, found, supported)	An engine announces a handshake version this release cannot speak.
`engine_duplicate`(name, distributions)	Two distributions claim the same engine entry-point name.
`engine_not_found`(name, available)	No installed entry point provides the requested engine.
`from_message`(message)	Wrap a bare string as an `AgentErrorCode.UNSPECIFIED` issue.
`inference_target_incomplete`(role, setting)	A model-role binding lacks a setting its provider requires.
`instruction_block_invalid`(component, reason)	An authored instruction block violates a compile-time rule.
`is_retriable`(code)	Return whether a run-time failure may be retried by the caller.
`max_agent_depth_invalid`(value)	The nesting bound is below the one entry every top-level run already spends.
`mcp_auth_conflict`(component)	A server sets both `headers_ref` and `auth`, two credentials for one connection.
`mcp_auth_strategy_invalid`(kind, reason)	A registered auth strategy could not be constructed, or is unusable.
`mcp_auth_strategy_unknown`(component, kind, ...)	A named auth strategy resolves to no entry point in `loom.ai.remote_auth`.
`mcp_connection_conflict`(server, agents)	One MCP server name resolves to two different connections in one worker.
`mcp_credentials_inline`(component, field)	Credentials were written into the artifact instead of being referenced.
`mcp_headers_ref_invalid`(component)	A resolved `headers_ref` payload is not one `Name=value` header pair.
`mcp_marker_unknown`(usecase, parameter, ...)	A use case's `Mcp()` marker names a server no engine compiled.
`mcp_server_unknown`(component, server)	An `mcp` capability names a server that is not configured.
`mcp_server_unreachable`(server, reason)	An MCP server is not reachable at start-up.
`mcp_transport_invalid`(component, reason, *)	An MCP server declares fields that its `transport` does not accept, or an unknown one.
`mcp_url_invalid`(component, url, reason)	An MCP server URL is malformed, not `https://`, or carries credentials.
`model_role_unbound`(component, role)	The agent's model role is not present in `ai.models`.
`native_tool_duplicate`(component, tool)	The same provider tool is granted twice to one agent.
`native_tool_unsupported`(component, *, tool, ...)	The model bound to this role cannot run the requested provider tool.
`on_output_input_unsatisfied`(component, key, ...)	The hook cannot build the use case's Input from the run context and output.
`on_output_invoker_missing`(agents, *[, reason])	Agents declare an output hook but the deployment has no usable use-case invoker.
`on_output_usecase_also_granted`(component, key)	The hook's use case is also granted to the model as a capability.
`on_output_usecase_unknown`(component, key)	The output hook names a use-case key absent from the registry.
`output_check_unresolvable`(component, ref)	The `module:symbol` output check reference cannot be imported.
`output_mode_unknown`(role, value, valid)	A model-role binding names an `output_mode` loom does not offer.
`output_schema_invalid`(component, reason)	The declared output schema is not a valid JSON Schema object.
`output_type_ref_unresolvable`(component, ref)	The `module:Symbol` output reference cannot be imported.
`output_type_ref_unsupported`(component, ref, ...)	The output reference resolves to a type the engine cannot use.
`policy_out_of_range`(component, policy, ...)	A policy value falls outside its documented range.
`provider_not_installed`(provider, extra)	A provider SDK is missing; the message names the extra to install.
`provider_setting_missing`(provider, setting)	A provider setting (credentials, region, endpoint) is absent.
`provider_unknown`(provider, supported)	The provider is not one this release knows how to bind.
`python_factory_failed`(component, factory, error)	A `python` factory raised while building its toolset at start-up.
`python_factory_not_callable`(component, factory)	A `python` capability factory does not satisfy `ToolsetFactory`.
`python_factory_params_rejected`(component, ...)	A `python` capability's `params` do not bind to the factory's signature.
`python_factory_unresolvable`(component, ...)	A `python` capability factory cannot be imported.
`python_remote_not_granted`(component, ...)	A `python` factory asked for an MCP server its agent was not granted.
`remote_clients_unknown`(value, valid)	The start-up tolerance of remote clients names no known mode.
`run_error_class`(code)	Return the failure class of a run-time error code.
`skills_library_escapes`(component, library)	A skill library resolves outside the directory it is anchored to.
`skills_library_invalid`(component, library, ...)	A skill library does not resolve to a readable library directory.
`skills_name_collision`(component, skill, ...)	Two libraries granted to one agent expose the same skill name.
`skills_root_missing`(component)	A bare skill library was named with no `skills_root` configured.
`spec_malformed`(component, reason[, field])	The artifact is not decodable as the version it declares.
`spec_unknown_field`(component, field)	An unrecognised field appeared in the artifact; it is never ignored.
`spec_version_deprecated`(component, found, latest)	The artifact's version is still accepted but has been superseded.
`spec_version_missing`(component)	An artifact declares no `spec_version`, so it cannot be routed.
`spec_version_unsupported`(component, found, ...)	The declared spec version is not understood by this release.
`sql_config_missing`(component)	A `sql` capability was declared with no data-layer config to validate.
`sql_connection_not_readonly`(component, ...)	A `sql` capability names a connection that permits writes.
`sql_connection_roles_unbound`(component, ...)	The connection's roles cannot be bound to a caller identity.
`sql_connection_unknown`(component, connection)	A `sql` capability names a connection that is not configured.
`sql_readonly_drift`(connection)	Live configuration contradicts the plan's read-only assumption.
`sql_result_bound_missing`(component, connection)	A `sql` capability declares no result bounds.
`state_declaration_conflict`(component)	Both `deps_type` and `deps_schema` are declared; only one may be.
`state_schema_invalid`(component, reason)	The declared state schema is not a valid JSON Schema object.
`state_surface_unsupported`(component, surface)	A stateful artifact is exposed over a run surface that carries no state.
`state_type_ref_unresolvable`(component, ref)	The `module:Symbol` state reference cannot be imported.
`state_type_ref_unsupported`(component, ref, ...)	The state reference resolves to a symbol no schema can be derived from.
`template_compilation_failed`(component, ...)	A templated instruction block fails to compile against its declared state.
`template_extra_missing`(component, block, extra)	A block declares `template:` while the templating extra is not installed.
`tool_filter_matches_nothing`(component, target)	An include/exclude filter excludes every tool the target exposes.
`use_case_tool_filter_matches_nothing`(...)	A use case's `Mcp()` `include` matches no tool the named server publishes.
`usecase_key_unknown`(component, key)	A granted use-case key is absent from the use-case registry.

Classes

`AgentCompilationIssue`(*, code, message[, ...])	One structured agent compilation failure.
`AgentErrorCode`(value)	Enumeration of all agent compile-time failure codes.
`AgentRunErrorClass`(value)	Class of a run-time failure; the retry policy reads this, not the message.
`AgentRunErrorCode`(value)	Enumeration of all agent run-time failure codes.

Exceptions

`AgentCompilationError`(issues)	Raised when one or more agent artifacts fail to compile.
`AgentRunError`(code, message, *[, ...])	A run failed with a stable, machine-readable code.

class loom.ai.errors.AgentErrorCode(value)[source]¶

Bases: StrEnum

Enumeration of all agent compile-time failure codes.

class loom.ai.errors.AgentCompilationIssue(*, code, message, component='', field=None)[source]¶

Bases: LoomFrozenStruct

One structured agent compilation failure.

Parameters:

code (AgentErrorCode) – Machine-readable AgentErrorCode.
message (str) – Human-readable description; the aggregated exception text is built from these messages.
component (str) – Artifact, agent or config section the issue points at (for example "agents/triage.agent.yaml").
field (str | None) – Optional field path involved (for example "capabilities[0].url").

loom.ai.errors.from_message(message)[source]¶

Wrap a bare string as an AgentErrorCode.UNSPECIFIED issue.

Parameters:: message (str)
Return type:: AgentCompilationIssue

exception loom.ai.errors.AgentCompilationError(issues)[source]¶

Bases: Exception

Raised when one or more agent artifacts fail to compile.

Aggregates every AgentCompilationIssue found in a compilation run so a generator sees the whole picture instead of one failure at a time.

issues¶: Structured issues, one per failure.

Parameters:: issues (tuple[AgentCompilationIssue, ...]) – Issues (or bare message strings) collected by the compiler. Strings are normalised through from_message().
Return type:: None

loom.ai.errors.spec_version_missing(component)[source]¶

An artifact declares no spec_version, so it cannot be routed.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.spec_version_unsupported(component, found, supported)[source]¶

The declared spec version is not understood by this release.

Parameters:

component (str)
found (int)
supported (Sequence[int])

Return type:

AgentCompilationIssue

loom.ai.errors.spec_unknown_field(component, field)[source]¶

An unrecognised field appeared in the artifact; it is never ignored.

Parameters:

component (str)
field (str)

Return type:

AgentCompilationIssue

loom.ai.errors.spec_malformed(component, reason, field=None)[source]¶

The artifact is not decodable as the version it declares.

Parameters:

component (str)
reason (str)
field (str | None)

Return type:

AgentCompilationIssue

loom.ai.errors.agent_name_invalid(component, reason)[source]¶

The agent name does not satisfy the published name pattern.

Parameters:

component (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.agent_name_duplicate(name, sources)[source]¶

Two artifacts in the same application declare the same agent name.

Parameters:

name (str) – The duplicated agent name.
sources (Sequence[str]) – Artifact paths that declare it, one entry per occurrence.

Return type:

AgentCompilationIssue

loom.ai.errors.output_schema_invalid(component, reason)[source]¶

The declared output schema is not a valid JSON Schema object.

Parameters:

component (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.output_type_ref_unresolvable(component, ref)[source]¶

The module:Symbol output reference cannot be imported.

Parameters:

component (str)
ref (str)

Return type:

AgentCompilationIssue

loom.ai.errors.output_type_ref_unsupported(component, ref, reason)[source]¶

The output reference resolves to a type the engine cannot use.

Parameters:

component (str)
ref (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.output_check_unresolvable(component, ref)[source]¶

The module:symbol output check reference cannot be imported.

Parameters:

component (str)
ref (str)

Return type:

AgentCompilationIssue

loom.ai.errors.on_output_usecase_unknown(component, key)[source]¶

The output hook names a use-case key absent from the registry.

Parameters:

component (str)
key (str)

Return type:

AgentCompilationIssue

loom.ai.errors.on_output_input_unsatisfied(component, key, reason)[source]¶

The hook cannot build the use case’s Input from the run context and output.

Parameters:

component (str)
key (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.on_output_usecase_also_granted(component, key)[source]¶

The hook’s use case is also granted to the model as a capability.

Parameters:

component (str)
key (str)

Return type:

AgentCompilationIssue

loom.ai.errors.INVOKER_MISSING_REASON: Final[str] = 'no use-case invoker is configured'¶

the deps bundle carries no invoker.

Type:: Default reason of the invoker-missing issues

loom.ai.errors.on_output_invoker_missing(agents, *, reason=INVOKER_MISSING_REASON)[source]¶

Agents declare an output hook but the deployment has no usable use-case invoker.

Parameters:

agents (Sequence[str]) – Names of the agents declaring a hook.
reason (str) – What is wrong with the invoker, when it is not simply absent.

Return type:

AgentCompilationIssue

loom.ai.errors.conversation_usecase_unknown(component, key)[source]¶

The conversation loader names a use-case key absent from the registry.

Parameters:

component (str)
key (str)

Return type:

AgentCompilationIssue

loom.ai.errors.conversation_input_unsatisfied(component, key, reason)[source]¶

The loader cannot build the use case’s Input from the run context.

Parameters:

component (str)
key (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.conversation_usecase_also_granted(component, key)[source]¶

The loader’s use case is also granted to the model as a capability.

Parameters:

component (str)
key (str)

Return type:

AgentCompilationIssue

loom.ai.errors.conversation_invoker_missing(agents, *, reason=INVOKER_MISSING_REASON)[source]¶

Agents declare a conversation loader but the deployment has no usable use-case invoker.

Parameters:

agents (Sequence[str]) – Names of the agents declaring a loader.
reason (str) – What is wrong with the invoker, when it is not simply absent.

Return type:

AgentCompilationIssue

loom.ai.errors.state_declaration_conflict(component)[source]¶

Both deps_type and deps_schema are declared; only one may be.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.state_type_ref_unresolvable(component, ref)[source]¶

The module:Symbol state reference cannot be imported.

Parameters:

component (str)
ref (str)

Return type:

AgentCompilationIssue

loom.ai.errors.state_type_ref_unsupported(component, ref, reason)[source]¶

The state reference resolves to a symbol no schema can be derived from.

Parameters:

component (str)
ref (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.state_schema_invalid(component, reason)[source]¶

The declared state schema is not a valid JSON Schema object.

Parameters:

component (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.state_surface_unsupported(component, surface)[source]¶

A stateful artifact is exposed over a run surface that carries no state.

Parameters:

component (str)
surface (str)

Return type:

AgentCompilationIssue

loom.ai.errors.instruction_block_invalid(component, reason)[source]¶

An authored instruction block violates a compile-time rule.

Parameters:

component (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.template_compilation_failed(component, block, reason)[source]¶

A templated instruction block fails to compile against its declared state.

Parameters:

component (str) – Artifact the block belongs to.
block (str) – The block’s name, or its position when it has none.
reason (str) – The template checker’s own message, interpolated verbatim. A compilation error can carry a fragment of the source template, so redacting it — if the caller needs that — is the caller’s responsibility, not this factory’s.

Return type:

AgentCompilationIssue

loom.ai.errors.template_extra_missing(component, block, extra)[source]¶

A block declares template: while the templating extra is not installed.

Parameters:

component (str) – Artifact the block belongs to.
block (str) – The block’s name, or its position when it has none.
extra (str) – The optional dependency extra that installs the templating engine.

Return type:

AgentCompilationIssue

loom.ai.errors.capability_kind_unsupported(component, kind, engine)[source]¶

The configured engine does not serve this capability kind.

Parameters:

component (str)
kind (str)
engine (str)

Return type:

AgentCompilationIssue

loom.ai.errors.native_tool_unsupported(component, *, tool, role, provider, model, supported)[source]¶

The model bound to this role cannot run the requested provider tool.

Parameters:

component (str)
tool (str)
role (str)
provider (str)
model (str)
supported (Sequence[str])

Return type:

AgentCompilationIssue

loom.ai.errors.native_tool_duplicate(component, tool)[source]¶

The same provider tool is granted twice to one agent.

Parameters:

component (str)
tool (str)

Return type:

AgentCompilationIssue

loom.ai.errors.capability_empty(component, kind)[source]¶

A capability entry grants nothing at all.

Parameters:

component (str)
kind (str)

Return type:

AgentCompilationIssue

loom.ai.errors.usecase_key_unknown(component, key)[source]¶

A granted use-case key is absent from the use-case registry.

Parameters:

component (str)
key (str)

Return type:

AgentCompilationIssue

loom.ai.errors.sql_connection_unknown(component, connection)[source]¶

A sql capability names a connection that is not configured.

Parameters:

component (str)
connection (str)

Return type:

AgentCompilationIssue

loom.ai.errors.sql_connection_not_readonly(component, connection)[source]¶

A sql capability names a connection that permits writes.

Parameters:

component (str)
connection (str)

Return type:

AgentCompilationIssue

loom.ai.errors.sql_config_missing(component)[source]¶

A sql capability was declared with no data-layer config to validate.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.sql_connection_roles_unbound(component, connection)[source]¶

The connection’s roles cannot be bound to a caller identity.

Parameters:

component (str)
connection (str)

Return type:

AgentCompilationIssue

loom.ai.errors.sql_result_bound_missing(component, connection)[source]¶

A sql capability declares no result bounds.

Parameters:

component (str)
connection (str)

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_server_unknown(component, server)[source]¶

An mcp capability names a server that is not configured.

Parameters:

component (str)
server (str)

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_url_invalid(component, url, reason)[source]¶

An MCP server URL is malformed, not https://, or carries credentials.

Parameters:

component (str)
url (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_credentials_inline(component, field)[source]¶

Credentials were written into the artifact instead of being referenced.

Parameters:

component (str)
field (str)

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_headers_ref_invalid(component)[source]¶

A resolved headers_ref payload is not one Name=value header pair.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.mcp_auth_conflict(component)[source]¶

A server sets both headers_ref and auth, two credentials for one connection.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.mcp_transport_invalid(component, reason, *, field='transport')[source]¶

An MCP server declares fields that its transport does not accept, or an unknown one.

Parameters:

component (str) – Configuration entry the issue points at.
reason (str) – What about the transport is invalid.
field (str) – Configuration key to blame; the transport itself unless a nested key, such as one env name, is the culprit.

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_auth_strategy_unknown(component, kind, available)[source]¶

A named auth strategy resolves to no entry point in loom.ai.remote_auth.

Parameters:

component (str)
kind (str)
available (Sequence[str])

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_auth_strategy_invalid(kind, reason)[source]¶

A registered auth strategy could not be constructed, or is unusable.

Parameters:

kind (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.skills_library_invalid(component, library, reason)[source]¶

A skill library does not resolve to a readable library directory.

Parameters:

component (str)
library (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.skills_library_escapes(component, library)[source]¶

A skill library resolves outside the directory it is anchored to.

Parameters:

component (str)
library (str)

Return type:

AgentCompilationIssue

loom.ai.errors.skills_name_collision(component, skill, first_library, second_library)[source]¶

Two libraries granted to one agent expose the same skill name.

Parameters:

component (str)
skill (str)
first_library (str)
second_library (str)

Return type:

AgentCompilationIssue

loom.ai.errors.skills_root_missing(component)[source]¶

A bare skill library was named with no skills_root configured.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.python_factory_unresolvable(component, factory, reason)[source]¶

A python capability factory cannot be imported.

Parameters:

component (str)
factory (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.python_factory_not_callable(component, factory)[source]¶

A python capability factory does not satisfy ToolsetFactory.

Parameters:

component (str)
factory (str)

Return type:

AgentCompilationIssue

loom.ai.errors.python_factory_params_rejected(component, factory, reason)[source]¶

A python capability’s params do not bind to the factory’s signature.

Parameters:

component (str)
factory (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.python_remote_not_granted(component, factory, server)[source]¶

A python factory asked for an MCP server its agent was not granted.

Parameters:

component (str)
factory (str)
server (str)

Return type:

AgentCompilationIssue

loom.ai.errors.python_factory_failed(component, factory, error)[source]¶

A python factory raised while building its toolset at start-up.

Only the exception class is named: the message could carry a params value or anything else the factory touched.

Parameters:

component (str)
factory (str)
error (str)

Return type:

AgentCompilationIssue

loom.ai.errors.a2a_agent_unknown(component, agent)[source]¶

An a2a capability names a remote agent that is not configured.

Parameters:

component (str)
agent (str)

Return type:

AgentCompilationIssue

loom.ai.errors.a2a_url_invalid(component, url, reason)[source]¶

A remote agent URL is malformed, not https://, or carries credentials.

Parameters:

component (str)
url (str)
reason (str)

Return type:

AgentCompilationIssue

loom.ai.errors.anonymous_with_data_capability(component, kind)[source]¶

An unauthenticated agent holds a data or remote capability.

Parameters:

component (str)
kind (str)

Return type:

AgentCompilationIssue

loom.ai.errors.model_role_unbound(component, role)[source]¶

The agent’s model role is not present in ai.models.

Parameters:

component (str)
role (str)

Return type:

AgentCompilationIssue

loom.ai.errors.inference_target_incomplete(role, setting)[source]¶

A model-role binding lacks a setting its provider requires.

Parameters:

role (str)
setting (str)

Return type:

AgentCompilationIssue

loom.ai.errors.output_mode_unknown(role, value, valid)[source]¶

A model-role binding names an output_mode loom does not offer.

The valid set is a parameter, as in every sibling factory that names one: it keeps this module free of domain imports.

Parameters:

role (str)
value (str)
valid (Sequence[str])

Return type:

AgentCompilationIssue

loom.ai.errors.policy_out_of_range(component, policy, value, minimum, maximum)[source]¶

A policy value falls outside its documented range.

value, minimum and maximum accept Decimal as well as int: every policy value is an integer count except max_usd, which is a Decimal (FR-043), and the two share this one factory rather than each carrying its own near-identical message.

Parameters:

component (str)
policy (str)
value (int | Decimal)
minimum (int | Decimal)
maximum (int | Decimal)

Return type:

AgentCompilationIssue

loom.ai.errors.engine_not_found(name, available)[source]¶

No installed entry point provides the requested engine.

Parameters:

name (str)
available (Sequence[str])

Return type:

AgentCompilationIssue

loom.ai.errors.engine_duplicate(name, distributions)[source]¶

Two distributions claim the same engine entry-point name.

Parameters:

name (str)
distributions (Sequence[str])

Return type:

AgentCompilationIssue

loom.ai.errors.engine_api_mismatch(name, found, supported)[source]¶

An engine announces a handshake version this release cannot speak.

Parameters:

name (str)
found (int)
supported (Sequence[int])

Return type:

AgentCompilationIssue

loom.ai.errors.provider_not_installed(provider, extra)[source]¶

A provider SDK is missing; the message names the extra to install.

Parameters:

provider (str)
extra (str)

Return type:

AgentCompilationIssue

loom.ai.errors.provider_unknown(provider, supported)[source]¶

The provider is not one this release knows how to bind.

Distinct from PROVIDER_NOT_INSTALLED: there is no extra to install, because no such provider exists in this release.

Parameters:

provider (str) – Provider identifier the artifact named.
supported (Sequence[str]) – Provider identifiers this release binds.

Return type:

AgentCompilationIssue

loom.ai.errors.provider_setting_missing(provider, setting)[source]¶

A provider setting (credentials, region, endpoint) is absent.

Parameters:

provider (str)
setting (str)

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_connection_conflict(server, agents)[source]¶

One MCP server name resolves to two different connections in one worker.

Parameters:

server (str) – The registered server name, never its URL — a URL carries credentials and hosts the redaction guarantee keeps out of diagnostics (FR-030a/FR-038).
agents (Sequence[str]) – Names of the two agents whose grants disagree, in plan order.

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_server_unreachable(server, reason)[source]¶

An MCP server is not reachable at start-up.

Parameters:

server (str) – The server’s registered name, never its URL — a URL carries credentials and hosts that the redaction guarantee keeps out of diagnostics (FR-030a/FR-038).
reason (str) – Why the connection did not complete.

Return type:

AgentCompilationIssue

loom.ai.errors.tool_filter_matches_nothing(component, target)[source]¶

An include/exclude filter excludes every tool the target exposes.

Parameters:

component (str)
target (str)

Return type:

AgentCompilationIssue

loom.ai.errors.sql_readonly_drift(connection)[source]¶

Live configuration contradicts the plan’s read-only assumption.

Parameters:: connection (str)
Return type:: AgentCompilationIssue

loom.ai.errors.endpoint_auth_missing(component)[source]¶

An agent opted into HTTP exposure without naming its authentication.

Parameters:: component (str)
Return type:: AgentCompilationIssue

loom.ai.errors.a2a_base_url_invalid(url, reason)[source]¶

Report an ai.a2a.base_url that is unsafe to publish.

Parameters:

url (str) – The offending URL, already redacted of userinfo and query.
reason (str) – Why it is unsafe, in the vocabulary of the URL check.

Returns:

The issue, coded AgentErrorCode.A2A_BASE_URL_INVALID.

Return type:

AgentCompilationIssue

loom.ai.errors.a2a_expose_empty()[source]¶

A2A exposure was enabled without naming a single agent.

Return type:: AgentCompilationIssue

loom.ai.errors.auth_exclusion_overlaps_agents(paths)[source]¶

An authentication exclusion covers an agent or A2A invocation path.

Parameters:: paths (Sequence[str])
Return type:: AgentCompilationIssue

loom.ai.errors.a2a_agent_unreachable(agent, reason)[source]¶

A remote agent’s card cannot be retrieved.

Parameters:

agent (str) – The remote agent’s registered name, never its URL — a URL carries credentials and hosts that the redaction guarantee keeps out of diagnostics (FR-030a/FR-038).
reason (str) – Why the card could not be retrieved.

Return type:

AgentCompilationIssue

loom.ai.errors.agent_specs_conflict()[source]¶

Both artifact sources declare agents; there is no implicit precedence.

Return type:: AgentCompilationIssue

loom.ai.errors.agent_specs_missing()[source]¶

The ai: section is configured but no artifact source declares agents.

Return type:: AgentCompilationIssue

loom.ai.errors.remote_clients_unknown(value, valid)[source]¶

The start-up tolerance of remote clients names no known mode.

Parameters:

value (str) – The rejected value of ai.remote_clients.
valid (Sequence[str]) – The accepted modes, supplied by the caller so this module keeps no knowledge of the configuration domain.

Return type:

AgentCompilationIssue

loom.ai.errors.max_agent_depth_invalid(value)[source]¶

The nesting bound is below the one entry every top-level run already spends.

Parameters:: value (int) – The rejected value of ai.max_agent_depth.
Return type:: AgentCompilationIssue

loom.ai.errors.spec_version_deprecated(component, found, latest)[source]¶

The artifact’s version is still accepted but has been superseded.

Parameters:

component (str)
found (int)
latest (int)

Return type:

AgentCompilationIssue

loom.ai.errors.agent_marker_unknown(usecase, parameter, agent, available)[source]¶

A use case’s Agent() marker names an agent no engine compiled.

Parameters:

usecase (str) – Registered key of the use case declaring the marker.
parameter (str) – Name of the execute parameter carrying the marker.
agent (str) – Agent name the marker declared.
available (Sequence[str]) – Names of the agents actually compiled in this deployment.

Return type:

AgentCompilationIssue

loom.ai.errors.mcp_marker_unknown(usecase, parameter, server, available)[source]¶

A use case’s Mcp() marker names a server no engine compiled.

The existing mcp_server_unknown() cannot serve this condition: it carries neither the parameter nor the available server names, both of which this message needs to point someone at the right signature.

Parameters:

usecase (str) – Registered key of the use case declaring the marker.
parameter (str) – Name of the execute parameter carrying the marker.
server (str) – Server name the marker declared.
available (Sequence[str]) – Names of the servers actually configured for this deployment.

Return type:

AgentCompilationIssue

loom.ai.errors.use_case_tool_filter_matches_nothing(usecase, parameter, server)[source]¶

A use case’s Mcp() include matches no tool the named server publishes.

A standalone factory, not a variant selected inside filter_issues: the use-case check runs over the marker’s own parameter, something filter_issues never carries a name for. It reuses AgentErrorCode.TOOL_FILTER_MATCHES_NOTHING rather than minting a new code — one condition, one code — and differs from tool_filter_matches_nothing() in both message and field: this one carries parameters.{parameter} (via _AGENT_MARKER_FIELD_TEMPLATE) instead of capabilities.include. That field difference is what makes reusing the shared code safe: it is the only thing that lets a caller filtering on AgentErrorCode.TOOL_FILTER_MATCHES_NOTHING tell an agent-artifact issue apart from a use-case-parameter one.

Parameters:

usecase (str) – Registered key of the use case declaring the marker.
parameter (str) – Name of the execute parameter carrying the marker.
server (str) – Server name the marker declared.

Return type:

AgentCompilationIssue

loom.ai.errors.agent_marker_output_mismatch(usecase, parameter, agent, expected, declared)[source]¶

A use case’s AgentHandle annotation disagrees with the named agent’s own declared output type.

Parameters:

usecase (str) – Registered key of the use case declaring the marker.
parameter (str) – Name of the execute parameter carrying the marker.
agent (str) – Agent name the marker declared.
expected (str) – Output type named by the parameter’s AgentHandle[...] annotation.
declared (str) – Output type the named agent actually declares.

Return type:

AgentCompilationIssue

class loom.ai.errors.AgentRunErrorClass(value)[source]¶

Bases: StrEnum

Class of a run-time failure; the retry policy reads this, not the message.

class loom.ai.errors.AgentRunErrorCode(value)[source]¶

Bases: StrEnum

Enumeration of all agent run-time failure codes.

exception loom.ai.errors.AgentRunError(code, message, *, interaction_id=None, usage=None)[source]¶

Bases: Exception

A run failed with a stable, machine-readable code.

Lives with AgentRunErrorCode rather than with the runtime that raises it: the engine adapters classify and re-raise it, and importing the whole live runtime — its exit stack, its shared sessions, its SQL configuration — to reach one exception class would point the dependency arrow at the concretion instead of at the contract.

Parameters:

code (AgentRunErrorCode) – Run-time failure code; the retry policy reads its class.
message (str) – Human-readable description, safe to return to the caller.
interaction_id (str | None) – Identifier of the admitted run, when the failure happened after admission; None for pre-admission failures.
usage (AgentUsage | None) – What the failed run had already spent, when the engine knew it; None when nothing was spent or nothing was measurable.

Return type:

None

code¶: The failure code carried by this error.

interaction_id¶: The run this error belongs to, or None.

usage¶: The partial accounting of the failed run, or None.

Example:

raise AgentRunError(AgentRunErrorCode.RUN_TIMEOUT, "the run took too long")

loom.ai.errors.CONVERSATION_LOAD_FAILED_MESSAGE: Final[str] = 'the conversation could not be loaded; the detail is recorded server-side'¶

Client text of every CONVERSATION_LOAD_FAILED error (D8).

Defined once here because both the runtime loader and an engine’s history decoder raise the code; the loader’s own detail is logged, never returned.

loom.ai.errors.CONVERSATION_LOAD_TIMEOUT_MESSAGE: Final[str] = 'the conversation loader exceeded its time limit'¶: Client text of every CONVERSATION_LOAD_TIMEOUT error (FR-063).

loom.ai.errors.run_error_class(code)[source]¶

Return the failure class of a run-time error code.

The mapping is total: every member of AgentRunErrorCode has an entry, so a new code without a class fails immediately instead of silently defaulting to a retriable class.

Parameters:: code (AgentRunErrorCode) – Run-time error code to classify.
Returns:: The class the retry policy must read.
Raises:: KeyError – If the code has no registered class.
Return type:: AgentRunErrorClass

loom.ai.errors.is_retriable(code)[source]¶

Return whether a run-time failure may be retried by the caller.

Only AgentRunErrorClass.INFRASTRUCTURE failures are retriable, with one explicit exception: COST_NOT_MEASURABLE stays INFRASTRUCTURE but is never retriable, because the provider call it reports on has already returned and already been billed.

Parameters:: code (AgentRunErrorCode) – Run-time error code to test.
Returns:: True when the code’s class is INFRASTRUCTURE; False for every other class, and for COST_NOT_MEASURABLE despite its INFRASTRUCTURE class.
Return type:: bool