Jeden/Docs

Jeden Desktop

The same sessions, in a window.

Jeden Desktop is the macOS app over Jeden's durable sessions. It reads the files and RPC answers listed here, continues work on the host Stado selects, and names every source that could not answer instead of showing an empty list.

What it reads#

  • Session index — $JEDEN_SESSION_ROOT or ~/.jeden/sessions/*/state.json; resolution mirrors session_root() in the harness, and sessions are global, not per checkout.
  • Transcript — <session>/transcript.jsonl; ledger v2 (payload.type / payload.data) and the pre-v2 flat entry are both parsed.
  • Lake session projection — $LAKE_DATA or ~/.transcript-lake, under exports/oko/runtime=<runtime>/<session>.jsonl: Transcript Lake's canonical per-session projection (schema oko-import-v1), one file per conversation grouped by runtime. The continuous Lake service creates and advances it; without it the app shows harness sessions only.
  • Lake goal labels — $LAKE_DATA/labels/labels.ndjson or ~/.transcript-lake/labels/labels.ndjson: the latest canonical goal assignment per runtime and session; labels take precedence over raw opening prompts.
  • Oko goal lifecycle — ~/Library/Caches/ai.wisent.jeden.desktop/oko/auto-goals.json, a read-only snapshot refreshed through oko-cli auto-goals snapshot. Resolution prefers Stado's managed ~/.stado/bin/oko-cli, then PATH, and uses the legacy ~/.oko/bin/oko-cli only when neither current installation exists; prompt mappings place goal starts, continuations and completions on the matching conversation turns.
  • Live session stream — $LAKE_DATA/live.sock or ~/.transcript-lake/live.sock, a process-local Unix socket: one snapshot followed by revisioned deltas carrying active source identities and masked oko-import-v1 events.
  • Artifacts — <session>/artifacts/, presence only; the app reveals the directory in Finder.
  • Usage — <cwd>/.jeden/usage.json and ~/.jeden/usage.json, side by side, the way jeden stats reports them.
  • Mode state — <cwd>/.jeden/mode-state.json and ~/.jeden/mode-state.json: armed modes, last task and active roadmap item; task acceptance lives in the session completion store.
  • Offline goal model source — STADO_API_URL, or api.url in the selected Stado profile. STADO_CONFIG selects an explicit profile; otherwise lookup tries ./stado.config.json, ~/.config/stado/config.json, then ~/.stado/config.json. An origin with no path uses /api/release/object; downloads require HTTPS except on a loopback IP address.
  • Model credentials — Jeden's token/status RPC on the selected Stado host: the direct provider, or the route Stado's inference alternatives give (alternatives in Stado's order, or Stado's declared routeRefusal), key source, redacted local token rows, last selected ID and the actual recorded refusals; secrets are only sent by token/add and never returned.
  • Hillclimb — Jeden's hillclimb/status and hillclimb/active RPCs on a Stado attachment placed for the selected workspace: the selected default or custom ledger, recorded rounds and receipts, and this connection's owned requests at the last read.

Every read ends in data or a named failure#

Each reader returns its failures beside the rows that survived (Sources/Jeden/Store/Availability.swift). A failure carries the system's own sentence, the file it was reading, and the jeden command that reproduces it — jeden sessions, jeden show <id>, jeden stats --cwd <project>, jeden config --cwd <project>. It is rendered full width with a severity edge, never as a modal that closes unread. Readers keep the last good display when a refresh fails: the banner explains why the data stopped advancing, and the data stays.

Absence is separated from failure and never coloured red. A session root that does not exist yet, a project that has spent no tokens, a lake the continuous service has not materialised — all Not configured, in .neutral. Red is kept for a source that was asked and could not answer. One unreadable session directory costs that row, not the index: the other rows still render, with one counted failure above them.

A transcript's torn final line is silent, because an append-only ledger being written to right now legitimately ends mid-line; a line that does not decode anywhere before the end is damage and is counted and reported. The live socket reports three outcomes: absent (Not configured), refused (Connection refused, from strerror), and a stream the service closed. The queue on Posture says "the live stream is unavailable, so this queue cannot be trusted", because a queue of zero means nothing when nothing is watching.

The live Tasks panel obtains completion.json state through session/completion/get and completion events, never from an agent-authored todo flag. Offline goal-model failures enter the same Posture read-failure list as Session goal classification: a profile error names the failed configuration read, a download error the object URL and transport error or HTTP status, and a size or digest failure is reported separately. No partial model is accepted as a successful download.

The session workspace#

Jeden Desktop uses a two-column workspace. The durable session index stays on the left and the selected session on the right; selecting another row changes the detail without replacing the index. The left column starts with Waiting for you and Working, then places idle history under Today, Yesterday, Earlier this week, Earlier this month and Earlier. Project scope, search, activity, recency, runtime and the automation switch stay directly above the rows they narrow.

The right column switches between Conversation, Transcript, Usage and Harness state for the selected session. Jeden takes no lease of a Brama account, so there is no Brama account view and no lease/* RPC: a client that still calls lease/list, lease/release or lease/end is answered JSON-RPC's method-not-found, as for any unknown method. Posture reports every failed read, the source signals and the live queue; Context asks Jeden's context advisor what to read for a task and shows the state of every source it consulted; Settings names every source path and its environment override. These views do not take the session index off screen.

Scope is not a destination. Sessions live in one shared root, so the only scope the harness records is the project each run named as its cwd; it is a selector above the session list that every screen reads and reports in its context bar. There is deliberately no grouping by repository: a session can work across several checkouts, but neither reader records that set. The lake stores one project per conversation and masks tool arguments at ingest; the harness stores one cwd, and its tool paths are relative to it. The recorded directory is still read: it names the scope chip on Usage and Harness state, backs Reveal in Finder, gives Stado the repository name for placement, and is matched by the search box.

The idle bands are the calendar's own days, weeks and months, not elapsed hours: a run that finished at 23:50 last night is under Yesterday at 00:10, and the week starts on the day the Mac's locale starts it. Each idle session lands in exactly one collapsible band. Live work is not buried in them: Waiting for you and Working are separate sections before history, with an activity mark on every live row. Activity, recency and runtime menus narrow independently, and their counts are taken from the project scope, search and automation filter only.

Gates, classifiers and fixers are agents talking to agents, so the automation filter keeps those sessions out of the default list without removing them. The rule is Oko's, ported so the two apps agree about what noise is: a session is classified by the opening words of its first human prompt (Sources/Jeden/Model/Session/SessionClassification.swift, mirroring Oko's TranscriptAutomationKind). Prefix, not search — a person quoting a gate's preamble is writing about it and stays visible. The app also recognises authorizationGate and emptyRun: the harness creates a session directory before a run produces anything, so a run that recorded nothing can still leave a state.json and an empty ledger. Nothing is deleted: the automation switch and its hidden count sit with the session list, and queuedUnknown is deliberately not hidden, so an automation nobody has named yet stays visible.

Model credentials#

Settings → Model credentials is the graphical half of jeden token. It reads the selected host's active route and redacted token list through Jeden's token/status RPC; Stado carries the connection to the selected host, and the app never reads a local credential file or persists the provider secret. An explicit JEDEN_MODEL_ENDPOINT selects an OpenAI-compatible provider, and JEDEN_MODEL_KEY from the Jeden process environment takes precedence; without it Jeden may use its own keys stored for that endpoint. The screen shows the route, key source, last selected row and the actual failed operation and HTTP refusal recorded for each row. The secret is never returned or rendered after storage.

Enter a label, the same provider base URL and its token to call token/add; Remove calls token/remove with the row's ID. An invalid URL, duplicate label, unknown ID or unreadable private store is shown as Jeden's refusal with its code and sentence, not as a successful save. An invalid or non-Unicode direct endpoint or key is shown as a direct-route refusal without echoing credential bytes. Without a direct provider the route shown is Stado's inference alternatives in Stado's order, or Stado's declared refusal; no Brama signing secret or bearer is read or shown. A direct request rotates to another untried key for that endpoint after an HTTP authentication, payment or rate-limit refusal before any model output is visible; budget pricing reads the catalog through the same rotation, and an unpriced model is refused rather than assigned an invented cost. Jeden never fetches provider or gateway secrets from Skarbiec.

Leaving Settings closes its connection. A token operation that had not answered is reported as having an unknown outcome; reopening Settings reads the persisted list. A reload discards the previous snapshot before requesting token/status: if the read fails, the stale rows and route stay hidden and edits stay disabled, and the refusal names the failed read. When an add or removal was acknowledged but the following read fails, the message separates the successful change from the failed verification. Replies from a closed connection cannot replace the state loaded after reopening Settings.

Context#

Context is the graphical half of jeden context. It asks context/recommend and context/sources over the same Jeden RPC the settings screens use and shows each recommendation with its source, exact locator, heading, score and snippet; a source that answered nothing is listed as unavailable with the reason Jeden observed. Every request carries the project chosen in the scope picker as its cwd; with All projects selected the screen sends nothing and says no_workspace. While a request runs, Live source diagnostics keeps the actual Stado and Jeden wait and error lines. Cancel sends context/cancel with that request's id; its acknowledgement means cancellation was requested, so the screen stays busy until the original response or a connection failure arrives, and a late acknowledgement cannot replace a newer request's state. The response must include unanswered diagnostics consistent with its source states, a failed Stado launch completes pending requests with the launch error, and a memory refusal (JEDEN_DATABASE_URL absent, or a database that cannot connect, migrate or answer) is shown beside the file recommendations that did complete.

Continuing work#

Continue this session keeps the session inside the app. The app launches stado host jeden-connect <workspace> and speaks Jeden's newline-delimited RPC over that attached stream. Stado ranks live local-fleet capacity, verifies that the selected host owns the checkout and the Jeden binary, and requires the existing ~/.jeden/sessions/<id> ledger when a native Jeden session is resumed. Sessions imported from Transcript Lake start a new Jeden ledger on the selected host and carry the visible prior conversation into the first request as bounded context. The app persists only {workspace, target, sessionPath}; after an app or transport restart it reconnects to that same host, reopens the durable session and opens on Conversation. Model access goes through Brama as it does in the terminal.

The conversation joins Oko's canonical prompt mappings to user turns and keeps a goal picker above the transcript; its previous and next controls scroll to the first turn for that goal, and completed goals stay marked. The composer always shows four common quick replies, and Jeden's RPC ready frame adds the file-based slash commands discovered for the selected workspace (quickReplies).

A tool approval is the one irreversible decision this window can take. It is a decision dialog quoting the protocol's own session/request_permission reason and listing the backend's detail block verbatim, with Deny — the verb that leaves the checkout untouched — as the primary button and Allow <tool> as a separate destructive one. A requested-input frame uses the same dialog without a red verb. A connection that fails is a full-width alert carrying Stado's or Jeden's own sentence and jeden doctor --cwd .. A failure after the session opens appears as a failure entry in Conversation with the original Jeden error; when a Stop hook refuses an answer and recording that refusal also fails, the message keeps the hook's reason, the failed persistence operation, the path and the filesystem error. Reconnecting is not evidence that the failed operation succeeded; inspect the retained Tasks state before continuing.

Coming back after a crash#

Every conversation the app carries has a recovery record in ~/Library/Application Support/Jeden/recovery.json. At launch a record marked interrupted — a request was in flight when the app went away — is reconnected and its retained work continued without a click. A record that was waiting for the operator comes back parked instead: the conversation shows Session parked and no Stado attach is started, because an attach holds its allocated host resources for as long as it lives. While the app runs, a connection that opened its session and then ended is reconnected at once. A launch that ended before its session opened is not repeated on a timer: the conversation shows the failure with Stado's sentence and is tried again when the Mac's network path changes, or when you press Reconnect.

A connected conversation is parked by Jeden itself. Stado hands jeden rpc the jeden-session kind's park_after_seconds; when nothing has run for that long — or at once when every open session carries a completion blocker — Jeden sends a parked frame, disposes its sessions to their ledgers and exits 0, and Stado releases the reservation. The conversation then shows Session parked with Jeden's reason, the connection ledger records parked, and nothing is reported as a failure or reconnected on its own. The next message, quick reply or Continue places the session again through Stado, reopens its ledger and then sends exactly that action.

A session another harness lost comes back like an interrupted record. jeden import leaves an import.json receipt beside each imported ledger and marks it interrupted when the source ended on a request nobody answered. At launch the app reads every receipt under the session root, and every interrupted import no run has opened yet (the harness writes an adopted marker on first open) is placed through Stado, opened and continued. The count and each connection's state are on Posture under Reopened after a crash. What the app does with every connection is written to ~/Library/Application Support/Jeden/connections.json: the restore pass and one row per conversation with its origin (selection, recovery, import), host, state and failure sentence. JEDEN_DESKTOP_STATE_DIR moves both files, and Settings names both paths and the override.

The process comes back too. The bundle carries the launch agent ai.wisent.jeden.desktop.relaunch.plist, which the app registers through SMAppService the first time it runs: launchd starts Jeden at login and again after any exit that is not status 0, and Quit leaves it closed. launchd only watches the instance it started, so a Jeden opened by the Finder or by a build while the agent is registered asks launchd for its instance and steps aside before restoring anything. Settings → Coming back after a crash shows the registration as macOS reports it, turns it off and on, and opens Login Items when macOS wants an approval. JEDEN_DESKTOP_RELAUNCH=off keeps a process out of this entirely.

GitHub star request#

Jeden counts every successful agent prompt, whichever surface sent it, and asks once for a GitHub star when the count reaches five (jeden star). When the app's prompt is that fifth one, Jeden's session/prompt answer carries starRequest (text, repository, prompts) and Conversation shows it above the composer. Star on GitHub opens the repository Jeden named; Not now hides it, and it does not return because Jeden already recorded it as shown; Don't ask again sends star/dismiss and closes it once Jeden answers with the dismissed stage. A refused dismissal stays on screen with Jeden's message and code; a starRequest without text, an https repository or a whole prompt count is shown as Star request naming the field. JEDEN_DESKTOP_TEST_STAR_REPORT=<jeden>/.build/star/<run>/report.json swift test --filter JedenStarTests reads the RPC answers a real Jeden star journey recorded.

Retained tasks and asks of you#

The Conversation screen's Tasks panel shows original requests, acceptance criteria, states, exact blocker details and verified session and event references; the full contract is on sessions and task commands. Pause, resume and cancel require an operator reason and the latest state revision. Add without running uses the native /todo add session command; Continue retained work uses session/completion/continue, so it creates no synthetic user request. Under each request the panel prints its time to completion in the words jeden todo list prints, from the snapshot's timing. An interim assistantMessage does not end the turn, and only a native verified completion snapshot marks work complete.

A task that waits on you shows Waiting on you: with the one thing the independent review found only you can supply, a Your answer field and Send answer, which records the answer through session/completion/control with action answer. The answer goes to Jeden's operator ask register, so it also reaches every other task, in any session, that waits on the same ask. The sidebar's Asked of you screen shows that register, newest first, with each ask's status (waiting, unanswered, answered), how often and since when it was asked, its workspace and your answer; choosing an ask reads asks/get and lists every place it was asked.

Hillclimb and chat memory#

The sidebar's Hillclimb screen uses a Stado RPC attachment placed for the selected workspace. Choose repository or organization scope, optional focus and admitted repository names, model, positive round, step and token limits and a ledger path; blank limits keep the workspace's configuration, and relative ledger paths belong to the selected workspace. Delivery is what a round does with its change before it is finished, sent as deliver; blank leaves the change where the round left it, and a backend whose ready frame does not advertise delivery is refused before the run is sent. Read ledger reads hillclimb/active and hillclimb/status separately; empty history is not a failed request and creates no ledger, and recorded rounds or a lock sidecar are not proof that a worker runs. Start hillclimb needs a successful scope read and explicit write and command grants; a different workspace clears them. Request stop sends hillclimb/cancel; its acknowledgement means cancellation was requested, and the screen waits for the original run result before rereading the ledger. The ready frame's hillclimb capabilities are checked before the controls are used, so an older backend is refused rather than ignoring an override. The native journeys are Jeden's tests/hillclimb/status.mjs and tests/hillclimb/control.mjs; they do not qualify the rendered Desktop screen.

Chat memory shows the agents' never-ending chats through Jeden's RPC on the host Stado selected, the same documents jeden chat-memory prints. Chats lists every chat (chat-memory/list); the screen opens on the chat the selected session wrote to (chat-memory/show), and choosing a line zooms into it (chat-memory/zoom) down to a message word for word. When was it said asks chat-memory/date, and Bring a session into a chat appends a session's messages as notes, once (chat-memory/import). Jeden's refusals are shown as Jeden wrote them, and an answer without the fields the screen shows is named, never shown as an empty memory. tests/memory in Jeden Desktop reads what the real Jeden answers for the chats Jeden's tests/chat_memory/chats.mjs left beside JEDEN_DESKTOP_TEST_SESSION_ROOT.