@code-yeongyu/senpi 2026.8.23 → 2026.8.24

package/dist/modes/interactive/streaming-reveal.d.ts

@@ -15,6 +15,14 @@ export declare class StreamingRevealController {
     begin(component: StreamingRevealComponent, message: AssistantMessage): void;
     setTarget(message: AssistantMessage): void;
     resyncVisibility(): void;
+    /**
+     * True while this controller is the pacing writer for the given head message:
+     * smooth streaming is on, the head carries no toolCall block (those dump in
+     * full), and a component is still bound (before stop()). While true, callers
+     * must not overwrite the component's content, or the next reveal tick
+     * repaints a shorter prefix after their full write (dual-write flicker).
+     */
+    isPacingHead(message: AssistantMessage): boolean;
     stop(): void;
 }
 //# sourceMappingURL=streaming-reveal.d.ts.map

package/dist/modes/interactive/streaming-reveal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-reveal.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/streaming-reveal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAWnF,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAE7C,KAAK,wBAAwB,GAAG,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAAC;AAEjF,MAAM,MAAM,gCAAgC,GAAG;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAC3C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,MAAM,CAAC;IAC7C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,OAAO,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAEF,qBAAa,yBAAyB;;gBAqBzB,OAAO,EAAE,gCAAgC;IAOrD,KAAK,CAAC,SAAS,EAAE,wBAAwB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAa3E,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAiB1C,gBAAgB,IAAI,IAAI;IAOxB,IAAI,IAAI,IAAI;CAkGZ"}
+{"version":3,"file":"streaming-reveal.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/streaming-reveal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAWnF,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAE7C,KAAK,wBAAwB,GAAG,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAAC;AAEjF,MAAM,MAAM,gCAAgC,GAAG;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAC3C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,MAAM,CAAC;IAC7C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,OAAO,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC;AAEF,qBAAa,yBAAyB;;gBAqBzB,OAAO,EAAE,gCAAgC;IAOrD,KAAK,CAAC,SAAS,EAAE,wBAAwB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAa3E,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAiB1C,gBAAgB,IAAI,IAAI;IAOxB;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;IAKhD,IAAI,IAAI,IAAI;CAkGZ"}

package/dist/modes/interactive/streaming-reveal.js

@@ -64,6 +64,18 @@ export class StreamingRevealController {
         this.#revealed = Math.min(this.#revealed, this.#visibleUnits(this.#target));
         this.#applyTarget();
     }
+    /**
+     * True while this controller is the pacing writer for the given head message:
+     * smooth streaming is on, the head carries no toolCall block (those dump in
+     * full), and a component is still bound (before stop()). While true, callers
+     * must not overwrite the component's content, or the next reveal tick
+     * repaints a shorter prefix after their full write (dual-write flicker).
+     */
+    isPacingHead(message) {
+        if (!this.#target || !this.#component)
+            return false;
+        return this.#getSmoothStreaming() && !message.content.some((block) => block.type === "toolCall");
+    }
     stop() {
         this.#stopTimer();
         this.#target = undefined;

package/dist/modes/interactive/streaming-reveal.js.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-reveal.js","sourceRoot":"","sources":["../../../src/modes/interactive/streaming-reveal.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { AssistantMessageComponent } from \"./components/assistant-message.ts\";\nimport { BlockUnitCounter, buildDisplayMessage, countVisibleUnits } from \"./streaming-reveal-content.ts\";\nimport {\n\tDEFAULT_SMOOTH_FPS,\n\tINITIAL_BUFFER_MS,\n\tMAX_SMOOTH_FPS,\n\tMIN_SMOOTH_FPS,\n\tnextStep,\n\tupdateArrivalRate,\n} from \"./streaming-reveal-pacing.ts\";\n\nexport * from \"./streaming-reveal-content.ts\";\nexport * from \"./streaming-reveal-pacing.ts\";\n\ntype StreamingRevealComponent = Pick<AssistantMessageComponent, \"updateContent\">;\n\nexport type StreamingRevealControllerOptions = {\n\treadonly getSmoothStreaming: () => boolean;\n\treadonly getSmoothStreamingFps: () => number;\n\treadonly getHideThinkingBlock: () => boolean;\n\treadonly requestRender: () => void;\n};\n\nexport class StreamingRevealController {\n\treadonly #getSmoothStreaming: () => boolean;\n\treadonly #getSmoothStreamingFps: () => number;\n\treadonly #getHideThinkingBlock: () => boolean;\n\treadonly #requestRender: () => void;\n\treadonly #unitCounter = new BlockUnitCounter();\n\treadonly #countOf = (index: number, text: string): number => this.#unitCounter.count(index, text);\n\treadonly #sliceOf = (index: number, text: string, units: number): string =>\n\t\tthis.#unitCounter.slice(index, text, units);\n\t#target: AssistantMessage | undefined;\n\t#component: StreamingRevealComponent | undefined;\n\t#timer: NodeJS.Timeout | undefined;\n\t#timerFps: number | undefined;\n\t#revealed = 0;\n\t#lastTickAt = 0;\n\t#firstBufferedAt: number | undefined;\n\t#lastTargetAt: number | undefined;\n\t#arrivalRate = 90;\n\t#stepCarry = 0;\n\t#hideThinkingBlock = false;\n\n\tconstructor(options: StreamingRevealControllerOptions) {\n\t\tthis.#getSmoothStreaming = options.getSmoothStreaming;\n\t\tthis.#getSmoothStreamingFps = options.getSmoothStreamingFps;\n\t\tthis.#getHideThinkingBlock = options.getHideThinkingBlock;\n\t\tthis.#requestRender = options.requestRender;\n\t}\n\n\tbegin(component: StreamingRevealComponent, message: AssistantMessage): void {\n\t\tthis.stop();\n\t\tthis.#component = component;\n\t\tthis.#target = message;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tif (this.#visibleUnits(message) > 0) {\n\t\t\tconst now = performance.now();\n\t\t\tthis.#firstBufferedAt = now;\n\t\t\tthis.#lastTargetAt = now;\n\t\t}\n\t\tthis.#applyTarget();\n\t}\n\n\tsetTarget(message: AssistantMessage): void {\n\t\tconst now = performance.now();\n\t\tconst previousUnits = this.#target ? this.#visibleUnits(this.#target) : 0;\n\t\tthis.#target = message;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tconst total = this.#visibleUnits(message);\n\t\tconst appended = Math.max(0, total - previousUnits);\n\t\tif (appended > 0) {\n\t\t\tif (this.#firstBufferedAt === undefined) this.#firstBufferedAt = now;\n\t\t\tif (this.#lastTargetAt !== undefined && now > this.#lastTargetAt) {\n\t\t\t\tthis.#arrivalRate = updateArrivalRate(this.#arrivalRate, appended, now - this.#lastTargetAt);\n\t\t\t}\n\t\t\tthis.#lastTargetAt = now;\n\t\t}\n\t\tif (this.#component) this.#applyTarget();\n\t}\n\n\tresyncVisibility(): void {\n\t\tif (!this.#target || !this.#component) return;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tthis.#revealed = Math.min(this.#revealed, this.#visibleUnits(this.#target));\n\t\tthis.#applyTarget();\n\t}\n\n\tstop(): void {\n\t\tthis.#stopTimer();\n\t\tthis.#target = undefined;\n\t\tthis.#component = undefined;\n\t\tthis.#revealed = 0;\n\t\tthis.#lastTickAt = 0;\n\t\tthis.#unitCounter.reset();\n\t\tthis.#firstBufferedAt = undefined;\n\t\tthis.#lastTargetAt = undefined;\n\t\tthis.#arrivalRate = 90;\n\t\tthis.#stepCarry = 0;\n\t}\n\n\t#applyTarget(): void {\n\t\tconst target = this.#target;\n\t\tconst component = this.#component;\n\t\tif (!target || !component) return;\n\t\tconst total = this.#visibleUnits(target);\n\t\tif (!this.#getSmoothStreaming() || target.content.some((block) => block.type === \"toolCall\")) {\n\t\t\tthis.#revealed = total;\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\tcomponent.updateContent(target);\n\t\t\treturn;\n\t\t}\n\t\tthis.#revealed = Math.min(this.#revealed, total);\n\t\tthis.#renderCurrent();\n\t\tthis.#syncTimer(total);\n\t}\n\n\t#visibleUnits(message: AssistantMessage): number {\n\t\treturn countVisibleUnits(message, this.#hideThinkingBlock, this.#countOf);\n\t}\n\n\t#renderCurrent(): void {\n\t\tif (!this.#target || !this.#component) return;\n\t\tthis.#component.updateContent(\n\t\t\tbuildDisplayMessage(this.#target, this.#revealed, this.#hideThinkingBlock, this.#countOf, this.#sliceOf),\n\t\t);\n\t}\n\n\t#syncTimer(total: number): void {\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\treturn;\n\t\t}\n\t\tthis.#startTimer();\n\t}\n\n\t#startTimer(): void {\n\t\tconst configuredFps = this.#getSmoothStreamingFps();\n\t\tconst fps = Number.isFinite(configuredFps)\n\t\t\t? Math.min(MAX_SMOOTH_FPS, Math.max(MIN_SMOOTH_FPS, configuredFps))\n\t\t\t: DEFAULT_SMOOTH_FPS;\n\t\tif (this.#timer && this.#timerFps === fps) return;\n\t\tthis.#stopTimer();\n\t\tthis.#lastTickAt = performance.now();\n\t\tconst timer = setInterval(() => this.#tick(), 1000 / fps);\n\t\ttimer.unref();\n\t\tthis.#timer = timer;\n\t\tthis.#timerFps = fps;\n\t}\n\n\t#stopTimer(): void {\n\t\tif (this.#timer) clearInterval(this.#timer);\n\t\tthis.#timer = undefined;\n\t\tthis.#timerFps = undefined;\n\t}\n\n\t#tick(): void {\n\t\tconst target = this.#target;\n\t\tif (!target || !this.#component) {\n\t\t\tthis.stop();\n\t\t\treturn;\n\t\t}\n\t\tconst total = this.#visibleUnits(target);\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\treturn;\n\t\t}\n\t\tconst now = performance.now();\n\t\tconst dt = now - this.#lastTickAt;\n\t\tthis.#lastTickAt = now;\n\t\tif (this.#firstBufferedAt !== undefined && now - this.#firstBufferedAt < INITIAL_BUFFER_MS) return;\n\t\tthis.#stepCarry += nextStep(total - this.#revealed, dt, this.#arrivalRate);\n\t\tconst wholeStep = Math.floor(this.#stepCarry);\n\t\tif (wholeStep <= 0) return;\n\t\tthis.#stepCarry -= wholeStep;\n\t\tthis.#revealed = Math.min(total, this.#revealed + wholeStep);\n\t\tthis.#renderCurrent();\n\t\tthis.#requestRender();\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"streaming-reveal.js","sourceRoot":"","sources":["../../../src/modes/interactive/streaming-reveal.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { AssistantMessageComponent } from \"./components/assistant-message.ts\";\nimport { BlockUnitCounter, buildDisplayMessage, countVisibleUnits } from \"./streaming-reveal-content.ts\";\nimport {\n\tDEFAULT_SMOOTH_FPS,\n\tINITIAL_BUFFER_MS,\n\tMAX_SMOOTH_FPS,\n\tMIN_SMOOTH_FPS,\n\tnextStep,\n\tupdateArrivalRate,\n} from \"./streaming-reveal-pacing.ts\";\n\nexport * from \"./streaming-reveal-content.ts\";\nexport * from \"./streaming-reveal-pacing.ts\";\n\ntype StreamingRevealComponent = Pick<AssistantMessageComponent, \"updateContent\">;\n\nexport type StreamingRevealControllerOptions = {\n\treadonly getSmoothStreaming: () => boolean;\n\treadonly getSmoothStreamingFps: () => number;\n\treadonly getHideThinkingBlock: () => boolean;\n\treadonly requestRender: () => void;\n};\n\nexport class StreamingRevealController {\n\treadonly #getSmoothStreaming: () => boolean;\n\treadonly #getSmoothStreamingFps: () => number;\n\treadonly #getHideThinkingBlock: () => boolean;\n\treadonly #requestRender: () => void;\n\treadonly #unitCounter = new BlockUnitCounter();\n\treadonly #countOf = (index: number, text: string): number => this.#unitCounter.count(index, text);\n\treadonly #sliceOf = (index: number, text: string, units: number): string =>\n\t\tthis.#unitCounter.slice(index, text, units);\n\t#target: AssistantMessage | undefined;\n\t#component: StreamingRevealComponent | undefined;\n\t#timer: NodeJS.Timeout | undefined;\n\t#timerFps: number | undefined;\n\t#revealed = 0;\n\t#lastTickAt = 0;\n\t#firstBufferedAt: number | undefined;\n\t#lastTargetAt: number | undefined;\n\t#arrivalRate = 90;\n\t#stepCarry = 0;\n\t#hideThinkingBlock = false;\n\n\tconstructor(options: StreamingRevealControllerOptions) {\n\t\tthis.#getSmoothStreaming = options.getSmoothStreaming;\n\t\tthis.#getSmoothStreamingFps = options.getSmoothStreamingFps;\n\t\tthis.#getHideThinkingBlock = options.getHideThinkingBlock;\n\t\tthis.#requestRender = options.requestRender;\n\t}\n\n\tbegin(component: StreamingRevealComponent, message: AssistantMessage): void {\n\t\tthis.stop();\n\t\tthis.#component = component;\n\t\tthis.#target = message;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tif (this.#visibleUnits(message) > 0) {\n\t\t\tconst now = performance.now();\n\t\t\tthis.#firstBufferedAt = now;\n\t\t\tthis.#lastTargetAt = now;\n\t\t}\n\t\tthis.#applyTarget();\n\t}\n\n\tsetTarget(message: AssistantMessage): void {\n\t\tconst now = performance.now();\n\t\tconst previousUnits = this.#target ? this.#visibleUnits(this.#target) : 0;\n\t\tthis.#target = message;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tconst total = this.#visibleUnits(message);\n\t\tconst appended = Math.max(0, total - previousUnits);\n\t\tif (appended > 0) {\n\t\t\tif (this.#firstBufferedAt === undefined) this.#firstBufferedAt = now;\n\t\t\tif (this.#lastTargetAt !== undefined && now > this.#lastTargetAt) {\n\t\t\t\tthis.#arrivalRate = updateArrivalRate(this.#arrivalRate, appended, now - this.#lastTargetAt);\n\t\t\t}\n\t\t\tthis.#lastTargetAt = now;\n\t\t}\n\t\tif (this.#component) this.#applyTarget();\n\t}\n\n\tresyncVisibility(): void {\n\t\tif (!this.#target || !this.#component) return;\n\t\tthis.#hideThinkingBlock = this.#getHideThinkingBlock();\n\t\tthis.#revealed = Math.min(this.#revealed, this.#visibleUnits(this.#target));\n\t\tthis.#applyTarget();\n\t}\n\n\t/**\n\t * True while this controller is the pacing writer for the given head message:\n\t * smooth streaming is on, the head carries no toolCall block (those dump in\n\t * full), and a component is still bound (before stop()). While true, callers\n\t * must not overwrite the component's content, or the next reveal tick\n\t * repaints a shorter prefix after their full write (dual-write flicker).\n\t */\n\tisPacingHead(message: AssistantMessage): boolean {\n\t\tif (!this.#target || !this.#component) return false;\n\t\treturn this.#getSmoothStreaming() && !message.content.some((block) => block.type === \"toolCall\");\n\t}\n\n\tstop(): void {\n\t\tthis.#stopTimer();\n\t\tthis.#target = undefined;\n\t\tthis.#component = undefined;\n\t\tthis.#revealed = 0;\n\t\tthis.#lastTickAt = 0;\n\t\tthis.#unitCounter.reset();\n\t\tthis.#firstBufferedAt = undefined;\n\t\tthis.#lastTargetAt = undefined;\n\t\tthis.#arrivalRate = 90;\n\t\tthis.#stepCarry = 0;\n\t}\n\n\t#applyTarget(): void {\n\t\tconst target = this.#target;\n\t\tconst component = this.#component;\n\t\tif (!target || !component) return;\n\t\tconst total = this.#visibleUnits(target);\n\t\tif (!this.#getSmoothStreaming() || target.content.some((block) => block.type === \"toolCall\")) {\n\t\t\tthis.#revealed = total;\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\tcomponent.updateContent(target);\n\t\t\treturn;\n\t\t}\n\t\tthis.#revealed = Math.min(this.#revealed, total);\n\t\tthis.#renderCurrent();\n\t\tthis.#syncTimer(total);\n\t}\n\n\t#visibleUnits(message: AssistantMessage): number {\n\t\treturn countVisibleUnits(message, this.#hideThinkingBlock, this.#countOf);\n\t}\n\n\t#renderCurrent(): void {\n\t\tif (!this.#target || !this.#component) return;\n\t\tthis.#component.updateContent(\n\t\t\tbuildDisplayMessage(this.#target, this.#revealed, this.#hideThinkingBlock, this.#countOf, this.#sliceOf),\n\t\t);\n\t}\n\n\t#syncTimer(total: number): void {\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\treturn;\n\t\t}\n\t\tthis.#startTimer();\n\t}\n\n\t#startTimer(): void {\n\t\tconst configuredFps = this.#getSmoothStreamingFps();\n\t\tconst fps = Number.isFinite(configuredFps)\n\t\t\t? Math.min(MAX_SMOOTH_FPS, Math.max(MIN_SMOOTH_FPS, configuredFps))\n\t\t\t: DEFAULT_SMOOTH_FPS;\n\t\tif (this.#timer && this.#timerFps === fps) return;\n\t\tthis.#stopTimer();\n\t\tthis.#lastTickAt = performance.now();\n\t\tconst timer = setInterval(() => this.#tick(), 1000 / fps);\n\t\ttimer.unref();\n\t\tthis.#timer = timer;\n\t\tthis.#timerFps = fps;\n\t}\n\n\t#stopTimer(): void {\n\t\tif (this.#timer) clearInterval(this.#timer);\n\t\tthis.#timer = undefined;\n\t\tthis.#timerFps = undefined;\n\t}\n\n\t#tick(): void {\n\t\tconst target = this.#target;\n\t\tif (!target || !this.#component) {\n\t\t\tthis.stop();\n\t\t\treturn;\n\t\t}\n\t\tconst total = this.#visibleUnits(target);\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t\treturn;\n\t\t}\n\t\tconst now = performance.now();\n\t\tconst dt = now - this.#lastTickAt;\n\t\tthis.#lastTickAt = now;\n\t\tif (this.#firstBufferedAt !== undefined && now - this.#firstBufferedAt < INITIAL_BUFFER_MS) return;\n\t\tthis.#stepCarry += nextStep(total - this.#revealed, dt, this.#arrivalRate);\n\t\tconst wholeStep = Math.floor(this.#stepCarry);\n\t\tif (wholeStep <= 0) return;\n\t\tthis.#stepCarry -= wholeStep;\n\t\tthis.#revealed = Math.min(total, this.#revealed + wholeStep);\n\t\tthis.#renderCurrent();\n\t\tthis.#requestRender();\n\t\tif (this.#revealed >= total) {\n\t\t\tthis.#stepCarry = 0;\n\t\t\tthis.#stopTimer();\n\t\t}\n\t}\n}\n"]}

package/docs/AGENTS.md

@@ -6,7 +6,7 @@ Public documentation for `@code-yeongyu/senpi`. Shipped inside the npm package:
 ## Navigation manifest
 
 `docs.json` has two top-level keys: `navigation` (ordered section and page list) and `redirects`.
-Page paths are relative to this directory.
+Sections are `{ "title", "items": [{ "title", "path" }] }`; page paths are relative to this directory.
 
 - Every new `.md` file needs an entry in `docs.json` under `navigation`.
 - Renamed or moved pages need a `redirects` entry to avoid broken links.
@@ -29,6 +29,8 @@ These pages must track their implementation counterparts. Treat them as specs, n
 | `app-server.md` | `packages/coding-agent/src/modes/app-server/` |
 | `json.md` | JSONL wire format and record shapes |
 | `session-format.md` | Session file structure and field types |
+| `extensions.md` | Public extension API in `src/core/extensions/`; largest page — API tables must match `types.ts` |
+| `release-guide.md` | Release tooling; canonical check/build/test/lock command sequences |
 
 Preserve LF line endings and exact field names in these pages. Field spellings and JSONL record
 structures are asserted by tests; prose-only rewording can still break them.

package/examples/AGENTS.md

@@ -5,16 +5,28 @@ Runnable examples for the public Senpi SDK and extension API. Examples are docum
 ## STRUCTURE
 
 ```text
-extensions/        Tools, commands, UI, providers, hooks, resources
-extensions/*/      Multi-file examples and nested private workspaces
-sdk/               Programmatic SDK usage
-rpc-extension-ui.ts RPC-compatible extension UI example
-extensions/kimi-deferred-tools.ts  Deferred tool discovery/activation example
+extensions/          Single-file extension catalog (70+ files) + multi-file dirs
+extensions/*/        Multi-file examples; several are private nested workspaces
+sdk/                 Numbered SDK programs (01-minimal.ts ... 13-session-runtime.ts)
+rpc-extension-ui.ts  RPC-mode extension UI as standalone JSONL child process
 ```
 
+## WHERE TO LOOK
+
+| Task | First choice |
+|---|---|
+| Tool/flag/command/shortcut registration | `extensions/tools.ts`, `commands.ts`, `dynamic-tools.ts` |
+| Custom provider, OAuth, streaming | `extensions/custom-provider-anthropic/` |
+| UI widgets, overlays, editors | `extensions/overlay-*.ts`, `modal-editor.ts`, `widget-placement.ts` |
+| Session-entry persistence | `extensions/todo.ts`, `bookmark.ts`, `handoff.ts` |
+| Safety guards | `extensions/permission-gate.ts`, `protected-paths.ts`, `sandbox/` |
+| Full SDK composition | `sdk/12-full-control.ts`, `sdk/13-session-runtime.ts` |
+
+Largest examples carry real complexity, not toy scope: `extensions/overlay-qa-tests.ts` (~1.5k LOC), `extensions/subagent/index.ts` (~1k), `extensions/tic-tac-toe.ts` (~1k), `extensions/custom-provider-anthropic/index.ts` (~600). See `extensions/AGENTS.md` for the catalog map.
+
 ## CONVENTIONS
 
-- Import public package surfaces such as `@code-yeongyu/senpi` and `@earendil-works/pi-ai`; do not reach into `packages/coding-agent/src/core/` internals.
+- Import public package surfaces — `@code-yeongyu/senpi` (newer alias), `@earendil-works/pi-coding-agent` (lower level), `@earendil-works/pi-ai`/`pi-tui` — never `packages/coding-agent/src/core/` internals.
 - Keep examples small enough to teach one pattern, while preserving real error, cleanup, cancellation, and persistence behavior where relevant.
 - Extension factories have no top-level runtime side effects. Register work through the public `pi.*` API and lifecycle events.
 - New interactive examples should use configurable keybindings and themed TUI helpers. Existing demos may keep fixed controls when the control scheme is part of the example. Direct terminal writes belong only in examples explicitly teaching a terminal protocol; ordinary SDK examples may use normal stdout.
@@ -23,6 +35,9 @@ extensions/kimi-deferred-tools.ts  Deferred tool discovery/activation example
 - Deferred-tool examples preserve the Kimi flow: expose search first, activate via `pi.setActiveTools()`, and register lifecycle work in `session_start`.
 - Stateful examples persist reconstructable state in session entries or tool-result details so fork/resume behavior remains valid.
 - Nested example packages are private workspaces with exact-pinned dependencies. Treat their manifests and lock impact as production dependency changes.
+- Kebab-case filenames and slash-command names; camelCase named exports; one example per file default-exporting its extension factory.
+- UI examples guard on `ctx.hasUI` and clean up timers/child processes on `session_shutdown`; stateful atomic tools (games, questionnaires) set `executionMode: "sequential"`.
+- Tool schemas use TypeBox; handlers follow the `(toolCallId, params, signal, onUpdate, ctx)` shape.
 
 ## DOCUMENTATION CONTRACT
 

package/examples/extensions/AGENTS.md

@@ -0,0 +1,50 @@
+# packages/coding-agent/examples/extensions
+
+Flat catalog of executable extension examples plus multi-file extension packages. Own file because it is the densest `pi.*` registration surface in the repo (score 14: 110+ files, 10 subdirs, heavy symbol/export density). Load any single file with `senpi -e <path>.ts`; per-example docs live in `README.md`.
+
+## STRUCTURE
+
+```text
+*.ts                        Single-file examples, one pattern each (kebab-case)
+subagent/                   Subagent tool: single/parallel/chain dispatch (~1k LOC)
+custom-provider-anthropic/  OAuth + Anthropic-compatible streaming provider
+custom-provider-gitlab-duo/ Provider against GitLab Duo
+gondolin/                   Route built-in tools + `!` commands into a Gondolin micro-VM
+sandbox/                    OS-level sandboxing via @anthropic-ai/sandbox-runtime
+plan-mode/                  Read-only planning mode (generated instructions)
+openai-codex-usage/         Codex usage tracking
+dynamic-resources/          Dynamic resource examples
+with-deps/                  Extension with its own private dependency manifest
+doom-overlay/               WASM Doom rendered as live overlay; doom/build/ is generated
+```
+
+## WHERE TO LOOK
+
+| Task | First choice |
+|---|---|
+| Register tool/command/flag/shortcut/renderer | `tools.ts`, `commands.ts`, `dynamic-tools.ts`, `custom-header.ts` |
+| Built-in tool override or rendering | `minimal-mode.ts`, `built-in-tool-renderer.ts` |
+| Overlays, focus, geometry | `overlay-test.ts`, `overlay-qa-tests.ts`, `widget-placement.ts` |
+| Provider auth/payload | `custom-provider-anthropic/`, `provider-payload.ts` |
+| Persistent state via session entries | `todo.ts`, `tic-tac-toe.ts`, `bookmark.ts`, `handoff.ts` |
+| Prompt/preset/config files | `preset.ts`, `prompt-customizer.ts`, `system-prompt-header.ts` |
+| Games / keyboard input | `snake.ts`, `space-invaders.ts`, `tic-tac-toe.ts` |
+| Deferred-tool activation (Kimi flow) | `kimi-deferred-tools.ts` |
+| RPC/UI child process | `../rpc-extension-ui.ts`, `rpc-demo.ts` |
+
+## CONVENTIONS
+
+- Event seams used across examples: `session_start`/`session_shutdown`, `turn_*`, `agent_*`, `before_agent_start`, `tool_call`/`tool_result`, `input`, `user_bash`, `model_select`.
+- Presets read `~/.senpi/agent/presets.json` then `<cwd>/.senpi/presets.json`; project file wins. `provider-payload.ts` writes under `CONFIG_DIR_NAME`.
+- `overlay-qa-tests.ts` is a runtime QA extension (many overlay commands, timers, spawned streaming processes), not a conventional test target.
+
+## ANTI-PATTERNS
+
+- Custom tools MUST truncate output (`truncated-tool.ts` demonstrates ripgrep wrapping with 50KB/2000-line caps).
+- Games never expose the user's cursor and never split a tool-call sequence across responses.
+- Never leave timers or child processes alive past `session_shutdown`.
+- Shell/process-delegating examples (`ssh.ts`, `interactive-shell.ts`, `inline-bash.ts`, `auto-commit-on-exit.ts`, `git-merge-and-resolve.ts`) cross trust boundaries; adopt deliberately, never as boilerplate.
+
+---
+
+Parent: `examples/AGENTS.md` (import rules, factory discipline, validation).