hermes-web-ui/docs/planning/learn-command-integration.md

# /learn Command Web UI Integration Plan

Date: 2026-06-25

## Context

Hermes Agent added a `/learn` slash command that turns a user-described source
or recent workflow into a reusable Hermes skill. The command does not use a
separate model or learning engine. It builds a standards-guided prompt with
`agent.learn_prompt.build_learn_prompt()` and submits that prompt through the
normal agent loop.

Web UI chat sessions use the local bridge run path instead of always going
through the upstream CLI or gateway slash-command handler. For a reliable user
experience, Web UI should explicitly recognize `/learn` and expand it through
the bridge command path before running the generated prompt.

## Goals

- Let users type `/learn <source or workflow>` in a normal Hermes chat session.
- Show `/learn` in the chat input slash-command picker.
- Run the prompt generated by Hermes Agent's `build_learn_prompt()` as the real
  agent input.
- Preserve the visible transcript as a command invocation, not as the expanded
  internal prompt.
- Support bare `/learn` as "learn from this conversation".
- Fail clearly when the bundled/runtime Hermes Agent version does not provide
  `agent.learn_prompt`.

## Non-Goals

- Do not add a dedicated model, provider, or auxiliary model for `/learn`.
- Do not create a new Web UI page for skill creation.
- Do not duplicate Hermes Agent's skill-authoring prompt in TypeScript.
- Do not treat `/learn` as memory, fine-tuning, or persistent model training.

## Proposed Design

### Server Bridge Command

Add `/learn` to the Web UI session-command layer:

- Extend `CommandName` in
  `packages/server/src/services/hermes/run-chat/session-command.ts`.
- Add `learn` to `COMMAND_ALIASES`.
- Handle `command.name === "learn"` similarly to `/skill`:
  - call the bridge command endpoint with `/learn <args>`;
  - expect a handled result with `type: "learn"` and a generated `message`;
  - enqueue or start a run with the generated message as the actual input;
  - keep the visible/display input as `/learn <args>`.

### Python Bridge

Add support in
`packages/server/src/services/hermes/agent-bridge/python/bridge_pool.py`:

- In `dispatch_command()`, recognize `learn`.
- Import `build_learn_prompt` from `agent.learn_prompt`.
- Return a handled bridge result:

```python
{
    "session_id": session_id,
    "command": name,
    "handled": True,
    "type": "learn",
    "message": build_learn_prompt(arg),
}
```

If the import fails, return a clear unsupported-version message instead of
silently passing `/learn` through as normal text.

### Client Slash Picker

Update `packages/client/src/utils/hermes/bridge-session-commands.ts`:

- Add `learn` to `BridgeSessionCommandName`.
- Add a command definition with text args.
- Keep it as a bridge session command so the UI renders it as a command message.

Update all locale files under `packages/client/src/i18n/locales/`:

- Add `chat.slashCommands.learn`.
- Reuse the existing `chat.slashCommandArgs.text` placeholder unless a more
  specific placeholder is needed.

### Runtime Compatibility

The feature depends on Hermes Agent containing `agent/learn_prompt.py`. Web UI
should not copy the prompt text locally. The bridge should surface a clear error
when the runtime agent is too old, for example:

```text
/learn requires a newer Hermes Agent runtime with agent.learn_prompt.
```

This keeps the upstream agent as the source of truth for skill-authoring rules.

## UX Notes

- Idle session:
  - user sees `/learn ...` as a command message;
  - assistant runs the generated skill-authoring prompt;
  - final answer should mention the created skill name and category, as directed
    by the upstream prompt.
- Running session:
  - `/learn ...` should queue like `/skill` and `/plan`;
  - queued item should display the original command, not the expanded prompt.
- Bare `/learn`:
  - should be accepted and should expand to the upstream fallback for the
    current conversation.

## Tests

Add or update focused tests:

- Server:
  - `parseSessionCommand("/learn from docs")` returns a learn command.
  - idle `/learn` starts a run using the bridge-generated prompt.
  - running `/learn` queues the command like `/skill`.
  - missing `agent.learn_prompt` returns a clear error.
- Client:
  - slash picker includes `/learn`.
  - `isKnownBridgeSessionCommand("/learn something")` is true.
  - queued/running behavior displays `/learn ...`, not the expanded prompt.
- Harness:
  - Run the smallest relevant unit tests while iterating.
  - Run `npm run harness:check` before opening a PR.

## Rollout

1. Land bridge command support and tests.
2. Update bundled/runtime Hermes Agent to a revision containing
   `agent/learn_prompt.py`.
3. Add the client slash-picker entry and locale strings.
4. Verify against a local chat session with:
   - `/learn`
   - `/learn from docs/workflow.md`
   - `/learn the workflow we just performed`

## Open Questions

- Should `/learn` be available in workflow node chat drawers, or only normal
  Hermes chat sessions?
- Should Web UI refresh the skills list automatically after `/learn` completes?
- Should the skills page show a lightweight "created by /learn" marker if the
  upstream skill metadata exposes one later?