Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatAgents/Sources/AgentRunner.swift3// Description: Multi-step agent loop over any TextGenerating backend: tool calls, human approval checkpoints, limits, cancellation, structured run log.4import Foundation5import LocalChatCore67public struct ApprovalRequest: Sendable, Identifiable, Hashable {8 public var id: String // tool call id9 public var runID: UUID10 public var toolName: String11 public var risk: ToolRisk12 public var arguments: JSONValue13 public var summary: String // one line for the approval sheet14 public var canApproveForRun: Bool // false for tools that must be approved every time (shell)15}1617public enum ApprovalDecision: Sendable, Hashable, Codable {18 case approve19 case approveForRun // do not ask again for this tool during this run20 case deny(reason: String?)21}2223public enum AgentLimit: String, Sendable, Codable { case steps, toolCalls, time }2425public struct AgentTotals: Sendable, Hashable, Codable {26 public var steps = 027 public var toolCalls = 028 public var promptTokens = 029 public var completionTokens = 030 public var duration: TimeInterval = 031 public init() {}32}3334public struct AgentRunLog: Codable, Sendable, Identifiable, Hashable {35 public enum Outcome: Codable, Sendable, Hashable { case running, completed, limitReached(AgentLimit), cancelled, failed(String) }36 public enum Decision: String, Codable, Sendable { case notRequired, approved, approvedForRun, denied, rejected } // rejected = refused before approval (permission / schema)37 public struct ToolCallLog: Codable, Sendable, Hashable, Identifiable {38 public var id: String39 public var name: String40 public var arguments: JSONValue41 public var decision: Decision42 public var denialReason: String?43 public var output: String?44 public var isError: Bool45 public var startedAt: Date46 public var duration: TimeInterval47 }48 public struct Step: Codable, Sendable, Hashable {49 public var index: Int50 public var text: String51 public var reasoning: String52 public var toolCalls: [ToolCallLog]53 public var metrics: GenerationMetrics?54 public var startedAt: Date55 }56 public var id: UUID57 public var agentID: UUID58 public var agentName: String59 public var modelID: String60 public var task: String61 public var startedAt: Date62 public var endedAt: Date?63 public var steps: [Step]64 public var outcome: Outcome65 public var finalText: String66 public var totals: AgentTotals67}6869public enum AgentEvent: Sendable {70 case stepStarted(Int)71 case text(String)72 case reasoning(String)73 case toolRequested(ToolInvocation)74 case approvalNeeded(ApprovalRequest)75 case toolDenied(callID: String, reason: String)76 case toolStarted(callID: String, name: String)77 case toolFinished(callID: String, name: String, output: ToolOutput, duration: TimeInterval)78 case limitReached(AgentLimit)79 case finished(text: String, totals: AgentTotals, log: AgentRunLog)80 case failed(String, log: AgentRunLog)81}8283public struct AgentRunOptions: Sendable {84 public var perToolTimeout: TimeInterval85 public var toolOutputTokenBudget: Int // tool results longer than this are truncated before they reach the model86 /// Opt-in fallback for models without native tool calling: a reply that is a single fenced JSON object87 /// `{"tool": "<name>", "arguments": {…}}` is treated as a tool call. The system prompt then explains this format.88 public var allowTextToolCalls: Bool89 public var sessionKey: String?90 public init(perToolTimeout: TimeInterval = 60, toolOutputTokenBudget: Int = 2000, allowTextToolCalls: Bool = false, sessionKey: String? = nil) {91 self.perToolTimeout = perToolTimeout; self.toolOutputTokenBudget = toolOutputTokenBudget92 self.allowTextToolCalls = allowTextToolCalls; self.sessionKey = sessionKey93 }94}9596public struct AgentRunner: Sendable {97 public typealias Approver = @Sendable (ApprovalRequest) async -> ApprovalDecision98 let generator: any TextGenerating99 let registry: ToolRegistry100 let knowledge: (any KnowledgeSearching)?101102 public init(generator: any TextGenerating, registry: ToolRegistry, knowledge: (any KnowledgeSearching)? = nil) {103 self.generator = generator; self.registry = registry; self.knowledge = knowledge104 }105106 /// Runs the agent on `messages` (the conversation so far, ending with the user's task). Cancel by ending the stream's consumer task.107 /// With no approver, any call that needs approval is denied.108 public func run(agent: AgentConfiguration, modelID: String, messages: [PromptMessage], permissions: ToolPermissions,109 options: AgentRunOptions = .init(), approve: Approver? = nil) -> AsyncStream<AgentEvent> {110 AsyncStream { continuation in111 let task = Task { await self.loop(agent, modelID, messages, permissions, options, approve, continuation); continuation.finish() }112 continuation.onTermination = { _ in task.cancel() }113 }114 }115116 public static func systemPrompt(agent: AgentConfiguration, tools: [ToolDefinition], textToolCalls: Bool) -> String {117 var parts: [String] = []118 let instructions = agent.instructions.trimmingCharacters(in: .whitespacesAndNewlines)119 parts.append(instructions.isEmpty ? "You are \(agent.name), a helpful assistant that completes tasks step by step." : instructions)120 if !tools.isEmpty {121 parts.append("""122 You can use tools. Call a tool only when it helps; otherwise answer directly. Use one step at a time and read each result before deciding \123 the next step. If a tool fails or is denied, do not retry the same call: explain or try another way. When the task is done, give the final \124 answer in plain text without calling a tool. Never invent tool results.125 """)126 if textToolCalls {127 let list = tools.map { "- \($0.name): \($0.summary) Arguments schema: \($0.parameters.serialized())" }.joined(separator: "\n")128 parts.append("To call a tool, reply with only one fenced block:\n```json\n{\"tool\": \"<name>\", \"arguments\": { … }}\n```\nAvailable tools:\n\(list)")129 }130 }131 return parts.joined(separator: "\n\n")132 }133134 /// Parses the opt-in text form. Only a reply whose sole content is one JSON object with "tool" (and optional "arguments") counts.135 public static func parseTextToolCall(_ text: String) -> ToolInvocation? {136 var body = text.trimmingCharacters(in: .whitespacesAndNewlines)137 if body.hasPrefix("```") {138 guard body.hasSuffix("```"), body.components(separatedBy: "```").count == 3 else { return nil }139 body = String(body.dropFirst(3).dropLast(3))140 if let newline = body.firstIndex(of: "\n"), body[..<newline].allSatisfy({ $0.isLetter }) { body = String(body[body.index(after: newline)...]) }141 body = body.trimmingCharacters(in: .whitespacesAndNewlines)142 } else { return nil }143 guard let value = JSONValue.parse(body), let object = value.objectValue, let name = object["tool"]?.stringValue, !name.isEmpty,144 Set(object.keys).isSubset(of: ["tool", "arguments"]) else { return nil }145 return ToolInvocation(name: name, arguments: object["arguments"] ?? .object([:]))146 }147148 static func describe(_ call: ToolInvocation) -> String {149 switch call.name {150 case "run_shell": return "Run: " + (call.arguments["command"]?.stringValue ?? "")151 case "write_file": return "Write \(call.arguments["path"]?.stringValue ?? "a file") (\((call.arguments["content"]?.stringValue ?? "").utf8.count) bytes)"152 case "fetch_url": return "Fetch " + (call.arguments["url"]?.stringValue ?? "")153 default: return "\(call.name) \(call.arguments.serialized())".prefix(300).description154 }155 }156157 static func truncate(_ text: String, tokens: Int) -> String {158 let limit = max(200, tokens * 4)159 guard text.count > limit else { return text }160 let head = text.prefix(limit * 3 / 4), tail = text.suffix(limit / 4)161 return "\(head)\n[… \(text.count - limit) characters omitted …]\n\(tail)"162 }163164 private func loop(_ agent: AgentConfiguration, _ modelID: String, _ input: [PromptMessage], _ permissions: ToolPermissions,165 _ options: AgentRunOptions, _ approve: Approver?, _ out: AsyncStream<AgentEvent>.Continuation) async {166 let started = Date()167 let deadline = started.addingTimeInterval(TimeInterval(max(1, agent.timeLimitSeconds)))168 let definitions = registry.definitions(for: permissions)169 let context = ToolContext(permissions: permissions, knowledge: knowledge, collectionIDs: agent.collectionIDs)170 var messages = input.filter { $0.role != .system }171 let extraSystem = input.filter { $0.role == .system }.map(\.content)172 let system = ([Self.systemPrompt(agent: agent, tools: definitions, textToolCalls: options.allowTextToolCalls)] + extraSystem).joined(separator: "\n\n")173 var log = AgentRunLog(id: UUID(), agentID: agent.id, agentName: agent.name, modelID: modelID,174 task: messages.last(where: { $0.role == .user })?.content ?? "", startedAt: started, endedAt: nil, steps: [],175 outcome: .running, finalText: "", totals: AgentTotals())176 var approvedForRun: Set<String> = []177 var finalText = ""; var limit: AgentLimit?178179 func close(_ outcome: AgentRunLog.Outcome) -> AgentRunLog {180 log.outcome = outcome; log.endedAt = Date(); log.finalText = finalText181 log.totals.duration = Date().timeIntervalSince(started); log.totals.steps = log.steps.count182 return log183 }184185 /// One model turn. Returns nil when the run must stop (cancelled / failed / time limit, already reported).186 func generate(step: Int, tools: [ToolDefinition]) async -> (text: String, calls: [ToolInvocation])? {187 out.yield(.stepStarted(step))188 var text = "", reasoning = "", calls: [ToolInvocation] = []; var metrics: GenerationMetrics?189 let request = GenerationRequest(messages: [.system(system)] + messages, settings: agent.settings, tools: tools, sessionKey: options.sessionKey)190 let stepStart = Date()191 do {192 for try await event in generator.generate(modelID: modelID, request: request) {193 try Task.checkCancellation()194 if Date() > deadline { limit = .time; break }195 switch event {196 case .text(let t): text += t; out.yield(.text(t))197 case .reasoning(let t): reasoning += t; out.yield(.reasoning(t))198 case .toolCall(let call): calls.append(call)199 case .finished(let m): metrics = m200 }201 }202 } catch {203 log.steps.append(.init(index: step, text: text, reasoning: reasoning, toolCalls: [], metrics: metrics, startedAt: stepStart))204 finalText = text205 if error is CancellationError || Task.isCancelled || (error as? InferenceError) == .cancelled { _ = close(.cancelled) }206 else {207 let message = (error as? LocalizedError)?.errorDescription ?? String(describing: error)208 out.yield(.failed(message, log: close(.failed(message))))209 }210 return nil211 }212 log.totals.promptTokens += metrics?.promptTokens ?? 0; log.totals.completionTokens += metrics?.completionTokens ?? 0213 if calls.isEmpty, options.allowTextToolCalls, !tools.isEmpty, let parsed = Self.parseTextToolCall(text) { calls = [parsed]; text = "" }214 log.steps.append(.init(index: step, text: text, reasoning: reasoning, toolCalls: [], metrics: metrics, startedAt: stepStart))215 if limit == .time {216 finalText = text; out.yield(.limitReached(.time))217 out.yield(.finished(text: finalText, totals: close(.limitReached(.time)).totals, log: log))218 return nil219 }220 return (text, calls)221 }222223 var step = 0224 while true {225 if Task.isCancelled { _ = close(.cancelled); return }226 if Date() > deadline { limit = .time; break }227 if step >= max(1, agent.maxSteps) { limit = .steps; break }228 step += 1229 guard let turn = await generate(step: step, tools: definitions) else { return }230 if turn.calls.isEmpty { finalText = turn.text; break }231 messages.append(PromptMessage(role: .assistant, content: turn.text, toolCalls: turn.calls))232233 for call in turn.calls {234 if Task.isCancelled { _ = close(.cancelled); return }235 out.yield(.toolRequested(call))236 var entry = AgentRunLog.ToolCallLog(id: call.id, name: call.name, arguments: call.arguments, decision: .notRequired, denialReason: nil,237 output: nil, isError: false, startedAt: Date(), duration: 0)238 var output: ToolOutput239 if log.totals.toolCalls >= max(0, agent.maxToolCalls) {240 limit = .toolCalls; entry.decision = .rejected241 output = .error("The tool-call budget for this task is exhausted. Answer with what you have.")242 } else if Date() > deadline {243 limit = .time; entry.decision = .rejected; output = .error("The time limit for this task is reached.")244 } else {245 switch registry.prepare(call, permissions: permissions) {246 case .failure(let error):247 entry.decision = .rejected; output = .error(error.message)248 case .success(let ready):249 var allowed = true250 let needsApproval = registry.requiresApproval(ready.tool, permissions: permissions)251 && !(approvedForRun.contains(call.name) && !ready.tool.alwaysRequiresApproval)252 output = .error("Denied.")253 if needsApproval {254 let request = ApprovalRequest(id: call.id, runID: log.id, toolName: call.name, risk: ready.tool.risk, arguments: ready.arguments,255 summary: Self.describe(call), canApproveForRun: !ready.tool.alwaysRequiresApproval)256 out.yield(.approvalNeeded(request))257 let decision = await approve?(request) ?? .deny(reason: "No one is available to approve this action.")258 if Task.isCancelled { _ = close(.cancelled); return }259 switch decision {260 case .approve: entry.decision = .approved261 case .approveForRun:262 entry.decision = ready.tool.alwaysRequiresApproval ? .approved : .approvedForRun263 if !ready.tool.alwaysRequiresApproval { approvedForRun.insert(call.name) }264 case .deny(let reason):265 allowed = false; entry.decision = .denied; entry.denialReason = reason266 let why = reason.flatMap { $0.isEmpty ? nil : $0 }267 output = .error("The user denied this action" + (why.map { ": \($0)" } ?? ".") + " Do not retry it.")268 out.yield(.toolDenied(callID: call.id, reason: why ?? "Denied by the user."))269 }270 }271 if allowed {272 log.totals.toolCalls += 1273 out.yield(.toolStarted(callID: call.id, name: call.name))274 let t0 = Date()275 let prepared = ToolInvocation(id: call.id, name: call.name, arguments: ready.arguments)276 output = await Self.withTimeout(min(options.perToolTimeout, max(1, deadline.timeIntervalSinceNow))) {277 await registry.execute(prepared, context: context)278 } ?? .error("The tool timed out after \(Int(options.perToolTimeout)) s.")279 entry.duration = Date().timeIntervalSince(t0)280 if Task.isCancelled { entry.output = output.text; entry.isError = true; log.steps[log.steps.count - 1].toolCalls.append(entry); _ = close(.cancelled); return }281 output.text = Self.truncate(output.text, tokens: options.toolOutputTokenBudget)282 out.yield(.toolFinished(callID: call.id, name: call.name, output: output, duration: entry.duration))283 }284 }285 }286 entry.output = output.text; entry.isError = output.isError287 log.steps[log.steps.count - 1].toolCalls.append(entry)288 messages.append(PromptMessage(role: .tool, content: output.text, toolCallID: call.id, toolName: call.name))289 }290 if limit != nil { break }291 }292293 if let reached = limit {294 out.yield(.limitReached(reached))295 if reached != .time, !Task.isCancelled {296 // one last turn without tools so the user still gets an answer from what was gathered297 messages.append(.user("You have reached the limit of actions for this task. Do not call tools. Give your best final answer now from what you already know, and say what is missing."))298 guard let turn = await generate(step: step + 1, tools: []) else { return }299 finalText = turn.text300 }301 out.yield(.finished(text: finalText, totals: close(.limitReached(reached)).totals, log: log))302 return303 }304 if Task.isCancelled { _ = close(.cancelled); return }305 out.yield(.finished(text: finalText, totals: close(.completed).totals, log: log))306 }307308 /// Runs `work`, returning nil when it takes longer than `seconds` (the work is cancelled).309 static func withTimeout<T: Sendable>(_ seconds: TimeInterval, _ work: @escaping @Sendable () async -> T) async -> T? {310 await withTaskGroup(of: T?.self) { group in311 group.addTask { await work() }312 group.addTask { try? await Task.sleep(nanoseconds: UInt64(max(0.01, seconds) * 1e9)); return nil }313 let first = await group.next() ?? nil314 group.cancelAll()315 return first316 }317 }318}319320/// File-backed store of run logs (one JSON file per run).321public struct AgentLogStore: Sendable {322 public let directory: URL323 public init(directory: URL) { self.directory = directory; try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) }324325 private func url(_ id: UUID) -> URL { directory.appendingPathComponent(id.uuidString + ".json") }326327 public func save(_ log: AgentRunLog) throws {328 let encoder = CoreCoding.encoder; encoder.outputFormatting = [.sortedKeys, .prettyPrinted]329 try encoder.encode(log).write(to: url(log.id), options: .atomic)330 }331 public func load(_ id: UUID) throws -> AgentRunLog { try CoreCoding.decoder.decode(AgentRunLog.self, from: Data(contentsOf: url(id))) }332333 /// Newest first. Unreadable files are skipped.334 public func list(agentID: UUID? = nil, limit: Int = 200) -> [AgentRunLog] {335 let files = (try? FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)) ?? []336 return files.filter { $0.pathExtension == "json" }337 .compactMap { try? CoreCoding.decoder.decode(AgentRunLog.self, from: Data(contentsOf: $0)) }338 .filter { agentID == nil || $0.agentID == agentID }339 .sorted { $0.startedAt > $1.startedAt }.prefix(limit).map { $0 }340 }341 @discardableResult public func delete(_ id: UUID) -> Bool { (try? FileManager.default.removeItem(at: url(id))) != nil }342 public func deleteAll() { for log in list(limit: .max) { delete(log.id) } }343}344