cleveragents/cleveragents-core

Fork 3

Proposal: update specification — session export --format flag and tool YAML wrapper key #1546

New issue

Open

opened 2026-04-02 20:51:08 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 20:51:08 +00:00

Owner

Spec Update Proposal

Triggered by merged PRs: #1392 (session export/import), #1498 (tool YAML wrapper key)

Summary of Changes Needed

Two spec gaps were identified by comparing recently merged implementation PRs against docs/specification.md.

Change 1: `agents session export` — add `--format` flag to CLI synopsis and reference

What changed in the implementation (PR #1392)

PR #1392 (feat(tui): implement session export/import (JSON + Markdown)) added a --format json|md flag to the agents session export CLI command. The implementation in src/cleveragents/cli/commands/session.py now accepts:

agents session export [--output/-o FILE] [--format json|md] <SESSION_ID>

--format json (default): canonical, importable JSON export
--format md: lossy Markdown transcript for sharing/documentation

What spec sections need updating

Current text (line 222, command synopsis overview):

agents session export [(--output|-o) <FILE>] <SESSION_ID>

Proposed text:

agents session export [(--output|-o) <FILE>] [--format (json|md)] <SESSION_ID>

Current text (line 1988, agents session export detailed reference):

agents session export [(--output|-o) <FILE>] <SESSION_ID>

Proposed text:

agents session export [(--output|-o) <FILE>] [--format (json|md)] <SESSION_ID>

Current text (line 1993–1996, Arguments section):

**Arguments**

- `<SESSION_ID>`: The session identifier.
- `--output/-o FILE`: Output file path (optional).

Proposed text:

**Arguments**

- `<SESSION_ID>`: The session identifier.
- `--output/-o FILE`: Output file path (optional).
- `--format json|md`: Export format. `json` (default) produces the canonical, importable JSON export. `md` produces a human-readable Markdown transcript (lossy — cannot be re-imported, intended for sharing and documentation).

Current text (line 1990, Purpose):

**Purpose**
Export a session as a portable JSON file.

Proposed text:

**Purpose**
Export a session as a portable JSON or Markdown file.

Rationale

The TUI section (§ Conversation Export, line 30208–30212) already documents both formats correctly. The CLI reference section was not updated when PR #1392 was merged, creating an inconsistency between the TUI spec and the CLI spec. The implementation is correct and better than the spec — the spec needs to catch up.

Change 2: Tool YAML configuration — document optional `tool:` wrapper key and `cleveragents:` header

What changed in the implementation (PR #1498)

PR #1498 (fix(cli): handle tool: wrapper key in agents tool add YAML config) added support for tool YAML files that use a tool: wrapper key (consistent with how actor config files use actors: as a top-level key). The implementation now silently handles both formats:

Flat format (existing, still supported):

name: local/my-tool
description: "My tool"
source: custom

Wrapped format (newly supported):

cleveragents:
  version: "3.0"
tool:
  name: local/my-tool
  description: "My tool"
  source: custom

What spec sections need updating

The Design Principles section (line 30827) already documents the cleveragents.version field for config files in general:

Schema version: Configuration files may include a top-level cleveragents.version field to indicate which schema version they target (currently "3.0"). When omitted, the latest schema version is assumed.

However, the Tool Configuration Files section (§ Tool Configuration Files, line 33438) only shows the flat format in its examples and JSON Schema. It does not mention the optional tool: wrapper key.

Proposed addition to the Tool Configuration Files section, after the introductory paragraph:

File format: Tool configuration files support two equivalent formats. The flat format places all fields at the top level. The wrapped format nests all tool fields under a tool: key and optionally includes a cleveragents: metadata header. Both formats are accepted by agents tool add. The flat format is idiomatic for simple tools; the wrapped format is useful when the file needs to be self-describing or when tooling requires a top-level type discriminator.
# Flat format (idiomatic)
name: local/my-tool
description: "My tool"
source: custom

# Wrapped format (also accepted)
cleveragents:
  version: "3.0"
tool:
  name: local/my-tool
  description: "My tool"
  source: custom

Rationale

The PR #1498 commit message says "handle spec-required tool: wrapper key" — indicating the spec was already intended to require this format but the implementation hadn't caught up. The fix makes the CLI accept both formats for backward compatibility. The spec should document both formats explicitly so users know both are valid.

Scope

Section	Lines	Change Type
CLI Command Synopsis (session export)	~222	Add `--format` flag
`agents session export` reference	~1988–1996	Add `--format` flag + argument description + update Purpose
Tool Configuration Files intro	~33438–33445	Add note about flat vs wrapped format with examples

Classification

Both changes are spec gaps (implementation is better/more complete than the spec). Neither is a deviation — the implementation is correct in both cases.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal **Triggered by merged PRs**: #1392 (session export/import), #1498 (tool YAML wrapper key) --- ## Summary of Changes Needed Two spec gaps were identified by comparing recently merged implementation PRs against `docs/specification.md`. --- ## Change 1: `agents session export` — add `--format` flag to CLI synopsis and reference ### What changed in the implementation (PR #1392) PR #1392 (`feat(tui): implement session export/import (JSON + Markdown)`) added a `--format json|md` flag to the `agents session export` CLI command. The implementation in `src/cleveragents/cli/commands/session.py` now accepts: ``` agents session export [--output/-o FILE] [--format json|md] <SESSION_ID> ``` - `--format json` (default): canonical, importable JSON export - `--format md`: lossy Markdown transcript for sharing/documentation ### What spec sections need updating **Current text** (line 222, command synopsis overview): ``` agents session export [(--output|-o) <FILE>] <SESSION_ID> ``` **Proposed text**: ``` agents session export [(--output|-o) <FILE>] [--format (json|md)] <SESSION_ID> ``` **Current text** (line 1988, `agents session export` detailed reference): ``` agents session export [(--output|-o) <FILE>] <SESSION_ID> ``` **Proposed text**: ``` agents session export [(--output|-o) <FILE>] [--format (json|md)] <SESSION_ID> ``` **Current text** (line 1993–1996, Arguments section): ``` **Arguments** - `<SESSION_ID>`: The session identifier. - `--output/-o FILE`: Output file path (optional). ``` **Proposed text**: ``` **Arguments** - `<SESSION_ID>`: The session identifier. - `--output/-o FILE`: Output file path (optional). - `--format json|md`: Export format. `json` (default) produces the canonical, importable JSON export. `md` produces a human-readable Markdown transcript (lossy — cannot be re-imported, intended for sharing and documentation). ``` **Current text** (line 1990, Purpose): ``` **Purpose** Export a session as a portable JSON file. ``` **Proposed text**: ``` **Purpose** Export a session as a portable JSON or Markdown file. ``` ### Rationale The TUI section (§ Conversation Export, line 30208–30212) already documents both formats correctly. The CLI reference section was not updated when PR #1392 was merged, creating an inconsistency between the TUI spec and the CLI spec. The implementation is correct and better than the spec — the spec needs to catch up. --- ## Change 2: Tool YAML configuration — document optional `tool:` wrapper key and `cleveragents:` header ### What changed in the implementation (PR #1498) PR #1498 (`fix(cli): handle tool: wrapper key in agents tool add YAML config`) added support for tool YAML files that use a `tool:` wrapper key (consistent with how actor config files use `actors:` as a top-level key). The implementation now silently handles both formats: **Flat format** (existing, still supported): ```yaml name: local/my-tool description: "My tool" source: custom ``` **Wrapped format** (newly supported): ```yaml cleveragents: version: "3.0" tool: name: local/my-tool description: "My tool" source: custom ``` ### What spec sections need updating The **Design Principles** section (line 30827) already documents the `cleveragents.version` field for config files in general: > **Schema version**: Configuration files may include a top-level `cleveragents.version` field to indicate which schema version they target (currently `"3.0"`). When omitted, the latest schema version is assumed. However, the **Tool Configuration Files** section (§ Tool Configuration Files, line 33438) only shows the flat format in its examples and JSON Schema. It does not mention the optional `tool:` wrapper key. **Proposed addition** to the Tool Configuration Files section, after the introductory paragraph: > **File format**: Tool configuration files support two equivalent formats. The **flat format** places all fields at the top level. The **wrapped format** nests all tool fields under a `tool:` key and optionally includes a `cleveragents:` metadata header. Both formats are accepted by `agents tool add`. The flat format is idiomatic for simple tools; the wrapped format is useful when the file needs to be self-describing or when tooling requires a top-level type discriminator. > > ```yaml > # Flat format (idiomatic) > name: local/my-tool > description: "My tool" > source: custom > > # Wrapped format (also accepted) > cleveragents: > version: "3.0" > tool: > name: local/my-tool > description: "My tool" > source: custom > ``` ### Rationale The PR #1498 commit message says "handle spec-required `tool:` wrapper key" — indicating the spec was already intended to require this format but the implementation hadn't caught up. The fix makes the CLI accept both formats for backward compatibility. The spec should document both formats explicitly so users know both are valid. --- ## Scope | Section | Lines | Change Type | |---------|-------|-------------| | CLI Command Synopsis (session export) | ~222 | Add `--format` flag | | `agents session export` reference | ~1988–1996 | Add `--format` flag + argument description + update Purpose | | Tool Configuration Files intro | ~33438–33445 | Add note about flat vs wrapped format with examples | --- ## Classification Both changes are **spec gaps** (implementation is better/more complete than the spec). Neither is a deviation — the implementation is correct in both cases. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo referenced this issue

2026-04-02 20:51:39 +00:00

🤖 [Session State] ca-spec-updater — Continuous Spec Evolution Monitor #1534