Package lifecycle, hosts and permissions
How AI Game Dev runs a package: the Extension Host, lazy activation, desktop versus CLI, levels and updates, errors and logs, permissions, and API versioning.
This page explains what happens to a package between install and removal: where its code runs, when it starts and stops, what it is allowed to do, how errors reach you, and how the API it is written against stays compatible. It is the background you need before you ship a package other people install.
Where a package runs
The app runs package code in an Extension Host, a separate process, the way VS Code runs extensions. The app's background service (the Kernel) runs one Extension Host per open project, shared by every desktop window and CLI that has that project open. Your code talks to the app only through ctx.aigd, over a message channel.
| Desktop app | gamedev CLI | |
|---|---|---|
| UI it shows | Everything: menus, panels, views, custom editors, status bar, tutorials, webviews | Slash commands, Tools rows, messages, quick picks, input boxes, forms, progress lines |
| Desktop-only calls | Work | Resolve to undefined or an inert object, logged once |
| The Extension Host process | Shared per project | Shared per project |
A window with no project runs no host. A package installed at the user level runs in every open project unless that project excludes it.
Lazy activation
- Install. The app reads the manifest and registers every declared contribution at once: the slash command, the Tools switch, the menu items and views appear without running any code.
- Activate. The first time something needs the code (a command runs, a view opens, a capability is switched on, a matching file opens, an engine project is found) the host loads
mainand callsactivate(ctx). Dependencies activate first.activatehas 30 seconds. - Run. Your handlers answer the app's calls. Everything you registered is in
ctx.subscriptions. - Stop. On removal, a disabled package, an update or a host restart the host calls
deactivate()(optional) and disposesctx.subscriptions.
A package with main and no event at all starts after the first render (onStartupFinished). The full list of events is in the manifest reference.
The host restarts when the set of active packages changes, and after a crash (after 1, 5 and 30 seconds). After three crashes in five minutes it stays stopped until the user clicks Reload in the Packages window.
Levels, locks and updates
Users add a package at one of three levels:
| Level | Declared in | Shared |
|---|---|---|
| User | ~/.ai-game-dev/packages.json | Every project of this user |
| Project | <project>/.ai-game-dev/packages.json | Committed: every teammate gets it |
| Local | <project>/.ai-game-dev/packages.local.json | This computer only, never committed |
Local beats project, project beats user. A lock file next to each level pins the exact version, tarball and hashes, so a teammate installs the same bytes. Auto-update is on by default (per package, per computer): every four hours the app moves each package to the newest version inside its declared range that the app can run, and shows one notification for the whole run. A file: link and a GitHub source pinned to a tag never auto-update.
Errors and logs
The host attributes every failure to its package: a throw in activate, deactivate or a handler, an uncaught exception or unhandled rejection from your files, ctx.reportError(err) and ctx.log.error(msg, err). Each package's Errors tab in the Packages window shows "N errors · M crashes" and the recent list with stacks.
gamedev pkg logs acme.level-tools # its last 100 lines
gamedev pkg logs acme.level-tools -f # and every new one until Ctrl+CLogs live in ~/.ai-game-dev/daemon/logs/ on every platform. Errors of third-party packages are never sent to AI Game Dev's crash reporting; only AI Game Dev's own packages report there, and only with the user's crash-reporting consent.
Permissions and trust
AI Game Dev follows the VS Code model: there is no sandbox and no permission prompt. A package's code runs with the user's own permissions: it can read and write files, start processes and use the network, like any program the user installs. What keeps users informed instead:
- Everything visible first. All a package shows is declared in its manifest and visible before its code runs.
- Ownership is enforced. A package can only register or change ids it owns (
<package id>.<local>commands, views and context keys,<publisher>--<name>servers), checked at load and on every call. It may run any command, its own, another package's or an app command; a webview page may run only its own package's commands and app commands. - What it declares is shown. Before install, the Packages window shows what the registry index says: native code, Claude plugins, dependencies. Once installed it also shows whether the package runs code, starts tool servers or contributes a game engine. This is information, never a gate.
- Registry checks. Every version in the community registry passed automatic checks for credentials, prompt injection aimed at the agent, malware and archive tricks; see Registry rules and checks.
- Revocation. AI Game Dev can revoke a malicious version; every app turns it off on its next index read (within about half an hour).
- Webview pages are isolated. A page runs in a sandboxed frame with no Node.js; a webview window has no network access at all.
As an author: do not ship secrets, keep what your package does obvious from its README and manifest, and ask the user before anything destructive.
Versioning and compatibility
Two numbers version the API, and neither is your package's version:
- The package API version (now 0.4.0) grows by additions only: new members and contribution points. Your
aigd.d.tsnames the version it was written for. - The oldest supported
engines.aigd(now 0.18.0) is the oldest floor the app still loads. Raising it is the only way a stable member is ever removed, after at least two minor releases of deprecation warnings.
Rules for you:
- Set
engines.aigdto the oldest app you tested with. An app older than that refuses the package and tells the user to update. - Feature-test optional members (
aigd.gameEngines?,item.pulse?.()) when you want to support apps older than the member. - Proposed members are not covered by any of this. See stable and proposed API.
- Your stored data is yours: version it with
dataVersionand migrate it inactivate.
Related pages
- Package API for the calls.
- Packages for levels and updates from the user's side.
- Package CLI reference for
pkg logs,linkanddev.