SPB Git

Repository Public

NotesAPI+Agents.swift 3.9 KB 69 lines swift

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
Files main
Menu

Theme