Skip to content

refactor: remove model API proxy and require native protocols #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SaladDay merged 12 commits into from
Sep 29, 2026
Merged

refactor: remove model API proxy and require native protocols #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
8ce525b
docs: define unified model configuration protocol
SaladDay Sep 29, 2026
fad8f80
Merge remote-tracking branch 'origin/main' into codex/model-protocol-…
SaladDay Sep 29, 2026
762133b
refactor: expose native model protocols as one client support list
SaladDay Sep 29, 2026
74441d1
fix: restrict model configuration to declared native protocols
SaladDay Sep 29, 2026
3f4dcdc
refactor: remove model proxy and require native provider protocols
SaladDay Sep 29, 2026
5206b8a
docs: regenerate native model support references
SaladDay Sep 29, 2026
bc44084
fix: reject unsupported model defaults without credential errors
SaladDay Sep 29, 2026
7cf804e
refactor: bind shared model configuration to every harness entry
SaladDay Sep 29, 2026
6687a06
docs: centralize model configuration obligations in shared contract
SaladDay Sep 29, 2026
b4c0b61
docs: regenerate shared harness configuration references
SaladDay Sep 29, 2026
f6d2587
Merge remote-tracking branch 'origin/main' into codex/model-protocol-…
SaladDay Sep 29, 2026
1b1d6c2
docs: pin merged guide sources
SaladDay Sep 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 39 additions & 30 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ one canonical owner, listed below; update that owner when changing its contract.
| API callers, credentials and route inventory | [API index](docs/api/README.md) |
| Public wire types and qualified behavior | [Agents API contracts](contracts/agents-api/README.md), [pinned upstream](contracts/agents-api/upstream.json), and linked operation contracts |
| Runtime messages, receipts and failure ownership | [Core–Runtime protocol](docs/runtime-protocol.md) and `internal/agentdaemon/proto` |
| Harness interfaces and onboarding | [Harness onboarding](contracts/agents-api/harness-onboarding.md) and `agent/harness.go` |
| Harness interfaces and onboarding | [Harness onboarding](contracts/agents-api/harness-onboarding.md) and `apps/parsar-daemon/internal/agent/harness.go` |
| Provider interfaces and onboarding | [Sandbox Provider guide](docs/sandbox-provider.md) and `sandbox/sandbox_provider.go` |
| Claude private bridge and Runtime artifact | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) |
| Operator installation and configuration | [Installation](docs/getting-started/install.md), [configuration](docs/configuration.md), [operations](docs/getting-started/operations.md) |
Expand Down Expand Up @@ -2779,25 +2779,18 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
identity; retries cannot replace it. Keep this administrator query separate from
runtime observations and do not touch activity or wake sandboxes. The versioned
contract is `contracts/agents-api/execution-configuration.md`.
- Model communication uses `internal/modeltransport` in the Runtime. Core sends one
frozen confidential `model_provider` bundle, independent of engine and placement;
it must not manufacture native provider options or retain a historical-options
dispatch path. The adapter declares native protocols. Native matches connect
directly; mismatches use one private loopback endpoint owned by the existing
Session execution resource. Its credential is distinct from the upstream key.
Keep endpoint cleanup on final native teardown, including preparation failure,
rather than on individual Turn completion. No second Session manager is added.
CLIProxyAPI's pinned translator is an embedded conversion dependency, not a
gateway service. Requests, JSON responses and incremental SSE events share the
same conversion implementation for hosted and self-hosted execution. The
dependency owns protocol fields, tools, reasoning and usage conversion. Do not
add local field maps, parameter restoration or parallel compatibility rules.
Keep SDK format selection, HTTP/SSE framing, limits, cancellation and resource
cleanup here. Pin dependency versions and qualify upgrades with contract and
native engine tests; document upstream limitations instead of silently promising
lossless conversion. Preserve model identity, reject incomplete streams and
never redirect upstream credentials. See `contracts/agents-api/model-protocol-conversion.md` for coverage,
limits and dependency qualification. Go 1.26.8 is the pinned build toolchain.
- Model communication uses native direct connections only. Core sends one frozen
confidential `model_provider` bundle, independent of engine and placement;
adapters apply it through their native provider configuration. The shared
`internal/harnessconfig` descriptor declares one ordered `protocols` list,
with the first entry as the default. Core admission and Runtime enforce it.
There is no built-in model API proxy, passthrough gateway or cross-protocol
conversion, including inside individual Harnesses. Unsupported combinations
fail explicitly; saved configurations and immutable Session snapshots are
never rewritten, aliased or migrated to another protocol. Provider validation,
credential encryption, capability checks and native lifecycle ownership remain
mandatory. See `contracts/agents-api/model-execution.md` for the current
protocol matrix. Go 1.26.8 is the pinned build toolchain.
- Provider input validation uses the adapter-owned rules in `internal/harnessconfig`.
Keep one internal registry for protocol and token-limit validation; Core owns
credential environment and endpoint admission policy. These rules are not a
Expand Down Expand Up @@ -3379,9 +3372,11 @@ or containment of descendants that deliberately leave the group.

### Harness qualification and onboarding

`apps/parsar-daemon/internal/agent/harness.go` is the single source entry point
`apps/parsar-daemon/internal/agent/harness.go` owns the lifecycle entry point
for Harness authors. Keep required lifecycle declarations, separate optional
interfaces and the existing registration methods there. Operation result types,
interfaces and the existing registration methods there. Model configuration has
one shared contract in `internal/harnessconfig/harness.go`, referenced by that
lifecycle entry point and consumed by Core without importing daemon internals. Operation result types,
errors and Registry lookup/storage implementation may remain in focused files.
Use the existing `proto.SupportedAgentKind` and `AgentKindCapabilities` schema;
do not introduce a second capability descriptor or a combined optional interface.
Expand Down Expand Up @@ -3596,15 +3591,29 @@ Keep the adapter artifact independent of the Core binary and product sources.

### Harness model configuration

The configuration preparation contract in `apps/parsar-daemon/internal/agent/harness.go`
is mandatory for every Executor factory. Shared wire types live in
`internal/agentdaemon/proto`; native model fields and their application are documented
in [Harness onboarding](contracts/agents-api/harness-onboarding.md#native-model-configuration).
The standalone Core build includes the shared `internal/modeltransport` route
qualification code alongside the adapter declarations; Runtime still owns proxy
startup and request forwarding.
Public configuration sources and inheritance belong to
`internal/harnessconfig/harness.go` is the sole authoring entry point for the
model configuration contract: its declaration and pure preparation cover the
current model, provider and native parameters. `RegisterKind` requires an explicit
adapter-owned declaration; direct, preparation and Executor registrations all run
that declaration's preparation before calling native code. Registry wrappers
transfer the same declaration, never reconstruct it from a second support table.
Core admission and support descriptions consume it too. JSON decoding, persistence
and native rendering may remain in focused implementation files.
Shared wire types remain in `internal/agentdaemon/proto`; current fields and
application are documented in
[Harness onboarding](contracts/agents-api/harness-onboarding.md#native-model-configuration).
Adapters configure direct native connections. Claude's private bridge receives
compiled native options and performs structural checks, not a second copy of
the Go declaration's enum, budget or combination rules.
Implemented public configuration sources and inheritance belong to
[model execution](contracts/agents-api/model-execution.md).
[Unified model configuration design](contracts/agents-api/model-configuration-design.md)
is the canonical planned field/ownership contract. Extend Web defaults and the
public API by extending the existing shared contract, types and resolver;
source and authority may differ. Implement planned fields and qualify their
native application before exposing them as accepted HTTP input. This design
does not change current native configuration or require speculative Runtime
scaffolding or a second configuration registration interface.

### Harness selection and Agent defaults

Expand Down
24 changes: 12 additions & 12 deletions apps/docs/content/docs/admin-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ resource inspection, Project and key management, credential issuance, audit, usa
and sandbox operations. It never calls `/v1` or `/api/v1`, and has no Agent
execution, copy or arbitrary asset editing operation.

Core request failures use the [Core administration error envelope](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/core-errors.md),
Core request failures use the [Core administration error envelope](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-errors.md),
including optional typed safe details. Console sign-in endpoints retain their
separate error shape described below.

Expand Down Expand Up @@ -49,9 +49,9 @@ label, but could set any value. Never use it for authorization or as proof of
origin.

Web calls Core only through the typed Core clients in `packages/agents-client`:
[AdminClient](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/packages/agents-client/src/admin-client.ts) (`/core/v1`),
[AdminClient](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/packages/agents-client/src/admin-client.ts) (`/core/v1`),
`SandboxAdminClient` (`/core/v1/sandbox`) and `CoreMetricsClient`
(`/core/v1/metrics`). See [the complete administrator reference](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/admin-api.md)
(`/core/v1/metrics`). See [the complete administrator reference](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md)
for methods, fields, filters, pagination and response shapes.
Routes below are relative to `/core/v1`:

Expand All @@ -62,8 +62,8 @@ Routes below are relative to `/core/v1`:
| Resource lists/details/deletion | `/projects/{id}/agents`, `/sessions`, `/environment-templates`, `/skills`, `/files`, `/vaults`, including the documented nested reads |
| Asset ownership | `GET /projects/{id}/resource-owners` with batched resource IDs |
| Key operation history | `GET /projects/{id}/write-operations` with key/resource/time filters |
| Executor credentials | `GET/POST /projects/{id}/environments/{environment_id}/executor-credentials`, `DELETE …/executor-credentials/{key_id}` ([contract](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/environment-executor-credentials.md)) |
| Deployment model configuration | `GET /harnesses`, `GET/PUT/DELETE /harnesses/{harness}/model-configuration`; the key is write-only ([contract](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/model-execution.md#deployment-defaults)) |
| Executor credentials | `GET/POST /projects/{id}/environments/{environment_id}/executor-credentials`, `DELETE …/executor-credentials/{key_id}` ([contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-executor-credentials.md)) |
| Deployment model configuration | `GET /harnesses`, `GET/PUT/DELETE /harnesses/{harness}/model-configuration`; the key is write-only ([contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/model-execution.md#deployment-defaults)) |
| Usage and health | `GET /summary`, `/sandbox/runtime-observations`, `/metrics` |
| Administrator audit | `GET /audit-log`; deployment-wide entries have `project_id: null` |

Expand All @@ -76,9 +76,9 @@ it is operational attribution, not per-key billing.

## Sandbox administration

The [deployment configuration contract](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/sandbox-deployment.md),
[nodes and sandbox backends reference](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/services/agents-api/HOSTED-SANDBOX-MANAGER.md)
and [generated OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/core.openapi.yaml)
The [deployment configuration contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/sandbox-deployment.md),
[nodes and sandbox backends reference](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/HOSTED-SANDBOX-MANAGER.md)
and [generated OpenAPI](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core.openapi.yaml)
define deployment and node operations:

- `GET/POST/PUT /core/v1/sandbox/deployment` and
Expand Down Expand Up @@ -119,7 +119,7 @@ is a durable serving pin, not proof of current connectivity. Target unknown, fai
or update-required state does not by itself invalidate confirmed old-generation
service; consume Core's connection/provider facts separately.

Administrators may [archive an individual hosted Session](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/admin-api.md#administrative-session-archive)
Administrators may [archive an individual hosted Session](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/admin-api.md#administrative-session-archive)
at the current generation without reset. History and persisted Files/Artifacts
survive; unpersisted workspace is lost and the original Session cannot resume.
Cancel reset stops further archives, not cleanup already requested. After zero
Expand Down Expand Up @@ -160,7 +160,7 @@ generated schema; do not interpret every empty or failed read as an absent resou
`GET /core/v1/metrics?range=1h|6h|24h|7d` returns Core process, execution
queue/slots, PostgreSQL and background-job measurements. It requires the Core key,
rejects arbitrary query filters and never grants
Agent execution access. See the [exact measurement contract](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/core-metrics.md)
Agent execution access. See the [exact measurement contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/core-metrics.md)
for complete buckets, null values, units and process-local retention. Frontend
implementation is maintained separately; this backend change does not modify
Agent metrics or the public Agent API.
Expand All @@ -169,7 +169,7 @@ Agent metrics or the public Agent API.

The Core key reads a node and its host history through
`GET /core/v1/sandbox/nodes/{node_id}?range=1h|6h|24h`. See the
[node host history contract](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/contracts/agents-api/node-host-history.md)
[node host history contract](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/node-host-history.md)
for nullable observations, freshness and aggregation. The node list is unchanged.

[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f45a4198aca79bf252412c55cad3647f5d704515/docs/api/web-management.md)
[Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/api/web-management.md)
Loading