@code-yeongyu/senpi 2026.7.14 → 2026.7.16-2

package/examples/AGENTS.md

@@ -0,0 +1,34 @@
+# packages/coding-agent/examples
+
+Runnable examples for the public Senpi SDK and extension API. Examples are documentation-quality code and must reflect shipped APIs, not private core internals. Unqualified paths below are relative to this directory; `packages/...` paths are repository-relative.
+
+## 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
+```
+
+## 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.
+- 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.
+- Tool string enums use the shared `StringEnum` helper for provider compatibility.
+- 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.
+
+## DOCUMENTATION CONTRACT
+
+- Keep `extensions/README.md`, `packages/coding-agent/docs/extensions.md`, and `packages/coding-agent/docs/sdk.md` aligned with public API changes.
+- New public extension capabilities should include a focused example when usage is not obvious from types alone.
+- Do not present experimental or internal behavior as stable API.
+
+## VALIDATION
+
+- Run the focused tests for the public API demonstrated by the example.
+- Typecheck examples through root `npm run check`.
+- Interactive examples require real CLI or visual QA when their behavior changes.

package/examples/extensions/README.md

@@ -36,6 +36,7 @@ cp permission-gate.ts ~/.senpi/agent/extensions/
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
 | `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
+| `kimi-deferred-tools.ts` | Search for and progressively activate tools for Kimi's deferred-tool loading protocol |
 | `structured-output.ts` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -46,7 +46,7 @@ import {
 } from "@earendil-works/pi-ai";
 
 // =============================================================================
-// OAuth Implementation (copied from packages/ai/src/utils/oauth/anthropic.ts)
+// OAuth implementation adapted for the legacy extension compatibility interface.
 // =============================================================================
 
 const decode = (s: string) => atob(s);

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.80.6",
+  "version": "0.80.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.80.6",
+      "version": "0.80.9",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.80.6",
+  "version": "0.80.9",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.80.6",
+  "version": "0.80.9",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.80.6",
+	"version": "0.80.9",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.80.6",
+			"version": "0.80.9",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.80.6",
+	"version": "0.80.9",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/kimi-deferred-tools.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal Kimi deferred-tool loading demo.
+ *
+ *   pi -e ./kimi-deferred-tools.ts
+ *    example prompt: Use the available tools to calculate 100 + 500. Do not calculate it yourself.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+function calculate(_expr: string): string {
+	return "42";
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "Calculator",
+		label: "Calculator",
+		description: "Evaluate a simple arithmetic expression.",
+		parameters: Type.Object({
+			expr: Type.String({ description: "An expression such as 100 + 500" }),
+		}),
+		async execute(_toolCallId, params) {
+			return {
+				content: [{ type: "text", text: calculate(params.expr) }],
+				details: {},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "tool_search",
+		label: "Tool Search",
+		description: "Find and activate tools for a capability.",
+		promptSnippet: "Search for additional tools when the active tools cannot perform the task",
+		parameters: Type.Object({
+			query: Type.String({ description: "Capability to search for" }),
+		}),
+		async execute(_toolCallId, params) {
+			if (!params.query.toLowerCase().includes("calc")) {
+				return {
+					content: [{ type: "text", text: "The relevant tools do not exist." }],
+					details: { matches: [], added: [] },
+				};
+			}
+
+			const active = pi.getActiveTools();
+			const added = active.includes("Calculator") ? [] : ["Calculator"];
+			if (added.length > 0) pi.setActiveTools([...active, ...added]);
+
+			return {
+				content: [{ type: "text", text: "Success. Found 1 matching tool(s)" }],
+				details: { matches: ["Calculator"], added },
+			};
+		},
+	});
+
+	pi.on("session_start", () => {
+		pi.setActiveTools(["tool_search"]);
+	});
+}

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.10.6",
+	"version": "1.10.9",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.10.6",
+			"version": "1.10.9",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.10.6",
+	"version": "1.10.9",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.80.6",
+  "version": "0.80.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.80.6",
+      "version": "0.80.9",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.80.6",
+  "version": "0.80.9",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/sdk/02-custom-model.ts

@@ -5,11 +5,9 @@
  */
 
 import { getModel } from "@earendil-works/pi-ai/compat";
-import { AuthStorage, createAgentSession, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, ModelRuntime } from "@earendil-works/pi-coding-agent";
 
-// Set up auth storage and model registry
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
 // Option 1: Find a specific built-in model by provider/id
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -18,13 +16,13 @@ if (opus) {
 }
 
 // Option 2: Find model via registry (includes custom models from models.json)
-const customModel = modelRegistry.find("my-provider", "my-model");
+const customModel = modelRuntime.getModel("my-provider", "my-model");
 if (customModel) {
 	console.log(`Found custom model: ${customModel.provider}/${customModel.id}`);
 }
 
 // Option 3: Pick from available models (have valid API keys)
-const available = await modelRegistry.getAvailable();
+const available = await modelRuntime.getAvailable();
 console.log(
 	"Available models:",
 	available.map((m) => `${m.provider}/${m.id}`),
@@ -34,8 +32,7 @@ if (available.length > 0) {
 	const { session } = await createAgentSession({
 		model: available[0],
 		thinkingLevel: "medium", // off, low, medium, high
-		authStorage,
-		modelRegistry,
+		modelRuntime,
 	});
 
 	try {

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -1,52 +1,34 @@
 /**
  * API Keys and OAuth
  *
- * Configure API key resolution via AuthStorage and ModelRegistry.
+ * Configure provider auth through ModelRuntime.
  */
 
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@code-yeongyu/senpi";
-
-// Default: AuthStorage uses ~/.senpi/agent/auth.json
-// ModelRegistry loads built-in + custom models from ~/.senpi/agent/models.json
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 
+const modelRuntime = await ModelRuntime.create();
 const { session: defaultAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 });
-console.log("Session with default auth storage and model registry");
+console.log("Session with default model runtime");
 defaultAuthSession.dispose();
 
-// Custom auth storage location
-const customAuthStorage = AuthStorage.create("/tmp/my-app/auth.json");
-const customModelRegistry = ModelRegistry.create(customAuthStorage, "/tmp/my-app/models.json");
-
+const customRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-app/auth.json",
+	modelsPath: "/tmp/my-app/models.json",
+});
 const { session: customAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage: customAuthStorage,
-	modelRegistry: customModelRegistry,
+	modelRuntime: customRuntime,
 });
-console.log("Session with custom auth storage location");
+console.log("Session with custom auth and models locations");
 customAuthSession.dispose();
 
-// Runtime API key override (not persisted to disk)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
 const { session: runtimeKeySession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 });
 console.log("Session with runtime API key override");
 runtimeKeySession.dispose();
-
-// No models.json - only built-in models
-const simpleRegistry = ModelRegistry.inMemory(authStorage);
-const { session: builtInModelsSession } = await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry: simpleRegistry,
-});
-console.log("Session with only built-in models");
-builtInModelsSession.dispose();

package/examples/sdk/12-full-control.ts

@@ -6,27 +6,23 @@
 
 import { getModel } from "@earendil-works/pi-ai/compat";
 import {
-	AuthStorage,
 	createAgentSession,
 	createExtensionRuntime,
-	ModelRegistry,
+	ModelRuntime,
 	type ResourceLoader,
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
-// Custom auth storage location
-const authStorage = AuthStorage.create("/tmp/my-agent/auth.json");
-
-// Runtime API key override (not persisted)
+const modelRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-agent/auth.json",
+	modelsPath: "/tmp/my-agent/models.json",
+});
 if (process.env.MY_ANTHROPIC_KEY) {
-	authStorage.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+	modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
 }
 
-// Model registry with no custom models.json
-const modelRegistry = ModelRegistry.inMemory(authStorage);
-
-const model = getModel("anthropic", "claude-opus-4-5");
+const model = getModel("anthropic", "claude-sonnet-4-5");
 if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides
@@ -55,8 +51,7 @@ const { session } = await createAgentSession({
 	agentDir: "/tmp/my-agent",
 	model,
 	thinkingLevel: "off",
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 	resourceLoader,
 	tools: ["read", "bash"],
 	sessionManager: SessionManager.inMemory(cwd),

package/examples/sdk/README.md

@@ -34,46 +34,44 @@ npx tsx examples/sdk/01-minimal.ts
 ```typescript
 import { getModel } from "@earendil-works/pi-ai";
 import {
-  AuthStorage,
   createAgentSession,
   DefaultResourceLoader,
-  ModelRegistry,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
 } from "@code-yeongyu/senpi";
 
-// Auth and models setup
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
 // Minimal
-const { session } = await createAgentSession({ authStorage, modelRegistry });
+const { session } = await createAgentSession({ modelRuntime });
 
 // Custom model
 const model = getModel("anthropic", "claude-opus-4-5");
-const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
 
 // Modify prompt
 const loader = new DefaultResourceLoader({
   systemPromptOverride: (base) => `${base}\n\nBe concise.`,
 });
 await loader.reload();
-const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
 
 // Read-only
-const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], authStorage, modelRegistry });
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
 
 // In-memory
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 });
 
 // Full control
-const customAuth = AuthStorage.create("/my/app/auth.json");
-customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
-const customRegistry = ModelRegistry.create(customAuth);
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
 
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
@@ -86,8 +84,7 @@ await resourceLoader.reload();
 
 const { session } = await createAgentSession({
   model,
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
+  modelRuntime: customRuntime,
   resourceLoader,
   tools: ["read", "bash", "my_tool"],
   customTools: [myTool],
@@ -108,8 +105,7 @@ await session.prompt("Hello");
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `authStorage` | `AuthStorage.create()` | Credential storage |
-| `modelRegistry` | `ModelRegistry.create(authStorage)` | Model registry |
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
 | `cwd` | `process.cwd()` | Working directory |
 | `agentDir` | `~/.senpi/agent` | Config directory |
 | `model` | From settings/first available | Model to use |

package/node_modules/@code-yeongyu/senpi-codemode/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2026.7.16-2] - 2026-07-16
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [2026.7.16] - 2026-07-16
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [2026.7.14-3] - 2026-07-14
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [2026.7.14-2] - 2026-07-14
+
+### Added
+
+### Changed
+
+### Fixed
+
 ## [2026.7.14] - 2026-07-14
 
 ### Added

package/node_modules/@code-yeongyu/senpi-codemode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.7.14",
+	"version": "2026.7.16-2",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -30,14 +30,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "7.29.7",
-		"@earendil-works/pi-ai": "^2026.7.14",
+		"@earendil-works/pi-ai": "^2026.7.16-2",
 		"typebox": "1.1.38"
 	},
 	"peerDependencies": {
 		"@code-yeongyu/senpi": "*"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.7.14"
+		"@code-yeongyu/senpi": "2026.7.16-2"
 	},
 	"keywords": [
 		"senpi",

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/local-module-loader.ts

@@ -47,8 +47,8 @@ function runtimeContext(options: LocalModuleLoaderOptions): RuntimeModuleContext
 	for (const [scheme, root] of Object.entries(options.localRoots ?? {})) {
 		roots[scheme.toLowerCase()] = directoryUrl(root);
 	}
-	if (options.artifactsDir && roots["local"] === undefined) {
-		roots["local"] = directoryUrl(join(options.artifactsDir, "local"));
+	if (options.artifactsDir && roots.local === undefined) {
+		roots.local = directoryUrl(join(options.artifactsDir, "local"));
 	}
 	return {
 		cwdUrl: directoryUrl(options.cwd),

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/rewrite-imports.ts

@@ -31,9 +31,9 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
 
 function nodeFrom(value: unknown): AstNode | undefined {
 	if (!isRecord(value)) return undefined;
-	const type = value["type"];
-	const start = value["start"];
-	const end = value["end"];
+	const type = value.type;
+	const start = value.start;
+	const end = value.end;
 	if (typeof type !== "string" || typeof start !== "number" || typeof end !== "number") return undefined;
 	return { type, start, end, value };
 }
@@ -131,7 +131,7 @@ function rewriteImportDeclaration(node: ImportDeclaration): string {
 
 function dynamicImportEdit(node: AstNode): TextEdit | undefined {
 	if (node.type !== "CallExpression") return undefined;
-	const callee = nodeFrom(node.value["callee"]);
+	const callee = nodeFrom(node.value.callee);
 	if (callee?.type !== "Import") return undefined;
 	return { start: callee.start, end: callee.end, text: DYNAMIC_IMPORT_CALLEE };
 }