mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-09 09:54:40 +00:00
Mohamed Boudra
28c188513e
* feat(protocol): option controls, options patch, and provider.controls.list
Add AgentOptionControl descriptors, snapshot options/controls, an options patch on
agent.config.apply, provider.controls.list RPC, and server_info.features.providerOptionControls.
featureValues stays accepted on the wire (COMPAT).
* feat(server): fold featureValues into providerOptions and describe composer controls
Providers emit option controls over top-level providerOptions keys; the daemon stores one
options record per agent, merges config.json defaults as effective values, and applies patches
live via AgentSession.applyOptions. Legacy featureValues (wire, stored records, profiles,
schedules, hooks, MCP) fold into providerOptions; snapshots still carry features built from
controls. Snapshot options expose only keys that have a control.
* fix(server): address Phase 1 audit findings on option controls
- Removing auto_accept (OpenCode, ACP) turns live approval off; ACP selects return to their session default.
- agent.create.before hook featureValues edits override options the create already set.
- Claude commits fast_mode only after the runtime accepts it.
- Codex snapshots show a saved Fast preference as the tier the model resolves it to (AgentSession.displayOptions).
- Profiles are folded into options in the daemon config store; the config API still answers with featureValues.
- Snapshot options and provider.controls.list carry all effective options.
- Test: Claude fast_mode survives a restart through stored providerOptions.
* fix(server): keep snapshot options as configured, restore OMP baseline, cover options through public interfaces
- Codex: drop displayOptions; a select choice may carry aliases so a saved Fast preference selects the model's Fast tier from options + controls alone.
- OMP: removing fast_mode restores the runtime's starting setting.
- ACP/Cursor removal tests run through real session initialization.
- agent.config.apply of a non-control option reaches the provider and shows in the next snapshot (daemon e2e).
- Daemon config store persists legacy-featureValues profiles as options on the next profile save.
* fix(server): read a pre-v0.10 Codex fast_mode record as service_tier "fast" and store it that way
A record holding `fast_mode: true` without `service_tier` ran Fast but the speed control showed
Normal, and picking Normal then wrote "default". The Codex session now normalizes the old boolean
at construction and reports the new shape through its existing options_changed event.
* fix(server): show Fast for a stored Codex fast_mode: true without rewriting the record
Reverts the storage migration from a987b4a43. The Codex speed control now takes its default from
the session's current options with the same rule the runtime uses (an explicit service_tier wins;
fast_mode: true applies only while service_tier is absent). This holds on create, resume, live
apply and for config.json defaults, and stored options stay as set.
* chore(website): regenerate the config schema for profile options
* refactor(server): providers report option differences once, after create, resume and apply
Providers used to write their own reports into the agent's options while a session was being
created, resumed or updated, which needed a growing set of reconciliation, baseline and
suppression rules to stay in step with the daemon.
The contract is now transactional. A provider opens or updates with the options it is given and
emits nothing while doing so; if the result differs it says so once, afterwards, as
`options_changed`. Live apply hands the provider only the keys the patch sets and the daemon stores
them onto the agent's current options when the provider accepts, so the last write wins. A change
the provider makes on its own is stored and forwarded, not undone. Removing an option drops the key
and sends nothing live. Controls carry no state; `options` is the only option state.
A legacy `agent.create.before` hook's `featureValues` edits are applied as a patch over the
returned options, so its deletions and replacements hold. The unreleased `aliases` field on option
choices is gone; a pre-v0.10 Codex Fast preference is reported once as the model's tier id.
* refactor(server): providers return what apply and open ended with instead of reporting it afterwards
applyOptions returns the options the session ended up with and the session
exposes its open difference as openOptionsPatch, so the manager stores the
patch and the provider's answer in one step. Removal is an ordinary patch:
the provider receives the default the key falls back to, or null, and returns
what it kept. Controls no longer take a default from a stored legacy feature
value.
* fix(server): apply an old app's profile featureValues over the profile's stored options
The unchanged app's profile form only knows the controls, so a name-only
edit dropped options it never shows, such as sandbox_mode. Its
featureValues now apply as a patch over the options already stored for the
profile (null removes a key), and a write with no featureValues keeps them.
* fix(server): ACP reports the selects it moved during open or apply as that call's result
A config_option_update that arrived before the write response was emitted
as an event on top of the result the manager stores. Notifications during
open or apply now fold into the open patch or apply result, and a rejected
apply reports what the agent moved since nothing is stored. Live options
are validated with the creation schema. Tests drive a stdio ACP agent.
* fix(server): providers validate live option patches and Claude reports Fast dropped by a model switch
Live patches go through the schema used at creation. A Claude model switch
that cannot keep Fast reports fast_mode as removed so the stored options
match the session.
* fix(server): Claude reports Fast as off, not removed, when a model switch drops it
A removed key lets a config.json default of fast_mode: true fill back in
while Fast is off at runtime.
* fix(server): fold an old app's profile featureValues by the provider and options the write carries
A write with options folds featureValues over those options. A write
without them patches the stored options, unless the profile moved to
another provider, which starts from no options.
* docs(server): a rejected apply reports what the provider moved after the call ends
* test(server): a patch key is resolved against nested configured defaults
* test(server): a setting a plugin changes on its own is forwarded as options_changed
* test(server): assert the forwarded plugin setting without nesting callbacks
* test(server): removal of auto_accept returns ACP to asking; Claude keeps opening restrictions across a patch
* fix(server): Codex returns the tier it resolved and drops a speed the new model lacks
A live service_tier: fast is stored as the catalog's Fast tier id instead of
a value the control cannot show, and a model switch to a model without the
stored speed reports Normal so choosing a supporting model again does not
bring the paid tier back.
* fix(server): Claude applies only the keys a patch sets over its current options
A Fast patch kept a copy of the options taken before the runtime answered, and
assigning it afterwards dropped a patch that landed meanwhile.
* fix(server): a plugin that moves settings and then refuses an apply reports what moved
* refactor(server): the legacy featureValues folds take one named-input object
* fix(server): a live patch is rejected for an option the session only reads at start, and opening reports every option it ended up with
A stored option has to describe what runs. OpenCode, OMP and ACP now reject a live change
to a key they apply only when the agent opens; Claude applies such a change from the next
turn and rejects it while a turn is running. Opening reports every select or setting the
session came up with, including ones nobody set, so a native default (Cursor opening with
Fast on) is stored as option state like any other.
* fix(server): Claude rejects a live change to an option it reads when the query starts
Replacing a started query to apply the option would end its background shells and
tasks. Once the query exists only Fast can change; before the first prompt every option
still applies, because it is read when the query is built.
* fix(server): a live options patch is rejected when the session cannot apply it
A session with no applyOptions (Pi) now rejects a patch instead of storing a value that
fails on reopen. Codex applies only service_tier, plan_mode and fast_mode live, since the
approval policy and sandbox are fixed when the thread starts. Claude also rejects a launch
option change while its first query is starting, after the options have been copied.
* fix(server): plugins reject keys they do not report as settings, and Codex opening reports the speed it runs
A plugin session applied the settings it knew and silently stored the rest; it now rejects
a patch that names a key the plugin does not report. Codex opening on a model without the
saved speed ran Normal while the stored options still said priority; opening now reports
the tier it runs, as a later model switch does.
* refactor(server): option helpers take named inputs, control types come from their schemas, and a plugin accepts launch options it opened with
A whole profile is applied by the unchanged app, so a launch-only plugin option whose value
has not changed must not fail the apply. applyProviderOptionsPatch and featuresFromControls
take one object, and the protocol control types are inferred from the wire schemas.
* fix(server): ACP reports a select that appears after startup with its native value
A model switch can introduce a select (Cursor Fast) that the session did not have at open.
Its value is now stored like any other native selection instead of being skipped because
the previous snapshot did not name it.
* fix(server): a loaded agent's options stay what its session opened with when a provider default is edited
effectiveOptions was recomputed from the current config.json defaults on every state emission, so editing a default changed the snapshot of an agent whose session never received it. It is now computed when the session opens and moves only through an apply or an options_changed. Editing a default affects agents the next time they open.
* fix(server): a live apply shows the merged defaults the provider was given in the options snapshot
The snapshot took the raw patch, so a nested patch over configured defaults dropped the defaults the provider had accepted. The snapshot now takes what the provider was sent plus what it reports back; stored options still keep the raw patch.
* fix(server): an option a session drops when opening is not brought back by a configured default
The opening snapshot merged defaults over the options after the session's openOptionsPatch had removed a key. Defaults now merge into what the session was given and the patch applies after.
* fix(server): Codex keeps the speed it opened with when the legacy Fast key is removed
Opening moves a legacy fast_mode into service_tier, so removing fast_mode afterwards changed the runtime speed to Normal while the stored options still said Fast. Removing the alias now changes no speed.
* fix(server): opening snapshots keep the defaults the session launched with, and config-change pushes carry legacy profile values
An opening resolved defaults once for the session and again at registration; an edit in between showed options the session never received. Create, resume and reload now resolve once, before the provider opens, and registration starts from that. The daemon_config_changed push skipped the featureValues projection that config replies apply, so the unchanged app lost a profile's legacy values when any setting changed.
* fix(server): every opening path hands registration the options it launched with
Registration took the launch options as optional and reread the defaults when a path did not supply them, as provider-session import did. It is now required, so create, resume, reload and import each resolve once before opening. The option helpers take named inputs.
* fix(server): a saved legacy Codex Fast preference wins over a configured service_tier default
The defaults merge put a configured service_tier next to the agent's own legacy fast_mode, and Codex reads service_tier first, so the agent opened Normal. The agent's own alias now replaces the default of the key it stands for.
* fix(server): Codex keeps a Fast chosen by alias as the catalog's tier id
A live fast_mode or service_tier "fast" was stored as the alias while the apply reported the catalog id, so a later switch to a model with a different Fast id ran Fast under an option that said otherwise. The session now stores the id it accepted and drops the folded fast_mode.
* fix(server): the legacy Codex Fast alias folds into one speed on apply and in configured defaults
A patch with both speed keys left the alias in the stored options, so a reload started Fast again after the speed was removed; the apply now reports the folded alias. A configured fast_mode default now supplies the service_tier default, so removing an agent's own speed falls back to the configured Fast like opening does.
* fix(server): an OMP replacement runtime starts with the Fast the session has now
A restart (for example an approval-mode change) restored Fast from the options the session opened with, turning back on a Fast the user had switched off. The session now keeps the Fast it applied or the provider changed, which is what a replacement reads.
* refactor(server): Codex's legacy fast_mode converts to service_tier where old data enters
Stored records, config.json defaults, profiles, older clients' requests, MCP settings and
plugin hooks go through convertLegacyOptions as they come in. Past that point the defaults
merge, the manager and the Codex session never see fast_mode for Codex, so the alias branch
in the defaults merge and Codex's fast_mode handling are deleted.
* fix(server): a legacy hook's replaced speed and an apply request's options convert before they are compared or applied
A hook that swaps the canonical speed it was sent for fast_mode is diffed in canonical form, so
its replacement is not read as a deletion. An apply request carrying featureValues and options
sends one options patch with options winning, so a superseded legacy value is never applied.
* refactor(server): the agent manager converts Codex's legacy fast_mode for the adapter behind the provider id
The rename is adapter-specific, so it lives where the provider id resolves to its adapter:
AgentManager converts an agent's own options on create, resume, import, reload, apply and
draft controls, following derivedFromProviderId, so a custom provider extending codex keeps
working with a saved or requested fast_mode. Storage, MCP, schedules, hub and profiles pass
options through. The featureValues-to-options fold stays provider-agnostic at the legacy edges.
* fix(server): a rejected OpenCode auto_accept leaves the session asking for permission
applyOptions committed the new flag before approving pending requests, so a failed reply left
the session auto-approving while the stored option stayed off. The flag is restored when the
apply throws.
* fix(server): legacy Fast reaches draft discovery and saved profiles, and overlapping or replaced options keep the state they committed
Draft controls and commands convert the config they hand to the provider, so inspecting a
legacy Fast preference no longer fails Codex's strict options. A profile naming codex converts
its saved fast_mode for the app's controls. OpenCode serializes auto_accept applies so a failed
one restores exactly what it changed, and a replacement OMP runtime starts from the Fast the
session opened with.
* fix(server): an OMP replacement runtime that refuses the session's Fast publishes what it accepted
The approval-mode restart installed the new runtime's state without comparing its Fast result to the session's, so a refusal never reached options_changed, the remembered value, or storage. The replacement now goes through the same comparison as refreshState.
* fix(server): OMP turn completion publishes a Fast change, and Claude opens with Fast off on a model that has none
OMP installed runtime state in several places and only one compared Fast; every state read from the runtime now goes through one install step. Claude kept a Fast default on a model without Fast, which made unrelated options reject until the user cleared it; the session now opens with Fast off and reports it in openOptionsPatch, as the model-switch path already does.
* fix(server): a malformed Codex fast_mode is rejected, and profile options are renamed for clients by the agent manager's conversion
convertLegacyOptions read any truthy fast_mode as Fast, so the string "false" ran priority. It now accepts only true, false or null. The profile store no longer renames keys: a literal codex profile was renamed in storage while an extends-codex profile was not. The config API now converts each profile's options with the manager's adapter-aware conversion, so codex and my-codex profiles read the same.
* fix(server): a profile is stored in the current option keys, converted for the adapter its provider extends
Profiles in config.json are old data entering, so the store converts them (stored value and incoming patch) with the same conversion the agent manager uses. Storage and clients now share one vocabulary: resetting a legacy Codex profile's speed removes what was shown, and a malformed fast_mode rejects the write instead of breaking later config reads. The config API goes back to copying the field shape only. The extends chain is followed by one function over either the registry's definitions or config.json's providers.
* fix(server): profile options convert against the provider graph a write commits
A write that edited a provider and a profile together folded the profile against a shallow merge that dropped the provider's extends, so its legacy Fast was not converted. The fold now sees the same deep-merged providers the write commits.
* fix(server): draft speed shows the tier the first turn will run with
Draft discovery reported the options as requested, so a Fast configured as a legacy fast_mode or the fast alias read as Normal while creating sent the model's own Fast tier. The draft now reports the options the scratch session opened with, as registration does.
* fix(server): ACP option applies run one at a time
Two overlapping applies shared one transaction guard, so when the first was refused after the agent had moved a select, its report was dropped as 'still in a transaction' and the second saw no difference. Applies are serialized, as OpenCode's are, so each reconciles against the state the previous one left.
* fix(server): an ACP removal reports the choice the select lands on, and the Codex plan tests enable plan mode
A removal asks the select for its empty choice and compared the result against that
same empty choice, so applyOptions returned nothing and the manager stored the removal
as null while the session ran the Default choice. The difference is now computed against
what was asked (null), so the options hold the value the session runs with.
The Codex plan-mode end-to-end tests called the removed session.setFeature through an
optional call and silently skipped plan mode; they apply the option and fail loudly if
the method is gone. The MCP parity wrapper forwards listControls instead of the removed
listFeatures.
* fix(server): plugin option applies run one at a time, and OpenCode reports the Auto Accept legacy full-access turns on
Plugin sessions let two applyOptions overlap. The second finished and re-recorded the
settings the plugin held, which included a change the first had already made and not yet
reported; when the first then failed, nothing was left to report and the stored options
kept the old value while the plugin ran the new one. Applies now queue on the session,
the way the ACP adapter's do, so each reconciles against what the one before left.
OpenCode normalizes the legacy full-access mode to build with Auto Accept on, but the
session never said so, so the options the manager keeps did not hold Auto Accept and a
reopen turned it off. The session now reports it through openOptionsPatch on create and
resume.
* refactor(server): openCodeOpenOptionsPatch takes one named-fields object
* feat(app): the client and app work on options and controls
The agent snapshot's `options` are the state and `controls` only draw them.
Running and closed agents draw from the snapshot; drafts and profile forms ask
`provider.controls.list.request` with their `providerOptions`, so aliases such
as a legacy Fast profile's `service_tier: "fast"` are resolved once, by the
daemon, and the draft keeps Fast highlighted. A draft adds only the user's
edits and each provider's last-used control values; applying a profile seeds
its non-control options (e.g. `sandbox_mode`) into the draft, and a profile
form saves them back instead of pruning to the controls it can draw.
A daemon without `server_info.features.providerOptionControls` still sends
`features` and `featureValues`. `LegacyProviderOptions` in the client package
is the one place that translates snapshots, draft listings, create and apply
requests, and daemon-config profiles, so the app never branches on it.
Persisted preferences and tab layouts rename `featureValues` through tagged
COMPAT preprocessors.
The features/controls bridge moves from the server into the protocol package
so the client can reuse it.
* fix(app): drafts and profile forms send every option layer to the daemon
A cold create against a daemon without providerOptionControls routed control
options (Claude fast_mode, Codex service_tier) as providerOptions, which that
daemon does not read for them. The client now lists the provider's features
before the first create or workspace create that carries options, so callers
never prime a cache.
Draft options moved into a plain model. Applying a profile replaces provider
and options in one step, so the form's provider change that follows no longer
clears a cross-provider profile's non-control options; choosing a provider by
hand still starts over. The model sends its complete options (seed, last-used
values once the provider says it still draws them, edits) to the daemon and
the controls draw only the answer, so a remembered legacy fast is drawn as
what it runs as. A toggle shows over the last answer until its own arrives.
The profile form does the same: its edits go through resolution too.
* fix(client): a legacy create routes its options from the controls of its own config
Which options a legacy daemon exposes as features depends on the model, mode
and thinking level, not only the provider: a Haiku snapshot with no features
says nothing about Opus. The provider-keyed memory of control keys sent an
Opus create's fast_mode as providerOptions, which that daemon does not read.
A create that carries options now lists the controls for its own draft
config and splits on that answer. The memory, and the snapshot and listing
hooks that fed it, are gone.
* fix(app): a closed agent shows its stored options, and a provider switch asks about its own options
A closed agent's snapshot is projected from its stored record, which kept
controls and provider options but dropped them from the payload, so the
app drew no speed or other controls for it. The stored projection now
carries them, with the legacy features derived from the same source.
The draft read the form's provider and the model's options separately, so
for the render after a manual provider change it asked the new provider
about the previous provider's options. The request is now built from one
snapshot of the model and is absent until the model has observed the new
provider.
* fix: persisted options keep their full shape, and every legacy snapshot gains controls
Draft setups and form preferences validated option values as booleans,
strings or null, but the options they now receive come from agents and
profiles and can be objects, arrays or numbers. One such value failed
validation and wiped the whole saved layout or the saved preferences. Both
schemas now accept any JSON value.
The legacy-daemon translation skipped the snapshots carried by
agent_created, agent_resumed and timeline responses, so a created agent or
a timeline refresh left the SDK handle without options and controls.
The profile journey asserted the create request's options field; the wire
field is providerOptions.
* fix(client): a legacy profile with both featureValues and options keeps both
A legacy daemon keeps an unknown `options` field on a profile it stored
(profiles are passthrough), for example after a downgrade, while its own app
keeps editing `featureValues`. Reading such a profile took `options` and
dropped `featureValues`, so a Fast setting there was lost and the next save
replaced it. Both are merged on read with an explicit `options` key winning,
the same rule the daemon applies when it folds `featureValues`.
The draft form input of draftControlsRequest is a named type.
* fix(app): a draft stops sending a toggle the model in use does not offer
A toggle made on one model stayed in the draft's edits after the form moved
to a model whose controls do not include it, and was sent with the create.
On a legacy daemon that key is not a feature for the new model, so it went
out as a native provider option the daemon rejects. The draft now sends an
edit only while the latest answer draws a control for it, and sends it again
when a control for it returns.
* fix(server): a closed agent's options include the provider defaults, like a live one's
The stored snapshot projected only the options the agent owns, so an agent
that ran with a config.json default (for example Claude fast_mode: true)
showed the option as missing, and its legacy Fast control as off, until it
was resumed. The projection takes the same resolver the live agent uses
(the provider's defaults under the agent's own options).
* fix(app): a draft keeps sending an option no control has drawn
The previous change stopped sending any edit the latest answer drew no control
for, which also dropped options set without a control (a plugin setting a
token budget on the draft). Only an edit of a key an earlier answer for this
draft drew as a control stops applying when a later answer draws none; every
other edit always applies.
* test(server): the MCP test agent manager resolves effective options
* fix(app): a profile stops saving a toggle the model in use does not offer
Switching a profile from Opus to Haiku kept the Fast edit, so the saved
profile carried fast_mode that no control draws and an old daemon's
provider rejects at create. The profile editor now drops a key an earlier
answer drew as a control and the latest one does not, the rule the draft
already follows; options no control ever drew are never touched.
* fix(client): resetting an option on an old daemon writes the default it can take
setAgentOptions({ service_tier: null }) sent a feature write with value
null, which the old Codex setter rejects, leaving the paid Fast tier on.
A toggle now resets to off and a choice to its default; an option with
no control to name a default fails with the host-update message before
anything is written.
* fix(client): applying a config with a reset option on an old daemon writes the default it can take
applyAgentConfig({ options: { service_tier: null } }) reached an old
daemon as featureValues with null, which its Codex setter rejects. The
config now takes the same translation as setAgentOptions: a toggle goes
off, a choice goes to its default, and an option with no named default
fails with the host-update message before anything is sent.
* feat(plugin): provider plugins declare option controls and receive option changes
A provider plugin reports `controls` and the `providerOptions` it runs in
`session.config`, and receives running-session changes as
`session.configure` `changes.providerOptions` (null returns a key to its
default), under the same apply-or-throw contract as built-in providers.
A control may declare a `defaultValue`; a value a plugin reports at that
default for a key nobody set stays unset instead of being pinned to the agent.
A plugin that still reports `settings` keeps working: the daemon reads each
setting as a control plus an option and sends changes in both shapes
(COMPAT(plugin-provider-settings)).
The app resolves a control's icon as a Lucide name when it is not one of the
built-in kebab-case names, so a plugin's icon shows live and in drafts.
Public docs and the provider-direct example use only `providerOptions` and
controls; the migration doc gains the rows.
* fix(server): a plugin provider's reported options are stored like any provider's
A control's `defaultValue` only says what the control shows for a key with no
value. Opening and applying store every option the session reports, defaults
and values nobody set included, as built-in providers do; the special case that
left a value at the default unset is removed.
* fix(server): a plugin decides which options it applies live
A plugin reporting `controls` and `providerOptions` receives every key a live
change touches, with or without a control, and applies them or rejects the
whole request. The daemon's live-key guard now runs only for a plugin still
reporting `settings`, which cannot refuse a key.
* fix(server): a rewound plugin session reopens with its options as they stand
The reopen merged the plugin's reported options over the launch record, so a
key the plugin reset by leaving it out came back at its launch value. The
session now keeps the committed options, removals included. The provider-direct
example also refuses a combined request before changing anything.
* fix(server): a plugin that stops reporting an option has reset it
The adapter only visited keys present in a new report, so a key the plugin
dropped to return to its default kept its stored value and its rewind value.
A previously reported key that disappears is now reported as removed.
* fix(server): an apply reports the options the plugin reset along the way
Applying and unsolicited reports now share one conversion from the plugin's
report to a patch, so a key the plugin stops reporting is a removal on both.
* fix(server): an apply never reads a requested option as one the plugin dropped
A plugin may run an option it never reports. Only a key it reported before can be
reported as removed, and a rewind reopens with the accepted request plus what the
plugin reported back.
* test(server): an apply to a plugin that reports controls sends its changes as provider options
* feat(plugins): agents and workspaces carry plugin metadata
Plugins had nowhere to keep their own data on an agent or workspace, so
Phase 5 and 6 surfaces would each have invented a side store. Both now
hold an opaque Record<string, JsonValue> that Paseo stores, snapshots and
hands to hooks without reading a key.
Set at creation or changed with agent.metadata.update.request /
workspace.metadata.update.request (top-level keys replace, null removes).
Persisted on the agent and workspace records, so it survives a restart.
Reaches agent.create.before (which may add to it), agent.open.before
(read-only), agent.create.after and workspace.create.before/after.
Gated once on server_info.features.entityMetadata; the client throws
"Update the host" instead of sending to a host without it.
* fix(plugins): an agent.open.before result may omit metadata
The result schema required metadata, so a plugin written before metadata
existed that returns its own object instead of spreading the request
failed validation and the session open failed, even for agents with no
metadata. An omitted metadata now means unchanged and is filled back in
from the request so later plugins in the chain still see it; a present
value that differs is still rejected.
The restart test now sets metadata through the PaseoApi handles and
checks that agent.open.before sees the patched value after the restart.
* fix(plugins): omitted metadata in a hook result means unchanged
An agent.create.before hook that returned its own { config, env } dropped
metadata that an earlier hook in the chain had added, because only the
caller's original metadata was restored at the end. The omitted field is
now carried forward at each hook handoff, as agent.open.before already
does.
The agent.open.before result type also required metadata, so an older
TypeScript plugin that returned its own object no longer compiled even
though the daemon accepted it. The result type now makes it optional.
* fix(plugins): omitted metadata in a workspace.create.before result means unchanged
Same handoff as agent.create.before: a legacy hook that returned only
{ source, ... } dropped the caller's metadata and anything an earlier
hook added, and workspace provisioning then defaulted it to {}. The
omitted field is carried forward at each handoff; an explicit {} still
replaces.
* test(server): fixtures for agents and workspaces carry metadata
Agent snapshots and workspace records now always carry metadata, so the
hand-built fixtures and expectations in three existing suites name it.
* docs(plugins): the hook result comment names metadata as the field that stays
* fix(server): reopening a closed agent keeps metadata saved just before
The loader reads the agent record, then queues a resume. A setMetadata
queued ahead of that resume saves a newer record, and the open hooks saw
it, but registration took metadata from the loader's older read and wrote
it back over the saved patch. Registration now uses the metadata read
inside the lifecycle lane.
* docs(server): name the metadata gap when a handle-less agent is recreated on load
* docs(server): the handle-less recreate gap spans the agent.create.before hook
* docs(plugins): an agent.open.before hook starts writes to its own agent without awaiting
An agent.open.before hook that awaits setMetadata (or any write) on the
agent being opened deadlocks: the write joins the agent's lifecycle lane
behind the open, and the open waits on the hook until it times out. The
hooks reference now says so and shows the supported shape, a write
started without awaiting, which runs right after the open.
Deferred, not in this stack: reject such a write immediately instead of
letting the hook time out. The host knows which plugin hook it is
awaiting for the agent and which channel the write arrives on, so the
rejection can be keyed on "this plugin is inside an open hook for this
agent" without cross-process tagging, and an unrelated client's write
would still wait as it does today.
* feat(plugins): composer items and controls in all three composers
A plugin registers a component with addComposerItem and reads and changes the
composer through useComposer(): provider, model, mode, thinking, options,
prompt, attachments and agent metadata. The agent, draft and New workspace
composers provide the same ComposerInput and ComposerAgent halves, so a
command reaches the right model without the plugin knowing which composer
it sits in.
Toggle, Select and Action are drawn by one ComposerControl renderer that
the thinking select and provider option controls now use too. Controls sit in
the toolbar when there is room and become rows in the existing overflow sheet
otherwise, so on a phone they appear in the overflow. Plugin items count in
the density presence so the composer condenses to make room. Model and mode
stay specialized but share the trigger, density and overflow.
Draft metadata is kept locally, sent at creation and reset when the prompt is
sent. PluginAgentSnapshot.metadata, deferred from the metadata phase, lands
here. The unused provider badge is removed.
vitest resolves @floating-ui/react-native to its ESM build: the CJS entry
requires the real react-native, whose Flow sources do not parse.
* fix(plugins): composer commands run on current state, report failures, and reach the overflow sheet
Draft commands read the state captured at render, so a plugin's
`await setProvider(); await setModel()` acted on a stale provider. The draft
form and options are now plain stores that commands read live, and
`setProvider`/`setModel` reject an unavailable provider or a model the loaded
catalog does not list. Draft `options` include the plugin's pending edits.
Shared composer controls own the pending state and show a rejected command as
an error toast, like the built-in controls. Callback payloads are objects
(`{ value }`, `onPress(event)`) so they can grow without breaking plugins.
The overflow sheet's content portals to the app root and lost the composer's
agent, input, toast and query contexts, so plugin items drew nothing in it.
`useComposerSheetBridge` carries them across.
* test(plugins): composer commands tested on the models, overflow sheet in Playwright
The draft composer's command rules (unavailable provider, unlisted model,
edits belonging to the provider the form has now) moved from the React hooks
into the form store and the draft options model. They take the host's catalog
as a plain input, so the command tests run on the real models with no module
mocks and no renderer.
The overflow-sheet test faked the portal it was meant to verify. It is
replaced by a Playwright spec that installs the composer-controls example and
checks its rows in the narrow composer's Features sheet; it fails when the
sheet's context bridge is removed.
* test(plugins): lock draft option ownership without a subscription, name the overflow-sheet steps
The draft option test subscribed the options model to the form, which in the
app happens in a render effect, so it passed without the model observing the
form's provider itself. A case with no subscription now fails when that
observation is removed.
The overflow-sheet spec reads as steps through a helper.
* fix(plugins): composer option resets and model checks match the documented commands
A draft kept `null` as an option value, so `setOptions({ key: null })` sent the null to the
provider and creation failed. A null edit now removes the key from every draft layer, as the patch
does on a running agent. A running agent's `setModel` accepted ids its catalog does not list; it
now rejects them the way a draft does.
The composer controls imported the toast host through the toast context, which pulled the host's
animation module into every module that loads plugins. They use the API-only context instead.
The migration guide's registration table gets the `addComposerItem` row its test requires.
* fix(plugins): draft metadata survives a remount, plugin commands follow the composer lock
Draft metadata was component state while the prompt lived in the draft store, so a composer that
remounted across the compact breakpoint kept its text and lost the plugin's choices. It now lives
in the draft store beside the prompt, is cleared when the draft is sent, and is not cleared when
the prompt is emptied. It is not persisted across app restarts.
While the New workspace composer is creating the agent, the built-in controls are disabled but
plugin controls and commands were not. They read the composer's own lock: Paseo controls render
disabled, and setPrompt, insertText and the agent commands refuse.
The options and metadata a plugin reads are frozen copies, through the same helper the timeline
projection uses. The composer control test mounted components in JSDOM, which the testing rules
ban; it now runs in the browser project.
* fix(plugins): a kept command honors the composer lock, and useAgent metadata is frozen
A plugin action that awaits an RPC holds the composer it was created with. The lock was captured
at that render, so a submit that started meanwhile did not stop its insertText. Commands now ask
the composer whether it is locked when they run.
The agent snapshot a plugin gets from useAgent froze only the outer metadata record. It now uses
the same deep frozen copy as the composer.
* fix(plugins): attachment commands honor the composer lock
The creation request captures the attachments when it starts, so an attachment a plugin added or
removed afterwards was lost or left in the request. They refuse like the prompt commands.
* fix(plugins): a built-in select in the compact sheet keeps its action name
The shared control named every icon-only select by its value ("Speed: Fast"),
including in the compact sheet, where the row already shows the value. The sheet
row is named by its action again ("Select speed"), as before the shared renderer.
* test(app): composer item test installation carries the subscribe main added to InstalledPlugin
Main's plugin streaming (#8527) made subscribe a required field of InstalledPlugin; the
composer item model test builds its own installation and predates it.
* feat(plugins): New workspace items set the branch and workspace metadata
addNewWorkspaceItem mounts a plugin field on the New workspace screen, and
useNewWorkspace() exposes host, project, isolation, base ref, branch and
metadata with commands that follow the composer item rules: they act on the
screen's state when they run, resolve once applied, reject while the screen
is locked, and take JSON payloads. Host and project are read-only because a
command that switched them would unmount the item that called it.
The screen's pickable state (base selection, manual isolation, branch,
metadata) moves into one plain store so pickers and plugin commands write to
the same place; the screen reports derived facts to it on each render. The
branch is sent as source.branchName only for a branch-off worktree, and
metadata on workspace.create.
Items render through ComposerControl with a new "field" surface (badge on
desktop, full-width field when compact). Combobox ships here: Paseo owns the
loading and error states, keeps previous results, and drops superseded
searches.
* fix(plugins): New workspace commands work from mount effects, and branch and base ref match what creation uses
A command called from a New workspace item's mount effect rejected because the
setup model only received its inputs and the pickers' handlers from a passive
effect on the screen, which runs after a child's. The model now takes its
inputs at construction, picks the base and isolation itself, and is refreshed
in a layout effect; the screen supplies the side effects of a pick (the PR
attachment, the remembered isolation) as listeners.
The branch a plugin sets was dropped when no base was resolved, such as on a
detached HEAD, because it was sent only for an explicit branch-off. It now
applies whenever the worktree cuts a new branch, decided in one place that
mirrors the daemon.
baseRef.name was the display-shortened branch name, so setting back what was
read based the worktree on the local branch instead of the origin one. It is
now the exact ref creation uses, and host and baseRef are frozen like project
and metadata.
* fix(plugins): New workspace commands have the same effects as a pick, even from a mount effect
The screen attached the pick side effects (remembering the isolation, syncing the picker's PR
attachment) as listeners in its own useEffect, which runs after a child item's mount effect. A
mount-time setIsolation("worktree") switched the screen but was not saved, and setBaseRef skipped
the attachment sync. The effects are now injected when the setup model is built, so a command and
a pick run the same code from the first render. Closing the picker stays in the picker's handler.
* fix(plugins): a Combobox shows a failed refresh instead of the old results
The query keeps its cached data when a reopened list fails to refresh, so the old items stayed
selectable and the error never showed. A failed search now clears the list so its error shows.
The migration guide maps addNewWorkspaceItem, which its registration-coverage test requires, and
the superseded-search test waits on a later search instead of sleeping.
* fix(plugins): a branch and metadata chosen for one project are not sent for another
The setup model outlives the project and host it was chosen for, so an issue picked for project A
was sent on workspace.create after the user switched to project B. The model now drops the branch
and metadata when the project changes (project ids are host-scoped, so a host switch counts). A
project that is still resolving is not a switch. The base selection is left alone: the built-in
picker keeps a branch pick across a project switch, and that behavior is unchanged.
* test(plugins): the project-switch spec expects the other project's metadata to be empty
* fix(plugins): a host switch drops the branch and metadata even when the project id repeats
A remote repository keeps the same project id on every host, so comparing the project id alone
missed a switch from host A to host B for the same repository. The target is now the host and the
project id together.
* fix(server): a branch the caller named is not renamed from the first agent context
The daemon marked every new branch-off worktree for automatic naming, recording the chosen branch
as the placeholder, so the first agent's prompt could rename a branch a plugin or client had
named through branchName. Only a branch the daemon derived from the worktree slug is a
placeholder now.
* fix(plugins): New workspace items remount when the project or host changes
An item stayed mounted across a project switch, and its Combobox kept the previous project's
results (same query key, cached data) selectable until the next search returned, so an issue from
the old project could set the branch and metadata on the new one. A Combobox cannot detect that
its inline search now means another project, so the item host keys the items by host and project
id. Items and their search results start fresh for the new target, and a mount effect sets up
again after the model clears the branch and metadata.
* docs(plugins): a layout-effect command on mount also races the reset on a project switch
* fix(plugins): a New workspace item's commands stop working once its project or host is left
Every item received the same command functions, which act on the current screen state. A lookup
that finished after the user switched projects could still call setBranch or setMetadata and
overwrite the new project's choices; the reset on a switch only clears what was already written.
The setup model now hands out commands per target with commandsFor({ serverId, projectId }).
They reject with a "moved to another project or host" error when the screen is on another target,
like the lock rejects, so the promise only resolves when the change took effect.
* feat(plugins): reach a running agent's composer by reference
useComposers(selector) in any plugin component and composers(selector) on every command context return the composer of a running agent, named by id or by focus, whether or not its tab is open.
A running agent now has one store-backed composer model apart from any mounted tab. The mounted composer plugs its cursor-aware insert in while mounted; otherwise insertText and setPrompt write the agent's saved prompt. model and thinking resolve through the provider catalog with the picker's own function, so a read equals what the picker shows.
The host reads one ComposerModel from context and no longer knows whether it is in an agent, a draft or New workspace. The daemon rejects an unlisted model or thinking option for a running agent, replacing the app-side guard.
* fix(plugins): composers by reference follow the focused agent and reach retained composers
- `{ focused: true }` is the agent Command Center hands to agent items, published by its
registration through plugins/focused-agent.ts and empty outside a workspace. The composer source
reads that module instead of the remembered workspace selection, the navigation store and the
layout store, which also removes the require cycles those imports added.
- A composer the app retains in a workspace the user left has no live input. `insertText` and
`setPrompt` now store the text with `replaceDraftText`, which asks the mounted input to show it;
before, the text reached the store but the retained input never displayed it.
- `model` and `thinking` read exactly what the picker resolves before the catalog loads (no
models), then re-resolve when it lands, instead of reading null.
- The daemon validates a thinking option against the model the agent runs: the runtime model when
the provider lists it, else the configured one.
- The composer sources subscribe to query-cache updates only. A query another component creates
during its render is announced as `added`, and a subscriber that updates then made React warn
about updating a component while rendering a different one. A catalog read no longer starts its
load synchronously either.
* test(plugins): a Command Center agent item reaches the composer through the real client state
The command-path test now reads workspace and agent through
createPluginClientStateSource over seeded session stores, so an empty
lookup, which makes the Command Center return before calling the item,
would fail it. Also records at the focused-agent publisher that it
publishes in an effect.
* fix(plugins): a running agent's composer validates and refreshes against the agent's own catalog
setAgentModel and setAgentThinkingOption checked the provider's global catalog,
while the picker reads the catalog of the agent's directory, so a model only
the project lists was rejected. The validation input now carries the directory.
The composer read the catalog once with no observer, so reconnect repair, which
refetches only active queries, never refreshed it and a failed load never
retried. While anything watches, the composer now observes the catalog query.
The shared composer map kept every agent's composer for the session. It is now
dropped when nothing watches it and no composer is mounted.
* fix(plugins): useComposers holds the composer it names, and a composer lives as long as its agent
PluginComposersSource.subscribe watched the stores directly and never the
composer model, so a component using useComposers did not keep the model's
catalog observer alive and reconnect repair skipped it. subscribe now takes the
selector and holds the model it names, following focus.
Dropping a composer when it went idle left a command a plugin had saved calling
a dead model after the tab reopened. A composer is now dropped when its agent
leaves the session and nothing watches it or has one mounted.
* fix(plugins): a composer refreshes a stale catalog on resumed demand, shares its store watches, and is released with its last holder
Watching again, or reading once, after the catalog was invalidated or failed
while nothing watched now starts one deduplicated refresh; the observer
refetches on mount. Reconnect repair only refetches watched queries, so an
unwatched catalog stayed stale.
Each subscribe installed its own session and draft store callbacks, so N
watchers received N squared notifications, including for other agents' drafts.
One pair of subscriptions now serves all listeners, and the draft callback
ignores drafts of other agents.
A composer whose agent was removed while it was held was only released on the
next session change. The last holder letting go now checks too, and an archived
agent's idle composer is releasable.
* test(server): live model and thinking switches use values the provider lists
The daemon rejects a model or thinking option its provider does not list, so the live-preferences
e2e can no longer switch to a made-up id. A provider that lists nothing to switch to skips the case.
* test(server): the test providers list two models with thinking options, and the live switches run
The fake providers listed one model and no thinking options, so once the daemon validated
selections against the catalog the live model and thinking switches had nothing valid to switch to
and skipped. Every fake provider now lists two models with thinking options, and the switches run
for all three providers without depending on installed binaries.
* fix(plugins): a retained composer that is not showing takes plugin writes through the draft
On native a retained composer keeps its input mounted under display none, so the ref alone said
the input was live and a plugin insertText replaced the stale selection instead of appending to
the draft. The input is live only while its retained panel is showing.
* test(plugins): the retained input liveness test runs in real Chromium
* fix(plugins): a model or thinking change, an unreported option key, and a draft model reach the provider unchecked
Paseo no longer checks these in front of the provider. A running agent's model or thinking
change no longer waits for the catalog or checks it, a plugin provider is sent every option
key and refuses what it cannot apply, and a draft setModel keeps the id as the model picker
does.
* fix(plugins): a plugin reporting settings is sent every key of an options patch
* Run option, model, thinking and mode changes in the agent's lifecycle lane
The agent manager owns all sequencing for one agent: applyOptions, setModel,
setThinkingOption and setMode now run in the same lane as open, close, archive,
labels and metadata, so a provider session never sees two of them at once.
Provider-side serialization (the applying chains in the ACP, plugin and OpenCode
sessions, and Claude's apply-over-current-options handling) is deleted.
* Reopen a handleless agent inside its lifecycle lane
A stored agent with no resumable session is now reopened by
AgentManager.createAgentFromRecord, which rereads the record inside the agent's
lane before creating the first session. A metadata or label write queued ahead
is in the record it reads; one queued behind applies to the live agent. The
loader no longer passes a record it read outside the lane. createAgent itself
also runs in the lane, like resume.
* Return the draft's options from AgentClient.listControls
listControls now answers { controls, options } like AgentManager.listDraftControls:
the options a session opened from the draft would run with, with config
defaults merged in and anything the provider resolves natively for the ones
nobody set. ACP fills unset feature selects from the probe session's
currentValue, so a fresh Cursor draft shows the Fast selection the agent opens
with instead of no selection. The legacy features response and the MCP draft
listing already project from the manager's result, so they follow.
* Send a profile's options on every write, empty included
The profile form always sends options. The daemon reads a write without them as
one from an app that predates options and folds featureValues over the stored
ones; a write that carries them, empty included, replaces them. A profile left
with no options is stored without the key, so removing the last one persists.
* Read a remembered Codex fast_mode as its service tier
The create-agent preferences convert the legacy key on read, keyed on the
built-in codex provider id, so the Codex draft shows the Fast selection the user
last used. Tagged COMPAT(featureValues) with the other legacy-option shims.
* Document one option change at a time per agent
The agent manager runs option, model, thinking and mode changes in the agent's
lifecycle lane; providers do no sequencing. The hook deadlock warning now covers
agent.create.before and option writes.
* Flatten the profile fold's base selection and drop an unused import
* Carry the New workspace context through portal hosts and the draft's metadata through retry
* Convert legacy options when resolving a stored agent's effective options
* Keep stored-record reads tolerant of a legacy option the conversion rejects
* Keep plugin attachment items separate from the draft's own
* Hand plugin command inputs to the host as its own copies
2954 lines
165 KiB
Markdown
2954 lines
165 KiB
Markdown
---
|
||
title: Plugin reference
|
||
description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands.
|
||
nav: Reference
|
||
order: 49
|
||
category: Plugins
|
||
---
|
||
|
||
# Plugin reference
|
||
|
||
Start with the [plugin quickstart](/docs/plugins) to create your first plugin.
|
||
|
||
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration).
|
||
|
||
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
|
||
|
||
- React Native screens and sidebar header and footer items to Paseo clients;
|
||
- workspace and agent panels opened as workspace tabs;
|
||
- [file panels](#file-panels) for viewing or editing matching files;
|
||
- global, workspace, and agent actions in the Command Center;
|
||
- slash commands in the message composer;
|
||
- transformed and daemon-pushed agent timeline rows;
|
||
- light and dark themes in Settings → Appearance;
|
||
- schema-validated RPC handlers running beside the daemon;
|
||
- normal Paseo operations through the TypeScript SDK;
|
||
- searchable external resources in the message composer.
|
||
|
||
Plugin code is trusted and unsandboxed. Client surfaces run in the Paseo app. Backend contributions run in a subprocess with access to the daemon machine, including its files, processes, credentials, and network.
|
||
|
||
## Connected hosts
|
||
|
||
`usePaseo().hosts` in a client surface and `context.paseo.hosts` in a server handler or lifecycle hook
|
||
use the same [SDK host API](/sdk/reference#clienthosts). They describe the selected daemon's saved
|
||
connections. Existing `useHosts()` and `getPaseoClient(serverId)` keep describing app-known hosts.
|
||
|
||
```ts
|
||
const remote = await context.paseo.hosts.client("srv_build_box");
|
||
try {
|
||
return await remote.workspaces.list();
|
||
} finally {
|
||
await remote.dispose();
|
||
}
|
||
```
|
||
|
||
A returned API owns its observations. Teardown of the plugin API also disposes derived scopes.
|
||
Keep remote calls inside the handler or lifecycle scope that owns them. Calling B does not forward
|
||
B's plugin lifecycle hooks to A. Registrations created by a routed plugin retain a source qualified
|
||
by the authenticated link and originating plugin.
|
||
|
||
## Project files
|
||
|
||
`paseo plugin init /absolute/path/to/my-plugin` creates:
|
||
|
||
```text
|
||
my-plugin/
|
||
paseo-plugin.json
|
||
index.client.tsx
|
||
index.server.ts
|
||
client/greeting.tsx
|
||
server/greeting.ts
|
||
shared/greeting.ts
|
||
package.json
|
||
tsconfig.json
|
||
```
|
||
|
||
The required root manifest is `paseo-plugin.json`:
|
||
|
||
```json
|
||
{
|
||
"id": "my-plugin",
|
||
"description": "Reviews changes before merge",
|
||
"requirements": { "paseo": ">=0.8.0" }
|
||
}
|
||
```
|
||
|
||
| Field | Required | Behavior |
|
||
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `id` | Yes | Default installation ID. |
|
||
| `name` | No | Non-empty display name for the registry, the website, your row in **Settings → Plugins**, and your settings header. Without it, Paseo shows the ID. |
|
||
| `icon` | No | Relative path to a PNG inside the plugin package. |
|
||
| `media` | No | Array of image or video paths inside the package, or HTTPS URLs. An empty array is valid. |
|
||
| `description` | No | Non-empty summary shown below the plugin name in **Settings → Plugins**. |
|
||
| `translations` | No | Listing text in other languages, read by the registry and ignored by Paseo. See [other languages](/docs/plugins/publishing#other-languages). |
|
||
| `requirements` | No | Supported Paseo versions, described below. |
|
||
| `build` | No | Preparation commands, described in the CLI reference. |
|
||
|
||
Paths are relative to `paseo-plugin.json`, use forward slashes, and cannot contain `..`
|
||
segments. Registry listings for visual plugins require an interface image even though `media` is
|
||
optional in the runtime manifest. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots)
|
||
for accepted formats and listing requirements.
|
||
Paseo validates the references without opening local assets or fetching URLs.
|
||
|
||
Unknown top-level fields are ignored. Known fields still validate, and unknown keys inside
|
||
`requirements` are rejected so a misspelled constraint cannot silently skip a compatibility check.
|
||
Manifests using `name`, `icon`, or `media` require Paseo 0.11.0 or later; older daemons reject
|
||
these fields during installation.
|
||
|
||
### Requirements
|
||
|
||
`requirements` is an optional object. Its currently supported key, `paseo`, accepts an npm semver
|
||
range. An omitted `requirements.paseo` means `<0.8.0`: the plugin predates the first breaking
|
||
plugin release. Paseo 0.8 and later reject it with a link to the [migration guide](migration).
|
||
Empty strings, invalid ranges, and unknown manifest requirement keys are rejected.
|
||
|
||
| Range | Compatible releases |
|
||
| ---------------- | ---------------------------------------------------------------------------- |
|
||
| `>=0.8.0` | 0.8.0 and later releases, including prereleases and future breaking releases |
|
||
| `^0.8.0` | 0.8.x releases, including prereleases |
|
||
| `>=0.8.3 <0.9.0` | 0.8.3 through the last 0.8 patch, including prereleases |
|
||
|
||
Prerelease Paseo versions also satisfy a range their stable core (`major.minor.patch`) satisfies, so `0.8.0-beta.1` satisfies `>=0.8.0` but not `<0.8.0`.
|
||
|
||
A prerelease minimum such as `>=0.12.0-beta.4` therefore also admits `0.12.0-beta.3` through its stable core `0.12.0`. Use a different stable core when you need to exclude earlier builds of that core.
|
||
|
||
`paseo plugin init` writes `>=` followed by the current CLI version and pins the matching SDK
|
||
for typechecking. Raise the minimum when adopting a newer API. Add an upper bound when a later
|
||
release is incompatible; a minimum alone does not promise protection from future breaking changes.
|
||
|
||
The daemon checks its version before installing, running preparation commands, or loading a plugin,
|
||
and checks again on startup, enable, and reload. A rejected update keeps the installed revision.
|
||
Each connected app checks its own version before evaluating client code and shows incompatibility
|
||
in Settings → Plugins. A compatible daemon does not make an older app compatible. A plugin with no
|
||
client entry does not require the connected app to match.
|
||
|
||
For example: `Plugin "review" requires Paseo >=0.8.0. Your daemon is 0.7.2.` Use a compatible plugin
|
||
revision or update the named runtime. Releases before 0.8 do not understand this manifest field
|
||
and cannot show this new diagnostic.
|
||
|
||
### Runtime entries
|
||
|
||
| Entry | Runtime | Receives | Required |
|
||
| ------------------ | --------------------- | --------------------- | ------------------------------------------------------------------------------- |
|
||
| `index.client.tsx` | Paseo app, per client | `PluginClientContext` | When the plugin has any UI, callback, theme, or attachment source |
|
||
| `index.server.ts` | Daemon subprocess | `PluginServerContext` | When the plugin contributes handlers, hooks, settings persistence, or providers |
|
||
|
||
At least one entry is required; both accept `.ts` or `.tsx`. A directory that still has only the
|
||
old `index.ts` fails to load and points at the [migration guide](/docs/plugins/migration).
|
||
|
||
Plugin, screen, sidebar-item, workspace-panel, Command Center item, attachment-source, and
|
||
slash-command IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.
|
||
|
||
The generated `package.json` installs `@getpaseo/plugin` and the other host modules as development
|
||
dependencies for local typechecking and tests. Paseo supplies their runtime instances. Consumers do
|
||
not install them when adding the plugin.
|
||
|
||
Every other module lives in one of three directories. Nesting inside them is fine; a module at the
|
||
plugin root is a compile error.
|
||
|
||
| Directory | Compiled into | Use it for |
|
||
| --------- | ------------------ | -------------------------------------------------------------------- |
|
||
| `client/` | App bundle only | React, React Native, hooks, styles, surfaces, panels, and callbacks. |
|
||
| `server/` | Daemon bundle only | Node APIs, local resources, credentials, and RPC handlers. |
|
||
| `shared/` | Both | Zod RPC contracts and plain values imported by both runtimes. |
|
||
|
||
## Runtime translations {#runtime-translations}
|
||
|
||
**Unreleased API.** Set `requirements.paseo` to the release that introduces these APIs before publishing your plugin. The [translation example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/translations) uses `>=0.12.1` provisionally; the introducing release has not been assigned.
|
||
|
||
Ship JSON resources with your client bundle. English (`en`) is required; other keys use canonical language tags such as `zh-CN`. Resources contain nested objects with string leaves. Other languages may omit keys, which fall back to English. Unknown keys, malformed resources, noncanonical locale tags, and mismatched interpolation placeholders are rejected when defining translations.
|
||
|
||
```ts
|
||
// client/messages.ts
|
||
import { defineTranslations } from "@getpaseo/plugin/client";
|
||
import en from "./locales/en.json";
|
||
import zhCN from "./locales/zh-CN.json";
|
||
|
||
export const messages = defineTranslations({ resources: { en, "zh-CN": zhCN } });
|
||
```
|
||
|
||
Enable `resolveJsonModule` in your plugin's `tsconfig.json`. Paseo bundles these imports locally; no network loader runs. For example, the resource pair can contain:
|
||
|
||
`client/locales/en.json`:
|
||
|
||
```json
|
||
{
|
||
"title": "Workspace notes",
|
||
"add": "Add note",
|
||
"notes_one": "{{count}} note",
|
||
"notes_other": "{{count}} notes"
|
||
}
|
||
```
|
||
|
||
`client/locales/zh-CN.json`:
|
||
|
||
```json
|
||
{
|
||
"title": "工作区笔记",
|
||
"add": "添加笔记",
|
||
"notes_other": "{{count}} 条笔记"
|
||
}
|
||
```
|
||
|
||
Call the plugin hook in React UI:
|
||
|
||
```tsx
|
||
import { useTranslation } from "@getpaseo/plugin/client";
|
||
import { Text } from "react-native";
|
||
import { messages } from "./messages";
|
||
|
||
function NoteCount({ count }: { count: number }) {
|
||
const { t, locale } = useTranslation(messages);
|
||
return <Text accessibilityLanguage={locale}>{t("notes", { count })}</Text>;
|
||
}
|
||
```
|
||
|
||
Use `messages.message(key, options?)` for persistent host-rendered labels:
|
||
|
||
```tsx
|
||
client.addScreen({
|
||
id: "notes",
|
||
title: messages.message("title"),
|
||
Component: Notes,
|
||
});
|
||
```
|
||
|
||
`PluginText` is `string | PluginMessage`. Message references work in screen titles (including title functions), settings and sidebar titles, workspace and file panel titles, Command Center titles, slash-command descriptions and argument hints, button titles and labels, nested menu titles, attachment-source titles/picker titles/search placeholders, and theme names. Existing literal strings remain valid. Keep IDs, slash-command names, icons, URLs, and command search keywords stable.
|
||
|
||
Descriptor types keep their existing string defaults. When explicitly annotating translated descriptors, use the text parameter, for example `PluginScreenContribution<PluginText>`. Inline registrations infer this automatically.
|
||
|
||
For transient text in callbacks, call `client.i18n.t(messages, "add")`; it reads the app's current language at invocation. `client.i18n.locale` and the hook's `locale` report the resolved app language even when a message falls back to English. Do not store the result of `t` as a persistent registration label.
|
||
|
||
Keys come from English. Plural base keys such as `notes` require a numeric `count`; i18next selects the locale's `_zero`, `_one`, `_two`, `_few`, `_many`, or `_other` form. Use `{{name}}` for named interpolation and pass `{ name: value }`. JSON string values are widened by TypeScript, so interpolation names from imported JSON are checked at runtime; inline literal resources also infer required interpolation names. i18next formatting syntax such as `{{amount, number}}` uses the resolved language's `Intl` formatter.
|
||
|
||
An explicit app language wins over the device language; System follows the app's supported-locale resolution. Separate connected apps have independent languages. Changing language updates mounted UI and host labels without reloading the plugin, resetting component state, or replacing its RPC/query cache. Modal and popover content receives the same installation context on web and native.
|
||
|
||
Return language-neutral structured RPC data and translate its presentation in the client. Keep user drafts, agent output, raw daemon errors, logs, and terminal text unchanged. Manifest listing translations and `OVERVIEW.<locale>.md` are separate publication metadata; see [your listing page](publishing#your-listing-page).
|
||
|
||
## Runtime modules
|
||
|
||
Paseo builds each bundle from its matching entry. An import from `client/` into the daemon bundle,
|
||
from `server/` into the app bundle, or of a Node module anywhere in the app bundle is a compile
|
||
error. Server imports of React, React Native, or client SDK entries also fail. Shared code imports
|
||
only shared code: no Node, React, runtime-specific SDK entries, or runtime-specific types.
|
||
|
||
The SDK root (`@getpaseo/plugin`) contains shared data, schemas, and runtime-neutral helpers only.
|
||
Import client contexts and hooks from `/client`, server contexts and lifecycle contracts from
|
||
`/server`, and UI from `/client/ui`. These rules include type imports and transitive
|
||
dependencies. `/client/host` is private to the app host; plugins cannot import it.
|
||
|
||
### Client runtime
|
||
|
||
Paseo provides these modules to client code:
|
||
|
||
| Module | Use it for |
|
||
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
|
||
| `@getpaseo/plugin` | Shared data, `defineRpc`, `defineSettings`, `defineAttachmentSource`, `RpcInput`, and `RpcOutput` |
|
||
| `@getpaseo/plugin/client/ui` | Paseo UI components and UI hooks |
|
||
| `@getpaseo/plugin/client` | Client contribution contexts, `usePaseo`, `useRpc`, `useSettings`, and data hooks |
|
||
| `@tanstack/react-query` | Request state and caching |
|
||
| `react` | Components and hooks |
|
||
| `react/jsx-runtime` | Compiled JSX |
|
||
| `react-native` | Cross-platform UI |
|
||
| `zod` | Shared schemas |
|
||
|
||
The host owns its paired React and renderer versions. The SDK's React peer range permits patch
|
||
versions for tooling and Node consumers; it does not change the app's pinned React version or
|
||
guarantee compatibility with another host's renderer.
|
||
|
||
These exact module specifiers use the host's runtime instances. A client bundle that requests another host module fails with `Module "<name>" is not available in plugin client code`.
|
||
|
||
Do not import `lucide-react-native`, `react-native-svg`, or DOM libraries. Set contribution `icon` fields to a [Lucide icon name](https://lucide.dev/icons/), inline SVG, or a component; Paseo validates the icon and renders it. See [Icons](#icons).
|
||
|
||
### Cross-platform rules
|
||
|
||
Client code runs on iOS, Android, and in browsers through React Native Web. A component that works
|
||
in your browser and crashes on a phone is the most common plugin bug. The rules:
|
||
|
||
| Do | Do not |
|
||
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||
| `View`, `Text`, `Pressable`, `ScrollView`, `TextInput` from `react-native` | `<div>`, `<span>`, `<button>`, or any HTML element |
|
||
| `style` objects built from `theme.colors` and `layout.compact` | `className`, CSS strings, or hardcoded colors |
|
||
| `onPress` | `onClick`, `onMouseEnter`, or other DOM handlers |
|
||
| `Linking`, `Clipboard`-style React Native APIs | `window`, `document`, `localStorage`, `navigator`, `location` in components |
|
||
|
||
The scaffold's `tsconfig.json` omits the DOM library. Keep DOM globals out of cross-platform
|
||
components; do not add `/// <reference lib="dom" />` or `"DOM"` to `lib`.
|
||
`layout.platform` carries the same value as React Native's `Platform.OS` for rendering decisions.
|
||
|
||
### Play audio
|
||
|
||
Call `client.playAudio({ base64, mimeType }): Promise<void>` to play an audio file on the
|
||
current client (browser, Electron, iOS, or Android). Pass the base64 file returned by your
|
||
plugin RPC; no browser globals or platform checks are needed.
|
||
|
||
```ts
|
||
const audio = await client.rpc(renderSpeech, { text: "Your agent needs you" });
|
||
// renderSpeech returns { base64: string, mimeType: "audio/wav" }.
|
||
await client.playAudio(audio);
|
||
```
|
||
|
||
The promise resolves when playback finishes and rejects if the file is invalid, playback
|
||
fails, or the plugin unloads. Calls share Paseo's voice playback queue and play in order.
|
||
Unloading a plugin cancels its active and queued audio. Voice playback controls can also
|
||
interrupt that shared queue. Playback does not request microphone permission.
|
||
|
||
Use PCM WAV or MP3 for portable files. Other codecs depend on the client's decoder.
|
||
MIME parameters are accepted. Pass a complete audio file; raw PCM samples are not supported.
|
||
Browsers require user interaction before allowing sound; handle rejection and offer a
|
||
play button. The function plays on the device running the plugin client, not on the daemon,
|
||
and does not promise delivery while the app is suspended or closed.
|
||
|
||
### External links and workspace browsers
|
||
|
||
Use `ExternalLink` to open documentation outside Paseo:
|
||
|
||
```tsx
|
||
import { ExternalLink } from "@getpaseo/plugin/client/ui";
|
||
|
||
export function DocumentationLink() {
|
||
return <ExternalLink href="https://paseo.sh/docs">Open documentation</ExternalLink>;
|
||
}
|
||
```
|
||
|
||
The component has accessible link semantics and uses the same opener as
|
||
`openExternalUrl(url: string): Promise<void>`:
|
||
|
||
```ts
|
||
import { openExternalUrl } from "@getpaseo/plugin/client";
|
||
|
||
export async function openDocumentation() {
|
||
await openExternalUrl("https://paseo.sh/docs");
|
||
}
|
||
```
|
||
|
||
Call the function directly from a user interaction so the browser permits a new tab.
|
||
|
||
| Platform | External links | `navigation.openBrowser` |
|
||
| ------------- | ---------------------------------- | ------------------------------------------------ |
|
||
| Electron | System browser | Available; creates a local workspace browser tab |
|
||
| Browser web | New tab with `noopener,noreferrer` | `undefined` |
|
||
| iOS / Android | OS URL handler | `undefined` |
|
||
|
||
#### ExternalLink props
|
||
|
||
| Prop | Required | Behavior / default |
|
||
| ------------------------------- | -------- | ------------------------------------------------------ |
|
||
| `href: string` | Yes | Absolute HTTP(S) destination |
|
||
| `children: ReactNode` | Yes | Link text or inline React Native content |
|
||
| `accessibilityLabel: string` | No | Overrides the accessible name derived from the content |
|
||
| `testID: string` | No | Test identifier; unset by default |
|
||
| `onError(error: unknown): void` | No | Receives opening errors; defaults to logging them |
|
||
|
||
#### Open a workspace browser
|
||
|
||
Use `navigation.openBrowser` from a surface or panel. Check availability before rendering
|
||
the action. This workspace panel chooses an external link on other platforms:
|
||
|
||
```tsx
|
||
import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
|
||
import { ExternalLink } from "@getpaseo/plugin/client/ui";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
export function DocumentationPanel({ navigation, workspaceId, theme }: PluginWorkspacePanelProps) {
|
||
const openBrowser = navigation?.openBrowser;
|
||
const url = "https://paseo.sh/docs";
|
||
|
||
if (!openBrowser) {
|
||
return <ExternalLink href={url}>Open documentation</ExternalLink>;
|
||
}
|
||
|
||
return (
|
||
<Pressable accessibilityRole="button" onPress={() => openBrowser({ url, workspaceId })}>
|
||
<Text style={{ color: theme.colors.foreground }}>Open in workspace browser</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
```
|
||
|
||
`navigation.openBrowser({ url, workspaceId, serverId? }): void` creates and focuses a new tab.
|
||
It never opens externally as an automatic fallback.
|
||
|
||
| Option | Required | Behavior / default |
|
||
| --------------------- | -------- | ----------------------------------------------------------------- |
|
||
| `url: string` | Yes | Absolute HTTP(S) destination |
|
||
| `workspaceId: string` | Yes | Workspace already present in the target host's app workspace list |
|
||
| `serverId: string` | No | Defaults to the surface or panel's selected host |
|
||
|
||
To target another host, pass its ID with that host's workspace ID:
|
||
|
||
```ts
|
||
openBrowser({ url, workspaceId: remoteWorkspaceId, serverId: remoteServerId });
|
||
```
|
||
|
||
`serverId` selects workspace ownership. The page runs on your local desktop, including
|
||
for remote workspaces; `localhost` URLs refer to that desktop.
|
||
|
||
#### Errors and refusal
|
||
|
||
| Condition | Result |
|
||
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||
| External URL is malformed or uses a non-HTTP(S) scheme | Ignored; `openExternalUrl` resolves without opening anything |
|
||
| OS opener fails | `openExternalUrl` rejects; `ExternalLink` calls `onError` or logs the error |
|
||
| Browser blocks a new external tab | Cannot be distinguished from a successful `noopener` open |
|
||
| In-app browser URL is malformed or uses a non-HTTP(S) scheme | Throws `Only absolute HTTP(S) URLs are supported.` before creating a tab |
|
||
| In-app browser workspace ID is empty | Throws `workspaceId is required.` before creating a tab |
|
||
| Target host/workspace is unknown or its workspace list has not loaded | Throws `Workspace is unavailable on the requested host.` before creating a tab |
|
||
|
||
Use the [settings API](#settings-screens) for typed host-scoped persistence across clients.
|
||
Use `openSettings`, `openScreen`, and `openPanel` for your own registered contributions.
|
||
|
||
### Server runtime
|
||
|
||
Paseo provides `@getpaseo/plugin`, `@getpaseo/plugin/server`,
|
||
`@getpaseo/plugin/server/provider`, `@getpaseo/plugin/server/acp`, and `zod` to server code. Backend
|
||
contributions run in a daemon subprocess with Node access to the host machine. Keep filesystem,
|
||
process, credential, and other machine-local work under `server/`. A plugin without
|
||
`index.server.ts` starts no subprocess.
|
||
|
||
### Providers
|
||
|
||
Follow [Build a provider plugin](/docs/plugins/providers) for direct and ACP implementations,
|
||
session lifecycle, option controls, timeline renderers, testing, and distribution.
|
||
|
||
Call `server.registerProvider()` with a `ProviderRegistration` from
|
||
`@getpaseo/plugin/server/provider`. Its connection accepts inputs with `send()` and emits complete state
|
||
snapshots through `onEvent()`. `send()` reports acceptance only; prompt disposition, turns,
|
||
configuration, persistence, permissions, and failures are events.
|
||
|
||
Use the single `session.prompt` input for messages, structured commands, steering, and command side
|
||
effects. Repeat `clientMessageId` on the live user timeline item and publish exactly one matching
|
||
`session.prompt_result`. Publish provider-created children as sessions with `parentSessionId`.
|
||
|
||
Provider options are one record, `ProviderSessionConfig.providerOptions` on `session.open`. It
|
||
includes configured defaults and per-agent overrides; validate and apply it in your provider. Report
|
||
`controls` in `session.config` for the top-level keys that get a toggle or select in the composer,
|
||
with the values the session runs under `providerOptions`. A running-session change arrives as
|
||
`session.configure` with `changes.providerOptions`. See [Provider options](/docs/sdk/provider-options)
|
||
for configuration and merge semantics.
|
||
Host tools arrive as MCP servers in the complete
|
||
session config.
|
||
|
||
Paseo refreshes an agent by closing its current provider session and opening it with current
|
||
configuration and persistence. Providers re-read external state during `session.open`.
|
||
|
||
Use `runAcpProvider()` from `@getpaseo/plugin/server/acp` to adapt a command-backed ACP. Add transformer
|
||
hooks only for a vendor's discovery, configuration, notification, or tool-call differences.
|
||
|
||
`ProviderRegistration.icon` is a file path relative to the plugin directory, such as `icon.svg`.
|
||
It must resolve inside that directory to a regular file that follows the
|
||
[SVG icon rules](#svg-rules). Paseo reads and validates the file when the plugin starts; the string
|
||
is never inline SVG or a URL.
|
||
|
||
### Usage sources
|
||
|
||
**Requires Paseo 0.11.** Register a source from your server entry with
|
||
`server.registerUsageSource()`. Import its contract and helpers from
|
||
`@getpaseo/plugin/server/usage`.
|
||
|
||
A source implements two calls:
|
||
|
||
```ts
|
||
interface UsageAccount {
|
||
key: string;
|
||
label?: string;
|
||
harness?: string;
|
||
input: JsonValue;
|
||
}
|
||
|
||
type UsageScope =
|
||
| { kind: "global" }
|
||
| { kind: "session"; provider: string; model?: string; env: Record<string, string> };
|
||
|
||
interface UsageSourceRegistration {
|
||
id: string;
|
||
label: string;
|
||
icon?: string;
|
||
input: ZodType;
|
||
discover(scope: UsageScope): Promise<UsageAccount[]>;
|
||
fetch(input: unknown): Promise<UsageReport>;
|
||
}
|
||
|
||
type UsageReport =
|
||
| {
|
||
status: "available";
|
||
planLabel?: string;
|
||
windows: UsageWindow[];
|
||
balances?: UsageBalance[];
|
||
details?: UsageDetail[];
|
||
}
|
||
| { status: "unavailable"; problem: UsageProblem }
|
||
| { status: "error"; error: string };
|
||
|
||
type UsageProblem =
|
||
| { kind: "expired"; expiresAt: string; refreshedBy?: string }
|
||
| { kind: "rejected"; status: number; refreshedBy?: string }
|
||
| { kind: "no_quota"; detail: string };
|
||
```
|
||
|
||
Session discovery returns only the login that agent runs on. The agent popover uses only those
|
||
inputs; it never tries logins from global discovery or other agents. For any other provider,
|
||
return `[]`. Global discovery lists every account, including expired logins.
|
||
|
||
Resolve the session account from that session's launch environment. Return `[]` when no login exists.
|
||
Never scan default stores from session discovery or scan agents from global discovery. Discovery is a query, with no agent
|
||
lifecycle hooks. Closed agents have no session scope until resumed.
|
||
|
||
Inputs name credential stores; never put credentials in inputs or reports. Paseo validates each
|
||
input against your schema before calling `fetch()`. The same key in any scope is the same report;
|
||
fetches share a five-minute cache only when their ordered login inputs match. Each login fetch
|
||
has a 20-second deadline.
|
||
|
||
Built-in session routes:
|
||
|
||
| Source | Session | Login store |
|
||
| ---------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| Claude | `claude` | `CLAUDE_CONFIG_DIR`, or the default; on macOS, the directory's Keychain entry takes precedence |
|
||
| Claude | `pi`, `omp` with `anthropic/…` model | That harness's Anthropic login store |
|
||
| Codex | `codex` | `CODEX_HOME/auth.json`, or the default |
|
||
| Codex | `pi`, `opencode`, `omp` with `openai/…` model | That harness's OpenAI login store |
|
||
| Cursor | `cursor` | cursor-agent's `auth.json` for that session's `XDG_CONFIG_HOME`, `APPDATA`, or home directory |
|
||
| Muse | `muse` | That session's own Muse launch/config |
|
||
| Other built-in sources | Any | No session discovery |
|
||
|
||
Claude excludes Bedrock, Vertex, and foreign `ANTHROPIC_BASE_URL` sessions. Codex excludes sessions
|
||
with `OPENAI_BASE_URL` set. Cursor excludes sessions that authenticate with `CURSOR_API_KEY` or
|
||
`CURSOR_AUTH_TOKEN`, and macOS sessions that keep the login in the Keychain, the default unless
|
||
`AGENT_CLI_CREDENTIAL_STORE=file`.
|
||
|
||
Use a stable account key: 1–128 characters from `[A-Za-z0-9._-]`. It identifies the account or
|
||
organization whose quota is metered and survives token rotation. Never use a credential or raw
|
||
email as the key. Use `hashAccountKey()` for sensitive stable identities or a store locator when
|
||
account metadata is unavailable. Labels can name accounts without becoming their identity.
|
||
|
||
Return logins in preference order and set `harness` to the owning harness's display name, such as
|
||
Codex, OpenCode, Pi, or OMP. The daemon treats inputs as opaque and never derives labels from them.
|
||
|
||
The host-wide Usage modal groups logins with the same key into one account card and tries them
|
||
concurrently, preferring the discovery order when selecting a result. If any login returns
|
||
`available`, it shows usage with no errors. If all fail, it shows
|
||
every login's error on a separate line with its harness label and its own remedy.
|
||
Discovery failures are logged by the daemon and produce no card.
|
||
|
||
Window names must come from provider data: an explicit duration, a named API field such as
|
||
`five_hour` or `weekly`, or the provider's own period name. Response slots and reset countdowns
|
||
do not establish duration. When the provider omits it, use a neutral name such as “Rolling” or
|
||
“Primary limit” and explain the missing metadata next to the adapter.
|
||
|
||
For numeric durations, use `windowFromReportedDuration()` from
|
||
`@getpaseo/plugin/server/usage` (Paseo 0.11+). Pass the reported seconds or `null`, a neutral
|
||
`unknown` identity and name, and an optional stable quota `scope`. The helper derives the ID,
|
||
label, and short label together; it accepts no duration-label override. For named API periods,
|
||
use `windowFromUsedPct()` with names justified by that field.
|
||
|
||
A window ID identifies a quota scope and period, never its response position, utilization, or
|
||
reset instant. Scope model-specific quotas by the provider's stable feature ID, falling back to
|
||
the reported limit name when no ID exists. Preserve IDs across slot moves and display-name
|
||
changes. Do not alias an old ambiguous ID to a different period: saved pins match source and
|
||
window IDs across all accounts, so users must select the corrected window again.
|
||
|
||
`summary: true` selects source defaults until the user customizes pins. The app computes one
|
||
effective selection for cards, the sidebar, and toggles. The first edit snapshots those defaults;
|
||
an explicit empty selection stays empty.
|
||
|
||
Re-read the selected store in `fetch()` so the CLI's token rotations take effect. Never redeem
|
||
refresh tokens or write credential stores: refreshing elsewhere can invalidate the CLI's copy,
|
||
and rewriting parsed files can discard fields you do not model. If the store disappeared after
|
||
discovery, throw; the card shows the error until the next discovery removes it.
|
||
|
||
Use `unavailable(problem)` to explain why an existing login cannot supply quota. It requires a
|
||
problem; there is no zero-argument form. `expiresAt` is an ISO timestamp. A rejected login carries
|
||
the upstream HTTP status. `refreshedBy` is a CLI name, such as `claude`, `codex`, `opencode`, `omp`, or
|
||
`pi`. Paseo owns the remedy sentence. Do not put instructions or user-facing sentences in that
|
||
field. For `no_quota`, `detail` is displayed verbatim.
|
||
|
||
```ts
|
||
import { z } from "zod";
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { hashAccountKey, unavailable } from "@getpaseo/plugin/server/usage";
|
||
import { findLoginStores, readLogin, readQuota } from "./server/logins";
|
||
|
||
const input = z.object({ path: z.string() }).strict();
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.registerUsageSource({
|
||
id: "example-usage",
|
||
label: "Example",
|
||
icon: "icon.svg",
|
||
input,
|
||
discover: async () =>
|
||
(await findLoginStores()).map((path) => ({
|
||
key: hashAccountKey(path),
|
||
input: { path },
|
||
})),
|
||
fetch: async (value) => {
|
||
const { path } = input.parse(value);
|
||
const login = await readLogin(path);
|
||
if (login.expiresAt <= Date.now())
|
||
return unavailable({
|
||
kind: "expired",
|
||
expiresAt: new Date(login.expiresAt).toISOString(),
|
||
refreshedBy: "example",
|
||
});
|
||
return readQuota(login);
|
||
},
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Built-in Claude discovery prefers the macOS Keychain login and uses the Claude Code credential
|
||
file only when Keychain is empty. `CLAUDE_CONFIG_DIR` selects that file's directory. Fresh tokens
|
||
use the OAuth profile's account and organization IDs; expired or rejected profiles use a locator
|
||
hash. Codex prefers Codex CLI, OpenCode, Pi, then OMP and groups by the ChatGPT account ID from stored
|
||
metadata or JWT claims. Pi and OMP logins remain discoverable when expired. OMP requires
|
||
`node:sqlite`.
|
||
|
||
`usage.list_reports` discovers accounts when called without IDs. With IDs, it refreshes known
|
||
accounts without rediscovering identity. If a store switches accounts, the existing card shows the
|
||
new login's quota until the next discovery. Reports are cached for five minutes; `forceRefresh`
|
||
bypasses that cache. Entries carry `id`, `account.label`, and `fetchedAt`. Failed accounts also carry optional
|
||
`loginErrors` entries with `harness` and each login's failed `report`. Clients gate the feature
|
||
on `server_info.features.usageSources`. The older `provider.usage.list` RPC maps the same reports
|
||
for 0.10 clients and renders problems into its `error` string.
|
||
|
||
The source icon is a file path with the same rules as a provider icon.
|
||
|
||
## Entry point and cleanup
|
||
|
||
Each present entry default-exports one contribution function and returns cleanup. Client entries
|
||
receive `PluginClientContext`; server entries receive `PluginServerContext`. Client registration methods return idempotent removers, except header buttons and composer pills,
|
||
which return `{ update, remove }` handles. The entry cleanup runs before Paseo removes remaining registrations.
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { Main } from "./client/main";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "My plugin", Component: Main });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Reload, disable, and removal dispose the affected installation. Stopping a server plugin also closes its daemon session and stops its subprocess. Client installations follow [Hosts and lifecycle](#hosts-and-lifecycle), including retention during a temporary disconnect.
|
||
|
||
## Lifecycle hooks
|
||
|
||
Register async handlers with `server.addHook(name, handler)`. See [Hooks](/docs/plugins/hooks) for names, payloads, ordering, errors, and complete examples.
|
||
|
||
## Sidebar views
|
||
|
||
`addSidebarView({ id, title, description?, Component })` registers an optional replacement for the
|
||
sidebar content region. It returns cleanup. The user selects one view in Settings > Sidebar;
|
||
registration does not activate it. See [Build a sidebar view](sidebar-views.md) for the props,
|
||
ref-based queries and actions, device state and theme tokens.
|
||
|
||
## Screens and sidebar items
|
||
|
||
A screen is a full page of plugin UI. A sidebar item is a component Paseo renders in the sidebar
|
||
header or footer; it decides what a press does. Register the screen, then an item that opens it:
|
||
|
||
`client/main.tsx`:
|
||
|
||
```tsx
|
||
import type { PluginScreenProps } from "@getpaseo/plugin/client";
|
||
import { useMemo } from "react";
|
||
import { Text, View } from "react-native";
|
||
|
||
export function Main({ theme, host, layout }: PluginScreenProps) {
|
||
const styles = useMemo(
|
||
() => ({
|
||
screen: {
|
||
flex: 1,
|
||
padding: layout.compact ? 16 : 24,
|
||
backgroundColor: theme.colors.surface0,
|
||
},
|
||
title: { color: theme.colors.foreground },
|
||
detail: { color: theme.colors.foregroundMuted },
|
||
}),
|
||
[theme, layout.compact],
|
||
);
|
||
return (
|
||
<View style={styles.screen}>
|
||
<Text style={styles.title}>{host.label}</Text>
|
||
<Text style={styles.detail}>{layout.platform}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`:
|
||
|
||
```tsx
|
||
import type { PluginClientContext, PluginSidebarItemProps } from "@getpaseo/plugin/client";
|
||
import { SidebarRow } from "@getpaseo/plugin/client/ui";
|
||
import { Main } from "./client/main";
|
||
|
||
function MainItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
|
||
return (
|
||
<SidebarRow
|
||
icon="Blocks"
|
||
active={currentScreen?.screenId === "main"}
|
||
onPress={() => openScreen({ screenId: "main" })}
|
||
/>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "My plugin", Component: Main });
|
||
client.addSidebarHeaderItem({ id: "main", title: "My plugin", Component: MainItem });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`PluginScreenProps` contains:
|
||
|
||
| Field | Meaning |
|
||
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `theme` | Typed `PluginTheme` color tokens for the active Paseo theme. |
|
||
| `host` | Selected host `id` and display `label`. |
|
||
| `layout` | `compact` and the `ios`, `android`, or `web` platform. |
|
||
| `params` | The params the screen was opened with, as string keys and values. `{}` when none. |
|
||
| `navigation` | Optional client navigation. `openAgent({ agentId, serverId? })` and `openWorkspace({ workspaceId, serverId? })` open targets on `serverId`, or on the selected host when omitted. `openBrowser({ url, workspaceId, serverId? })` is available only on Electron; see [links and browsers](#external-links-and-workspace-browsers). |
|
||
|
||
Paseo owns the route, header, close action, host picker, error boundary, and query client. The plugin owns the screen body.
|
||
|
||
`addScreen({ id, title, Component })` registers a screen. `title` is the screen header's title: a
|
||
[display text](#runtime-translations), or a function that takes the screen's params and returns
|
||
display text. The function runs again when params or language change. Invalid or empty literal
|
||
titles are rejected. A title function that throws or resolves to an empty string shows the screen
|
||
ID instead; the screen still renders.
|
||
|
||
`openScreen({ screenId, params })` opens a screen with params, such as the bot a bot screen shows.
|
||
Params live in the screen's URL query, so a reload, back and forward, and a link to the screen keep
|
||
them. Any string key works; values must be strings, and anything else throws. Opening the same
|
||
screen with other params shows the new params.
|
||
|
||
### Sidebar items
|
||
|
||
`addSidebarHeaderItem` adds a row to the list at the top of the sidebar. `addSidebarFooterItem`
|
||
adds a row to the footer, between **Add project** and the footer's icon row. The icon row is fixed;
|
||
plugins can't add to it. Both take `{ id, title, Component }`. `title` labels the item in
|
||
Settings > Sidebar, where users reorder and hide items, and is the default label and accessibility
|
||
label of `SidebarRow`. Settings shows a generic plugin icon for these items; a row from the
|
||
deprecated `addSidebarItem` keeps its registered icon.
|
||
|
||
With the plugin on several hosts, an item renders from the host of the screen the app shows. Off a
|
||
host's screens, it uses the host last picked in one of the plugin's screens or last opened from one
|
||
of its items, else the first host.
|
||
|
||
`Component` receives `PluginSidebarItemProps`:
|
||
|
||
| Field | Meaning |
|
||
| ------------------------- | --------------------------------------------------------------------------------------------- |
|
||
| `theme`, `host`, `layout` | As in `PluginScreenProps`. |
|
||
| `currentScreen` | `{ screenId, params }` of this plugin's screen open on the item's host, or `null`. |
|
||
| `openScreen(input)` | Opens one of this plugin's screens: `{ screenId, params? }`. Unknown screen IDs throw. |
|
||
| `openPopover(Content)` | Opens `Content` anchored to the pressed row on wide layouts and as a bottom sheet on compact. |
|
||
|
||
`Content` receives `theme`, `host`, `layout`, `close()`, and `openScreen(input)`. Opening a screen
|
||
closes the popover.
|
||
|
||
Render the item with the sidebar kit from `@getpaseo/plugin/client/ui`:
|
||
|
||
| Component | Props and behavior |
|
||
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `SidebarRow` | Required `onPress`; optional `icon` (any [icon](#icons) form), `label`, `active`, `trailing`, `id`. A full-width row. `trailing` renders beside the row's pressable, so a button in it presses on its own; a press elsewhere in it presses the row. `id` tells rows of one item apart in test IDs. |
|
||
| `SidebarSeparator` | No props. The sidebar's separator line, between groups of rows. |
|
||
|
||
A popover anchors to the row that was pressed, whether the press landed on the row or on its
|
||
`trailing` content, so a per-row "More" button opens its popover next to its own row.
|
||
|
||
```tsx
|
||
import type { PluginSidebarItemProps, PluginPopoverProps } from "@getpaseo/plugin/client";
|
||
import { SidebarRow } from "@getpaseo/plugin/client/ui";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
function SyncDetails({ theme, close, openScreen }: PluginPopoverProps) {
|
||
return (
|
||
<Pressable onPress={() => openScreen({ screenId: "sync" })}>
|
||
<Text style={{ color: theme.colors.foreground }}>Open sync history</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
|
||
function SyncItem({ openPopover }: PluginSidebarItemProps) {
|
||
return <SidebarRow icon="RefreshCw" onPress={() => openPopover(SyncDetails)} />;
|
||
}
|
||
|
||
client.addSidebarFooterItem({ id: "sync", title: "Sync", Component: SyncItem });
|
||
```
|
||
|
||
An item that throws renders nothing; the rest of the sidebar keeps working.
|
||
|
||
#### Several rows in one item
|
||
|
||
An item's `Component` may return a fragment, an array, or `null`, so one item can render a list
|
||
that changes at runtime. Settings lists the item once, and it moves and hides as one block. This
|
||
item shows a row per bot and opens the bot's screen with its ID as a param:
|
||
|
||
```tsx
|
||
import type {
|
||
PluginClientContext,
|
||
PluginScreenProps,
|
||
PluginSidebarItemProps,
|
||
} from "@getpaseo/plugin/client";
|
||
import { SidebarRow, SidebarSeparator } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
import { botName, useBots } from "./client/bots";
|
||
|
||
function BotScreen({ theme, params }: PluginScreenProps) {
|
||
return <Text style={{ color: theme.colors.foreground }}>Bot {params.botId}</Text>;
|
||
}
|
||
|
||
function BotsItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
|
||
const bots = useBots();
|
||
const openBotId = currentScreen?.screenId === "bot" ? currentScreen.params.botId : null;
|
||
return (
|
||
<>
|
||
<SidebarSeparator />
|
||
{bots.map((bot) => (
|
||
<SidebarRow
|
||
key={bot.id}
|
||
id={bot.id}
|
||
icon="Bot"
|
||
label={bot.name}
|
||
active={bot.id === openBotId}
|
||
onPress={() => openScreen({ screenId: "bot", params: { botId: bot.id } })}
|
||
/>
|
||
))}
|
||
</>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({
|
||
id: "bot",
|
||
title: (params) => botName(params.botId) ?? "Bot",
|
||
Component: BotScreen,
|
||
});
|
||
client.addSidebarHeaderItem({ id: "bots", title: "Bots", Component: BotsItem });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
#### Add and remove items at runtime
|
||
|
||
`addSidebarHeaderItem` and `addSidebarFooterItem` work after the entry returns. Each returns a
|
||
remover; the item appears and disappears without a reload:
|
||
|
||
```tsx
|
||
let removeAlerts: (() => void) | null = null;
|
||
|
||
function showAlerts(client: PluginClientContext) {
|
||
removeAlerts ??= client.addSidebarFooterItem({
|
||
id: "alerts",
|
||
title: "Alerts",
|
||
Component: AlertsItem,
|
||
});
|
||
}
|
||
|
||
function hideAlerts() {
|
||
removeAlerts?.();
|
||
removeAlerts = null;
|
||
}
|
||
```
|
||
|
||
## Host UI
|
||
|
||
Import Paseo-owned UI from `@getpaseo/plugin/client/ui` in client code. This example
|
||
opens a controlled modal, renders a host icon, and confirms the action with a toast:
|
||
|
||
```tsx
|
||
import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
|
||
import { Icon, Modal, useToast } from "@getpaseo/plugin/client/ui";
|
||
import { useState } from "react";
|
||
import { Pressable, Text, View } from "react-native";
|
||
|
||
export function IssueActions({ theme }: PluginSurfaceProps) {
|
||
const [open, setOpen] = useState(false);
|
||
const toast = useToast();
|
||
|
||
function saveIssue() {
|
||
toast.show("Issue saved", { variant: "success" });
|
||
setOpen(false);
|
||
}
|
||
|
||
return (
|
||
<View>
|
||
<Pressable accessibilityRole="button" onPress={() => setOpen(true)}>
|
||
<View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
|
||
<Icon name="Pencil" size={18} color={theme.colors.foreground} />
|
||
<Text style={{ color: theme.colors.foreground }}>Edit issue</Text>
|
||
</View>
|
||
</Pressable>
|
||
|
||
<Modal
|
||
title="Edit issue"
|
||
icon={<Icon name="Pencil" size={18} color={theme.colors.foreground} />}
|
||
open={open}
|
||
onOpenChange={setOpen}
|
||
>
|
||
<Modal.Content>
|
||
<Pressable accessibilityRole="button" onPress={saveIssue}>
|
||
<Text style={{ color: theme.colors.foreground }}>Save</Text>
|
||
</Pressable>
|
||
</Modal.Content>
|
||
</Modal>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
### Markdown
|
||
|
||
Import `Markdown` from `@getpaseo/plugin/client/ui` to render a string with Paseo's
|
||
Markdown presentation on web, iOS, and Android:
|
||
|
||
```tsx
|
||
import { Markdown } from "@getpaseo/plugin/client/ui";
|
||
|
||
<Markdown>{"## Review\n\nThe checks **passed**."}</Markdown>;
|
||
```
|
||
|
||
`children` is the only prop and must be a string. Updating it renders the new content
|
||
immediately; an empty string renders nothing. The host supplies theme, text selection,
|
||
code blocks, tables, diagrams, and link handling. Workspace file links and images use
|
||
workspace context when the containing surface supplies it.
|
||
|
||
The component adds no page padding or scroll container. Use a surrounding layout or
|
||
scroll view when needed. Fetching content and showing loading or error states belong
|
||
to your plugin.
|
||
|
||
### Modal
|
||
|
||
`Modal` uses a bottom sheet on compact layouts and a centered dialog otherwise. The plugin owns
|
||
the `open` state.
|
||
|
||
| Prop | Type | Required | Behavior |
|
||
| -------------- | ------------------------- | -------- | -------------------------------------------- |
|
||
| `title` | `string` | Yes | Labels the modal and its visible header. |
|
||
| `icon` | `ReactNode` | No | Renders before the title in the header. |
|
||
| `open` | `boolean` | Yes | Shows the modal content when `true`. |
|
||
| `onOpenChange` | `(open: boolean) => void` | Yes | Receives `false` when the user dismisses it. |
|
||
| `children` | `ReactNode` | Yes | Contains `Modal.Content`. |
|
||
|
||
`Modal.Content` owns the body below the host-rendered header:
|
||
|
||
| Prop | Type | Default | Behavior |
|
||
| ----------------------- | ---------------------- | ------------------ | --------------------------------------------------------------------------------- |
|
||
| `children` | `ReactNode` | Required | Body content below the header. |
|
||
| `style` | `StyleProp<ViewStyle>` | — | Styles the full body viewport, including empty space. Use for backgrounds. |
|
||
| `contentContainerStyle` | `StyleProp<ViewStyle>` | Padding 24, gap 16 | Overrides the content layout. Set `padding: 0, gap: 0` for edge-to-edge rows. |
|
||
| `scrollable` | `boolean` | `true` | The host scrolls the body. Set `false` for a bounded body with your own scroller. |
|
||
|
||
A plain `Modal.Content` is already padded and scrollable. Avoid adding a second padded wrapper
|
||
unless you want another inset. Body styles leave the host header, drag handle, and dismissal controls
|
||
intact. The host reserves bottom safe-area space on compact native layouts; setting content padding
|
||
to zero removes the decorative inset, not that space. Keyboard clearance is handled separately.
|
||
|
||
With `scrollable={false}`, the body fills the available sheet height, and the centered dialog uses
|
||
85% of the available height. Use `flex: 1, minHeight: 0` on your list. Default scrolling dialogs stay
|
||
content-sized on wide layouts. Presentation follows window size, including narrow desktop windows
|
||
and wide tablets.
|
||
|
||
The close button, backdrop, platform back action, web Escape key, and compact sheet gesture dismiss
|
||
the modal. Dismissal calls `onOpenChange(false)`; the plugin must update `open` to close it.
|
||
|
||
Modal children keep the plugin runtime context. `usePaseo`, `useRpc`, `useWorkspace`, and
|
||
`useAgent` work inside them.
|
||
|
||
### Scrolling
|
||
|
||
Import `ScrollView` and `FlatList` from `@getpaseo/plugin/client/ui` when content can appear in a
|
||
Paseo modal. They accept React Native props and refs and integrate with the sheet's gestures. Outside
|
||
a sheet they use ordinary React Native scrolling. Do not import bottom-sheet libraries directly.
|
||
|
||
Use one vertical scroll owner: either the default modal body, or your own list with
|
||
`scrollable={false}`. A fixed-height vertical list nested inside the default scrolling body can compete
|
||
with the sheet for gestures on Android. Horizontal scrolling can coexist with the host's vertical body.
|
||
|
||
Both the default body and SDK lists share native sheet gestures: drag up to expand before scrolling;
|
||
drag down at the top of the list to collapse or dismiss. `scrollable={false}` removes the host's scroll
|
||
container without changing these gestures. Expand the sheet before using list methods such as
|
||
`scrollToEnd`; the sheet locks list offsets below its largest height.
|
||
|
||
```tsx
|
||
import { FlatList, Modal } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
|
||
// Inside your controlled Modal:
|
||
<Modal.Content
|
||
scrollable={false}
|
||
style={{ backgroundColor: theme.colors.surface1 }}
|
||
contentContainerStyle={{ padding: 0, gap: 0 }}
|
||
>
|
||
<FlatList
|
||
style={{ flex: 1, minHeight: 0 }}
|
||
data={items}
|
||
keyExtractor={(item) => item.id}
|
||
renderItem={({ item }) => (
|
||
<Text style={{ padding: 16, color: theme.colors.foreground }}>{item.title}</Text>
|
||
)}
|
||
/>
|
||
</Modal.Content>;
|
||
```
|
||
|
||
For horizontal tabs, place `<ScrollView horizontal style={{ flexGrow: 0 }}>…</ScrollView>` inside the
|
||
default `Modal.Content`. Keep the content's vertical scrolling on the host.
|
||
|
||
### Copy and paste
|
||
|
||
`copyText(text): Promise<void>` writes to the clipboard on the device running the app. Call it from a
|
||
user action and await it before reporting success. It rejects if the platform denies copying or the
|
||
clipboard is unavailable; browser permissions and secure-context requirements still apply.
|
||
|
||
```tsx
|
||
import { copyText, useToast } from "@getpaseo/plugin/client/ui";
|
||
|
||
// Inside your component:
|
||
const toast = useToast();
|
||
async function copyResult() {
|
||
try {
|
||
await copyText(result);
|
||
toast.show("Copied", { variant: "success" });
|
||
} catch {
|
||
toast.error("Could not copy. Select the text and use Copy.");
|
||
}
|
||
}
|
||
```
|
||
|
||
Programmatic copying and native text selection are separate interactions. Use `<Text selectable>`
|
||
for long-press selection and OS Copy. Import `TextInput` from `@getpaseo/plugin/client/ui` for modal forms. It accepts React Native
|
||
input props and refs, supports OS Paste, and registers focus with the native sheet so the keyboard
|
||
can raise the form. Outside a sheet it uses the ordinary input. A plain React Native input supports
|
||
Paste too, but does not register focus with the sheet; the keyboard can cover it. No clipboard read
|
||
API is needed for OS Paste. Avoid DOM clipboard code in native plugins and the deprecated
|
||
`Clipboard` export from `react-native`.
|
||
|
||
The runnable [modal UI example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/modal-ui)
|
||
contains a padded form, full-width rows, a virtualized list, horizontal tabs, and a copy/paste input.
|
||
|
||
### Toasts
|
||
|
||
`useToast()` returns two methods:
|
||
|
||
| Method | Behavior |
|
||
| ------------------------- | ----------------------------------------------------------- |
|
||
| `show(message, options?)` | Shows a toast for 2,200 ms unless `durationMs` is supplied. |
|
||
| `error(message)` | Shows an error toast for 3,200 ms. |
|
||
|
||
`show` accepts these options:
|
||
|
||
| Option | Type | Default |
|
||
| ------------ | ---------------------------------------------------------- | ----------- |
|
||
| `variant` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` |
|
||
| `durationMs` | `number` | `2200` |
|
||
|
||
Showing another toast replaces the currently visible toast. An empty message is ignored.
|
||
|
||
### Icons
|
||
|
||
Every contribution `icon` field takes one of three forms, typed `PluginIcon` in
|
||
`@getpaseo/plugin/client`:
|
||
|
||
| Form | Example | Use it for |
|
||
| ----------- | --------------------------- | --------------------------------------------------- |
|
||
| Lucide name | `icon: "Scan"` | Any [Lucide icon](https://lucide.dev/icons/). |
|
||
| Inline SVG | `icon: { svg: reviewIcon }` | A brand mark or an icon Lucide does not have. |
|
||
| Component | `icon: ReviewBadge` | An icon that changes with state, such as a counter. |
|
||
|
||
Attachment sources take a Lucide name or inline SVG (`PluginSerializableIcon`), because each
|
||
attached item stores its source's icon.
|
||
|
||
Paseo validates the icon when the contribution registers. An unknown Lucide name or an SVG that
|
||
breaks a rule fails the plugin with the reason:
|
||
|
||
```text
|
||
Workspace panel review has an invalid icon: script elements are not allowed
|
||
```
|
||
|
||
Paseo draws inline SVG at the surface's icon size and passes the surface's icon color as
|
||
`currentColor`. Paint with `currentColor` to follow the theme; fixed fills keep their colors.
|
||
|
||
A component receives `PluginIconProps`, `{ size, color }`, and renders within that size. Header
|
||
buttons and composer pills pass [`PluginButtonIconProps`](#custom-icons-and-popover-content).
|
||
|
||
#### SVG rules
|
||
|
||
Inline SVG, provider icons, and usage-source icons follow the same rules:
|
||
|
||
- One `<svg>` document, no larger than 64 KiB.
|
||
- No `<script>`, `<style>`, or `<foreignObject>` elements.
|
||
- No event-handler attributes such as `onclick`, and no `javascript:` URLs.
|
||
- `href` and `xlink:href` point only at fragments in the same document, such as `#mark`.
|
||
|
||
#### Ship SVG markup
|
||
|
||
Keep the markup in a client module:
|
||
|
||
```ts
|
||
// client/icons.ts
|
||
export const reviewIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
|
||
<path d="M4 4h16v16H4z" />
|
||
</svg>`;
|
||
```
|
||
|
||
Or put an `.svg` file in `client/` and import it. The plugin compiler bundles the file's markup as a
|
||
string. Declare the module once so TypeScript accepts the import:
|
||
|
||
```ts
|
||
// client/svg.d.ts
|
||
declare module "*.svg" {
|
||
const markup: string;
|
||
export default markup;
|
||
}
|
||
```
|
||
|
||
```ts
|
||
// index.client.tsx
|
||
import reviewIcon from "./client/review.svg";
|
||
|
||
client.addWorkspacePanel({ id: "review", title: "Review", icon: { svg: reviewIcon } /* … */ });
|
||
```
|
||
|
||
#### Render an icon
|
||
|
||
`Icon` from `@getpaseo/plugin/client/ui` draws an icon in your own UI. Plugin bundles do
|
||
not import `lucide-react-native` or `react-native-svg`.
|
||
|
||
| Prop | Type | Required | Behavior |
|
||
| ------- | ------------ | ---------------- | ------------------------------------------------------------ |
|
||
| `name` | `string` | `name` or `icon` | Lucide icon name. |
|
||
| `icon` | `PluginIcon` | `name` or `icon` | Any icon form above. |
|
||
| `size` | `number` | No | Icon width and height. Defaults to 24. |
|
||
| `color` | `string` | No | Icon color and SVG `currentColor`. Use a plugin theme token. |
|
||
|
||
An unknown name or an SVG that breaks a rule renders nothing.
|
||
|
||
## Timeline items
|
||
|
||
A plugin can replace an agent timeline entry with its own data and React Native renderer. Both
|
||
registrations are client contributions. Paseo applies the transformer while building the render
|
||
model, including every live streaming update.
|
||
|
||
```tsx
|
||
import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin/client";
|
||
import { Text } from "react-native";
|
||
import { z } from "zod";
|
||
|
||
const schema = z.object({ label: z.string() });
|
||
|
||
function Card({ item, theme }: PluginTimelineItemProps<z.output<typeof schema>>) {
|
||
return <Text style={{ color: theme.colors.foreground }}>{item.data.label}</Text>;
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addTimelineTransformer({
|
||
id: "command-card",
|
||
query: { itemType: "tool_call" },
|
||
transform({ item, phase }) {
|
||
return {
|
||
items: [
|
||
{
|
||
type: "plugin",
|
||
kind: "command-card",
|
||
version: 1,
|
||
data: { label: item.name, phase },
|
||
},
|
||
],
|
||
};
|
||
},
|
||
});
|
||
client.addTimelineRenderer({
|
||
kind: "command-card",
|
||
version: 1,
|
||
schema,
|
||
Component: Card,
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`query.itemType` is the stable, coarse selector. Inspect the selected item inside `transform` for
|
||
provider- or tool-specific recognition. Returning `undefined` keeps the original entry. Returning
|
||
`items` replaces it; an empty array removes it. Item `data` must be JSON-compatible. The `phase`
|
||
input is `"streaming"` for the live assistant message, running tool calls, and loading reasoning;
|
||
it is `"complete"` for committed or fetched messages and finished tools or reasoning.
|
||
Assistant and reasoning callbacks receive the full accumulated text on each update, including
|
||
paragraph separators. Paseo invokes transformers before splitting native Markdown or grouping
|
||
tools in Overview. A claimed assistant message remains one source item throughout streaming;
|
||
return `undefined` until recognizable if the first text is insufficient to identify it.
|
||
Each replacement may set an optional plugin-local `id`; otherwise Paseo uses its index within that
|
||
source item's output.
|
||
|
||
Renderers receive `agentId`, `item`, `timestamp`, `theme`, `host`, and `layout`. Paseo validates
|
||
`item.data` with the registered schema before rendering. Keep transformers synchronous and
|
||
deterministic. Paseo memoizes results by source-item reference and derives replacement identity from
|
||
the source row, so updates to one streaming item do not remount its renderer. Render `<StreamedText text={item.data.text} phase={item.data.phase} />` from
|
||
`@getpaseo/plugin/client/ui` for plain text paced like Paseo's assistant rows. It accepts React Native
|
||
`Text` props (including `style`) and supplies assistant typography and foreground color by default.
|
||
Completion displays the full text immediately; the host owns pacing while streaming. Requires Paseo 0.13 or later.
|
||
|
||
Chat find (Ctrl or Cmd+F) finds and highlights text in replacement rows when the query also
|
||
matches the original message. The host searches the original prompt text or the assistant reply
|
||
with Markdown syntax removed, then the app counts matches in the text your renderer draws.
|
||
Text added only by your renderer is not independently indexed. Matches stay within a rendered
|
||
block, and find skips buttons, icons, and anything with `aria-hidden="true"`. Find only runs on
|
||
the web and desktop apps.
|
||
|
||
### Append a timeline row from the daemon
|
||
|
||
A server handler can add a plugin-owned row to canonical history:
|
||
|
||
```ts
|
||
import type { PluginHandlerContext } from "@getpaseo/plugin/server";
|
||
|
||
async function publishReview(agentId: string, { paseo }: PluginHandlerContext) {
|
||
await paseo.agents.ref(agentId).timeline.append({
|
||
type: "plugin",
|
||
id: "review",
|
||
kind: "review-result",
|
||
version: 1,
|
||
data: { verdict: "ready" },
|
||
});
|
||
}
|
||
```
|
||
|
||
| Field | Type | Required | Behavior |
|
||
| --------- | ---------------- | -------- | -------------------------------------------------------------- |
|
||
| `type` | `"plugin"` | Yes | Selects the plugin timeline variant. |
|
||
| `id` | `string` | Yes | Stable plugin-local identity. Reusing it replaces the old row. |
|
||
| `kind` | `string` | Yes | Selects the registered renderer. |
|
||
| `version` | positive integer | Yes | Selects the renderer contract version. |
|
||
| `data` | JSON-compatible | Yes | Renderer payload, at most 64 KiB after JSON serialization. |
|
||
|
||
The daemon stamps `pluginId` from the calling plugin session and rejects this RPC from non-plugin
|
||
sessions. The row appears live, survives timeline refetches, and keeps only the latest value for the
|
||
same plugin and `id`. If its renderer is missing, Paseo shows the existing unavailable row. Daemons
|
||
reject `data` over the limit rather than truncating it. Daemons that support this operation
|
||
advertise `server_info.features.pluginTimelineItems`.
|
||
|
||
## Theme and layout
|
||
|
||
Plugin UI runs on desktop, browser, iOS, and Android, across every Paseo theme. `theme` is a typed `PluginTheme` mapped from the active host theme. Color and spacing must come from those props. Hardcoded colors and unstyled `Text` break when the host theme changes.
|
||
|
||
Recreate styles when `theme` or `layout.compact` changes.
|
||
|
||
| Key | Required for | Use it for |
|
||
| ------------------------------- | -------------------------- | ----------------------------------- |
|
||
| `theme.colors.foreground` | Every primary `Text` | Titles and body copy |
|
||
| `theme.colors.foregroundMuted` | Secondary `Text` | Labels and supporting copy |
|
||
| `theme.colors.surface0` | Root view | Panel background |
|
||
| `theme.colors.surface1` | Raised surfaces | Cards and panels |
|
||
| `theme.colors.surface2` | Control surfaces | Inputs and secondary controls |
|
||
| `theme.colors.border` | Surface boundaries | Borders and dividers |
|
||
| `theme.colors.accent` | Primary action fills | Buttons and selected states |
|
||
| `theme.colors.accentForeground` | Text on an accent fill | Button labels |
|
||
| `theme.colors.statusSuccess` | Success feedback | Success messages and indicators |
|
||
| `theme.colors.statusWarning` | Warning feedback | Warning messages and indicators |
|
||
| `theme.colors.statusDanger` | Failure copy | Error messages and destructive text |
|
||
| `layout.compact` | Padding and stacking | `true` on mobile and narrow windows |
|
||
| `layout.platform` | Platform-specific behavior | `ios`, `android`, or `web` |
|
||
|
||
Do not hardcode `#000`, `#fff`, or React Native's default text color. Primary copy uses `foreground`. Labels use `foregroundMuted`. Tighten padding when `layout.compact` is true.
|
||
|
||
Workspace and agent panels receive the same `theme`, `layout`, and optional `navigation` fields.
|
||
|
||
## Contribute a theme
|
||
|
||
`addTheme` adds a light or dark theme to Settings → Appearance, listed under the built-ins by its
|
||
`name`. A theme is data, so it needs no component file:
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addTheme({
|
||
id: "mocha",
|
||
name: "Catppuccin Mocha",
|
||
appearance: "dark",
|
||
colors: {
|
||
background: "#1e1e2e",
|
||
foreground: "#cdd6f4",
|
||
raised: "#313244",
|
||
control: "#45475a",
|
||
border: "#45475a",
|
||
accent: "#cba6f7",
|
||
mutedForeground: "#a6adc8",
|
||
ring: "#6c7086",
|
||
},
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Every color is a hex string; anything else fails to load. Paseo expands the palette into the full
|
||
token set the built-in dark themes use, so a contributed theme covers panels, menus, diffs, status
|
||
colors, and the terminal without listing them.
|
||
|
||
| Color | Becomes |
|
||
| ----------------- | ----------------------------------------------------------------- |
|
||
| `background` | App, workspace, and terminal background |
|
||
| `foreground` | Primary text, terminal foreground and cursor |
|
||
| `raised` | Cards, popovers, and hovered rows |
|
||
| `control` | Inputs, secondary fills, and the light-theme sidebar |
|
||
| `border` | Borders and the highest raised-surface tint |
|
||
| `accent` | Buttons, selection, and focus. Optional; `foreground` if omitted. |
|
||
| `mutedForeground` | Secondary text |
|
||
| `ring` | Focus rings, scrollbars, and terminal bright black |
|
||
|
||
`appearance` is `"light"` or `"dark"`. Paseo uses it to select the matching surface, status,
|
||
diff, syntax, terminal, and shadow derivation.
|
||
|
||
Only one contributed theme is active at a time. Selecting one persists the choice; if the plugin is
|
||
later disabled or removed, Paseo falls back to the default theme rather than leaving the app
|
||
unpainted.
|
||
|
||
Themes need a host that supports them. A client released before `addTheme` cannot evaluate that client entry and reports
|
||
`client.addTheme is not a function`. Update the client.
|
||
|
||
## Settings screens
|
||
|
||
Register a component with `client.addSettingsScreen({ id, title, icon, Component })` in
|
||
`index.client.tsx`. Your plugin's row in **Settings → Plugins** on that host then shows a settings
|
||
button (cog) that opens your first screen. When you register several screens, the settings page shows
|
||
one tab per screen, labeled with its `title` and `icon`, in registration order. With one screen there
|
||
are no tabs. The page header shows your manifest `name`, or your plugin ID when you leave `name`
|
||
out; it never includes a screen title. `id` is unique within the installation; `icon` is any [icon](#icons) form. Registration returns an
|
||
idempotent remover, and plugin teardown removes remaining screens.
|
||
|
||
Call `client.openSettings(id)` or a Command Center callback's `openSettings(id)` to open one
|
||
of your own screens. Each installation has its own values and route, even when several hosts
|
||
install the same plugin.
|
||
|
||
The component receives `PluginSurfaceProps`. Paseo owns the header, back navigation, safe areas,
|
||
scrolling, and the centered settings column. Compact windows push a full-screen detail; wide
|
||
windows keep the settings sidebar. Render content inside that frame using React Native components.
|
||
A disabled or removed plugin leaves an unavailable screen with working Back navigation.
|
||
|
||
### Named UI components
|
||
|
||
Import settings components from `@getpaseo/plugin/client/ui`. They work with your own state and RPCs;
|
||
no form wrapper or storage binding is required.
|
||
|
||
```tsx
|
||
import { useState } from "react";
|
||
import { SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
|
||
|
||
export function DisplaySettings() {
|
||
const [visible, setVisible] = useState(true);
|
||
return (
|
||
<SettingsSection title="Display">
|
||
<SettingsCard>
|
||
<SettingsSwitch label="Show metadata" value={visible} onValueChange={setVisible} />
|
||
</SettingsCard>
|
||
</SettingsSection>
|
||
);
|
||
}
|
||
```
|
||
|
||
| Component | Props and behavior |
|
||
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `SettingsSection` | Required `title`, `children`; optional `info` tooltip, `trailing` content, `testID`. Own section spacing and headings. |
|
||
| `SettingsCard` | `children`, optional `testID`. Owns the card surface and dividers between direct children. Give mapped rows stable React keys. |
|
||
| `SettingsRow` | Required `label`; optional `hint`, `error`, `children`, `testID`. Wrap any custom control or content. |
|
||
| `SettingsSwitch` | Row props plus required `value: boolean`, `onValueChange`; optional `disabled`. |
|
||
| `SettingsSelect` | Row props plus required string `value`, `options: { label, value }[]`, `onValueChange`; optional `disabled`. Uses Paseo's adaptive menu. |
|
||
| `SettingsInput` | Row props plus required `onChangeText`; optional `initialValue`, `placeholder`, `disabled`, `secureTextEntry`, `ref`. |
|
||
| `SettingsAction` | Row props plus required `actionLabel`, `onPress`; optional `disabled`. |
|
||
|
||
`SettingsInput` owns in-progress text. `initialValue` seeds it when mounted. Its ref exposes
|
||
`focus()`, `blur()`, `getText()`, and `replaceText(text)` for explicit programmatic changes.
|
||
Keep draft text outside persisted values until the user saves. Custom previews and controls
|
||
can sit beside or inside these components.
|
||
|
||
### Persisted values
|
||
|
||
Define a settings document in `shared/`:
|
||
|
||
```ts
|
||
import { defineSettings } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const preferences = defineSettings({
|
||
id: "display",
|
||
scope: "host",
|
||
version: 1,
|
||
schema: z.object({ showMetadata: z.boolean().default(true) }),
|
||
});
|
||
```
|
||
|
||
Register it in `index.server.ts` before returning cleanup. The returned handle lets server code
|
||
read the document and react to changes. A screen using its own data can remain client-only.
|
||
|
||
```ts
|
||
export default function contribute(server: PluginServerContext) {
|
||
const settings = server.registerSettings(preferences);
|
||
|
||
settings.subscribe((next) => {
|
||
if (next.status === "ready") {
|
||
console.log("Settings changed", next.revision);
|
||
}
|
||
});
|
||
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
| Definition field | Contract |
|
||
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `id` | Lowercase identifier matching `[a-z][a-z0-9_-]*`; unique within the installation. |
|
||
| `scope` | Required `"host"` or `"device"`. Host documents are shared by authorized clients. Device documents stay on this device, keyed by installation and settings ID; use them for layout preferences. |
|
||
| `version` | Required positive integer describing the schema, independent of the write revision. |
|
||
| `schema` | Zod schema for JSON values. Supply defaults so parsing `{}` produces a complete document. |
|
||
| `migrate(values, fromVersion)` | Optional synchronous or asynchronous conversion from an older stored version. Its output must pass the current schema. |
|
||
|
||
Call `useSettings(preferences)` in any contributed component. It returns a discriminated state:
|
||
|
||
| `status` | Available data |
|
||
| --------- | ------------------------------------------------------------------------ |
|
||
| `loading` | Read is pending; do not render default values as though they were saved. |
|
||
| `ready` | Typed `values` and an opaque `revision`. |
|
||
| `invalid` | `error` and `revision`; stored data is preserved. |
|
||
| `error` | `error` from the read/connection. |
|
||
|
||
The server handle exposes `read()` and `subscribe()`. `read()` returns the same `ready` or
|
||
`invalid` state as the client hook, including the opaque revision. `subscribe()` returns a cleanup
|
||
function and receives a new `ready` state after a successful save, reset, or migration. Invalid
|
||
writes and revision conflicts do not notify subscribers. Listener failures are logged without
|
||
turning a committed write into a failed save.
|
||
|
||
```ts
|
||
const current = await settings.read();
|
||
if (current.status === "ready") {
|
||
// Use current.values and current.revision.
|
||
}
|
||
```
|
||
|
||
Every state also exposes `saving`, `saveError`, and these actions:
|
||
|
||
- `save(values, revision): Promise<boolean>` validates and saves a complete document. Returns
|
||
`false` and sets `saveError` on validation, conflict, or transport failure; it does not throw.
|
||
- `reset(): Promise<boolean>` explicitly replaces the document with schema defaults, using the
|
||
revision loaded by the hook. It can recover invalid stored data.
|
||
- `reload(): Promise<void>` clears the save error and reads again. Your component owns its draft;
|
||
reloading does not discard that draft automatically.
|
||
|
||
For an immediate toggle, pass `{ ...settings.values, showMetadata }` and `settings.revision`
|
||
to `save`. For a draft editor, capture both the values and revision when opening it. Keep that
|
||
revision until a save succeeds or the user discards the draft. A stale revision rejects the
|
||
save, preserving both the draft and the newer saved values.
|
||
|
||
Writes are atomic and validated on the host. Connected clients receive updates without reloading
|
||
the plugin. Values survive daemon restart, plugin reload, disable, and updates. Removing an
|
||
installation deletes its settings. Reinstalling that ID starts from defaults.
|
||
|
||
A missing document uses schema defaults. Invalid data, failed migrations, and unsupported newer
|
||
versions produce `invalid` without silently resetting the file. Successful migrations persist
|
||
the new version once. These documents are ordinary host-side JSON, not a credential vault.
|
||
Settings RPCs use the existing `daemon.manage` permission for plugin execution.
|
||
|
||
See the complete [settings example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/settings)
|
||
for immediate controls, a draft editor with validation, custom content, and Command Center navigation.
|
||
|
||
## Workspace panels
|
||
|
||
Register workspace panels with `addWorkspacePanel` and agent panels with `addAgentPanel`.
|
||
Both receive the same panel contract as [file panels](#file-panels).
|
||
|
||
`client/review.tsx`:
|
||
|
||
```tsx
|
||
import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin/client";
|
||
import { useMemo } from "react";
|
||
import { Text, View } from "react-native";
|
||
|
||
export function ReviewPanel({ theme, layout, workspaceId, params }: PluginAgentPanelProps) {
|
||
const workspaceName = useWorkspace(workspaceId, (workspace) => workspace.name);
|
||
const agent = useAgent(params.agentId, ({ id, title }) => ({ id, title }));
|
||
const styles = useMemo(
|
||
() => ({
|
||
screen: {
|
||
flex: 1,
|
||
padding: layout.compact ? 16 : 24,
|
||
backgroundColor: theme.colors.surface0,
|
||
},
|
||
title: { color: theme.colors.foreground },
|
||
detail: { color: theme.colors.foregroundMuted },
|
||
}),
|
||
[theme, layout.compact],
|
||
);
|
||
return (
|
||
<View style={styles.screen}>
|
||
<Text style={styles.title}>{workspaceName}</Text>
|
||
<Text style={styles.detail}>{agent?.title ?? agent?.id}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`:
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { ReviewPanel } from "./client/review";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addAgentPanel({
|
||
id: "review",
|
||
title: "Review",
|
||
icon: "Scan",
|
||
locations: ["workspace", "explorer"],
|
||
Component: ReviewPanel,
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`addWorkspacePanel` and `addAgentPanel` fields:
|
||
|
||
| Field | Required | Meaning |
|
||
| ----------- | -------- | ------------------------------------------------------------- |
|
||
| `id` | Yes | Plugin-local panel ID. |
|
||
| `title` | Yes | Workspace-tab title. |
|
||
| `icon` | Yes | Lucide name, `{ svg }`, or component. See [Icons](#icons). |
|
||
| `locations` | No | `workspace` and/or `explorer`. Defaults to `workspace`. |
|
||
| `Component` | Yes | React Native component matching the selected context's props. |
|
||
|
||
Every panel receives `PluginPanelProps<Params>` with `theme`, `host`, `layout`, `navigation`,
|
||
`workspaceId`, read-only `params`, `revision`, and `tab`. Workspace panels have empty
|
||
`PluginWorkspacePanelParams`; agent panels have `PluginAgentPanelParams` containing `agentId`.
|
||
`revision` increments whenever params are re-sent to the same tab, including an identical request.
|
||
|
||
`tab.setModified(boolean)` marks unsaved work and asks before closing. `tab.state` is opaque
|
||
persisted JSON, initially `undefined`; `tab.setState(value)` replaces it. Each tab owns its state.
|
||
Paseo stores it without interpreting it. Validate it with `useTabState(tab, schema, defaultState)`:
|
||
|
||
```tsx
|
||
const schema = z.object({ view: z.enum(["preview", "source"]) });
|
||
const [state, setState] = useTabState(tab, schema, { view: "preview" });
|
||
// Missing or invalid persisted state returns the default.
|
||
// In an event handler, call setState({ view: "source" }).
|
||
```
|
||
|
||
Import `useTabState` from `@getpaseo/plugin/client` and `z` from `zod`. The setter replaces the
|
||
entire JSON value. State survives tab restoration and app reloads.
|
||
|
||
The unified props, `addAgentPanel`, and `useTabState` require Paseo 0.13.0 or later.
|
||
|
||
**Deprecated until removal after 2027-04-23:** the 0.12 panel `context` and flat `agentId` props,
|
||
`addWorkspacePanel({ context: "workspace" })`, and `addWorkspacePanel({ context: "agent" })`
|
||
continue to work. Omit workspace `context`, register agent panels with `addAgentPanel`, and read
|
||
`params.agentId`.
|
||
|
||
Read cached state with `useWorkspace(workspaceId, selector)` and `useAgent(params.agentId, selector)`. A selector is required. Paseo compares its result shallowly, so selecting `{ name, status }` does not re-render when unrelated fields change. Select every field the component renders in one call; do not select the whole snapshot.
|
||
|
||
Both hooks return `null` when the record is unavailable. Otherwise they run synchronously against normalized client state. Snapshot DTOs and their nested values are deeply readonly and frozen at runtime. Do not call plugin RPC to discover the current workspace or agent. Fetch optional or vendor-specific enrichment after the component renders.
|
||
|
||
Workspace snapshot fields:
|
||
|
||
| Field | Type |
|
||
| -------------------- | ----------------------------------------------------------------- |
|
||
| `id` | `string` |
|
||
| `projectId` | `string` |
|
||
| `projectDisplayName` | `string` |
|
||
| `projectRootPath` | `string` |
|
||
| `directory` | `string` |
|
||
| `projectKind` | `"git" \| "non_git" \| "directory"` |
|
||
| `kind` | `"directory" \| "local_checkout" \| "checkout" \| "worktree"` |
|
||
| `name` | `string` |
|
||
| `title` | `string \| null` |
|
||
| `status` | `"needs_input" \| "failed" \| "running" \| "attention" \| "done"` |
|
||
| `statusEnteredAt` | ISO timestamp or `null` |
|
||
| `archivingAt` | ISO timestamp or `null` |
|
||
| `diffStat` | `{ additions: number; deletions: number } \| null` |
|
||
|
||
Agent snapshot fields:
|
||
|
||
| Field | Type |
|
||
| ------------------- | -------------------------------------------------------------- |
|
||
| `id` | `string` |
|
||
| `workspaceId` | `string` |
|
||
| `provider` | `string` |
|
||
| `status` | `"initializing" \| "idle" \| "running" \| "error" \| "closed"` |
|
||
| `createdAt` | ISO timestamp |
|
||
| `updatedAt` | ISO timestamp |
|
||
| `lastActivityAt` | ISO timestamp |
|
||
| `title` | `string \| null` |
|
||
| `cwd` | `string` |
|
||
| `model` | `string \| null` |
|
||
| `currentModeId` | `string \| null` |
|
||
| `thinkingOptionId` | `string \| null` |
|
||
| `requiresAttention` | `boolean` |
|
||
| `attentionReason` | `"finished" \| "error" \| "permission" \| null` |
|
||
| `parentAgentId` | `string \| null` |
|
||
| `labels` | `Record<string, string>` |
|
||
|
||
Paseo owns tab focus, splitting, closing, persistence, query state, the API/RPC providers, and the render error boundary. A restored tab whose plugin, panel, context, workspace, or agent is unavailable stays open with an unavailable message instead of crashing the workspace.
|
||
|
||
## File panels
|
||
|
||
Register a component that renders a file as the body of its file tab. Your component receives a
|
||
handle to the file on the selected host, including remote hosts. It reads the file, shows its own
|
||
loading state, and writes the file when the user edits it. The tab shows a dot while your panel
|
||
reports unsaved changes.
|
||
|
||
```tsx
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { PdfPanel } from "./client/pdf-panel";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
return client.addFilePanel({
|
||
id: "pdf",
|
||
title: "PDF",
|
||
icon: "FileText",
|
||
files: { extensions: ["pdf"] },
|
||
Component: PdfPanel,
|
||
});
|
||
}
|
||
```
|
||
|
||
`addFilePanel` takes a `PluginFilePanelContribution` and returns an idempotent cleanup function.
|
||
Paseo also removes the registration when the client entry is unloaded.
|
||
|
||
| Field | Required | Meaning |
|
||
| ----------- | -------- | ------------------------------------------------------------------------ |
|
||
| `id` | Yes | Plugin-local ID matching `^[a-z][a-z0-9-]*$`. |
|
||
| `title` | Yes | Non-empty label in the picker, the Open with menu, and Settings > Files. |
|
||
| `icon` | Yes | Lucide name, `{ svg }`, or component. See [Icons](#icons). |
|
||
| `files` | Yes | `{ extensions: readonly string[]; filenames?: readonly string[] }`. |
|
||
| `Component` | Yes | Component receiving `PluginFilePanelProps`. |
|
||
|
||
Extensions have no leading dot and match without case sensitivity. Filenames match the exact
|
||
basename, including case. Selectors contain no paths, globs, or wildcards. Use `extensions: []`
|
||
for a filename-only selector. At least one extension or filename is required.
|
||
|
||
### File panel props
|
||
|
||
`PluginFilePanelProps` includes the common `theme`, `host`, `layout`, and optional `navigation`
|
||
props described under [Theme and layout](#theme-and-layout), plus:
|
||
|
||
| Prop | Type | Meaning |
|
||
| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| `workspaceId` | `string` | Workspace containing the file tab. |
|
||
| `params` | `PluginFilePanelParams` | Read-only `path`, `lineStart?`, and `lineEnd?` from the opener. |
|
||
| `revision` | `number` | Increments each time params are re-sent to this tab, even for the same line. |
|
||
| `file` | `PluginFile` | File capability resolved from `params.path`, stable while the tab shows this file. |
|
||
| `tab` | `PluginTab` | `setModified`, opaque persisted `state`, and `setState`. See [Workspace panels](#workspace-panels). |
|
||
|
||
Paseo mounts your panel once it knows the file exists and its size, without reading it. The
|
||
`file` object is stable, and its stat fields hold the latest version Paseo knows. Read them while
|
||
rendering; changing them does not re-render your panel. A `watch` listener, or a re-render from
|
||
`useFileText`, `useFileBytes`, or `useFileUrl`, is how your panel learns they changed:
|
||
|
||
| Member | Meaning |
|
||
| -------------------------------- | ------------------------------------------------------------------------------------------- |
|
||
| `path`, `name`, `extension` | Absolute path on the host, basename, and lowercase extension without the dot (or `""`). |
|
||
| `size`, `modifiedAt`, `mimeType` | Size in bytes, modification timestamp, and host-reported MIME type. |
|
||
| `readText()` | Reads the file as UTF-8. A byte order mark is dropped and written back by `writeText`. |
|
||
| `readBytes()` | Reads the file's bytes. |
|
||
| `url()` | A local `blob:` (web) or `file:` (native) URL of the current bytes, for `DocumentFrame`. |
|
||
| `writeText(text, options?)` | Writes UTF-8 text if the file has not changed on disk since this handle last read or wrote. |
|
||
| `writeBytes(bytes, options?)` | The same for bytes. |
|
||
| `watch(listener)` | Calls `listener(event)` with a `PluginFileEvent`; returns the unsubscribe function. |
|
||
|
||
A `PluginFileEvent` is `{ type: "changed" }` or `{ type: "deleted" }`. Switch on `type`; later
|
||
versions may add fields. Your panel stays mounted when the file is deleted. `watch` reports
|
||
`{ type: "deleted" }` once a read confirms the file is gone, so a program that removes the file and
|
||
writes it back reports only `{ type: "changed" }`. A deleted file that comes back reports
|
||
`{ type: "changed" }`.
|
||
|
||
A write rejects with `PluginFileConflictError` when the file changed on disk after the handle's
|
||
last read or write. Pass `{ force: true }` to write anyway. A write rejects with
|
||
`PluginFileDeletedError` when the file is gone, with or without `force`. The handle's own writes do not notify
|
||
its watchers. Paseo owns the URL from `url()`: it stays valid until a URL for a newer version
|
||
resolves or the tab closes. Do not build daemon URLs from `file.path`; local URLs also work when
|
||
the daemon is remote.
|
||
|
||
### Read the file
|
||
|
||
Most panels read through a hook. Each hook reads when mounted, re-reads when the file changes on
|
||
disk, and keeps the current value during a re-read:
|
||
|
||
| Hook | Ready state |
|
||
| -------------------- | ---------------------------------------- |
|
||
| `useFileText(file)` | `{ status: "ready", text: string }` |
|
||
| `useFileBytes(file)` | `{ status: "ready", bytes: Uint8Array }` |
|
||
| `useFileUrl(file)` | `{ status: "ready", url: string }` |
|
||
|
||
Each also returns `{ status: "loading" }` before the first read and `{ status: "error", error }`
|
||
when a read fails. For a deleted file, `error` is a `PluginFileDeletedError`. Show `Loading` from `@getpaseo/plugin/client/ui` until
|
||
your content is on screen; it fills the panel, so render it over content that is still laying out.
|
||
|
||
```tsx
|
||
import { type PluginFilePanelProps, useFileUrl } from "@getpaseo/plugin/client";
|
||
import { DocumentFrame, Loading } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
|
||
export function PdfPanel({ file, theme }: PluginFilePanelProps) {
|
||
const url = useFileUrl(file);
|
||
if (url.status === "loading") return <Loading />;
|
||
if (url.status === "error") {
|
||
return <Text style={{ color: theme.colors.statusDanger }}>{url.error.message}</Text>;
|
||
}
|
||
return <DocumentFrame url={url.url} testID="pdf-panel" />;
|
||
}
|
||
```
|
||
|
||
### Edit the file
|
||
|
||
A hook's re-read adopts the version on disk, so the next write overwrites whatever changed there.
|
||
A panel that holds unsaved edits reads with `readText()` once, then handles `watch` itself:
|
||
|
||
1. Read with `file.readText()` and show the text.
|
||
2. On each edit, call `tab.setModified(true)` and write with `file.writeText(text)`, debounced.
|
||
3. When the write resolves and no newer edit is pending, call `tab.setModified(false)`.
|
||
4. On `{ type: "changed" }` with nothing unsaved, read again. With unsaved edits, show a conflict
|
||
and let the user reload or overwrite with `{ force: true }`.
|
||
5. On `PluginFileConflictError`, show the same conflict.
|
||
6. On `{ type: "deleted" }` or `PluginFileDeletedError`, tell the user the file is gone.
|
||
|
||
Write pending edits before the component unmounts: opening the tab with another panel or closing
|
||
the tab unmounts it. Paseo asks before closing a tab whose panel reports unsaved changes. The
|
||
[Markdown panel](https://github.com/getpaseo/paseo/tree/main/plugin-examples/markdown-panel)
|
||
example implements these steps.
|
||
|
||
### Selection and Open with
|
||
|
||
A plugin panel is a candidate for every file its selector matches, text or binary. The built-in
|
||
panels require the host's file kind: Markdown, HTML, and **Source** open text files; Image opens
|
||
images. The Markdown and HTML panels each have a Preview and a Source view of the file, switched
|
||
in their toolbar. **Source**, Paseo's editor, is the built-in panel for text files that no other
|
||
built-in panel claims; it is never offered beside another built-in panel. Candidates are ordered:
|
||
the built-in panel that claims the file, then plugin panels in host catalog order, then Source
|
||
when no other built-in claims the file.
|
||
|
||
A remembered association selects its panel when that panel is available on the current host.
|
||
Otherwise Paseo opens the first candidate. When a plugin panel is among several candidates and no
|
||
association applies, Paseo asks once per tab open, over the panel it already opened. A file with
|
||
one candidate never asks. With a Markdown plugin installed, the picker offers **Markdown — Paseo**
|
||
and **Rich Markdown — markdown-panel**. A plugin that claims a text extension no built-in panel
|
||
claims competes with Source, so its first open asks; a plugin that alone claims a binary file
|
||
opens without asking.
|
||
|
||
**Don't ask me again** remembers the choice on this device for the extension. When a candidate
|
||
matches an exact filename, the choice applies to that basename instead. An unavailable association
|
||
is ignored on that host and retained for hosts where its panel is installed.
|
||
|
||
Users choose a panel three ways: the picker on first open, **Open with…** in the tab menu, and
|
||
**Settings > Files**. Open with switches the current tab and wins over the remembered association
|
||
for this tab until it is retargeted; its **Always use** remembers the shown panel. Opening a file
|
||
at a line, from a link or a search result, switches the tab to its built-in panel, which shows the
|
||
line in its Source view. Files with no candidate show **Binary preview unavailable**; binary files
|
||
have no Source panel.
|
||
|
||
### DocumentFrame
|
||
|
||
Import `DocumentFrame` from `@getpaseo/plugin/client/ui` to display a local file URL from
|
||
`file.url()` or `useFileUrl`:
|
||
|
||
| Prop | Required | Meaning |
|
||
| -------- | -------- | -------------------------------------------------------------------------------- |
|
||
| `url` | Yes | Local file URL; `blob:` on web or `file:` on native. Other schemes are rejected. |
|
||
| `testID` | No | Test identifier for the frame. |
|
||
|
||
Web inspects the local URL’s media type before mounting the iframe. PDF uses the browser’s PDF
|
||
viewer without a sandbox; every other type, including HTML and unknown types, keeps a full sandbox
|
||
with no scripts or same-origin access. Native uses a WebView with JavaScript, storage, and further
|
||
navigation disabled. Where the platform cannot show the document inline, such as a PDF on Android,
|
||
`DocumentFrame` shows a message naming the file type instead, so render it on every platform.
|
||
|
||
Inline PDF rendering needs a daemon from Paseo 0.13.0 or later; older daemons report PDFs as
|
||
`application/octet-stream`.
|
||
|
||
### Version requirement and examples
|
||
|
||
File panels, `DocumentFrame`, and `Loading` require Paseo 0.13.0 or later. Declare
|
||
`"requirements": { "paseo": ">=0.13.0" }` in `paseo-plugin.json`. Both daemon and app check the
|
||
[version requirement](#requirements); older apps skip the client bundle before evaluation.
|
||
Writing with `writeBytes` needs a daemon from Paseo 0.13.0 or later.
|
||
|
||
Complete directory examples:
|
||
|
||
- [PDF panel](https://github.com/getpaseo/paseo/tree/main/plugin-examples/pdf-panel): `useFileUrl` with `Loading` and `DocumentFrame`.
|
||
- [Markdown panel](https://github.com/getpaseo/paseo/tree/main/plugin-examples/markdown-panel): a bundled CodeMirror editor that reads once, saves with `writeText`, and resolves conflicts, with read-only native text.
|
||
|
||
## Command Center items
|
||
|
||
Open the Command Center with **⌘K** on macOS or **Ctrl+K** on Windows and Linux, then search for the item title.
|
||
|
||
Register an action and open a panel from the callback:
|
||
|
||
```tsx
|
||
import { defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
const refreshReview = defineRpc({
|
||
name: "review.refresh",
|
||
input: z.object({ agentId: z.string(), scope: z.string().optional() }),
|
||
output: z.object({ refreshed: z.boolean() }),
|
||
});
|
||
|
||
client.addCommandCenterItem({
|
||
id: "open-review",
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
keywords: ["inspect"],
|
||
context: "agent",
|
||
async onSelect({ paseo, rpc, workspace, agent, openPanel }) {
|
||
await paseo.workspaces.ref(workspace.id).setTitle(`Review ${agent.id}`);
|
||
await rpc(refreshReview, { agentId: agent.id });
|
||
openPanel("review");
|
||
},
|
||
});
|
||
```
|
||
|
||
`addCommandCenterItem` fields:
|
||
|
||
| Field | Required | Meaning |
|
||
| ---------- | -------- | ---------------------------------------------------------- |
|
||
| `id` | Yes | Plugin-local item ID. |
|
||
| `title` | Yes | Search result title. |
|
||
| `icon` | Yes | Lucide name, `{ svg }`, or component. See [Icons](#icons). |
|
||
| `keywords` | No | Additional Command Center search terms. |
|
||
| `context` | Yes | `global`, `workspace`, or `agent`. |
|
||
| `onSelect` | Yes | Client-side callback for the matching context. |
|
||
|
||
Global items appear on the installation's selected host. Workspace items appear only when that host has an active cached workspace. Agent items appear only when the focused workspace tab is an agent or an agent-context plugin panel whose cached record belongs to that workspace. Missing context removes the item rather than calling the plugin to discover it.
|
||
|
||
Every callback receives:
|
||
|
||
| Field | Context | Meaning |
|
||
| ------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||
| `context` | All | Matching discriminator. |
|
||
| `paseo` | All | Selected host's existing `PaseoApi`. |
|
||
| `rpc(contract, input)` | All | Typed call to this installation's daemon-side plugin handler. |
|
||
| `openScreen(input)` | All | Opens one of this plugin's registered screens: `{ screenId, params? }`. |
|
||
| `workspace` | Workspace and agent | Synchronous workspace snapshot. |
|
||
| `agent` | Agent | Synchronous matching agent snapshot. |
|
||
| `openPanel(id, options?)` | Workspace and agent | Opens a registered panel in the callback's current context. Pass `{ location: "explorer" }` to target Explorer. |
|
||
|
||
An agent callback may open either an agent panel or a workspace panel. A workspace callback may open only a workspace panel. Unknown screen and panel IDs fail visibly. Use `paseo` for normal workspace, agent, provider, and daemon-config operations. Use `rpc` for plugin-specific filesystem, credential, vendor, or daemon-local work.
|
||
|
||
## Slash commands
|
||
|
||
Register a command that runs in the Paseo client when the user submits `/name args` from the
|
||
message composer. The text is never sent to the agent:
|
||
|
||
```ts
|
||
client.addSlashCommand({
|
||
name: "review",
|
||
description: "Run the review bot",
|
||
argumentHint: "[scope]",
|
||
context: "agent",
|
||
async onSubmit({ args, agent, rpc, openPanel }) {
|
||
await rpc(refreshReview, { agentId: agent.id, scope: args });
|
||
openPanel("review");
|
||
},
|
||
});
|
||
```
|
||
|
||
| Field | Required | Meaning |
|
||
| -------------- | -------- | ---------------------------------------------- |
|
||
| `name` | Yes | Command name without the leading slash. |
|
||
| `description` | Yes | Composer autocomplete description. |
|
||
| `argumentHint` | Yes | Short usage hint shown after the command name. |
|
||
| `context` | Yes | `"workspace"` or `"agent"`. |
|
||
| `onSubmit` | Yes | Client callback for the matching context. |
|
||
|
||
`onSubmit` receives the matching Command Center callback context plus `args`. For `/review src`,
|
||
`args` is `"src"`; Paseo trims only the remainder's leading and trailing whitespace and leaves
|
||
parsing to the plugin. Paseo owns the autocomplete row, input clearing, and the error toast. It
|
||
does not wait for `onSubmit` or show a pending state; use a composer pill or panel for that.
|
||
|
||
Precedence is built-in client commands, plugin commands, then provider commands. A lower-precedence
|
||
collision is omitted. Built-in aliases also reserve their names. The first plugin in stable catalog
|
||
order wins a collision between plugins. Commands do not run while the composer has attachments.
|
||
|
||
## Header buttons
|
||
|
||
Try the [button example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/buttons) for
|
||
actions, menus, custom icons and content, and visibility updates in both the header and composer.
|
||
It switches one header button between modes; additional actions use a named Tools menu.
|
||
|
||
`client.addHeaderButton({ id, workspaceId, button })` adds a button before the built-in actions on
|
||
the workspace header's right side. It returns a registration with `update(patch)` and `remove()`.
|
||
|
||
```tsx
|
||
const review = client.addHeaderButton({
|
||
id: "review",
|
||
workspaceId,
|
||
button: {
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
label: "Review",
|
||
behavior: {
|
||
kind: "action",
|
||
onPress() {
|
||
client.openPanel("review", { workspaceId });
|
||
},
|
||
},
|
||
},
|
||
});
|
||
|
||
review.update({ label: "Review · 3" });
|
||
review.update({ visible: false });
|
||
review.update({ visible: true });
|
||
review.remove();
|
||
```
|
||
|
||
Omit `label` for an icon-only header button. Menus and popovers show a chevron on wide layouts.
|
||
Paseo moves excess contributions into a shared overflow menu. On phones and narrow windows the
|
||
header has no room for plugin buttons, so each one is a row of the workspace menu (`···`), with its
|
||
icon and title; its menus and popovers open as pages of that sheet. Placement and overflow are host
|
||
decisions.
|
||
|
||
## Composer items
|
||
|
||
`client.addComposerItem({ id, Component })` puts a component in the composer: the agent composer,
|
||
the draft composer for a new agent, and the composer on the New workspace screen. `useComposer()`
|
||
reads and changes what the composer configures, and `Toggle`, `Select` and `Action` from
|
||
`@getpaseo/plugin/client/ui` draw the controls.
|
||
|
||
```tsx
|
||
import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
|
||
|
||
function ReviewFlag() {
|
||
const composer = useComposer();
|
||
return (
|
||
<Toggle
|
||
title="Needs review"
|
||
icon="Flag"
|
||
value={composer.agent.metadata["review.needsReview"] === true}
|
||
onValueChange={({ value }) =>
|
||
composer.setMetadata({ "review.needsReview": value ? true : null })
|
||
}
|
||
/>
|
||
);
|
||
}
|
||
|
||
function Checklist() {
|
||
const composer = useComposer();
|
||
return (
|
||
<Action
|
||
title="Insert checklist"
|
||
icon="ListChecks"
|
||
onPress={() => composer.insertText("- [ ] Tests\n- [ ] Docs\n")}
|
||
/>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
|
||
client.addComposerItem({ id: "checklist", Component: Checklist });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`useComposer()` returns the composer the item sits in:
|
||
|
||
| Field or command | Meaning |
|
||
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `context` | `"agent"` for a running agent, `"draft"` for a new agent in a workspace, `"new-workspace"` for the New workspace screen. |
|
||
| `prompt`, `setPrompt(text)`, `insertText(text)` | The prompt. `insertText` replaces the selection or inserts at the cursor. |
|
||
| `attachments`, `addAttachment`, `removeAttachment` | Items from [your own attachment sources](#add-a-composer-attachment-source). Attachments from other plugins and Paseo's own are not listed. |
|
||
| `agent.provider`, `model`, `mode`, `thinking` | What the agent runs with, or what the draft will create. |
|
||
| `agent.options` | The provider options in effect, defaults included. In a draft: the options the agent will be created with, including your changes. |
|
||
| `agent.metadata` | The agent's [metadata](/docs/plugins/hooks#metadata). In New workspace, the first agent's. |
|
||
| `setProvider`, `setModel`, `setMode`, `setThinking` | Return promises. `setProvider` resets the model like the provider picker. It rejects on `context: "agent"`, which keeps its provider, and for a provider the host does not offer. `setModel` and `setThinking` pass the value on as given; on a running agent the provider's refusal rejects the promise. |
|
||
| `setOptions(patch)`, `setMetadata(patch)` | Top-level keys replace; `null` removes the key. Metadata set in a draft is sent when the agent is created and cleared once the prompt is sent. |
|
||
|
||
The same call does the same thing in every composer; a plugin does not choose a composer's
|
||
implementation. `setMetadata` on a running agent needs a host that supports metadata. On an older
|
||
host the promise rejects with "Update the host to use metadata."
|
||
|
||
`Toggle` takes `value` and `onValueChange({ value })`. `Select` takes `value`, `options` (`{ value, label,
|
||
description? }`) and `onValueChange({ value })`. `Action` takes `onPress(event)`. All three take `title`,
|
||
`icon` (a [Lucide name, SVG or component](#icons)) and `disabled`. A callback may return a promise:
|
||
the control stays disabled until it settles, and Paseo shows a rejection to the user as an error
|
||
toast, the way it does for its own controls. Paseo owns where each control sits: inline in the
|
||
toolbar when the composer has room, and a row in the composer's overflow sheet when it does not,
|
||
which is always the case on a phone. A `Select` opens its list in place of the sheet row. A
|
||
`Component` that renders something other than these controls draws it where its item is placed; in
|
||
the overflow sheet that is the sheet.
|
||
|
||
Each command acts on the composer's state when it runs, not on the render that created your
|
||
callback, so `await composer.setProvider("codex")` followed by `await composer.setModel("gpt")`
|
||
changes both. A command's promise resolves once the change has taken effect, and `composer.agent`
|
||
shows it on the next render.
|
||
|
||
While the New workspace screen creates the workspace and its agent, the composer is locked. Your
|
||
controls render disabled, `setPrompt` and `insertText` throw, and the agent commands reject with
|
||
"The composer is locked while the agent is being created." `composer.agent.options` and
|
||
`composer.agent.metadata` are frozen copies; change them through `setOptions` and `setMetadata`.
|
||
|
||
A composer item counts toward how much fits before Paseo knows what it renders. An item that
|
||
renders nothing can still leave an empty overflow sheet on a narrow composer, so always render a
|
||
control.
|
||
|
||
The [composer controls example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)
|
||
registers a `Select`, two `Toggle`s (one writes a provider option) and an `Action`, plus an
|
||
Explorer panel and a Command Center item that reach a composer by reference.
|
||
|
||
### Reach a composer by reference
|
||
|
||
A running agent has a composer whether or not its tab is open. `useComposers(selector)` in any plugin
|
||
component, and `composers(selector)` on every command context, return the same `PluginComposer` that
|
||
`useComposer()` gives an item, for an agent you name or for the focused one:
|
||
|
||
```tsx
|
||
import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
|
||
|
||
function InsertChecklist() {
|
||
const [focused] = useComposers({ focused: true });
|
||
return (
|
||
<Pressable disabled={!focused} onPress={() => focused?.insertText("- [ ] Tests\n")}>
|
||
<Text>Insert checklist</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addWorkspacePanel({
|
||
id: "tools",
|
||
title: "Tools",
|
||
icon: "ListChecks",
|
||
locations: ["explorer"],
|
||
Component: InsertChecklist,
|
||
});
|
||
client.addCommandCenterItem({
|
||
id: "mark-for-review",
|
||
title: "Mark for review",
|
||
icon: "Flag",
|
||
context: "agent",
|
||
async onSelect({ agent, composers }) {
|
||
for (const composer of composers({ agentId: agent.id })) {
|
||
await composer.setMetadata({ "review.needsReview": true });
|
||
}
|
||
},
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
| Selector | Result |
|
||
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `{ agentId }` | The composer of that agent on this host. Empty for an agent that is unknown or archived. |
|
||
| `{ focused: true }` | The composer of the agent the Command Center hands to agent items: the focused agent tab of the workspace on screen. Empty when the screen is not a workspace, such as a plugin screen or New workspace, or when the focused tab is not an agent. It follows focus as the user changes tabs. |
|
||
|
||
The result is always an array, empty or with one composer, so the same code reads either selector.
|
||
`useComposers` re-renders when a composer changes. A composer from `composers()` is the state at the
|
||
call; call `composers()` again for the next state.
|
||
|
||
The commands are those of [`useComposer()`](#composer-items), with these differences for a composer
|
||
you reach from outside:
|
||
|
||
- `insertText` inserts at the cursor while the agent's composer is on screen. While it is not, for
|
||
example when the user is in another workspace, it appends to the agent's saved prompt, and the text
|
||
is in the input when the user returns. `setPrompt` replaces the saved prompt the same way.
|
||
- A running agent's composer is never locked.
|
||
- `setProvider` rejects, as it does inside the agent's own composer.
|
||
- `setModel` and `setThinking` send the value to the provider unchecked. A value the provider refuses
|
||
rejects with the provider's message. `model` and `thinking` read what the model picker
|
||
shows at that moment: until the provider's catalog loads that is the id the agent reports or was
|
||
created with, which may be an alias, and once it loads the catalog's own id.
|
||
- Drafts and the New workspace screen are not addressable by reference. Only an item inside one
|
||
reaches its composer, through `useComposer()`.
|
||
|
||
## New workspace items
|
||
|
||
`client.addNewWorkspaceItem({ id, Component })` puts a field on the New workspace screen, beside
|
||
the project, host and branch pickers. `useNewWorkspace()` reads and changes what the screen will
|
||
create, and `Combobox`, `Select`, `Toggle` and `Action` from `@getpaseo/plugin/client/ui` draw the
|
||
fields. On desktop an item is a badge in the setup row; on a phone it is a full-width field.
|
||
|
||
```tsx
|
||
import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { Combobox } from "@getpaseo/plugin/client/ui";
|
||
import { searchIssuesRpc } from "../shared/issues";
|
||
|
||
function IssueField() {
|
||
const newWorkspace = useNewWorkspace();
|
||
const searchIssues = useRpc(searchIssuesRpc);
|
||
const issueId = newWorkspace.metadata["issues.id"];
|
||
return (
|
||
<Combobox
|
||
title="Issue"
|
||
icon="CircleDot"
|
||
value={typeof issueId === "string" ? { id: issueId, label: issueId } : null}
|
||
search={async ({ query }) => (await searchIssues({ query })).issues}
|
||
onSelect={async ({ item }) => {
|
||
await newWorkspace.setBranch(item.branch);
|
||
await newWorkspace.setMetadata({ "issues.id": item.id });
|
||
}}
|
||
/>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`useNewWorkspace()` returns the setup the item sits in:
|
||
|
||
| Field or command | Meaning |
|
||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `host`, `project` | The user's choices, `{ id, label }` and `{ id, name } \| null`. Read-only: an item cannot switch host or project. |
|
||
| `isolation`, `setIsolation` | `"local"` or `"worktree"`. A project that cannot make worktrees reads `"local"`, and `setIsolation("worktree")` rejects. |
|
||
| `baseRef`, `setBaseRef` | What a new worktree starts from: `{ type: "branch", name }`, `{ type: "change-request", number }`, or `null` until the default is known. A branch's `name` is the exact ref creation uses, such as `refs/remotes/origin/main`, so `setBaseRef(newWorkspace.baseRef)` changes nothing. `setBaseRef` takes any ref the Base picker offers, or a bare branch name, which Paseo resolves as it does anywhere else. It rejects while no project is chosen. |
|
||
| `branch`, `setBranch` | The name of the branch a new worktree is created on. `null` lets Paseo pick one. It is kept while isolation is local or the base is a change request, and it names the new branch of any worktree that cuts one, from the default base or a chosen branch. It does not apply to a worktree that checks out an existing branch or change request. |
|
||
| `metadata`, `setMetadata` | The created workspace's [metadata](/docs/plugins/hooks#metadata), not the first agent's. Top-level keys replace; `null` removes a key. Rejects on a host that does not support metadata with "Update the host to use metadata." |
|
||
|
||
Commands follow the [composer item](#composer-items) rules: each one acts on the screen's state
|
||
when it runs, so `await newWorkspace.setBranch(name)` followed by `newWorkspace.setMetadata(patch)`
|
||
changes both, and its promise resolves once the change has taken effect. A command works from your component's first effect, including a mount effect. Payloads are JSON values.
|
||
Your items are mounted for one project on one host. When the user changes either, Paseo remounts them and clears `branch` and `metadata`, so state and `Combobox` results for the previous project do not carry over; an item that sets up in a mount effect sets up again for the new project. A command called after its project or host has been left, such as the end of a lookup the user abandoned by switching, rejects with "The New workspace screen moved to another project or host; this item belongs to the previous one." and changes nothing; the items mounted for the new project are not affected.
|
||
`host`, `project`, `baseRef` and `metadata` are frozen. While the screen creates the workspace it is locked: your fields render
|
||
disabled and every command rejects with "The New workspace screen is locked while the workspace is
|
||
being created." A callback that returns a promise keeps the control disabled until it settles, and a
|
||
rejection reaches the user as an error toast.
|
||
|
||
`Combobox` is a field with a searchable list whose results come from your code:
|
||
|
||
| Prop | Meaning |
|
||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `value` | `{ id, label, description? } \| null`, what the field shows. It need not be among the search results, so it can show a choice made earlier. |
|
||
| `search` | `({ query }) => Promise<Item[]>`. Called with `""` when the list opens and again, debounced, as the user types. Each `Item` is `{ id, label, description? }` plus any fields you add. |
|
||
| `onSelect` | `({ item }) => void \| Promise<void>`. `item` is the object `search` returned. |
|
||
|
||
Paseo shows "Searching…" while a search runs, "Search failed" with the error message when it
|
||
rejects, and an empty state for no results. It keeps the previous results while a newer search runs
|
||
and ignores a search that a newer one replaced, so `search` needs no cancellation of its own.
|
||
`Combobox` takes the same `title`, `icon` and `disabled` as the other controls, and draws as a row
|
||
with a list in the composer's overflow sheet too.
|
||
|
||
The [New workspace issues example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)
|
||
searches a fixed issue list from a daemon handler and sets the branch and metadata from the choice.
|
||
|
||
## Composer pills
|
||
|
||
`client.addComposerPill({ id, workspaceId, agentId, button })` uses the same [button descriptor](#button-descriptor)
|
||
and returns the same registration. It targets one agent's composer track alongside Tasks and
|
||
Subagents. Composer pills always show the icon and `label` (or `title` when `label` is omitted).
|
||
Menus and popovers add an upward chevron on every layout, because their surface opens above the
|
||
pill; actions show none, so a pill that runs on tap reads differently from one that opens something.
|
||
The track keeps its space above the composer whether or not it has pills, so adding and removing
|
||
pills does not move the transcript.
|
||
|
||
```tsx
|
||
const pill = client.addComposerPill({
|
||
id: "review",
|
||
workspaceId,
|
||
agentId,
|
||
button: {
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
label: "Review",
|
||
behavior: {
|
||
kind: "action",
|
||
onPress() {
|
||
client.openPanel("review", { workspaceId, agentId });
|
||
},
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
For pills that follow the agent directory, use an explicit [owned list subscription](/docs/sdk/events#follow-one-agents-status).
|
||
The [local plugin example](https://github.com/getpaseo/paseo/blob/main/plugin-examples/local-plugin/client/main.tsx)
|
||
replaces registrations on each snapshot and aborts the observation during entry cleanup, including pending bootstrap.
|
||
|
||
## Button descriptor
|
||
|
||
These contracts are exported from `@getpaseo/plugin/client`.
|
||
|
||
| Field | Required | Meaning |
|
||
| ---------- | -------- | ----------------------------------------------------------------------- |
|
||
| `title` | Yes | Non-empty accessible label, tooltip, and sheet title. |
|
||
| `icon` | Yes | Lucide name, `{ svg }`, or `ComponentType<PluginButtonIconProps>`. |
|
||
| `label` | No | Non-empty display text. Omit to use the placement's default. |
|
||
| `visible` | No | Defaults to `true`. False removes the trigger and its layout space. |
|
||
| `disabled` | No | Defaults to `false`. Keeps the button visible and prevents interaction. |
|
||
| `behavior` | Yes | One of the three shapes below. |
|
||
|
||
```tsx
|
||
type PluginButtonBehavior =
|
||
| { kind: "action"; onPress(): void | Promise<void> }
|
||
| { kind: "menu"; items: readonly PluginButtonMenuEntry[] }
|
||
| { kind: "popover"; Content: React.ComponentType<PluginButtonContentProps> };
|
||
```
|
||
|
||
An action runs on the client. Paseo marks the button busy until its promise settles, blocks repeated
|
||
presses, and shows failures in a toast. A failed action can be retried. Use the client's `paseo` for
|
||
ordinary operations and `rpc` for plugin-specific backend work.
|
||
|
||
Menus and popovers open anchored surfaces on wide layouts and bottom sheets on compact layouts.
|
||
The whole trigger opens the surface; there is no split-button behavior.
|
||
|
||
### Menu entries
|
||
|
||
A menu contains items and separators. IDs use lowercase letters, digits, and hyphens, start with
|
||
a letter, and are unique within that menu.
|
||
|
||
```tsx
|
||
const behavior: PluginButtonBehavior = {
|
||
kind: "menu",
|
||
items: [
|
||
{
|
||
kind: "item",
|
||
id: "refresh",
|
||
title: "Refresh review",
|
||
icon: "RefreshCw",
|
||
behavior: { kind: "action", onPress: refreshReview },
|
||
},
|
||
{ kind: "separator", id: "details-divider" },
|
||
{
|
||
kind: "item",
|
||
id: "details",
|
||
title: "Review details",
|
||
behavior: { kind: "popover", Content: ReviewDetails },
|
||
},
|
||
],
|
||
};
|
||
```
|
||
|
||
An item requires `kind: "item"`, `id`, `title`, and `behavior`. Its optional `icon`, `visible`, and
|
||
`disabled` follow the button rules. A separator contains only `kind: "separator"` and `id`.
|
||
Paseo removes leading, trailing, and consecutive separators after filtering hidden items.
|
||
|
||
Items can use all three behaviors. Nested menus open flyouts on wide layouts and pages with back
|
||
navigation within the same compact sheet. Custom content pages open on selection, never hover.
|
||
Choosing an action closes the menu; opening another page keeps it open.
|
||
|
||
### Custom icons and popover content
|
||
|
||
`PluginButtonIconProps` contains `theme`, `host`, `layout`, `size`, `color`, and the target context.
|
||
Render a React Native icon or indicator within the supplied size. Paseo bounds the icon slot and
|
||
owns all pointer interaction. The icon component can use plugin hooks.
|
||
|
||
`PluginButtonContentProps` contains `theme`, `host`, `layout`, the target context, and `close()`.
|
||
Render the body only; Paseo owns anchoring, scrolling, padding, and sheet presentation. Content can
|
||
use `usePaseo`, `useRpc`, `useWorkspace`, `useAgent`, and the installation's React Query cache.
|
||
|
||
The target context is one of:
|
||
|
||
```ts
|
||
{ context: "workspace", workspaceId: string } // Header button
|
||
{ context: "agent", workspaceId: string, agentId: string } // Composer pill
|
||
```
|
||
|
||
### Updates and lifecycle
|
||
|
||
Each registration belongs to one plugin installation, placement, workspace, and (for pills) agent.
|
||
`id` is plugin-local within that target and uses the same format as menu IDs. The same ID may be
|
||
used in different targets or placements. Duplicate registration in the same target throws.
|
||
|
||
`update(patch: Partial<PluginButton>)` changes the descriptor in place, preserving identity and
|
||
order. When changing `behavior`, supply the complete new behavior object. Invalid updates throw
|
||
without changing the existing button. Subscribe to your own model or the client API and call
|
||
`update` to publish reactive changes; mutating the original descriptor does not update the UI.
|
||
|
||
Hiding or disabling a button closes its surface. Updating its behavior also closes the surface.
|
||
Hiding preserves the registration, so showing it again restores its position. It does not cancel
|
||
an action already in progress.
|
||
|
||
`remove()` is idempotent. Updates after removal do nothing. Paseo removes outstanding buttons when
|
||
the plugin installation is disposed (see [Hosts and lifecycle](#hosts-and-lifecycle)). Return cleanup from the client entry for
|
||
your subscriptions, timers, and other resources.
|
||
|
||
## Use the Paseo SDK
|
||
|
||
Use `usePaseo()` for ordinary Paseo operations from a surface. It borrows the selected host's existing connection; do not create another client.
|
||
|
||
`usePaseo()` is your plugin's one Paseo client, the same `client.paseo` your setup receives, in
|
||
every surface. Release what you subscribe to in your cleanup; when the plugin is disabled, reloaded,
|
||
or removed, or its host goes away, Paseo disposes the client and ends every subscription still open.
|
||
|
||
```tsx
|
||
import { usePaseo } from "@getpaseo/plugin/client";
|
||
import { useEffect, useState } from "react";
|
||
import { Text } from "react-native";
|
||
|
||
function ProjectChanges() {
|
||
const paseo = usePaseo();
|
||
const [changes, setChanges] = useState(0);
|
||
useEffect(() => {
|
||
const observation = paseo.observeEvents(["project.update"]);
|
||
observation.subscribe({ snapshot() {}, update: () => setChanges((count) => count + 1) });
|
||
return () => void observation.release();
|
||
}, [paseo]);
|
||
return <Text>{changes} project changes</Text>;
|
||
}
|
||
```
|
||
|
||
```tsx
|
||
import { type PluginSurfaceProps, usePaseo } from "@getpaseo/plugin/client";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
function PullRequestAction({ theme }: PluginSurfaceProps) {
|
||
const paseo = usePaseo();
|
||
|
||
async function createReviewWorkspace() {
|
||
const workspace = await paseo.workspaces.create({
|
||
title: "Review PR 42",
|
||
source: {
|
||
kind: "worktree",
|
||
cwd: "/absolute/path/to/repository",
|
||
action: "checkout",
|
||
checkoutSource: { kind: "change_request", forge: "github", number: 42 },
|
||
},
|
||
});
|
||
await workspace.agents.create({
|
||
config: { provider: "codex/gpt-5.5" },
|
||
prompt: "Review PR #42.",
|
||
});
|
||
}
|
||
|
||
return (
|
||
<Pressable accessibilityRole="button" onPress={() => void createReviewWorkspace()}>
|
||
<Text style={{ color: theme.colors.foreground }}>Create review workspace</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
```
|
||
|
||
The returned API covers projects, workspaces, agents, terminals, providers, and daemon config. See the [SDK API reference](/docs/sdk/reference) for its methods. Connection lifecycle methods are intentionally absent because Paseo owns the connection.
|
||
|
||
To run a helper the user shouldn't see, such as a classifier or summarizer, create it as a [background agent](/docs/sdk/agents#run-a-helper-as-a-background-agent) in an existing workspace.
|
||
|
||
### Discover hosts and target another host
|
||
|
||
Use `useHosts()` to display configured hosts and `getPaseoClient(serverId)` in an action callback
|
||
to run SDK operations on one of them:
|
||
|
||
```tsx
|
||
import { getPaseoClient, useHosts, type PluginSurfaceProps } from "@getpaseo/plugin/client";
|
||
import { useMemo, useState, type ReactElement } from "react";
|
||
import { Pressable, Text, View } from "react-native";
|
||
|
||
export function HostAgents({ theme }: Pick<PluginSurfaceProps, "theme">): ReactElement {
|
||
const hosts = useHosts();
|
||
const textStyle = useMemo(() => ({ color: theme.colors.foreground }), [theme]);
|
||
const [result, setResult] = useState("");
|
||
|
||
async function listAgents(serverId: string): Promise<void> {
|
||
try {
|
||
const { entries } = await getPaseoClient(serverId).agents.list();
|
||
setResult(`${entries.length} agents`);
|
||
} catch (error) {
|
||
setResult(error instanceof Error ? error.message : String(error));
|
||
}
|
||
}
|
||
|
||
const rows = hosts.map((host) => ({
|
||
host,
|
||
onPress() {
|
||
void listAgents(host.serverId);
|
||
},
|
||
}));
|
||
|
||
return (
|
||
<View>
|
||
{rows.map(({ host, onPress }) => (
|
||
<Pressable key={host.serverId} accessibilityRole="button" onPress={onPress}>
|
||
<Text style={textStyle}>
|
||
{host.label}: {host.status}
|
||
</Text>
|
||
</Pressable>
|
||
))}
|
||
<Text style={textStyle}>{result}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`useHosts(): readonly PluginHostSummary[]` includes offline hosts and updates when hosts,
|
||
labels, or statuses change.
|
||
|
||
| Summary field | Type or values | Meaning |
|
||
| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||
| `serverId` | `string` | ID to pass to `getPaseoClient`. |
|
||
| `label` | `string` | Host's display name. |
|
||
| `status` | `"idle"`, `"connecting"`, `"online"`, `"offline"`, `"error"` | Current app connection status. SDK calls require `"online"`. |
|
||
|
||
`getPaseoClient(serverId: string): PaseoApi` borrows the host's authenticated app connection.
|
||
Call it in client entry code or callbacks; it opens no socket and does not require the plugin
|
||
on the target daemon. Acquire the API when performing an action to use the current connection.
|
||
|
||
| Event or condition | Result and caller action |
|
||
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Unknown host ID | Throws `Unknown Paseo host: <id>`; never falls through to another host. |
|
||
| Host is not online | Throws `Paseo host is disconnected: <id>`, including calls through a retained API. Retry when online. |
|
||
| Same connection reconnects | Retained APIs remain usable after reconnection; observations resume automatically. |
|
||
| Connection settings change or the app switches connections, including automatic failover | The old API is released. Call `getPaseoClient(serverId)` again and recreate subscriptions. |
|
||
| Host is removed | Its API is released; the removed ID is unknown. |
|
||
| `client.dispose()` | Releases that API and its observations. A later getter call returns a fresh API over the app connection. Disposing the old API again leaves the new API usable. |
|
||
| Originating plugin unloads | All its borrowed APIs and observations are released, including those targeting other hosts. Retained handles cannot outlive the installation. |
|
||
| Surface host selection changes | `usePaseo()` follows the selected host. An explicitly acquired API keeps its original target. |
|
||
|
||
You can also release individual subscriptions through the normal SDK API.
|
||
|
||
Plugins are trusted app code; cross-host access is intentional. Summaries contain no connection
|
||
URLs or credentials, and borrowed APIs provide no connection lifecycle controls. See the
|
||
[host agents example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/hosts).
|
||
|
||
## Add plugin-specific backend behavior
|
||
|
||
Use plugin RPC only for work that is not a normal Paseo operation: reading a vendor API, accessing daemon-local resources, or keeping credentials off the client.
|
||
|
||
Define one contract with Zod, handle it in the subprocess, and call it from the surface:
|
||
|
||
`shared/greeting.ts`:
|
||
|
||
```ts
|
||
import { defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const greeting = defineRpc({
|
||
name: "greeting.create",
|
||
input: z.object({ name: z.string() }),
|
||
output: z.object({ message: z.string() }),
|
||
});
|
||
```
|
||
|
||
`client/greeting.tsx`:
|
||
|
||
```tsx
|
||
import { useRpc } from "@getpaseo/plugin/client";
|
||
import { greeting } from "../shared/greeting";
|
||
|
||
export function GreetingButton() {
|
||
const createGreeting = useRpc(greeting);
|
||
// Call createGreeting({ name: "Ada" }) from an event or query.
|
||
return null;
|
||
}
|
||
```
|
||
|
||
`server/greeting.ts`:
|
||
|
||
```ts
|
||
import type { RpcInput } from "@getpaseo/plugin";
|
||
import { greeting } from "../shared/greeting";
|
||
|
||
export function createGreeting({ name }: RpcInput<typeof greeting>) {
|
||
return { message: `Hello, ${name}` };
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`:
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { GreetingButton } from "./client/greeting";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "Greeting", Component: GreetingButton });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`index.server.ts`:
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { createGreeting } from "./server/greeting";
|
||
import { greeting } from "./shared/greeting";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.handle(greeting, createGreeting);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Inputs are parsed once in the plugin process; outputs are parsed once on the client. Send schema inputs from the client and return output-schema inputs from the handler; schema transforms run at the receiving side. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations.
|
||
|
||
Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](/docs/sdk/events) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory.
|
||
|
||
## Stream events from the daemon {#subscriptions}
|
||
|
||
A subscription runs a daemon handler for as long as one client listens and sends that client typed
|
||
events. Use it for watchers, tails, and live media; use plugin RPC for a single answer.
|
||
|
||
Define the contract in `shared/`:
|
||
|
||
```ts
|
||
// shared/diff.ts
|
||
import { defineSubscription } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const diffWatch = defineSubscription({
|
||
name: "diff.watch",
|
||
input: z.object({ cwd: z.string(), from: z.string() }),
|
||
event: z.object({ type: z.literal("changes"), files: z.array(z.string()) }),
|
||
});
|
||
```
|
||
|
||
Handle it in `index.server.ts`. The handler receives `push` and an abort `signal` next to `paseo`:
|
||
|
||
```ts
|
||
server.handle(diffWatch, ({ cwd, from }, { push, signal }) => {
|
||
const watcher = watchChanges(cwd, from, (files) => void push({ type: "changes", files }));
|
||
signal.addEventListener("abort", () => watcher.close(), { once: true });
|
||
});
|
||
```
|
||
|
||
Subscribe from a surface with `useSubscription(contract, input, onEvent)`:
|
||
|
||
```tsx
|
||
const [files, setFiles] = useState<string[]>([]);
|
||
const subscription = useSubscription(diffWatch, { cwd, from: "HEAD" }, (event) => {
|
||
setFiles(event.files);
|
||
});
|
||
if (subscription.status === "error") return <Text>{subscription.error.message}</Text>;
|
||
```
|
||
|
||
Outside React, `client.subscribe` takes the same arguments plus options and returns a remover:
|
||
|
||
```ts
|
||
const stop = client.subscribe(diffWatch, { cwd, from: "HEAD" }, onChanges, { signal });
|
||
await stop.ready; // the daemon accepted the subscription
|
||
stop(); // or await stop.release()
|
||
```
|
||
|
||
RPCs and subscriptions share one name space; registering the same name for both fails the plugin
|
||
load.
|
||
|
||
### Handler lifetime
|
||
|
||
| The handler... | Result |
|
||
| --------------------------------------------- | ------------------------------------------------------------ |
|
||
| Throws synchronously, or the input is invalid | The subscribe call fails with the error. No events are sent. |
|
||
| Returns nothing | The subscription stays open until the client releases it. |
|
||
| Returns a promise that resolves | The subscription closes. |
|
||
| Returns a promise that rejects | The subscription closes with the error. |
|
||
|
||
`signal` aborts when the client releases the subscription, unmounts the hook, changes its input,
|
||
disconnects, or the plugin stops. Pushes after the abort are dropped. `push` validates the event
|
||
against the contract and resolves once the event has left the plugin process; await it in a loop
|
||
to pace a producer.
|
||
|
||
Each subscriber runs its own handler. Paseo does not share one handler between clients and does
|
||
not replay missed events: after a reconnect or a plugin reload, mounted surfaces subscribe again and
|
||
the handler starts from the beginning. Share an
|
||
expensive watcher inside your plugin when several subscribers need it.
|
||
|
||
`useSubscription` returns a union on `status`:
|
||
|
||
| Status | Meaning |
|
||
| ------------ | ---------------------------------------------------------------------------------------------- |
|
||
| `connecting` | Sent; the daemon has not accepted it yet. |
|
||
| `live` | The handler is running. Events arrive through `onEvent`. |
|
||
| `closed` | The handler finished. |
|
||
| `error` | The subscribe failed, the handler failed, an event failed the contract, or the plugin stopped. |
|
||
|
||
The hook subscribes again when `input` changes by shallow equality. `onEvent` is always the latest
|
||
render's callback, so an inline function does not resubscribe. `client.subscribe` takes
|
||
`{ signal, onClosed }`; `onClosed` receives `{ error? }`.
|
||
|
||
### Bytes
|
||
|
||
A top-level `Uint8Array` crosses the wire as binary, without JSON or base64. Everything else is
|
||
JSON. The rule applies to subscription events, RPC outputs, and RPC inputs. A Node `Buffer` is a
|
||
`Uint8Array`.
|
||
|
||
```ts
|
||
export const thumbnail = defineRpc({
|
||
name: "thumbnail.render",
|
||
input: z.object({ path: z.string(), width: z.number() }),
|
||
output: z.instanceof(Uint8Array),
|
||
});
|
||
|
||
// index.server.ts
|
||
server.handle(thumbnail, ({ path, width }) => renderPng(path, width));
|
||
|
||
// client
|
||
const renderThumbnail = useRpc(thumbnail);
|
||
const png = await renderThumbnail({ path, width }); // Uint8Array
|
||
```
|
||
|
||
Declare bytes with `z.instanceof(Uint8Array)`. An event can be bytes or JSON per push: declare a
|
||
union and branch with `event instanceof Uint8Array`. A `Uint8Array` nested in an object fails
|
||
validation on the sending side with an error that names the rule; send the bytes as their own
|
||
event or RPC value and the metadata as a separate JSON event.
|
||
|
||
One event or RPC value carries at most 100 MiB less 65 KiB of framing. Push large payloads in
|
||
chunks of a few hundred KiB; each `push` waits for the previous one to leave the plugin process.
|
||
Uploads from a phone have a lower limit: Android closes the connection when one send exceeds
|
||
16 MiB, so split a larger upload into several RPCs.
|
||
|
||
### Several streams on one subscription
|
||
|
||
Put a header byte in front of each payload to multiplex streams. Keep the layout in `shared/`, so
|
||
the handler and the surface call named functions:
|
||
|
||
```ts
|
||
// shared/media-frames.ts
|
||
export const MediaOpcode = { Video: 0x01, Audio: 0x02 } as const;
|
||
|
||
export function encodeMediaFrame(opcode: number, payload: Uint8Array): Uint8Array {
|
||
const bytes = new Uint8Array(1 + payload.byteLength);
|
||
bytes[0] = opcode;
|
||
bytes.set(payload, 1);
|
||
return bytes;
|
||
}
|
||
|
||
export function decodeMediaFrame(bytes: Uint8Array) {
|
||
return { opcode: bytes[0], payload: bytes.subarray(1) }; // a view, not a copy
|
||
}
|
||
|
||
export const mediaStream = defineSubscription({
|
||
name: "media.stream",
|
||
input: z.object({ source: z.string() }),
|
||
event: z.instanceof(Uint8Array),
|
||
});
|
||
```
|
||
|
||
```ts
|
||
useSubscription(mediaStream, { source }, (bytes) => {
|
||
const frame = decodeMediaFrame(bytes);
|
||
if (frame.opcode === MediaOpcode.Audio) audio.enqueue(frame.payload);
|
||
else video.draw(frame.payload);
|
||
});
|
||
```
|
||
|
||
Events from one subscription arrive in push order, JSON and binary alike.
|
||
`plugin-examples/media-stream` streams video and audio this way and uploads a frame back through
|
||
an RPC with a `Uint8Array` input; `plugin-examples/diff-watch` watches a working tree.
|
||
|
||
### Older hosts
|
||
|
||
Subscriptions and binary RPC values need a host that advertises them. Against an older host,
|
||
`useSubscription` reports `error` asking to update the host, `client.subscribe` rejects `ready`
|
||
with the same message, and an RPC with a `Uint8Array` input or output fails. Raise your plugin's
|
||
`requirements.paseo` to the release that ships subscriptions.
|
||
|
||
## Debug backend output
|
||
|
||
Backend contributions can write to stdout and stderr with normal Node logging:
|
||
|
||
```ts
|
||
console.log("Refreshing issues");
|
||
console.error("Issue refresh failed", error);
|
||
```
|
||
|
||
Paseo adds `[paseo]` entries when the plugin starts loading, becomes ready, starts stopping, and has
|
||
stopped. It records compilation and load failures as stderr entries, including failures that happen
|
||
before the plugin subprocess starts. Paseo also captures output emitted during initialization, RPC
|
||
handlers, cleanup, and process failure. Protocol traffic uses a separate channel, so `console.log()`
|
||
cannot corrupt plugin RPCs.
|
||
|
||
Open **Settings → Plugins → Logs** for the plugin, or inspect the same recent tail from the daemon
|
||
CLI:
|
||
|
||
```bash
|
||
paseo plugin logs my-plugin
|
||
paseo plugin logs my-plugin --json
|
||
paseo --host <url> plugin logs my-plugin
|
||
```
|
||
|
||
The command returns a snapshot rather than following live output. Refresh the settings view or run
|
||
the command again for newer entries. Each entry includes its timestamp, stdout or stderr stream,
|
||
sequence, and message.
|
||
|
||
Paseo retains up to 500 entries and 256 KiB per plugin in memory. Individual lines are capped at
|
||
16 KiB. Reload, disable, compilation failure, initialization failure, and process failure retain the
|
||
tail. Removing the plugin clears it, and a daemon restart starts a new tail. Structured copies are
|
||
also written to the daemon log at `$PASEO_HOME/daemon.log`.
|
||
|
||
Only daemon-side output is captured. Logs from client surfaces remain in the app runtime. Do not log
|
||
credentials, access tokens, or other secrets: connected users can read the retained tail, and the
|
||
daemon log persists it.
|
||
|
||
## Add a composer attachment source
|
||
|
||
An attachment source searches external resources and returns a stable text snapshot for an agent prompt. Keep credentials and vendor calls in the backend handler.
|
||
|
||
`shared/issues.ts`:
|
||
|
||
```ts
|
||
import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const searchIssues = defineRpc({
|
||
name: "issues.search",
|
||
input: z.object({ query: z.string() }),
|
||
output: z.object({
|
||
items: z.array(
|
||
z.object({
|
||
id: z.string(),
|
||
identifier: z.string(),
|
||
title: z.string(),
|
||
subtitle: z.string().optional(),
|
||
url: z.string().url(),
|
||
text: z.string(),
|
||
resourceType: z.string(),
|
||
}),
|
||
),
|
||
}),
|
||
});
|
||
|
||
export const issues = defineAttachmentSource({
|
||
id: "issues",
|
||
title: "Acme issue",
|
||
icon: "CircleDot",
|
||
pickerTitle: "Attach Acme issue",
|
||
searchPlaceholder: "Search by identifier or title",
|
||
search: searchIssues,
|
||
});
|
||
```
|
||
|
||
`server/issues.ts`:
|
||
|
||
```ts
|
||
import type { RpcInput } from "@getpaseo/plugin";
|
||
import { searchIssues } from "../shared/issues";
|
||
|
||
export function search({ query }: RpcInput<typeof searchIssues>) {
|
||
return searchAcmeIssues(query);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`:
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { issues } from "./shared/issues";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addAttachmentSource(issues);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`index.server.ts`:
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { search } from "./server/issues";
|
||
import { searchIssues } from "./shared/issues";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.handle(searchIssues, search);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Paseo owns the composer menu, search picker, selected pill, draft state, and submission. The `text` value is the complete snapshot sent to the agent. `icon` is a Lucide name or `{ svg }`; see [Icons](#icons).
|
||
|
||
## Hosts and lifecycle
|
||
|
||
Plugins are installed per daemon. When the same contribution exists on several connected hosts, Paseo shows one sidebar item and adds a host picker. The selected host supplies the bundle, Paseo API, RPC transport, and query cache. Calls never fall through to another host when the selected host is offline.
|
||
|
||
Attachment sources remain scoped to each composer's host.
|
||
|
||
A dropped connection keeps client plugin registrations, mounted surfaces, local state, and query caches. Reconnecting through the existing `DaemonClient` object keeps unchanged installations and refreshes their settings. Consume SDK observation snapshots to refresh other daemon state; setup does not run again for an unchanged installation. Daemon calls still depend on connectivity.
|
||
|
||
Switching connections (for example, from direct to relay) currently replaces the `DaemonClient` object and reinstalls client plugins. Reload, changed bundles or requirements, disable, plugin removal, and host removal also dispose affected installations and clear their query state. A replacement that fails evaluation leaves its contributions unavailable.
|
||
|
||
Workspace panels and Command Center items stay scoped to the active host and exact cached context. An already-restored panel tab
|
||
remains as unavailable until its matching contribution returns or the user closes it. Panel render
|
||
failures stay inside the plugin error boundary.
|
||
|
||
Reload queues behind the daemon's other plugin work, such as a running installation or preparation
|
||
command, and the daemon answers when the plugin is running again or has failed. Nothing reads the
|
||
plugin's status as the reload's outcome: while the reload is queued, `plugin ls`, Settings, and the
|
||
logs show the plugin's previous state, and while the daemon stops and starts it, a status read
|
||
reports `failed` because the plugin is absent from the runtime catalog until its start completes.
|
||
|
||
## Plugin sources
|
||
|
||
Paste one of these source identifiers into **Settings → Plugins**, or pass it to
|
||
`paseo plugin install`. `paseo plugin add <source>` and `paseo plugin install <source>` are aliases.
|
||
The CLI resolves relative directory paths from your current working directory and expands `~`
|
||
to your local home directory, preserving any `:plugin/path` suffix. With `--host`, use an absolute
|
||
path that exists on the daemon host; plugin files are read there and are never uploaded by the CLI.
|
||
Paths entered in Settings resolve relative to the daemon's working directory, and `~` expands to
|
||
the daemon's home directory.
|
||
|
||
| Source | Accepted form | Example |
|
||
| -------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
|
||
| Plugin registry | `owner/slug` or `host/owner/slug` | `acme/review` |
|
||
| Host directory | Absolute or relative path on the daemon host | `/srv/paseo/plugins/review` |
|
||
| GitHub repository | `git:owner/repository` or `github:owner/repository` | `github:acme/paseo-review` |
|
||
| Git repository | `git:<URL or SCP source>`; the prefix is optional for URLs and SCP sources | `git:https://git.example.com/acme/review.git` |
|
||
| npm package | `npm:<name>[@<version, tag, or range>]`; `npm:` is optional | `npm:@acme/paseo-review@^1.2.0` |
|
||
| Plugin below a source root | Append `:relative/plugin/path` to a directory, Git, or npm source | `github:acme/monorepo:plugins/review` |
|
||
|
||
Git URLs use `https://`, `http://`, `ssh://`, `git://`, or `file://`. SCP sources use
|
||
`user@host:path`. `file://` selects Git acquisition, not directory installation.
|
||
|
||
npm names are lowercase unscoped `name` or scoped `@scope/name`. Each component starts with a
|
||
letter or digit and then contains letters, digits, `.`, `_`, or `-`. After the package name, an
|
||
optional `@` introduces an exact version, distribution tag, or npm semver range. Omitting it means
|
||
`latest`. Quote shell arguments containing spaces or comparison operators. npm aliases, tarball
|
||
URLs, and npm's `file:` specifications are not plugin source identifiers; use a directory or Git
|
||
source for those locations. Use the `npm:` prefix for an unscoped package with both a selector
|
||
and subdirectory (`npm:review@1.2.0:nested`); without it, `user@host:path` is an SCP Git source.
|
||
The package registry validates the selected version, tag, or range.
|
||
|
||
Paseo resolves an identifier in this order:
|
||
|
||
1. A bare `owner/slug` is a registry id; local directory sources are `.` or `..`, or start with `./`, `../`, `.\`, `..\`, `/`, `~`, a Windows drive (`C:\` or `C:/`), or a UNC (`\\server\share`) prefix.
|
||
2. Otherwise, recognize `npm:`, `github:`, or `git:` before interpreting a subdirectory suffix.
|
||
`git://` is a Git URL scheme. An explicit prefix selects acquisition of that kind.
|
||
3. Recognize a final `:relative/plugin/path` only when its suffix contains no empty, `.` or `..`
|
||
segments. A lone `.` selects the source root. Both `/` and `\` separate suffix segments; use `/`
|
||
across hosts. URL ports and the separator in an SCP source stay part of the source. A suffix
|
||
that does not satisfy these rules stays part of the identifier.
|
||
4. Resolve bare `owner/slug` through the default plugin registry and `host/owner/slug` through
|
||
that registry host. Resolve Git URLs and SCP sources as Git. `github:` requires
|
||
`owner/repository` shorthand; `git:` accepts it as well as URLs and SCP sources.
|
||
5. Resolve a remaining npm package name with its optional selector through the host's registry.
|
||
Reject anything else.
|
||
|
||
The default registry is `https://plugins.paseo.sh`. Browse [published plugins](https://paseo.sh/plugins)
|
||
and install with `paseo plugin add owner/slug`. Registry records own the revision and plugin path.
|
||
Use `git:owner/repository` for explicit GitHub shorthand or a full Git URL.
|
||
Set `PASEO_PLUGIN_REGISTRY` to use a self-hosted default URL, including a path prefix.
|
||
Private registry credentials use `pluginRegistries: { "host": { "authorization": "Bearer token" } }`
|
||
in daemon config. Restart the daemon after changing these startup settings. Credentials go only
|
||
to that registry, never to artifact hosts or redirects. Installed plugins retain their recorded
|
||
source and registry URL when defaults change.
|
||
|
||
Directory lookup happens on the daemon host. The app uses the `paseo-plugin.json` ID; the CLI
|
||
accepts `--id <runtime-id>` to override it. An existing installation ID is rejected without changing
|
||
its enabled state or files.
|
||
|
||
```bash
|
||
paseo plugin install /srv/paseo/plugins/review
|
||
paseo plugin install github:acme/paseo-review
|
||
paseo plugin install git:https://git.example.com:8443/acme/monorepo.git:plugins/review --ref main
|
||
paseo plugin install git@git.example.com:acme/review.git
|
||
paseo plugin install file:///srv/repos/monorepo:plugins/review
|
||
paseo plugin install npm:paseo-review@1.2.0
|
||
paseo plugin install npm:@acme/paseo-review@next
|
||
paseo plugin install 'npm:@acme/paseo-review@>=1.2.0 <2.0.0' --id review-staging
|
||
paseo plugin install npm:@acme/plugins@^1.2.0:plugins/review
|
||
```
|
||
|
||
`--ref` applies only to Git and accepts a branch, tag, or commit for this installation. Without it,
|
||
Paseo installs the remote's default HEAD. Installation selectors do not constrain later updates. The legacy
|
||
`--path relative/plugin/path` option is equivalent to a subdirectory suffix, including for npm.
|
||
|
||
### npm installation and publishing
|
||
|
||
Install Node.js with npm on the **daemon host** and make `npm` available on the daemon's `PATH`.
|
||
The daemon uses that host's npm user/global configuration and environment for registry selection
|
||
and authentication, including scope-specific registries. The client does not download packages or
|
||
run npm. Loading, enabling, and reloading an installed plugin do not need npm.
|
||
|
||
The daemon installs each candidate and its production dependencies in an isolated directory. It
|
||
keeps the complete dependency tree and `package-lock.json` when activating it. The installed
|
||
package and lockfile provide its current version and artifact integrity. A version, tag, or range
|
||
chooses content for this installation only.
|
||
|
||
The installed lockfile records what this installation resolved. Authors submitting npm plugins
|
||
with runtime dependencies must also ship the [publication lock](/docs/plugins/publishing#2-lock-installed-dependencies).
|
||
For package contents, preparation and submission, see [Publish a plugin](/docs/plugins/publishing).
|
||
|
||
A failed download, dependency installation, manifest check, preparation command, compilation, or
|
||
activation discards the candidate. Other installed plugins keep running. Removing an npm plugin
|
||
deletes its managed files; removing a directory plugin keeps your source directory.
|
||
|
||
## CLI reference
|
||
|
||
```bash
|
||
paseo plugin init /absolute/path/to/plugin
|
||
paseo plugin install /absolute/path/to/plugin
|
||
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
|
||
paseo plugin add owner/slug
|
||
paseo plugin add git:owner/repository
|
||
paseo plugin add https://git.example.com/owner/repository.git --ref main
|
||
paseo plugin add git:owner/monorepo:plugins/review
|
||
paseo plugin ls [id]
|
||
paseo plugin update <id>
|
||
paseo plugin update --all --check
|
||
paseo plugin update --all --yes
|
||
paseo plugin update my-plugin --version 1.2.0
|
||
paseo plugin update my-plugin --ref v2
|
||
paseo plugin reload my-plugin
|
||
paseo plugin logs my-plugin
|
||
paseo plugin disable my-plugin
|
||
paseo plugin enable my-plugin
|
||
paseo plugin remove my-plugin
|
||
```
|
||
|
||
`ls` and Settings show source identity and the current installed revision without contacting the
|
||
remote. Identity includes the selected subdirectory and excludes installation selectors.
|
||
|
||
`update <id>` checks for an update, shows the current and proposed revision with available review
|
||
links, and asks for approval. Declining leaves the installed content unchanged.
|
||
|
||
- npm checks the package's `latest` version. It offers only a newer version; an installed version
|
||
newer than latest stays installed. Host npm registry/auth configuration governs resolution.
|
||
- Git checks the remote's current default HEAD, regardless of the branch, tag, or commit selected
|
||
during installation.
|
||
- Directory plugins are skipped; edit the directory and use `reload`.
|
||
|
||
`--check` only previews, including with an explicit target or `--yes`. `--yes` skips the question.
|
||
`--all` checks each configured plugin and reports independent results; one failure does not stop
|
||
others. Neither flag permits ordinary npm downgrades.
|
||
|
||
`--version <version|tag|range>` or `--ref <branch|tag|commit>` selects one matching plugin's update
|
||
content and applies it without another question. An explicit npm version can be older. The next
|
||
ordinary update checks latest again. Explicit targets cannot be combined with `--all`.
|
||
JSON and noninteractive ordinary updates require `--yes`.
|
||
|
||
Approval acquires exactly the reviewed commit or npm artifact. If it is unavailable or the installed
|
||
plugin changed while reviewing, the update fails and asks you to check again. Failed preparation or
|
||
activation retains the previous installation. Manual app update review is not available yet.
|
||
|
||
Put `--host <url>` before a management command when the target is not the CLI's default daemon. `remove`
|
||
never deletes a directory source; it deletes managed files for Git and npm sources. The install-time
|
||
`--id` is the runtime ID and allows the same directory or repository to be installed more than once.
|
||
|
||
> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Server code and preparation commands run unsandboxed with the daemon user's access on the daemon host; client contributions run inside Paseo. Dependencies and future updates are part of that decision. With the global `--host` option, commands run on the remote daemon host.
|
||
|
||
Most plugins should omit `build`. Use it only when the staged checkout must install a dependency
|
||
that Paseo does not provide, generate source or assets, or perform another required preparation
|
||
step:
|
||
|
||
```json
|
||
{
|
||
"id": "review",
|
||
"requirements": { "paseo": ">=0.8.0" },
|
||
"build": [["npm", "ci", "--omit=dev"]]
|
||
}
|
||
```
|
||
|
||
`build` is a list of non-empty argv arrays. Paseo runs each executable directly, without a shell,
|
||
from the staged plugin directory after resolving the exact commit and manifest. It never infers a
|
||
package manager or commands from lockfiles. Install and update both run `build` before validation,
|
||
compilation, activation, or replacement. A failing command reports its output, discards the
|
||
candidate, and leaves the installed/running version intact. The daemon log records each command and
|
||
output; with the global `--host` option, execution is on that daemon host.
|
||
|
||
Run `npm run typecheck` before install or reload. Manage plugin source entries with the CLI or
|
||
Settings; see [Plugin sources](#plugin-sources) for install syntax.
|
||
|
||
The daemon-wide **Enable plugins** switch lives under **Settings → Plugins**. A configured plugin remains `disabled` until that switch and the plugin's own enabled state are both on.
|
||
|
||
The switch is the root `pluginsEnabled` field in `config.json`. After changing it, run `paseo reload --json`. Enabling starts every configured plugin whose own `enabled` value is not `false`; disabling tears down all plugins. No daemon restart is required. Manual edits to plugin source entries are not reloaded; use the plugin lifecycle commands for those.
|
||
|
||
## Load failures
|
||
|
||
Use `paseo plugin ls` to read the current status and error.
|
||
|
||
| Symptom | Check |
|
||
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `This plugin was made for an older version of Paseo` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/migration). |
|
||
| `Plugin entry points are missing` | Neither `index.client.tsx` nor `index.server.ts` exists with that exact name. |
|
||
| `server-only module cannot be imported into the plugin client bundle` | Client code imports `server/`. Move the work behind an RPC and import its contract from `shared/`. |
|
||
| `client-only module cannot be imported into the plugin server bundle` | Server code imports `client/`. Register that contribution from `index.client.tsx` instead. |
|
||
| `Node module cannot be imported into the plugin client bundle` | Client code imports `node:*`. Move the operation to `server/` and call it through an RPC. |
|
||
| Sidebar item is missing | The plugin is `running`, the item is not hidden in Settings > Sidebar, its component does not throw, and the client is on the installation's host. |
|
||
| Client module is unavailable | Import only the host-provided client modules listed above. |
|
||
| RPC rejects | Check both Zod schemas and the daemon-side handler error. |
|
||
| Edited code does not appear | Run `npm run typecheck`, then `paseo plugin reload <id>`. |
|
||
| Reload fails | Read `paseo plugin ls` and `paseo plugin logs <id>`, fix the source error, then reload; Paseo does not restore the previous bundle. |
|
||
| Plugin exits unexpectedly | Read `paseo plugin logs <id>` for retained initialization, cleanup, stderr, and final crash output. |
|