Skip to content

Refactor agent tool effects and centralize tool catalog - #17

Open
hhszzzz wants to merge 11 commits into
masterfrom
taibu-agent
Open

hhszzzz wants to merge 11 commits into
masterfrom
taibu-agent

Conversation

@hhszzzz

@hhszzzz hhszzzz commented Oct 10, 2026

Copy link
Copy Markdown
Owner

Summary

  • What changed:

    1. Extracted tool result side effects into a centralized checkpointEffects map in createAgentTools, ensuring all checkpoint mutations happen only after successful cache writes
    2. Created new src/lib/agent/tool-catalog.ts to unify tool identity, family classification, and canonical text projection across the codebase
    3. Refactored SSE heartbeat logic to check cursor/epoch against the run row before building the full public view, avoiding unnecessary command queue reads during idle periods
    4. Updated tool implementations (ask_user, todo_write, web_search, select_final_artifacts, search_knowledge) to return results without side effects; effects now apply uniformly via the reducer map
    5. Migrated AGENT_CHART_NAMES from tool-presentation.ts to tool-catalog.ts and updated all imports
  • Why:

    • Cache failure safety: Previously, failed agent_cache_tool writes could leave phantom checkpoint state (pending questions, advanced task revisions, stale selections). Now effects only apply after successful cache persistence, allowing the model to safely retry the same step.
    • Single source of truth: Tool names, families, and canonical text projection were scattered across multiple files. Centralizing in tool-catalog.ts prevents inconsistencies (e.g., three chart kinds missing from the projection whitelist, tool icons guessing from name fragments).
    • SSE efficiency: Idle heartbeats no longer read the command queue or build the full public view; only cursor/epoch changes trigger view construction.
    • Code clarity: Tool implementations now focus on validation and computation; checkpoint mutations are declarative and testable in isolation.

Spec-Kit (Required)

  • Spec Type:
    • No Spec
  • If No Spec, explain why: This is a refactoring of internal tool execution and state management with no changes to database schema, API contracts, or user-facing behavior. The checkpoint structure and SSE message format remain identical.

Validation

  • Commands run:
    • pnpm lint — passes
    • pnpm test — all tests pass, including new agent-tool-effects.test.ts and agent-tool-catalog.test.ts
  • Manual checks:
    • Verified that failed cache writes leave no checkpoint state and allow model retry with the same revision
    • Verified that fresh execution and cache replay produce identical checkpoint state without re-running tools or re-caching
    • Verified that all 15 Core tools and registered Agent tools have a tool family assignment
    • Verified that all chart kinds retain canonical text in the projection

Risk & Rollback

  • Risk: Low. The changes are internal to tool execution and state management:

    • No database or API changes
    • Checkpoint structure and SSE format unchanged
    • All existing tests pass; new tests cover the refactored behavior
    • Tool families are additive; missing assignments default to 'other' without breaking functionality
  • Rollback plan: Revert the commit. No data migration or cleanup required.

Checklist

  • I selected Spec Type and provided a No Spec reason.
  • I updated tests: Added agent-tool-effects.test.ts (cache failure safety, fresh vs. replay consistency, knowledge hit counting) and agent-tool-catalog.test.ts (tool family coverage, canonical text projection).
  • No DB/schema/env changes.

https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m

Chart kinds, tool families and canonical-text projection were spread
across hand-written name lists. The durable projection kept canonical
text for only eight chart kinds, so taiyi, astrology and almanac
results fell back to raw JSON, and tool cards guessed icons from name
fragments.

- tool-catalog.ts is the browser-safe source for chart identity, tool
  families and canonical-text projection.
- The projection, chart tools, presentation helpers and tool cards read
  it; presentation types are keyed by the catalog's chart kinds, so a
  kind without a canonical JSON type fails to compile.
- Tests guard that every Core and registered Agent tool has a family
  and that all eleven chart kinds keep canonical text end to end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
…ched

ask_user, todo_write, web_search, select_final_artifacts and
search_knowledge changed the checkpoint before agent_cache_tool stored
their result, and each effect was written twice: in execute and in the
cache-replay branch. A failed cache write left a question that paused
the task, a task-list revision the model never saw (so retrying the
same revision always conflicted), sources or a final selection.

One reducer per tool now derives checkpoint state from persisted
details. It runs after the cache write succeeds and on cache replay;
execute only validates and returns the result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
Every connection built the full public view once per second, which
also reads the command queue, even for idle heartbeats. The run row
already holds the cursor, worker epoch and status that decide whether
a frame is sent, so the view is built only for snapshots. Frames,
resync and terminal behavior are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
@vercel

vercel Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ming-ai Error Error Oct 11, 2026 11:36pm UTC

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T15:40:42.251585Z 654bc97 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

- Keep Core canonical text on dayun, pillar resolution, ziwei horoscope
  and flying-star results so their views can fall back to it.
- remember_user_fact returns only the memory's id, title, content, kind
  and update time; ownership and fingerprint columns no longer reach the
  model or the transcript.
- Collaboration progress records each member's actual reasoning effort
  and configured focus.
- The public run view carries the settled billing state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
Every tool call maps to one workspace location chosen through the tool
catalog: reads, inspections and focus of one chart share a tab, searches
share the evidence view, records, attachments and methods merge by
identity, plans go to the process section and final selections to the
results section. Following tracks the latest call except plan updates;
chart, question and collaboration events may open the panel. Parsers
read stored results only and reject incomplete ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
Workspace: one view per tool family (charts, Core calculations, evidence,
records, attachments, methods, questions, collaboration, memory, raw
external results), results and process sections, model following, and
a canonical-text fallback for any view error.

Chat column: header with mode badge and live task clock, avatar message
header, one-row task list, a single task-process card whose steps show
state, summary, time and family tag and open in the workspace, compact
chart and collaboration cards, an evidence chip, mode and web controls
beside the composer, a docked question panel and a greeting empty state.
Five-element colors become readable tokens inside the chat only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4fc35eb6eb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/components/chat/AgentMessage.tsx Outdated
);
return null;
})}
<AgentEvidenceChip parts={data.parts} />

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Suppress the old source links when adding the evidence chip

Whenever web_search returns HTTP results, its checkpoint effect still adds source parts, and the loop above still renders every one as an .agent-source-link; appending this chip therefore shows both the full per-source list and the new workspace-backed summary. This defeats the documented behavior of moving retrieval results out of the chat and can leave large searches cluttering every answer, so the source parts should be omitted from the inline rendering when the evidence chip is used.

Useful? React with 👍 / 👎.

…boards

Replicate the "Taibu Agent 对话工作台" boards for the session header,
composer, empty state, model menu and question panel.

- Header: 56px bar with title menu (rename, export, delete), Agent and
  collaboration badge, run status with elapsed time or collaboration
  progress, workspace button with result count, and a more menu holding
  the reading width (default now 700px).
- Composer: single shell with "+", @, Agent/对话 switch, web toggle,
  context ring, model trigger and send/stop; state-dependent note,
  credit strip, saved-chart chips and suggestion cards on the hero.
- Model menu: tier labels from /api/models, segmented reasoning, style
  and mode controls, collaboration members as chips with one editor.
- Question dock replaces the modal dialog in the composer position:
  step navigation with short headers, review before submit, and
  "稍后回答" folding into a strip that hands the input back.
- Shared conversation export helper for header, /export and workspace.
- Tests: export helper, collaboration progress, question labels,
  composer copy, model tiers; browser fixture and live scripts follow
  the new dock, menu and labels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
Message: status pill icons per state, a folded process line that names
its steps, step rows with marker, summary, note, measured time and
family tag that open their view in the workspace, and a current-step
mark shared with the reading cards. Plan updates stay in the task list,
answered questions are not repeated, and reasoning alone shows as a
thinking line. Steps are numbered once across the task.

Readings become one-line cards (pillars or glyph, title, summary, a
workspace button that reads 正在工作区显示 while shown); outside the
workspace they expand in a dialog. Collaboration shows members side by
side with model, effort and state, and a member left running when the
task ended reads 未完成. The answer gets its own typography and caret,
本任务成果 lists saved readings and names the intermediate ones, and
evidence and message actions share one row.

Workspace process section: the step being looked at shows as 第 N 步
with its arguments and result to copy, its execution time apart from
waiting, and whether a replay reuses the cached result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
… suggestions

- Number evidence once per conversation: search results and chart focuses
  carry a server-stamped cite; answers render [n] as badges that open the
  cited source in the workspace and show which paragraph cited it.
- Rebuild the evidence view to the AgentResearch board: source filter,
  numbered cards, highlighted excerpts, empty-search notices.
- parallel_analysis accepts a title and up to 4 topics; members end with a
  <positions> block, the workspace shows live member steps, call counts,
  durations and a divergence table for option topics.
- The final answer may end with a <followups> block; it is stripped from the
  stored text and shown as suggestion chips above the composer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GzFwaF8xWLhKF9YvLdD34m
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

This branch had an error being deployed

1 failed deployment
Preview — a114e2a2 Deployed Oct 11, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants