RFC 0003: Agent-model runtime optimization profiles

[ericksoa]

RFC 0003: Agent-Model Runtime Optimization Profiles

• Status: Draft.
• Author: Aaron Erickson.
• Created: 2026-08-24.
• Discussion: #10449.
• Related design: RFC 0001 managed inference serving specifications discussion #7636 and RFC 0002 modular agent runtime integration packages discussion #9909.
• Related implementation: model-specific setup architecture issue #3120, agent-scoped registry PR #3121, model capability audit PR #5528, Deep Agents profile plugin PR #6431, and Nemotron Ultra request safeguards PR #6494.
• Implementation: Partial mechanisms exist. The common contract is not implemented.

Decision requested

NemoClaw should add a public, versioned contract that selects at most one agent-runtime optimization profile, or an explicit no-profile result, for a resolved agent runtime and inference route.

An optimization profile can configure model-specific request behavior, tool exposure, a native harness profile, middleware, or a plugin. Optimization does not mean performance only. A profile can establish compatibility, prevent an invalid tool call, or improve a measured outcome.

Maintainers are asked to accept these decisions:

• The agent runtime integration package owns each profile and its native artifacts.
• NemoClaw core owns one agent-neutral compiler and resolver.
• The resolver consumes inference and managed-serving identity. It does not select a provider, model, endpoint, serving backend, or compute platform.
• RFC 0003 extends the plans, helper protocol, support catalog, and lifecycle authority from RFC 0002. It does not create parallel versions of them.
• A new profile that uses an existing package application contract adds no agent-specific production code to src/lib/**.
• The resolver selects zero or one complete profile. It does not merge matching profiles or use priority to resolve overlap.
• Profiles match pinned identities. Version 1 does not support model-name prefixes, regular expressions, wildcards, or dynamic Model Router pools.
• The RFC 0002 support catalog remains the only admission authority. Qualification evidence, product status, selection mode, and artifact eligibility remain separate fields.
• Normal product workflows do not accept arbitrary profile overrides or remote profile sources.

Acceptance establishes architecture direction. It does not change current support or qualify a new model, profile, route, agent runtime, serving recipe, or platform.

Why this is needed

NemoClaw already has two versions of this idea.

The first is the agent-scoped registry under nemoclaw-blueprint/model-specific-setup. It matches OpenClaw or Hermes with model and route fields. OpenClaw records can set compatibility fields, tool behavior, and plugins.

The second is the LangChain Deep Agents Code profile plugin under agents/langchain-deepagents-code/profile-plugin. It maps NemoClaw-managed Nemotron 3 Ultra keys to a reviewed native Deep Agents profile. It also adds a narrow malformed-tool-call guard.

These implementations prove that:

• The same model can need different behavior in different agent runtimes.
• A declarative selector can activate agent-owned executable behavior.
• Runtime versions, artifacts, negative tests, live trajectories, and removal conditions matter.
• Agent-specific behavior should not become a global inference-proxy rewrite.

The mechanisms do not form one subsystem today:

• The current schema hardcodes OpenClaw and Hermes effect fields.
• OpenClaw and Hermes have separate discovery and merge implementations.
• Deep Agents Code has a separate registry, alias map, source gate, and test suite.
• Fresh OpenClaw configuration consumes the registry, but nemoclaw inference set does not.
• Persisted state does not identify the selected optimization.
• The model capability audit defines useful evidence, but it is not a machine-checked selection input.

This split permits lifecycle drift. Fresh setup can apply behavior that an inference switch omits. A dependency update can preserve the model string while invalidating the native profile. Status can report a model without reporting the behavior required to use it.

RFC 0002 gives agent-specific behavior a package owner. RFC 0003 defines how NemoClaw selects and qualifies that behavior for a model route.

Ownership

Responsibility	Owner
Model and provider selection	Existing NemoClaw inference workflow
Model artifact, server image, chat template, parser, serving arguments, readiness, and topology	Managed inference serving catalog
Model-specific native agent behavior and artifacts	Agent runtime integration package
Generic profile compilation, resolution, provenance, and workflow coordination	NemoClaw core
Profile admission and support decision	RFC 0002 support catalog
Provider state, credential custody, inference interception, effective policy, sandbox state, and sandbox lifecycle	OpenShell

The managed inference catalog answers: Which model server and model configuration should NemoClaw run?

The optimization profile answers: How should this agent runtime use that resolved route?

A profile can require a named serving preset or recipe when behavior depends on a chat template or parser. It cannot patch that recipe. A serving recipe cannot install agent-native behavior.

Contract

Resolved inference identity

Inference resolves before optimization. The inference subsystem provides one secret-free identity with these fields:

• Operator-selected provider identifier.
• Gateway live-route provider and model.
• In-sandbox provider key and route profile.
• Canonical model identifier and provider revision when available.
• API family.
• Endpoint descriptor.
• Managed serving catalog, preset, recipe, model revision, and runtime-image identities when present.

The optimization resolver does not reconstruct one identity from another. This matters because OpenClaw maps several upstream providers to its in-sandbox inference key, while Deep Agents Code consumes both the managed provider and upstream provider identities.

Version 1 supports only a route resolved to one model. Model Router requires a later contract with an immutable pool digest, declared members, route policy, and qualification for every member.

Optimization profile

An optimization profile is immutable. It names pinned runtime versions, selectors, one package application contract, an acceptance contract, and a removal condition.

This abbreviated example shows the proposed shape:

apiVersion: nemoclaw.nvidia.com/agent-runtime-optimization/v1
kind: AgentRuntimeOptimizationProfile

metadata:
  id: langchain-deepagents-code.nemotron-3-ultra.managed.v1
  displayName: Nemotron 3 Ultra managed Deep Agents profile
  publisher: NVIDIA
  license: Apache-2.0

spec:
  agentRuntime:
    packageId: langchain-deepagents-code
    packageContract: 1
    runtimeVersions: ["0.1.55"]

  selection:
    modelIds:
      - nvidia/nemotron-3-ultra-550b-a55b
      - nvidia/nvidia/nemotron-3-ultra
    operatorProviderIds:
      - nvidia-prod
      - openrouter-api
      - compatible-endpoint
    inSandboxProviderKeys: [inference]
    inSandboxRouteProfileIds: [inference-local]
    inferenceApis: [openai-completions]

  application:
    contractId: deepagents.harness-profile
    contractVersion: 1
    input:
      nativeProfileKey: nvidia:nvidia/nemotron-3-ultra-550b-a55b
      managedAliasKeys:
        - openrouter:nvidia/nemotron-3-ultra-550b-a55b
        - openai:nvidia/nemotron-3-ultra-550b-a55b
        - openai:nvidia/nvidia/nemotron-3-ultra
        - openrouter:nvidia/nvidia/nemotron-3-ultra
      forceNonemptyContent: true
      rejectedExecutePlaceholder: "[content]"

  objective:
    observedInvalidState: reasoning and tool calls can produce empty assistant content or a literal execute placeholder
    acceptanceCriteriaRef: acceptance/dcode-nemotron-ultra-managed-v1.yaml
    removalCondition: a reviewed dependency supplies equivalent behavior and passes the accepted trajectory without this profile

Each provider selector names its layer. For example, operatorProviderIds, gatewayProviderIds, and inSandboxProviderKeys are different fields. The generic field providerIds is invalid.

A profile may list several models. The list defines technical applicability, not a qualified Cartesian product. The support catalog binds every admitted model and route context to context-specific evidence.

Profile input is declarative data. It cannot contain executable source, shell fragments, unrestricted commands, command templates, environment expansion, credentials, policy patches, OpenShell operations, or remote artifact selectors. Only the registered package application contract may dispatch reviewed bundled code.

Compilation and resolution

The build compiles package-owned profile YAML into canonical packaged JSON. The compiled envelope records schema and compiler versions, profile and source digests, package release identities, application schemas, and source provenance.

The runtime does not scan URLs, the current directory, home directories, restored state, workspaces, or mutable package registries.

For a new selection, the resolver:

1. Validates the package release and contract.
2. Validates the resolved inference and serving identity.
3. Loads profiles owned by that package.
4. Establishes a matching support entry or protected qualification authorization.
5. Matches runtime, model, named provider layers, API, endpoint, and serving fields.
6. Applies product status, selection mode, and eligibility.
7. Fails if more than one profile remains.
8. Validates the receipt or bounded qualification authorization.
9. Writes AgentRuntimeOptimizationSelectionV1 into the generic RFC 0002 runtime plan.

File order, description text, and computed specificity do not affect selection.

No match has three possible results:

• A supported context that requires a profile fails before effects.
• A qualified explicit no-profile context proceeds.
• An unsupported custom route follows its existing policy and reports that no qualified optimization was selected.

Package application contract

Each package declares its application contracts in the RFC 0002 operation registry. RFC 0003 does not add another helper or operation protocol.

Each contract version declares:

• The package-owned contract identifier and version.
• The generic operation-envelope protocol major.
• Input, result, and postcondition schema digests.
• Pinned helper, plugin, middleware, or artifact identity.
• The config keys, files, or native registry namespace it may control.
• Idempotence and restart behavior.
• A bounded reconstruction contract.
• Core or OpenShell observer references.

Application and reconstruction input remains declarative. The operation registry cannot provide a shell rollback hook or turn profile fields into commands.

The profile supplies the operation-specific input. Core validates and digests the input but does not interpret agent-native fields. The request and result use AgentRuntimeOperationRequestV1 and AgentRuntimeOperationResultV1 from RFC 0002.

An application can generate package-owned configuration, activate a bundled plugin or native profile, register model aliases, set request fields, narrow a tool mode, or add bounded in-process middleware.

It cannot download code, change provider or credential state, patch a serving recipe, widen policy, call OpenShell directly, own sandbox lifecycle, or modify another agent runtime.

Observation and product state

The helper result is the executor's claim. It does not independently establish product state.

Core and OpenShell own a small generic observer registry. Profiles may declare observable files, process identities, local endpoints, or canonical configuration projections. Profiles cannot add trusted observer code.

A helper, plugin, package command, or agent-runtime command that reports its own state remains an executor claim, even when core invokes it. A trusted postcondition requires direct core or OpenShell observation of an external file, process, endpoint, or canonical projection. Behavioral agent invocations can produce qualification evidence, but they cannot independently establish native configuration state through self-reporting.

A supported automatic profile needs enough independent observations to establish every state claim required by status, rebuild, restore, or recovery. If the supported OpenShell baseline lacks an observer, the profile remains candidate-only unless the support catalog records a reviewed limitation on the claim NemoClaw may make.

The optimization selection is a nested field in the generic RFC 0002 startup, capability, and operation plans. It does not create a new state store.

A plan authorized only for initial qualification carries an evidence-only classification. It may execute the authorized protected workflow and produce a receipt. It cannot establish support, normal automatic selection, or a normal selectable deployment.

Adding an optimization

The public contribution contract includes JSON Schemas, a deterministic compiler, resolver fixtures, package conformance fixtures, an explanation result, and a qualification template.

Every contribution follows this sequence:

1. Add the profile, application input, artifacts, and tests under the owning package.
2. Run schema, compiler, package-boundary, and application conformance checks.
3. Prove the selected agent runtime, inference identity, model behavior, owned projection, and negative boundaries.
4. Obtain bounded protected qualification authorization for the named package, profile, context, workflow, limits, and expiry.
5. Run that workflow and produce an immutable receipt.
6. Add a candidate, qualification-only, and active support entry that pins the receipt.
7. Promote that entry through a separate support decision.

Publication, conformance, qualification authorization, evidence, candidate admission, and supported promotion are separate results.

After the framework exists:

• A profile that uses an existing package application contract adds no production TypeScript to src/lib/**.
• New native behavior may add code inside the owning agents/<id>/** package.
• A new core contract requires an independent agent-neutral change with at least two substantially different consumers.

Package-owned source should use this shape:

agents/<agent-runtime>/
  manifest.yaml
  optimizations/
    profiles/
    schemas/
    artifacts/
    acceptance/
    qualifications/

An external package can use the same contract after RFC 0002 supplies the external release, provenance, and conformance path. NemoClaw still admits only pinned package and profile releases through its repository-owned support catalog.

Versioning

The contract keeps these versions separate:

• Profile schema major.
• Agent runtime package contract major.
• Generic operation-envelope protocol major.
• Package application contract identifier and version.
• Input, result, and postcondition schema digests.
• Immutable profile identifier and digest.
• Pinned upstream agent runtime version.

Any selector, input, objective, lifecycle, or behavior change creates a later profile version. Adding a model also creates a later version because it expands the qualification set.

Rebuild and restore require the recorded application contract and schema digests. If they are unavailable, the workflow can use only a repository-authorized replacement for the same inference identity.

Qualification and support

The RFC 0002 support catalog owns three independent fields:

• productStatus: supported | candidate
• selectionMode: automatic | qualification-only
• eligibility: active | superseded | revoked

Normal workflows accept only supported, automatic, and active. Protected qualification may accept candidate, qualification-only, and active.

Initial qualification cannot require a receipt that does not exist. The protected qualification authority first issues a bounded authorization. The resulting plan is evidence-only and cannot create admitted product state. The run produces the receipt. The catalog can then add a candidate entry that pins it.

Each receipt binds:

• NemoClaw commit.
• Integration package release, upstream runtime, image, profile, and schema digests.
• Operator provider, gateway route, in-sandbox provider, model, API, and endpoint descriptor.
• Serving provenance when present.
• OpenShell release, compute driver, platform, and scenario suite.
• Behavior results, timing and retry observations when material, and secret-absence results.

One receipt may cover several contexts only when it names and evaluates each context.

For an immutable model or serving revision, receipt validity lasts until catalog supersession or revocation. A revision-opaque hosted route uses a provider contract, endpoint descriptor, observation time, and validUntil. Resolution rejects expired or drifted evidence. Requalification creates a later receipt and catalog revision.

An expired running deployment is reported as ineligible. RFC 0003 does not terminate it automatically.

Lifecycle and recovery

Optimization selection is part of the existing inference workflow, not a best-effort post-step.

Operation	Required result
Fresh onboarding	Resolve inference, compile the selection into AgentRuntimeStartupPlanV1, apply it through the RFC 0002 helper, observe the result, then persist the generic plan identities.
nemoclaw inference set	Validate and journal the candidate before route mutation. Commit desired route and selection, apply the package projection, and observe it. Post-commit failure enters rebuild-recoverable state.
Restart	Reuse a converged recorded selection. Pending state must recover before profile-dependent use.
Rebuild or restore	Validate the recorded selection, application schemas, evidence validity, eligibility, and rematerialization policy. Reconstruct package-owned config and merge only declared user-owned fields.
Clone	Preserve the selection only when package, platform, and inference identities remain compatible.
Runtime upgrade	Require an active support entry and receipt for the selected later runtime.
Status	Compare recorded selection, observed state, transition phase, eligibility, and receipt validity without mutation.

Current nemoclaw inference set commits the OpenShell route and registry before its crash-prone in-sandbox config write. RFC 0003 keeps that recovery direction. It does not require unsafe reverse mutation after the durable commit.

RFC 0003 requires the RFC 0002 lifecycle owner to add a generic crash-transition journal to existing product state. This is new shared lifecycle state under the existing authority, not a new authority or optimization-specific store.

Before the first external mutation, that journal records:

• Transition identifier.
• Prior and candidate inference identities.
• Prior and candidate optimization selections.
• Generic operation and package application identities.
• Current transition phase.

Phases are prepared, route-mutated, registry-persisted, application-completed, process-converged, observed, and complete. A classified failure records recovery-required and the last completed phase.

If the process exits between OpenShell route mutation and local registry persistence, the prepared journal preserves both intended identities. Recovery compares the journal with the live route, registry, package projection, and process state before another mutation.

Supersession and replacement

New selection never chooses a superseded or revoked profile.

A recorded superseded selection may be rematerialized only when its rematerializationPolicy permits the operation before expiry. A revoked selection cannot be selected or rematerialized.

The catalog may name one replacement. The replacement must preserve the complete resolved inference identity and have its own active profile, receipt, and reconstruction contract. A provider, model, endpoint, API, gateway route, or serving change uses the ordinary inference-selection workflow as a separate operator decision.

If no qualified replacement exists for the same inference identity, the operation fails and names the remediation owner.

Security and precedence

Profiles and compiled plans contain no provider credentials. The runtime does not load profile data or code from user-writable or remote sources.

The package contract declares the owned projection it controls. Precedence is:

1. OpenShell policy and NemoClaw product restrictions.
2. A more restrictive explicit user choice.
3. An accepted optimization safeguard within its package-owned projection.
4. Package defaults.

An optimization may narrow a less restrictive preference only when the support entry declares the safeguard and diagnostics report the effective result. It cannot widen user intent, grant a tool, replace a credential or provider, or write outside its projection.

If required profile behavior conflicts with explicit user intent, resolution fails before configuration effects.

User experience

Supported automatic selection requires no new flag.

Onboarding and status report:

• Agent runtime and version.
• Provider, model, API, and serving profile.
• Optimization identifier, objective, and selection reason.
• Qualification receipt, validity, and requalification result.
• Restart requirement and transition phase.
• Independently observed state and executor-only limitations.

An explicit no-profile result says that the combination was qualified without model-specific behavior. An unqualified custom route says that no qualified optimization was selected.

Version 1 has no public arbitrary profile override. Candidate testing uses protected qualification authority.

Delivery sequence

1. Extend RFC 0002 contracts. Add profile schemas, compiler, resolver, nested selection, qualification receipt, generic crash-transition journal, public fixtures, and architecture checks. Add no agent-specific behavior change.
2. Migrate Deep Agents Code. Preserve its pinned version gates, reviewed source digests, native profile, aliases, request parameter, malformed-call guard, and live validation.
3. Admit new runtime optimizations. Pi, DeepSeek Harness, and future packages can use the accepted contract without waiting for OpenClaw migration.
4. Migrate OpenClaw after its RFC 0002 package migration. Translate current model-specific records and prove fresh setup, inference switching, rebuild, clone, restore, and upgrade parity.
5. Enable external packages. Do this only after RFC 0002 supplies pinned external release, provenance, and conformance contracts.
6. Remove the legacy registry. Remove duplicate OpenClaw and Hermes readers after no active consumer uses the old path.

Hermes does not receive an optimization merely to prove the design. Add one only from Hermes-specific evidence.

Validation

The implementation must test four boundaries.

Boundary	Required tests
Catalog and resolver	Strict schemas, deterministic digests, pinned identity fields, ambiguity, no-match, receipt expiry, provider and endpoint drift, Model Router rejection, evidence-only authorization boundaries, executable-input and credential rejection, control-character rejection, unknown application and schema versions, mutable-artifact rejection, and external conformance parity.
Package application	Envelope and application version separation, schema and artifact digests, owned projection, idempotence, partial application, reconstruction, unrelated-model isolation, and denial of provider, credential, policy, OpenShell, and compute changes.
Lifecycle	Fresh setup parity, journal crash injection at each phase, inference-set post-commit recovery, restart, rebuild, restore, clone, upgrade, supersession, replacement, and status drift.
Agent behavior	Baseline chat, structured tool calls, correlated results, final response, multi-turn continuation, applicable subagent and UI paths, failure and retry behavior, policy denials, and credential non-disclosure.

An optimization claim needs an accepted before-and-after evaluation with the same runtime, route, model, serving identity, task set, and limits. Runtime selection uses the catalog decision, not a live score.

Passing schema or conformance tests does not establish model compatibility or product support.

Non-goals

RFC 0003 does not:

• Select or change a model, provider, endpoint, serving recipe, or compute platform.
• Replace the managed inference catalog or RFC 0002 package architecture.
• Load arbitrary host-side or remote executable code.
• Define a marketplace or independent profile installation command.
• Treat conformance, a match, or a successful configuration write as support.
• Generalize behavior that applies to every model. That belongs in the package baseline.
• Support dynamic model pools or request-time profile switching in version 1.
• Automatically terminate an ineligible running deployment.

Open questions

• Which component produces the canonical endpoint descriptor for custom providers?
• Which serving fields participate in matching when behavior depends on a chat template or parser?
• Which generic observers are available on the supported OpenShell baseline?
• How should one gateway agent record profiles for several logical-agent model bindings without global-effect conflicts?
• Which custom-provider workflows may proceed without a qualified profile?
• Who owns the qualification receipt schema, evidence retention, and external conformance release?
• What compatibility window applies to earlier application contracts used by rebuild and restore?
• Which current OpenClaw prefix-based records must expand into listed model identifiers?
• When can the general AgentQualification fixture move out of managed inference ownership?

[ericksoa]

RFC 0003 Revision Note

The original migration, validation, alternatives, and open-question appendix was folded into the Discussion body on 2026-08-26 during an editorial pass. The shorter body preserves the accepted design contracts and is now the complete RFC.

This comment remains to preserve existing links.

[cv]

The build compiles package-owned profile YAML into canonical packaged JSON.

Not sure why we should move from one format to another, save from some parsing considerations.