CLI command
jeden rpc
Serve Jeden's newline-delimited JSON RPC interface on standard input and output.
Exact invocation#
jeden rpcInputs and options#
- No command-specific positional input or option is required.
- Clients send one JSON request per line with an
id,method, and optionalparamsobject. session/opentakes{session,options?}and reopens the existing ledger in place. Its returnedsessionPathremains the source path; retained request identities and revisions are preserved. A session that is not there isjeden.session.find.session-not-found; a directory withoutstate.jsonissession-state-absent(tests/sessions/listing/records.mjs), rather than creating another conversation.session/completion/gettakes{sessionId};session/completion/controltakes{sessionId,taskId,action,reason,revision}, with action pause, resume, cancel, defect or answer. For answer,reasoncarries the operator's answer to the register ask the task waits on, and it reaches every task waiting on that ask, asjeden todo answerdoes; a task that asked nothing refuses it. Both return{sessionId,completion}, whose tasks carryoperatorRequest {askedAt,ask,answer?}when a review asked the operator for something and whose status readswaiting_for_operatorwhile an ask is unanswered. Task IDs may also name an original request.asks/listtakes{}and returns{register,revision,asks}, each ask{id,ask,status,askedAt,timesAsked,workspace,sessions,follows,answer}asjeden asks list --jsonprints it;asks/gettakes{askId}and addsoccurrences, each{askedAt,source,sessionPath,taskId?,wording,answeredFromRegister?,taskStatus?,waiting?,taskState?};asks/answertakes{askId,text}and returns{ask,deliveries}, each delivery{sessionPath,taskId,outcome,detail}with outcome delivered, not_waiting or failed. A missing askId or text is invalid_params; every refusal ofjeden asksis ask_error with its sentence.session/completion/continuetakes{sessionId,requestId}and uses the ordinary prompt response and event stream without capturing a new user request. Eventscompletion {state}andassistantMessage {text}are nonterminal;resultincludes text and the completion snapshot.session/completion/addtakes{sessionId,prompt}and returns{sessionId,completion}without running a model. Native/todocommands sent through session/prompt also operate on that selected session rather than becoming model instructions, and so do/compact,/handoff,/move,/checkpoint(and/checkpoint list),/rewind <id>,/new,/forkand/branch: the prompt's answer is the command's own text (for exampleCheckpoint <id> created,Rewound to checkpoint <id>; new active leaf is <leaf>.), and a rewind marks what it took back in the session's chat memory, asjeden chat-memorydescribes. A session created with model-only options sends every prompt, these included, to the model instead.- session/import takes {paths,refresh?} — the same paths the CLI takes, as an array of strings — and returns the same report as
jeden importwithout invoking a model or terminating a source process. A missing or empty paths array is refused as invalid_params, and so are an entry that is not a string (paths[<n>] is <value>, not a path string) and a refresh that is not true or false (refresh must be true or false, not <value>); nothing is imported then. hillclimb/statustakes{cwd,ledger?,last?,ending?,round?,repository?,withoutRepository?}and returns{ledger,rounds,accepted,total,ending,round,repository,withoutRepository}. Ending is accepted or failed; round is an unsigned u64 JSON integer matching recorded identity, not physical position or execution limit. Repository is any exact recorded string, including empty, whitespace, path-like or option-like text; null/omitted leaves names unrestricted. WithoutRepository is a boolean, omitted false; true selects omitted/null record identities only, distinct from an empty string. True together with a non-null repository is invalid_params. No name is trimmed, resolved, canonicalized, case-folded or used as an execution target. Wrong field types, non-u64 rounds and unknown fields refuse with the field and actual decoding/selection cause. Omitted/null round or ending is unrestricted; every response echoes actual selections. Intersect repository/absence, round and ending before retaining a positive last suffix; missing/null last retains every match. Total/accepted cover the complete ledger even with no matches. Paths and repository input are borrowed through response encoding rather than copied per record. Relative ledger paths belong to canonical cwd. Invalid/missing/non-string/blank cwd or ledger types are invalid_params; supplied ledger must be a nonblank string or null. Every physical record is decoded and validated before/after and outside the filters/suffix; malformed/unreadable history is hillclimb_unreadable with actual physical line/path/cause, including earlier blanks. No successful prefix is returned and bytes stay unchanged. Retention bounds decoded-history memory, not scan time. Reads create no missing ledger and start no model or writer.hillclimb/runtakes{cwd,scope?,focus?,only?,rounds?,ledger?,deliver?,model?,maxSteps?,maxTokens?,allowWrite,allowCommand}. Scope is repository by default or organization; only is an array of immediate repository names admitted for organization scope. Round count and supplied execution limits are positive integers. Missing model and limits use the selected workspace's ordinary configuration. Both grants must be true or the request ispermission_deniedbefore registration or execution. Unknown fields and malformed values areinvalid_params. Focus is typed data, including text beginning with option-like words; it is not converted into shell or CLI arguments. Deliver is what a round does with its change before it is finished, as--delivertakes it; a blank one isinvalid_params.- Run remains pending through the native chooser and Pursuit loop, returning
{scope,ledger,rounds,accepted,total,ending,round,repository,withoutRepository}for this invocation, orhillclimb_failedwith its observed cause. Run results are unfiltered: ending, round and repository are null and withoutRepository is false; total counts this invocation's rounds, not earlier history. Inspect each round's ending and receipt: a successful RPC response alone does not establish independent acceptance. Nonterminal{type:hillclimbProgress,requestId,message}frames identify the owning request. hillclimb/activetakes{}and returns{requests:[{requestId,cwd,scope,cancellationRequested}]}for this connection only, not all hosts or ledger owners.hillclimb/canceltakes{requestId}; an owned request returns{requestId,cancellationRequested:true}, while an unknown or ended request isrequest_not_running. This is cooperative cancellation, not a finished-work receipt. Await the original run result and read current history; completed rounds remain recorded. Failed run responses, including a worker that could not be created, includeerror.data.cancellationRequested, the actual observed flag, not an inference that cancellation caused another error. Request ownership is released before a final response is published. If writing a startup refusal also fails, the native error retains both the worker-creation cause and the response-write cause.- Input EOF, shutdown and dispatch failure request cancellation of owned climbs/context work, then drain workers and dispose sessions. One cleanup failure does not skip others; failed operations/causes remain. Ready advertises
hillclimb:{run:true,cancel:true,active:true,ledgerOverride:true,historyLimit:true,historyEnding:true,historyRound:true,historyRepository:true,delivery:true}; this is negotiation, not consumer proof. Desktop checks every required capability, including combined ledger, count, ending, round and repository/absence selection. It refuses unsupported controls rather than dropping a selector. An older unfiltered response without repository metadata remains explicitly not reported. - The no-model journey
JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/hillclimb/status.mjsdrives actual RPC/CLI processes in isolated workspaces/homes: workspace/ledger refusals, pre-model run failure, cancellation metadata and cleanup, relative paths, whole-ledger totals, intersected repository/absence/round/ending-before-suffix selection, no matches and cleared selectors. It distinguishes literal all/empty/whitespace/Unicode/quote/backslash/path-like/option-like names from omitted/null identities without resolving paths, and refuses malformed/conflicting repository parameters. It also covers invalid/unknown/object-shaped ending fields, invalid round/counts, wide unsigned identifiers, malformed JSON before/after selected rows, malformed repository metadata outside retained matches, invalid UTF-8 after blanks, no partial success and unchanged bytes. Native /hillclimb runs through real CLI run with quoted paths/names and inline empty selectors. Persisted fixtures test the reader, not model acceptance. Model-backed tests/hillclimb/control.mjs needs JEDEN_TEST_MODEL and covers acceptance, cancellation, EOF and ledger reuse. Reports/raw frames and source/binary identity remain under .build. Unexecuted sources/capability advertisements qualify neither runtime nor rendered Desktop/TUI; these journeys do not force kernel worker exhaustion. - Model-backed hillclimb journeys require an exclusively reserved canonical
JEDEN_TEST_REPOSITORY, its matchingJEDEN_TEST_REPOSITORY_ORIGIN, and a dedicated preparedJEDEN_TEST_HOMEinside the product checkout's ignored.build. The target's clean main baseline tracks exactly the shared fixture README and greeter templates. No nested checkout, clone, operator home or automatic commit rewind is used; generated fixture changes are retained and restored before a subsequent serial journey. Missing prerequisites or failed restoration remain failures, not passing qualification.
Output and state effect#
Keeps an in-process session map, emits one-line JSON responses and interaction events, and creates normal Jeden session state for requests that start or resume work. User-facing session prompts use the same structured task-report contract as CLI/TUI, headless, and the SDKs; accepted task_report events carry version, complete-or-blocked status, the seven-area report, and its rendered human text. The config/contracts/get and config/contracts/set results include the two editable user contract settings plus a localized, versioned, built-in read-only taskContract with instructions and requirement descriptors. config/communication/get and config/communication/set return the resolved effective communication policy. Session events include toolCall, toolResult, and reasoningDelta only when that policy shows them. RPC opens no listener.
Refusals and boundaries#
- Frames larger than 1 MiB are refused.
- Malformed JSON, missing methods, unknown methods, invalid parameters, and writes to a closed output stream are returned as RPC errors rather than guessed.
- A declared refusal's error frame carries
databesidecodeandmessage:{functionality, cause, remedy, retryable}, read by field rather than out of the message.jeden errors show jeden.rpc.dispatchlists the refusals of answering a request around its method: a method Jeden does not serve (method-unknown, codemethod_not_found;lease/list,lease/releaseandlease/endwent with Jeden's leases and are answered so),config/task-limits/setwithoutlimits(limits-missing,invalid_params; a declaration the limits refuse keeps its own cause with acontext:line),star/*with parameters (star-parameters) or of another verb (star-method-unknown),initializein a working directory that is gone (directory-unreadable, naming the system's words) and an answer that cannot be written as JSON (answer-unserialized). The real journey isJEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/dispatch.mjs. jeden errors show jeden.rpc.dispatchalso lists the stream's refusals: a frame that is not JSON (frame-not-json, naming its size) or not a request (frame-shapeless), both answeredmalformed_jsonwith a null id; standard output the client closed (output-unwritable), which ends the server with that refusal; and steps of ending the server that failed (shutdown-incomplete, each step named).jeden errors show jeden.rpc.sessionslists the session methods' own: a parameter a method needs as a non-empty string (parameter-missing, naming the method, the parameter and what came instead),revisionofsession/completion/control, session options of another shape, a session id this connection does not hold (session-unknown, naming the ones it holds), andworkspace/discover'spathandsession/import'spathsandrefresh.jeden errors show jeden.rpc.interactionlists the answers tosession/request_inputandsession/request_permission: a token no interaction waits on (token-unknown, saying how many wait), one answered by the other method, an answer without its value, which the turn that asked is told, and a server that ends while one waits (server-ending). The real journey isJEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/sessions.mjs.- A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits
2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.