From 3fcfb7abf77784bfe52567f7670870834efb65d1 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sun, 14 Jun 2026 02:05:11 +0200 Subject: [PATCH] docs(coding-agent): document extension resource lifecycle --- packages/coding-agent/docs/extensions.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md index cb02960f3..7038351d1 100644 --- a/packages/coding-agent/docs/extensions.md +++ b/packages/coding-agent/docs/extensions.md @@ -216,6 +216,12 @@ export default async function (pi: ExtensionAPI) { This pattern makes the fetched models available during normal startup and to `pi --list-models`. +### Long-lived resources and shutdown + +Extension factories may run in invocations that never start a session. Do not start background resources such as processes, sockets, file watchers, or timers from the factory. + +Defer background resource startup until `session_start` or the command/tool/event that needs the resource. Register an idempotent `session_shutdown` handler to close any session-scoped resources you start. + ### Extension Styles **Single file** - simplest, for small extensions: @@ -471,7 +477,7 @@ pi.on("session_tree", async (event, ctx) => { #### session_shutdown -Fired before an extension runtime is torn down. +Fired before a started session runtime is torn down. Use this to clean up resources opened from `session_start` or other session-scoped hooks. ```typescript pi.on("session_shutdown", async (event, ctx) => {