@vaclav-synacek/pi-coding-agent-termux 0.45.7

package/examples/sdk/04-skills.ts

@@ -0,0 +1,47 @@
+/**
+ * Skills Configuration
+ *
+ * Skills provide specialized instructions loaded into the system prompt.
+ * Discover, filter, merge, or replace them.
+ */
+
+import { createAgentSession, discoverSkills, SessionManager, type Skill } from "@mariozechner/pi-coding-agent";
+
+// Discover all skills from cwd/.pi/skills, ~/.pi/agent/skills, etc.
+const { skills: allSkills, warnings } = discoverSkills();
+console.log(
+	"Discovered skills:",
+	allSkills.map((s) => s.name),
+);
+if (warnings.length > 0) {
+	console.log("Warnings:", warnings);
+}
+
+// Filter to specific skills
+const filteredSkills = allSkills.filter((s) => s.name.includes("browser") || s.name.includes("search"));
+
+// Or define custom skills inline
+const customSkill: Skill = {
+	name: "my-skill",
+	description: "Custom project instructions",
+	filePath: "/virtual/SKILL.md",
+	baseDir: "/virtual",
+	source: "custom",
+};
+
+// Use filtered + custom skills
+await createAgentSession({
+	skills: [...filteredSkills, customSkill],
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log(`Session created with ${filteredSkills.length + 1} skills`);
+
+// To disable all skills:
+// skills: []
+
+// To use discovery with filtering via settings:
+// discoverSkills(process.cwd(), undefined, {
+//   ignoredSkills: ["browser-tools"],  // glob patterns to exclude
+//   includeSkills: ["brave-*"],        // glob patterns to include (empty = all)
+// })

package/examples/sdk/05-tools.ts

@@ -0,0 +1,56 @@
+/**
+ * Tools Configuration
+ *
+ * Use built-in tool sets or individual tools.
+ *
+ * IMPORTANT: When using a custom `cwd`, you must use the tool factory functions
+ * (createCodingTools, createReadOnlyTools, createReadTool, etc.) to ensure
+ * tools resolve paths relative to your cwd, not process.cwd().
+ *
+ * For custom tools, see 06-extensions.ts - custom tools are now registered
+ * via the extensions system using pi.registerTool().
+ */
+
+import {
+	bashTool,
+	createAgentSession,
+	createBashTool,
+	createCodingTools,
+	createGrepTool,
+	createReadTool,
+	grepTool,
+	readOnlyTools,
+	readTool,
+	SessionManager,
+} from "@mariozechner/pi-coding-agent";
+
+// Read-only mode (no edit/write) - uses process.cwd()
+await createAgentSession({
+	tools: readOnlyTools,
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Read-only session created");
+
+// Custom tool selection - uses process.cwd()
+await createAgentSession({
+	tools: [readTool, bashTool, grepTool],
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Custom tools session created");
+
+// With custom cwd - MUST use factory functions!
+const customCwd = "/path/to/project";
+await createAgentSession({
+	cwd: customCwd,
+	tools: createCodingTools(customCwd), // Tools resolve paths relative to customCwd
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Custom cwd session created");
+
+// Or pick specific tools for custom cwd
+await createAgentSession({
+	cwd: customCwd,
+	tools: [createReadTool(customCwd), createBashTool(customCwd), createGrepTool(customCwd)],
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("Specific tools with custom cwd session created");

package/examples/sdk/06-extensions.ts

@@ -0,0 +1,79 @@
+/**
+ * Extensions Configuration
+ *
+ * Extensions intercept agent events and can register custom tools.
+ * They provide a unified system for extensions, custom tools, commands, and more.
+ *
+ * By default, extension files are discovered from:
+ * - ~/.pi/agent/extensions/
+ * - <cwd>/.pi/extensions/
+ * - Paths specified in settings.json "extensions" array
+ *
+ * An extension is a TypeScript file that exports a default function:
+ *   export default function (pi: ExtensionAPI) { ... }
+ */
+
+import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
+
+// Extensions are discovered automatically from standard locations.
+// You can also add paths via:
+//   1. settings.json: { "extensions": ["./my-extension.ts"] }
+//   2. additionalExtensionPaths option (see below)
+
+// To add additional extension paths beyond discovery:
+const { session } = await createAgentSession({
+	additionalExtensionPaths: ["./my-logging-extension.ts", "./my-safety-extension.ts"],
+	sessionManager: SessionManager.inMemory(),
+});
+
+session.subscribe((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	}
+});
+
+await session.prompt("List files in the current directory.");
+console.log();
+
+// Example extension file (./my-logging-extension.ts):
+/*
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("agent_start", async () => {
+		console.log("[Extension] Agent starting");
+	});
+
+	pi.on("tool_call", async (event) => {
+		console.log(\`[Extension] Tool: \${event.toolName}\`);
+		// Return { block: true, reason: "..." } to block execution
+		return undefined;
+	});
+
+	pi.on("agent_end", async (event) => {
+		console.log(\`[Extension] Done, \${event.messages.length} messages\`);
+	});
+
+	// Register a custom tool
+	pi.registerTool({
+		name: "my_tool",
+		label: "My Tool",
+		description: "Does something useful",
+		parameters: Type.Object({
+			input: Type.String(),
+		}),
+		execute: async (_toolCallId, params, _onUpdate, _ctx, _signal) => ({
+			content: [{ type: "text", text: \`Processed: \${params.input}\` }],
+			details: {},
+		}),
+	});
+
+	// Register a command
+	pi.registerCommand("mycommand", {
+		description: "Do something",
+		handler: async (args, ctx) => {
+			ctx.ui.notify(\`Command executed with: \${args}\`);
+		},
+	});
+}
+*/

package/examples/sdk/07-context-files.ts

@@ -0,0 +1,36 @@
+/**
+ * Context Files (AGENTS.md)
+ *
+ * Context files provide project-specific instructions loaded into the system prompt.
+ */
+
+import { createAgentSession, discoverContextFiles, SessionManager } from "@mariozechner/pi-coding-agent";
+
+// Discover AGENTS.md files walking up from cwd
+const discovered = discoverContextFiles();
+console.log("Discovered context files:");
+for (const file of discovered) {
+	console.log(`  - ${file.path} (${file.content.length} chars)`);
+}
+
+// Use custom context files
+await createAgentSession({
+	contextFiles: [
+		...discovered,
+		{
+			path: "/virtual/AGENTS.md",
+			content: `# Project Guidelines
+
+## Code Style
+- Use TypeScript strict mode
+- No any types
+- Prefer const over let`,
+		},
+	],
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log(`Session created with ${discovered.length + 1} context files`);
+
+// Disable context files:
+// contextFiles: []

package/examples/sdk/08-prompt-templates.ts

@@ -0,0 +1,42 @@
+/**
+ * Prompt Templates
+ *
+ * File-based templates that inject content when invoked with /templatename.
+ */
+
+import {
+	createAgentSession,
+	discoverPromptTemplates,
+	type PromptTemplate,
+	SessionManager,
+} from "@mariozechner/pi-coding-agent";
+
+// Discover templates from cwd/.pi/prompts/ and ~/.pi/agent/prompts/
+const discovered = discoverPromptTemplates();
+console.log("Discovered prompt templates:");
+for (const template of discovered) {
+	console.log(`  /${template.name}: ${template.description}`);
+}
+
+// Define custom templates
+const deployTemplate: PromptTemplate = {
+	name: "deploy",
+	description: "Deploy the application",
+	source: "(custom)",
+	content: `# Deploy Instructions
+
+1. Build: npm run build
+2. Test: npm test
+3. Deploy: npm run deploy`,
+};
+
+// Use discovered + custom templates
+await createAgentSession({
+	promptTemplates: [...discovered, deployTemplate],
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log(`Session created with ${discovered.length + 1} prompt templates`);
+
+// Disable prompt templates:
+// promptTemplates: []

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

@@ -0,0 +1,55 @@
+/**
+ * API Keys and OAuth
+ *
+ * Configure API key resolution via AuthStorage and ModelRegistry.
+ */
+
+import {
+	AuthStorage,
+	createAgentSession,
+	discoverAuthStorage,
+	discoverModels,
+	ModelRegistry,
+	SessionManager,
+} from "@mariozechner/pi-coding-agent";
+
+// Default: discoverAuthStorage() uses ~/.pi/agent/auth.json
+// discoverModels() loads built-in + custom models from ~/.pi/agent/models.json
+const authStorage = discoverAuthStorage();
+const modelRegistry = discoverModels(authStorage);
+
+await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	authStorage,
+	modelRegistry,
+});
+console.log("Session with default auth storage and model registry");
+
+// Custom auth storage location
+const customAuthStorage = new AuthStorage("/tmp/my-app/auth.json");
+const customModelRegistry = new ModelRegistry(customAuthStorage, "/tmp/my-app/models.json");
+
+await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	authStorage: customAuthStorage,
+	modelRegistry: customModelRegistry,
+});
+console.log("Session with custom auth storage location");
+
+// Runtime API key override (not persisted to disk)
+authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	authStorage,
+	modelRegistry,
+});
+console.log("Session with runtime API key override");
+
+// No models.json - only built-in models
+const simpleRegistry = new ModelRegistry(authStorage); // null = no models.json
+await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	authStorage,
+	modelRegistry: simpleRegistry,
+});
+console.log("Session with only built-in models");

package/examples/sdk/10-settings.ts

@@ -0,0 +1,38 @@
+/**
+ * Settings Configuration
+ *
+ * Override settings using SettingsManager.
+ */
+
+import { createAgentSession, loadSettings, SessionManager, SettingsManager } from "@mariozechner/pi-coding-agent";
+
+// Load current settings (merged global + project)
+const settings = loadSettings();
+console.log("Current settings:", JSON.stringify(settings, null, 2));
+
+// Override specific settings
+const settingsManager = SettingsManager.create();
+settingsManager.applyOverrides({
+	compaction: { enabled: false },
+	retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },
+});
+
+await createAgentSession({
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log("Session created with custom settings");
+
+// For testing without file I/O:
+const inMemorySettings = SettingsManager.inMemory({
+	compaction: { enabled: false },
+	retry: { enabled: false },
+});
+
+await createAgentSession({
+	settingsManager: inMemorySettings,
+	sessionManager: SessionManager.inMemory(),
+});
+
+console.log("Test session created with in-memory settings");

package/examples/sdk/11-sessions.ts

@@ -0,0 +1,48 @@
+/**
+ * Session Management
+ *
+ * Control session persistence: in-memory, new file, continue, or open specific.
+ */
+
+import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
+
+// In-memory (no persistence)
+const { session: inMemory } = await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+});
+console.log("In-memory session:", inMemory.sessionFile ?? "(none)");
+
+// New persistent session
+const { session: newSession } = await createAgentSession({
+	sessionManager: SessionManager.create(process.cwd()),
+});
+console.log("New session file:", newSession.sessionFile);
+
+// Continue most recent session (or create new if none)
+const { session: continued, modelFallbackMessage } = await createAgentSession({
+	sessionManager: SessionManager.continueRecent(process.cwd()),
+});
+if (modelFallbackMessage) console.log("Note:", modelFallbackMessage);
+console.log("Continued session:", continued.sessionFile);
+
+// List and open specific session
+const sessions = await SessionManager.list(process.cwd());
+console.log(`\nFound ${sessions.length} sessions:`);
+for (const info of sessions.slice(0, 3)) {
+	console.log(`  ${info.id.slice(0, 8)}... - "${info.firstMessage.slice(0, 30)}..."`);
+}
+
+if (sessions.length > 0) {
+	const { session: opened } = await createAgentSession({
+		sessionManager: SessionManager.open(sessions[0].path),
+	});
+	console.log(`\nOpened: ${opened.sessionId}`);
+}
+
+// Custom session directory (no cwd encoding)
+// const customDir = "/path/to/my-sessions";
+// const { session } = await createAgentSession({
+//   sessionManager: SessionManager.create(process.cwd(), customDir),
+// });
+// SessionManager.list(process.cwd(), customDir);
+// SessionManager.continueRecent(process.cwd(), customDir);

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

@@ -0,0 +1,72 @@
+/**
+ * Full Control
+ *
+ * Replace everything - no discovery, explicit configuration.
+ *
+ * IMPORTANT: When providing `tools` with a custom `cwd`, use the tool factory
+ * functions (createReadTool, createBashTool, etc.) to ensure tools resolve
+ * paths relative to your cwd.
+ */
+
+import { getModel } from "@mariozechner/pi-ai";
+import {
+	AuthStorage,
+	createAgentSession,
+	createBashTool,
+	createReadTool,
+	ModelRegistry,
+	SessionManager,
+	SettingsManager,
+} from "@mariozechner/pi-coding-agent";
+
+// Custom auth storage location
+const authStorage = new AuthStorage("/tmp/my-agent/auth.json");
+
+// Runtime API key override (not persisted)
+if (process.env.MY_ANTHROPIC_KEY) {
+	authStorage.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+}
+
+// Model registry with no custom models.json
+const modelRegistry = new ModelRegistry(authStorage);
+
+const model = getModel("anthropic", "claude-sonnet-4-20250514");
+if (!model) throw new Error("Model not found");
+
+// In-memory settings with overrides
+const settingsManager = SettingsManager.inMemory({
+	compaction: { enabled: false },
+	retry: { enabled: true, maxRetries: 2 },
+});
+
+// When using a custom cwd with explicit tools, use the factory functions
+const cwd = process.cwd();
+
+const { session } = await createAgentSession({
+	cwd,
+	agentDir: "/tmp/my-agent",
+	model,
+	thinkingLevel: "off",
+	authStorage,
+	modelRegistry,
+	systemPrompt: `You are a minimal assistant.
+Available: read, bash. Be concise.`,
+	// Use factory functions with the same cwd to ensure path resolution works correctly
+	tools: [createReadTool(cwd), createBashTool(cwd)],
+	// Pass empty array to disable extension discovery, or provide inline factories
+	extensions: [],
+	skills: [],
+	contextFiles: [],
+	promptTemplates: [],
+	sessionManager: SessionManager.inMemory(),
+	settingsManager,
+});
+
+session.subscribe((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	}
+});
+
+await session.prompt("List files in the current directory.");
+console.log();

package/examples/sdk/README.md

@@ -0,0 +1,150 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()`.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tools, custom tools |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@mariozechner/pi-ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  discoverAuthStorage,
+  discoverModels,
+  discoverSkills,
+  discoverExtensions,
+  discoverContextFiles,
+  discoverPromptTemplates,
+  loadSettings,
+  buildSystemPrompt,
+  ModelRegistry,
+  SessionManager,
+  codingTools,
+  readOnlyTools,
+  readTool, bashTool, editTool, writeTool,
+} from "@mariozechner/pi-coding-agent";
+
+// Auth and models setup
+const authStorage = discoverAuthStorage();
+const modelRegistry = discoverModels(authStorage);
+
+// Minimal
+const { session } = await createAgentSession({ authStorage, modelRegistry });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+
+// Modify prompt
+const { session } = await createAgentSession({
+  systemPrompt: (defaultPrompt) => defaultPrompt + "\n\nBe concise.",
+  authStorage,
+  modelRegistry,
+});
+
+// Read-only
+const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
+});
+
+// Full control
+const customAuth = new AuthStorage("/my/app/auth.json");
+customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const customRegistry = new ModelRegistry(customAuth);
+
+const { session } = await createAgentSession({
+  model,
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
+  systemPrompt: "You are helpful.",
+  tools: [readTool, bashTool],
+  customTools: [{ tool: myTool }],
+  extensions: [{ factory: myExtension }],
+  skills: [],
+  contextFiles: [],
+  promptTemplates: [],
+  sessionManager: SessionManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `authStorage` | `discoverAuthStorage()` | Credential storage |
+| `modelRegistry` | `discoverModels(authStorage)` | Model registry |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.pi/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `systemPrompt` | Discovered | String or `(default) => modified` |
+| `tools` | `codingTools` | Built-in tools |
+| `customTools` | Discovered | Replaces discovery |
+| `additionalCustomToolPaths` | `[]` | Merge with discovery |
+| `extensions` | Discovered | Replaces discovery |
+| `additionalExtensionPaths` | `[]` | Merge with discovery |
+| `skills` | Discovered | Skills for prompt |
+| `contextFiles` | Discovered | AGENTS.md files |
+| `promptTemplates` | Discovered | Prompt templates (slash commands) |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | From agentDir | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_end":
+      console.log("Done");
+      break;
+  }
+});
+```