HostService

When to use this pageCopy Anchor Link

You need it when your plugin logs, reports progress, emits evidence, reads referenced artifacts or reaches a customer system with a credential. The mechanism is the same for all of them: the plugin quotes the invocation_id of the Invoke it is serving, and the host decides.

The serviceCopy Anchor Link

service HostService {
  rpc Log(LogRequest) returns (LogResponse) { ... }
  rpc EmitEvidence(EmitEvidenceRequest) returns (EmitEvidenceResponse) { ... }
  rpc RequestCredential(RequestCredentialRequest) returns (RequestCredentialResponse) { ... }
  rpc ResolveReference(ResolveReferenceRequest) returns (stream ResolveReferenceResponse) { ... }
  rpc ReportProgress(ReportProgressRequest) returns (ReportProgressResponse) { ... }
}

HostService is served by the host and called by a plugin during an Invoke. It is never exposed as a model tool and never an action target. Every element is since: "1.0.0" except RequestCredentialResponse.egress_proxy, which is since: "1.1.0".

Invocation-scoped authorityCopy Anchor Link

Every request carries an invocation_id: the ActionContext.invocation_id of the call being served.

• The host assigned that id to this plugin process and still has the call in flight. Any other id is rejected, so a plugin can act only inside the authority of the call it serves.
• The host identifies the calling plugin by the connection it established at launch, never by request content. Quoting someone else's id from another connection does not work.
• Per invocation, at most 256 EmitEvidence, 1024 Log, 1024 ReportProgress, 64 ResolveReference and 16 RequestCredential calls, and 2048 HostService calls in total. A call over any count is rejected and the invocation is recorded FAILED.
• No HostService RPC declares evidence. The host records each call and its outcome in the invocation's evidence.
• Strings are at most 1024 bytes and repeated fields at most 256 entries unless a field says otherwise. Over-limit input is rejected, never truncated. A rejection names an index-based field path and the violated bound, never the offending value.

"Printable" in the rules below means Unicode categories L, M, N, P, S and U+0020; Cc, Cf, Cs, Co, Cn, Zl and Zp (including bidi and zero-width controls) are rejected.

LogCopy Anchor Link

message LogRequest {
  string invocation_id = 1;
  Severity severity = 2;
  Reason reason = 3;
  repeated LogField fields = 4;
}

message LogField {
  string key = 1;
  string value = 2;
}

message LogResponse {}

The log vocabulary is closed on purpose: a plugin cannot smuggle prose or instructions into the host's retained logs. Log has no dry run; the entry is the whole effect.

EmitEvidenceCopy Anchor Link

message EmitEvidenceRequest {
  string invocation_id = 1;
  string emit_key = 2;
  string record_type = 3;
  google.protobuf.Any payload = 4;
  repeated numinance.types.v1.Reference artifacts = 5;
}

message EmitEvidenceResponse {
  string evidence_id = 1;
}

The plugin submits; the host validates and appends under the runner identity. The plugin never appends. The risk is LOW because the host can refuse, while the append itself is the host's.

EmitEvidenceResponse.evidence_id is the ev_ prefixed id of the record the host appended. The plugin lists it in ActionResult.evidence_ids; any id the host did not return for this invocation is rejected there.

Evidence is why a plugin cannot forge a history. It supplies a typed fact about its own work; the host stamps who, under which grant, at what time. See the record chain.

RequestCredentialCopy Anchor Link

message RequestCredentialRequest {
  string invocation_id = 1;
  string intent = 2;
}

message RequestCredentialResponse {
  string handle = 1;
  google.protobuf.Timestamp expires_at = 2;
  string egress_proxy = 3;
}

(Per-field options omitted. handle is annotated sensitive: true; egress_proxy is since: "1.1.0".)

The credential handleCopy Anchor Link

RequestCredential returns a handle for a declared credential intent, never credential material.

Why the plugin never gets a reusable tokenCopy Anchor Link

A plugin that holds a raw token can use it outside the call, copy it, log it or hand it to a model. A handle cannot do any of that: it is bound to one invocation and one intent, it only means something at the egress proxy, and it expires with the call. The proxy applies the real credential on the way out, so the secret never enters the plugin process.

When ActionContext.dry_run is set, the broker issues a handle only for a read-class intent and the egress proxy denies any non-read method on it. The host records dry_run on the invocation's evidence, so a write that happened anyway is flagged on reconciliation.

Credential-issuance records are host-authored evidence kinds: a plugin cannot emit them through EmitEvidence, so the record of what was issued is not the plugin's to write.

ResolveReferenceCopy Anchor Link

message ResolveReferenceRequest {
  string invocation_id = 1;
  numinance.types.v1.Reference reference = 2;
}

message ResolveReferenceResponse {
  bytes chunk = 1;
}

Orchestration payloads carry references and digests, not content. When a plugin needs the bytes, it asks the host to stream them.

• reference must equal (proto.Equal on all three fields) a Reference in a field of the method's input type, found by walking the request with the host's descriptor copy. A Reference inside an Any is never resolvable. Anything else is rejected as not found.
• A reference whose sha256.value equals that of a field the port marks host_only, or of a Reference nested under one, is refused whatever its artifact_type or artifact_ref. The mark is inherited by every Reference nested under a marked message-typed field. For example, authorexecutor worktree_ref and network_policy_ref are host-only.
• Each chunk is at most 64 KiB. The host verifies the object's sha256 against the reference before the first chunk and streams nothing on a mismatch. The total per invocation is at most ActionContext.budget.disk_bytes.
• There are no presigned URLs. The host streams the exact bytes whose sha256 it verified before the first chunk (a pinned object version or a buffered copy).

ReportProgressCopy Anchor Link

message ReportProgressRequest {
  string invocation_id = 1;
  uint64 completed = 2;
  uint64 total = 3;
  Reason reason = 4;
}

message ReportProgressResponse {}

Failure modes and safeguardsCopy Anchor Link

TroubleshootingCopy Anchor Link

• RequestCredential is rejected although the manifest declares the intent: the grant for this call must also allow it. The manifest declares; the grant authorizes.
• EmitEvidence is rejected for a type you declared: the type must be in both your capability's evidence_declared and the host's allow-list of plugin-emittable types.
• A handle works in a unit test but not at run time: the handle is only usable through the egress proxy address in egress_proxy; an empty value means the host runs no proxy and the handle cannot be used.

Next stepsCopy Anchor Link