Jeden/Docs

CLI command

jeden rpc

Serve Jeden's newline-delimited JSON RPC interface on standard input and output.

Exact invocation#

Shell
jeden rpc

Inputs and options#

  • No command-specific positional input or option is required.
  • Clients send one JSON request per line with an id, method, and optional params object.
  • session/open takes {session,options?} and reopens the existing ledger in place. Its returned sessionPath remains the source path; retained request identities and revisions are preserved. A session that is not there is jeden.session.find.session-not-found; a directory without state.json is session-state-absent (tests/sessions/listing/records.mjs), rather than creating another conversation.
  • session/completion/get takes {sessionId}; session/completion/control takes {sessionId,taskId,action,reason,revision}, with action pause, resume, cancel, defect or answer. For answer, reason carries the operator's answer to the register ask the task waits on, and it reaches every task waiting on that ask, as jeden todo answer does; a task that asked nothing refuses it. Both return {sessionId,completion}, whose tasks carry operatorRequest {askedAt,ask,answer?} when a review asked the operator for something and whose status reads waiting_for_operator while an ask is unanswered. Task IDs may also name an original request.
  • asks/list takes {} and returns {register,revision,asks}, each ask {id,ask,status,askedAt,timesAsked,workspace,sessions,follows,answer} as jeden asks list --json prints it; asks/get takes {askId} and adds occurrences, each {askedAt,source,sessionPath,taskId?,wording,answeredFromRegister?,taskStatus?,waiting?,taskState?}; asks/answer takes {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 of jeden asks is ask_error with its sentence.
  • session/completion/continue takes {sessionId,requestId} and uses the ordinary prompt response and event stream without capturing a new user request. Events completion {state} and assistantMessage {text} are nonterminal; result includes text and the completion snapshot.
  • session/completion/add takes {sessionId,prompt} and returns {sessionId,completion} without running a model. Native /todo commands 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, /fork and /branch: the prompt's answer is the command's own text (for example Checkpoint <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, as jeden chat-memory describes. 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 import without 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/status takes {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/run takes {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 is permission_denied before registration or execution. Unknown fields and malformed values are invalid_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 --deliver takes it; a blank one is invalid_params.
  • Run remains pending through the native chooser and Pursuit loop, returning {scope,ledger,rounds,accepted,total,ending,round,repository,withoutRepository} for this invocation, or hillclimb_failed with 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/active takes {} and returns {requests:[{requestId,cwd,scope,cancellationRequested}]} for this connection only, not all hosts or ledger owners. hillclimb/cancel takes {requestId}; an owned request returns {requestId,cancellationRequested:true}, while an unknown or ended request is request_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, include error.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.mjs drives 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 matching JEDEN_TEST_REPOSITORY_ORIGIN, and a dedicated prepared JEDEN_TEST_HOME inside 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 data beside code and message: {functionality, cause, remedy, retryable}, read by field rather than out of the message. jeden errors show jeden.rpc.dispatch lists the refusals of answering a request around its method: a method Jeden does not serve (method-unknown, code method_not_found; lease/list, lease/release and lease/end went with Jeden's leases and are answered so), config/task-limits/set without limits (limits-missing, invalid_params; a declaration the limits refuse keeps its own cause with a context: line), star/* with parameters (star-parameters) or of another verb (star-method-unknown), initialize in 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 is JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/rpc/dispatch.mjs.
  • jeden errors show jeden.rpc.dispatch also lists the stream's refusals: a frame that is not JSON (frame-not-json, naming its size) or not a request (frame-shapeless), both answered malformed_json with 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.sessions lists 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), revision of session/completion/control, session options of another shape, a session id this connection does not hold (session-unknown, naming the ones it holds), and workspace/discover's path and session/import's paths and refresh. jeden errors show jeden.rpc.interaction lists the answers to session/request_input and session/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 is JEDEN_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) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: <operation>.<cause>, and jeden errors show <operation> lists every cause of that functionality.