@nghyane/arcane 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+## [Unreleased]

package/README.md

@@ -0,0 +1,12 @@
+# @nghyane/arcane
+
+Core implementation package for the \`arc\` coding agent in the `arcane` monorepo.
+
+For installation, setup, provider configuration, model roles, slash commands, and full CLI reference, see:
+- [Monorepo README (local)](../../README.md)
+- [Monorepo README (GitHub)](https://github.com/nghyane/arcane#readme)
+
+Package-specific references:
+- [CHANGELOG](./CHANGELOG.md)
+- [Documentation](./docs/)
+- [DEVELOPMENT](./DEVELOPMENT.md)

package/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+Example code for arc-coding-agent SDK, hooks, and custom tools.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, hooks, and session management.
+
+### [hooks/](hooks/)
+Example hooks for intercepting tool calls, adding safety gates, and integrating with external systems.
+
+### [custom-tools/](custom-tools/)
+Example custom tools that extend the agent's capabilities.
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Hooks Documentation](../docs/hooks.md)
+- [Custom Tools Documentation](../docs/custom-tools.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/custom-tools/README.md

@@ -0,0 +1,109 @@
+# Custom Tools Examples
+
+Example custom tools for arc-coding-agent.
+
+## Examples
+
+Each example uses the `subdirectory/index.ts` structure required for tool discovery.
+
+### hello/
+
+Minimal example showing the basic structure of a custom tool.
+
+### todo/
+
+Full-featured example demonstrating:
+
+- `onSession` for state reconstruction from session history
+- Custom `renderCall` and `renderResult`
+- Proper branching support via details storage
+- State management without external files
+
+## Usage
+
+```bash
+# Test directly (can point to any .ts file)
+arc --tool examples/custom-tools/todo/index.ts
+
+# Or copy entire folder to tools directory for persistent use
+cp -r todo ~/.arcane/agent/tools/
+```
+
+Then in arc:
+
+```
+> add a todo "test custom tools"
+> list todos
+> toggle todo #1
+> clear todos
+```
+
+## Writing Custom Tools
+
+See [docs/custom-tools.md](../../docs/custom-tools.md) for full documentation.
+
+### Key Points
+
+**Factory pattern:**
+
+```typescript
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@nghyane/arcane-ai";
+import { Text } from "@nghyane/arcane-tui";
+import type { CustomToolFactory } from "@nghyane/arcane";
+
+const factory: CustomToolFactory = (pi) => ({
+	name: "my_tool",
+	label: "My Tool",
+	description: "Tool description for LLM",
+	parameters: Type.Object({
+		action: StringEnum(["list", "add"] as const),
+	}),
+
+	// Called on session start/switch/branch/clear
+	onSession(event) {
+		// Reconstruct state from event.entries
+	},
+
+	async execute(toolCallId, params) {
+		return {
+			content: [{ type: "text", text: "Result" }],
+			details: {
+				/* for rendering and state reconstruction */
+			},
+		};
+	},
+});
+
+export default factory;
+```
+
+**Custom rendering:**
+
+```typescript
+renderCall(args, theme) {
+  return new Text(
+    theme.fg("toolTitle", theme.bold("my_tool ")) + args.action,
+    0, 0  // No padding - Box handles it
+  );
+},
+
+renderResult(result, { expanded, isPartial }, theme) {
+  if (isPartial) {
+    return new Text(theme.fg("warning", "Working..."), 0, 0);
+  }
+  return new Text(theme.fg("success", "✓ Done"), 0, 0);
+},
+```
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+
+```typescript
+import { StringEnum } from "@nghyane/arcane-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const);
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")]);
+```

package/examples/custom-tools/hello/index.ts

@@ -0,0 +1,20 @@
+import type { CustomToolFactory } from "@nghyane/arcane";
+
+const factory: CustomToolFactory = pi => ({
+	name: "hello",
+	label: "Hello",
+	description: "A simple greeting tool",
+	parameters: pi.typebox.Type.Object({
+		name: pi.typebox.Type.String({ description: "Name to greet" }),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		const { name } = params;
+		return {
+			content: [{ type: "text", text: `Hello, ${name}!` }],
+			details: { greeted: name },
+		};
+	},
+});
+
+export default factory;

package/examples/custom-tools/todo/index.ts

@@ -0,0 +1,206 @@
+/**
+ * Todo Tool - Demonstrates state management via session entries
+ *
+ * This tool stores state in tool result details (not external files),
+ * which allows proper branching - when you branch, the todo state
+ * is automatically correct for that point in history.
+ *
+ * The onSession callback reconstructs state by scanning past tool results.
+ */
+import type { CustomTool, CustomToolContext, CustomToolFactory, CustomToolSessionEvent } from "@nghyane/arcane";
+
+interface Todo {
+	id: number;
+	text: string;
+	done: boolean;
+}
+
+// State stored in tool result details
+interface TodoDetails {
+	action: "list" | "add" | "toggle" | "clear";
+	todos: Todo[];
+	nextId: number;
+	error?: string;
+}
+
+const factory: CustomToolFactory = pi => {
+	const { Type } = pi.typebox;
+	const { StringEnum, Text } = pi.pi;
+
+	// Define schema separately for proper type inference
+	const TodoParams = Type.Object({
+		action: StringEnum(["list", "add", "toggle", "clear"] as const),
+		text: Type.Optional(Type.String({ description: "Todo text (for add)" })),
+		id: Type.Optional(Type.Number({ description: "Todo ID (for toggle)" })),
+	});
+	// In-memory state (reconstructed from session on load)
+	let todos: Todo[] = [];
+	let nextId = 1;
+
+	/**
+	 * Reconstruct state from session entries.
+	 * Scans tool results for this tool and applies them in order.
+	 */
+	const reconstructState = (_event: CustomToolSessionEvent, ctx: CustomToolContext) => {
+		todos = [];
+		nextId = 1;
+
+		// Use getBranch() to get entries on the current branch
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type !== "message") continue;
+			const msg = entry.message;
+
+			// Tool results have role "toolResult"
+			if (msg.role !== "toolResult") continue;
+			if (msg.toolName !== "todo") continue;
+
+			const details = msg.details as TodoDetails | undefined;
+			if (details) {
+				todos = details.todos;
+				nextId = details.nextId;
+			}
+		}
+	};
+
+	const tool: CustomTool<typeof TodoParams, TodoDetails> = {
+		name: "todo",
+		label: "Todo",
+		description: "Manage a todo list. Actions: list, add (text), toggle (id), clear",
+		parameters: TodoParams,
+
+		// Called on session start/switch/branch/clear
+		onSession: reconstructState,
+
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+			switch (params.action) {
+				case "list":
+					return {
+						content: [
+							{
+								type: "text",
+								text: todos.length
+									? todos.map(t => `[${t.done ? "x" : " "}] #${t.id}: ${t.text}`).join("\n")
+									: "No todos",
+							},
+						],
+						details: { action: "list", todos: [...todos], nextId },
+					};
+
+				case "add": {
+					if (!params.text) {
+						return {
+							content: [{ type: "text", text: "Error: text required for add" }],
+							details: { action: "add", todos: [...todos], nextId, error: "text required" },
+						};
+					}
+					const newTodo: Todo = { id: nextId++, text: params.text, done: false };
+					todos.push(newTodo);
+					return {
+						content: [{ type: "text", text: `Added todo #${newTodo.id}: ${newTodo.text}` }],
+						details: { action: "add", todos: [...todos], nextId },
+					};
+				}
+
+				case "toggle": {
+					if (params.id === undefined) {
+						return {
+							content: [{ type: "text", text: "Error: id required for toggle" }],
+							details: { action: "toggle", todos: [...todos], nextId, error: "id required" },
+						};
+					}
+					const todo = todos.find(t => t.id === params.id);
+					if (!todo) {
+						return {
+							content: [{ type: "text", text: `Todo #${params.id} not found` }],
+							details: { action: "toggle", todos: [...todos], nextId, error: `#${params.id} not found` },
+						};
+					}
+					todo.done = !todo.done;
+					return {
+						content: [{ type: "text", text: `Todo #${todo.id} ${todo.done ? "completed" : "uncompleted"}` }],
+						details: { action: "toggle", todos: [...todos], nextId },
+					};
+				}
+
+				case "clear": {
+					const count = todos.length;
+					todos = [];
+					nextId = 1;
+					return {
+						content: [{ type: "text", text: `Cleared ${count} todos` }],
+						details: { action: "clear", todos: [], nextId: 1 },
+					};
+				}
+
+				default:
+					return {
+						content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+						details: { action: "list", todos: [...todos], nextId, error: `unknown action: ${params.action}` },
+					};
+			}
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", String(args.action));
+			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
+			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			const { details } = result;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			// Error
+			if (details.error) {
+				return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+			}
+
+			const todoList = details.todos;
+
+			switch (details.action) {
+				case "list": {
+					if (todoList.length === 0) {
+						return new Text(theme.fg("dim", "No todos"), 0, 0);
+					}
+					let listText = theme.fg("muted", `${todoList.length} todo(s):`);
+					const display = expanded ? todoList : todoList.slice(0, 5);
+					for (const t of display) {
+						const check = t.done ? theme.fg("success", "✓") : theme.fg("dim", "○");
+						const itemText = t.done ? theme.fg("dim", t.text) : theme.fg("muted", t.text);
+						listText += `\n${check} ${theme.fg("accent", `#${t.id}`)} ${itemText}`;
+					}
+					if (!expanded && todoList.length > 5) {
+						listText += `\n${theme.fg("dim", `... ${todoList.length - 5} more`)}`;
+					}
+					return new Text(listText, 0, 0);
+				}
+
+				case "add": {
+					const added = todoList[todoList.length - 1];
+					return new Text(
+						`${theme.fg("success", "✓ Added ") + theme.fg("accent", `#${added.id}`)} ${theme.fg("muted", added.text)}`,
+						0,
+						0,
+					);
+				}
+
+				case "toggle": {
+					const text = result.content[0];
+					const msg = text?.type === "text" ? text.text : "";
+					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", msg), 0, 0);
+				}
+
+				case "clear":
+					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Cleared all todos"), 0, 0);
+			}
+		},
+	};
+
+	return tool;
+};
+
+export default factory;

package/examples/extensions/README.md

@@ -0,0 +1,143 @@
+# Extension Examples
+
+Example extensions for pi-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+pi --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.arcane/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension                | Description                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| `permission-gate.ts`     | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `protected-paths.ts`     | Blocks writes to protected paths (.env, .git/, node_modules/)                |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch)          |
+| `dirty-repo-guard.ts`    | Prevents session changes with uncommitted git changes                        |
+
+### Custom Tools
+
+| Extension     | Description                                                                   |
+| ------------- | ----------------------------------------------------------------------------- |
+| `todo.ts`     | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts`    | Minimal custom tool example                                                   |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions                  |
+| `subagent/`   | Delegate tasks to specialized subagents with isolated context windows         |
+
+### Commands & UI
+
+| Extension        | Description                                                                    |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `plan-mode.ts`   | Claude Code-style plan mode for read-only exploration with `/plan` command     |
+| `tools.ts`       | Interactive `/tools` command to enable/disable tools with session persistence  |
+| `handoff.ts`     | Transfer context to a new focused session via `/handoff <goal>`                |
+| `qna.ts`         | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors      |
+| `snake.ts`       | Snake game with custom UI, keyboard handling, and session persistence          |
+
+### Git Integration
+
+| Extension                | Description                                                               |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `git-checkpoint.ts`      | Creates git stash checkpoints at each turn for code restoration on branch |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message      |
+
+### System Prompt & Compaction
+
+| Extension              | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| `pirate.ts`            | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation                 |
+
+### External Dependencies
+
+| Extension         | Description                                                               |
+| ----------------- | ------------------------------------------------------------------------- |
+| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
+| `with-deps/`      | Extension with its own package.json and dependencies                      |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation             |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@nghyane/arcane";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+	// Subscribe to lifecycle events
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+			const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+			if (!ok) return { block: true, reason: "Blocked by user" };
+		}
+	});
+
+	// Register custom tools
+	pi.registerTool({
+		name: "greet",
+		label: "Greeting",
+		description: "Generate a greeting",
+		parameters: Type.Object({
+			name: Type.String({ description: "Name to greet" }),
+		}),
+		async execute(toolCallId, params, onUpdate, ctx, signal) {
+			return {
+				content: [{ type: "text", text: `Hello, ${params.name}!` }],
+				details: {},
+			};
+		},
+	});
+
+	// Register commands
+	pi.registerCommand("hello", {
+		description: "Say hello",
+		handler: async (args, ctx) => {
+			ctx.ui.notify("Hello!", "info");
+		},
+	});
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+
+```typescript
+import { StringEnum } from "@nghyane/arcane-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const);
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")]);
+```
+
+**State persistence via details:**
+
+```typescript
+// Store state in tool result details for proper branching support
+return {
+	content: [{ type: "text", text: "Done" }],
+	details: { todos: [...todos], nextId }, // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type === "message" && entry.message.toolName === "my_tool") {
+			const details = entry.message.details;
+			// Reconstruct state from details
+		}
+	}
+});
+```

package/examples/extensions/api-demo.ts

@@ -0,0 +1,89 @@
+/**
+ * API Demo Extension
+ *
+ * Demonstrates using ExtensionAPI's logger, typebox, and pi module access.
+ * These features are now exposed directly on the ExtensionAPI, matching
+ * the CustomToolAPI interface.
+ */
+import type { ExtensionAPI } from "@nghyane/arcane";
+
+export default function (pi: ExtensionAPI) {
+	// 1. Access TypeBox directly from pi.typebox (no separate import needed)
+	const { Type } = pi.typebox;
+
+	// 2. Access the logger for debugging
+	pi.logger.debug("API demo extension loaded");
+
+	// 3. Register a tool that uses all three API features
+	// Import StringEnum from typebox helpers
+	const { StringEnum } = pi.pi;
+
+	pi.registerTool({
+		name: "api_demo",
+		label: "API Demo",
+		description: "Demonstrates ExtensionAPI capabilities: logger, typebox, and pi module access",
+		parameters: Type.Object({
+			message: Type.String({ description: "Test message" }),
+			logLevel: Type.Optional(
+				StringEnum(["error", "warn", "debug"], {
+					description: "Log level to use",
+					default: "debug",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _onUpdate, ctx, _signal) {
+			const { message, logLevel = "debug" } = params as { message: string; logLevel?: "error" | "warn" | "debug" };
+
+			// Use logger at specified level
+			pi.logger[logLevel]("API demo tool executed", { message, logLevel });
+
+			// Access pi module utilities
+			const { logger: piLogger } = pi.pi;
+			piLogger.debug("Accessed pi module from extension", { sessionFile: ctx.sessionManager.getSessionFile() });
+
+			// Get session information
+			const sessionInfo = `Session: ${ctx.sessionManager.getSessionFile()}`;
+			const modelInfo = ctx.model ? `Model: ${ctx.model.id}` : "Model: none";
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: [
+							`API Demo Tool executed successfully!`,
+							``,
+							`Message: ${message}`,
+							`Log Level: ${logLevel}`,
+							``,
+							`Features demonstrated:`,
+							`1. ✓ Logger access via pi.logger`,
+							`2. ✓ TypeBox access via pi.typebox`,
+							`3. ✓ Pi module access via pi.pi`,
+							``,
+							`Context:`,
+							`- ${sessionInfo}`,
+							`- ${modelInfo}`,
+							`- CWD: ${ctx.cwd}`,
+						].join("\n"),
+					},
+				],
+				details: {
+					message,
+					logLevel,
+					sessionFile: ctx.sessionManager.getSessionFile(),
+					modelId: ctx.model?.id,
+				},
+			};
+		},
+	});
+
+	// Demonstrate event handling with logger
+	pi.on("session_start", async () => {
+		pi.logger.debug("Session started", { extension: "api-demo" });
+	});
+
+	pi.on("agent_start", async () => {
+		pi.logger.debug("Agent started", { extension: "api-demo" });
+	});
+}

package/examples/extensions/chalk-logger.ts

@@ -0,0 +1,25 @@
+/**
+ * Example extension that uses a 3rd party dependency (chalk).
+ * Tests that jiti can resolve npm modules correctly.
+ */
+import type { ExtensionAPI } from "@nghyane/arcane";
+import chalk from "chalk";
+
+export default function (pi: ExtensionAPI) {
+	// Log with colors using chalk
+	console.log(`${chalk.green("✓")} ${chalk.bold("chalk-logger extension loaded")}`);
+
+	pi.on("agent_start", async () => {
+		console.log(`${chalk.blue("[chalk-logger]")} Agent starting`);
+	});
+
+	pi.on("tool_call", async event => {
+		console.log(`${chalk.yellow("[chalk-logger]")} Tool: ${chalk.cyan(event.toolName)}`);
+		return undefined;
+	});
+
+	pi.on("agent_end", async event => {
+		const count = event.messages.length;
+		console.log(`${chalk.green("[chalk-logger]")} Done with ${chalk.bold(String(count))} messages`);
+	});
+}

package/examples/extensions/hello.ts

@@ -0,0 +1,32 @@
+/**
+ * Hello Tool - Minimal custom tool example
+ *
+ * Demonstrates using ExtensionAPI's logger, typebox, and pi module access.
+ */
+import type { ExtensionAPI } from "@nghyane/arcane";
+
+export default function (pi: ExtensionAPI) {
+	// Access TypeBox via pi.typebox (no need to import separately)
+	const { Type } = pi.typebox;
+
+	pi.registerTool({
+		name: "hello",
+		label: "Hello",
+		description: "A simple greeting tool",
+		parameters: Type.Object({
+			name: Type.String({ description: "Name to greet" }),
+		}),
+
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+			const { name } = params as { name: string };
+
+			// Use logger for debugging
+			pi.logger.debug("Hello tool executed", { name });
+
+			return {
+				content: [{ type: "text", text: `Hello, ${name}!` }],
+				details: { greeted: name },
+			};
+		},
+	});
+}