schema-sync

name: schema-sync description: Synchronizes Swift types with the ACP protocol schema. Use when updating SDK types to match the latest protocol specification.

Schema Sync Skill

Synchronizes Swift types with the ACP protocol schema.

Trigger

User says: "/schema-sync" or "update schema" or "sync with ACP protocol"

Process

1. Fetch latest schema files from the ACP protocol repository:

   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/schema.json
   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/schema.unstable.json
   • https://raw.githubusercontent.com/agentclientprotocol/agent-client-protocol/main/schema/meta.json

2. Compare with current types in Sources/ACP/:

   • Methods in Client/Methods/
   • Notifications in Client/Methods/Notifications.swift
   • Models in Models/

3. Report changes:

   • New types to add
   • Modified types to update
   • Removed types to deprecate

4. Update Swift files:

   • Add new Method/Notification definitions
   • Update Parameters/Result structs
   • Mark RFD APIs with appropriate deprecation warnings:
     • Draft RFD: @available(*, deprecated, message: "Draft RFD - API may change without notice")
     • Preview RFD: @available(*, deprecated, message: "Preview RFD - API may change")
   • Reference the RFD URL in doc comments

5. Update SCHEMA_VERSION.md with:

   • New commit hash
   • Schema date
   • Protocol version
   • List of changes

6. Run tests to verify changes:

   swift test
   

Schema Mapping

Naming Conventions

• JSON snake_case → Swift camelCase
• JSON sessionId → Swift sessionID (use ID suffix)
• JSON tool_call_id → Swift toolCallID

Example Update

When adding a new method like session/get_config:

/// Gets session configuration.
public enum SessionGetConfig: Method {
    public static let name = "session/get_config"

    public struct Parameters: Codable, Hashable, Sendable {
        public var sessionID: String

        private enum CodingKeys: String, CodingKey {
            case sessionID = "sessionId"
        }

        public init(sessionID: String) {
            self.sessionID = sessionID
        }
    }

    public struct Result: Codable, Hashable, Sendable {
        public var config: Value

        public init(config: Value) {
            self.config = config
        }
    }
}

RFD Status Handling

ACP uses an RFD (Request for Dialog) process for new features:

When syncing schema:

1. Check docs/docs.json for RFD status groupings
2. Apply appropriate deprecation warnings
3. Include RFD URL in doc comments for draft/preview APIs

Notes

• Always maintain backward compatibility when possible
• Use deprecation warnings for removed APIs
• Update golden test files when protocol changes
• Run full test suite after updates