API — ICoreBlocks/ICoreStudio/AgentBridge

The public contract of 4 header(s) under src/ICoreBlocks/ICoreStudio/AgentBridge — 4 class/struct definition(s), 27 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreAgentBridge.h#

src/ICoreBlocks/ICoreStudio/AgentBridge/ICoreAgentBridge.h

ICoreAgentBridge#

ICoreAgentBridge.h:41 · class · final · 13 declaration(s)

ICoreAgentBridge How a coding agent reaches the running app (the agent-bridge board, AB.4-AB.6).

class ICoreAgentBridge final {
public:
    // The protocol version `hello` reports. A client that needs more checks it.
    static int protocolVersion();

    // Starts listening, installs the client and publishes the session file.
    // Idempotent: true when the bridge is (now) running. Does not consult the
    // preference -- startForSession() does.
    static bool start();

    // What a windowed session calls at startup: start() when the "agent
    // bridge" preference is on (it is by default), nothing otherwise.
    static void startForSession();

    // Stops listening and withdraws the session file and the socket.
    static void stop();

    [[nodiscard]] static bool isRunning();

    // The socket file clients connect to; empty when not running.
    [[nodiscard]] static std::string socketPath();

    // <application home>/agent -- the client, the session files, scratch.
    [[nodiscard]] static std::filesystem::path agentFolder();

    // <agentFolder>/icore.py. Written by start(); installClient() writes it
    // without starting anything (the project guides name this path).
    [[nodiscard]] static std::filesystem::path clientPath();
    static bool installClient();

    // The command that runs the client on this machine: the absolute path of a
    // Python pinned in Tools > Toolchains when there is one; otherwise
    // `python3`, except on Windows, where it is the first of
    // `py`, `python`, `python3` on PATH (the Store's placeholder alias does not
    // count), else `python`. The guides and
    // .mcp.json spell it; on Windows installClient() also writes
    // <agentFolder>/icore.cmd, a one-line launcher that uses it, so `icore`
    // resolves in the Terminal panel's shell (AB.13).
    [[nodiscard]] static std::string pythonCommand();

    // The bridge in a process with no window (`agentServe`, AB.9): start(),
    // then pump the event loop until `seconds` pass, or -- with 0 -- until a
    // client sends the `shutdown` op, which only a serving process honours.
    // Returns the process exit code the console command should report.
    static int serveHeadless(int seconds);

    // Answers one request line with one response line (no trailing newline).
    // The socket handler is a thin loop around this; public so a regression
    // case can drive the protocol without a socket.
    static std::string handleRequest(const std::string& requestLine);

    // (name, value) pairs for a shell started by the Terminal panel:
    // ICORE_AGENT_CLI and PATH (the inherited PATH with agentFolder() first)
    // always; ICORE_AGENT_SOCKET while the bridge runs; ICORE_PROJECT_DIR
    // while a project is open.
    [[nodiscard]] static std::vector<std::pair<std::string, std::string>> terminalEnvironment();
};
};

ICoreAgentCommands.h#

src/ICoreBlocks/ICoreStudio/AgentBridge/ICoreAgentCommands.h

ICoreAgentCommands#

ICoreAgentCommands.h:28 · class · final · 1 declaration(s)

ICoreAgentCommands The console's side of the agent-bridge board: agentGuide [status|write|refresh|on|off] The coding-agent guides (ICoreProjectAgentGuide) in the open project, and whether new proje...

class ICoreAgentCommands final {
public:
    static void registerAll();
};
};

ICoreAgentSandbox.h#

src/ICoreBlocks/ICoreStudio/AgentBridge/ICoreAgentSandbox.h

ICoreAgentSandbox#

ICoreAgentSandbox.h:49 · class · final · nested Job, Verdict · 7 declaration(s)

ICoreAgentSandbox A coding agent's change is tried in ANOTHER PROCESS before the open model sees it (the agent-bridge board, AB.27-AB.28).

class ICoreAgentSandbox final {
public:
    // What to check.
    struct Job {
        // The project's FOLDER as it is on disk (what `reload` would load), or
        // the model ON SCREEN with its settings (what push/apply/eval act on).
        enum class Source { ProjectFolder, OpenModel };
        Source source = Source::OpenModel;

        // For Source::ProjectFolder: the folder to check; empty is the open
        // project's. (`icore check` asks for the folder the agent is in.)
        std::filesystem::path projectFolder;

        // One bridge request line (JSON) to apply to the copy after it opens;
        // empty applies nothing.
        std::string requestLine;

        // An `eval` request is judged by survival only: its statements may name
        // variables that live only in the app's workspace, so an ordinary error
        // in the copy is not a reason to refuse it -- a crash or a hang is.
        bool survivalOnly = false;

        bool simulate = true;
        std::vector<std::string> blocks;     // as `simulate` takes them; empty = every sink
        std::string csv;                     // absolute path, or empty

        int timeoutSeconds = 120;

        // Test support: makes the CHILD crash or hang on purpose at one step
        // ("crash:open", "crash:edit", "crash:simulate", "hang:simulate").
        std::string testFault;
    };

    struct Verdict {
        bool green = false;          // the live app may go on
        bool ran = false;            // the child started and ended (or was stopped)
        bool crashed = false;
        bool timedOut = false;
        std::string summary;         // one paragraph: what happened and why
        std::string phase;           // the step the child was in when it ended
        std::string crashReport;     // the signal and the stack (demangled), when it crashed
        std::string verdictJson;     // the child's own verdict.json, when it wrote one
        std::string jobFolder;       // kept on disk when the verdict is red
    };

    // Runs `job` in a child process and waits for it, pumping the event loop.
    static Verdict run(const Job& job);

    // The verdict as one JSON object (compact), for a bridge answer.
    [[nodiscard]] static std::string toJson(const Verdict& verdict);

    // Whether the bridge checks first (the "agents/checkFirst" preference, on
    // by default). Always false inside the child itself.
    [[nodiscard]] static bool isEnabled();

    // True in a process started for a check: the bridge applies requests
    // directly there, since the process IS the sandbox.
    [[nodiscard]] static bool isInsideCheck();

    // The child's side: the body of `agentCheck [<job folder>]` (the folder
    // defaults to $ICORE_AGENT_CHECK_JOB, which is how run() hands it over).
    // Writes <job>/verdict.json and returns the process exit code: 0 green,
    // 1 red, 2 the job could not be read. `summary` gets the verdict's text.
    static int runCheck(const std::filesystem::path& jobFolder, std::string* summary = nullptr);

    // The binary a check runs: this one.
    [[nodiscard]] static std::filesystem::path executable();

    // Writes <agentFolder>/app.json naming executable(), for `icore check`.
    static void publishExecutable(const std::filesystem::path& agentFolder);
};
};

ICoreProjectAgentGuide.h#

src/ICoreBlocks/ICoreStudio/AgentBridge/ICoreProjectAgentGuide.h

ICoreProjectAgentGuide#

ICoreProjectAgentGuide.h:26 · class · final · nested FileOutcome · 6 declaration(s)

ICoreProjectAgentGuide The instructions a coding agent finds in a project folder (the agent-bridge board, AB.1-AB.3): one canonical guide, read by Codex, Cursor, Copilot and most others; one each f...

class ICoreProjectAgentGuide final {
public:
    // What one call did to one file, for the console command's report.
    struct FileOutcome {
        std::string fileName;     // one of managedFileNames()
        std::string action;       // "written", "refreshed", "kept (yours)", "up to date", "failed: <why>"
    };

    // Writes every guide file that is MISSING from `projectFolder`. Existing
    // files are left exactly as they are. What New Project and a project made
    // from a template call, through writeForNewProject().
    static std::vector<FileOutcome> writeMissing(const std::filesystem::path& projectFolder);

    // writeMissing(), and also rewrites every file that still carries the
    // generator's marker (a newer app's text, a moved client). Files without
    // the marker are the user's and are reported, not touched.
    static std::vector<FileOutcome> refresh(const std::filesystem::path& projectFolder);

    // writeMissing() when the "agent guides for new projects" preference is on
    // (it is by default); nothing otherwise. Never raises a dialog: a failure
    // to write is logged, and the project is created either way.
    static void writeForNewProject(const std::filesystem::path& projectFolder);

    // The file names this class manages, in the order it writes them.
    static std::vector<std::string> managedFileNames();

    // The first line of every generated .md file. Public so a test can tell a
    // generated file from a user's without restating the text.
    static const std::string& markerLine();

    // True when `text` (a whole file, or its first line) starts with the marker
    // of ANY version of the generator, so an older generated guide still reads
    // as generated, and is refreshed rather than kept as the user's.
    static bool isGenerated(const std::string& text);
};
};