Omniscio

Plugin AI-Native Sessions

The in-plugin session experience: start and open AI sessions inside any marketplace plugin, with a Sessions pane, suggested-prompt chips, first-class visibility in the Inbox, an auto-context briefing the agent receives, and optional standing context contributed into your own projects.

On this page

What it is

Status: shipped (always on). The plugin-ai-native-cli feature landed 2026-08-06 — the plugin CLI forwarder and the in-plugin session experience below are available in every installation. No Lab flag gates them, and this surface is safe to document publicly.

The in-plugin session experience: inside every marketplace-plugin surface (GitHub Integration, Calendar, Newsletter, Smrzz, …) you can see, open, and start first-class AI sessions — "start a session right there" — and every session started there opens already knowing what the plugin is and how to drive it through its AI-callable actions.

Where to find it

It has no sidebar row of its own; it lives inside the plugins you already have. Open a marketplace plugin from wherever it sits in the app, and look beside the plugin's own screen: a Sessions pane mounts there whenever that plugin declares at least one AI-callable action or a ui.sessions block, carrying the standard "+ New session" affordance, the usual section model, and the right-click management menu every integration shares. From a paired phone, opening a plugin shows the plugin's own screen first, with an AI sessions button on it; that button opens the same sessions in the normal list, and a Show <plugin> bar above the list (and above any open plugin chat) brings you back.

How it behaves

The experience is made of five pieces.

The Sessions pane

When a plugin project is active AND that plugin's OWN manifest declares at least one AI-callable endpoint (cli.endpoints) or a ui.sessions block, a pane mounts beside the plugin's webview listing the AI sessions that live at this plugin, with the standard "+ New session" affordance, section model, and right-click management menu (the same shared SessionHostSidebar every integration uses). The ui.sessions block alone is enough: a first-party plugin such as Flashcards, whose AI routes live in the core control server (/flashcards/*) rather than in its own cli block, still gets the pane. A plugin that declares neither (a UI-only plugin, like the former Uplink messenger) never shows the pane — it is a per-plugin manifest opt-in, not feature-wide. A plugin that DOES earn the pane can still decline it with ui.hideSessionsPane: true — the sibling of ui.hideProjectPanel, for a plugin that owns its full width; both are needed to clear the column entirely, because declining only one hands the slot to the other surface. Opening a session swaps the webview for the chat; a "Show <plugin>" button swaps back. On a phone there is no side-by-side pane, so the same swap is a pair of buttons: the plugin's own screen opens first with an "AI sessions (N)" button (offered when the plugin has sessions or declares AI actions, whether or not it declined the pane with ui.hideSessionsPane), the sessions list and an open plugin chat carry a "Show <plugin>" bar, and Back from a chat lands on the plugin's screen. A plugin whose screen the phone cannot serve yet shows the "only available on the desktop app" notice in that same place, with the AI sessions button still one tap away; Nighty Tidy 2 keeps its native phone panel, and Decks (desktop-only) shows the same notice.

One column for a plugin's list and its sessions

A plugin that shows its own list in the left column (ui.sidebar, without ui.hideProjectPanel) AND earns the Sessions pane never gets two columns. It gets ONE column at the sessions-sidebar width with the app's standard tab switch at the top, the same one Mind Maps, Mission Control, Writer and Agent Email use: [the plugin's list | Sessions]. The first tab is named after the plugin's sidebar title (or the plugin's name) and is the default. The header is one 40 px row: the tabs on the left (arrow keys move between them), 13 px text, the chosen one in semibold with a 2 px accent underline, and the New session button on the right while Sessions is shown. The Sessions tab carries one small dot: orange while a session needs you, red while one has an error (red wins), nothing otherwise; hover the tab for the split counts ("2 running, 1 needs you"). The Sessions list has no second title under the tabs. The app remembers which tab you picked for each plugin until it restarts. While one of the plugin's chats has the screen, the column shows the Sessions tab, so the "Show <plugin>" way back is always in view; picking the list tab then also brings the plugin back. A plugin with only a list, or only sessions, keeps its single column as before. This column does not fold; the fold below belongs to the sessions-only rail.

When the plugin's sidebar lives inside its webview

While Sessions is chosen, the Sessions view covers the whole plugin area, including the switch the plugin draws in its own page. So that view keeps the same header row on top, and picking the plugin's tab there returns to the plugin.

A plugin that owns its whole width (ui.hideProjectPanel) and draws its own sidebar INSIDE its webview — Courses, today — cannot get the column above: a host component cannot reach into a guest document, and the guest cannot import host modules. Such a plugin draws the same two-tab switch at the top of its own sidebar, with its own list underneath, and the APP keeps ownership of which half is showing: the guest asks through host.setSurfaceTab({ tab }) (one of items or sessions, nothing else) and the host — which already owns the plugin column tab — applies it and echoes the current tab, with the live session count, down the existing commands channel as surfaceTab. The guest renders the host's answer, never a local idea of the state, so a chat opening and forcing the sessions tab can never leave the two disagreeing. Neither side draws a bar across the top of the panel: the switch belongs to the sidebar, at the sidebar's width, in both layouts. The text switch renders at md+ only; below that the plugin's sidebar is a 48px icon rail and the phone keeps its existing AI-sessions door. A plugin that ignores the echo only loses its own switch, never the pane.

A plugin that asks for its chat beside it is never swapped. When a full-width plugin also sets ui.sessions.chatPlacement: "beside" (Site Studio and PDF Viewer today), the in-place swap does not apply: it keeps the ordinary sessions rail, and an opened chat takes the right side while the plugin keeps the left (computePluginSurfaceTabbed in compute-plugin-chat-active.ts). Swapping such a plugin away would hide the very screen its chat is meant to work on — the plugin a person is editing disappears and the space reserved for it beside the chat stays blank.

Folding the rail

The Sessions rail folds. A button in the rail's top corner (the same panel icon the projects sidebar uses) shrinks it to a 48 px strip and back. The strip is never empty: it still starts a new session, offers one sparkle icon per suggested prompt (one click opens the shared Start session dialog with the prompt in Message), shows Interrupted with a red count and Agent sessions with an orange needs-you count, and holds an Archived icon whose hover name carries the total. Clicking a section icon unfolds the rail. While one of the plugin's chats has the screen, the strip also shows a "Show <plugin>" arrow at the top, so the way back to the plugin never disappears. The counts are the same numbers the open list shows (the Interrupted badge includes ended sessions), and Focus Mode hides them, as it does on the Sessions tab badge. A per-context plugin with nothing open shows no start icons on the strip, exactly as its open pane offers no way to start a chat.

Each plugin remembers its own folded state and dragged width across restarts, so folding Newsletter never changes Calendar or the regular sessions sidebar. The slide takes 0.2 s, only when you fold or unfold, and is instant with reduced motion; the resize handle is gone while folded. The button is the only way to fold the rail: there is no keyboard shortcut for it, and Ctrl+Shift+\ keeps its job of hiding the regular sessions sidebar. Plugins that decline the rail (ui.hideSessionsPane, as Decks, Forms and GitHub do) fold their own side panels instead. The folded rail is desktop-only, because the pane never mounts on mobile.

First-class visibility — from ANY entry point

Sessions the USER starts under a plugin — the pane's "+ New session" OR the global "+ New" / Cmd+N / quick-launch (which carry source='ui') — live in the plugin's own project and appear in the unified Inbox, project badges, and Needs-You counters like any other session. Only sessions the PLUGIN starts for itself (the v2-worker ctx.sessions.create background research spawn, source='plugin:<id>') stay hidden. The chokepoint decides by a POSITIVE managed-discriminator — hidden IFF the source is plugin:<id> (or provenance is nullish → fail-safe, or the feature is dark) — NEVER a user-source allowlist (that allowlist was a bug that hid ui/quick-launch user sessions). The archived count AND list apply the same __plugin__ exclusion (flag-independent) so the pane header can't drift from the list and managed sessions don't leak into the global Archive view.

Sessions an AI started for the plugin

A plugin sometimes starts a session because an AI asked it to (for example a GitHub plugin that opens a session from an issue an AI picked), not because you clicked. The plugin says so when it creates the session: ctx.sessions.create({ userInitiated: true, startedBy: 'agent' }). You still see that session in the sidebar and inbox like any other, and can answer it, but Omniscio treats it as started by an AI, so the Agent Firewall (when it is on) screens what it reads instead of waving it through as something you typed. Leaving startedBy out, or 'me', keeps today's behaviour. The claim can only make a session safer, never less safe, and any other value is refused. The answer to a create includes startedBy: 'agent' when Omniscio honoured it; a plugin running on an older Omniscio gets no such field, which is how it knows the request was ignored. In Ctrl+K's "Started by" filter these sessions appear under Omniscio, and your own clicks under Me.

Purpose-built auto-context (the capability card)

The first message of a plugin-surface session invisibly carries: a short orientation (the agent runs inside Omniscio; the user is viewing the chat inside this plugin's surface; Omniscio provides the session, the inbox where approvals land, and the control server), the plugin's identity, its AI-action list as method-bearing lines (GET status — description, [requires human approval] marks reflecting the ask-first rule — any action that is not a declared read or marked safe, whichever key the caller holds, not just a bare requiresConfirmation flag), how to call http://127.0.0.1:19519/plugins/<id>/cli/<path*> (bearer from the session's own AMC_CLI_TOKEN, plus the X-AMC-Source-Session-Id header) including one worked curl example synthesized from the plugin's own first read action plus the generic POST form, what to do when an action needs the user's approval (HTTP 202 + approvalRequired → the request is in the Omniscio inbox; the AI must never claim the action already ran, and once the person has decided it re-sends the same request with the same X-Client-Request-Id to read the plugin's own answer — an approved call returns that answer, a declined one returns a refusal), a scope contract ("you are the <plugin> agent — prefer this plugin's actions; work unrelated to the plugin is out of scope for this session, suggest a regular Omniscio session"), and the caveat that a CLI call fails loudly (404 unknown plugin · 409 disabled / worker down) rather than silently doing nothing. Only the SENT text carries this — the chat bubble shows just what the user typed.

Suggested-prompt chips (chat-first entry)

A plugin may declare up to 4 curated starters in its manifest — ui.sessions.suggestedPrompts: [{ label, prompt }]. The Sessions pane renders them as chips: front and center in the empty state, a compact row above the list otherwise. ONE click opens the shared Start session dialog for the plugin (and the item open in it) with that prompt in Message; Start sends it as the first message, with the item's note and the plugin's description of the open item after it. A malformed list fails the whole manifest loudly at load; no declaration means the pane looks exactly as before. An auto-sent prompt gets no special powers: if the agent immediately calls an action marked requiresConfirmation, the call still queues to the inbox for the human. When that endpoint declares preview, the approval card shows the plugin's own summary of what will happen (see plugin-cli-discovery.md).

Per-context chats — each open item keeps its own chats

A plugin can say what is open right now (for PDF Viewer, the open document) and opt its pane into showing only that item's chats. The person then sees "Chats for report.pdf", only those chats, and the chips and New button start chats for that document. Switching to another document switches the list. When nothing is open the pane says so in the plugin's own words and offers no start button. Chats are remembered per item, so reopening a document after a restart brings its chats back. Omniscio only files a chat under an item the plugin itself named, so the app window cannot invent one. Other plugins' panes are unchanged unless they opt in (ui.sessions.perContext). Desktop only — the pane has no phone version.

Chat beside the plugin

Normally, opening a plugin's chat covers the plugin. A plugin can ask for its chats to sit beside it instead (ui.sessions.chatPlacement: 'beside'): the plugin stays on the left, still loaded and usable, and the chat takes a strip on the right. Closing the chat gives the plugin its full width back. Desktop only.

A Sessions side panel for plugins with their own tabs

A plugin that already draws its own top tabs (Calendar, Forms) can set ui.sessions.sidePanel: true and show its chats in a 320 px panel on the right instead of the column tabs or the left rail. The plugin page stays on the left and usable. The plugin draws only its own button; it opens and closes the panel with the existing host.setSurfaceTab call (sessions opens, items closes), and Omniscio echoes the state back on the surfaceTab command with sidePanel: true while it shows the panel for that plugin. At the top of the panel is an "Ask about your <plugin>..." box: Enter opens the shared Start session dialog with the typed text in Message, and Start sends it as the chat's first message (Shift+Enter adds a line), filed under the open item for a per-context plugin. Below it are all the plugin's chats, newest first. Opening a chat replaces the list in the same strip, which widens to chat width under a "Back to sessions" bar; closing the panel closes the chat. Omniscio remembers whether the panel was open, per plugin, across restarts (a plugin never opened starts closed), keeps the width fixed at 320 px with no drag edge, slides it in over 180 ms (none under reduced motion), puts the cursor in the Ask box on open, closes it on Esc, and below about 1100 px of window width floats it over the page with a soft shadow instead of squeezing the page. The plugin draws the pressed look on its own button and focuses it when the panel closes. The panel is desktop only, and an older Omniscio ignores the key. Rules 23 to 25 of the plugin pane contract.

Locked sessions — an AI that can only talk

A plugin can start a session that is locked: it has no tools at all — no shell, no file reads, no web, no tool servers — so it can only read what the plugin sends it and write replies. The plugin does every action itself. This is for a plugin that shows an AI untrusted text (someone else's database rows, a stranger's message): text in that data cannot talk the AI into running a command, because there is nothing to run. Database Studio's Ask agent works this way.

  • The lock stays with the session for its whole life — after a restart, a resume, a model change and after the plugin moves the session into view ("Continue in chat"). Moving it into view also opens that chat for the person, whatever their "auto-switch to inbox" setting says, and it shows in the inbox, the counts and the plugin's session list straight away, on the desktop and on a paired phone.
  • If the session ever comes up with a tool anyway, Omniscio stops it before its first turn; if it asks permission for anything, Omniscio refuses at once.
  • Its standing instructions leave out everything it could only use with a tool — Omniscio's control server, files, commands, shares, messages to other sessions — so it is not paid to read them. The safety rules and your own instructions still reach it. With default settings that cuts a hidden locked session's standing prompt from about 25,000 to about 4,700 characters, and one moved into view from about 49,500 to about 26,300.
  • It runs only on this computer and only on an engine Omniscio can lock (Claude or a Claude-compatible vendor). The same holds for every session of a plugin that did not declare sessionTools: its sessions have no tools, and only those engines can keep them that way. On Codex, Gemini, Cursor or any other engine with its own program, including when that engine is your default and the plugin picked none, the session is refused before it starts, with a message naming the engines that can run it. A locked session also cannot be switched to such an engine later, and is never resumed on one.
  • A plugin may name the model by tier (worker, genius, …) rather than by model id.

A hidden plugin session that is NOT locked also never waits on a permission card nobody can see: an ask that would need a person is refused instead, while calls your permission level already allows still run.

A hidden plugin session is also never sent the automatic "Please continue." that Auto-continue adds after a turn that stopped without a question. The plugin reads the answer and decides what to send next; an unasked nudge only spends a paid turn nobody is watching. A session the plugin silently stops hearing from is still revived by the silence watchdog (no output at all), as before.

A visible plugin session (one the person can see, with or without tools) gets neither "Please continue." nor the Plain Speak request for a missing card. Its instructions come only from the plugin's own short brief, which never asks for the app's finish marker or a card, so a complete answer without them is normal. Before 2026-11-04 both nudges fired after every Newsletter answer, and the person saw one answer split across three or four bubbles. Rule: no-nudge-for-a-contract-it-never-got in plugin-session-floor-contract.md.

The same goes for the app's low-context recovery and its "unfinished gate report" nudge: neither is ever sent to a hidden plugin session. A plugin can check host.getCapabilities() for plugin-session-restart-safe to know the app leaves its sessions alone after a restart.

The safety floor — every session a plugin starts for itself

On top of all this, every new AI agent session a plugin starts for itself runs on the plugin agent safety floor, on by default: none of your own setup, a folder of its own, Claude-family engines only, and never more tools than the plugin was granted. A hidden one answers in text only (the floor locks it the same way as above, unless its plugin asks for web search), and one you can see asks you before every command and every web request. "Continue in chat" turns a hidden session the floor locked into one that asks you; a session its plugin locked on purpose stays locked. Sessions YOU start here, from "+ New session" or a suggested-prompt chip, are not plugin agents and are not floored. Two switches loosen it, and you or an agent can change them like any other setting (no plugin can): Lock down plugins' AI agents in Settings → Plugins, and Give this plugin's AI agents my full access (not recommended) on the plugin's Marketplace card. The full rules are on Plugin agent safety floor.

Reach into YOUR OWN projects (opt-in, grant-scoped)

Everything above is about sessions living at the plugin. A plugin may also contribute standing context to sessions you start in your own repositories — so a session in my-app opens already knowing that plugin is there and how to drive it. Two things must both be true: the plugin declares ui.sessions.realProjectContext: true in its manifest, and you have granted it that specific project (the same per-project workspace grant used for file access). There is no new permission and no new toggle — granting is the opt-in, revoking the grant or disabling the plugin is the off switch. In an ungranted project the block never appears, which is deliberate: every action it would advertise there would be refused anyway, so showing it would advertise a lie. Unlike the static contextTemplate, the block is built by the plugin — the host calls the plugin's own single-segment context action (host-called only; it is not in the agent-facing action list) and expects { "context": "<the block>" } back. Rules the host enforces: it is frozen at spawn and rides the whole session, so it should name only stable facts (how to call the plugin, package/test counts, detected runners) and nothing that changes per run; it gets ~1.5 seconds and is dropped if the plugin is slow, not running, or answers oddly — a session never waits on a plugin to launch; it carries the same 5,000-character cap as contextTemplate, and over it the block is dropped whole, never truncated; it is never written into your repository (no .claude/session-context.md in your git tree); and it runs only when the plugin declares GET context as an unflagged read — it runs automatically as the session starts, with no one there to approve it, so anything else (a different verb, an undeclared path, or a path flagged requiresConfirmation) is skipped entirely rather than run without the approval it would need. You can see when it fired: the session shows a collapsed "seed-context" divider labelled with the plugin's name. Several granted plugins compose into one block.

Two neighbouring pages cover what a plugin's sessions can reach. The human-facing one-liner about those AI actions is plugin-capability-card.md, and the rules for what a plugin's own screen may call are plugin-bridge-capabilities.md. A session that instead has to FIND a plugin by name and drive it is plugin-cli-discovery.md, and installing or removing the plugins themselves is plugin-marketplace.md. What every session a plugin starts for itself may and may not do is plugin-agent-safety-floor.md.

Knowing when a streamed answer is finished

A plugin can listen for host.sessionTurnFinished on its own webview event stream. The host sends one completion for the finalized reply after its output, so a plugin can keep the pieces of one story together in one bubble. The payload is { sessionId, turnId }; the turn identifier is opaque. A settled output message replaces its previous text instead of adding another copy. Older hosts do not send this new event.

The finish event is a generation-completion marker emitted after the finalization attempt. It makes no promise that the transcript was saved. Use it to close streamed output, never as a persistence receipt.

Last verified 2026-11-11