Extension Version Management
View installation state across all content kinds, review workflow impact, and update extensions from an extension's Version & security tab.
An extension's row on Settings → Platform → Extensions → Installed (and its sheet's Includes and Version & security tabs) is the single place to track which version is installed, see per-content-kind install state, and apply updates. For the full versioning model from an extension author's perspective — semver rules, the release checklist, and how pins/policies decide what runs — see Extension versioning. When an extension has an update available, its row on the Extensions → Installed tab shows it in the version column — 1.3.0 → 1.4.0 — never on the state line, so a pending update can't hide a failing credential. The update itself is reviewed and applied in the extension's Version & security tab. Data sources are not part of that update — they update per workspace — so when installed data sources are behind the latest release, the tab's Installed release section says how many and on which version, and a workspace admin updates them with Update to vX in Analytics → Marketplace (one click reconciles the extension's full set of sources).
Update behavior by content type
Not every kind of extension content updates the same way — the platform applies the least automation that is safe for each kind. This table is the mental model; the sections below detail each.
| Content type | How updates apply | Why |
|---|---|---|
| Static reference data sources (inline data, no external calls) | Automatic on sync — installed when an extension update reaches your catalog, unless the extension's policy is Manual. | Additive, makes no external calls, and can't overwrite your data — the safest kind. |
| External (polling) data sources | Install from Analytics → Marketplace — Update to vX reconciles the extension's full set. | A new source begins calling an external system, so installing it is your decision. |
| Ontology & KB domains | New schema items apply automatically on sync in every existing workspace environment where the extension is already installed; changes to existing items, and new KB domains, apply when you click Update extension. | Adding new object/link types is safe; modifying or removing them can affect bound tables, analytics, and the graph. |
| Process flows | Automatic — always the latest catalog version. | A template only appears in the gallery; it runs nothing until a workspace opts in. |
| Extensions | Per connection: manual (default), or opt-in auto_patch / auto_minor; breaking changes always held. | Executable vendor code + credentials + egress — the highest-risk kind. |
| Workflows | Deployed per environment from the agentic Extensions page; a newer release shows Update available on that environment's row, and you apply it there. | You choose which environment runs which version, and an update never discards changes made in that environment. |
| Notebooks | Stored at install; materialize / update per workspace in Analytics. | Nothing runs until you materialize it. |
Safety guarantees, always: an automatic apply only ever adds — it never deletes your data, never overwrites a source or type you already have, never starts a new external call, and never runs new code without you. A breaking extension change is never applied automatically — it is flagged and waits for your review.
Each extension has an update policy (default Automatic). Additive, no-egress content — static reference data sources and new ontology schema items — installs automatically when an extension update reaches your catalog. Set an extension's policy to Manual to review every update yourself; anything that calls an external system, runs code, or changes an existing item always keeps its review step regardless of policy. So you never miss a withheld update, the extension's Includes tab flags declared-but-uninstalled data sources ("N available, not installed"), and the map shows a not provisioned state when a layer's backing table is missing — instead of a silent "(0)".
When a new version drops an ontology item
An update never removes an ontology item that a newer version of the extension no longer declares — in any mode, including Update extension. The item stays live, and the platform proposes its removal for your review instead: it opens a draft branch on the extension's ontology, named for example osint-intelligence: 1 item no longer declared, review to retire (…), in each workspace environment where the extension is installed. Find it in Ontology → History (Analytics). Submit and publish the branch to retire the items; archive it to keep them. The same branch is reused on every later sync until the set of dropped items changes, so archiving it is a lasting decision. Only items the extension itself declared in its previous version are ever proposed: anything you or your team added to the ontology, and anything another source contributed, is never part of this branch.
Only items whose removal cannot lose data are proposed: watch rules, bindings, action types, shapes, rules and aliases. Retiring a watch rule keeps its past detections; retiring a binding keeps its table and rows. A dropped object type or link type is never proposed, because retiring it would strand every record of that type — it stays live, and removing it is a deliberate schema change you make yourself. The Extensions page does not yet link to these branches.
Seeing where an extension is used
The catalog table's In use column shows what each installed extension actually produced in your organization:
- Workflows — workflows deployed from the extension, per workspace environment. Click a workflow to open it in Agentic.
- Process flows — live process-flow instances created from the extension's templates. The count is the true total; the popover lists the 25 most recent. Click an instance to open it in Agentic.
- Data sources — data sources installed from the extension. Click to open the data sources page in Analytics.
A dash (—) means the extension is in your catalog but nothing currently uses it — a useful signal before retiring an extension.
Expanding an extension row shows the same information in detail, plus Workflows using this extension's extensions: workflows anywhere in your organization whose blocks call an extension this extension installed. This is the same impact analysis the update flow runs — shown at all times, so you can assess blast radius before retiring or updating.
If a panel shows State unavailable, one backing service could not be reached; the other panels remain accurate.
Install State Column
Each row in the Catalog tab shows one extension at its highest available version. The Install state column shows the most important state across all of that extension's content kinds:
| State | Meaning |
|---|---|
| Update available | At least one content kind has a newer version in the catalog than what is currently installed. |
| Installed | All installed content kinds are current (no update needed). |
| Not installed | No content from this extension has been installed in your organization. |
When an update is available, the version column shows the installed version alongside the latest: for example v1.1.0 → v1.1.1.
For ontology content, this organization-level state is deliberately strict. It is shown only after the platform reads every expected workspace environment and finds the same extension version, ontology identity, catalog/source provenance, and normalized manifest in each one. A missing or divergent environment makes the ontology panel report State unavailable instead of choosing one row and presenting it as organization-wide truth.
Expanded Row — Per-Kind State
Click any row to expand it and see the install state broken down by content kind:
Extensions
One line per vendor included in the extension. Shows the installed version and whether an update is pending. The update check is based on the artifact hash: if the published artifact differs from what is installed, an update is available.
Ontology and KB Domains
Shows one representative installed extension version and the date it was last applied, but only after all existing workspace environments pass the consistency check above. An organization-wide install or update fans out to every existing environment; an install/update from Analytics → Marketplace targets only the active environment.
Consistency includes the catalog row, extension-source ID and entry reference, and the complete normalized manifest snapshot. Environment-local revision IDs and timestamps are expected to differ and are not used for version comparison. The source fields can be empty for legacy/manual installs, but kernel-backed reads always return the manifest snapshot and preserve any available provenance.
For API consumers, InstalledExtensionRow remains source-compatible: sourceId
and sourceEntryRef are additive optional-nullable fields, and legacy TypeScript
fixtures may still omit manifestSnapshot as an input convenience. A
kernel-backed installed row always supplies the complete normalized
manifestSnapshot and returns the two provenance fields (possibly null);
clients must not replace the snapshot with a hash or a reconstructed subset.
Workflows
Shows one row per workspace environment in which this extension's workflows have been deployed. Each row includes:
- The workspace environment name.
- The installed extension version, or version unknown if the workflow was deployed before version tracking was introduced. "Version unknown" is harmless — the workflow is running, but its extension version cannot be compared.
Deploying a workflow to a workspace is a separate action on the agentic Extensions page. The extension's Includes tab shows workflows that were already deployed; "not deployed" environments are omitted from the list.
Updating a deployed workflow
When the catalog holds a newer release of a workflow than an environment runs, that environment's row on the agentic Extensions page shows Update available. Each environment has its own signal and its own update: updating the development environment does not touch production.
These rows are grouped in their own Updates available section at the top of the page. Each row shows both versions, for example Installed v1.0.0 → v2.0.0. If the environment never recorded the version it was deployed from, the row reads Version unknown → v2.0.0. To list only these rows, turn on the Updates filter next to the content-type filter. It shows how many rows have an update, and you can use it together with a content-type filter. Every member can see the signal. Only workspace admins get Review update.
If the new release links its release notes (links.releaseNotes in the extension's extension.json), a Release notes link appears next to the versions and opens them in a new tab. Only http and https links are shown.
The platform normally detects an update by comparing the release's content with the content the environment installed. A workflow deployed before content was recorded has nothing to compare. For those workflows the platform compares version numbers instead, and shows an update only when the catalog's version is strictly newer.
A catalog release with a lower version than the one an environment runs is never shown as an update, even when its content differs. This happens when a newer release is withdrawn. The environment keeps the version it has.
A workflow is tracked by the package.id in its workflow manifest, so within one organization each package id belongs to one extension. Publishing or syncing an extension whose workflow uses a package id that another extension already ships is refused with workflow_package_id_claimed, and the message names that extension. Give the workflow manifest its own package.id. Otherwise both extensions would install into the same workflow in every environment, and one could replace the other's.
If two extensions already ship the same workflow under the same package id (for example, both were published before this check existed), the extension that shipped the package id first can still publish new releases. The other extension stays refused until it changes its package.id.
Until only one extension ships it, the workflow is shown in a Shipped by more than one extension section on the agentic Extensions page, with a Conflict badge that names both extensions. Nobody can turn it on, update it or turn it off from either extension, and no update is shown for it anywhere. The platform cannot tell which extension an environment's copy came from, so it changes nothing rather than risk overwriting the wrong one. A request to add, update or remove it is refused with workflow_row_contested (HTTP 409), and the message names both extensions. To resolve the conflict, give one extension's workflow manifest its own package.id, or remove one of the extensions from the catalog.
If a workflow the update replaces changes while the update runs, the update is refused with WORKFLOW_CONCURRENT_CHANGE (HTTP 409, with retryable: true) and the environment keeps the workflows it had. Run the update again.
The same signal is shown wherever you meet the workflow, always for the environment you are working in:
| Where | What you see |
|---|---|
| Marketplace in the agentic sidebar | A count of workflows in this environment with a newer release. Personal workspaces have no Marketplace entry and show no count. |
| The workflow list (the workflow switcher in the editor) | An Update available badge on the workflow's row. |
| The workflow editor header | An Update available badge next to the workflow name. |
| Settings → Extensions on the platform | A dot next to the extension's version, and a Workflow updates in workspaces card on its Version & security tab naming the workflows and the number of environments, with a link to the Marketplace (it opens your active workspace; switch workspace there if the workflow lives elsewhere). The organization's Update button does not apply these updates. |
The badges link to the Marketplace. Hover a badge to see which extension has the newer release and the version it moves to. The count refreshes at most every few minutes, so an update you just applied can take a moment to disappear from it.
A workspace admin clicks Review update to see, before anything changes:
- What the release changes — blocks added, removed, or changed.
- Changes made here that are kept — edits you made in this environment (a model, a prompt, a credential, a tool, a trigger setting, and whether a block uses its advanced mode) are carried over, not reset.
- Published surfaces that stay on their version — a published form or agent keeps pointing at the deployment version it was published on. Republish it when you want it to use the update.
Update saves the merged workflow as a new deployment version; earlier versions stay in the deployment history. Webhook URLs and schedules are kept.
When a value was changed here and the new release changes it too, the panel lists it under Choose which value to keep. For each one, pick:
- Use the release's version — your change to that field is dropped and the release's value is used.
- Keep mine — your value stays, and the release's change to that one field is skipped. Everything else in the release still applies.
Nothing is chosen for you: Update stays disabled until every listed value has a choice. The earlier version stays in the deployment history, so you can go back to it.
The update is refused — and Update stays disabled — when it cannot keep one of your changes in any other way. The panel names each reason:
| Reason | What to do |
|---|---|
| A value was changed here and the new release removes its block or field, or changes the block to a different type (for example a credential chosen for one vendor, on a block that now calls another) | Remove the change here, then update. |
| A block was added here, or a release block was deleted here | Undo the structural change, then update. |
| Connections were changed here and in the release, differently | Restore the release's connections, then update. |
| The release removes the trigger behind a live webhook URL or schedule | Move the callers of that webhook, or the schedule, off the trigger first. |
| The installed release can no longer be read (this includes a workflow deployed before content was recorded, which has a newer release) | Remove the workflow from the environment and deploy it again. |
The server checks again, with your choices, when you click Update. A conflict that appears after you opened the panel is shown in the same list, and nothing is changed.
Data Sources
Shows one row per workspace environment in which a data source from this extension is installed. Installing and updating data sources happens on Analytics → Marketplace: when a newer extension version is in the catalog, each installed source there shows an Update to vX action that reconciles the whole extension's data-source set — existing sources are refreshed, sources added by the new version are installed, and sources it removed are pruned. A data source that is already added in another environment of your organization is skipped — a data source lives in one environment at a time — and so, in a personal workspace, is a database source, which no connection can serve there; the update names each one it skipped and says why, and the rest are updated. See Extensions.
Process Flows
Process flows always track the latest catalog version — they do not have a fixed installed version. The expanded row shows a badge confirming this. There is no update action for process flows; they automatically use the content from the newest active catalog row for this extension.
Updating an Extension
When at least one content kind has an update available, an update bar appears at the top of the expanded row.
Click the extension in the Catalog tab to open the expanded view. If there is an update available, the update bar shows the target version (for example, Update to v1.1.1) and a summary of which extensions will be affected.
For extensions that include extension content, the platform automatically loads a workflow impact analysis — showing which workflows reference tools from this extension's extensions. The Update extension button stays disabled until this analysis has finished loading.
If the impact analysis fails to load, the Update extension button remains disabled. Check your network connection or contact your platform administrator.
The platform diffs the installed and target extension manifests and lists detected breaking changes directly in the update bar: removed tools, new required inputs, changed input/output types, or auth-mode changes — each annotated with the tool it affects.
Two warning levels can appear:
- Potentially breaking (amber) — the update is a major version bump, or the manifest diff found breaking changes that the author declared correctly.
- Breaking changes in a non-major update (red) — the manifest diff found breaking changes but the version bump is only a minor or patch. Treat this with extra care and contact the extension author.
Review the affected-workflows list together with these findings before proceeding.
The platform installs the latest catalog version for this extension. Extension code stays organization-owned; ontology and KB content fan out to every existing workspace environment. A success toast confirms the update only after all ontology targets succeed. If one target fails, successful targets remain applied and a retry safely revisits the operation.
Per-environment content is updated from its own surface: data sources from Analytics → Marketplace (where the update reconciles the extension's full source set — see Data Sources above), and workflows with Review update on each environment's row of the agentic Extensions page (see Updating a deployed workflow).
Clicking Update extension also moves your organization's version pin for the extension's extensions: in-flight workflow runs finish on the version they started with, and new runs use the updated version.
Version Pinning and Update Policies
Installed extension versions are pinned per connection. A newer version arriving in your catalog (for example via a Git extension source sync) is staged but inert — nothing changes about what your workflows execute until the pin moves. The pin moves in one of two ways:
- Manually — you click Update extension after the impact review (the default for every connection).
- Automatically — a connection can opt in to auto-updates via its update policy:
| Policy | Behavior |
|---|---|
manual (default) | Updates are staged only; you apply them from the extension's Version & security tab. |
auto_patch | Patch releases (1.1.0 → 1.1.1) apply automatically when the manifest diff finds no breaking changes. |
auto_minor | Patch and minor releases apply automatically when the manifest diff finds no breaking changes. |
Auto-updates never apply when the manifest diff detects a breaking change — the connection is flagged (update blocked: breaking_diff) and the update waits for your manual review in the extension's Version & security tab. Major version bumps always require a manual update.
SDK Compatibility Errors
Code releases are compiled against a specific version of the Scrydon authoring SDK. If an archive was built against an SDK contract the platform no longer (or does not yet) support, you will see:
- At install time: the extension install fails with
extension_contract_incompatibleand a message naming the contract versions involved. - At run time: tools from the archive fail with
BUNDLE_CONTRACT_INCOMPATIBLEinstead of executing.
Both messages mean the same thing: the archive needs to be republished with a current @scrydon/sdk-authoring release. If you author the extension, rebuild it with the latest SDK and publish a new version; if it comes from a vendor, ask them for an updated release. Archives built against the immediately previous SDK contract continue to work — the platform translates for them automatically.
Retired and Quarantined Versions
Each version in your catalog is active, quarantined or retired.
- A retired version has left the catalog: an administrator retired it, or its source stopped listing it (see Extension sources). It can no longer be installed.
- A quarantined version stays in the catalog but is held for review. Quarantine is set by your platform operator; there is no action in the product to set or clear it yet.
What each state allows:
| Active | Quarantined | Retired | |
|---|---|---|---|
| Install, update or repair from Analytics → Marketplace or the Add data source sheet | Yes | No: listed as unavailable, and the install is refused with marketplace_content_quarantined | No: the version is not offered (marketplace_content_not_found) |
| Remove from the Marketplace | Yes | Yes | Not applicable |
| Applied automatically after a source sync | Yes | No | No |
| A data source already running from it | Keeps running | Keeps running, with a warning in its detail view | Keeps running |
A quarantined or retired version never stops a data source that is already running: it is flagged, never removed. To move off it, install a supported version.
When the automatic apply after a source sync reaches a data source from a retired or quarantined version, the apply is refused before anything is written, with data_source_extension_retired or data_source_extension_quarantined (HTTP 409).
Other Live Catalog Versions
At the bottom of the expanded row, Other live catalog versions lists any older versions of this extension that are still present in your catalog (for example, if a previous version was installed and the catalog was not cleaned up). These entries are informational — they show what is available but are not the active installed version.
Finding Updates for Installed Extensions
When an extension has an update available, the vendor's row on Settings → Platform → Extensions → Installed shows it in the version column as 1.3.0 → 1.4.0. The state line stays free for anything that needs a human. Opening the row leads to its Version & security tab, where the update card says what changes and what carries over, and you apply it there.
The Add extension catalog only offers what is not installed yet; an installed extension is the vendor's own row there, muted in place, with Manage opening its sheet.