Build production Code Assist Agent on Runner and Kernel contract

[fractional-pm]

Objective

Build AGenNext Code Assist as a production-grade agent in the AGenNext stack.

This is not an MVP track. The goal is a publishable, production-ready agent that runs through AGenNext Runner and uses AGenNext Kernel-backed execution primitives.

Platform comes later. First we need a production agent that the Platform can configure, operate, and showcase.

Architecture position

AGenNext Code Assist = agent / requester / planner
AGenNext Runner      = runtime enforcement point
AGenNext Kernel      = infrastructure abstraction layer
AuthZEN service      = authorization decision point
Agent ID Protocol    = optional identity/governance context
Audit service        = evidence ledger
Security gates       = production readiness gates

Protocol and framework configuration compatibility

Code Assist does not need to implement protocol clients/servers for every framework.

Code Assist must support configuration metadata and binding context so AGenNext Runner and AGenNext Platform can bind the agent to the required protocols/frameworks.

Required configuration compatibility:

AuthZEN
OpenFGA
OPA
Agent ID Protocol over OIDC
Agent Network Protocol, ANP
Agent Communication Protocol, ACP
Agent Client Protocol
A2A, Agent-to-Agent protocol

Compatibility expectations:

AuthZEN:
  Code Assist exposes decision context fields. Runner calls/enforces the AuthZEN decision.

OpenFGA:
  Code Assist exposes subject/action/resource/context metadata that Runner/AuthZEN can map to object-relation checks.

OPA:
  Code Assist exposes policy context metadata: run mode, branch, requested operation, update mode, gates, audit state, Agent ID context, waiver state.

Agent ID Protocol over OIDC:
  Code Assist supports config for agent DID, owner, role, environment, trust level, capabilities, delegation mode, scope reference, audit/status/deprovision endpoints, and bindings.

ANP, Agent Network Protocol:
  Code Assist supports config fields for discovery, network identity, delegation, trust metadata, and endpoint metadata. Runner/Platform supplies the transport.

ACP, Agent Communication Protocol:
  Code Assist supports config fields for messaging/command/event compatibility. Runner/Platform supplies the transport.

Agent Client Protocol:
  Code Assist exposes stable input/output schemas and invocation config so a client-protocol gateway can call it.

A2A:
  Code Assist supports A2A-style agent card/binding metadata and task invocation schema. Runner/Platform supplies the A2A endpoint/binding.

Important rule:

Do not add direct clients for all protocols inside Code Assist.
Do not make Code Assist a protocol server for all protocols.
Code Assist should expose config, schemas, capabilities, and metadata.
AGenNext Runner/Platform bind those configs to actual protocol transports and enforcement.

Production scope

1. Production agent contract

Define a stable Code Assist Agent request/response contract:

instruction
repo target / issue / PR / discussion / branch URL
file hints
check presets
run mode: dry_run | proposed_change | production_change
requested capabilities
Agent ID context
AuthZEN context
OpenFGA/OPA-compatible policy context metadata
ANP/ACP/Agent Client Protocol/A2A binding metadata
Runner run_id / capability_id
audit trace id
security gate policy
result / checks / diff / change log / artifacts

2. Protocol configuration schema

Add a provider-neutral protocol configuration schema.

The schema should support config sections like:

protocols.authzen
protocols.openfga
protocols.opa
protocols.agent_id
protocols.anp
protocols.acp
protocols.agent_client_protocol
protocols.a2a

Each section should capture:

enabled
required
provider / backend name
endpoint or binding name when relevant
metadata
capabilities/actions supported
input/output schema references
security/auth requirements
timeout/fail-closed policy where relevant

Code Assist should pass this metadata to Runner/Platform context, not own the transport implementation.

3. Runner enforcement integration

Code Assist must request capabilities from AGenNext Runner instead of self-enforcing privileged operations.

Capabilities:

repo.read
repo.write
repo.diff
repo.check
repo.commit
repo.push
repo.open_pr
notify.send
audit.write
security.scan
container.simulate
protocol.invoke
protocol.publish_metadata

Runner owns allow/deny, scoped capability issuance, capability expiry, fail-closed behavior, and execution rights.

4. Kernel execution contract

Code Assist must not directly own infrastructure operations in production. Runner invokes Kernel primitives for:

github-api update
git-cli worktree
filesystem sandbox
process execution
container/docker simulation
secret access
network access
artifact storage
cloud / VM / Docker / Kubernetes deployment targets
protocol transport adapters

5. AuthZEN support

Use the generic AuthZEN adapter already added in:

src/agentnxt_code_assist/authzen.py

Code Assist may construct AuthZEN-compatible context, but Runner is the enforcement point.

6. Agent ID Protocol support

Use the generic Agent ID Protocol module already added in:

src/agentnxt_code_assist/agent_id_protocol.py

Agent ID is optional enrichment unless configured as required for governed agent operations.

7. OpenFGA and OPA compatibility metadata

Code Assist must expose OpenFGA and OPA compatible context, even when they are deployed behind AuthZEN or Runner.

Required metadata fields:

subject
agent identity / Agent ID
organization / project / repository / branch
requested action
requested capability
run mode
update mode
security gate status
audit trace status
waiver status
resource metadata
protocol binding metadata

8. Agent interoperability configuration

Code Assist must expose metadata and request/response shapes that can be bound by Runner/Platform to:

ANP
ACP
Agent Client Protocol
A2A

Required metadata:

agent name
agent DID when available
display name
version
capabilities
supported actions
input schema
output schema
auth requirements
Runner capability requirements
protocol binding config
status/audit/deprovision links when available

9. Production execution loop

Implement focused production passes:

plan
request Runner capabilities
hydrate repo/task context
load optional Agent ID context
prepare bounded memory/RAG context
propose/edit
run required checks
run security gates
simulate Docker/container production path where applicable
collect diff
write changelog
write audit trace
return production-readiness result

10. Hard safety defaults

Default behavior:

no commit
no push
no PR
no merge
no notification
no secret persistence
no write outside Runner-granted scope
no self-authorization
no production-ready status without required gates

11. Mandatory production gates

Production Code Assist must support these gates before being called production-ready:

audit trace gate
secrets scan gate
dependency vulnerability gate
SAST gate
container/Dockerfile gate
IaC/config gate where applicable
SBOM/supply-chain gate where applicable
license/policy gate where applicable
README/code consistency gate
unit/integration/smoke check gate where applicable
Docker Desktop/local production simulation where applicable

Default policy:

critical/high security findings = fail
secret leak = fail
missing audit trace = fail
unknown update path = fail
required Runner/AuthZEN decision unavailable = fail
required Kernel primitive unavailable = fail

12. Audit trace requirement

Every production run must create a trace:

run_id
capability_id
AuthZEN decision reference
OpenFGA/OPA decision references when surfaced by Runner/AuthZEN
Agent ID context reference when available
ANP/ACP/Agent Client Protocol/A2A binding context when used
before/after repo SHA or content hashes
per-file operation records
check results
security gate results
change log path
artifacts
final result

Any changed file without an audit operation record must fail the run.

13. Packaging and publishing

Production build must include:

Dockerfile
Compose profile
health checks
CI tests
GitHub Actions release workflow
GHCR publishing
Docker Hub publishing if configured
versioned release tags
SBOM artifact
security scan report artifact

14. Documentation

Production docs must include:

architecture
Runner contract
Kernel contract
protocol configuration contract
AuthZEN config
OpenFGA compatibility config
OPA compatibility config
Agent ID Protocol config
ANP config
ACP config
Agent Client Protocol config
A2A config
security gates
audit trace model
local development
Docker Desktop simulation
production deployment
release process
operator runbook

Acceptance criteria

• Code Assist runs as a production-grade agent with a stable request/response contract.
• Code Assist requests capabilities from AGenNext Runner and does not self-authorize privileged actions.
• Runner is documented as the runtime enforcement point.
• Kernel is documented as the infrastructure abstraction layer.
• AuthZEN-compatible decision context is supported.
• OpenFGA-compatible relationship context metadata is supported.
• OPA-compatible policy context metadata is supported.
• Agent ID Protocol context is supported as optional/governed enrichment.
• ANP-compatible configuration metadata is supported.
• ACP-compatible configuration metadata is supported.
• Agent Client Protocol-compatible invocation schema/config is supported.
• A2A-compatible agent card/binding metadata is supported.
• Code Assist does not implement unnecessary direct protocol clients/servers.
• Code Assist can run dry-run and production-change modes.
• Production-change mode requires Runner-granted capabilities.
• All file changes are traceable to approved GitHub API or Git CLI paths through Runner/Kernel.
• Required checks and security gates run before production-ready status.
• Critical/high findings and secret leaks fail closed.
• Audit traces are generated for every run and every changed file.
• Docker/Compose/CI publishing path exists and passes.
• The repo is publishable to GHCR and Docker Hub when credentials are configured.
• Documentation is complete enough for an operator to deploy and run safely.

Out of scope for this issue

• Full AGenNext Platform UI
• Multi-agent marketplace
• Enterprise tenant billing
• Direct protocol server/client implementations for ANP/ACP/A2A unless Runner/Platform requires a thin adapter later

These come after the production Code Assist Agent exists.