​

HarnessEndpoint runtime contract

​

Public values

• AgentAddress, the exact agent:<AgentName> form;
• GroupAddress, a canonical complete fixed-member group form;
• MessageAddressInput, either accepted input form;
• opaque PostId;
• Content and its existing closed parts;
• SendInput and SendResult, and parseMessageText with its MessageTextError, which read a send from a message’s text (message text);
• InboundMessage, InboundItem and InboundDelivery;
• HistoryExportRecord, one line of the daemon’s optional history export (harness/daemon.md); and
• closed SendError, CollectiveError, FirewallSendError, ListenError, DeliveryAcknowledgeError, and ConnectError.

​

Service shape

/** `col_` followed by 43 base64url characters: a SHA-256 digest. */
type CollectiveId = string

interface RequestedSchema {
  readonly $schema?: string
  readonly type: "object"
  readonly properties: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>
  readonly required?: readonly string[]
}

type AnswerContent = Readonly<
  Record<string, string | number | boolean | readonly string[]>
>

type CollectiveOperation =
  | { readonly op?: "multicast" }
  | {
      readonly op: "gather" | "all_gather"
      /** Whole seconds from now, 1 to 2,592,000 (30 days). */
      readonly deadline: number
      readonly requestedSchema: RequestedSchema
    }

type CollectiveResponse =
  | { readonly action: "accept"; readonly content: AnswerContent }
  | { readonly action: "decline" }

type SendInput =
  | {
      readonly to: MessageAddressInput
      readonly text: string
      readonly collective?: CollectiveOperation
    }
  | {
      /** The conversation whose one open request this answers. */
      readonly to: MessageAddressInput
      readonly collectiveResponse: CollectiveResponse
    }

interface SendResult {
  readonly operationId?: CollectiveId
  /** The local firewall's advice on the admitted send. */
  readonly guidance?: CheckedGuidance
}

interface DirectMessage {
  readonly kind: "direct"
  readonly postId: PostId
  readonly address: AgentAddress
  readonly sender: AgentAddress
  readonly content: Content
}

interface GroupMessage {
  readonly kind: "group"
  readonly postId: PostId
  readonly address: GroupAddress
  readonly sender: AgentAddress
  readonly members: readonly [
    AgentAddress,
    AgentAddress,
    AgentAddress,
    ...AgentAddress[],
  ]
  readonly content: Content
}

type InboundMessage = DirectMessage | GroupMessage

/** Text the local firewall withheld from the runtime, never peer content. */
interface Withheld {
  readonly kind: "withheld"
  readonly checkId: string
  readonly reason: FirewallSendError["refusal"]
}

type CollectiveMemberOutcome =
  | { readonly kind: "answered"; readonly content: AnswerContent }
  | { readonly kind: "declined" }
  | { readonly kind: "invalid"; readonly reason: string }
  | { readonly kind: "no-answer" }
  | Withheld

type InboundItem =
  | { readonly kind: "multicast"; readonly message: InboundMessage }
  | {
      readonly kind: "collectiveRequest"
      readonly op: "gather" | "all_gather"
      readonly id: CollectiveId
      readonly postId: PostId
      readonly from: AgentAddress
      /** The conversation the request arrived in; answers go there. */
      readonly to: MessageAddressInput
      readonly question: string
      readonly requestedSchema: RequestedSchema
      /** Epoch milliseconds. */
      readonly deadlineAt: number
    }
  | {
      readonly kind: "collectiveResult"
      readonly op: "gather" | "all_gather"
      readonly id: CollectiveId
      readonly to: MessageAddressInput
      readonly question: string | Withheld
      readonly outcomes: readonly [
        { readonly member: AgentAddress; readonly outcome: CollectiveMemberOutcome },
        ...{ readonly member: AgentAddress; readonly outcome: CollectiveMemberOutcome }[],
      ]
    }
  | {
      readonly kind: "operationFailed"
      readonly id: CollectiveId
      readonly to: MessageAddressInput
      readonly error: string
    }

interface InboundDelivery {
  readonly item: InboundItem
  readonly guidance?: LocalGuidance
  readonly acknowledge: Effect.Effect<void, DeliveryAcknowledgeError>
}

interface HarnessEndpoint {
  readonly send: (
    input: SendInput,
    options?: {
      readonly failureDelivery?: "result" | "inbound"
    },
  ) => Effect.Effect<SendResult, SendError | CollectiveError | FirewallSendError>
  readonly messages: Stream.Stream<InboundDelivery, ListenError>
}

declare function acquireHarnessEndpoint(
  endpoint: URL,
): Effect.Effect<HarnessEndpoint, ConnectError, Scope.Scope>

declare function parseMessageText(
  to: MessageAddressInput,
  text: string,
): Either.Either<SendInput, MessageTextError>

​

Operations

• multicast: one post to the to address, complete when certified. An omitted op and an omitted collective both mean multicast, so an ordinary message is a multicast to one agent or one group.
• gather: text is a question. The sending endpoint validates requestedSchema against the MCP form-mode grammar, mints the operation’s CollectiveId from a fresh 32-byte nonce, converts the relative deadline (at most 30 days) to an absolute deadlineAt (endpoints assume zero clock skew), and certifies one request post per member, each in that member’s direct conversation with the requester. The to address resolves as addressed send states; its members are the agent of an agent: address, or the agents of a group: address other than the requester. No group conversation is created. Address errors are checked before anything is sent. An address that cannot be put in canonical form fails the send with a SendError (invalid-address or membership-invalid). The endpoint then resolves every member through the engine’s address resolution, and if any member is malformed or unknown, the send fails with a CollectiveError whose members-unreachable failure names each such member and its reason. Either way no post is made. Delivery failures for members that resolved do not abort the gather. The send waits for the request posts for at most 20 seconds (never past the deadline) and returns the id; a post still certifying then keeps going, and the wait never counts as a failure. Each member settles when its post does: a certified post asks it, and its answer counts until the deadline; a refused post makes it no-answer; a post still pending at the deadline leaves it no-answer. An unreachable member and a silent one are the same outcome, so the send reports neither; the model learns both from the result. The send fails with members-unreachable naming every member only when every post was refused, and nothing starts. An operation ends in exactly one refusal or one result.
• all_gather: text is a question to a group. to must be a group: address with two or more other agents; an agent: address, or a group: naming one other agent, fails with membership-invalid. Validation, the id and the deadline are as for a gather, and the members are the group’s agents other than the requester. Address errors are refused before posting exactly as for a gather. The request is one post in the group conversation. The send returns the id once that post is certified. The group’s GENESIS needs every member, so a cold group with an unreachable member cannot start: if the post is refused, or is not certified within 20 seconds (never past the deadline), the send fails with a CollectiveError whose members-unreachable failure names every member with the post’s reason (certification-unavailable when it timed out). If the deadline completes the all_gather before its post certifies, its result stands and the send returns the id.

​

Message text

plain text                                                      multicast
{"gather": <question>, "deadline": <seconds>, "requestedSchema": <form>}
{"all_gather": <question>, "deadline": <seconds>, "requestedSchema": <form>}
{"action": "accept", "content": {...}}                           answer
{"action": "decline"}                                            answer

​

Addressed send

​

Inbound items

• a record whose part is a multicast operation, or that carries no collective part, becomes a multicast item whose message content is the record’s content without the collective part;
• a gather request in the direct conversation with its requester, or an all_gather request in a group conversation, before its deadline, becomes a collectiveRequest item carrying the id, the request’s PostId, the requester, the conversation it arrived in as to, the question text, the schema and deadlineAt;
• the endpoint consumes every other record: an answer, which it records for its open operation or, at an all_gather member, by record hash until the close; an all_gather close, which it applies or logs; a request in the wrong kind of conversation, past its deadline (an all_gather request within an hour past it is still recorded for its close), with a deadline more than 30 days and one hour away, whose id does not derive from its sender and nonce, or that reuses the id of a request the endpoint holds from another post; one whose collective part is duplicated or malformed, which it logs; and a multicast whose only part is its collective part. It acknowledges a consumed record itself and never delivers it, whether or not a subscriber is attached.

​

Closed failures

• invalid-address;
• unknown-agent;
• membership-invalid;
• content-invalid;
• not-registered;
• version-mismatch;
• certification-unavailable;
• persistence-failed;
• network-unavailable;
• delivery-pending; or
• outcome-unknown.

• outcome-unknown says the message may have been sent. The send ended without a typed failure, interrupted or by a defect, the store failed while binding the post’s intent in a way that can follow its commit, or the host’s request failed or timed out after it may have reached the daemon. A request the daemon cannot have acted on, such as one whose connection was refused, fails as network-unavailable.
• delivery-pending says the message will still be sent. The send durably bound its post’s intent, and a later step failed or timed out: queueing its proposal, or its drain. The daemon proposes a bound intent again when the conversation’s head moves or after a restart, and delivers a queued post once the Router answers or, when that failure stopped the daemon, once it restarts and resumes the post.

​

Host ownership

​

Acceptance

• Public type canaries pin exactly the service and values above.
• Address order, self insertion, duplicates, unknown names, and 2/3/32/33 member boundaries are tested.
• Distinct calls with identical input mint distinct posts, and restart recovery retains the persisted post identity for one unfinished intent.
• A send without collective and a send with {op: "multicast"} certify the same content: the text part, then the explicit multicast part.
• parseMessageText reads every operation shape, sends plain text and JSON-looking prose as a multicast, and refuses a malformed operation naming its fields.
• An answer is matched to the one request open in its conversation; none open and several open are refused, and nothing is sent.
• Multicast items carry the certified content without its collective part, and the endpoint consumes records it does not deliver.
• A gather refuses an unknown member before any post, fans out one request post per member, keeps a post certifying past the send wait and counts that member’s answer, makes a refused member no-answer, fails only when every post was refused, ends in exactly one refusal or result, validates answers on both sides, keeps each member’s first answer, completes at the deadline with no-answer outcomes, and ignores a late answer; three real daemons run it end to end.
• An all_gather posts one request to the group, fails naming each unreachable member, closes with the record hash of each counted answer, keeps peer answers from every model until the close, and gives every member the result the close lists; a requester and three members on four real daemons receive identical results, with a silent member reported as no-answer.
• Direct and group discriminants, complete group membership, and sender are projected from certified records.
• Lost acknowledgment replays one stable Client delivery; host qualification establishes the acceptance and replay requirements.
• No public export or MCP adapter path restores a retired turn-grant interface, public conversation identity, inherited target, or proof-shaped success.

​

Local guidance

interface CheckedGuidance {
  readonly checkId: string
  readonly subjects: readonly {
    readonly id: string
    readonly sender: string
    readonly recipients: readonly string[]
    readonly text: string
  }[]
  readonly instructions: readonly (
    | {
        readonly middlewareId: string
        readonly ruleId: string
        readonly expectation: "required" | "permitted" | "wait" | "none"
        readonly subjects: readonly string[]
        readonly instruction: string
      }
    | {
        readonly middlewareId: string
        readonly ruleId: string
        readonly uncertain: {
          readonly choice: string
          readonly probability: number
        }
        readonly instruction: string
      }
  )[]
}

type LocalGuidance =
  | CheckedGuidance
  | {
      readonly question?: CheckedGuidance
      readonly answers: readonly (CheckedGuidance & { readonly member: string })[]
    }