@nghyane/arcane 0.1.0

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

@@ -0,0 +1,49 @@
+/**
+ * Custom Model Selection
+ *
+ * Shows how to select a specific model and thinking level.
+ */
+
+import { createAgentSession, discoverAuthStorage, discoverModels } from "@nghyane/arcane";
+import { getModel } from "@nghyane/arcane-ai";
+
+// Set up auth storage and model registry
+const authStorage = await discoverAuthStorage();
+const modelRegistry = await discoverModels(authStorage);
+
+// Option 1: Find a specific built-in model by provider/id
+const opus = getModel("anthropic", "claude-opus-4-5");
+if (opus) {
+	console.log(`Found model: ${opus.provider}/${opus.id}`);
+}
+
+// Option 2: Find model via registry (includes custom models from models.json)
+const customModel = modelRegistry.find("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 = modelRegistry.getAvailable();
+console.log(
+	"Available models:",
+	available.map(m => `${m.provider}/${m.id}`),
+);
+
+if (available.length > 0) {
+	const { session } = await createAgentSession({
+		model: available[0],
+		thinkingLevel: "medium", // off, low, medium, high
+		authStorage,
+		modelRegistry,
+	});
+
+	session.subscribe(event => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+
+	await session.prompt("Say hello in one sentence.");
+	console.log();
+}

package/examples/sdk/03-custom-prompt.ts

@@ -0,0 +1,43 @@
+/**
+ * Custom System Prompt
+ *
+ * Shows how to replace or modify the default system prompt.
+ */
+import { createAgentSession, SessionManager } from "@nghyane/arcane";
+
+// Option 1: Replace prompt entirely
+const { session: session1 } = await createAgentSession({
+	systemPrompt: `You are a helpful assistant that speaks like a pirate.
+Always end responses with "Arrr!"`,
+	sessionManager: SessionManager.inMemory(),
+});
+
+session1.subscribe(event => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	}
+});
+
+console.log("=== Replace prompt ===");
+await session1.prompt("What is 2 + 2?");
+console.log("\n");
+
+// Option 2: Modify default prompt (receives default, returns modified)
+const { session: session2 } = await createAgentSession({
+	systemPrompt: defaultPrompt => `${defaultPrompt}
+
+## Additional Instructions
+- Always be concise
+- Use bullet points when listing things`,
+	sessionManager: SessionManager.inMemory(),
+});
+
+session2.subscribe(event => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	}
+});
+
+console.log("=== Modify prompt ===");
+await session2.prompt("List 3 benefits of TypeScript.");
+console.log();

package/examples/sdk/04-skills.ts

@@ -0,0 +1,43 @@
+/**
+ * Skills Configuration
+ *
+ * Skills provide specialized instructions loaded into the system prompt.
+ * Discover, filter, merge, or replace them.
+ */
+import { createAgentSession, discoverSkills, SessionManager, type Skill } from "@nghyane/arcane";
+
+// Discover all skills from cwd/.arcane/skills, ~/.arcane/agent/skills, etc.
+const { skills: allSkills } = await discoverSkills();
+console.log(
+	"Discovered skills:",
+	allSkills.map(s => s.name),
+);
+
+// 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/06-extensions.ts

@@ -0,0 +1,80 @@
+/**
+ * Extensions Configuration
+ *
+ * Extensions intercept agent events and can register custom tools.
+ * They provide a unified system for extensions, custom tools, commands, and more.
+ *
+ * Extension files are discovered from:
+ * - ~/.arcane/agent/extensions/
+ * - <cwd>/.arcane/extensions/ (legacy: <cwd>/.arcane/extensions/)
+ * - Paths specified in settings.json "extensions" array
+ * - Paths passed via --extension CLI flag
+ *
+ * An extension is a TypeScript file that exports a default function:
+ *   export default function (pi: ExtensionAPI) { ... }
+ */
+import { createAgentSession, SessionManager } from "@nghyane/arcane";
+
+// Extensions are loaded from disk, not passed inline to createAgentSession.
+// Use the discovery mechanism:
+//   1. Place extension files in ~/.arcane/agent/extensions/ or .arcane/extensions/
+//   2. Add paths to settings.json: { "extensions": ["./my-extension.ts"] }
+//   3. Use --extension flag: pi --extension ./my-extension.ts
+
+// 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 "@nghyane/arcane";
+
+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/06-hooks.ts

@@ -0,0 +1,61 @@
+/**
+ * Hooks Configuration
+ *
+ * Hooks intercept agent events for logging, blocking, or modification.
+ * Note: "hooks" is now called "extensions" in the API.
+ */
+import { createAgentSession, type ExtensionFactory, SessionManager } from "@nghyane/arcane";
+
+// Logging hook (now called extension)
+const loggingHook: ExtensionFactory = api => {
+	api.on("agent_start", async () => {
+		console.log("[Hook] Agent starting");
+	});
+
+	api.on("tool_call", async event => {
+		console.log(`[Hook] Tool: ${event.toolName}`);
+		return undefined; // Don't block
+	});
+
+	api.on("agent_end", async event => {
+		console.log(`[Hook] Done, ${event.messages.length} messages`);
+	});
+};
+
+// Blocking extension (returns { block: true, reason: "..." })
+const safetyHook: ExtensionFactory = api => {
+	api.on("tool_call", async event => {
+		if (event.toolName === "bash") {
+			const cmd = (event.input as { command?: string }).command ?? "";
+			if (cmd.includes("rm -rf")) {
+				return { block: true, reason: "Dangerous command blocked" };
+			}
+		}
+		return undefined;
+	});
+};
+
+// Use inline extensions (hooks is now extensions)
+const { session } = await createAgentSession({
+	extensions: [loggingHook, safetyHook],
+	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();
+
+// Disable all extensions:
+// extensions: []
+
+// Merge with discovered extensions:
+// const discovered = await discoverExtensions();
+// extensions: [...discovered.extensions.map(e => e.factory), myHook]
+
+// Add paths without replacing discovery:
+// additionalExtensionPaths: ["/extra/extensions"]

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

@@ -0,0 +1,35 @@
+/**
+ * Context Files (AGENTS.md)
+ *
+ * Context files provide project-specific instructions loaded into the system prompt.
+ */
+import { createAgentSession, discoverContextFiles, SessionManager } from "@nghyane/arcane";
+
+// 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,36 @@
+/**
+ * Prompt Templates
+ *
+ * File-based templates that inject content when invoked with /templatename.
+ */
+import { createAgentSession, discoverPromptTemplates, type PromptTemplate, SessionManager } from "@nghyane/arcane";
+
+// Discover templates from cwd/.arcane/prompts/ and ~/.arcane/agent/prompts/
+const discovered = await 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/08-slash-commands.ts

@@ -0,0 +1,41 @@
+/**
+ * Slash Commands
+ *
+ * File-based commands that inject content when invoked with /commandname.
+ * Note: File-based slash commands are now called "prompt templates".
+ */
+import { createAgentSession, discoverPromptTemplates, type PromptTemplate, SessionManager } from "@nghyane/arcane";
+
+// Discover prompt templates from cwd/.arcane/prompts/ and ~/.arcane/agent/prompts/
+const discovered = await discoverPromptTemplates();
+console.log("Discovered prompt templates:");
+for (const cmd of discovered) {
+	console.log(`  /${cmd.name}: ${cmd.description}`);
+}
+
+// Define custom prompt templates
+const deployCommand: 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`,
+};
+
+// Note: slashCommands is now managed by the agent session automatically.
+// Custom commands can be loaded via discoverCustomTSCommands() for TypeScript commands.
+// For file-based markdown commands, use promptTemplates instead.
+
+// Convert file-based slash commands to prompt templates
+await createAgentSession({
+	promptTemplates: [...discovered, deployCommand],
+	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,54 @@
+/**
+ * API Keys and OAuth
+ *
+ * Configure API key resolution via AuthStorage and ModelRegistry.
+ */
+import {
+	AuthStorage,
+	createAgentSession,
+	discoverAuthStorage,
+	discoverModels,
+	ModelRegistry,
+	SessionManager,
+} from "@nghyane/arcane";
+
+// Default: discoverAuthStorage() uses ~/.arcane/agent/agent.db
+// discoverModels() loads built-in + custom models from ~/.arcane/agent/models.json
+const authStorage = await discoverAuthStorage();
+const modelRegistry = await 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 = await AuthStorage.create("/tmp/my-app/agent.db");
+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/11-sessions.ts

@@ -0,0 +1,47 @@
+/**
+ * Session Management
+ *
+ * Control session persistence: in-memory, new file, continue, or open specific.
+ */
+import { createAgentSession, SessionManager } from "@nghyane/arcane";
+
+// 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: await 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: await 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/README.md

@@ -0,0 +1,150 @@
+# SDK Examples
+
+Programmatic usage of arc-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-hooks.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 "@nghyane/arcane-ai";
+import {
+	AuthStorage,
+	createAgentSession,
+	discoverAuthStorage,
+	discoverModels,
+	discoverSkills,
+	discoverHooks,
+	discoverCustomTools,
+	discoverContextFiles,
+	discoverSlashCommands,
+	loadSettings,
+	buildSystemPrompt,
+	ModelRegistry,
+	SessionManager,
+	BUILTIN_TOOLS,
+	createTools,
+} from "@nghyane/arcane";
+
+// 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 tools
+const { session } = await createAgentSession({ toolNames: ["read", "grep", "find", "ls"], authStorage, modelRegistry });
+
+// In-memory
+const { session } = await createAgentSession({
+	sessionManager: SessionManager.inMemory(),
+	authStorage,
+	modelRegistry,
+});
+
+// Full control
+const customAuth = await AuthStorage.create("/my/app/agent.db");
+customAuth.setRuntimeApiKey("anthropic", Bun.env.MY_KEY!);
+const customRegistry = new ModelRegistry(customAuth);
+
+const { session } = await createAgentSession({
+	model,
+	authStorage: customAuth,
+	modelRegistry: customRegistry,
+	systemPrompt: "You are helpful.",
+	toolNames: ["read", "bash"],
+	customTools: [{ tool: myTool }],
+	hooks: [{ factory: myHook }],
+	skills: [],
+	contextFiles: [],
+	slashCommands: [],
+	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`                  | `~/.arcane/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` |
+| `toolNames`                 | All built-in tools            | Filter which tools to include     |
+| `customTools`               | Discovered                    | Replaces discovery                |
+| `additionalCustomToolPaths` | `[]`                          | Merge with discovery              |
+| `hooks`                     | Discovered                    | Replaces discovery                |
+| `additionalHookPaths`       | `[]`                          | Merge with discovery              |
+| `skills`                    | Discovered                    | Skills for prompt                 |
+| `contextFiles`              | Discovered                    | AGENTS.md files                   |
+| `slashCommands`             | Discovered                    | File 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;
+	}
+});
+```