Plugin Bridge Capabilities (what a plugin can call)
Every capability a plugin can call through Omniscio’s sandboxed bridge: the permission model and the host-primitive methods, with what each one refuses and the bounds it enforces. The session capabilities continue on part 3; the data, file and output capabilities on part 2.
On this page
What it is
Every Omniscio plugin talks to the host through a single sandboxed bridge exposed to its
webview as window.Omniscio (the same object a v2 worker backend receives as ctx). The same
bridge is also installed as window.AgentMC, its name before plugin SDK 3.4.0, so plugins written
against the old name keep working.
A plugin never touches the app's internals directly — it calls namespaced methods
(Omniscio.<namespace>.<method>(...)), and the host runs each one behind a Zod-validated,
permission-gated handler. The full surface (storage, db, sessions, ui, toast, clipboard,
shell, http, auth, …) is large; this page documents the higher-power capabilities most
useful for building a rich plugin — the ones a deck/report/AI plugin reaches for. The
complete, authoritative list of methods and their argument shapes is
capability-args.ts; the
permission each namespace requires is plugin-permissions.ts.
Permissions. A namespace that touches elevated capability is gated: the plugin must
declare the permission in its manifest.json permissions array, and the user consents at
install (a third-party plugin shows a permission-consent dialog; a
first-party built-in is exempt — its runtime pickers/logs are the control surface). A call to
a namespace whose permission is undeclared is rejected by the host. The
marketplace consent flow shows the user exactly which permissions a
third-party plugin requests before install. A plugin's own data is gated on BOTH surfaces:
storage, db and fs need storage, and the notifications namespace needs notifications, in
the panel exactly as in the background worker. Namespaces that reveal nothing beyond the plugin
itself (export, host, …) are ungated.
Toasts and desktop notifications. The toast namespace is gated on the notifications
permission. toast.show draws an in-app toast. toast.notify raises a real desktop
notification: it goes to the same plugin-notification path as notifications.fire, so it
follows Silence all, the "when to notify" behavior, Focus Mode and project mute, plays the app
sound only when sounds are allowed, and reports a blocked or denied OS notification setting
through the usual delivery-failure card. Alerts with the same title and body replace the one
still on screen instead of stacking. Nothing is shown on an isolated dev or sandbox instance.
A call from a plugin whose granted permissions no longer include notifications is refused.
Which plugins count as first-party. Declaring a permission is never enough on its own for the
capabilities that are first-party only: a built-in plugin qualifies, and so does a marketplace
plugin an admin has marked firstParty in the marketplace catalogue — but only while its
installed package still verifies against that catalogue entry. A valid signature on its own never
qualifies a plugin, because the marketplace signs every approved publisher's upload with the same
key. A plugin without the flag, a developer-installed one, and one whose package has drifted from
what the catalogue approved are all refused exactly as a third-party plugin is, so dropping the
flag on the server takes the capability away from the next call the plugin makes.
The full sign-in is first-party only. The auth namespace's identity reads (getSession,
getUser, and so on) require the plain auth permission, but auth.getWebAuth — which signs the
plugin in as the person, with the same access to their chats and workspace actions — needs its
own elevated permission, Sign In As You (auth.teamChatSignIn), and the first-party test above.
So a plugin holding only the identity permission can no longer obtain a token that acts as the user.
Where to find it
There is no Omniscio menu that opens this surface — it is reached from a plugin’s own code.
The host hands every plugin one sandboxed bridge object (the same one a v2 worker backend
receives as ctx), and every capability below is a namespaced method on it.
The one part of this a user meets directly is the permission surface: a plugin has to declare each elevated namespace in its own manifest, the user consents at install, and the resulting grants are managed afterwards in Settings → Plugins — the same panel that lists the folders a plugin may reach, the past session history it may read, and the files it may reopen without being asked again.
How it behaves
One subsection per capability: what it lets a plugin do, the permission it takes, what the host refuses, and the bounds it enforces. The host-primitive and session capabilities (including session history) are on this page; the data, file and output capabilities are on Plugin Bridge Capabilities (part 2).
How much a plugin may spend — the $5-a-day cap
The two metered capabilities — ai.* (title, message and structured generation) and tts.*
(speak text aloud) — draw on one shared budget: $5 of spend per plugin per calendar day, and
they draw it together rather than separately. A plugin that has spent three dollars on generated
titles has two dollars left for speech, and vice versa. Past the cap every further ai.* and tts.*
call is refused with a message naming the cap and telling the caller to try again tomorrow; the
budget resets at local midnight.
Three details a plugin author should know before building against it:
- The user sets it, the plugin cannot. It is the Plugins (AI) row in Cost Control (default $5, $0 turns plugin AI off). A plugin cannot raise, disable or read it — it is a host-enforced backstop, not a quota the plugin manages.
- It is per plugin, across the whole install — not per user and not per account. Every call the plugin makes anywhere counts against the same five dollars.
- The user's own daily ceiling applies on top. This cap bounds what a plugin can spend; it does not raise what the account may spend, so a plugin can still be stopped by the account's own daily limit first.
stt.* (transcription) is not on this budget — it bills to its own provider label, so a
per-plugin dollar cap on it would read zero forever; it rides the user's existing daily voice cap
and the Pro entitlement check instead. See Reading Queue for the read-aloud
consumer of the tts half.
Pictures (ai.generateImage, below) are not on this budget either: they have their own
per-plugin daily limit, described in the next section.
ai.estimateImage / ai.generateImage — make pictures on the user's credit (ai.images, elevated)
A plugin can ask Omniscio for one picture per request, or for a set of up to eight pictures behind one confirmation, from Image Studio, paid from the user's own Omniscio credit. The plugin never holds a key and never sees the image service: Omniscio prices the pictures, asks the user, pays, and hands the pictures back.
- Its own permission. All four methods need
ai.images, shown to the user at install as Make Pictures (elevated). Holdingai(text AI) grants nothing here. - Panel only. All four methods answer only from the plugin's own panel (
window.AgentMC.ai). The background worker and the phone relay are refused. ai.estimateImage(request)is free. It resolves{ ok: true, model, priceUsd }— Omniscio's own price for one picture, its service fee included.ai.generateImage(request)runs, in order: the off switch, sign-in, Omniscio's own price, the user's balance, the plugin's daily limit, then a confirmation Omniscio draws itself — the plugin's name marked "(plugin)", the prompt quoted, and the price in Omniscio's own words. Only Generate spends; Cancel, closing it, or leaving it for two minutes means nothing is made and nothing is charged. A plugin cannot pass in a price, and asking for more than one picture is refused. On success it resolves{ ok: true, imageId, base64, model, costUsd }: the picture always arrives as bytes. When Image Studio answers with only a storage address, Omniscio downloads it itself (https, Image Studio's own storage host, at most 10 MB, a 20-second deadline, PNG/JPEG/WebP/GIF only) so the plugin can draw it on a canvas; a download that fails is theimage-service-errorrefusal, and the charge already made is still recorded.requestis{ subject, model, aspectRatio, style?, imageSize?, transparentBackground?, referenceImages? }— the same fields Image Studio takes, minus the picture count and style references. Any other field is refused.- Reference pictures.
referenceImagesis a list of at most 2 base64 data URIs, eachdata:image/png;base64,…,data:image/jpeg;base64,…ordata:image/webp;base64,…, each at most 1,500,000 characters, and all the reference pictures in one set together at most 6,000,000. A third picture, a web address, another image type or a longer string is refused. They are sent to Image Studio as-is. The price does not change with them: it depends on the model, size and count only. ai.estimateImageSet(requests)is free.requestsis a list of 1 to 8 requests (each with its own subject and references). It resolves{ ok: true, items: [{ model, priceUsd }], priceUsd }— one price per request, in order, and their total.ai.generateImageSet(requests)runs the same checks asgenerateImage, but for the whole set: the off switch, sign-in, each price, the sum, the balance for the total, and the plugin's daily limit for the total (a set that would pass it is refused before any confirmation). Then Omniscio draws one confirmation — the plugin's name marked "(plugin)", the number of pictures, every prompt quoted and the total price — and only Generate starts. The pictures are made one after another, in the order asked. A set counts as one request for the busy and five-a-minute rules.- What a set returns.
{ ok: true, items, costUsd }: one entry per request, in order — either a made picture ({ ok: true, imageId, base64, model, costUsd }) or{ ok: false, code, message }for one that failed.costUsdadds up only the pictures actually made. A failed picture does not stop the rest; running out of credit does (the rest come back asinsufficient-creditand Omniscio offers Add credit once). Cancel, closing the confirmation, or leaving it for two minutes resolves{ ok: false, code: 'declined', message }with nothing charged. A set refused up front resolves a single refusal in the same shape. - A daily limit per plugin. Each plugin may spend up to $2 a day on this computer on pictures, set in Cost Control as Plugin pictures ($0 turns plugin pictures off). A request that would pass it is refused before the confirmation appears. The plugin cannot raise it.
- Not enough credit. When the balance cannot cover the price, or the payment is refused, nothing is charged and Omniscio offers Add credit (Plan & Billing → Buy credit) where buying credit is available.
- Refusals are answers, not errors. A picture that was not made resolves
{ ok: false, code, message }, wherecodeis one ofplugin-images-off,signed-out,plugin-image-daily-cap,insufficient-credit,declined,busy(another request from this plugin is already waiting, or it asked more than five times in a minute) orimage-service-error.messageis a plain sentence you can show the user. - Its own cost line. Each plugin's picture spend shows in the cost view as its own line, Plugin pictures: <plugin id>, separate from its text AI.
- Feature-detect it.
host.getCapabilities()includesai-imageswhile plugin pictures are switched on (Settings → Lab → Plugin pictures, on by default).
The promises behind this are in the plugin picture contract; billing runs through the same gateway wallet as Image Studio itself.
teamChat.offerCustomEmoji / teamChat.listCustomEmoji / teamChat.getCustomEmojiImage — offer a custom emoji to Team Chat (teamChat.emoji)
A plugin can hand Team Chat one picture to add as a custom emoji, and can read which custom emoji the workspace already has. The plugin never writes anything itself: only the person's Upload click in Team Chat's own add-emoji dialog uploads, through the same upload code as every other custom emoji.
- Its own permission. All three methods need
teamChat.emoji, shown at install as Team Chat emoji ("Offer custom emoji to Team Chat and see your workspace's custom emoji. You always confirm before anything is added."). It is a standard consent, not an elevated one. - Panel only. All three answer only from the plugin's own panel (
window.AgentMC.teamChat). The background worker and the phone relay are refused. teamChat.offerCustomEmoji({ imageBase64, contentType, suggestedShortcode }).imageBase64is the picture's bytes in base64 (nodata:prefix),contentTypeisimage/png,image/giforimage/webp, andsuggestedShortcodeis 2 to 32 lowercase letters, numbers, hyphens or underscores. Omniscio checks all three before anything is shown, using the same rules as the Team Chat uploader (PNG, GIF and WebP only; at most 256 KB once decoded; the shortcode rule). A failed check resolves a refusal and opens nothing.- What the person sees. Team Chat's add-emoji dialog opens with that one picture already in a row, named with the suggested shortcode. The person can rename it, remove it, or add other pictures too. Nothing uploads until they press Upload.
- It resolves when the dialog closes.
{ ok: true, outcome: 'added', shortcode }when the emoji was uploaded (the shortcode is the one the person confirmed, which may differ from the suggestion), or{ ok: true, outcome: 'dismissed' }when the dialog closed with nothing uploaded, the panel was hidden, or the plugin was reloaded. - Limits per plugin. Only one offer may be open at a time, and at most five may be made in a minute. Over either limit resolves a refusal without opening anything.
- Refusals are answers, not errors. An offer that was not shown resolves
{ ok: false, code, message }, wherecodeis one ofunsupported-type,too-large,invalid-image,invalid-shortcode,busy(an offer is already open),rate-limited(more than five in a minute) orteam-chat-unavailable(the person is signed out of Team Chat or has no workspace picked).messageis a plain sentence you can show the user. A call that is not from a panel on this computer is refused with an error instead. teamChat.listCustomEmoji()is read-only and takes no arguments. It resolves{ ok: true, workspaceName, emoji: [{ shortcode, imageUrl, animated }] }for the workspace Team Chat has active, sorted by shortcode and cut off at 200 entries (the per-workspace maximum), or{ ok: false, code: 'team-chat-unavailable', message }. It never returns who uploaded an emoji or where it is stored.teamChat.getCustomEmojiImage({ shortcode })is read-only. Team Chat reports the picture's address for that shortcode in the active workspace, and the main process downloads it itself: only from Omniscio's own storage host, no redirects, a 10-second deadline, PNG, GIF or WebP only, and at most 256 KB (checked on the declared length and again while reading). It resolves{ ok: true, base64, contentType, animated }(plain base64, so a panel canvas is never tainted), or a refusal:not-found(no emoji with that name),team-chat-unavailable(signed out, no workspace, or no answer within 10 seconds) orinvalid-image(the address was not Omniscio storage, or the download failed or broke a limit). The panel never receives or loads the address.- The matching button. When a plugin with the id
emoji-makeris installed and on, Team Chat shows a Make one button beside Add Emoji in the Custom emoji dialog and in the emoji picker's Custom section. It opens that plugin's panel. It never appears on a phone.
The promises behind this are in the Team Chat custom emoji contract (the offer door and Make one rules).
When the host refuses your arguments — branch on err.code
Every bridge call from a plugin's window whose arguments the host refuses rejects with an Error
carrying a machine-readable err.code, so a plugin branches on the code instead of matching the
English message (a plugin's background worker receives the message only, not the code):
VALIDATION_FAILED— an argument has the wrong shape or a value the method does not accept.MODEL_RETIRED— the call named a Claude model that has retired (for exampleclaude-haiku-4-5-20251001). The message names the model and says to pick another one. The host never swaps in a different model for you; show the user your own "pick another model" message.
A genuine host failure (not your arguments) carries INTERNAL or a network class instead — except
for the operating-system and share failures below, which have codes of their own so a plugin can tell
the person what actually went wrong instead of "please try again".
When the computer or the share service refuses — branch on err.code
These codes arrive the same way (err.code on the rejected call, in a plugin's window and on the web
relay alike). The message is already plain language: it never contains a file path, a user name or an
operating-system error name, so a plugin can show it or replace it with its own sentence.
err.code |
What happened | What a plugin can say |
|---|---|---|
DISK_FULL |
The disk (or the user's quota) has no room left to write. | "Your disk is full. Free some space and save again." |
NO_PERMISSION |
The operating system refused access to the folder or file. On Windows this also covers a file another program has locked. | "Omniscio isn't allowed to use that folder, or the file is open in another program." |
READ_ONLY |
The folder or drive is read-only. | "That location is read-only. Pick another folder." |
SHARE_SIGN_IN_REQUIRED |
Publishing a share needs the person to be signed in, and they are not. | "Sign in to Omniscio to share this." |
SHARE_TOO_LARGE |
The page is over the size a share can serve (the limit is stated in the message). | "This is too big to share. Make it smaller." |
Two things worth knowing:
FORBIDDENis notNO_PERMISSION.FORBIDDENmeans Omniscio itself refused the call (for example a path outside the folders the plugin was given).NO_PERMISSIONmeans Omniscio allowed it and the operating system said no.- The share limit in bytes is not a separate field. The message names the limit in megabytes; a plugin that needs the number should read it from there rather than expect a second field on the error.
Any other failure, including an operating-system error with no code of its own (a missing file, a
file in use), stays INTERNAL or its existing class. The set is additive: a plugin written before
these codes existed sees an unfamiliar code string and treats it as a generic failure.
A setting the user saved earlier never blocks a save: if a plugin update drops an option the user had already chosen, the settings screen still saves their other changes, and the old value stays until they pick a new one.
host.getCapabilities — ask what this Omniscio can actually do (no permission)
Returns the capability tokens this host currently offers plugins. It exists so a plugin can refuse to spend the user's money on something this host cannot deliver.
const capabilities = await Omniscio.host.getCapabilities()
if (!capabilities.includes('ai-native-cli')) {
// Don't open the paid AI door — it would spawn a session that can do nothing.
}
The failure it prevents. A plugin's "consult the AI" door spawns a real, paid
session whose only job is to drive that plugin's own registered CLI endpoints through
ALL /plugins/:id/cli/:path*. Before the guard existed, a plugin had no way to check the
door would actually work — if the host did not offer AI-native CLI dispatch, the session
would spawn, 404/409 on every call, edit nothing, and the user would have paid for an empty
result. Today the route is always-on (shipped 2026-08-06), but the guard still earns its
keep: a host may legitimately omit the token in a given deployment, and the plugin should
refuse the paid door rather than discover the gap by burning money.
Do NOT try to infer a capability by probing. A plugin can guess an offering from the
route's 404-vs-401 answer, but only from a worker via a raw loopback fetch that evades the
deliberate anti-SSRF guard on ctx.http, and only while the route happens to answer before
auth. A one-line reorder would silently invert the inference, and every user of that plugin
would quietly start paying for nothing. Ask the host instead.
Properties worth knowing:
- Read-only and free — no side effects, no model call, nothing billed.
- No permission required, because it reveals nothing a plugin could not learn by simply trying the capability.
- Tokens only, never settings. It returns values from a curated allow-list, so it can never become a general-purpose window into the user's configuration. Adding a raw setting here is the trap; add a token instead.
- Absence means "not offered", not "error". An empty array is the correct answer when nothing is on — do not treat it as a failure.
- The list is open-ended:
ai-native-cliabove,ai-engine-choice(AI picks, part 2), andplugin-session-restart-safe(a plugin session is never resumed or auto-continued by the app after a restart, so a plugin can rely on being the only thing that drives it),share-revoke-artifact(a plugin can take down a link it published, part 2),ai-images(only while plugin pictures are switched on —ai.generateImageabove), andopen-settings(only to a plugin screen on the desktop —host.openSettings()opens the calling plugin's own settings window, plugin-settings-panel.md). Check for the token you need. - Both surfaces answer it: the webview, and a worker's
ctx.hoston a current host.
Locked by invariant every-bridge-case-classified-or-denied in
plugin-bridge-hardening-contract.md,
plus host-handler.test.ts and the
dispatcher-level cases in plugin-bridge-handler.test.ts.
backend.invoke / ctx.rpc.handle — call your own backend and await a result (no permission)
Lets a plugin's webview UI call a method on its own v2 worker backend and await the return
value. It is the request/response counterpart to the fire-and-forget events bus: use
events.emit/events.on to notify (progress ticks, "a file changed"), and backend.invoke
when the UI needs an answer back (e.g. "scan this file → give me the candidates", "regenerate
→ tell me it worked"). This is what replaces hand-rolling a correlation-id dance over events.
// ── backend (v2 worker) — register the methods your UI may call, in activate() ──
export function activate(ctx) {
ctx.rpc.handle('scanFile', async ({ path }) => {
const candidates = await doScan(path) // your real work, on the sandboxed worker
return { candidates } // the return value crosses back to the UI
})
}
// ── webview UI — call it and await the result ──
const { candidates } = await Omniscio.backend.invoke('scanFile', { path: 'x.ahk' })
Properties worth knowing:
- No permission — self-gated to your OWN backend. A webview can only ever reach the backend
of the same plugin (enforced by the host's un-forgeable webContents→pluginId binding), so it
grants nothing the plugin does not already hold — like
host/decks, it needs no manifest permission. - v2 worker backend required. The plugin must declare
sdkVersion+backend.entryPoint. A UI-only plugin (or one whose worker isn't running yet) gets a clean error, never a hang. - Register in
activate(). Only methods registered viactx.rpc.handleare callable; invoking an unregistered method returns a clean "no handler" error. Handlers stay on the worker — the function never crosses the process boundary. - Never hangs. A throwing handler, a non-serializable return value, a missing backend, and a wedged handler (generous timeout) all resolve to a clean error; a per-plugin in-flight cap bounds a runaway UI; in-flight calls are drained if the worker stops.
- Long work is fine. The timeout is generous (a UI invoke can drive a real, multi-second
operation) — stream progress over
eventsand let the call resolve when the work is done.
Locked by invariant backend-namespace-is-self-gated in
plugin-bridge-hardening-contract.md
and backend-invoke-is-plugin-scoped in plugin-worker-backend-contract.md,
plus the backend namespace dispatcher cases in
plugin-bridge-handler.test.ts,
plugin-worker-host.test.ts, and
plugin-worker-entry-helpers.test.ts.
rpc.call / ctx.rpc.emit — one TYPED channel between a panel and its own background (no permission)
The same pair of doors as backend.invoke and events.emit above, declared once so a panel and
its own background are checked against the same shapes — the panel calls and awaits, the
background pushes and the panel subscribes:
// ── shared/rpc.js — imported by BOTH the panel and the backend ──
export const rpc = defineRpc({
methods: { scanFile: (arg) => ({ candidates: [] }) }, // panel → background, awaits a result
events: { progress: (payload) => {} } // background → panel, fire-and-forget
})
// ── backend ──
export async function activate(ctx) {
rpc.handle(ctx, { scanFile: async ({ path }) => ({ candidates: await doScan(path) }) })
await rpc.emit(ctx, 'progress', { done: 1, total: 10 })
}
// ── panel ──
const { candidates } = await rpc.call(Omniscio, 'scanFile', { path: 'x.ahk' })
const off = rpc.on(Omniscio, 'progress', (p) => setProgress(p))
defineRpc is in-tree at rpc.ts; it is types
plus a few lines of wiring, with no dependency to install.
Properties worth knowing:
- No permission — self-gated to your OWN backend and your own panel.
rpc.callcan only reach the worker of the plugin whose webview is calling, andctx.rpc.emitonly ever delivers to the emitting plugin's own panel (the same plugin-scoped delivery as the events bus). - One channel, one object. A method renamed, an argument added or a payload changed is ONE edit, and the panel and the background stop compiling together rather than failing at runtime.
- Registering is unchanged.
ctx.rpc.handle(method, fn)holds your handlers worker-side; the function never crosses the process boundary, andctx.rpc.removeHandler(method)drops one. - The panel side reads the wire name.
rpc.calldrivesOmniscio.rpc.call, and the background'srpc.emitisctx.rpc.emit; both appear in the published SDK types an author's editor reads, so neither is a name you have to guess.
The older doors, still supported (legacy)
Four ways a panel and its background have always talked; all of them keep working, and
defineRpc above is the typed form of the first two rather than a replacement for any of them:
Omniscio.backend.invoke+ctx.rpc.handle— panel → background, request/response. The older name ofrpc.call; same wire, same self-gating, no type checking between the two sides.ctx.events.emit+Omniscio.events.on— both directions, fire-and-forget.ctx.rpc.emitandrpc.onride exactly this bus, so a plugin may migrate one side at a time.ctx.sidebar.setItems/ctx.sidebar.setBadgeandctx.inbox.setItems— background → dashboard state. Deliberately specialised (Omniscio renders them), not replaced by the channel.ctx.inbox.onDismiss— dashboard → background. A plugin hears when the reader dismisses one of its own inbox rows ({ itemId, dismissed };dismissed: falseis the undo). It is declared in the SDKPluginInboxtype and not on the webviewOmniscio.inbox. An inbox item may carryquiet: true: it stays in the Inbox but is left out of the plugin's sidebar number and its popover.Omniscio.events.onSessionStatus+ctx.sessions.onStatusChange— session status subscriptions, with their own per-session keying and permission.
The system permission — approved programs, the clipboard and opening files (Tier-1 elevated)
Lets a plugin ask Omniscio to run a program, read and replace the clipboard, and open a file. It is Tier-1 elevated on the consent screen, because running a program is the widest power a plugin can hold.
The clipboard half is read AND write. clipboard.readText / readImage and
clipboard.writeText / writeImage all gate on this one permission, so a plugin that asks for it
can silently replace what the user copied. The consent copy says so: the row reads "read and
replace the clipboard" and the marketplace line reads "reads and replaces your clipboard".
Which road runs the program depends on where the call comes from. They are two different surfaces with two different guards, and neither is reachable from the other:
| The call comes from | The road | What guards it |
|---|---|---|
| the plugin's backend | ctx.process.exec / spawn / kill |
the plugin's allow-list or pinned programs, with general-purpose interpreters refused |
| the plugin's backend, inside a project | ctx.workspace.exec (or ctx.workspace.run) |
the workspace the user granted, plus the per-command block in Settings → Plugins |
| the plugin's webview UI | window.Omniscio.process.spawn |
the same allow-list or pinned programs as the backend |
- What the wording promises, it means. The consent row reads "Run approved programs through
this app's own launcher, read and replace the clipboard, and open files". It no longer claims full
user access, and it should not: the plugin's own backend is forked under Node's
--permissionmodel without--allow-child-process, so its ownchild_processis refused. - A backend that tries anyway gets a sentence, not a crash.
spawn,exec,execSync,execFile,execFileSyncandforkall throw "A plugin cannot start programs by itself" and namectx.process.spawn/ctx.process.execas the way to do it. ctx.processis the same launcher as the webview's.exec/spawn/killreach the one host launcher with the same checks; spawn output and exit come back asctx.process.onOutput/ctx.process.onExitevents. The working directory is always the plugin's data folder.- Pinned programs run only as pinned. A plugin can ship or download its own binary (FFmpeg,
say) and pin it in
process.pinnedProgramswith its SHA-256. Omniscio copies it to a folder the plugin cannot write, checks the fingerprint, and runs that read-only copy; a changed file, a path outside the plugin's folder (links included) and a name pinned only for another platform are refused before anything starts. The consent card lists each pinned program by name. - Worker threads stay.
--allow-workeris still granted forsystem, because a worker thread inherits the permission model (measured on Node 24.22.1: a worker under--allow-workeris still refused fs reads outside the allow-list andchild_process).--allow-addonsis not granted: no bundled plugin loads a native addon.
ctx.launch.open — open a link/file, or run a program the user confirms (launch, Tier-1 elevated)
Lets a worker plugin ask the host to open a url, open a document, or — with a native confirm
the plugin cannot bypass — run a program. The plugin never gets raw spawn: it REQUESTS a
launch and Omniscio (plus, for anything that runs code, the user) authorizes it. This is the
mediated substitute for raw process in ~90% of cases.
// open a link — http/https only, no confirm (reversible)
await ctx.launch.open({ kind: 'url', value: 'https://example.com' })
// open a document/folder with the OS default app — executables are refused (use kind:'exe')
await ctx.launch.open({ kind: 'path', value: 'C:\\Users\\me\\report.pdf' })
// run a program — ALWAYS pops a native "Run this?" the plugin can't skip or fake
const r = await ctx.launch.open({ kind: 'exe', value: 'C:\\tools\\app.exe' })
if (!r.ok) { /* user declined, headless context, or a bad target */ }
Properties worth knowing:
- Tier-1 elevated permission.
launchshows a stronger consent notice at install; without it everyctx.launch.*call is denied (fail-closed). - exe/cmd ALWAYS confirm, and the plugin cannot bypass it. There is no
confirmedparameter — the host decides fromkind, draws a native OS dialog, and runs only on a real Run click. A headless / no-window context (e.g. an AI-driven plugin CLI endpoint) fails closed and refuses. urlis http(s)-only;pathrefuses executables (Windows binaries/scripts, interpreted scripts like.py/.sh, and trailing-dot/space forms), so "open a file" can never silently run a program.- The launched program is credential-stripped — it never inherits Omniscio's Claude OAuth token
/
AMC_CLI_TOKEN, and every launch is spawn-audited. - Worker (v2) surface only for now — a plugin's webview does not yet get
ctx.launch.
Locked by plugin-launch-primitive-contract.md
(launch-open-gated-by-launch-permission … worker-never-spawns-launch-is-host-mediated) and plugin-launch-service.test.ts.
ctx.core.* — read the user's sessions, projects, and message text (coreRead, Tier-1 elevated)
Gives a worker plugin a blanket, read-only view of the user's own work: session and
project metadata, and the plain text of messages. Where sessionHistory (below) hands the
plugin a scoped slice the user picks project-by-project, ctx.core is the "I need to see
everything" capability — so it is a stronger, elevated permission and the plugin should
reach for it only when a per-session grant genuinely won't do.
// sessions — every non-hidden session, optionally scoped to one project
const all = await ctx.core.sessions.list()
const forProject = await ctx.core.sessions.list({ projectId })
const one = await ctx.core.sessions.get(sessionId) // null if unknown / hidden / deleted
// projects
const projects = await ctx.core.projects.list()
const proj = await ctx.core.projects.get(projectId)
// a session's messages — text-only, capped (default 200; a window can only shrink it)
const messages = await ctx.core.messages.list(sessionId) // { id, role, content, timestamp }[]
const recent = await ctx.core.messages.list(sessionId, 50)
- Tier-1 elevated permission (
coreRead). The consent copy is blunt — "read your sessions, projects, and the text of their messages (never their secrets)". Without the permission everyctx.core.*call is denied (fail-closed). - Blanket, not scoped — prefer
sessionHistorywhen you can. There is no per-session picker; the install-time consent IS the authorization. If your plugin can enumerate the handful of sessions it needs,sessionHistory(a lower-privilege, user-scoped grant) is the better fit; usecoreReadwhen you genuinely need the whole corpus. - Text-only.
messages.listreturns a{ id, role, content, timestamp }[]projection withcontentreduced to plain text andsystemrows dropped — raw tool-use / tool-result blocks (which can carry shell output, file contents, secrets) are never included. An AI message'scontentis its answer alone: no activity lines, so no command the AI ran. - Hidden + deleted are invisible. Silently-hidden recipe lanes are filtered from every list and refused for messages; soft-deleted rows never appear.
- Windowed.
messages.listcaps at 200 messages per call so a single read can't pull an unbounded transcript; a caller-supplied window only ever shrinks that. - Audited + read-only. Every read is appended to a host-owned audit table the plugin can't touch, and there is no write or raw-table path.
- Worker (v2) surface only for now — a plugin's webview does not yet get
ctx.core.
Locked by plugin-core-read-contract.md (C1–C7) and plugin-core-read-service.test.ts.
ctx.oauth.authorize — sign the user in to a third-party service (oauth, Tier-1 elevated)
Runs a standard OAuth 2.0 authorization-code flow so the user can connect a third-party
service (Notion, Slack, Spotify, anything) to your plugin, and your plugin gets the resulting
tokens. It is bring-your-own-credentials: you supply your OWN OAuth app; Omniscio never uses its
own Google or marketplace secrets. Omniscio owns only the parts that must not be plugin-controlled —
the loopback redirect, PKCE, and the CSRF state.
// you supply your own OAuth app; Omniscio owns the loopback redirect + PKCE + state
const res = await ctx.oauth.authorize({
authUrl: 'https://accounts.example.com/o/oauth2/auth', // provider authorize endpoint (https)
tokenUrl: 'https://oauth2.example.com/token', // provider token endpoint (https)
clientId: 'your-oauth-client-id',
clientSecret: 'your-oauth-client-secret', // optional (confidential clients only)
scopes: ['read', 'write'], // string[] or a space-delimited string
extraAuthParams: { access_type: 'offline', prompt: 'consent' } // optional provider params
})
if (res.ok) {
// { accessToken, refreshToken?, tokenType?, scope?, expiresIn?, expiresAt?, idToken? }
await ctx.secrets.set('provider-tokens', res.tokens) // persist in YOUR own encrypted storage
} else {
ctx.log.warn(`sign-in failed: ${res.error}`) // friendly message; never a raw provider error
}
- Tier-1 elevated permission (
oauth). The consent copy is "sign you in to third-party services you choose to connect". Without the permission the call is denied (fail-closed). - You bring the OAuth app. Omniscio opens the user's browser to YOUR
authUrl, catches the callback on an Omniscio-owned loopback (http://localhost:<random>/callback), and exchanges the code at YOURtokenUrl. The redirect URI is Omniscio-owned and ephemeral — you cannot supply or override it, andextraAuthParamscan never overrideclient_id/redirect_uri/response_type/code_challenge/code_challenge_method/state. - PKCE + state are mandatory on every flow (no opt-out), and the loopback constant-time-checks
the returned
statefor CSRF. - Any https provider, no internal addresses. Both
authUrlandtokenUrlmust be https; a token endpoint that resolves to localhost / a private / link-local address is refused (SSRF). - Tokens are yours to keep. They are returned to your worker only (never the renderer) and
Omniscio keeps no copy — persist them in your own
ctx.secrets(OS-keychain-backed). Refreshing later is your job: you hold therefreshToken,tokenUrl, andclientId. - One sign-in at a time per plugin, and an abandoned browser flow times out after 5 minutes with a friendly error.
- Worker (v2) surface only for now — a plugin's webview does not yet get
ctx.oauth.
Locked by plugin-oauth-primitive-contract.md
(authorize-gated-by-oauth-permission … no-host-side-token-cache) and plugin-oauth-service.test.ts.
ctx.channel.connect — keep a live connection to a service (channel, Tier-1 elevated)
Lets a worker plugin maintain a long-lived outbound WebSocket to a third-party service it
chooses (e.g. Slack's socket mode). Omniscio owns the whole socket lifecycle — reconnect, health
checks, backpressure — and your plugin just gets message callbacks plus a send() handle. The
plugin never touches a raw socket. This is what lets a real-time integration (a chat bridge, a
live event feed) ship as a plugin.
// Omniscio owns the socket; you get events + a { send, close } handle
const { send, close } = await ctx.channel.connect(
{
kind: 'ws', // outbound WebSocket (the only kind for now)
url: 'wss://gateway.example.com/socket', // wss:// only; internal addresses refused
headers: { Authorization: 'Bearer your-token' }, // optional; used for the handshake, stays Main-side
protocols: ['json'] // optional Sec-WebSocket-Protocol values
},
(event) => {
switch (event.type) {
case 'open': send(JSON.stringify({ type: 'hello' })); break // connected — start your protocol
case 'message': handleFrame(event.data); break // a text frame arrived
case 'close': ctx.log.info(`closed ${event.code}`); break // Omniscio will reconnect on its own
case 'error': ctx.log.warn(event.message); break // friendly message; Omniscio reconnects
}
}
)
await send('a text frame') // resolves { ok } / { ok:false, error } — send AFTER the open event
await close() // permanent teardown (no reconnect)
- Tier-1 elevated permission (
channel). The consent copy is "maintain a live connection to an external service you choose". Without it everyctx.channel.*call is denied (fail-closed). - Omniscio owns the socket — you never get a raw one.
connectresolves as soon as Omniscio accepts and starts the connection (not when it opens), and hands you only a{ send, close }handle. Omniscio reconnects with capped backoff, runs a ping/pong heartbeat that heals a silently-dead socket, and a generation guard keeps a superseded socket from interfering. - Outbound
wssonly; internal addresses refused. The scheme must bewss:; a url that is localhost / a private / loopback / link-local address is refused synchronously, and a hostname is DNS-pinned at connect (a name that resolves to an internal IP is refused too — no SSRF). Inboundkind: 'webhook'is not supported yet. - Everything is bounded. A per-plugin channel cap (and a global cap), a connect-rate limit,
an outbound send-rate limit + per-message size cap, and a reserved-header denylist.
sendreturns{ ok:false }(never a throw) when the socket is not open or a bound is hit. - The event stream is one callback.
onMessagereceives{ type: 'open' },{ type: 'message', data }(text frames; binary is dropped for now),{ type: 'close', code, reason }, and{ type: 'error', message }. Send after you seeopen. - Your credentials stay Main-side. Any
headersyou pass are used only for the Main-side handshake, never exposed to the renderer, and never logged. - A channel never outlives your plugin. Disabling the plugin (or a worker crash) closes every
channel it holds;
close()is permanent and idempotent. - Worker (v2) surface only for now — a plugin's webview does not yet get
ctx.channel.
Locked by plugin-channel-primitive-contract.md (C1–C10) and plugin-channel-service.test.ts.
ctx.recording.* — start and stop screen recordings the user confirms (recording, Tier-1 elevated)
Lets a worker plugin trigger a screen recording through Omniscio's own screen recorder. Your plugin can start a recording (the user confirms each one), stop it, and read the status of the recordings it started — but it never touches the raw capture, the screen frames, or the media files. The recording lands in the user's normal recorder library, owned by them. This is what lets a "record my demo / session" plugin work without ever handing a plugin the user's screen.
// Every start pops a native "Record your screen?" confirm the plugin cannot bypass
const started = await ctx.recording.start()
if (!started.ok) return ctx.log.warn(started.error) // declined / recorder off / already busy
const { recordingId } = started
// ...later, stop the recording YOU started (only while it is the active one)
await ctx.recording.stop(recordingId) // { ok } / { ok:false, error }
// poll status / enumerate — only the recordings YOUR plugin started, redacted
const rec = await ctx.recording.get(recordingId) // { id, status, durationMs, ... } | null
const mine = await ctx.recording.list() // RecordingSummary[]
- Tier-1 elevated permission (
recording). The consent copy is "start and stop screen recordings, with your confirmation each time". Without it everyctx.recording.*call is denied (fail-closed). - Omniscio owns the capture — you never get frames or files.
start()runs Omniscio's existing screen recorder; you receive only arecordingIdand redacted status summaries, never a capture buffer, a file path, the share token, or the transcript. - Every start needs a fresh user confirm. A spoof-proof native dialog the plugin cannot script or auto-dismiss; a headless context (e.g. a plugin CLI endpoint) starts nothing. The plugin does not choose the source — Omniscio records the user's default screen.
- You can only touch your own recordings.
stop/list/getare scoped to the recordings your plugin started; you can never stop or read the user's own or another plugin's recording, andstopworks only while your recording is the active one. - Single recorder, bounded.
start()refuses when screen recording is turned off or a recording is already in progress; one confirm shows at a time, and a per-plugin rate limit caps repeated starts. Every failure is a friendly{ ok:false, error }, never a throw. RecordingSummaryis redacted —{ id, status, durationMs, sourceType, sourceLabel, startedAt, endedAt }only.- Ownership does not survive a restart. After Omniscio restarts, a plugin can't manage a recording it started earlier (it can always start a new one); the recording itself stays in the user's recorder library.
- Worker (v2) surface only for now — a plugin's webview does not yet get
ctx.recording.
Locked by plugin-recording-primitive-contract.md (R1–R10) and plugin-recording-service.test.ts.
AgentMC.auth.getWebAuth — sign a plugin panel in as the person (auth.actAsUser, Tier-1 elevated)
Hands a plugin's webview the same Firebase web config Team Chat uses plus a custom token minted
server-side for the signed-in person's own uid, so the panel can signInWithCustomToken and use the
Firebase Web SDK without running its own sign-in flow.
const { config, customToken, organizationId } = await AgentMC.auth.getWebAuth()
// firebase.initializeApp(config); await signInWithCustomToken(auth, customToken)
- Its own elevated permission (
auth.actAsUser), never implied byauth.auth(Identity) promises only "see who is signed in (your name and email)". Inside the shared project the token carries no narrower scope: whoever holds it is the person, against every Firestore rule there, for as long as the sign-in lives. The consent screen therefore asks for full account access in its own row, and a plugin that declares onlyauthis refused withauth.actAsUser permission required for auth namespace. The Team Chat write opt-in (allowAgentTokenTeamChat), agent attribution and the guest channel scope do not apply to writes made with this token — they read as the person's own. - A plugin's token never reaches Omniscio's own backend services. The plugin bridge asks the
teamChatTokenrelay for the plugin audience, and the relay stamps the token with theamcPluginScopeclaim (valueteam-chat). Every sign-in made with it carries that claim, and the shared amc-back verifier (amc-back/packages/core/firebase-verifier.ts) refuses any token that has it, so Mission Control and the other amc-back services never accept a plugin as the person. The relay also keeps the claim when a plugin-scoped sign-in asks it for a fresh token, so a plugin cannot trade its token for an unscoped one. Plugin tokens are cached apart from the native Team Chat token and never share a cache entry. On its first load after this change, each plugin webview deletes the Firebase sign-in it saved before (thefirebaseLocalStorageDbdatabase and anyfirebase:authUser:localStorage entry), once per storage partition, so the next sign-in is a fresh scoped one. The Cordial back end (amc-back/apps/cordial-back) keeps its own verifier and still accepts a plugin token, because the Cordial plugin signs in this way. - The in-app Team Chat panel is unaffected. The app's own renderer reaches the same mint through
IPC (
team-chat:get-web-auth), not through the plugin bridge, and keeps minting the unscoped token. - No secret crosses the bridge. The web API key and config are public by design; Security Rules
are the trust boundary. The mint itself is the
teamChatTokenrelay, which verifies the caller's ID token and issues a token for that uid only.
Locked by plugin-bridge-handler.test.ts (the
auth namespace cases: a plugin holding auth alone is refused and no token is minted, and a
granted plugin mints through the plugin-scoped path),
plugin-capability-registry.test.ts
(the catalog gate plus the golden matrix), and the plugin scope tests:
team-chat-web-auth-handler.test.ts,
token-relay-plugin-scope.test.ts,
plugin-scope-claim-parity.test.ts and
plugin-sign-in-scope-preload.test.ts.
Related
- Plugin Bridge Capabilities (part 2) — the data, file and output capabilities.
- Plugin Bridge Capabilities (part 3) — the session capabilities: spawning and driving a session, granted past history, and the live feeds.
- Plugin access to boards and tasks — the boards and task lists a person picks, the changes that ask first, and how to take access back
- Plugin Marketplace — installing plugins, the permission-consent UX, the developer dashboard
- Plugin CLI Discovery — how a session discovers + drives installed plugins
- Plugin Run Keep-Alive — how a plugin keeps its screen alive while long work runs in it (
runs.start/runs.heartbeat/runs.finish), and what the user is told when that screen dies anyway - AI spend alerts — the built-in daily spend digest whose numbers
spend.getBreakdownreconciles with - Authoritative sources: bridge method schemas · permission catalog · SpendReportBreakdown shape
Last verified 2026-11-09