The plugin host API
A plugin reaches buddi through one object, ctx.buddi. This page is the
design behind it: what it holds, what a plugin must declare to get more, what
the boundary really is, and how it is versioned. The method-by-method reference
is plugins.md §1.1 and §9b.
1. The problem it answers
Section titled “1. The problem it answers”A plugin could once reach core by three roads: the fields of ToolContext
(and its cousins SourceContext, SentinelContext and the page query
context), any function @buddi/core happened to export, and plain SQL
against core.* tables through the one shared pool. Only the first was
designed. The other two are where the risk sits: a plugin that can call
createVault can read every secret on the machine, buddi’s own keys included,
and one that reads core.events, core.actions and core.approvals decides
for itself whether the owner already said yes.
“Whatever core exports” is not a contract a plugin author can rely on or an
owner can read at install, and owner secrets
(owner-secrets.md) cannot be built on a vault any plugin
can open. So plugins get one stable surface, ctx.buddi, and nothing else.
2. What each plugin uses
Section titled “2. What each plugin uses”Every plugin in both repositories is on the host. The areas each one declares (§5) are the whole of its reach beyond its own schema and directory:
| Plugin | Repository | uses |
|---|---|---|
| template | buddi-plugins | none |
| memory | buddi | none |
| finance | buddi-plugins | files:library |
| artifacts | buddi | files:library |
| web | buddi | http |
| weather (example) | buddi | http |
| weather | buddi-plugins | http, owner:notify, owner:places |
| calendar | buddi-plugins | http, secrets |
| browser | buddi | files, secrets |
| host | buddi | files:library |
| image | buddi-plugins | accounts, files:library |
| speech | buddi-plugins | accounts, files:library |
| developer | buddi-plugins | files, secrets |
| buddi | files, proposals, schedule, secrets, owner:channel, owner:notify |
The families registered in the gateway (goal, learning, schedule, reminders, platform, canvas) are core’s own surfaces over core’s rows, not plugins, and do not go through the host.
3. The shape
Section titled “3. The shape”ctx.buddi is the host; the rest of ToolContext is the call. Facts about
this one call stay on the context (agentId, conversationId,
toolUseId, provenance, signal, actionId, choices,
approvedEffect, suspend, ownerRequest, sessionTools,
delegationDepth, group, surface, nativeSearch, jobId). Everything
the plugin reaches beyond its arguments is under ctx.buddi. The same
object is on SourceContext, SentinelContext and the query context, so a
source and a tool see one host.
Core builds one ctx.buddi per plugin at register(), bound to the
plugin’s name, schema and declared areas. Pure helpers and types
(localDateString, sha256Of, pageFile, QueryRefusal,
parseViewDescriptors, checkUrl, the manifest types) live in a separate
entry point, @buddi/core/plugin, which holds nothing with state or I/O.
One pure module sits beside it rather than in it, so the entry stays lean:
@buddi/core/sheet, the sheet engine (docs/files.md, “Composed workbooks”),
whose formula library loads only when a formula is computed.
Core itself runs plugins on CoreToolContext, CoreSourceContext and
CoreSentinelContext, which /plugin never exports; tests import
@buddi/core/testing.
A manifest may carry a register({ version, plugin, dir, channels? }) hook. It runs once
at register(), for a plugin that fixes something before any context exists;
dir.legacyPath names <data>/<plugin>, which browser and host used before
the host gave them a directory.
4. The areas
Section titled “4. The areas”Seven are always present because they reach nothing beyond the plugin
itself. Nine must be declared (§5), and one member of an always-present
area, owner.notify, must be declared too.
4.1 Always present
Section titled “4.1 Always present”interface BuddiHost { readonly version: string; // '1.19'; see §7 readonly plugin: string; // this plugin's name log(line: string): void; // operational log, scrubbed (owner-secrets §5) owner: OwnerArea; clock: ClockArea; db: DbArea; dir: DirArea; approvals: ApprovalsArea; pages: PagesArea; tools: ToolsArea; network: NetworkArea; http?: HttpArea; accounts?: AccountsArea; files?: FilesArea; memory?: MemoryArea; proposals?: ProposalsArea; schedule?: ScheduleArea; secrets?: SecretsArea; channels?: ChannelsArea; plugins?: PluginsArea; // 1.18, with `requires`; 1.27, or `optional` assets?: AssetsArea; // 1.27 onnx?: OnnxArea; models?: ModelsArea; // 1.32, both with `onnx`}owner. id: string, timezone: string, agentForRole(role): string | undefined, hasAgent(id): boolean (1.1), protectedPaths: readonly string[], language(): Promise<string | undefined> (1.5: the profile’s
“Answer me in” as a tag like fr or pt-BR, undefined when blank or not
a language), formats(): Promise<{ time, date }> (1.19: the profile’s time
format, 12h, 24h or null for Auto, and date format, short, long,
iso or null), notify(message) (1.2) when the plugin declares
owner:notify, and places() (1.18) when it declares owner:places: the
owner’s Home, Work and named places from Settings → Profile, each { id, label, address, name, latitude, longitude, timezone }, read-only, in the
owner’s order. Never returns an agent’s file, grant or provider.
clock. now(): Date, today(): string (the owner’s local date).
db. query<R>(sql, params?) and transaction<T>(fn: (tx) => Promise<T>): Promise<T>; both answer rowCount beside rows. query is one
statement on the shared pool and sets no search_path, so a plugin names its
tables with its schema; transaction puts the plugin’s schema first on the
search_path. §6 says what enforces the scope. Never a raw Pool, so a
plugin cannot connect() and change role.
dir. path: string: <data>/plugins-data/<plugin>, created on first
use. Never the data directory itself, where the file vault and the Files
library live.
approvals. configuredForRun(tool): Promise<boolean> (1.33: whether
the plugin a mission run was started from vouches for one of this plugin’s
own tools in that run, below), assert(ctx, envelope): void (the approved-effect check),
standing(tool): Promise<ToolPermission | null> (for this plugin’s own tools
only), and approvedInConversation(tool, conversationId): Promise<boolean>
(whether the owner already approved this tool in this conversation, own tools
only), and decisionsInConversation(tool, conversationId): Promise<{ envelope, state, choices? }[]> (1.4: every card on that tool in this
conversation, so a tool that asks once per subject knows a yes from a no).
Never another plugin’s actions.
pages. previewPort(): number | undefined, previewUrl(name): string | undefined. Page descriptors and queries stay in the manifest; this is only
what a query or a tool asks of the host.
tools. (1.6) register(definitions: ToolDefinition[]): void,
unregister(names: string[]): void, registered(): string[]. Tools added
and removed while buddi runs, for a plugin whose tools are not known at boot:
a connection the owner makes at 3pm brings its tools without a restart
(Connections, the MCP client). Names must be in the plugin’s own namespace
(<plugin>.<what>); the registry applies the checks a manifest’s tools get
(name shape, tier and tierFor, untrusted, the input schema, no name twice),
and a batch is all or nothing. A plugin removes only what it added this way,
never a manifest tool and never another plugin’s. After a change the gateway
reloads the agent catalog, so every agent’s tools: grant is resolved again
before its next turn: mcp.github.* covers a tool added after the agent
loaded. Also on the register hook’s host. A tool may describe its input with
a JSON Schema (inputSchema) instead of zod, validated with Ajv and
canonicalised into the approval envelope the same way (plugins.md §9).
network. (1.7) declare(uses: { host, why }[]): void,
undeclare(hosts: string[]): void, declared(): { host, why, runtime }[].
The manifest’s network is fixed at register(); a plugin that learns where
it talks while buddi runs declares those hosts here. They join the manifest’s
in the one list the http area checks a request against, and the Plugins page
lists them under what leaves the machine from that moment: Connections
declares each connected service’s host when the connection is made and takes
it back on disconnect. A host is a name or *.name, with a one-line why;
undeclare removes only what declare added. Also on the register hook’s
host.
4.2 Declared
Section titled “4.2 Declared”owner:places. ctx.buddi.owner.places(): Promise<OwnerPlace[]> (1.18).
The owner’s places live in core (core.owner_places), written only from
Settings → Profile; a plugin reads them and never writes them. The card says
“reads your places (Home, Work…) and their addresses”. The weather plugin is
the first reader: it offers them as its locations, and its own Home and Work
were moved into core once, at the first start of 1.18 (the one time core
reads a plugin’s table, recorded in core.owner_place_imports so it never
runs again).
assets. (1.27) put(key, bytes, mime): Promise<{ key, bytes, updatedAt }>,
delete(key): Promise<boolean>, list(). Small images the plugin fetched —
an outlet’s logo — kept by core and served by buddi, so a page or a widget
draws them without the dashboard ever reaching the host they came from. put
takes PNG, JPEG, GIF (its first frame) or ICO, at most 256 KB; SVG is refused
because it can carry script, and WebP for now because no pure-JavaScript
decoder here reads it. Core decodes the bytes and writes PNGs it drew itself,
64 and 128 pixels square with the picture fitted and centred, under
<data>/plugin-assets/<plugin>/ — core’s directory, not the plugin’s dir.
Only those files are served, at /api/plugin-assets/<plugin>/<key>
(?size=64 for the small one), behind the dashboard session like every
other read, as image/png with nosniff, default-src 'none'; sandbox and a
day’s private cache. A key is lower case, digits, ., _ and -, at most
96 characters. 20 MB per plugin; everything is removed with the plugin. The
decoding is the gateway’s (pngjs, jpeg-js, omggif, an ICO reader), handed to
core as configurePluginHost({ images }) the way the HTTP transport is; a
process without it refuses put in a sentence. An export’s read-only host
keeps only list. The card says “keeps small images it fetched, like logos”.
onnx. (1.32) The one engine plugins run local models on, and the models
they share. A plugin that runs an ONNX model (speech’s Whisper through
@huggingface/transformers, news’s embeddings) used to carry
onnxruntime-node itself: about 208 MB per plugin, because that npm package
bundles every platform. With uses: ['onnx'] it carries none; buddi fetches
the engine when it is first needed, for this platform only, like a model.
interface OnnxArea { state(): Promise<OnnxRuntimeState>; // { state: 'absent'|'downloading'|'ready'|'failed', version, sizeBytes, downloadBytes, platform, available, reason?, receivedBytes?, pending? } ensure(req: { reason: string; model?: { name?, bytes?, id?, files? } }): Promise<OnnxRuntimeState>; createSession(modelPath: string, opts?: { threads?: number; idleUnloadMs?: number }): Promise<OnnxSession>;}interface OnnxSession { run(feeds: Record<string, OnnxTensor>): Promise<Record<string, OnnxTensor>>; // { type, data, dims } names(): Promise<{ inputs: string[]; outputs: string[] }>; readonly loaded: boolean; close(): Promise<void>;}interface ModelsArea { state(id: string): Promise<ModelState>; // { id, state, sizeBytes, path?, reason?, receivedBytes?, pending? } ensure(req: { id: string; files: { url, sha256, bytes, name? }[]; reason: string; name?: string }): Promise<ModelState>;}Where it comes from. The onnxruntime-node tarball on the npm registry,
because it is the only place Microsoft publishes the small N-API binding
(onnxruntime_binding.node) next to the library it links; the GitHub
release archives (onnxruntime-<os>-<arch>-<ver>.tgz) carry the C library
and no binding. The tarball holds every platform, so buddi downloads it once,
checks its sha256, and extracts only this platform’s two files, each checked
against its own pin; the rest is never written. Pins live in
packages/core/src/runtimes/pins.ts:
| Platform | Version | Download | On disk |
|---|---|---|---|
| macOS arm64 | 1.30.0 | 114 MB | 45 MB |
| macOS x64 | — | not available on this platform (for now) | |
| Linux x64 | 1.30.0 | 114 MB | 46 MB |
| Linux arm64 | 1.30.0 | 114 MB | 26 MB |
| Windows | — | not available on this platform |
1.30.0 is the newest stable. Microsoft stopped building macOS x64 at 1.24
(npm and GitHub alike); 1.23.2, the last build that has it, is left out until
its library’s install name has been checked on an Intel Mac, so an Intel Mac
reads “not available on this platform”. buddi talks to the binding directly
(runtimes/native.ts), with a tensor class of its own, so neither
onnxruntime-node nor onnxruntime-common is in the install. The binding is
opened in a worker thread the engine owns, and every session loads and runs
there: its run is synchronous, and a batch must never hold the event loop.
On disk. <data>/runtimes/onnx/<version>/<platform>-<arch>/: the binding,
the library, and .verified.json. Everything is written under a .tmp-*
name in the folder it ends up in; the sha256 and length are checked while the
bytes arrive; the folder is renamed into place only once every file matched;
a download that dies deletes what it wrote, and one a dead process left is
swept by the next. Before the binding is opened, each file is hashed again.
Nothing downloaded runs before its hash matched.
The states. absent (no folder), downloading (in this process, with
receivedBytes), ready, failed with the reason. A failed download or a
failed load is kept in <platform>-<arch>.failed.json and never retried by
itself, across restarts too; Remove in Settings → System clears it. Windows
answers failed with available: false and “The engine is not available on
this platform (win32-x64).”
Consent. ensure answers at once. When the engine (or the model it names)
is missing it raises one card and answers pending with its id; nothing is
fetched before the owner approves. The card covers the engine and the
plugin’s first model together: ensure({ reason: 'to transcribe your voice notes', model: { name: 'Whisper base model', bytes: 135_000_000 } }) asks
“Download the Whisper base model (135 MB) and the engine that runs it
(114 MB)?”. While a card is pending, asking again — from the same plugin, or
another that needs only the engine — answers the same card. Once the engine
is ready, a later plugin’s ensure raises nothing for a model it fetches
itself. Approving runs core’s ownerOnly runtimes.download, which starts the
download(s); the plugin polls state().
Sessions. createSession(modelPath) opens a model in the plugin’s dir or
in the shared models, never elsewhere (links followed). Every session shares
the process’s one loaded binding. A session loads its model on its first
run, with threads intra-op threads (default 2, clamped to half the cores,
at most 8) and one inter-op thread, runs one call at a time, and unloads after
idleUnloadMs without a run (default five minutes, 0 keeps it); the next
run loads it again. run takes and answers plain { type, data, dims }
tensors; the binding’s run is synchronous, so a long inference holds the
event loop as it did in each plugin. No tokenizer helper: a plugin keeps its
own.
Shared models. models.ensure({ id, files, reason, name? }): one folder,
<data>/models/<id>/, per id across plugins, downloaded once under the same
rules and the same single card. Files are https, pass checkUrl, carry
their sha256 and length, and may redirect (a CDN) — the bytes are checked
either way. An id already kept with other files is refused rather than
replaced. state(id).path is the folder once it is ready. onnx.ensure
also takes model: { id, files } to put a shared model on the engine’s card.
Plugins keep their own download code until they move here.
An export’s read-only host keeps onnx.state and models.state only. The
card says “runs local models on buddi’s engine, downloaded only when you
agree”.
plugins (with requires, not a uses area). ctx.buddi.plugins.call(name, exportName, args) (1.18) calls a named read-only export of a plugin this one
requires. Core enforces every edge of it: the target must be in the
manifest’s requires, loaded, at a version in the range, and export that
name; args pass the export’s own zod params; the export runs with the
target’s own host over the read-only pool (a write fails as a page query’s
does), and of that host only the parts that read: owner facts and places,
the clock, db, dir, approvals, pages, http for GET and HEAD,
network.declared, tools.registered, files.get|read|list,
accounts.list, memory.recall, secrets.list and plugins.call. Anything
else — schedule, owner.notify, proposals, channels, registering a tool
or a host, a POST — throws a PluginCallRefusal. It runs within five seconds,
and is open alike from a tool, a page, a widget and the background: a source,
a watcher and a sentinel run under the same binding the registry made. A refusal is a PluginCallRefusal naming why. No
tool is ever reachable this way, and no schema but the target’s own.
Since 1.27 a manifest may also name plugins it uses only when they are there,
as optional: { speech: '^0.1.3' } (and buddi.optional in package.json,
compared at load like requires). Nothing is held back without one; the
plugins area exists, plugins.has(name) answers whether a plugin named in
requires or optional is loaded now at a version in the range (false for any
other name), and plugins.call reaches its exports while it is. Core has one
call of its own on the same road: a mission’s context (§7, 1.27), read
before the run with the target’s read-only host.
owner:notify. ctx.buddi.owner.notify({ urgency, title, text?, link?, dedupeKey?, agentId?, action? }): Promise<{ id }> tells the owner something
(notifications.md). The kind is always plugin and the
plugin’s name is on the row. A plugin picks an urgency (now, today,
digest), never a channel: the owner’s settings pick that, so a plugin
cannot send anything through a channel the owner did not choose. Offers and
approval cards are core’s and do not pass through. A dedupeKey collapses
only with the plugin’s own messages. action (1.24, at most 80 characters)
is what the owner is asked to do; with it the message needs the owner and
sits in Needs you, without it the message is information.
owner:channel. ctx.buddi.channels.register({ kind, describe(buddi), can, deliver(message, buddi) }): () => void (1.3) adds a way to reach the
owner that the plugin carries, kind <plugin>.<what>, listed in Settings →
Notifications beside Telegram and the system notification
(notifications.md). The area is also on the register
hook’s host, which is where a channel is normally registered. Core calls
describe and deliver from its routing, outside any context, so each is
handed the plugin’s host built over the pool the composition root gave
(configurePluginHost({ db })); a process that gave none has no plugin
channels. describe answers { label, where? }, or null when there is
nothing to carry a message now (no account), and the channel is then neither
listed nor picked. deliver gets the stored message: title, text, link: { route, url? } (url only with a public origin), offers as labels; never an
approval’s action id or an offer’s prompt. It answers { id } or { refused: sentence }, kept on the notification. A plugin’s channel is never the default
over core’s, and the owner still picks where each kind goes: the plugin
carries, it never routes. The email plugin’s mail to yourself is the first
(email.md).
http. request(req: HttpRequest): Promise<HttpResponse> on the shared
transport. Every plugin’s requests pass the address guard: checkUrl in front
and guardedLookup as the socket’s resolver, so this machine, its network and
ports other than 80 and 443 are refused, and a public name that answers with a
private address is refused where it is dialled. Redirects are not followed. A
request to a host not in the manifest’s network is logged with the plugin’s
name, and will be refused once every plugin declares its hosts. It is also
where an owner secret bound to a header is inserted (owner-secrets §3), so a
plugin that wants a token never holds it. Since 1.9 a secret may be the whole
address instead (auth: { secret, as: 'url' }, kind http.url): a private
link whose credential is its path, like a calendar’s ICS address. The request
names only the host; core fetches the stored address once it is HTTPS on that
host and passes the address rules, GET only. Its binding’s target is { plugin, host }, the plugin filled in by the area, so only the plugin that
stored the link can fetch it; secrets.put accepts that one core kind from a
plugin that declares http. Since 1.26 a secret may be a sign-in’s password
(auth: { secret, as: 'basic', username }, kind http.basic): core builds
Authorization: Basic base64(username:password) after the address checks,
for a CalDAV or WebDAV account. HTTPS; GET, HEAD, OPTIONS, PROPFIND, REPORT,
PUT and DELETE only; a body of at most 256 KiB; an answer capped at 10 MB
whatever maxBytes asks; 120 requests a minute per secret. Its binding’s
target is { plugin, host }, the host exact or *. a domain of at least two
labels (*.icloud.com, where an account’s calendars live on a numbered host
found at discovery), the plugin filled in by the area; secrets.put accepts
it from a plugin that declares http. The plugin keeps the user name; it
never holds the password. Since 1.28 a secret may be an OAuth sign-in
core made for the plugin (auth: { secret, as: 'bearer' }, kind
http.bearer, written only by secrets.signIn): core inserts Authorization: Bearer <access token>, refreshing the token at the provider that issued it
when it expires within five minutes, and once more — then sending again —
when the answer is 401. HTTPS; GET, HEAD, POST, PUT, PATCH and DELETE; a body
of at most 256 KiB; an answer capped at 10 MB; 300 requests a minute per
secret. A provider that refuses the refresh (revoked, expired) marks the
sign-in out, and every request with it throws SignInExpiredError (code: 'sign-in-expired') without asking the provider again until the owner signs
in anew. checkUrl lives in
@buddi/core/plugin; guardedLookup lives in core but not in /plugin, and
the gateway hands it to browser’s proxy.
accounts. list(): ProviderAccountListing[], resolve(id, model, signal?): Promise<ResolvedProvider>, generateCodexImage(id, { prompt, references, size?, model?, signal? }): Promise<{ bytes, mime, revisedPrompt? }>
(1.8), and withCodexProfile(id, use, signal?), deprecated since 1.8 and kept
for compatibility. generateCodexImage is one picture from a ChatGPT
subscription: the gateway sends a Responses request to the Codex backend whose
one tool is the hosted image_generation (forced by tool_choice, or auto
with an instruction when the backend refuses that) and reads the
image_generation_call item’s base64 result off the stream, under the
account’s lock and refresh, so the token never reaches the plugin.
resolve, generateCodexImage and withCodexProfile are refused for an
account the owner has not bound to this plugin; the binding is what the owner picks on the plugin’s
settings page, written through accounts.bind(id) from an ownerOnly tool.
list never returns a key; since 1.30 each account carries capabilities
({ audioIn, audioOut, source }, §7).
files. The Files library.
interface FilesArea { save(input: { bytes: Buffer; mime: string; filename?: string; caption?: string; source?: ArtifactSource; version?: { base: string; ext: string } }): Promise<FileRow & { existed?: boolean; version?: number }>; get(id: string): Promise<FileRow | null>; read(id: string): Promise<Buffer>; list(opts?: { since?: Date; before?: Date; kind?: string; sha256?: string; surface?: string; limit?: number }): Promise<FileRow[]>;}createdBy and the data directory are filled in by core. Bytes already in
Files come back as the file that held them, with existed: true; nothing new
is written. version (1.25) names a document by its title: the save is the
next version of the conversation’s file named base.ext (ignoring case), or
a new file, resolved and saved under one lock so two writes at once never
make two files. Since 1.34 every FileRow says its fileId and version
(and createdBy, the version’s author), and stored names carry no version
mark (before 1.34 a second version was named base (v2).ext; a download
still is). FileRow has no
storagePath, and says its conversationId only when that conversation
exists. Scope: a plugin sees files it saved and files handed into a
conversation its tool is running in. A manifest that declares
files:library sees every file, and the install card says so in those
words; a personal assistant that reads everything should say so. Files saved
before the host existed are attributed to the plugin their
provenance names.
memory. recall(query, opts?): Promise<MemoryNote[]> and
note(text, opts?): Promise<{ id }>, both as the calling agent and under
the same scope rules as memory.recall and memory.note. It is a type only:
no plugin reads memory from the outside, and the area exists so the first one
does not reach into the memory schema. When it is provided, it is the
memory plugin that provides it, through a port the composition root wires, so
core still imports no plugin.
proposals. proposePolicy(ctx, input): Promise<CreateProposalResult>
and countOpen(): Promise<number>. Core’s policy proposal with the plugin’s
name filled in (learning.md §2), and the open count email’s
Settings page shows. proposePolicy takes a nullable call and a within
transaction, and a policy handler’s context carries the plugin’s host. Never
another plugin’s proposals.
Since 1.14 a plugin may also keep a rule itself, where its own rule allows
it without asking (learning.md §4): proposePolicy(ctx, input, tx, { announce: false }), write the rule in the same transaction,
then keepItself(id, tx), recorded as decided by auto. trackRecord(kind)
is the owner’s record with this plugin’s rules of one kind (owner keeps
since their last discard, and whether that reaches five), listOpen() its
open cards, and takeBack(id) turns a kept one into the owner’s discard (an
Undo on the plugin’s page).
schedule. enqueueRun(input) and remindersFor(key: { contextKey: string; values: string[] }, days: string[]): Promise<{ value: string; day: string }[]> (which of these values already has a reminder on these days).
Never a reminder’s text or another plugin’s jobs.
secrets. The owner’s secrets, used and never read by tools:
registerDestination, use(name, kind, target), list, put, rename,
rebind, delete. list returns names and bindings that point at this
plugin’s destinations, never values; put is for an ownerOnly tool storing
an account credential the owner typed. Since 1.28, with http declared,
signIn, signInStatus, signInFinish and signInCancel run an OAuth
sign-in to one of core’s providers (OAUTH_PROVIDERS in
@buddi/core/plugin; Google today) on the plugin’s behalf: PKCE and a state,
core listening on a loopback port (http://127.0.0.1:<port>/) while the
sign-in waits, ten minutes at most, and the address the browser ended on
pasted back when the owner’s browser is on another computer. The tokens are
written by core as the owner secret the plugin names, bound to http.bearer
for that plugin and one of the provider’s API hosts; the plugin sees a state,
never a token. The calendar plugin’s Google accounts are the first:
const started = await ctx.buddi!.secrets!.signIn!({ provider: 'google', clientId, clientSecret, // a Desktop client's secret is not confidential scopes: ['https://www.googleapis.com/auth/calendar.events'], secret: 'Calendar sign-in: Google', host: 'www.googleapis.com',});// show started.authorizeUrl as a link; laterawait ctx.buddi!.secrets!.signInStatus!(started.id); // { state: 'signed-in', scopes }await ctx.buddi!.http!.request({ url: 'https://www.googleapis.com/calendar/v3/users/me/calendarList', auth: { secret: 'Calendar sign-in: Google', as: 'bearer' } });A plugin that delivers secrets declares destinations in its manifest:
{ kind, checkTarget(target, bound), describe(target), deliver(value, target, ctx), maxRule }. Core looks up the binding, calls checkTarget,
runs the approval rule, reads the vault and calls deliver. deliver is
the only code that ever receives a value, and only for a binding that names
its own kind. There is no get, and createVault is not reachable from a
plugin. A use of a <plugin>.account kind is recorded held: the plugin’s
connection keeps the value for as long as it lives (email’s mailbox
password), the one stated exception to “never held”. The product is
owner-secrets.md.
5. Permissions
Section titled “5. Permissions”The manifest carries uses: ('http' | 'accounts' | 'files' | 'files:library' | 'memory' | 'proposals' | 'schedule' | 'secrets' | 'owner:notify' | 'owner:channel' | 'owner:places' | 'assets' | 'onnx')[]. Because the staged
install screen may not import anything, the same list goes in
package.json as buddi.uses; at load the two must match or the plugin
does not register, as network is compared with buddi.md.
The owner sees the list at install, beside the tools, the schema, the
timers and the hosts, one plain line each: “sends web requests”, “uses a
model account you pick”, “reads every file in your Files library”,
“reads and writes memory as the agent that calls it”, “proposes rules”,
“starts agent runs by itself”, “fills secrets you bind to it”, “can send
you messages when you are away”, “adds a way for buddi to reach you”, “reads
your places (Home, Work…) and their addresses”, “keeps small images it
fetched, like logos”, “runs local models on buddi’s engine, downloaded only
when you agree”. An area
not declared is absent from ctx.buddi, so a call to it is a type error
and, at runtime, undefined. Adding an area in an upgrade is shown as a
change on the upgrade card.
6. Scope and the trust boundary
Section titled “6. Scope and the trust boundary”Scope. In every area a plugin sees its own data: its schema, its
directory, files it saved, its tools’ approvals, its proposals, secrets
bound to its destinations, accounts bound to it. More only when the owner
binds it (a secret, an account) or the manifest declares it and the owner
accepted (files:library).
In db, scope is a rule, not a grant. Each plugin connecting as its own
Postgres role, plugin_<name>, with no grant on core, would give it teeth;
that needs createrole on every install path, which the bundled Postgres has
and a Homebrew or remote one may not, so it is not done. Until every install
path can grant it, the import test’s core. table check below is the scope
rule for db.
The boundary, plainly. Plugins run inside buddi’s process. ctx.buddi
is the supported path, not a sandbox: a plugin that wants to can import
a file by absolute path, read process.env or open a socket to Postgres.
What stands between a hostile plugin and the owner is the two install
approvals, the recorded integrity hash, and the owner reading the card.
What the host adds is that honest plugins have no reason to reach further,
so any reach is visible in review:
packages/gateway/src/plugin-imports.test.tswalks every plugin source inpackages/tools/*and fails on any import of@buddi/coreother than@buddi/core/pluginand@buddi/core/sheet(and@buddi/core/testingin tests), any@buddi/runtime,@buddi/gatewayor@buddi/tool-*, and anycore.table in a SQL string, naming the file, asbundle.test.tsdoes for the web package. buddi-plugins runs the same check from its rootpnpm test(scripts/check-plugin-imports.mjs).- For installed plugins, staging writes a
@buddi/corewhose only export is./plugin, re-exporting the running core’sdist/plugin, so an import of an internal by package name fails to resolve. It is written, not linked, and not hashed. A directory install andplugins devkeep the checkout’s ownlink:, whole. - After boot the gateway deletes the mailbox passwords from
process.env, and no plugin writes a password there.DATABASE_URL,BUDDI_VAULT_KEYand the provider, Telegram and search keys stay, each still read after boot;packages/gateway/src/owner-secrets.tssays by what.
Not done: process isolation. Running each plugin in its own worker
or process, with ctx.buddi as an RPC surface and its own database role,
would make the boundary real. It needs every area to be serialisable
(files as streams, deliver run in core with the destination’s backend
reached over the bridge), and tools that hold handles (developer’s child
processes, browser’s driver) to live in the plugin’s process. The areas are
designed so that move is possible later: every method is async and takes and
returns plain data.
7. Versioning
Section titled “7. Versioning”ctx.buddi.version is major.minor; this buddi is 1.35
(packages/core/src/plugin/version.ts). A plugin declares the version it was
built against as buddi.hostApi in package.json ("^1.0"), and one that
asks for more than this buddi has is refused at stage time with both numbers.
1.10 adds no method: it is the first buddi that draws the tiles renderer
and Home glances (placement: 'glance'), and an older one refuses a
descriptor it cannot parse. A plugin contributing either asks for ^1.10.
1.11 adds no method either: it is the first buddi that draws the calendar
page component (docs/plugin-pages.md §4). A plugin whose pages use one asks
for ^1.11.
1.12 adds no method either: it is the first buddi that draws the tabs,
hero and tiles page components, a chart’s series, and the sun and
cloud page icons (docs/plugin-pages.md §4). A plugin whose pages use any
of them asks for ^1.12.
1.13 adds no method either: it is the first buddi that draws the
series-panel page component (docs/plugin-pages.md §4). A plugin whose pages
use it asks for ^1.13.
1.14 adds proposals.listOpen, keepItself, trackRecord and takeBack,
and proposePolicy’s optional { announce } (§4, proposals). A plugin that
keeps rules itself asks for ^1.14.
1.15 adds no method either: it is the first buddi that starts a source’s
optional watch (a long-lived watcher beside the poll, such as IMAP IDLE;
docs/plugins.md §2.2) and stops it when the plugin is taken out. An older
buddi ignores the field and only polls, so a plugin with a watch keeps
working there and need not ask for ^1.15.
1.16 adds no method either: it is the first buddi that asks a manifest’s
optional carryOver contributor for lines in the note a rolled-over
conversation opens with, and writes a proposed agent’s optional
idleRollover into its file (docs/plugins.md §2.6, §2.7). An older buddi
ignores both, so neither needs ^1.16.
1.17 adds no method either: it is the first buddi that reads a manifest’s
optional widgets — small live panels the owner places on Home, each a
read-only produce(ctx, { size }) answering a body from a fixed vocabulary
(stat, list, strip, progress, text; docs/plugins.md §2.5d). An older
buddi ignores the field, so declaring widgets need not mean asking for ^1.17.
1.18 adds owner.places() behind owner:places, and three optional manifest
fields with the area that goes with them: setup (one read-only answer, { ready, note?, page? }, that turns the Plugins row into “needs setup”),
requires ({ "<plugin>": "<range>" }, repeated as buddi.requires; until
each is installed, enabled, in range and set up, the plugin’s tools and
widgets do not load), and exports (named read-only queries), reached through
ctx.buddi.plugins.call (docs/plugins.md §2.8–§2.10). An older buddi ignores
setup, requires and exports, but refuses owner:places, so a plugin that
declares it asks for ^1.18.
1.19 adds owner.formats(), the tile icons check and clock, and a
widget’s optional settings: up to eight fields from a fixed vocabulary
(select, multiselect, toggle, text, place, timeFormat; a select’s
choices fixed or read by options(ctx) when the sheet opens), set per
placement — the same widget can sit twice on Home and on the lock screen,
each placement with its own — and handed to produce(ctx, { size, settings }) resolved: defaults filled, places with coordinates and zone, a time format
with the Profile applied (docs/plugins.md §2.5d). An older buddi ignores
settings and calls produce(ctx, { size }), so a widget reads settings ?? {} and need not ask for ^1.19.
1.20 adds no method either: it is the first buddi that reads a sentinel’s
optional coalesce: { windowSeconds, maxWaitSeconds } and gathers that
watcher’s wakes for the same agent into one run carrying every finding
(docs/plugins.md §2.3). An older buddi ignores the field and wakes once per
finding, so a watcher that sets it need not ask for ^1.20.
1.21 adds no method either: it is the first buddi that draws the clocks
widget body — analog faces from zones and labels, ticked by the page
(docs/plugins.md §2.5d). An older buddi refuses the body as a kind it cannot
draw, so a widget that answers one asks for ^1.21.
1.22 adds no method either: it is the first buddi that draws the tile icon
moon-cloud, a partly cloudy night. An older buddi leaves an icon it does not
know off, so a plugin that wants one there checks ctx.buddi.version and
answers cloud before 1.22 (the weather plugin does). It is also the first that takes a page’s
tabs with one tab and a pick — the bar drawn as the pick alone, a filter
over one view (docs/plugin-pages.md); an older buddi refuses the descriptor,
so a plugin that draws one asks for ^1.22.
1.23 adds no method either: it is the first buddi that reads a finding’s
owner-facing fields — ownerLine (what the owner reads; detail is now the
agent brief and is never shown), kind, subject, group and actions
(open, run, fill, ask, dismiss; docs/plugins.md §2.3) — and lists
only urgent findings, grouped, with Not now, Stop telling me this and Clear
all. An older buddi ignores the fields and shows the title, so a watcher that
sets them need not ask for ^1.23.
1.24 adds an optional argument: owner.notify’s action, what the owner is
asked to do in a few words (“Bring the plants in?”), at most 80 characters
once trimmed — the same rule as an agent’s owner.notify. A message with one
waits in Home’s Needs you and counts on every badge until the owner deals
with it, and Telegram says it last; one without is information. An older
buddi ignores the field and delivers the message as information, so a plugin
that sets it need not ask for ^1.24.
1.25 adds an optional argument and two optional fields on a return:
files.save’s version (the next version of a document in the calling
conversation, allocated under a lock) and, on what it returns, version and
existed (the bytes were already in Files). An older buddi ignores
version and saves under filename.
1.26 adds an optional argument: http.request’s auth: { as: 'basic', username } and the core kind http.basic that secrets.put accepts with it
(§4.2, http) — a sign-in’s password sent as Basic auth by core, with the
WebDAV verbs, so a plugin can read and write a CalDAV account without
holding its password. An older buddi treats the auth as a header secret and
refuses the binding, so a plugin that uses it asks for ^1.26. It also adds
swatch on a page table’s column: a path within the row to a #rrggbb
colour, drawn as a small dot before the cell’s text (a calendar’s own colour
beside its name); an older buddi refuses a descriptor that carries it.
1.27 is what the News plugin and Anchor need (buddi-planning
specs/news-and-anchor.md §6). Eight additions, each optional; a plugin or a
package that uses any of them asks for ^1.27:
-
assets, a declared area (§4.2):put,delete,list. A logo fetched once is kept as PNGs core drew and served by buddi:uses: ['http', 'assets'],// when an outlet is addedconst icon = await ctx.buddi!.http!.request({ url: `https://${domain}/apple-touch-icon.png`, maxBytes: 256 * 1024 });if (icon.ok) {const bytes = Buffer.from(await icon.arrayBuffer());await ctx.buddi!.assets!.put(domain, bytes, icon.headers.get('content-type') ?? '');} // an SVG or a WebP is refused: try the next candidate -
Pictures in the page grammar. A list item’s
images— up to four fixed slots{ asset, label }, or{ from, asset, label }over an array in the row — draws the first three logos overlapping and the rest in words (“Reuters and 3 more”), a letter tile for a key that is missing. A widgetlistrow’simage: { asset }leads it as a small logo on medium and on the lock screen. Each is a key of the plugin’s own assets; the page builds buddi’s own path from it and never draws anything else (plugin-pages.md §4, plugins.md §2.5d):item: { title: { path: 'title' }, images: { from: 'outlets', asset: 'logo', label: 'name' } },// a widget row{ title: story.title, sub: story.outlet, side: '2 h', image: { asset: story.logo } } -
Links out.
RouteRefgains{ href: ValueRef }: an absolutehttps:address read from the data, opened in a new tab withnoopener noreferrerand the outside-link mark. Anything else is no link, and a tool’sthennever follows one. The dashboard still makes no request outside buddi: a link is followed by the owner, never fetched.to: { href: { path: 'url' } }. -
Mission context. A mission (
SuggestedMission, a proposed agent’s missions, an agent package’smissions[]) may carrycontext: { plugin, export, args? }. Core calls that export before each fresh run, with the target’s read-only host and its ownparams, and puts its JSON in the run’s first message under a line naming where it came from (at most 48,000 characters); a call that fails is said in the message and the run goes on. The plugin must be the declaring plugin or one it requires — for an agent package, one in itsrequires— checked at register and at install:{ "id": "morning", "cron": "0 7 * * *", "reportMax": 3800,"context": { "plugin": "news", "export": "edition_material", "args": { "edition": "morning" } } } -
A longer report. A mission’s
reportMax(200 to 6,000 characters) replaces the 1,500 cap on itsmission.report; Telegram splits a long one at its paragraphs, links as full URLs with previews off. An agent package’s update changes a mission’scontextandreportMaxand leaves the owner’s prompt and hour. -
A linked, spoken report.
mission.reporttakeslink(a dashboard route,#/…),linkLabel(its button’s words, “Open edition”) andaudio(the Files id of a voice note made in the same run, checked to be audio from that conversation). The notification opens the link; Telegram sends the voice note first, then the text; the run’s conversation on the dashboard draws the player above the text and the button under it; a channel without audio leaves it (notifications.md).const voice = await call('speech.say', { text: spoken });await call('mission.report', { urgency: 'normal', text, link: '#/p/news/stories', linkLabel: 'Open edition', audio: voice.id }); -
Optional plugins.
optionalin the manifest (andbuddi.optional),ctx.buddi.plugins.has(name), andplugins.callopen while the plugin is there (§4.2, plugins). -
The
newspage icon, a folded newspaper, in the pinned set (and the kit’sassets/icons/news.svg). An older buddi refuses a descriptor that names it; ask for^1.27or useglobe. -
A feed of stories (
stories, plugin-pages.md §4): the News page as the kit draws it — cards under one head per group with See all, the outlets’ logos and “Reuters and 3 more”, quiet marks, a ⋯ of ways out (each a tool; one thathidesleaves its sentence and Undo in the card’s place for eight seconds), and a sheet per story with its sources linked out, how it moved, and the ways out again. Rows areStoryRows. -
The rest of the News page’s grammar. A rail page’s head
actions(links and buttons,tone: 'accent'for the primary); atabspick drawn as chips (look: 'chips') with anaddchip, and the chosen tab kept in a page parameter (param); a notice drawn as one quiet line (look: 'quiet',icon) ending with alink, or a box with anaction; an intro notice read from the page’s data; and a list row’slogo(leading it),tag(after its title),status(a sentence under it, in a tone), ⋯ menu actions (menu: true, withhintandgroup) and group heads read from the rows (groupBy.label,groupBy.aside). -
Widget lists for headlines. A
listbody’smax: 5asks for five denser rows at medium (small and the lock screen still draw three),wraplets a title take two lines, a row’s title may be 120 characters (the page cuts it to its line) and its side 24 (“Ars Technica · 1 h”), and a row’simageleads it at both sizes; itslabelkeeps a letter tile in its place when there is no kept picture. Amultiselectsetting may carryinTitle: the placement is named by every option ticked (“Top stories · AI, US politics”).
1.28 is OAuth sign-ins for plugins: secrets.signIn, signInStatus,
signInFinish and signInCancel (optional methods, present with http
declared), http.request’s auth: { as: 'bearer' } with the core kind
http.bearer, and OAUTH_PROVIDERS, SignInExpiredError and
isSignInExpired in @buddi/core/plugin. An older buddi has no signIn
and treats a bearer auth as a header secret it cannot find, so a plugin that
uses them asks for ^1.28.
1.28 also adds to the page grammar what Settings → Calendar’s redesign needs
(plugin-pages.md §4), each optional, each refused by an
older buddi’s descriptor check — a plugin that uses one asks for ^1.28:
-
A row’s choice. A list item’s
choice: two to four options drawn as a segment on the row’s right, the row’svaluethe chosen one,{ choice: true }the picked value in the tool’s arguments, an option hidden (when) or greyed with why (disabledWhen,hint). Not linked · Read · Read and change on each calendar:choice: { tool: 'calendar.set_access', label: 'What agents may do with {name}', value: 'access',options: [{ value: 'off', label: 'Not linked', when: { path: 'kind', equals: 'account' } },{ value: 'read', label: 'Read' },{ value: 'change', label: 'Read and change', disabledWhen: { path: 'canChange', equals: false }, hint: '{why}' }],args: { id: { row: 'id' }, access: { choice: true } } }(
labelandhinttake{field}placeholders read from the row.) -
A list row’s swatch.
swatchon a list item, as 1.26’s on a table column: the row’s own colour as a dot leading it. -
A group’s head.
groupBy.actions(row actions read against the group’s first row: Sign in again, ⋯ Remove account…) andgroupBy.asideTone. -
A menu.
{ kind: 'menu', label, tone?, items }, in a body or a section’s or a rail page’s head; an item runs a tool (action) or opens a drawer form by its id (open, matched todrawer.id, whosebuttonis then optional; the page parameteropen=<id>opens it from a link). -
A card that finishes by itself. A
repeat’spoll.finish: { when, action }runs the tool once for the first row wherewhenholds — a sign-in whose loopback answer has arrived — with itsbusyline in place of the rows. -
Where the page is opened.
where: 'local' | 'remote'on any component: a browser on this computer, or anywhere else. -
An event’s sheet, and a count. A
calendar’ssheetmakes an event open a sheet of its own (on the right; full width on a phone) instead of its day’s list: the title, when and how long (“Mon 5 Oct · 14:00–15:00 · 1 h”), its calendar with itscolor, the place linked out (mapHref), thenotes,open(a link out to the event where it lives), and up to threeasksthat open the corner chat with a request written in —{field}read from the row,{when}as the sheet says it — for the owner to edit and send; a change still goes through an agent and its card.count: truewrites “12 events” beside the range’s name:sheet: { notes: 'notes', color: 'color', mapHref: 'mapHref', open: { label: 'openLabel', href: 'openHref' },asks: [{ label: 'Move or change…', text: 'Move or change “{title}” ({when}) on {calendar}: ' }] }
A minor adds a method, an optional argument or an optional field on a
return; it never changes what an existing call does. A major removes or
changes something, and ships only after one release in which both shapes
exist and the old one logs its caller. plugins.md §9b lists each
method with the minor that introduced it, and plugin-reference.test.ts
checks that table against the interface as it does for ToolContext.
1.29 is routes for the browser runtime (browser.md): a
manifest’s optional routes: [{ kind: 'apps', label, health, look, do, release?, exclusive?, platforms?, reach?, takeover?, resume?, handMessage?, focused?, typeSecret? }] (types RouteProvider, RouteHealth, RoutePage,
RouteCommand, RouteReach, RouteTarget in @buddi/core/plugin) declares
a route the runtime may pick for app jobs. Core has no apps route of its own:
computer control is @withbuddi/plugin-computer. reach answers who a name
stands for, whether it is on the owner’s list and what to do with one that is
not (core draws the card); takeover/resume/handMessage are take-over
without a remote hand; focused/typeSecret (together or neither) carry
secret.type. A tool’s waitsForOwner may be a function of its result, a tool
may declare ownBudget (its turns do not spend the run’s maxTurns), and
ctx.ask lets a tool put one question card with choices in front of the
owner on an interactive surface. An older buddi ignores routes and treats
a function waitsForOwner as false, so a plugin that relies on them asks for
^1.29.
1.30 adds capabilities to each account accounts.list() returns:
{ audioIn, audioOut, source } (type AccountCapabilities), computed by
accountCapabilities from the account’s kind, sign-in and address. An
OpenAI key and Gemini (an OpenAI-compatible account on
generativelanguage.googleapis.com) are known with both true; a ChatGPT
subscription and Claude are none with both false; Ollama and any other
OpenAI-compatible address are probe, both false, since only a sample tells.
Settings → Speech reads it to offer only accounts that can listen or speak.
An older buddi leaves it out, so a plugin computes the same from kind and
baseUrl when it is absent.
1.30 also brings the page grammar’s reading pane (plugin-pages.md
§4, “A message, read”): the message component, whose data is a
PageMessage (PageMessageAddress, PageMessageAttachment in
@buddi/core/plugin) — sanitised HTML with remote pictures held back per
sender, text with links, quotes folded, attachments as file rows; a
section’s query and heading; a list item’s strong and preview. Each
is refused by an older buddi’s descriptor check, so a plugin that uses one
asks for ^1.30.
1.31 adds no method: a page query’s sensitive may be a list of paths into
its answer instead of true (plugin-pages.md §3,
“Sensitive values”). The page then masks only those values (••••, one
Show amounts per page, masked again when the window is left or after five
minutes) and keeps every piece of structure visible; buddi.page_query over
MCP answers with them reading "(hidden)" unless includeSensitive. The mark
sits on the query, not on each { path }, so one line covers every place a
value is drawn and the gateway redacts by the same paths without reading a
layout:
// The query marks the values, once; the descriptor stays as it was.queries: [{ name: 'overview', params: z.object({}), sensitive: ['netWorth', 'accounts[].balance'], produce: async (_p, ctx) => ({ netWorth: 48210.5, accounts: [{ id: 'a1', name: 'Checking', bank: 'N26', balance: '1,204.10' }] }),}],
// A stats item: drawn "Net worth ••••" until Show amounts.{ label: 'Net worth', value: { path: 'netWorth' }, unit: 'currency' }
// A list item's meta: "Checking N26 · ••••".{ title: { path: 'name' }, meta: [{ path: 'bank' }, { path: 'balance' }] }An older buddi refuses a query whose sensitive is not a boolean, so a
plugin that marks values asks for ^1.31.
1.32 adds the onnx area (§4.2): uses: ['onnx'] gives ctx.buddi.onnx
(state, ensure, createSession) and ctx.buddi.models (state,
ensure), one engine downloaded on first need for this platform only, after
one owner card that covers the engine and the plugin’s first model. An older
buddi refuses onnx in uses at staging, so a plugin that declares it asks
for ^1.32. A plugin that must still run on an older buddi keeps its own
onnxruntime-node as an optional fallback and checks ctx.buddi.onnx.
1.33 adds one method and one export name, and nothing in core that names a plugin:
- A mission run’s context may vouch for a tool. A mission whose
contextis plugin P’s export E with arguments A may have P vouch for a tool in that run. When a tool’s own plugin asksctx.buddi.approvals.configuredForRun(tool)(its own tools only), core calls P’s exportconsent_for_run(RUN_CONSENT_EXPORT) with{ tool, export: E, args: A }, afresh on every call, and answers true only if it returns exactlytrue. Always false outside a mission run with a context, in a delegated run, for another agent or conversation, and when P has no such export, refuses or fails. The export runs like any other (read-only pool, P’s own host, five seconds). P decides from the owner’s own settings; whether a yes lowers the tool’s tier is the tool’s plugin’s decision. Speech honours it forspeech.say; News vouches for it in an edition the owner set to be read aloud. - Canvas renderers
story(oneStoryRow, or a list atmap.rows),audio(a saved recording) andquery(one of the plugin’s page queries, drawn as page components the view declares), and a view’smessengerdeclaration with the reservedattachmentsfield of a tool’s output: plugins.md §2.5. - Page components and grammar:
sheet(a drawer opened by a page parameter),digest(a saved digest card),section.look: 'setup', links withparams, anexpandwithout a query, and on a story rowimage, the…Attributionlabels andask.context: plugin-pages.md. - Assets also keep an aspect-preserving PNG up to 768 pixels on its
longest side, never upscaled, read with
?size=768. The 64 and 128 squares and the limits are unchanged; an asset kept before 1.33 has no 768 variant, and whatever draws one hides a missing image.
An older buddi refuses the renderers, components and fields it does not
know, so a plugin using any of them asks for ^1.33.
1.34 makes a file a row with numbered versions (docs/files.md, “Versions”):
FileRow gains fileId, version and createdBy, a document’s versions
keep its name (no (vN) in stored names), and files.list takes latest
(each file once, as its current version). files.save takes:
workspacePath: the absolute path the bytes were read from, inside the plugin’s own data folder (anything else is refused). The save is a version of the file captured from that path in this conversation; when the owner edits it on the Canvas and saves, buddi writes his version back there too, while that copy is still the one buddi last read or wrote (otherwise his save is refused with what the copy holds now). The host plugin passes it for a command’s outputs.version.of: an existing file’s id (or any version’s): the save is that file’s next version, whateverbasesays; the file keeps its name and workspace.version.readVersion: the number of the version the writer read. A save over a newest version someone else wrote (the owner’s edit) is refused without it, and with an older one, so a writer cannot drop that version unread. An older buddi ignores all three.- A made document (
version.extdocx,pdforxlsx, with Markdown or a CSV as the bytes): buddi’s exporter makes the file and that is what is stored, under that format’s mime; by title, an existing file of that name is rebuilt as below. - Onto an Office file (
version.ofnaming a .docx, .xlsx or .pdf): Markdown (a .docx, .pdf) or a CSV (a .xlsx) is rebuilt into the file’s own format by buddi’s exporter, and the row saysrebuilt: true— the formatting of the version before is not kept. A file the owner made or handed in is refused unlessversion.confirmedRebuildis true, which a writer passes only once the owner agreed (since 1.35: over his own newest version, only as an action he approved, below); a .pptx is never written (docs/files.md, “Office documents”).
1.35 keeps a program beside a version (docs/files.md, “Composed documents”):
-
files.save({ composed }):{ kind: 'docx'|'pptx', library, libraryVersion, nodeVersion, program }says a program made these bytes. They must be a whole package of that kind under its Office mime, and are stored as they are — never rebuilt from text — with the program incore.compose_sourcesbeside the version, in the same transaction. Saved by title (version) or onto a file (version.of) of the same kind. -
The owner’s yes is an approval, not a flag. Since 1.35 any save that rebuilds over a newest version the owner wrote — from text or composed — runs only as an action he approved (the call carries the executor’s
actionId);version.confirmedRebuildno longer lets it through, and now only says the owner asked for text onto a composed version. A tool raises the card by deciding its tier per call (tierFor→gated) whenfiles.rebuildCheck({ version, composing? })answersneed: 'owner'; it answersnull, or{ need: 'owner'|'asked'|'never', message, fileId, name, version }, the sentence the agent is told included. -
files.source(id): the program a version was composed from (by a version’s id), or the newest version’s (by a file’s id):{ artifactId, fileId, version, kind, library, libraryVersion, nodeVersion, program, createdAt }, ornullwhen it was not composed or is out of scope. -
files.get(id)(andread) take a file’s own id too: its newest live version. -
confinement, always present:{ kind, argv(work, { readable?, network?, fork? }) }, the OS sandbox skill scripts run under (the host plugin’s, handed in by the gateway), for a process a plugin starts;kindisnullwhere there is none.
An older buddi ignores composed and has no source.
8. End to end
Section titled “8. End to end”plugin-imports.test.tspasses, and fails naming the file when a plugin importscreateVaultor queriescore.events.- A plugin with no
usesgets actx.buddiwith only the always-present areas;ctx.buddi.secretsisundefined. - Installing image shows “uses a model account you pick” and “keeps files in your Files library” on the card before its code runs.
- The email plugin adds and removes a mailbox with no
createVaultimport, and no mailbox password is inprocess.env. - A plugin declaring
buddi.hostApi: "^1.9"is refused at stage time on a1.2host.
A tarball install of the scaffold has a known problem that predates the host:
it needs the link: devDependency removed, the peer resolution fixed and
buddi.name in the scaffold (plugins.md §8).
