Jean-Pierre

Appearance

View Markdown

Ubiquitous Language ​

This is JP's domain vocabulary: the shared, rigorous terms used across code, documentation, commits, RFDs, CLI help, and error messages. Every contributor (human or AI) should use these terms as written — don't paraphrase or substitute near-synonyms.

When you encounter a new concept that doesn't fit existing terms, add it here. When an existing term is contradicted by usage or misleading, update the definition — don't paper over the drift with aliases or inline comments explaining the mismatch.

In disagreements between code and docs, the code is authoritative.

Table of Contents ​

Terms ​

Attachment ​

External content attached to a conversation to provide context: a file, URL contents, command output, Bear note, etc. Implemented as Attachment in jp_attachment. Each attachment kind is a separate crate (jp_attachment_file_content, jp_attachment_cmd_output, and so on).

Background Task ​

Async work scheduled to run alongside a command and committed to the workspace before JP exits. Implemented by the Task trait and TaskHandler in jp_task. A task is two-phase: run (off the main critical path, cancellable, accumulates state) and sync (with &mut Workspace, commits the accumulated state). The handler lives at Ctx::task_handler and is drained exactly once per jp invocation, at the end of jp_cli::lib::run.

CommandConfig ​

The shape of an external command JP runs on behalf of the user: a program, arguments, and an optional shell flag. Implemented as CommandConfig in jp_config::types::command, with CommandConfigOrString providing a string-shorthand variant for TOML/JSON config.

String-shorthand values (command = "git log --oneline") are parsed with shell-word semantics via shlex::split, so quoting works ("echo 'hello world'" is one hello world arg). Malformed shell quoting is rejected at config-parse time.

Consumers (tools, conversation labels, the editor env-var fallback, the cmd: attachment URL) share the same shape and parser. The policy around when JP is allowed to run a CommandConfig (prompt or not, confirm shell = true invocations) lives on each consumer, not on the shape itself.

Compacted View ​

What the LLM actually receives for a conversation: the raw event stream with every Compaction and Event Overlay applied. Produced by ConversationStream::apply_projection in jp_conversation, which also returns a TurnOrigin per resulting turn mapping it back to the raw turn number(s) it stands for. jp conversation print --compacted renders it.

Turn numbering differs between the two: a Summary collapses its range into a single turn, so the compacted view can be shorter than the conversation it came from.

Not the same as a Workspace Projection. The word "projection" carries two unrelated meanings in the codebase: applying conversation overlays (jp_conversation::stream::projection) and writing a conversation into the workspace directory (Projection in jp_storage).

Compaction ​

A non-destructive overlay that reduces what the provider sees for an inclusive range of turns. The original events are never removed: the overlay is appended to the conversation stream and applied when the Compacted View is built. Implemented as Compaction in jp_conversation::compaction, carrying up to three independent policies over its range — a Summary, a reasoning policy, and a tool-call policy. See RFD-064.

A Summary supersedes the other two for the turns it covers.

Compaction Rule ​

The configuration that produces a Compaction: how many turns to preserve at each end, and which policies to apply to the rest. Implemented as CompactionRuleConfig in jp_config::conversation::compaction; each rule yields exactly one Compaction when applied.

Not the same as a Compaction. A rule is durable configuration in relative terms ("keep the last turn"); a Compaction is the event it produced, pinned to absolute turn indices and stored in the conversation.

Config Delta ​

A recorded change to a conversation's configuration: values to merge, and the paths to clear before merging them. Folding a conversation stream's deltas over its base config is what produces the conversation's resolved config. Implemented as ConfigDelta in jp_conversation::stream, either an ApplyDelta (values plus the paths it clears) or a ResetDelta (discard the accumulated state and restart from program defaults).

A delta is computed once, against the state its author means to diff from, and recorded as given.

Not the same as a config snapshot, which states every value rather than what changed. Both are carried as a PartialAppConfig, so diffing a delta as though it were a snapshot type-checks — and silently changes what its values mean.

Conversation ​

A persistent sequence of events identified by a ConversationId, living within a Workspace. Implemented as ConversationStream in jp_conversation. The user-facing notion of "a chat history with the assistant."

Not to be confused with Thread. A Conversation is the stored entity; a Thread is what we build from it to send to an LLM.

Conversation Event ​

The atomic unit of a conversation. Implemented as ConversationEvent (with EventKind) in jp_conversation. The variants are TurnStart, ChatRequest, ChatResponse, ToolCallRequest, ToolCallResponse, InquiryRequest, InquiryResponse.

Not every event is sent to LLM providers. EventKind::is_provider_visible() filters the stream down to the chat and tool-call events; turn markers and inquiries are internal.

EditorBackend ​

The frontend seam for invoking the user's configured editor. Exposes edit_text (string in, edited string out) and edit_file (open the editor on caller-owned paths), covering both editing shapes a frontend offers. Each frontend is one implementation: TerminalEditorBackend spawns the editor as a local process via EditorConfig::command(), and MockEditorBackend scripts outcomes for tests. Defined as the EditorBackend trait in jp_editor; call sites obtain one through build_editor_backend in jp_cli.

Envelope ​

The argument shape a Fan-Out tool is advertised with: an object holding one ops array, each element of which is one complete set of the tool's own arguments. JP's construction rather than anything the tool declares; built by envelope in jp_mcp::server::fan_out.

Not the same as the tool's own parameter schema, which describes one Operation and is what each operation is validated against.

Event Overlay ​

A non-destructive overlay that rewrites the metadata of the events it matches when the Compacted View is built. Recorded when a provider rejects metadata on events already in the stream — most often a reasoning signature that no longer covers the content beneath it. The events themselves are never modified: the overlay is appended to the conversation stream, so the stored history stays byte-identical. Implemented as EventOverlay in jp_conversation::patch, matching events by metadata value rather than by position.

Not the same as a Compaction, which is also a non-destructive overlay. An Event Overlay changes the metadata of individual events; a Compaction reduces what a range of turns contributes.

External Login ​

A subscription login whose credentials and refresh lifecycle are owned by an external runtime. JP registers its configuration directory and observed account identity without storing its tokens. Implemented by CredentialSecret::External in jp_credentials.

Not the same as a JP-stored token or a subscription flow: the login identifies an account, while the flow selects how requests reach the provider.

Fan-Out ​

A tool call carrying several independent Operations in an Envelope, which the JP MCP Server runs as separate Invocations and folds into the single response the caller is waiting for. A property of a tool's configuration, not of its implementation, which still receives one operation per execution; configured by FanOutConfig in jp_config::conversation::tool.

Not the same as a tool that takes several targets as one action, such as fs_modify_file, which applies them together and is approved as one.

InlineReply ​

The jp_inquire widget for short replies: the interrupt-menu reply (r in both the streaming and tool menus) and the tool argument / result / skip-reason edits. It renders on the /dev/tty prompt writer and accepts inline typing, with a Ctrl+X escape to the configured editor (the EditorBackend) for longer edits. Submitting produces a ReplyOutcome; the call site decides what an empty submission or a Ctrl+C cancel means. Built on a patched fork of reedline; the inline buffer's editing style is set by editor.inline.edit_mode.

Inquiry ​

A structured question-and-answer pair between the assistant, a tool, and/or the user — distinct from a regular chat message. Carried as InquiryRequest and InquiryResponse events within a conversation. Used for mid-turn clarification that should not appear in the main chat stream or be sent to the LLM provider as context.

Invocation ​

One execution of one tool call inside the JP MCP Server, from the moment the call is admitted to the moment its result is recorded. It carries an identity the server assigns itself, so two callers asking for the same tool with the same arguments at the same time remain distinguishable. Implemented as InvocationId in jp_mcp::server::service.

Each Operation of a Fan-Out call runs as a child of the call's invocation, and ends by settling into it rather than by being recorded.

Not the same as a Tool Call, which is the pair of conversation events an invocation produces, nor a transport request ID, which belongs to whichever protocol carried the call.

A tool that asks for input ends its execution attempt and runs again with the answer; both attempts belong to the same invocation.

JP MCP Server ​

The in-process service that executes tool calls: it resolves the tool, validates arguments, runs the local command, built-in, or upstream MCP tool, and produces the result. It owns no conversation and makes no policy decision about who answers a question; it asks the MCP Host for each decision it needs. Implemented as Service in jp_mcp::server::service.

Not the same as a third-party MCP server, which is an external process configured under providers.mcp and reached through this one.

Match ​

A Search Hit whose line actually contains the pattern, as opposed to one included only for surrounding context. Recorded as is_match on the hit, along with the byte ranges of the matched substrings.

Matches are the unit every count in jp conversation grep uses: the figure in a heading, the --output count value, and the --max-matches cap.

Not the same as. A Search Hit, which also covers context lines.

MCP Host ​

The side of a tool call that owns everything the JP MCP Server deliberately does not: admission, argument and result editing, inquiry routing, and writing the conversation. The server asks; the Host decides and records. In JP the Host is the CLI process, reached through the private channel a HostReceiver carries.

Not the same as an MCP client, which is any caller that invokes tools over the protocol. The Host is one such caller, and a third-party client is another; only the Host answers the server's decisions.

Operation ​

One element of a Fan-Out call's ops array: one complete set of the tool's arguments, run as its own child Invocation and shown, approved, and reviewed as a call of its own. Operation in jp_mcp::server::service identifies one by its call's invocation, its position, and the number of operations in the call.

Not the same as a Tool Call: the operations of one call share its tool call id, and the conversation records one response for all of them. Nor the informal sense used by access policies, where an operation is whatever one tool execution does to a path.

Pinned Conversation ​

A conversation the user has marked as important, so it stays prominent and is protected from casual removal. Pinning is a property of the conversation itself, not of any session or view: it persists with the conversation and means the same thing everywhere the conversation appears. Persisted as a pinned_at timestamp on the conversation metadata; Conversation::is_pinned() in jp_conversation is the predicate.

Not the same as binding a session to a particular target. Pinning marks one conversation as important; it does not make a session "keep using" that conversation. Keeping a session attached to a chosen target is a separate, per-session concept, not conversation pinning.

Provider ​

An LLM vendor integration — one of anthropic, google, openai, openrouter, llamacpp, ollama, cerebras, deepseek. Each implements the Provider trait in jp_llm.

RFD ​

"Request for Discussion" — JP's design document format, stored in docs/rfd/. Each RFD captures design rationale for a significant change. Numeric-prefixed RFDs (001-, 002-, …) are the accepted series; D-prefixed RFDs (D01-, D02-, …) are drafts or abandoned proposals. The process itself is defined in RFD-001.

Search Hit ​

One line of conversation content emitted by a search, together with the coordinate that locates it: the conversation, the turn it came from, and which part of the conversation it was found in (its scope — title, user, assistant, reasoning, tool call, and so on). Implemented as Hit in jp_cli::cmd::conversation::grep.

A hit is either a Match or a context line pulled in by --context; both are hits.

Not the same as. A Match (a hit whose line contains the pattern), a Conversation Event (one hit is a single line from within an event, and one event can yield many hits).

Service Tier ​

The grade of capacity a request is served from, trading price against latency and availability. JP models four rungs (off, flex, standard, priority) as ServiceTier in jp_config::model::parameters, and each Provider maps them onto its own wire vocabulary. off is the rung that asks for nothing, which every provider expresses by sending no tier at all.

A provider that sells no equivalent of the requested tier refuses the query rather than substituting a neighbouring rung, since the substitute would cost something else. A tier that is sent is still only a request: providers may shed it to another tier under load, and bill at whatever actually served it.

Not the same as the model: a tier changes what the request costs and how fast it is served, not which weights answer it.

Signal Router ​

The process-wide owner of OS signal handling: SignalRouter in jp_cli::signals (RFD 045). It consumes SIGINT/SIGTERM/SIGQUIT once, tracks Ctrl+C escalation (first press → topmost interrupt handler, second press within the cooldown → graceful shutdown, any press after shutdown began → immediate exit), and owns the root shutdown token — a CancellationToken cancelled when a graceful shutdown is requested, observed cooperatively by teardown and long-running work.

Scopes that can act on a Ctrl+C register an interrupt handler on the router's LIFO stack via push_handler, receiving an RAII guard and a notification channel polled from their own event loop. Only the topmost handler is notified; a handler may decline to pass the interrupt down the stack. The registered scopes are the streaming loop, the tool execution loop, and the turn-level handler covering gaps between turn phases.

Subscription Flow ​

The request implementation selected for subscription authentication within a provider. Represented by SubscriptionFlow in jp_config::providers::llm::anthropic.

Not the same as a credential, model, or service tier: selecting a flow does not select an account, change the model ID, or authorize another billing kind. API-key requests do not use this selection.

Summary ​

Text that stands in for a range of turns in the Compacted View: the turns it covers collapse into a single synthetic request/response pair carrying the text. Attached to a Compaction as SummaryPolicy in jp_conversation::compaction, whose SummarySource records whether the text was generated (produced by a model reading the raw events in the range) or authored (supplied verbatim by the user).

The distinction is operational: a generated summary can be re-derived for a wider range, an authored one cannot.

Not the same as the mechanical compaction policies (reasoning stripping, tool-call stripping), which filter events within their range rather than replacing the range.

Thread ​

The decomposed, provider-facing projection of a Conversation: a rendered system prompt, rendered instruction sections, raw attachments, and a filtered event stream, ready to be sent to an LLM provider. Implemented as Thread in jp_conversation::thread.

A Conversation becomes a Thread at query time, via the config and conversation pipeline. A Thread is transient; a Conversation is persisted.

Tool Call ​

An LLM-requested function invocation (ToolCallRequest) and its eventual response (ToolCallResponse). Tool calls are events within a Turn. The tool itself can be a built-in, a local command, an MCP-provided tool, or a plugin.

Tracking Ticket ​

The single ticket that stands for an RFD's implementation as a whole, carrying its implementation plan as the description. It is the ticket whose Implements field names the RFD and whose labels include type=tracking; an RFD has at most one. Whether that ticket is In Progress is what "this RFD is in development" means.

Not the same as a phase ticket, which names the same RFD in Implements but carries no type=tracking label and covers one slice of the work.

Turn ​

A group of conversation events delimited by a TurnStart marker: one user chat request through the assistant's final response for that request, including any intermediate tool calls and inquiries. Implemented as Turn<'a> in jp_conversation::stream::turn_iter.

A single Conversation contains many Turns, separated by TurnStart events.

User-Workspace Directory ​

A workspace's per-user data directory, ~/.local/share/jp/workspace/<slug>-<id>/: this user's durable state for one workspace — conversations, session mappings, locks, the roots registry, and the user-workspace config search root. Named for the user-workspace config scope: the this user × this workspace point in the user-global / workspace / user-workspace scope taxonomy. Located by workspace-ID suffix, never by exact name; <slug> is cosmetic, display-only, and never renamed. Implemented by FsStorageBackend::with_user_storage in jp_storage; directory-name parsing lives in jp_workspace::roots. See RFD-031 and RFD-087.

Workspace ​

The top-level project unit, housing conversations, configuration, plugins, and state for JP. Identified by a .jp/ directory at the project root. Implemented as Workspace in jp_workspace.

Workspace Projection ​

The copy of a conversation written into the workspace's .jp/conversations/ directory so it can be committed to version control alongside the project. The durable source of truth is the user-local copy; the workspace copy is a projection of it. Non-local conversations are projected (written to both roots); --local conversations live only in user-local storage and have no projection. The write intent is carried by a conversation's lock (Projection in jp_storage) and derived at load time from where the data lives (StoragePresence). See RFD-031.