DEV Community

NEE
NEE

Posted on

Deep Dive into SwiftWork (Part 3): Tool Card — An Extensible Tool Visualization System

#swift #swiftui #agents #visualization

The previous two posts covered how events flow from the SDK to the UI. This post focuses on visualizing one specific type of event: tool calls.

Tool invocations are the most frequent operations in an Agent application. A typical task might call tools twenty or thirty times—reading files, writing files, executing commands, searching code. If every tool call renders as the same gray block, it's hard for users to quickly tell "what command is Bash running" or "which file is Edit changing."

SwiftWork's solution is an extensible tool rendering system: each tool type registers a renderer, and ToolCardView looks up the matching renderer by tool name. When adding a new tool type, you only need to write a struct that implements the ToolRenderable protocol and register it with ToolRendererRegistry—no changes to TimelineView required.

Starting from the Problem: Why Not Use a Unified Tool View

The simplest approach is to use the same view for all tool calls—showing the tool name, input parameters, and output. The ToolCallView from post 2 serves this role:

struct ToolCallView: View {
    let event: AgentEvent
    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            HStack(spacing: 4) {
                Image(systemName: "wrench.and.screwdriver")
                Text(event.content)  // 工具名称
            }
            Text(input)  // 原始 JSON
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

This view treats all tools equally—the same wrench icon, the same JSON output. It works fine as a fallback, but has a few problems:

  • For Bash calls, users want to see the command itself (git status), not {"command": "git status"}
  • For Read calls, users want to see the file path (src/main.swift), not the full JSON
  • Search tool results might contain multi-line matches, which need to be distinguished from single-line output

Each tool has different "most useful information." The Tool Card system lets each tool decide how to present itself.

The ToolRenderable Protocol

The protocol defines the contract for tool renderers:

protocol ToolRenderable: Sendable {
    /// 此渲染器处理的工具名称（与 SDK ToolUseData.toolName 匹配）
    static var toolName: String { get }

    /// 工具类型主题色（左边条、图标着色）
    static var accentColor: Color { get }

    /// 工具类型 SF Symbol 图标名
    static var icon: String { get }

    /// 根据工具内容生成 SwiftUI 视图
    @ViewBuilder @MainActor
    func body(content: ToolContent) -> any View

    /// 生成摘要标题（折叠状态显示）
    func summaryTitle(content: ToolContent) -> String

    /// 生成副标题（如文件路径、命令摘要）
    func subtitle(content: ToolContent) -> String?
}
Enter fullscreen mode Exit fullscreen mode

The protocol extension provides default values:

extension ToolRenderable {
    static var accentColor: Color { .gray }
    static var icon: String { "wrench.and.screwdriver" }

    func summaryTitle(content: ToolContent) -> String {
        content.toolName
    }

    func subtitle(content: ToolContent) -> String? {
        nil
    }
}
Enter fullscreen mode Exit fullscreen mode

Six members, three with defaults. Implementers only need to provide toolName (the static routing key) and body (the rendered content). summaryTitle and subtitle can be overridden to provide more meaningful summaries, and accentColor and icon can be overridden for visual distinction.

ToolRendererRegistry

The registry is a [String: ToolRenderable] dictionary, keyed by toolName:

@MainActor
@Observable
final class ToolRendererRegistry {
    private var renderers: [String: any ToolRenderable] = [:]

    init() {
        register(BashToolRenderer())
        register(FileEditToolRenderer())
        register(SearchToolRenderer())
        register(ReadToolRenderer())
        register(WriteToolRenderer())
    }

    func register(_ renderer: any ToolRenderable) {
        renderers[type(of: renderer).toolName] = renderer
    }

    func renderer(for toolName: String) -> (any ToolRenderable)? {
        renderers[toolName]
    }
}
Enter fullscreen mode Exit fullscreen mode

Five built-in renderers are pre-registered during init. Lookup is O(1) dictionary access. The @Observable annotation lets SwiftUI automatically refresh when new renderers are registered—though in current usage all renderers are registered at init time, dynamic registration is reserved for a future plugin system.

5 Built-in Renderers

BashToolRenderer — Terminal Commands 

struct BashToolRenderer: ToolRenderable {
    static let toolName = "Bash"
    static let accentColor: Color = .green
    static let icon: String = "terminal"

    func summaryTitle(content: ToolContent) -> String {
        // 从 input JSON 提取 command 字段
        // {"command": "git status"} → "git status"
        guard let json = parseInput(content),
              let command = json["command"] as? String
        else { return content.toolName }
        return command
    }
}
Enter fullscreen mode Exit fullscreen mode

Green theme + terminal icon. summaryTitle extracts the command field from the input JSON—users see the running command directly in the collapsed state.

ReadToolRenderer — File Reading 

struct ReadToolRenderer: ToolRenderable {
    static let toolName = "Read"
    static let accentColor: Color = .blue
    static let icon: String = "doc.text"

    func summaryTitle(content: ToolContent) -> String {
        // {"file_path": "src/main.swift"} → "src/main.swift"
        guard let json = parseInput(content),
              let filePath = json["file_path"] as? String
        else { return content.toolName }
        return filePath
    }
}
Enter fullscreen mode Exit fullscreen mode

Blue theme + document icon. summaryTitle extracts the file path.

WriteToolRenderer — File Writing 

struct WriteToolRenderer: ToolRenderable {
    static let toolName = "Write"
    static let accentColor: Color = .orange
    static let icon: String = "pencil.and.outline"

    func summaryTitle(content: ToolContent) -> String {
        // 提取 file_path
    }

    func subtitle(content: ToolContent) -> String? {
        // 提取 content 字段，截取前 80 字符
        // {"content": "import Foundation\n..."} → "import Foundation..."
        guard let json = parseInput(content),
              let contentStr = json["content"] as? String, !contentStr.isEmpty
        else { return nil }
        return "\(contentStr.prefix(80))..."
    }
}
Enter fullscreen mode Exit fullscreen mode

Orange theme + pencil icon. It has one more field than Read—a subtitle showing the first 80 characters of the written content. Since written content is typically long, the subtitle gives users a quick preview.

FileEditToolRenderer — File Editing 

struct FileEditToolRenderer: ToolRenderable {
    static let toolName = "Edit"
    static let accentColor: Color = .orange
    static let icon: String = "pencil.line"

    func summaryTitle(content: ToolContent) -> String {
        // 提取 file_path
    }

    func subtitle(content: ToolContent) -> String? {
        // 提取 old_string，截取前 50 字符
        // {"old_string": "func hello() {"} → "Editing: func hello() {"
        guard let json = parseInput(content),
              let oldString = json["old_string"] as? String, !oldString.isEmpty
        else { return nil }
        return "Editing: \(oldString.prefix(50))"
    }
}
Enter fullscreen mode Exit fullscreen mode

Orange theme + edit icon. The subtitle displays the old text being replaced—so users know which line Edit is changing.

SearchToolRenderer — Code Search 

struct SearchToolRenderer: ToolRenderable {
    static let toolName = "Grep"
    static let accentColor: Color = .purple
    static let icon: String = "text.magnifyingglass"

    func summaryTitle(content: ToolContent) -> String {
        // 提取 pattern
    }

    func subtitle(content: ToolContent) -> String? {
        // 提取 path
    }
}
Enter fullscreen mode Exit fullscreen mode

Purple theme + magnifying glass icon. summaryTitle shows the search pattern, and subtitle shows the search path.

Visual Distinction Summary

Tool Color Icon summaryTitle subtitle
Bash Green terminal Command -
Read Blue doc.text File path -
Write Orange pencil.and.outline File path First 80 chars of content
Edit Orange pencil.line File path First 50 chars of replaced text
Grep Purple text.magnifyingglass Search pattern Search path

All five tool types can be distinguished at a glance in the collapsed state: different colors, different icons, different summary text.

ToolCardView: The Container View

ToolCardView is the container for tool cards. It doesn't handle rendering itself—it delegates to the renderer looked up from the registry:

struct ToolCardView: View {
    let content: ToolContent
    let registry: ToolRendererRegistry
    let isSelected: Bool
    let onSelect: () -> Void

    @State private var isExpanded = false

    var body: some View {
        HStack(spacing: 0) {
            // 左边条（3px，渲染器的主题色）
            RoundedRectangle(cornerRadius: 2)
                .fill(toolAccentColor)
                .frame(width: 3)

            VStack(alignment: .leading, spacing: 0) {
                titleRow       // 始终可见
                    .onTapGesture {
                        onSelect()
                        withAnimation { isExpanded.toggle() }
                    }

                if isExpanded {
                    expandedContent  // 展开后可见
                }
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The card has two layers: titleRow (always visible) and expandedContent (shown on click to expand).

titleRow 

private var titleRow: some View {
    HStack(alignment: .top, spacing: 6) {
        Image(systemName: toolIcon)          // 渲染器的图标
            .foregroundStyle(toolIconColor)

        VStack(alignment: .leading, spacing: 2) {
            HStack(spacing: 4) {
                Text(resolvedSummaryTitle)    // 渲染器的 summaryTitle
                    .fontWeight(.medium)
                Spacer()
                if content.status == .running {
                    ProgressView().controlSize(.mini)  // 运行中转圈
                }
                Text(statusLabel)             // pending / running / completed / failed
                    .font(.system(size: 9))
                    .background(statusColor.opacity(0.15))
            }
            Text(content.toolName)            // 工具名称（小字）
            if let subtitle = resolvedSubtitle {  // 渲染器的 subtitle
                Text(subtitle)
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The title row gets its icon, color, summary title, and subtitle from the renderer. The status label (pending/running/completed/failed) is determined by ToolContent.status and is outside the renderer's control—it's a generic execution status, independent of tool type.

expandedContent 

private var expandedContent: some View {
    VStack(alignment: .leading, spacing: 8) {
        Divider()

        // 工具特定的 body（从渲染器获取）
        if let renderer = registry.renderer(for: content.toolName) {
            AnyView(renderer.body(content: content))
        } else {
            genericToolBody  // fallback
        }

        // 通用 INPUT 区域
        if !content.input.isEmpty {
            HStack {
                Text("INPUT")
                Spacer()
                CopyButton(text: content.input)
            }
            Text(content.input)
                .font(.system(.caption, design: .monospaced))
        }

        // 通用 OUTPUT 区域
        if let output = content.output, !output.isEmpty {
            ToolResultContentView(output: output, isError: content.isError)
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The expanded content has three sections:

  1. The renderer's body: Tool-specific custom content. The current 5 built-in renderers each display an icon summary block in their body—similar to the information in titleRow but more detailed. In the future, more complex tools could provide richer body content (such as code diff previews).
  2. INPUT section: Generic raw input JSON display with a copy button.
  3. OUTPUT section: ToolResultContentView, covered in the next section.

genericToolBody is the fallback when no renderer is registered—it just shows the tool name and raw input.

ToolResultContentView: Output Rendering + Diff Detection

ToolResultContentView has a smart feature: it automatically detects whether the output content is in diff format, and if so, applies color highlighting.

private var isDiffContent: Bool {
    let lines = output.components(separatedBy: "\n")
    let diffLines = lines.filter { $0.hasPrefix("+") || $0.hasPrefix("-") || $0.hasPrefix("@@") }
    return diffLines.count >= 2
}
Enter fullscreen mode Exit fullscreen mode

Detection logic: if the output has at least two lines starting with +, -, or @@, it's treated as diff content. Simple but effective—the SDK's Edit tool outputs results in diff format.

Diff rendering adds background colors to each line:

private func diffLineView(_ line: String) -> some View {
    Text(line)
        .font(.system(.caption, design: .monospaced))
        .padding(.horizontal, 4)
        .background(diffLineBackground(line))
}

private func diffLineBackground(_ line: String) -> Color {
    if line.hasPrefix("+") { return .green.opacity(0.15) }  // 新增行
    if line.hasPrefix("-") { return .red.opacity(0.15) }    // 删除行
    if line.hasPrefix("@@") { return .blue.opacity(0.1) }   // 位置标记
    return .clear
}
Enter fullscreen mode Exit fullscreen mode

Non-diff content renders as plain text with truncation logic—it collapses when exceeding 5 lines or 200 characters, with an expand button.

How to Add a New Tool Renderer

Say the SDK adds a new WebFetch tool, and you want to give it a dedicated card style in SwiftWork. You only need two steps:

Step 1: Write the renderer

struct WebFetchToolRenderer: ToolRenderable {
    static let toolName = "WebFetch"
    static let accentColor: Color = .cyan
    static let icon: String = "globe"

    @MainActor
    func body(content: ToolContent) -> any View {
        // 自定义视图...
    }

    func summaryTitle(content: ToolContent) -> String {
        // 从 input 提取 URL
        guard let json = parseInput(content),
              let url = json["url"] as? String
        else { return content.toolName }
        return url
    }
}
Enter fullscreen mode Exit fullscreen mode

Step 2: Register it

// ToolRendererRegistry.init()
register(WebFetchToolRenderer())
Enter fullscreen mode Exit fullscreen mode

No need to modify TimelineView, ToolCardView, or any other file. ToolCardView looks up the renderer at render time via registry.renderer(for:)—if found, it uses it; if not, it falls back to the generic view.

Summary

The Tool Card system follows a protocol + registry design pattern:

Component Responsibility
ToolRenderable Defines the rendering contract—tool name, color, icon, summary, custom view
ToolRendererRegistry Dictionary lookup, toolName → ToolRenderable
ToolCardView Container view, delegates to renderer, handles generic logic (expand/collapse, status labels, INPUT/OUTPUT sections)
ToolResultContentView Output rendering with automatic diff detection

The benefit of this pattern is open for extension, closed for modification. TimelineView's dispatch logic (the toolCardView(for:) from post 2) doesn't need to know how many tool types exist—it only queries the registry. When adding a new tool type, the scope of changes is limited to the renderer file and the registry's init method.

The next and final post covers the data layer—SwiftData session/event persistence, app state restoration, Markdown rendering, and syntax highlighting.

Deep Dive into SwiftWork Series:

GitHub: SwiftWork | Open Agent SDK

Top comments (0)