HarperFast / HarperFast/harper

No models.* config params: a models block cannot be set via set_configuration, so the built-in agent cannot be given a model over the ops API

Open
#2,267 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

## Summary

`CONFIG_PARAMS` has no `models` entry, so no `models.*` key exists in `CONFIG_PARAM_MAP` and a `models` block cannot be set through `set_configuration`. Combined with #2266 the request is accepted and discarded with a success response.

The practical consequence: **the built-in agent can be enabled over the operations API but can never be given a model over it.** `agent_enabled`, `agent_model`, `agent_maxTurns`, `agent_autoApprove`, `agent_allowDestructive`, `agent_user` and friends are all present (`utility/hdbTerms.ts:620-628`), so the agent half of the feature is fully configurable; the backend it needs to actually run is not. The only routes to a generative backend today are editing `harper-config.yaml` on disk, or registering one from component code via `models.registerBackend(...)`.

That is a hard wall for any hosted instance where the operator has no filesystem access.

## Detail

`bootstrapModels` reads the root config's `models` block and dispatches each `models.embedding.` / `models.generative.` entry to a backend registrar (`resources/models/bootstrap.ts`). The block is root-config-only by design — `loadComponent` gates it on `isRoot` (`components/componentLoader.ts:497`) — so the config file is the single intended source, and the operations API cannot write to it.

Confirmed live on 5.2.4: enabling the agent via `set_configuration` works and all six agent operations register, but the first prompt fails with `No backend registered for 'generative.default'`, with no API-reachable way to fix it.

## Why it isn't just #2266

#2266 makes the failure *silent* — that is the bug, and fixing it turns this into an honest `unrecognized config parameter: models` 400. This issue is the missing capability behind that error: even with perfect error reporting, there would still be no way to configure a model backend over the API.

## Design question the fix has to answer

`models.generative.` is user-named, so entry names can't be enumerated in a static `CONFIG_PARAMS` table the way `agent_*` is. Options:

1. **Whole-block param.** Add `MODELS: 'models'` to `CONFIG_PARAMS` and accept the nested object as one value (`configDoc.setIn(['models'], value)`), validating its shape on the way in. Precedent exists for object-valued params, and it matches how an operator thinks about the block. Replace-not-merge semantics need stating.
2. **Dynamic path params.** Teach the `parsedArgs` loop to accept a dotted/underscored path under a known prefix (`models_generative_default_backend`), extending the existing `_package` / `_port` suffix escape hatch at `configUtils.ts:848` into something general.

(1) is the smaller change and the easier one to validate; (2) generalises better but widens the config write surface.

Either way, credentials need care: `apiKey` is a documented field of these entries, `bootstrapModels` already warns when it is a literal rather than a `${VAR}` placeholder, and #1925 covers the config file's world-readable permissions. An API that accepts `models` should push operators toward `${VAR}` / secret references rather than inline key material.

## Related

- #2266 — why this currently fails silently instead of erroring.
- #1925 — config file permissions, relevant because these entries can carry `apiKey`.
- #1676 — secrets/env-var management, the mechanism a non-literal `apiKey` should resolve through.

Contributor guide

Open the contributing guide

Research direction

Start by reading CONFIG_PARAMS and the set_configuration handling, then review configUtils.ts:848 and resources/models/bootstrap.ts to understand accepted config paths and model registration. Compare the whole-block and dynamic-path approaches described in the issue, including validation and how API keys should use secret references. Done means operators can configure a model backend through the operations API and the built-in agent can use it.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.