agent_request_queue.hpp

Go to the documentation of this file.

#pragma once
 
// agent_request_queue.hpp — a durable, file-backed queue of free-text requests
// a human raises from the running design (the inspector's "send to agent"
// affordance) for the driving agent to pick up on its next turn.
//
// The channel is PULL-BASED by design: the inspector appends a request; the
// agent reads the pending set at the top of its turn and acks what it consumes.
// Nothing is pushed to the agent, so it degrades honestly across agent harnesses
// — the worst case is the agent sees a request one turn later, never that a
// request is lost. This inverts nothing about the MCP request/response model: a
// `pulp_inspect_pending_requests` read tool surfaces the queue; the human's
// "send" button just enqueues a payload the agent reliably picks up.
//
// The queue lives beside the design ledger (`.pulp-design-meta.json`) as
// `.pulp-design-requests.json`, so a request is anchored to a specific project.
// On-disk schema:
//
//   {
//     "$schema": "pulp-design-requests://v1",
//     "version": 1,
//     "requests": [ { "id","text","design","screen",
//                     "editmode_state","screenshot_path","created_at",
//                     "consumed" }, ... ]
//   }
//
// The pure parse/serialize/append/ack functions are separable from disk I/O so
// the model is unit-testable without a filesystem. The file-backed wrappers add
// an atomic write (`<path>.tmp` then rename) so a crash mid-write never leaves a
// half-flushed queue at the canonical path. The core takes no clock and no RNG:
// `created_at` is supplied by the caller and ids are assigned deterministically
// from the existing contents, so a given input always yields the same output.
 
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace pulp::inspect {

struct AgentRequest {
    std::string id;              
    std::string text;            
    std::string design;          
    std::string screen;          
    std::string editmode_state;  
    std::string screenshot_path; 
    std::string created_at;      
    bool consumed = false;       
};

std::string_view queue_filename();

std::string requests_to_json(const std::vector<AgentRequest>& requests);

std::optional<std::vector<AgentRequest>> requests_from_json(std::string_view queue_json);

std::optional<std::string> append_request(std::string_view queue_json, AgentRequest request);

std::vector<AgentRequest> pending_requests(std::string_view queue_json);

std::optional<std::pair<std::string, bool>> ack_request(std::string_view queue_json,
                                                        std::string_view id);
 
// ── file-backed wrappers (atomic write) ─────────────────────────────────────

std::string queue_path(std::string_view project_dir);

std::optional<std::string> enqueue_to_file(const std::string& path, AgentRequest request);

std::vector<AgentRequest> read_pending_file(const std::string& path);

bool ack_in_file(const std::string& path, std::string_view id);
 
}  // namespace pulp::inspect