Skip to main content

Agent

An agent as data: one loom.agent/1 document naming the agent and its brief, its models, the harness session it may run (kind, run budget, stop policy, confinement and tool policy), its outer and inner loop, the states an item is projected by, the bindings it reads and writes through, its channel, write policy, capabilities, exposure, runtime and deployment.

loom.agent is one of loom's bounded contexts. All domains.

Types​

A2aCard​

loom.agent.A2aCard is a record of three fields:

  • name — String
  • description — String
  • skills — List<String>

A2aExposure​

loom.agent.A2aExposure is a record of three fields:

  • port — Integer
  • path — String
  • card — loom.agent.A2aCard

A2aRefusalReason​

loom.agent.A2aRefusalReason is one of MissingBearer and WrongBearer.

ActionBudget​

loom.agent.ActionBudget is a record of six fields:

  • action — String
  • max_trials — Optional<Integer>, which may be absent
  • max_tokens_in — Optional<Integer>, which may be absent
  • max_tokens_out — Optional<Integer>, which may be absent
  • max_duration_ms — Optional<Integer>, which may be absent
  • max_cost_micro_usd — Optional<Integer>, which may be absent

AgentId​

loom.agent.AgentId wraps String and is not interchangeable with one: the whole value of naming it separately is the crossings the model then refuses.

AgentIdentity​

loom.agent.AgentIdentity is a record of three fields:

  • id — loom.agent.AgentId
  • name — String
  • brief — String

AgentSpec​

loom.agent.AgentSpec is a record of 13 fields:

  • format — String
  • agent — loom.agent.AgentIdentity
  • model — loom.models.ModelsConfig
  • session — Optional<loom.agent.SessionSpec>, which may be absent
  • loops — Optional<loom.agent.Loops>, which may be absent
  • states — List<loom.agent.AgentState>
  • bindings — List<loom.agent.Binding>
  • channel — Optional<loom.agent.ChannelSpec>, which may be absent
  • writes — Optional<loom.agent.WritesSpec>, which may be absent
  • policy — Optional<loom.agent.PolicySpec>, which may be absent
  • expose — Optional<loom.agent.ExposeSpec>, which may be absent
  • runtime — Optional<loom.agent.RuntimeSpec>, which may be absent
  • deploy — Optional<loom.agent.DeploySpec>, which may be absent

AgentState​

loom.agent.AgentState is a record of four fields:

  • name — String
  • when — loom.agent.StateWhen
  • actions — List<String>
  • sources — List<loom.datasource.SourceName>

Binding​

loom.agent.Binding is one of two shapes, told apart by a kind field — tagged, so a decoder never has to guess which branch it is reading:

  • connectors — loom.agent.ConnectorsBinding
  • http — loom.agent.HttpBinding

BreachStep​

loom.agent.BreachStep is one of DiscardStep and KeepStep.

BudgetLimit​

loom.agent.BudgetLimit is one of MaxSteps, MaxTrials, MaxTokensIn, MaxTokensOut, MaxDurationMs, MaxCostMicroUsd, MaxTokens and Deadline.

ChannelSpec​

loom.agent.ChannelSpec is a record of three fields:

  • binding — loom.datasource.SourceName
  • allow — List<String>
  • bot_user_id — String

ConfinementMode​

loom.agent.ConfinementMode is one of none.

ConnectorsBinding​

loom.agent.ConnectorsBinding is a record of seven fields:

  • name — loom.datasource.SourceName
  • adapter — loom.datasource.AdapterAlias
  • connection — loom.datasource.ConnectionId
  • list — Optional<loom.datasource.OperationId>, which may be absent
  • search — Optional<loom.datasource.OperationId>, which may be absent
  • get — Optional<loom.datasource.OperationId>, which may be absent
  • write — Optional<loom.datasource.OperationId>, which may be absent

DecisionMode​

loom.agent.DecisionMode is one of frame, ask and observe.

DeploySpec​

loom.agent.DeploySpec is a record of one field:

  • kubernetes — Optional<loom.agent.KubernetesDeploy>, which may be absent

EgressAperture​

loom.agent.EgressAperture is a record of four fields:

  • name — String
  • host — String
  • port — Integer
  • max_bytes — Optional<Integer>, which may be absent

ExposeSpec​

loom.agent.ExposeSpec is a record of one field:

  • a2a — Optional<loom.agent.A2aExposure>, which may be absent

HttpBinding​

loom.agent.HttpBinding is a record of six fields:

  • name — loom.datasource.SourceName
  • base_url — String
  • allow_paths — List<String>
  • method — String
  • bearer_env — Optional<String>, which may be absent
  • max_bytes — Integer

HttpReadRefusalReason​

loom.agent.HttpReadRefusalReason is one of MethodNotGet, PathNotAllowed, BearerMissing, Redirected and FailedStatus.

HttpTrustRefusalReason​

loom.agent.HttpTrustRefusalReason is one of Unreadable, TooLarge and NoCertificate.

InnerLoop​

loom.agent.InnerLoop is a record of four fields:

  • protocol — String
  • step_budget — Integer
  • model_budget — Integer
  • classify_threshold — Optional<Decimal>, which may be absent

KubernetesDeploy​

loom.agent.KubernetesDeploy is a record of six fields:

  • namespace — String
  • service_account — String
  • image_repository — Optional<String>, which may be absent
  • resources — loom.agent.KubernetesResources
  • egress — List<loom.agent.KubernetesEgress>
  • ingress — List<loom.agent.KubernetesIngress>

KubernetesEgress​

loom.agent.KubernetesEgress is a record of five fields:

  • name — String
  • host — Optional<String>, which may be absent
  • namespace — Optional<String>, which may be absent
  • selector — List<loom.agent.Label>
  • port — Integer

KubernetesIngress​

loom.agent.KubernetesIngress is a record of three fields:

  • name — String
  • from_namespace — String
  • port — Integer

KubernetesResources​

loom.agent.KubernetesResources is a record of two fields:

  • cpu — String
  • memory — String

Label​

loom.agent.Label is a record of two fields:

  • name — String
  • value — String

LimitBreachStep​

loom.agent.LimitBreachStep is a record of two fields:

  • limit — loom.agent.BudgetLimit
  • step — loom.agent.BreachStep

Loops​

loom.agent.Loops is a record of two fields:

  • outer — loom.agent.OuterLoop
  • inner — loom.agent.InnerLoop

OuterLoop​

loom.agent.OuterLoop is a record of four fields:

  • poll_interval_seconds — Integer
  • sources — List<loom.datasource.SourceName>
  • min_age_minutes — Integer
  • lookback_minutes — Optional<Integer>, which may be absent

PolicySpec​

loom.agent.PolicySpec is a record of one field:

  • capabilities — List<String>

RefusalReason​

loom.agent.RefusalReason is one of Malformed, SecretLiteral, UnknownFormat, BlankText, NotAVariableName, PortOutOfRange, NotAPlainPath, NotAnInstant, UnknownProtocol, UnknownAction, UnboundSource, HttpMethod, SendWithoutWrites and EmptyChannelAllow.

RunBudget​

loom.agent.RunBudget is a record of eight fields:

  • max_steps — Optional<Integer>, which may be absent
  • max_tokens_in — Optional<Integer>, which may be absent
  • max_tokens_out — Optional<Integer>, which may be absent
  • max_duration_ms — Optional<Integer>, which may be absent
  • max_cost_micro_usd — Optional<Integer>, which may be absent
  • max_tokens — Optional<Integer>, which may be absent
  • deadline — Optional<Timestamp>, which may be absent
  • per_action — List<loom.agent.ActionBudget>

RunRefusalReason​

loom.agent.RunRefusalReason is one of SpecRefused, InputAbsent, InputUnreadable, InputEmpty and SendRefused.

RuntimeSpec​

loom.agent.RuntimeSpec is a record of three fields:

  • state_dir — String
  • connectors — Optional<loom.datasource.ConnectorsCliConfig>, which may be absent
  • confinement — loom.agent.ConfinementMode

SendRefusalReason​

loom.agent.SendRefusalReason is one of WritesNone, OutsideAllowList, NoProposal and RateLimited.

ServeRefusalReason​

loom.agent.ServeRefusalReason is one of NothingToServe.

SessionSpec​

loom.agent.SessionSpec is a record of nine fields:

  • kind — loom.session.SessionKind
  • budget — loom.agent.RunBudget
  • stop — loom.agent.StopPolicy
  • confinement — loom.agent.ConfinementMode
  • tools — loom.agent.ToolPolicy
  • effort — Optional<String>, which may be absent
  • max_budget_micro_usd — Optional<Integer>, which may be absent
  • strict_version — Optional<Boolean>, which may be absent
  • context — List<String>

StateWhen​

loom.agent.StateWhen is a record of one field:

  • intent — loom.plugin.Intent

StopPolicy​

loom.agent.StopPolicy is a record of four fields:

  • approval_gate — Boolean
  • idle_bound — Optional<Integer>, which may be absent
  • on_breach — loom.agent.BreachStep
  • breach_by_limit — List<loom.agent.LimitBreachStep>

ToolPolicy​

loom.agent.ToolPolicy is a record of four fields:

  • allow — List<String>
  • deny — List<String>
  • egress — List<loom.agent.EgressAperture>
  • decisions — loom.agent.DecisionMode

WriteMode​

loom.agent.WriteMode is one of auto, approval and none.

WritesSpec​

loom.agent.WritesSpec is a record of two fields:

  • mode — loom.agent.WriteMode
  • max_per_hour — Integer

Commands​

AdmitA2aRequest​

loom.agent.AdmitA2aRequest.

It takes:

  • probe — Boolean
  • bearer_presented — Boolean
  • bearer_matches — Boolean

It has four outcomes.

missing-bearer — Taken when (probe == false and bearer_presented == false) holds of the input. No entity in this specification changes. It reports loom.agent.A2aRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

wrong-bearer — Taken when (probe == false and bearer_matches == false) holds of the input. No entity in this specification changes. It reports loom.agent.A2aRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

probe — Taken when probe == true holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

admitted — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

AdmitHttpRead​

loom.agent.AdmitHttpRead.

It takes:

  • method — String
  • path_allowed — Boolean
  • bearer_missing — Boolean

It has four outcomes.

method-not-get — Taken when method != GET holds of the input. No entity in this specification changes. It reports loom.agent.HttpReadRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

path-not-allowed — Taken when path_allowed == false holds of the input. No entity in this specification changes. It reports loom.agent.HttpReadRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

bearer-missing — Taken when bearer_missing == true holds of the input. No entity in this specification changes. It reports loom.agent.HttpReadRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

admitted — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

AdmitHttpTrust​

loom.agent.AdmitHttpTrust.

It takes:

  • named — Boolean
  • read — Boolean
  • bytes — Integer
  • certificates — Integer

It has five outcomes.

unreadable — Taken when (named == true and read == false) holds of the input. No entity in this specification changes. It reports loom.agent.HttpTrustRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

too-large — Taken when (named == true and bytes > 1048576) holds of the input. No entity in this specification changes. It reports loom.agent.HttpTrustRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

no-certificate — Taken when (named == true and certificates <= 0) holds of the input. No entity in this specification changes. It reports loom.agent.HttpTrustRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

webpki-only — Taken when named == false holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

extended — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

AdmitSend​

loom.agent.AdmitSend.

It takes:

  • mode — loom.agent.WriteMode
  • channel_allowed — Boolean
  • proposed — Boolean
  • granted — Boolean
  • sent_in_window — Integer
  • max_per_hour — Integer

It has six outcomes.

writes-none — Taken when mode == none holds of the input. No entity in this specification changes. It reports loom.agent.SendRefused, carrying reason and final. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

outside-allow-list — Taken when channel_allowed == false holds of the input. No entity in this specification changes. It reports loom.agent.SendRefused, carrying reason and final. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

no-proposal — Taken when proposed == false holds of the input. No entity in this specification changes. It reports loom.agent.SendRefused, carrying reason and final. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

rate-limited — Taken when sent_in_window >= {fact: max_per_hour} holds of the input. No entity in this specification changes. It reports loom.agent.SendRefused, carrying reason and final. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

held — Taken when (mode == approval and granted == false) holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

admitted — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

AdmitServe​

loom.agent.AdmitServe.

It takes:

  • channel — Boolean
  • a2a — Boolean

It has four outcomes.

nothing-to-serve — Taken when (channel == false and a2a == false) holds of the input. No entity in this specification changes. It reports loom.agent.ServeRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

polls-and-answers — Taken when (channel == true and a2a == true) holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

polls — Taken when channel == true holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

answers — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

BoundHttpAnswer​

loom.agent.BoundHttpAnswer.

It takes:

  • status — Integer
  • bytes — Integer
  • max_bytes — Integer

It has four outcomes.

redirected — Taken when (status >= 300 and status <= 399) holds of the input. No entity in this specification changes. It reports loom.agent.HttpReadRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

failed-status — Taken when (status <= 199 or status >= 400) holds of the input. No entity in this specification changes. It reports loom.agent.HttpReadRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

cut — Taken when bytes > {fact: max_bytes} holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

whole — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

CheckAgentSpec​

loom.agent.CheckAgentSpec.

It takes:

  • path — String

It has 15 outcomes.

malformed — Decided outside the input: the document at the path does not decode as a loom.agent/1 document. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

secret-literal — Decided outside the input: a string of the document holds a credential. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

unknown-format — Decided outside the input: the document's format is not loom.agent/1. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

blank-text — Decided outside the input: a text member of the document is empty or only whitespace. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

not-a-variable-name — Decided outside the input: a bearer_env of the document is not an environment variable name. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

port-out-of-range — Decided outside the input: a port of the document is outside 1 to 65535. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

not-a-plain-path — Decided outside the input: an allow_paths entry of an http binding is not a plain path. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

not-an-instant — Decided outside the input: a Timestamp member of the document is not an RFC 3339 instant. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

unknown-protocol — Decided outside the input: the inner loop names a protocol the plugin catalog does not hold, or states are declared with no inner loop. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

unknown-action — Decided outside the input: a state names an action the inner loop's protocol does not declare. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

unbound-source — Decided outside the input: a state, the outer loop or the channel names a source no binding declares. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

http-method — Decided outside the input: an http binding's method is not GET. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

send-without-writes — Decided outside the input: reply.send is a capability while writes are none or undeclared. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

empty-channel-allow — Decided outside the input: the channel's allow list is empty. No predicate over the input reaches this branch, and saying when: false instead would have claimed it is unreachable, which is a different and false statement. No entity in this specification changes. It reports loom.agent.SpecRefused, carrying reason, member and detail. It emits nothing. A test reaches it by injecting the declared fault, because no input can.

serveable — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

RunOnce​

loom.agent.RunOnce.

It takes:

  • spec_refused — Boolean
  • input_given — Boolean
  • input_read — Boolean
  • input_blank — Boolean
  • send_refused — Boolean
  • answered — Boolean

It has seven outcomes.

spec-refused — Taken when spec_refused == true holds of the input. No entity in this specification changes. It reports loom.agent.RunRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

input-absent — Taken when input_given == false holds of the input. No entity in this specification changes. It reports loom.agent.RunRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

input-unreadable — Taken when input_read == false holds of the input. No entity in this specification changes. It reports loom.agent.RunRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

input-empty — Taken when input_blank == true holds of the input. No entity in this specification changes. It reports loom.agent.RunRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

send-refused — Taken when send_refused == true holds of the input. No entity in this specification changes. It reports loom.agent.RunRefused, carrying reason. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

no-answer — Taken when answered == false holds of the input. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies that condition.

answered — The default branch, taken when no other outcome's condition matched. No entity in this specification changes. It emits nothing. A test reaches it by constructing an input that satisfies no other outcome's condition.

Errors​

A2aRefused​

It carries:

  • reason — loom.agent.A2aRefusalReason

Reported by loom.agent.AdmitA2aRequest on its missing-bearer and wrong-bearer outcomes.

HttpReadRefused​

It carries:

  • reason — loom.agent.HttpReadRefusalReason

Reported by loom.agent.AdmitHttpRead on its method-not-get, path-not-allowed and bearer-missing outcomes.

Reported by loom.agent.BoundHttpAnswer on its redirected and failed-status outcomes.

HttpTrustRefused​

It carries:

  • reason — loom.agent.HttpTrustRefusalReason

Reported by loom.agent.AdmitHttpTrust on its unreadable, too-large and no-certificate outcomes.

RunRefused​

It carries:

  • reason — loom.agent.RunRefusalReason

Reported by loom.agent.RunOnce on its spec-refused, input-absent, input-unreadable, input-empty and send-refused outcomes.

SendRefused​

It carries:

  • reason — loom.agent.SendRefusalReason
  • final — Boolean

Reported by loom.agent.AdmitSend on its writes-none, outside-allow-list, no-proposal and rate-limited outcomes.

ServeRefused​

It carries:

  • reason — loom.agent.ServeRefusalReason

Reported by loom.agent.AdmitServe on its nothing-to-serve outcome.

SpecRefused​

It carries:

  • reason — loom.agent.RefusalReason
  • member — String
  • detail — String

Reported by loom.agent.CheckAgentSpec on its malformed, secret-literal, unknown-format, blank-text, not-a-variable-name, port-out-of-range, not-a-plain-path, not-an-instant, unknown-protocol, unknown-action, unbound-source, http-method, send-without-writes and empty-channel-allow outcomes.

Generated from loom v1 · model digest 687ce3d39bdb34d56d1fe0c221f558534fa9c3e8eda9e34862b5b742d61331e9 · contract digest slice-sha256/2:ca54f5f028a6cb54dd4cc2065889eab554a30154bf3975b0884475d97225a8c8. Do not edit this file; change the specification and regenerate it with task docs-generate.