aeat.entrypoints.mcp._harness_tools module

The harness.load floor tool: the universal operating-layer delivery channel.

ADR R4 decides the operating layer reaches an arbitrary client through four channels, floor-first. This module owns the FLOOR: a single read-only tool that returns the shipped operator operating rules plus the active persona document as text. A tool is the only channel guaranteed to reach a model on a minimal tools-only client (prompts and resources are negotiated capabilities a client may not support), so this tool is the one delivery path that always works. It is advertised on every session regardless of the active persona - the floor must never be scoped away - and is annotated readOnlyHint because it reads shipped harness data and computes nothing.

Like _tools and _meta_tools, this module is SDK-independent pure functions over typed models: build_harness_floor_payload() and render_harness_floor_text() carry no protocol detail and are unit-tested directly, while build_harness_floor_tool() lazily adapts the payload surface onto the MCP SDK’s Tool type so the module still imports (and the server still refuses gracefully) when the aeat-cli[agent] extra is absent.

The operating-layer text is read through the aeat.agent package facade (operator_rules_text() and iter_personas()), never a private submodule, per the service-imports-via-top-level-reexports discipline.

HARNESS_LOAD_TOOL

The floor tool’s MCP name, following the per-verb aeat_<key> naming convention (_dispatch.tool_name_for_command): the conceptual harness.load verb renders as aeat_harness_load.

WHOAMI_TOOL

The identity-assertion tool’s MCP name (ADR I1). Like the floor and grounding tools it is a read-only console tool carrying the aeat_ prefix; unlike the per-verb surface it is always advertised and never persona-scoped away, so an agent can always confirm the active taxpayer.

off_host_consent_text()[source]

Return the localized off-host consent disclosure (ADR R9).

A standing disclosure carried on every floor load rather than a stateful “first-run” flag: the floor is the read-first channel a client loads at the start of a session, so surfacing the disclosure here guarantees it reaches the operator BEFORE the first off-host-visible interaction, on every session, with no fragile first-run state that a returning session could skip.

Return type:

str

class ActivePersonaDocument(**data)[source]

Bases: BaseModel

The active persona’s shipped document, resolved for the floor payload.

Parameters:
name: str
text: str
class WhoamiIdentity(**data)[source]

Bases: BaseModel

The active taxpayer identity block returned by the whoami tool.

The identity anchor the agent reconciles before a mutating command: a filing must never run under the wrong profile (Erika must not file while Erik is the active profile). active_profile is the operator-chosen display LABEL (the plaintext manifest name, never the redacted profile/bucket UUID — the same label semantics the envelope-spine active_profile carries), or None when no profile is active. tax_id_present states whether the active profile carries a tax id (its legal identity). readiness is the active-profile health status (ready / incomplete / none / a degraded-pointer status), and next_action is the recovery step the health projection recommends.

Parameters:

  • active_profile (str | None)

  • tax_id_present (bool)

  • readiness (str)

  • next_action (str)

active_profile: str | None
tax_id_present: bool
readiness: str
next_action: str
class HarnessFloorPayload(**data)[source]

Bases: BaseModel

The floor tool’s structured result: operator rules plus the active persona.

off_host_consent is the standing R9 privacy disclosure (the operator’s words + figures go off-host to the LLM provider; source documents never leave the machine), surfaced first so it is read before any off-host-visible interaction. operator_rules is the concatenated shipped operator operating-rule text - the always-on operating contract every session carries. active_persona is the persona document resolved from the session’s AEAT_MCP_PERSONA scope, or None for an un-personified session (the full, unscoped surface). identity is the same active-taxpayer block the whoami tool returns, so session orientation (this floor tool’s job) carries WHO is active; it is None when the caller does not inject it (the SDK-independent unit surface), resolved and passed in at the server boundary.

Parameters:
operator_rules: str
active_persona: ActivePersonaDocument | None
identity: WhoamiIdentity | None
build_harness_floor_payload(*, persona, identity=None)[source]

Build the floor payload for persona (None = un-personified session).

Reads the shipped operator rules verbatim and, when a persona is active, its document verbatim. A persona whose document is somehow absent yields a None active_persona rather than raising: the floor’s rules half must always deliver even if a persona document is missing.

identity is the active-taxpayer block surfaced on the floor response so session orientation carries WHO is active. It stays a caller-injected parameter (defaulting None) rather than being resolved here so this builder stays a pure function over shipped data: the server boundary resolves the runtime identity (which reads storage) and passes it in, the same resolve-at-the-boundary / inject-into-the-payload shape the envelope spine uses.

Return type:

HarnessFloorPayload

Returns:

The HarnessFloorPayload for the session.

Parameters:
render_harness_floor_text(payload)[source]

Render the floor payload as one markdown document for the tool’s text content.

The consent disclosure leads, then the shipped rules and persona texts are embedded verbatim under headings, so a tools-only client that reads only the text block still receives the disclosure first and the whole operating layer. The structured content carries the same texts as discrete fields for a client that prefers to parse them.

Return type:

str

Parameters:

payload (HarnessFloorPayload)

build_harness_floor_tool()[source]

Build the SDK Tool object for the harness.load floor tool.

Lazily imports the SDK types so the module still imports when the aeat-cli[agent] extra is absent. The tool takes no arguments (the active persona is resolved server-side from the session scope) and is annotated readOnlyHint / idempotentHint: it reads shipped data and never mutates state.

Return type:

Tool

Returns:

The harness.load Tool object.

build_whoami_identity()[source]

Resolve the active taxpayer identity block (ADR I1), best-effort.

Wraps the active-profile health assessment (assess_active_profile_health()): its status is the readiness and its next_action the recovery step. The display LABEL is resolved from the plaintext bucket manifest (read_profile_bucket_by_id()) - the same non-secret name the envelope-spine active_profile carries, never the redacted bucket/profile UUID the health projection’s active_profile field holds. tax_id_present is derived from the health projection: a tax id is on file when the profile record is present and the canonical identity.tax_id fact path (TAX_ID_FACT_PATH) is not among the missing required fields, so it reports correctly even for an otherwise-incomplete profile. The health assessment never raises for an absent or unreadable profile (it returns a degraded status), and label resolution is guarded, so this read-only identity probe is safe to call on every session and before every mutation.

Return type:

WhoamiIdentity

render_whoami_identity_text(identity)[source]

Render the identity block as plain text for a tools-only MCP client.

Return type:

str

Parameters:

identity (WhoamiIdentity)

build_whoami_tool()[source]

Build the SDK Tool object for the whoami identity tool (ADR I1).

Lazily imports the SDK types so the module still imports when the aeat-cli[agent] extra is absent. The tool takes no arguments and is annotated readOnlyHint / idempotentHint: it reads the active-profile health projection and never mutates state. Its description states its identity-safety job so an agent calls it to confirm WHO is active before a mutation and again after a profile switch.

Return type:

Tool

Returns:

The whoami Tool object.