Omniscio

AI Coaching sidebar (interview prompts and artifacts) (part 4)

Part 4 of the AI Coaching sidebar page: the CLI control-server surface for AI Coaching, the developer-only interview prompt editor, and the implementation pointers for agents working on the feature.

On this page

What it is

This is part 4 of the AI Coaching sidebar (interview prompts and artifacts) page. It is the reference half of the feature: the CLI control-server routes an agent can call, the developer-only interview prompt editor, and the file-by-file implementation pointers for anyone touching the AI Coaching code.

Where to find it

The CLI routes below are served by the localhost control server at 127.0.0.1:19519 — there is no UI for them. The developer-only Prompts section appears in the AI Coaching sub-sidebar only in an unpackaged build, and every route is gated the same way the rest of the feature is; the parent page covers the surfaces a user actually clicks.

How it behaves

CLI control

AI Coaching is reachable from the localhost CLI control server at 127.0.0.1:19519 through a family of endpoints; the table below lists the ones this page relies on, and the full list is in cli-ai-coaching.md. They list interview prompts, list/get/search/version-history artifacts, get session-scoped coaching info, CRUD bookmarks and read compaction summaries; they let the coach save its own interview write-up and create a custom interview; and they carry the approval-gated POST (create a new artifact), PATCH (update artifact), DELETE (remove artifact + all versions), and POST (start a new interview). Reads are bearer-gated and read-budgeted; artifact mutations require user approval in the Omniscio inbox before any side effect; bookmark mutations apply immediately (no approval needed). The whole surface is gated by a two-tier kill switch: aiCoachingEnabled (master) + aiCoachingCliEnabled (CLI-specific, default true) at Settings → CLI Control. With the master switch off every route returns 403 with disabled: true, to everyone; with the CLI switch off every route returns that 403 to outside callers, but never to the in-app coach, which saves each interview's write-up over this surface. Both switches are checked again when an approved request is carried out, so a request approved or always-allowed before you turned either switch off changes nothing. Idempotency via X-Client-Request-Id (≤64 chars, 30-day window, scoped per action_kind) on the approval-gated routes, answered by the shared approval gate so a repeat of a still-pending request keeps its approval link; the apply-immediately creates replay a repeated id for ten minutes. Writing your coaching data (artifact create, update, delete and custom-interview create) takes the full-access key only — no other app session's key can plant text there. Optimistic concurrency on artifact updates via expectedLatestVersion (returns STALE_ARTIFACT on mismatch).

Method Path Gating
GET /ai-coaching/prompts bearer + read-budget
GET /ai-coaching/artifacts full-access key or the coach's own key + read-budget
GET /ai-coaching/artifacts/:id full-access key or the coach's own key + read-budget
GET /ai-coaching/artifacts/:id/versions full-access key + read-budget
GET /ai-coaching/artifacts/:id/versions/:version full-access key + read-budget
GET /ai-coaching/sessions/:sessionId/info bearer + read-budget
GET /ai-coaching/bookmarks bearer + read-budget
GET /ai-coaching/compaction-summaries bearer + read-budget
GET /ai-coaching/compaction-summaries/latest bearer + read-budget
POST /ai-coaching/bookmarks bearer + apply-immediately
PATCH /ai-coaching/bookmarks/:id bearer + apply-immediately
DELETE /ai-coaching/bookmarks/:id bearer + apply-immediately
POST /ai-coaching/artifacts full-access key; approval-gated (ai_coaching.artifact_create)
PATCH /ai-coaching/artifacts/:id full-access key; approval-gated (ai_coaching.artifact_update)
DELETE /ai-coaching/artifacts/:id full-access key; approval-gated (ai_coaching.artifact_delete)
POST /ai-coaching/interviews approval-gated (ai_coaching.start_interview); the coach's own session key is accepted
POST /ai-coaching/sessions/:sessionId/artifact the coach's own session key (its own session only) or the full-access key; apply-immediately, 6 a minute per session
GET /ai-coaching/artifacts/search full-access key or the coach's own key + read-budget
POST /ai-coaching/custom-interviews full-access key; apply-immediately, 2 a minute

Full route reference, examples, and the approval-gated pipeline live in cli-ai-coaching.md.

Only the signed-in account's data is ever served

On a computer that more than one Omniscio account signs into, every AI Coaching, Life Inventory and Journal entry point waits until the signed-in account's own data is the live data before it reads anything. In the app, a screen waits while that account's data is being brought back (a few seconds after a different account signs in), and shows "Sign in to use AI Coaching, Life Inventory and Journal." while nobody is signed in, or "Your coaching data isn't ready yet. Please try again in a moment." if the move takes longer than a minute. The /ai-coaching, /life-inventory and /journal CLI routes answer 403 while nobody is signed in and 503 with a Retry-After header while the data is still being prepared. A coach still running in a chat that belongs to a set-aside account is refused outright, so it can neither read nor save into the new account's space — and a message sent, scheduled or resent into that chat is refused too, with "This chat is set aside on this computer. It belongs to a different account, or it is waiting to be claimed in AI Coaching." rather than the sign-in sentence, because the person reading it is signed in. That one sentence has to be true for every chat in the set-aside store, which holds both another account's chats and coaching data with no recorded owner. While nobody is signed in, no message reaches any coaching chat, including the chats of the account that just signed out: a typed reply is refused with the sign-in sentence, a scheduled message stays scheduled and a resume after a usage limit waits, so all three go through once that account signs back in. Every other chat sends as normal. While the space is not open, the coach's context (the free-form "+ New" chat and every interview) is built empty: no profile, write-up, bookmark, memory or Journal entry goes into it. Background work that was still running when the account changed (a Core Profile rebuild, memory extraction, a session summary or an insight) never saves its result into the new account's space; the result is dropped rather than saved in the wrong place. The Core Profile and insight are made again on their next refresh. The rules behind this are in personal-space-per-account-contract.md. The person's answer to "may agents write my coaching profile without asking me?" ends with the person who gave it: when a different account signs in, that switch goes back to asking and any "always allow" standing on those approval cards is withdrawn, so the new account is asked again. A person who signs straight back in keeps their own choice, and no other approval setting or grant is touched.

The interview coach can use the safe endpoints itself

The AI coach running an interview is told — inside its own session context — that it is operating in the Omniscio AI Coaching module, and it may call a few of these endpoints on your behalf. They are best-effort and non-blocking:

  • Bookmark a meaningful moment (POST /ai-coaching/bookmarks) — when you have a genuine realization or say a line worth revisiting, the coach can save it as a Key Moment (the same bookmarks you make by hand), so you may notice bookmarks it added.
  • Recall an earlier part of a long session (GET /ai-coaching/compaction-summaries/latest) — to pick up context after a paused-and-resumed interview.
  • Suggest a follow-up interview (POST /ai-coaching/interviews) — if the conversation clearly points to an interview that would help, the coach can offer to start it; because that spawns a new (paid) session it normally lands as an approval request in your inbox rather than starting silently. With approvals switched off it starts at once, and the coach tells you which of the two happened. It asks with its own session key and a request id built from its session id and the prompt id, so asking twice never queues two cards. If you decline, the coach does not ask again on its own; only when you ask for that interview again yourself does it send one fresh request, and never more than that one.
  • Search and browse your saved artifacts (GET /ai-coaching/artifacts/search, GET /ai-coaching/artifacts?fields=slim, GET /ai-coaching/artifacts/:id) — to find the documents that matter for today's topic and pull one in full. These take the coach's own session key; any other app session's key is refused, and the version history stays out of its reach.

The coach is deliberately not told how to create, update, or delete artifacts over the API — those stay approval-gated and out of its instructions, and it saves your interview's write-up only through its own session-bound save route. Every helper call carries a short time limit, and if one is refused, rate-limited or times out, the coach skips it silently and the conversation is unaffected. Turning off AI Coaching CLI access in Settings → CLI Control closes these routes to outside callers, not to the coach; turning AI Coaching itself off closes them to everyone. It also treats your saved profile as data, never as instructions to call tools. The exact instruction block (COACHING_MODULE_TOOLS) and its locking test are covered in ai-coaching-contract.md.

The user-facing half of the feature is on the AI Coaching sidebar (interview prompts and artifacts) page: its artifacts in part 2, its memory and profile in part 3, and what happens around an interview — the wrap-up, Quick check-ins, opening messages, Bookmarks and Goals — in part 5. CLI control is the companion page for driving coaching from an agent.

Last verified 2026-11-02