@ampcode/plugin 0.0.0-20260422002301-gff243b1 → 0.0.0-20260424002713-g01c9b5d

package/index.d.ts

@@ -57,7 +57,7 @@ declare module '@ampcode/plugin' {
 		 */
 		on<E extends keyof PluginEventMap>(
 			event: E,
-			handler: (event: PluginEventMap[E], ctx: PluginEventContext) => PluginHandlerResult<E>,
+			handler: (event: PluginEventMap[E], ctx: PluginEventContext<E>) => PluginHandlerResult<E>,
 		): Subscription
 
 		/**
@@ -338,8 +338,8 @@ declare module '@ampcode/plugin' {
 	 * Thread API for manipulating the current thread.
 	 */
 	export interface PluginThread {
-		/** Active thread ID when available in the current invocation context */
-		id?: ThreadID
+		/** Active thread ID for the current invocation context */
+		id: ThreadID
 
 		/**
 		 * Append a user message to the thread.
@@ -426,13 +426,9 @@ declare module '@ampcode/plugin' {
 	}
 
 	/**
-	 * Event payload for tool.call event.
-	 * This is a request that expects a response from the handler.
+	 * A tool call.
 	 */
-	export interface ToolCallEvent {
-		/** The active thread for this tool invocation, when available */
-		thread?: { id: ThreadID }
-
+	export interface ToolCall {
 		/** Unique identifier for this tool use (e.g., "toolu_xxx") */
 		toolUseID: string
 
@@ -443,6 +439,15 @@ declare module '@ampcode/plugin' {
 		input: Record<string, unknown>
 	}
 
+	/**
+	 * Event payload for tool.call event.
+	 * This is a request that expects a response from the handler.
+	 */
+	export interface ToolCallEvent extends ToolCall {
+		/** The active thread for this tool invocation */
+		thread: { id: ThreadID }
+	}
+
 	/**
 	 * Result returned from a tool.call handler.
 	 * Determines how the tool execution should proceed.
@@ -464,9 +469,9 @@ declare module '@ampcode/plugin' {
 		| { action: 'error'; message: string }
 
 	/**
-	 * Event payload for tool.result event.
+	 * A terminal tool result.
 	 */
-	export interface ToolResultEvent {
+	export interface ToolResult {
 		/** Unique identifier for this tool use (e.g., "toolu_xxx") */
 		toolUseID: string
 
@@ -486,6 +491,14 @@ declare module '@ampcode/plugin' {
 		output?: unknown
 	}
 
+	/**
+	 * Event payload for tool.result event.
+	 */
+	export interface ToolResultEvent extends ToolResult {
+		/** The active thread for this tool result */
+		thread: { id: ThreadID }
+	}
+
 	/**
 	 * Result returned from a tool.result handler.
 	 * Allows modifying the tool result before it is sent back to the model.
@@ -513,6 +526,9 @@ declare module '@ampcode/plugin' {
 	 * Fired when a user submits a prompt (initial or reply).
 	 */
 	export interface AgentStartEvent {
+		/** The active thread for this agent turn */
+		thread: { id: ThreadID }
+
 		/** The user's prompt message */
 		message: string
 
@@ -537,6 +553,9 @@ declare module '@ampcode/plugin' {
 	 * Fired when the agent finishes handling a user prompt.
 	 */
 	export interface AgentEndEvent {
+		/** The active thread for this agent turn */
+		thread: { id: ThreadID }
+
 		/** The user's prompt message that started this turn */
 		message: string
 
@@ -581,9 +600,9 @@ declare module '@ampcode/plugin' {
 	}
 
 	/**
-	 * Context passed as the second argument to event handlers.
+	 * Context shared by all plugin event handlers.
 	 */
-	export interface PluginEventContext {
+	export interface PluginEventContextBase {
 		/** Scoped logger for plugin output. Log messages are appended to the handler's trace span events. */
 		logger: PluginLogger
 
@@ -599,13 +618,17 @@ declare module '@ampcode/plugin' {
 		/** System capabilities */
 		system: PluginSystem
 
-		/** Thread manipulation API */
-		thread: PluginThread
-
 		/** The trace span ID for this handler invocation, if tracing is enabled */
 		span?: SpanID
 	}
 
+	/**
+	 * Context passed as the second argument to event handlers.
+	 * `session.start` may be emitted before a thread exists, while all other events are thread-scoped.
+	 */
+	export type PluginEventContext<E extends keyof PluginEventMap> = PluginEventContextBase &
+		(E extends 'session.start' ? { thread?: PluginThread } : { thread: PluginThread })
+
 	/**
 	 * Handler return type based on whether the event expects a response.
 	 * Request events (in PluginRequestResultMap) must return a result.
@@ -628,15 +651,15 @@ declare module '@ampcode/plugin' {
 	 * A tool call and its corresponding terminal tool result extracted from thread messages.
 	 */
 	export interface ToolCallWithResult {
-		call: ToolCallEvent
-		result: ToolResultEvent
+		call: ToolCall
+		result: ToolResult
 	}
 
 	/**
 	 * Extracts the shell command from a Bash or shell_command tool call.
 	 * Returns null if the event is not a shell command tool call.
 	 */
-	export type ShellCommandFromToolCall = (event: ToolCallEvent) => ShellCommand | null
+	export type ShellCommandFromToolCall = (event: ToolCall) => ShellCommand | null
 
 	/**
 	 * Extracts paired tool calls and terminal tool results from a list of thread messages.
@@ -647,7 +670,7 @@ declare module '@ampcode/plugin' {
 	 * Returns an array of file URIs modified by a tool call, or null if the tool doesn't modify files.
 	 * Supports edit/create/apply_patch tools and sed in-place shell commands.
 	 */
-	export type FilesModifiedByToolCall = (event: ToolCallEvent | ToolResultEvent) => URI[] | null
+	export type FilesModifiedByToolCall = (event: ToolCall | ToolResult) => URI[] | null
 
 	/**
 	 * Options for registering a command.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260422002301-gff243b1",
+	"version": "0.0.0-20260424002713-g01c9b5d",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/manual/plugin-api",
 	"author": {