Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+Agents.swift3// Description: The bounded agents: catalogue and executions, starting a run, and deciding its proposals (approve,4// reject, undo, cancel).5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910extension NotesAPI {11 /// `GET /api/agents[?limit=]` — the catalogue, where a run would be sent, the last executions (1…100, default 40).12 public func agents(limit: Int? = nil) async throws -> AgentCatalogue {13 try await client.decode(AgentCatalogue.self, .get("/api/agents", query: Self.item("limit", limit.map(String.init))))14 }1516 private struct RunBody: Encodable {17 var agent: String18 var pageId: String?19 var confirmCost: Bool?20 }2122 /// `POST /api/agents` `{ agent, pageId?, confirmCost }` → 201 — queues a run. **A confirmed run calls a paid23 /// model** (capped by the agent's `limits.maxCostUsd`). `confirmCost` must be `true` and states that the owner24 /// saw the scope and the cost limit: without it the server answers `409 confirm_required`25 /// (`APIError.needsCostConfirmation`) and nothing is started. Other errors: `400 unknown_agent | page_required`,26 /// `404` page, `409 already_running` (`APIError.runningExecutionID`), `503 not_configured | queue_unavailable`.27 public func runAgent(_ agent: String, pageID: String? = nil, confirmCost: Bool) async throws -> AgentRunStarted {28 try await client.decode(AgentRunStarted.self, .json(.post, "/api/agents", body: RunBody(agent: agent, pageId: pageID, confirmCost: confirmCost ? true : nil)))29 }3031 /// `GET /api/agents/<id>` — one execution with its proposals and log. `404` (no code) when unknown.32 public func agentExecution(id: String) async throws -> AgentExecution {33 try await client.decode(AgentExecution.self, .get("/api/agents/\(Self.segment(id))"))34 }3536 private struct DecisionBody: Encodable {37 var action: String38 var changes: [Int]?39 var confirmDestructive: Bool?40 }4142 private func agentAction<T: Decodable & Sendable>(_ id: String, _ body: DecisionBody, _ key: String?) async throws -> T {43 try await client.decode(T.self, .json(.post, "/api/agents/\(Self.segment(id))", body: body, idempotencyKey: key))44 }4546 /// `POST /api/agents/<id>` `{ action: "approve", changes, confirmDestructive? }` — applies proposals (1…20047 /// indices): the only way an agent proposal is ever written. Trash proposals need `confirmDestructive` (409 otherwise).48 public func approveAgentProposals(executionID: String, changes: [Int], confirmDestructive: Bool = false, idempotencyKey: String? = nil) async throws -> AgentDecisionResult {49 try await agentAction(executionID, DecisionBody(action: "approve", changes: changes, confirmDestructive: confirmDestructive ? true : nil), idempotencyKey)50 }5152 /// `POST /api/agents/<id>` `{ action: "reject", changes }`.53 public func rejectAgentProposals(executionID: String, changes: [Int], idempotencyKey: String? = nil) async throws -> AgentDecisionResult {54 try await agentAction(executionID, DecisionBody(action: "reject", changes: changes), idempotencyKey)55 }5657 /// `POST /api/agents/<id>` `{ action: "undo", changes }` — reverses applied proposals.58 public func undoAgentProposals(executionID: String, changes: [Int], idempotencyKey: String? = nil) async throws -> AgentUndoResult {59 try await agentAction(executionID, DecisionBody(action: "undo", changes: changes), idempotencyKey)60 }6162 /// `POST /api/agents/<id>` `{ action: "cancel" }` — stops a pending or running run (nothing of it survives), or63 /// rejects the proposals still waiting. `409` for a finished run.64 @discardableResult65 public func cancelAgentExecution(id: String, idempotencyKey: String? = nil) async throws -> OKResult {66 try await agentAction(id, DecisionBody(action: "cancel"), idempotencyKey)67 }68}69