Envelope, ActionContext and ActionResult

When to use this pageCopy Anchor Link

Use it to see exactly what a plugin receives for one Invoke (who it acts as, under which grant and policy decision, with what budget and deadline) and what it may report back. The transport for these messages is PluginService.Invoke.

Rules for the whole fileCopy Anchor Link

• Every element is since: "1.0.0".
• Enums are closed. A consumer rejects the zero value and any unknown number.
• No field carries credential material or content. Large data travels as a types.v1.Reference: references and digests, never content.
• Every string is at most 1024 bytes and every repeated field at most 256 entries unless stated; over-limit input is rejected, never truncated. Duplicates are rejected, keyed as: evidence_ids by value, side_effects by kind and target, diagnostics by all four fields. Every repeated bound applies per invocation across the stream.
• A rejection names an index-based field path and the violated bound, never the offending value.

EnvelopeCopy Anchor Link

message Envelope {
  string method = 1;
  ActionContext context = 2;
  google.protobuf.Any request = 3;
}

Typed AnyCopy Anchor Link

request and ActionResult.result are google.protobuf.Any, but not free-form: the type URL is derived from the method, not chosen by the sender. A request whose type URL is not exactly type.googleapis.com/ plus the method's input type is rejected, and a result must name the method's output type. Decoding is strict and rejects unknown fields. A Reference inside an Any is never resolvable through ResolveReference, which is why references that must be resolvable sit in ordinary fields of the request.

ActionContextCopy Anchor Link

ActionContext is the authority under which one action runs. Every field is set by the host.

message ActionContext {
  string invocation_id = 1;
  string change_id = 2;
  string run_id = 3;
  numinance.types.v1.PrincipalKind actor_kind = 4;
  string actor_principal = 5;
  string grant_id = 6;
  string policy_decision_id = 7;
  numinance.types.v1.Digest plan_digest = 8;
  numinance.types.v1.Digest profile_digest = 9;
  string idempotency_key = 10;
  google.protobuf.Timestamp deadline = 11;
  ResourceBudget budget = 12;
  numinance.types.v1.ResidencyClass residency = 13;
  bool dry_run = 14;
}

Grants and policy decisionsCopy Anchor Link

grant_id and policy_decision_id are how capability-based authority reaches the plugin. The policy decision (DecisionOutcome is ALLOW, DENY or REQUIRE_APPROVAL) is made by the host outside the model before dispatch. The plugin receives only the ids of an allow, never the ability to produce or alter one. A plugin has no way to widen its grant: the context is host-set, and HostService calls are accepted only for an invocation_id the host has in flight. See Authority and policy.

LimitsCopy Anchor Link

Limits arrive as deadline and budget and are enforced by the host, not requested by the plugin.

ResourceBudgetCopy Anchor Link

message ResourceBudget {
  uint64 cpu_millicores = 1;
  uint64 memory_bytes = 2;
  uint64 disk_bytes = 3;
}

A zero value means the host default in a manifest declaration; in ActionContext.budget every field is non-zero. disk_bytes also caps the total bytes ResolveReference may stream in one invocation.

ActionResultCopy Anchor Link

ActionResult is what the plugin reports. Every field is a claim the host checks or records, never trusts.

message ActionResult {
  InvokeStatus status = 1;
  google.protobuf.Any result = 2;
  repeated string evidence_ids = 3;
  repeated ObservedSideEffect side_effects = 4;
  bytes compensation_token = 5;
  ResourceBudget cost = 6;
  google.protobuf.Duration duration = 7;
  repeated Diagnostic diagnostics = 8;
}

A RUNNING message carries status and diagnostics only (plus the stream message in result on a server-streaming target).

What the host does with a claimCopy Anchor Link

ObservedSideEffectCopy Anchor Link

message ObservedSideEffect {
  SideEffect kind = 1;
  string target = 2;
}

kind is a SideEffect (NONE is rejected here). target identifies the external resource, printable characters only; it is untrusted and rendered delimited and labelled.

SideEffectCopy Anchor Link

enum SideEffect {
  SIDE_EFFECT_UNSPECIFIED = 0;
  SIDE_EFFECT_NONE = 1;
  SIDE_EFFECT_READ = 2;
  SIDE_EFFECT_WRITE = 3;
  SIDE_EFFECT_DELETE = 4;
  SIDE_EFFECT_DEPLOY = 5;
}

READ reads external state, WRITE creates or changes it, DELETE removes it, DEPLOY changes what runs in an environment.

DiagnosticCopy Anchor Link

message Diagnostic {
  Reason reason = 1;
  Severity severity = 2;
  string field_path = 3;
  string subject = 4;
}

A diagnostic has no free text. field_path is empty or starts with the literal request or response, resolves segment by segment against the method's input or output type in the host's descriptor copy (for example request.items[3].name), matches ^[a-z][a-z0-9_]*(\[[0-9]+\])?(\.[a-z][a-z0-9_]*(\[[0-9]+\])?)*$ and is at most 256 bytes. subject is empty or a full name, at most 256 bytes, that resolves in the host's registry to an element of a numinance.ports.* or numinance.plugin.v1 file (for example numinance.ports.scm.v1.GetFileRequest.path). A diagnostic that fails either check is rejected and never rendered.

EnumsCopy Anchor Link

InvokeStatusCopy Anchor Link

InvokeStatus is how the plugin reports a call; the host derives the evidence/v1 ActionOutcome itself and never trusts the claim.

SeverityCopy Anchor Link

Severity is the severity of a diagnostic or log entry.

ReasonCopy Anchor Link

Reason is the closed vocabulary of diagnostics, log entries and progress reports; there is no free text. The outcomes (REASON_DEPRECATED through REASON_CANCELLED) are valid in Diagnostic and Log; the phases (REASON_STARTED through REASON_COMPLETED) are valid in ReportProgress and Log; a value added later is placed in a subset by its name in this comment, never by its number; the host rejects a value outside the subset of its consumer. This enum may grow.

Example: an envelope for a readCopy Anchor Link

This is an illustration of which values the host fills for a read-only call. It is not captured output.

method:              /numinance.ports.scm.v1.ScmService/GetFile
context.invocation_id:     inv_<32 lowercase hex characters>
context.actor_kind:        PRINCIPAL_KIND_AUTHOR_AGENT
context.grant_id:          grant_...
context.policy_decision_id: dec_...
context.dry_run:           false
request:             Any, type URL type.googleapis.com/numinance.ports.scm.v1.GetFileRequest

Failure modes and safeguardsCopy Anchor Link

Next stepsCopy Anchor Link