Skip to content

feat(substrate): converge egress policy on every resume - #291

Open
Anish Ramasekar (aramase) wants to merge 4 commits into
agent-primitives:mainfrom
aramase:aramase/f/egress_policy_converge
Open

Anish Ramasekar (aramase) wants to merge 4 commits into
agent-primitives:mainfrom
aramase:aramase/f/egress_policy_converge

Conversation

@aramase

Copy link
Copy Markdown
Collaborator

Closes #251.

A changed WithEgressPolicy (or -substrate-egress-policy-file) used to reach only actors created after it changed: an actor that already had a policy kept it. The backend now converges each actor's stored policy on the configured one before every resume of a suspended actor, with no opt-out.

  • The backend reads the stored policy and compares it semantically. An unchanged policy means no write; a changed one is replaced with UpdateActorEgressPolicy under the UID and version it read. A conflicting writer starts a new read, up to three attempts, then the call fails as ErrActorBusy.
  • A function that returns no policy clears a stored one to an empty rule set (deny-all) with a preconditioned Update, never a Delete.
  • It applies on Create, Restore, re-attaching a suspended actor, and the stateful fork clone.
  • Backend.SyncEgressPolicy(ctx, sessionUID) applies a changed policy to a running actor without suspending it. Substrate picks it up within its policy caches (about 10 seconds for requests and new connections, 5 seconds for DNS on v1.0.0); an open TLS passthrough connection is not cut. The daemon does not call it.
  • A Substrate router wake resumes an actor without the backend, so convergence runs the next time the backend resumes it.
  • A stored policy the adapter cannot convert is now ErrEgressPolicyInvalid, which reaches callers as FAILED_PRECONDITION / COMPUTE_CONFIG_INVALID with fixed text.

Compatibility (changelog fragment in the Compatibility category):

  • A policy edited in Substrate by anyone else is overwritten at the next resume while the option is set.
  • A custom EgressPolicyClient used with WithEgressPolicy must implement GetActorEgressPolicy and UpdateActorEgressPolicy as well as CreateActorEgressPolicy. A ControlClient without EgressPolicyClient is refused (ErrEgressPolicyUnsupported) on every resume of an existing actor and every Sync, whatever the function returns, instead of resuming with the old policy. The daemon already refused that setup at startup.

Docs updated: the EgressPolicyClient and SyncEgressPolicy docs in runtime/substrate/egress.go, docs/security.md, docs/substrate-conformance.md (with spec and conformance IDs) and spec.md.

Tested:

  • Unit tests against a fake ControlClient cover unchanged, changed, nil-clears, create-exists and update-not-found races, precondition conflicts and retry exhaustion, error classification through Exec, Resume and Fork, fork children, and Sync. The fail-closed refusal for a client without EgressPolicyClient is pinned for Restore, Create attach and Sync.
  • go test -race ./runtime/substrate/... ./session/... and go test -race ./... in integrations/substrate.
  • gofmt, go vet, hack/changelog check, hack/check-doc-links.py and hack/doccheck pass.
  • golangci-lint was not run locally (the installed version cannot type-check Go 1.27); CI runs it. A live Substrate e2e was not run (needs a cluster).

Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
@aramase
Anish Ramasekar (aramase) marked this pull request as ready for review November 20, 2026 09:06
@aramase
Anish Ramasekar (aramase) requested a review from a team as a code owner November 20, 2026 09:06
Copilot AI balanced review requested due to automatic review settings November 20, 2026 09:06

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical races allow stale convergence to restore revoked permissions and let Create/Fork retain an allow policy when the callback returns nil instead of enforcing deny-all.

2 open issues
What changed in this PR

This PR extends the Substrate backend’s egress-policy management so configuration changes reach existing actors before backend-driven resumes, supporting the session isolation work in #251.

Changes:

  • Adds semantic policy comparison, version-preconditioned updates, bounded conflict retries, and deny-all clearing.
  • Introduces SyncEgressPolicy for running actors and classifies unreadable stored policies as configuration errors.
  • Expands lifecycle and error-handling tests, with documentation covering compatibility changes and enforcement limits.
File Description
spec.md Records policy convergence before later resumes.
session/​egress_policy_error_test.go Tests API error classification and safe error text.
runtime/​substrate/​substrate.go Integrates convergence into create, restore, attach, and fork.
runtime/​substrate/​egress.go Implements comparison, convergence, retries, and explicit sync.
runtime/​substrate/​egress_test.go Tests policy changes, clearing, conflicts, and sync behavior.
integrations/​substrate/​egress.go Classifies stored-policy conversion failures.
integrations/​substrate/​egress_test.go Tests conversion-error classification and privacy.
integrations/​substrate/​e2e/​egress_test.go Adds stored-policy checks across resume and running-actor sync.
integrations/​substrate/​cmd/​agentsessionsd/​substrate.go Updates policy-file flag help for convergence behavior.
integrations/​substrate/​cmd/​agentsessionsd/​egress_test.go Tests changed policy files reaching existing actors.
docs/​substrate-conformance.md Documents convergence, sync, cache limits, and coverage.
docs/​security.md Explains policy authority, revocation, and enforcement limits.
changelog/​unreleased/​egress-policy-sync.md Announces the explicit sync API.
changelog/​unreleased/​egress-policy-stored-invalid.md Records stored-policy error classification changes.
changelog/​unreleased/​egress-policy-converge-compat.md Documents changed behavior and client requirements.

Review effort: Balanced

Comment thread runtime/substrate/egress.go Resolved
Comment thread runtime/substrate/egress.go Resolved
@aramase
Anish Ramasekar (aramase) force-pushed the aramase/f/egress_policy_converge branch from 4bb6c9a to cc62da1 Compare November 21, 2026 02:21
Copilot AI balanced review requested due to automatic review settings November 21, 2026 02:21

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A wrapped ErrActorBusy can leak private client diagnostics through Exec/Resume ABORTED errors even with authorization enabled, requiring sanitization via busyRefusal and a regression test.

1 open issue
2 resolved since last review

Review effort: Balanced

Comment thread runtime/substrate/egress.go Resolved
@aramase
Anish Ramasekar (aramase) force-pushed the aramase/f/egress_policy_converge branch from cc62da1 to 08c8d6b Compare November 21, 2026 06:45
Copilot AI balanced review requested due to automatic review settings November 21, 2026 06:45

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The security documentation should distinguish an unset WithEgressPolicy option, which allows an existing actor to resume with its stored policy, from a configured function returning nil, rather than describing removed configuration as fail-closed.

2 open issues

Review effort: Balanced

Comment thread docs/security.md Resolved
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
@aramase
Anish Ramasekar (aramase) force-pushed the aramase/f/egress_policy_converge branch from 08c8d6b to d93ad36 Compare November 21, 2026 08:11
Copilot AI balanced review requested due to automatic review settings November 21, 2026 08:11

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation needs to qualify its stored-policy guarantee because a quick suspend, policy tightening, and resume can still permit traffic under the cached old policy.

1 open issue
2 resolved since last review

Review effort: Balanced

Comment thread docs/security.md Resolved
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
…refusal

Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
@aramase
Anish Ramasekar (aramase) force-pushed the aramase/f/egress_policy_converge branch from d93ad36 to 4d7b85e Compare November 21, 2026 17:40
Copilot AI balanced review requested due to automatic review settings November 21, 2026 17:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Maintainer validation is needed because security-sensitive policy convergence depends on Substrate versioning and gateway-cache behavior, while tests verify stored policies rather than live traffic enforcement or credential injection.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

runtime/substrate: install an egress policy on a session's actor before its compute starts

2 participants