update(api): align framework surface

Author: Tom-Ryder

Sources/AgentRunKit/Core/Context/SubAgentContext.swift

@@ -1,4 +1,5 @@
-protocol CurrentDepthProviding {
+/// Surfaces a current sub-agent recursion depth for custom depth-aware contexts.
+public protocol CurrentDepthProviding {
     var currentDepth: Int { get }
 }
 

Sources/AgentRunKit/Documentation.docc/Articles/DefiningTools.md

@@ -125,6 +125,7 @@ let searchTool = try Tool<SearchParams, String, EmptyContext>(
 | Property | Default | Description |
 |---|---|---|
 | `isConcurrencySafe` | `false` | Whether the tool can safely run concurrently with other tools. ``Agent`` honors this: unsafe tools form exclusive barriers in the execution schedule. |
+| `isReadOnly` | `false` | Whether the tool only reads state without side effects. This is advisory metadata for callers and approval policy. |
 | `maxResultCharacters` | `nil` | Per-tool override for ``AgentConfiguration/maxToolResultCharacters``. When set, this limit governs instead of the global default. |
 | `strict` | `nil` | Whether the provider should enforce strict JSON Schema adherence on the tool's arguments. Preserved on first-party OpenAI Chat and Responses function tools where supported; unsupported providers reject strict schemas instead of dropping the request. |
 
@@ -134,7 +135,7 @@ When ``Agent`` executes sibling tool calls, it groups contiguous `isConcurrencyS
 
 ## Per-Tool Timeout
 
-Override ``AgentConfiguration/toolTimeout`` for a specific tool by passing `toolTimeout: Duration?` to ``Tool/init(name:description:isConcurrencySafe:maxResultCharacters:strict:toolTimeout:executor:)``. `nil` (the default) inherits the agent's configured timeout. Set an explicit `Duration` to apply a per-tool ceiling:
+Override ``AgentConfiguration/toolTimeout`` for a specific tool by passing `toolTimeout: Duration?` to ``Tool/init(name:description:isConcurrencySafe:isReadOnly:maxResultCharacters:strict:toolTimeout:executor:)``. `nil` (the default) inherits the agent's configured timeout. Set an explicit `Duration` to apply a per-tool ceiling:
 
 ```swift
 let deepPoll = try Tool<PollParams, PollResult, AppContext>(

Sources/AgentRunKit/Documentation.docc/Articles/SubAgents.md

@@ -96,7 +96,7 @@ When a sub-agent executes, ``SubAgentTool`` calls `descending()` to increment th
 
 **Tool timeout.** `toolTimeout` overrides the parent agent's default tool timeout for this sub-agent invocation. `nil` (the default) inherits the parent's ``AgentConfiguration/toolTimeout``.
 
-**Tool metadata.** `SubAgentTool` also exposes `isConcurrencySafe` and `maxResultCharacters`, matching `Tool`. ``Agent`` honors `isConcurrencySafe` for scheduling: sibling sub-agents default to sequential execution and must opt in to concurrent execution.
+**Tool metadata.** `SubAgentTool` also exposes `isConcurrencySafe`, `isReadOnly`, and `maxResultCharacters`, matching `Tool`. ``Agent`` honors `isConcurrencySafe` for scheduling: sibling sub-agents default to sequential execution and must opt in to concurrent execution. `isReadOnly` is advisory metadata for callers and approval policy.
 
 ## Streaming Propagation
 

Sources/AgentRunKit/LLM/Providers/Responses/ResponsesAPIClient.swift

@@ -353,4 +353,6 @@ extension ResponsesAPIClient {
 public extension ResponsesAPIClient {
     nonisolated static let openAIBaseURL =
         URL(validStaticString: "https://api.openai.com/v1")
+    nonisolated static let chatGPTBaseURL =
+        URL(validStaticString: "https://chatgpt.com/backend-api/codex")
 }

Sources/AgentRunKit/MCP/MCPClient.swift

@@ -51,6 +51,22 @@ public actor MCPClient {
         self.toolCallTimeout = toolCallTimeout
     }
 
+    #if os(macOS)
+        public init(configuration: MCPServerConfiguration) {
+            self.init(
+                serverName: configuration.name,
+                transport: StdioMCPTransport(
+                    command: configuration.command,
+                    arguments: configuration.arguments,
+                    environment: configuration.environment,
+                    workingDirectory: configuration.workingDirectory.map { URL(fileURLWithPath: $0) }
+                ),
+                initializationTimeout: configuration.initializationTimeout,
+                toolCallTimeout: configuration.toolCallTimeout
+            )
+        }
+    #endif
+
     func connectAndInitialize() async throws {
         guard case .created = state else {
             throw MCPError.connectionFailed("MCPClient is in state \(state), expected .created")

Sources/AgentRunKit/Tools/AnyTool.swift

@@ -13,6 +13,9 @@ public protocol AnyTool<Context>: Sendable {
     /// Whether this tool can safely execute concurrently with other tools.
     var isConcurrencySafe: Bool { get }
 
+    /// Whether this tool only reads state without producing side effects.
+    var isReadOnly: Bool { get }
+
     /// Per-tool override for the maximum tool result length before truncation, or `nil` to use the global default.
     var maxResultCharacters: Int? { get }
 
@@ -30,6 +33,10 @@ public extension AnyTool {
         false
     }
 
+    var isReadOnly: Bool {
+        false
+    }
+
     var maxResultCharacters: Int? {
         nil
     }

Sources/AgentRunKit/Tools/Tool.swift

@@ -10,6 +10,7 @@ public struct Tool<P: Codable & SchemaProviding & Sendable, O: Codable & Sendabl
     public let description: String
     public let parametersSchema: JSONSchema
     public let isConcurrencySafe: Bool
+    public let isReadOnly: Bool
     public let maxResultCharacters: Int?
     public let strict: Bool?
     public let toolTimeout: Duration?
@@ -19,6 +20,7 @@ public struct Tool<P: Codable & SchemaProviding & Sendable, O: Codable & Sendabl
         name: String,
         description: String,
         isConcurrencySafe: Bool = false,
+        isReadOnly: Bool = false,
         maxResultCharacters: Int? = nil,
         strict: Bool? = nil,
         toolTimeout: Duration? = nil,
@@ -34,6 +36,7 @@ public struct Tool<P: Codable & SchemaProviding & Sendable, O: Codable & Sendabl
         self.name = name
         self.description = description
         self.isConcurrencySafe = isConcurrencySafe
+        self.isReadOnly = isReadOnly
         self.maxResultCharacters = maxResultCharacters
         self.strict = strict
         self.toolTimeout = toolTimeout

Tests/AgentRunKitTests/LLM/Responses/ResponsesAPIClientTests.swift

@@ -13,6 +13,12 @@ struct ResponsesRequestSerializationTests {
         )
     }
 
+    @Test
+    func baseURLConstantsExposeOpenAIAndChatGPTEndpoints() {
+        #expect(ResponsesAPIClient.openAIBaseURL.absoluteString == "https://api.openai.com/v1")
+        #expect(ResponsesAPIClient.chatGPTBaseURL.absoluteString == "https://chatgpt.com/backend-api/codex")
+    }
+
     @Test
     func userMessageMapsToInputItem() async throws {
         let client = makeClient()

Tests/AgentRunKitTests/MCP/MCPClientTests.swift

@@ -45,6 +45,14 @@ struct MCPClientTests {
         await client.shutdown()
     }
 
+    #if os(macOS)
+        @Test
+        func configurationInitializerPreservesServerName() {
+            let client = MCPClient(configuration: MCPServerConfiguration(name: "configured", command: "/bin/test"))
+            #expect(client.serverName == "configured")
+        }
+    #endif
+
     @Test
     func initializeVersionMismatch() async throws {
         let transport = ScriptedMCPTransport(responses: [

Tests/AgentRunKitTests/Tools/SubAgentToolMetadataTests.swift

@@ -22,6 +22,7 @@ struct SubAgentToolMetadataTests {
         )
 
         #expect(tool.isConcurrencySafe == false)
+        #expect(tool.isReadOnly == false)
         #expect(tool.maxResultCharacters == nil)
         #expect(tool.toolTimeout == nil)
     }
@@ -34,12 +35,34 @@ struct SubAgentToolMetadataTests {
             description: "Research tool",
             agent: childAgent,
             isConcurrencySafe: true,
+            isReadOnly: true,
             maxResultCharacters: 500,
             toolTimeout: .seconds(5),
             messageBuilder: { $0.query }
         )
 
         #expect(tool.isConcurrencySafe == true)
+        #expect(tool.isReadOnly == true)
+        #expect(tool.maxResultCharacters == 500)
+        #expect(tool.toolTimeout == .seconds(5))
+    }
+
+    @Test
+    func factoryPreservesMetadataOverrides() throws {
+        let childAgent = Agent<SubAgentContext<EmptyContext>>(client: MockLLMClient(responses: []), tools: [])
+        let tool = try subAgentTool(
+            name: "research",
+            description: "Research tool",
+            agent: childAgent,
+            isConcurrencySafe: true,
+            isReadOnly: true,
+            maxResultCharacters: 500,
+            toolTimeout: .seconds(5),
+            messageBuilder: { (params: MetadataQueryParams) in params.query }
+        )
+
+        #expect(tool.isConcurrencySafe == true)
+        #expect(tool.isReadOnly == true)
         #expect(tool.maxResultCharacters == 500)
         #expect(tool.toolTimeout == .seconds(5))
     }