/* runvil_plugin.h * * Generated by `cargo xtask header` from crates/runvil-plugin-sys/src/lib.rs. * Edit that file and regenerate; never edit this one. * * The C contract every Plugin entry point follows, library or linked. * `runvil_plugin.h` declares it for C and C++, and the `runvil-plugin-sys` * crate mirrors it for Rust; `cargo xtask header` writes the header from * the crate's source, comments included, so the two never disagree. * * A Plugin is one entry point, with the shape of `runvil_plugin`. A * library Plugin exports it under that name; a linked Plugin has the same * shape under any name. * * # The contract * * - Every call passes an `RvCall` that names a verb. The call carries * three pointers that belong to the Plugin, which the Host stores and * passes back and never reads through: `plugin`, the Plugin instance; * `pack_run`, one run's instance of a Pack; and `tool_call`, the state * one tool call keeps between its steps. * - `RvHost` holds only what is true on every call: the contract version * the Host speaks. Each function a Plugin may call back belongs to one * verb and sits in that verb's arguments struct, behind `call->args`, * beside the `ctx` pointer it takes first. * - Strings are a pointer plus a length, UTF-8, not NUL-terminated. Each * string a Plugin passes has a limit in bytes, which one of the * `RV_MAX_` constants names, and a longer string is a misuse. The * bytes a Plugin passes for a file have such a limit too. * - A struct, a string, or a run of bytes that one side passes to the * other is valid only until the function it was passed to returns. The * receiver copies what it keeps. The answer to a file request stays * valid for the whole step that receives it, as the section on files * says. * - Verb names follow `RV__`. Libraries open and close; * Plugins load and unload. * * # Verbs * * - `RV_PLUGIN_LOAD` (1), with an `RvLoadArgs`: makes the Plugin * instance and sets `call->plugin`, names the Plugin once with * `describe_plugin`, and inserts each of the Plugin's Packs with * `insert_pack`. * - `RV_PLUGIN_UNLOAD` (2), with no arguments: frees `call->plugin`. * - `RV_PACK_NEW` (3), with an `RvPackNewArgs`: makes one run's * instance of a Pack and sets `call->pack_run`, and lists that * instance's tools with `add_tool`. * - `RV_PACK_DELETE` (4), with no arguments: frees `call->pack_run`. * - `RV_TOOL_CALL` (5), with an `RvToolCallArgs`: runs one step of a * tool call on `call->pack_run`. * - `RV_TOOL_CANCEL` (6), with no arguments: frees `call->tool_call`, * the state of a tool call the Host has abandoned. * * A Plugin answers a verb it does not know with `RV_ERR_UNSUPPORTED`. * `RV_PLUGIN_UNLOAD`, `RV_PACK_DELETE`, and `RV_TOOL_CANCEL` return * `RV_OK`, and the Host ignores their status. * * # Packs * * - A Plugin inserts each of its Packs once, while it loads. The Host * makes one instance of a Pack for each run that holds the Pack, with * `RV_PACK_NEW`, and frees the instance with `RV_PACK_DELETE` when * the run ends. * - An instance's tools are the ones it adds during `RV_PACK_NEW`, and * they stay fixed for the run. The Host forms each tool's id from the * Pack's id, which is the second segment of the Pack's name, and the * tool's name: the tool `fetch` of the Pack `acme/url` is `url/fetch`. * - `RV_PACK_NEW` runs while the Host prepares a run, so it returns * promptly: it does not block and does no I/O. What is costly to make * belongs in the Plugin instance, which every run shares. * * # Tool calls * * - A tool call is a series of steps. The Host starts the call by sending * `RV_TOOL_CALL` with `call->tool_call` NULL, and that step may set * `call->tool_call` to state of its own. A step that returns * `RV_PENDING` asks for another step: the Host sends `RV_TOOL_CALL` * again with the same `tool`, the same `arguments`, and the * `call->tool_call` the last step left. * - A step ends the call by calling `finish` once and returning * `RV_OK`. Any return other than `RV_PENDING` ends the call, and a * call that ends without a result fails. * - The Host may abandon a call between two steps, for example when its * run is canceled. It then sends `RV_TOOL_CANCEL` once, with the * `call->tool_call` the last step left, and no further step. * - A step does a bounded slice of work and returns. A step that works * for long, or blocks, stalls its run, and a run can be canceled only * between steps. * - A step that made a file request waits for its answer by returning * `RV_PENDING`, as the section on files says. `RV_PENDING` is a way * to wait for nothing else: after a step that made no request, the Host * sends the next step as soon as the run's other work has had a turn. * - A tool whose calls change files sets `RV_TOOL_CHANGES_FILES` in the * `flags` of its `RvToolInfo`. Of the calls that one reply of a model * asks for, the Host runs a call of such a tool by itself: the call * starts when every call the reply lists before it has ended, and the * calls the reply lists after it start when it has ended. So two * changes of one reply happen in the order the reply lists them. The * calls of tools without the flag may run at the same time. * * # Files * * - A tool call reaches its run's files only through the nine file * functions in its `RvToolCallArgs`, so the run's policy applies to * every operation. `file_stat`, `file_list`, and `file_read` read. * `file_write`, `file_append`, `file_mkdir`, `file_remove`, * `file_rename`, and `file_copy` change the files. * - A file function only takes a request. It returns `RV_OK` when the * Host took the request and `RV_ERR_MISUSE` for a misuse, and it * fills nothing. The call's next step receives the answer: `answer` in * that step's `RvToolCallArgs` points to an `RvFileAnswer`. In a * step that follows no request, `answer` is NULL. * - A call has one request outstanding at a time. A second request in * one step is a misuse, and so is a request in a step that calls * `finish`. * - A step that made a request returns `RV_PENDING`. The Host sends * that call its next step when the answer is ready, and no step before * then. * - An answer's `status` is `RV_OK` or `RV_ERR_FILE`. With `RV_OK` * the answer holds what the request asked for, in the one field its * file function names. A function that changes the files names no * field, so its answer holds a status alone. With `RV_ERR_FILE` the * answer's `error` says what went wrong. Every other field of the * answer is zero. An operation that fails does not fail the tool call: * the tool decides what its result says. * - The answer, and what it points to, is valid for the step that * receives it: the bytes, the entries and the names in them, and an * error's text. All of it belongs to the Host. The Plugin copies what * it keeps and frees none of it. * - The Host holds an answer in memory, so a Plugin reads a large file in * ranges. `file_write` and `file_append` take at most `RV_MAX_WRITE` * bytes, so a Plugin writes a longer file as one `file_write` and then * one `file_append` for each further part. * - `file_write`, `file_append`, `file_rename`, and `file_copy` make each * directory that is absent on the way to the path they write, and * `file_mkdir` does when its `recursive` is 1. * - When the Host abandons a call, an operation it had taken either * happened in full or did not happen. * - A path names a file of the run, with `/` between its segments, and is * at most `RV_MAX_PATH` bytes long. Every path is taken from the run's * root, whether or not it begins with `/`. An empty segment and a `.` * segment change nothing, a `..` segment steps up one directory, and a * `\` is read as `/`. An empty path, and a path that steps above the * root, fail as file errors. * - The answer to `file_stat`, and each entry in the answer to * `file_list`, describe a link and not what it leads to. `file_mkdir`, * `file_remove`, and `file_rename` act on a link itself. Every other * file function acts on what a link leads to. * * # Threads and lifetime * * - `RV_PLUGIN_LOAD` runs on the thread on which the Host loads the * Plugin. Every other verb may come on any thread, and the steps of one * tool call may come on different threads. * - Calls may run at the same time on different threads, with three * exceptions. No two steps of one tool call run at the same time, and * `RV_TOOL_CANCEL` runs beside no step of its call. * `RV_PACK_DELETE` comes after every tool call of its * `pack_run` has ended, and runs beside no call that names it. * `RV_PLUGIN_UNLOAD` comes after every Pack instance of the Plugin is * deleted, and runs beside no other call. * - The functions in a verb's arguments struct answer only while that * call runs, only on its thread, and only for its `ctx`. Any other use * returns `RV_ERR_MISUSE`, and so does a function called against its * own rules, such as `describe_plugin` called twice. A misuse on the * call's own thread fails that call, whatever status the Plugin * returns. A function called on another thread while its call runs * returns `RV_ERR_MISUSE` and has no other effect. * - The Host keeps the `ctx` of a load valid while the Plugin is loaded, * until `RV_PLUGIN_UNLOAD` returns, so a late call through it is * answered `RV_ERR_MISUSE` instead of reaching freed memory. The `ctx` * of a load the Host rejects, and the `ctx` of every other call, is * gone once the call returns, and the Plugin must not use it. * - `RV_PLUGIN_UNLOAD` must stop every thread the Plugin started and * release everything it holds before it returns. A library Plugin's * library closes right after, and a thread still running crashes the * process. * * # What the Plugin frees * * - A load the Host rejects gets no `RV_PLUGIN_UNLOAD`: a refusal, a * misuse, a status other than `RV_OK`, or no description. The Plugin * frees whatever it made before it returns on every such path. A load * that succeeds is unloaded later, even if the Host then drops the * Plugin, for example because its name repeats one already loaded. * - An `RV_PACK_NEW` the Host rejects gets no `RV_PACK_DELETE`: a * refusal, a misuse, or a status other than `RV_OK`. The Plugin frees * whatever it made before it returns on every such path. One that * succeeds gets exactly one `RV_PACK_DELETE`. * - The step that ends a tool call frees the call's state before it * returns. A call that is abandoned gets `RV_TOOL_CANCEL` instead, * which frees the state; its `call->tool_call` is NULL when no step set * it. Each call gets one or the other, never both. * * # Reserved numbers * * Verbs 7 and 8 and status codes 1 to 3 are reserved for later versions, * so those numbers never get another meaning. This version declares no * constant for them, sends neither verb, and returns none of those codes. * * # Status codes * * - `RV_OK` (0) is success. * - Codes 1 to 3 are reserved. * - `RV_ERR_MISUSE` (4) means the caller broke the contract. * - `RV_ERR_REFUSED` (5) means the Plugin declined: to load, or to make * a Pack instance. * - `RV_ERR_UNSUPPORTED` (6) means the Plugin cannot answer the call: it * does not know the verb, the Host reports a version the Plugin was not * built for, or a struct's `size` is smaller than the Plugin expects. * - `RV_PENDING` (7) means a tool call needs another step. Only * `RV_TOOL_CALL` returns it. * - `RV_ERR_FILE` (8) means a file operation failed. No function * returns it: it is the `status` of an `RvFileAnswer`, whose `error` * says what went wrong. * * # Versions * * - `RV_API_MAJOR` and `RV_API_MINOR` name the contract's version, and * the `runvil-plugin-sys` crate's version is the same number. * - A 0.x version makes no compatibility promise. Each one is a contract * of its own, and a Plugin built for one loads only in a Host whose * `RvHost` reports exactly that version. The Plugin checks the * version first in `RV_PLUGIN_LOAD`, before it reads `call->args`, * and answers a version it was not built for with * `RV_ERR_UNSUPPORTED`. * - From 1.0, a minor version only adds: a field at the end of a struct * that has a `size` field, which shows whether the field is there, such * as a function at the end of a verb's arguments struct; a verb with an * arguments struct of its own; or a number for a result kind, a file * type, a file error kind, or a tool flag. A struct with no `size` * field never changes. A Plugin built for 1.n loads in a Host that * reports major version 1 and a minor version of at least n. */ #ifndef RUNVIL_PLUGIN_H #define RUNVIL_PLUGIN_H #include #include typedef struct RvStr RvStr; typedef struct RvBytes RvBytes; typedef struct RvStat RvStat; typedef struct RvDirEntry RvDirEntry; typedef struct RvDirEntries RvDirEntries; typedef struct RvFileError RvFileError; typedef struct RvFileAnswer RvFileAnswer; typedef struct RvPluginInfo RvPluginInfo; typedef struct RvPackInfo RvPackInfo; typedef struct RvToolInfo RvToolInfo; typedef struct RvToolResult RvToolResult; typedef struct RvHost RvHost; typedef struct RvLoadArgs RvLoadArgs; typedef struct RvPackNewArgs RvPackNewArgs; typedef struct RvToolCallArgs RvToolCallArgs; typedef struct RvCall RvCall; /** * The contract's major version, which `RvHost` reports. */ #define RV_API_MAJOR 0 /** * The contract's minor version, which `RvHost` reports. */ #define RV_API_MINOR 5 /** * The most bytes in a name segment, a version, or a wire name. */ #define RV_MAX_NAME 64 /** * The most bytes in a refusal reason or a Pack's description. */ #define RV_MAX_LINE 1024 /** * The most bytes in a path a file function takes. */ #define RV_MAX_PATH 4096 /** * The most bytes in a tool's description, and in its parameters. */ #define RV_MAX_TOOL_TEXT 65536 /** * The most bytes in the text of a tool call's result. */ #define RV_MAX_RESULT 16777216 /** * The most bytes `file_write` or `file_append` takes in one request. */ #define RV_MAX_WRITE 16777216 /** * What every function in the contract returns, and the `status` of an * `RvFileAnswer`: zero for success. */ typedef uint32_t RvStatus; /** * The operation an `RvCall` asks for. A fixed-width integer, not a C * enum, so its size never depends on the compiler. */ typedef uint32_t RvVerb; /** * How a tool call ended, in an `RvToolResult`. A fixed-width integer, * as `RvVerb` is. */ typedef uint32_t RvResultKind; /** * What a path names, in an `RvStat`. A fixed-width integer, as * `RvVerb` is. */ typedef uint32_t RvFileType; /** * Why a file operation failed, in an `RvFileError`. A fixed-width * integer, as `RvVerb` is. */ typedef uint32_t RvFileErrorKind; /** * What a tool does beyond answering its calls, in the `flags` of an * `RvToolInfo`: one bit for each `RV_TOOL_` constant. A fixed-width * integer, as `RvVerb` is. */ typedef uint32_t RvToolFlags; /** * A UTF-8 string that is not NUL-terminated. */ struct RvStr { /** * The first byte. It may be NULL when `len` is zero. */ const char *ptr; /** * The length in bytes. */ size_t len; }; /** * A run of bytes: what `file_write` and `file_append` take, and what the * answer to `file_read` holds. */ struct RvBytes { /** * The first byte. It may be NULL when `len` is zero. */ const uint8_t *ptr; /** * The length in bytes. */ size_t len; }; /** * What a path names, which the answer to `file_stat` and each * `RvDirEntry` hold. */ struct RvStat { /** * One of the `RV_FILE_TYPE_` constants. */ RvFileType file_type; /** * Zero. */ uint32_t reserved; /** * The length of a file in bytes. For anything but a file the number * means nothing. */ uint64_t len; }; /** * One entry of a directory, in an `RvDirEntries`. */ struct RvDirEntry { /** * The entry's name within its directory. */ struct RvStr name; /** * What the entry is. */ struct RvStat stat; }; /** * The entries of a directory, in no promised order, which the answer to * `file_list` holds. */ struct RvDirEntries { /** * The first entry. It may be NULL when `len` is zero. */ const struct RvDirEntry *ptr; /** * How many entries there are. */ size_t len; }; /** * Why a file operation failed, in an `RvFileAnswer` whose `status` is * `RV_ERR_FILE`. */ struct RvFileError { /** * One of the `RV_FILE_ERROR_` constants. */ RvFileErrorKind kind; /** * Zero. */ uint32_t reserved; /** * What went wrong, in words a model can read. */ struct RvStr text; }; /** * The answer to a file request, which the step after the request * receives through `answer` in its `RvToolCallArgs`. The Host fills * the one field the request's file function names, or `error`, and * leaves every other field zero. */ struct RvFileAnswer { /** * The size of this struct in bytes: `sizeof(RvFileAnswer)`. */ uint32_t size; /** * `RV_OK` when the operation succeeded, or `RV_ERR_FILE` with * `error` filled. */ RvStatus status; /** * What the path names, in the answer to `file_stat`. */ struct RvStat stat; /** * The entries of the directory, in the answer to `file_list`. */ struct RvDirEntries entries; /** * The bytes read, in the answer to `file_read`. */ struct RvBytes bytes; /** * Why the operation failed, when `status` is `RV_ERR_FILE`. */ struct RvFileError error; }; /** * What a Plugin tells `describe_plugin` about itself. */ struct RvPluginInfo { /** * The size of this struct in bytes: `sizeof(RvPluginInfo)`. */ uint32_t size; /** * Zero. */ uint32_t reserved; /** * One name segment, such as `acme-url`: 1 to `RV_MAX_NAME` bytes of * lowercase ASCII letters, digits, `-`, `_`, and `.`. */ struct RvStr name; /** * Non-empty, at most `RV_MAX_NAME` bytes, with no control characters. */ struct RvStr version; }; /** * What a Plugin tells `insert_pack` about one of its Packs. */ struct RvPackInfo { /** * The size of this struct in bytes: `sizeof(RvPackInfo)`. */ uint32_t size; /** * Zero. */ uint32_t reserved; /** * The Pack's name: a vendor and a Pack id joined by `/`, such as * `acme/url`. Each is one name segment, as a Plugin's name is. */ struct RvStr name; /** * One line saying what the Pack offers: at most `RV_MAX_LINE` bytes * with no control characters. It may be empty. */ struct RvStr description; }; /** * What a Pack instance tells `add_tool` about one of its tools. */ struct RvToolInfo { /** * The size of this struct in bytes: `sizeof(RvToolInfo)`. */ uint32_t size; /** * Zero, or `RV_TOOL_CHANGES_FILES`. A set bit that is no `RV_TOOL_` * constant is a misuse. */ RvToolFlags flags; /** * The tool's name within its Pack: one name segment, such as `fetch`. */ struct RvStr name; /** * The name a model calls the tool by: 1 to `RV_MAX_NAME` bytes of * ASCII letters, digits, `_`, and `-`. Empty lets the Host derive it * from the tool's id, as `url_fetch` from `url/fetch`. */ struct RvStr wire_name; /** * What the tool does, for a model to read: non-empty, at most * `RV_MAX_TOOL_TEXT` bytes. */ struct RvStr description; /** * The tool's parameters: the JSON text of a JSON Schema whose value is * an object, at most `RV_MAX_TOOL_TEXT` bytes. */ struct RvStr parameters; }; /** * How a tool call ended, which a step tells `finish`. */ struct RvToolResult { /** * The size of this struct in bytes: `sizeof(RvToolResult)`. */ uint32_t size; /** * Whether the call succeeded, and if so how far its text is trusted, * or else why it failed: one of the `RV_RESULT_` constants. */ RvResultKind kind; /** * The call's output when it succeeded, and otherwise a message a model * can read that says what went wrong: at most `RV_MAX_RESULT` bytes. */ struct RvStr text; }; /** * What the Host reports on every call: the contract version it speaks. * The functions a Plugin may call back sit in each verb's arguments * struct instead. */ struct RvHost { /** * The size of this struct in bytes: `sizeof(RvHost)`. */ uint32_t size; /** * `RV_API_MAJOR`. */ uint32_t api_major; /** * `RV_API_MINOR`. */ uint32_t api_minor; /** * Zero. */ uint32_t reserved; }; /** * The arguments of `RV_PLUGIN_LOAD`: the functions the Plugin may call * while it loads, each taking `ctx` first. */ struct RvLoadArgs { /** * The size of this struct in bytes: `sizeof(RvLoadArgs)`. */ uint32_t size; /** * Zero. */ uint32_t reserved; /** * The Host's context for this load, passed back as the first argument * of each function below. The Plugin never reads through it. */ void *ctx; /** * Declines the load, at most once, with a UTF-8 reason of at most * `RV_MAX_LINE` bytes; returns `RV_ERR_REFUSED`. */ RvStatus (*refuse)(void *ctx, struct RvStr reason); /** * Names the Plugin, exactly once. */ RvStatus (*describe_plugin)(void *ctx, const struct RvPluginInfo *info); /** * Inserts one Pack, once for each Pack the Plugin offers. No two * Packs of one Plugin share a name. */ RvStatus (*insert_pack)(void *ctx, const struct RvPackInfo *info); }; /** * The arguments of `RV_PACK_NEW`: the Pack to make an instance of, and * the functions the Plugin may call while it makes one, each taking `ctx` * first. */ struct RvPackNewArgs { /** * The size of this struct in bytes: `sizeof(RvPackNewArgs)`. */ uint32_t size; /** * Zero. */ uint32_t reserved; /** * The Host's context for this call, passed back as the first argument * of each function below. The Plugin never reads through it. */ void *ctx; /** * The name of the Pack, as the Plugin gave it to `insert_pack`. */ struct RvStr pack; /** * Declines to make the instance, at most once, with a UTF-8 reason of * at most `RV_MAX_LINE` bytes that a model can read; returns * `RV_ERR_REFUSED`. The run then goes without the Pack. */ RvStatus (*refuse)(void *ctx, struct RvStr reason); /** * Adds one tool to the instance, once for each tool it offers. No two * tools of one instance share a name. */ RvStatus (*add_tool)(void *ctx, const struct RvToolInfo *info); }; /** * The arguments of `RV_TOOL_CALL`: the tool, its arguments, the * function that ends the call, the file functions, and the answer to the * file request of the call's last step. Every step of one call gets the * same `tool` and `arguments`. */ struct RvToolCallArgs { /** * The size of this struct in bytes: `sizeof(RvToolCallArgs)`. */ uint32_t size; /** * Zero. */ uint32_t reserved; /** * The Host's context for this step, passed back as the first argument * of each function below. The Plugin never reads through it. */ void *ctx; /** * The tool's name, as the instance gave it to `add_tool`. */ struct RvStr tool; /** * The call's arguments: the JSON text of the value the caller passed. */ struct RvStr arguments; /** * Ends the call with its result, exactly once, in the step that then * returns `RV_OK`. */ RvStatus (*finish)(void *ctx, const struct RvToolResult *result); /** * Asks what `path` names. The answer holds `stat`. A path longer * than `RV_MAX_PATH` bytes is a misuse, here and in every file * function below. */ RvStatus (*file_stat)(void *ctx, struct RvStr path); /** * Asks for the entries of the directory at `path`. The answer holds * `entries`. */ RvStatus (*file_list)(void *ctx, struct RvStr path); /** * Asks for up to `len` bytes of the file at `path`, starting at the * byte `offset`. The answer holds `bytes`, with fewer than `len` * bytes when the file ends first, and none when `offset` is at or * past its end. */ RvStatus (*file_read)(void *ctx, struct RvStr path, uint64_t offset, uint64_t len); /** * The answer to the file request the call's last step made, or NULL * when that step made none. */ const struct RvFileAnswer *answer; /** * Asks to write `bytes` as the whole contents of the file at `path`. * The file is made when it is absent, and its contents give way to * `bytes` when it is there. More than `RV_MAX_WRITE` bytes are a * misuse, here and in `file_append`. */ RvStatus (*file_write)(void *ctx, struct RvStr path, struct RvBytes bytes); /** * Asks to add `bytes` to the end of the file at `path`. The file is * made when it is absent. */ RvStatus (*file_append)(void *ctx, struct RvStr path, struct RvBytes bytes); /** * Asks to make a directory at `path`. With `recursive` 0 every * directory on the way to `path` must be there, and with `recursive` * 1 each one that is absent is made. Any other `recursive` is a * misuse, here and in `file_remove`. Something already at `path` * fails the operation as `RV_FILE_ERROR_ALREADY_EXISTS`. */ RvStatus (*file_mkdir)(void *ctx, struct RvStr path, uint32_t recursive); /** * Asks to remove the file or the directory at `path`. With * `recursive` 0 a directory that has entries fails the operation as * `RV_FILE_ERROR_NOT_EMPTY`, and with `recursive` 1 it goes with * everything in it. Nothing at `path` fails the operation as * `RV_FILE_ERROR_NOT_FOUND`. */ RvStatus (*file_remove)(void *ctx, struct RvStr path, uint32_t recursive); /** * Asks to move the file or the directory at `from` to `to`. A * directory moves with everything in it. */ RvStatus (*file_rename)(void *ctx, struct RvStr from, struct RvStr to); /** * Asks to copy the file at `from` to `to`. The file at `to` is made * when it is absent, and its contents give way to the copy when it * is there. */ RvStatus (*file_copy)(void *ctx, struct RvStr from, struct RvStr to); }; /** * One call into a Plugin's entry point. */ struct RvCall { /** * The size of this struct in bytes: `sizeof(RvCall)`. */ uint32_t size; /** * The operation. */ RvVerb verb; /** * What the Host reports on every call. */ const struct RvHost *host; /** * The Plugin instance: NULL going into `RV_PLUGIN_LOAD`, which sets * it, and that pointer on every later call. */ void *plugin; /** * One run's instance of a Pack: NULL going into `RV_PACK_NEW`, * which sets it, that pointer on `RV_PACK_DELETE`, * `RV_TOOL_CALL`, and `RV_TOOL_CANCEL`, and NULL otherwise. */ void *pack_run; /** * The verb's own arguments: an `RvLoadArgs` for `RV_PLUGIN_LOAD`, * an `RvPackNewArgs` for `RV_PACK_NEW`, an `RvToolCallArgs` for * `RV_TOOL_CALL`, and NULL for every other verb. */ const void *args; /** * The state of one tool call: NULL going into the call's first * `RV_TOOL_CALL`, what the last step left on each later step and on * `RV_TOOL_CANCEL`, and NULL otherwise. */ void *tool_call; }; /** * Success. */ #define RV_OK 0 /** * The caller broke the contract. */ #define RV_ERR_MISUSE 4 /** * The Plugin declined to load or to make a Pack instance; `refuse` * returns it. */ #define RV_ERR_REFUSED 5 /** * The Plugin cannot answer the call: it does not know the verb, it was * not built for the Host's version, or a struct is shorter than it * expects. */ #define RV_ERR_UNSUPPORTED 6 /** * The tool call needs another step; only `RV_TOOL_CALL` returns it. */ #define RV_PENDING 7 /** * A file operation failed. No function returns it: it is the `status` of * an `RvFileAnswer`, whose `error` says what went wrong. */ #define RV_ERR_FILE 8 /** * Make the Plugin instance, name the Plugin, and insert its Packs. */ #define RV_PLUGIN_LOAD 1 /** * Free the Plugin instance. */ #define RV_PLUGIN_UNLOAD 2 /** * Make one run's instance of a Pack and list its tools. */ #define RV_PACK_NEW 3 /** * Free one run's instance of a Pack. */ #define RV_PACK_DELETE 4 /** * Run one step of a tool call. */ #define RV_TOOL_CALL 5 /** * Free the state of a tool call the Host has abandoned. */ #define RV_TOOL_CANCEL 6 /** * The call succeeded, and its text may hold data an attacker can * influence, such as the contents of a file or a web page. The Host marks * such text before a model reads it. Zero, so a result that names no kind * is treated with care. */ #define RV_RESULT_UNTRUSTED 0 /** * The call succeeded, and the Plugin vouches for every byte of its text. */ #define RV_RESULT_TRUSTED 1 /** * The call failed: its arguments do not match the tool's parameters. */ #define RV_RESULT_INVALID_ARGUMENTS 2 /** * The call failed: what the tool reaches refused or failed the request. */ #define RV_RESULT_BACKEND 3 /** * The call failed: the request never got through. */ #define RV_RESULT_TRANSPORT 4 /** * The call failed for any other reason. */ #define RV_RESULT_OTHER 5 /** * Something that is none of the kinds below, such as a pipe, a socket, or * a device. */ #define RV_FILE_TYPE_OTHER 0 /** * A regular file. */ #define RV_FILE_TYPE_FILE 1 /** * A directory. */ #define RV_FILE_TYPE_DIRECTORY 2 /** * A symbolic link. */ #define RV_FILE_TYPE_SYMLINK 3 /** * A reason the kinds below do not name. */ #define RV_FILE_ERROR_OTHER 0 /** * Nothing is at the path. */ #define RV_FILE_ERROR_NOT_FOUND 1 /** * The path names something that is not a directory, where the operation * needs one. */ #define RV_FILE_ERROR_NOT_A_DIRECTORY 2 /** * The path names a directory, where the operation needs a file. */ #define RV_FILE_ERROR_IS_A_DIRECTORY 3 /** * The run's policy does not allow the operation. The error's text is the * policy's own reason. */ #define RV_FILE_ERROR_DENIED 4 /** * Another tool call of the run changed the path, or is changing it, at * the same time. The same operation can succeed in a later call. */ #define RV_FILE_ERROR_CONFLICT 5 /** * The operating system failed the operation. */ #define RV_FILE_ERROR_IO 6 /** * Something is at the path already, where the operation needs nothing * there. */ #define RV_FILE_ERROR_ALREADY_EXISTS 7 /** * The path names a directory that has entries, where the operation * needs an empty one. */ #define RV_FILE_ERROR_NOT_EMPTY 8 /** * A call of the tool changes files of its run. Bit 0. */ #define RV_TOOL_CHANGES_FILES 1 #ifdef __cplusplus extern "C" { #endif /** * The one symbol a library Plugin exports. A linked Plugin has the same * shape under a name of its own crate's choosing. It must not unwind. */ RvStatus runvil_plugin(RvCall *call); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* RUNVIL_PLUGIN_H */