@akonwi/kit 0.1.0 → 0.2.0

package/dist/plugin.d.ts

@@ -1,45 +1,76 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { Api, Model, Static, TSchema } from "@mariozechner/pi-ai";
-import type { JSX } from "solid-js";
 import type { ToastInput } from "./toasts";
 
-export type PluginSubscription = () => void;
-export type PluginDispose = () => void;
+export type Disposer = () => void;
 
-export type PluginOverlaySurfaceProps = {
-	zIndex?: number;
-};
+interface UI {
+	toast: (toast: ToastInput) => void;
+	select(input: {
+		title: string;
+		message?: string;
+		options: string[];
+		filterable?: boolean;
+		placeholder?: string;
+	}): Promise<string | undefined>;
+	select<T>(input: {
+		title: string;
+		message?: string;
+		options: Array<{ label: string; value: T; description?: string }>;
+		filterable?: boolean;
+		placeholder?: string;
+	}): Promise<T | undefined>;
+	input(input: {
+		title: string;
+		message?: string;
+		placeholder?: string;
+		initialValue?: string;
+	}): Promise<string | undefined>;
+	confirm(input: {
+		title: string;
+		message?: string;
+		confirmLabel?: string;
+		cancelLabel?: string;
+		defaultValue?: boolean;
+	}): Promise<boolean>;
+}
 
-export type PluginOverlayComponentProps<T> = {
-	done: (result: T) => void;
-	surfaceProps: PluginOverlaySurfaceProps;
-};
+export type ToolExecutionMode = "sequential" | "parallel";
 
-export type PluginUI = {
-	toast: (toast: ToastInput) => void;
-	custom: <T>(
-		component: (props: PluginOverlayComponentProps<T>) => JSX.Element,
-	) => Promise<T>;
-	getTranscriptViewport: () => { width: number; height: number } | null;
+export type ToolCall = {
+	id: string;
+	name: string;
+	input: Record<string, unknown>;
 };
 
-export type PluginToolExecutionMode = "sequential" | "parallel";
+export type ToolCallDecision =
+	| { action: "allow" }
+	| { action: "reject-and-continue"; message?: string }
+	| undefined
+	// biome-ignore lint/suspicious/noConfusingVoidType: tool call handlers may omit a return value to allow the call.
+	| void;
 
-export type PluginToolResultContentBlock =
+export type ToolCallHandler = (
+	toolCall: ToolCall,
+	ctx: EventContext,
+	signal?: AbortSignal,
+) => ToolCallDecision | Promise<ToolCallDecision>;
+
+export type ToolResultContent =
 	| { type: "text"; text: string }
 	| { type: "image"; data: string; mimeType: string };
 
-export type PluginToolResult<TDetails = unknown> = {
-	content: PluginToolResultContentBlock[];
+export type ToolResult<TDetails = unknown> = {
+	content: ToolResultContent[];
 	details: TDetails;
 	terminate?: boolean;
 };
 
-export type PluginToolUpdateCallback<TDetails = unknown> = (
-	partialResult: PluginToolResult<TDetails>,
+export type ToolUpdateCallback<TDetails = unknown> = (
+	partialResult: ToolResult<TDetails>,
 ) => void;
 
-export type PluginToolDefinition<
+export type ToolDefinition<
 	TParameters extends TSchema = TSchema,
 	TDetails = unknown,
 > = {
@@ -54,21 +85,21 @@ export type PluginToolDefinition<
 		toolCallId: string,
 		params: Static<TParameters>,
 		signal?: AbortSignal,
-		onUpdate?: PluginToolUpdateCallback<TDetails>,
-	) => Promise<PluginToolResult<TDetails>>;
-	executionMode?: PluginToolExecutionMode;
+		onUpdate?: ToolUpdateCallback<TDetails>,
+	) => Promise<ToolResult<TDetails>>;
+	executionMode?: ToolExecutionMode;
 };
 
-export type PluginLogger = {
+type Logger = {
 	log: (...args: unknown[]) => void;
 };
 
-export type PluginMessagePart = {
+export type MessagePart = {
 	type: string;
 	[key: string]: unknown;
 };
 
-export type PluginSession = {
+export type Session = {
 	id: string;
 	cwd: string;
 	name?: string;
@@ -82,11 +113,11 @@ export type PluginSession = {
 	[key: string]: unknown;
 };
 
-export type PluginSessionAPI = {
-	get: () => PluginSession;
+type SessionAPI = {
+	get: () => Session;
 	getMessages: () => AgentMessage[];
 	setName: (name: string) => Promise<void>;
-	submitMessage: (input: string | PluginMessagePart[]) => Promise<void>;
+	submitMessage: (input: string | MessagePart[]) => Promise<void>;
 	submitPromptCommandMessage: (
 		command: string,
 		args: string,
@@ -94,9 +125,7 @@ export type PluginSessionAPI = {
 	) => Promise<void>;
 };
 
-export type PluginReviewDiffView = "unified" | "split";
-
-export type PluginSettings = {
+export type Settings = {
 	theme?: string;
 	bells?: boolean;
 	speech?:
@@ -110,7 +139,7 @@ export type PluginSettings = {
 	guidedQuestions?: boolean;
 	sessionNaming?: boolean;
 	diffs?: {
-		view?: PluginReviewDiffView;
+		view?: "unified" | "split";
 	};
 	retry?: {
 		enabled?: boolean;
@@ -121,76 +150,76 @@ export type PluginSettings = {
 	[key: string]: unknown;
 };
 
-export type PluginSettingsAPI = {
-	get: () => PluginSettings;
-	update: (patch: Partial<PluginSettings>) => Promise<void>;
+type SettingsAPI = {
+	get: () => Settings;
+	update: (patch: Partial<Settings>) => Promise<void>;
 };
 
-export type PluginModelAPI = {
+type ModelAPI = {
 	getCurrent: () => Model<Api> | undefined;
 };
 
-export type PluginSystemAPI = {
+type SystemAPI = {
 	readonly cwd: string;
 	open: (url: string | URL) => Promise<void>;
 };
 
-export type PluginEventContext = {
-	logger: PluginLogger;
-	ui: PluginUI;
-	session: PluginSessionAPI;
-	settings: PluginSettingsAPI;
-	model: PluginModelAPI;
-	system: PluginSystemAPI;
+export type EventContext = {
+	logger: Logger;
+	ui: UI;
+	session: SessionAPI;
+	settings: SettingsAPI;
+	model: ModelAPI;
+	system: SystemAPI;
 };
 
-export type PluginCommandContext = PluginEventContext & {
+export type CommandContext = EventContext & {
 	args: string;
 };
 
-export type PluginCommandOptions = {
+export type CommandOptions = {
 	title?: string;
 	description?: string;
 	argName?: string;
 	category?: string;
 };
 
-export type PluginRuntimeEvent<Type extends string = string> = {
+export type RuntimeEvent<Type extends string = string> = {
 	type: Type;
 } & Record<string, unknown>;
 
-export type PluginEventHandler<Type extends string = string> = (
-	event: PluginRuntimeEvent<Type>,
-	ctx: PluginEventContext,
+export type EventHandler<Type extends string = string> = (
+	event: RuntimeEvent<Type>,
+	ctx: EventContext,
 ) => void | Promise<void>;
 
 export interface PluginAPI {
-	logger: PluginLogger;
-	ui: PluginUI;
-	session: PluginSessionAPI;
-	settings: PluginSettingsAPI;
-	model: PluginModelAPI;
-	system: PluginSystemAPI;
-	on(handler: PluginEventHandler): PluginSubscription;
-	on<Type extends string>(
-		type: Type,
-		handler: PluginEventHandler<Type>,
-	): PluginSubscription;
+	logger: Logger;
+	ui: UI;
+	session: SessionAPI;
+	settings: SettingsAPI;
+	model: ModelAPI;
+	system: SystemAPI;
+	on(handler: EventHandler): Disposer;
+	on<Type extends string>(type: Type, handler: EventHandler<Type>): Disposer;
 	on<Prefix extends string>(
 		options: { prefix: Prefix },
-		handler: PluginEventHandler<`${Prefix}${string}`>,
-	): PluginSubscription;
+		handler: EventHandler<`${Prefix}${string}`>,
+	): Disposer;
 	registerCommand: (
 		id: string,
-		options: PluginCommandOptions,
-		handler: (ctx: PluginCommandContext) => void | Promise<void>,
-	) => PluginSubscription;
+		options: CommandOptions,
+		handler: (ctx: CommandContext) => void | Promise<void>,
+	) => Disposer;
 	registerTool: <TParameters extends TSchema, TDetails>(
-		tool: PluginToolDefinition<TParameters, TDetails>,
-	) => PluginSubscription;
-	addSystemPrompt: (text: string) => PluginSubscription;
-	addDebugSection: (key: string, lines: string[]) => PluginSubscription;
+		tool: ToolDefinition<TParameters, TDetails>,
+	) => Disposer;
+	onToolCall: (handler: ToolCallHandler) => Disposer;
+	addSystemPrompt: (text: string) => Disposer;
+	addDebugSection: (key: string, lines: string[]) => Disposer;
 }
 
-// biome-ignore lint/suspicious/noConfusingVoidType: plugin definitions may omit a return value or return a disposer.
-export type PluginDefinition = (kit: PluginAPI) => void | PluginDispose;
+export type Plugin = (
+	kit: PluginAPI,
+	// biome-ignore lint/suspicious/noConfusingVoidType: plugin definitions may omit a return value or return a disposer.
+) => void | Disposer;

package/dist/toasts.d.ts

@@ -3,7 +3,7 @@ export type ToastVariant = "error" | "warning" | "info";
 export type ToastInput = {
 	variant: ToastVariant;
 	title: string;
-	lines: string[];
+	subtitle?: string;
 	persistent?: boolean;
 };
 

package/docs/features/plugins.md

@@ -37,7 +37,7 @@ export default function MyPlugin(kit: PluginAPI) {
 		async (ctx) => {
 			ctx.ui.toast({
 				title: "Hello plugin",
-				lines: ["Loaded from a Kit plugin."],
+				subtitle: "Loaded from a Kit plugin.",
 				variant: "info",
 			});
 		},
@@ -45,7 +45,7 @@ export default function MyPlugin(kit: PluginAPI) {
 }
 ```
 
-Plugin functions may return a disposer for resources not registered through Kit:
+Plugin functions may return a `Disposer` for resources not registered through Kit:
 
 ```ts
 import type { PluginAPI } from "@akonwi/kit/plugin";
@@ -61,6 +61,64 @@ export default function WatchPlugin(kit: PluginAPI) {
 
 Registrations made through `kit` are cleaned up automatically on `/reload`.
 
+Common exported SDK types include `PluginAPI`, `Plugin`, `Disposer`, `CommandContext`, `CommandOptions`, `RuntimeEvent`, `EventContext`, `ToolDefinition`, `ToolResult`, `ToolCall`, and `ToolCallDecision`.
+
+## UI helpers
+
+`kit.ui.toast({ title, subtitle, variant })` remains the lightweight notification API. For small interactive flows, Kit also provides app-owned UI primitives:
+
+```ts
+const picked = await kit.ui.select({
+	title: "Choose target",
+	options: [
+		{ label: "Current file", value: "file", description: "Use the active context" },
+		{ label: "Whole project", value: "project" },
+	],
+	filterable: true,
+});
+
+const name = await kit.ui.input({
+	title: "Name this run",
+	placeholder: "experiment name",
+});
+
+const ok = await kit.ui.confirm({
+	title: "Continue?",
+	message: "This will submit a follow-up message.",
+	confirmLabel: "Continue",
+});
+```
+
+These helpers use Kit-owned dialogs and return `undefined` when selection/input is cancelled. `confirm` returns `false` for cancel/escape. The public plugin UI API is intentionally limited to `toast`, `select`, `input`, and `confirm` so Kit can keep ownership of rendering, focus, theme, and compatibility.
+
+## Tool approval hooks
+
+Plugins can register a callback that runs before a tool executes. Return `{ action: "allow" }` or no value to run the tool; return `{ action: "reject-and-continue", message }` to block it and let the agent continue.
+
+If multiple plugins register tool-call handlers, Kit evaluates them in registration order. `allow` does not short-circuit; the first rejection blocks the call.
+
+```ts
+kit.onToolCall(async (toolCall, ctx) => {
+	if (toolCall.name !== "bash") return { action: "allow" };
+	const command = toolCall.input.command;
+	if (typeof command !== "string" || !command.includes("rm")) {
+		return { action: "allow" };
+	}
+
+	const approved = await ctx.ui.confirm({
+		title: "Approve bash?",
+		message: command,
+		confirmLabel: "Allow",
+		cancelLabel: "Block",
+		defaultValue: false,
+	});
+
+	return approved
+		? { action: "allow" }
+		: { action: "reject-and-continue", message: "User denied bash." };
+});
+```
+
 ## Reloading
 
 Use `/reload` after editing plugin files. Kit re-discovers plugin files and reloads them with cache busting so changed `.ts` contents are picked up.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@akonwi/kit",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"author": "Akonwi Ngoh <akonwi@gmail.com>",
 	"description": "Standalone kit app with Pi-core compatibility and a custom terminal shell.",
 	"license": "MIT",