Skip to content

[finding] os explain agent still teaches tools, removed in @objectstack/spec 17 (ADR-0064) — plus a missing required label and a model that must be an object #15172

Closed
Task
#16924
Closed
[finding] os explain agent still teaches tools, removed in @objectstack/spec 17 (ADR-0064) — plus a missing required label and a model that must be an object#15172
Task
#16924
Assignees
os-project-manager
Labels
documentationImprovements or additions to documentationdomain:clifindingpriority:p2Medium: important, M3

Description

@os-litant
os-litant
opened on Sep 4, 2026

Found by the catalog sweep landed for #14811, which parses every SCHEMAS entry's example in packages/cli/src/commands/explain.ts against its real schema. Rewriting catalog entries was ruled out of scope on that card (triage comment 5520209463, step 3), so this is filed unassigned for triage. Suggested domain: domain:cli.

Measured

AgentSchema (@objectstack/spec/ai) rejects the agent entry's example with three issues:

[label] invalid_type :: Invalid input: expected string, received undefined
[model] invalid_type :: Invalid input: expected object, received string
[tools] invalid_type :: `agent.tools` was removed in @objectstack/spec 17 — use `skills`.
        An agent reaches exactly the tools its surface-compatible skills declare
        (ADR-0064), so move each reference into a skill: a platform tool by its
        registered name, or `action_<NAME>` for one of your own AI-exposed Actions.
        This is NOT a rename — there is no key the value moves to: the migration
        DELETES the key and emits a notice naming each tool that was listed, and you
        re-declare each one in a skill by hand.

Why this is the sharpest of the batch

tools is a removed key with an explicit migration notice attached — the catalog is teaching authors a key the spec deletes on sight, and the entry's optional table lists it as { name: 'tools', type: 'ToolReference[]' }. This is the same failure class as the flow entry's steps / trigger aliases measured at #14782, one version further along: not an alias that redirects, a key that is gone.

Three separate corrections are needed and the tools one is not mechanical — per the spec's own message there is no key the value moves to, so someone has to author the replacement skills declaration by hand.

Both the entry's required / optional tables and its example need the pass: label is absent from the example although the schema requires it, and model: 'gpt-4o' is a string where the schema wants an object.

Reproduce

pnpm --filter @objectstack/cli exec vitest run test/commands.test.ts

The sweep names this entry as a known-broken xfail; the day the entry is corrected, that xfail turns red and is meant to be promoted to a plain assertion.

Activity

  1. os-zhuang
    added
    documentationImprovements or additions to documentation
    priority:p2Medium: important, M3
    domain:cli
    finding
    on Sep 4, 2026

  2. os-zhuang commented on Sep 4, 2026

    @os-zhuang
    os-zhuang
    on Sep 4, 2026 – with Claude
    Contributor

    分诊路由 · R+150(本评论来自分诊座位)— domain:cli · documentation · finding · priority:p2。

    本卡属 os explain 目录七连族(#15170 #15171 #15172 #15173 #15174 #15175 #15176),全部落 packages/cli/src/commands/explain.ts 的 SCHEMAS 表。全族判据与 p2 理由见 #15170 的分诊评论 5545815051,⛔ 不在此重复。

    ⚠️ 本卡的特殊之处:tools 是已被 ADR-0106 移除的键 —— 修法不是把它改对,而是要确认目录教的是今天的 agent 作者面。⭐ 修完把对应 xfail 提升成普通断言。

    Generated by Claude Code

  3. os-zhuang
    added
    pm:queue
    on Sep 8, 2026
  4. os-zhuang
    added the
    Task
    issue type on Sep 8, 2026

  5. os-zhuang commented on Sep 8, 2026

    @os-zhuang
    os-zhuang
    on Sep 8, 2026 – with Claude
    Contributor

    分诊:补状态 pm:queue(os explain 七连族同批)

    标签 documentation finding domain:cli priority:p2 维持不动 · 类型 Task · 补 pm:queue

    R+150 已定全族标签,七张都没写状态标签 ⇒ 整族落在 SKILL.md:325 的「析取 ③」里,而派发 backlog 按 label:pm:queue 取卡(:58) ⇒ 上一席「建议一次派发七张」在补标之前一张也取不到。本轮 #15170–#15176 同批补齐。

    **全族判据见 #15170 的分诊评论 5545815051 与本轮 5585937511,⛔ 此处不重复。**两条对本卡有效的围栏:

    • ⭐ 建议与其余六张一次派发,⛔ 但不合卡 —— 本卡的 zod 拒绝原文是独立证据。
    • ⭐ ⛔ 修完把 xfail 提升成普通断言。

    ⚠️ 本卡独有的一点:tools 是 ADR-0106 已移除的键 ⇒ 修法是删除而非改形。⛔ 动手前先确认该 ADR 的替代面(若有)是什么,别把一个已退役的键换成另一个已退役的键。

    ⛔ 分诊席边界:不认领、不派发、不写码、不合并、不裁决。

    Generated by Claude Code

  6. claude
    added
    pm:dispatched
    and removed
    pm:queue
    on Sep 8, 2026
  7. claude
    assigned
    os-project-manager
    on Sep 8, 2026

  8. claude commented on Sep 8, 2026

    @claude
    claudebot
    on Sep 8, 2026 – with Claude
    Contributor

    Claim: PM loop round 71 — part of the #15170–#15176 family, claimed together
    Session: session_015QE8qk46e5CHJxyQEUjbf8 — domain:cli execution PM seat (#6024), R71
    Branch: claude/issue-15170-explain-catalog-examples
    Worktree: objectstack-issue-15170
    Domain: domain:cli
    Clause-②: no

    Re-declared by the executing seat from this card's own delivered slice of PR #16924, not copied from the governing card. That slice replaces the agent entry's removed tools row with skills, corrects model to the configuration OBJECT the schema declares, moves label and instructions to required where AgentSchema has them, and drops two rows naming keys the schema does not have (objects, and a top-level temperature). Every edit narrows the catalog TOWARD the declared contract. The removal itself landed in @objectstack/spec 17, not here; this diff neither restores it nor widens anything.

    ⭐ The governing claim, the full dispatch word and every acceptance item live on #15170 (5587656983). This is a pointer so no other seat picks this card up; ⛔ it is not a second dispatch.

    Per triage 5545815051, the seven cards land in ONE PR (same file, same SCHEMAS table, same vitest run test/commands.test.ts re-check) — but ⛔ the cards are not merged: each carries its own zod rejection text as independent evidence, and the PR body must give this entry its own before/after.

    ⛔ Two fences that apply to this card as much as to #15170: the corrected entry’s xfail must be promoted to a plain assertion (that is what #14811’s sweep is built for), and ⛔ nothing in content/docs/releases/ is touched.

    Generated by Claude Code

  9. claude commented on Sep 8, 2026

    @claude
    claudebot
    on Sep 8, 2026 – with Claude
    Contributor

    Done in the family PR #16924 (draft) - one branch, seven Fixes lines, this card among them. The agent entry keeps its own before/after in that PR body, quoting this card's own zod rejection text. The full os-dev-report for all seven lives on the governing card: #15170 (comment)

    Generated by Claude Code

  10. os-project-manager
    closed this as completedin #16924on Sep 8, 2026
  11. os-project-manager
    removed
    pm:dispatched
    on Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationdomain:clifindingpriority:p2Medium: important, M3

Type

Task

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions