mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-20 07:04:34 +00:00
Split HookContext and HookCommandContext to prevent deadlocks
HookContext (all events): - isIdle() - read-only state check - hasQueuedMessages() - read-only state check - abort() - fire-and-forget, does not wait HookCommandContext (slash commands only): - waitForIdle() - waits for agent to finish - newSession(options?) - create new session - branch(entryId) - branch from entry - navigateTree(targetId, options?) - navigate session tree Session control methods moved from HookAPI (pi.*) to HookCommandContext (ctx.*) because they can deadlock when called from event handlers that run inside the agent loop (tool_call, tool_result, context events).
This commit is contained in:
parent
ccdd7bd283
commit
0d9fddec1e
9 changed files with 170 additions and 203 deletions
|
|
@ -20,7 +20,7 @@ The hooks API has been restructured with more granular events and better session
|
||||||
|
|
||||||
**Type renames:**
|
**Type renames:**
|
||||||
- `HookEventContext` → `HookContext`
|
- `HookEventContext` → `HookContext`
|
||||||
- `HookCommandContext` removed (use `HookContext` for command handlers)
|
- `HookCommandContext` is now a new interface extending `HookContext` with session control methods
|
||||||
|
|
||||||
**Event changes:**
|
**Event changes:**
|
||||||
- The monolithic `session` event is now split into granular events: `session_start`, `session_before_switch`, `session_switch`, `session_before_branch`, `session_branch`, `session_before_compact`, `session_compact`, `session_shutdown`
|
- The monolithic `session` event is now split into granular events: `session_start`, `session_before_switch`, `session_switch`, `session_before_branch`, `session_branch`, `session_before_compact`, `session_compact`, `session_shutdown`
|
||||||
|
|
@ -33,12 +33,9 @@ The hooks API has been restructured with more granular events and better session
|
||||||
**API changes:**
|
**API changes:**
|
||||||
- `pi.send(text, attachments?)` → `pi.sendMessage(message, triggerTurn?)` (creates `CustomMessageEntry`)
|
- `pi.send(text, attachments?)` → `pi.sendMessage(message, triggerTurn?)` (creates `CustomMessageEntry`)
|
||||||
- New `pi.appendEntry(customType, data?)` for hook state persistence (not in LLM context)
|
- New `pi.appendEntry(customType, data?)` for hook state persistence (not in LLM context)
|
||||||
- New `pi.registerCommand(name, options)` for custom slash commands
|
- New `pi.registerCommand(name, options)` for custom slash commands (handler receives `HookCommandContext`)
|
||||||
- New `pi.registerMessageRenderer(customType, renderer)` for custom TUI rendering
|
- New `pi.registerMessageRenderer(customType, renderer)` for custom TUI rendering
|
||||||
- New `pi.newSession(options?)` to create new sessions with optional setup callback
|
- New `ctx.isIdle()`, `ctx.abort()`, `ctx.hasQueuedMessages()` for agent state (available in all events)
|
||||||
- New `pi.branch(entryId)` to branch from a specific entry
|
|
||||||
- New `pi.navigateTree(targetId, options?)` to navigate the session tree
|
|
||||||
- New `ctx.isIdle()`, `ctx.waitForIdle()`, `ctx.abort()`, `ctx.hasQueuedMessages()` for agent state access
|
|
||||||
- New `ctx.ui.custom(component)` for full TUI component rendering with keyboard focus
|
- New `ctx.ui.custom(component)` for full TUI component rendering with keyboard focus
|
||||||
- New `ctx.ui.setStatus(key, text)` for persistent status text in footer (multiple hooks can set their own)
|
- New `ctx.ui.setStatus(key, text)` for persistent status text in footer (multiple hooks can set their own)
|
||||||
- New `ctx.ui.theme` getter for styling text with theme colors
|
- New `ctx.ui.theme` getter for styling text with theme colors
|
||||||
|
|
@ -46,6 +43,14 @@ The hooks API has been restructured with more granular events and better session
|
||||||
- `ctx.sessionFile` → `ctx.sessionManager.getSessionFile()`
|
- `ctx.sessionFile` → `ctx.sessionManager.getSessionFile()`
|
||||||
- New `ctx.modelRegistry` and `ctx.model` for API key resolution
|
- New `ctx.modelRegistry` and `ctx.model` for API key resolution
|
||||||
|
|
||||||
|
**HookCommandContext (slash commands only):**
|
||||||
|
- `ctx.waitForIdle()` - wait for agent to finish streaming
|
||||||
|
- `ctx.newSession(options?)` - create new sessions with optional setup callback
|
||||||
|
- `ctx.branch(entryId)` - branch from a specific entry
|
||||||
|
- `ctx.navigateTree(targetId, options?)` - navigate the session tree
|
||||||
|
|
||||||
|
These methods are only on `HookCommandContext` (not `HookContext`) because they can deadlock if called from event handlers that run inside the agent loop.
|
||||||
|
|
||||||
**Removed:**
|
**Removed:**
|
||||||
- `hookTimeout` setting (hooks no longer have timeouts; use Ctrl+C to abort)
|
- `hookTimeout` setting (hooks no longer have timeouts; use Ctrl+C to abort)
|
||||||
- `resolveApiKey` parameter (use `ctx.modelRegistry.getApiKey(model)`)
|
- `resolveApiKey` parameter (use `ctx.modelRegistry.getApiKey(model)`)
|
||||||
|
|
|
||||||
|
|
@ -542,7 +542,7 @@ if (ctx.model) {
|
||||||
|
|
||||||
### ctx.isIdle()
|
### ctx.isIdle()
|
||||||
|
|
||||||
Returns `true` if the agent is not currently streaming. Useful for hooks that need to wait or check state:
|
Returns `true` if the agent is not currently streaming:
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
if (ctx.isIdle()) {
|
if (ctx.isIdle()) {
|
||||||
|
|
@ -550,18 +550,9 @@ if (ctx.isIdle()) {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### ctx.waitForIdle()
|
|
||||||
|
|
||||||
Wait for the agent to finish streaming:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
await ctx.waitForIdle();
|
|
||||||
// Agent is now idle
|
|
||||||
```
|
|
||||||
|
|
||||||
### ctx.abort()
|
### ctx.abort()
|
||||||
|
|
||||||
Abort the current agent operation:
|
Abort the current agent operation (fire-and-forget, does not wait):
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
await ctx.abort();
|
await ctx.abort();
|
||||||
|
|
@ -578,6 +569,62 @@ if (ctx.hasQueuedMessages()) {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## HookCommandContext (Slash Commands Only)
|
||||||
|
|
||||||
|
Slash command handlers receive `HookCommandContext`, which extends `HookContext` with session control methods. These methods are only safe in user-initiated commands because they can cause deadlocks if called from event handlers (which run inside the agent loop).
|
||||||
|
|
||||||
|
### ctx.waitForIdle()
|
||||||
|
|
||||||
|
Wait for the agent to finish streaming:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await ctx.waitForIdle();
|
||||||
|
// Agent is now idle
|
||||||
|
```
|
||||||
|
|
||||||
|
### ctx.newSession(options?)
|
||||||
|
|
||||||
|
Create a new session, optionally with initialization:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const result = await ctx.newSession({
|
||||||
|
parentSession: ctx.sessionManager.getSessionFile(), // Track lineage
|
||||||
|
setup: async (sm) => {
|
||||||
|
// Initialize the new session
|
||||||
|
sm.appendMessage({
|
||||||
|
role: "user",
|
||||||
|
content: [{ type: "text", text: "Context from previous session..." }],
|
||||||
|
timestamp: Date.now(),
|
||||||
|
});
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
if (result.cancelled) {
|
||||||
|
// A hook cancelled the new session
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ctx.branch(entryId)
|
||||||
|
|
||||||
|
Branch from a specific entry, creating a new session file:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const result = await ctx.branch("entry-id-123");
|
||||||
|
if (!result.cancelled) {
|
||||||
|
// Now in the branched session
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ctx.navigateTree(targetId, options?)
|
||||||
|
|
||||||
|
Navigate to a different point in the session tree:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const result = await ctx.navigateTree("entry-id-456", {
|
||||||
|
summarize: true, // Summarize the abandoned branch
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
## HookAPI Methods
|
## HookAPI Methods
|
||||||
|
|
||||||
### pi.on(event, handler)
|
### pi.on(event, handler)
|
||||||
|
|
@ -693,47 +740,6 @@ const result = await pi.exec("git", ["status"], {
|
||||||
// result.stdout, result.stderr, result.code, result.killed
|
// result.stdout, result.stderr, result.code, result.killed
|
||||||
```
|
```
|
||||||
|
|
||||||
### pi.newSession(options?)
|
|
||||||
|
|
||||||
Start a new session, optionally with a setup callback to initialize it:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
await pi.newSession({
|
|
||||||
parentSession: ctx.sessionManager.getSessionFile(), // Track lineage
|
|
||||||
setup: async (sessionManager) => {
|
|
||||||
// sessionManager is writable, can append messages
|
|
||||||
sessionManager.appendMessage({
|
|
||||||
role: "user",
|
|
||||||
content: [{ type: "text", text: "Context from previous session..." }]
|
|
||||||
});
|
|
||||||
}
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
Returns `{ cancelled: boolean }` - cancelled if a `session_before_switch` hook cancelled.
|
|
||||||
|
|
||||||
### pi.branch(entryId)
|
|
||||||
|
|
||||||
Branch from a specific entry, creating a new session file:
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
const result = await pi.branch(entryId);
|
|
||||||
if (!result.cancelled) {
|
|
||||||
// Branched successfully
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### pi.navigateTree(targetId, options?)
|
|
||||||
|
|
||||||
Navigate to a different point in the session tree (in-place):
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
const result = await pi.navigateTree(targetId, { summarize: true });
|
|
||||||
if (!result.cancelled) {
|
|
||||||
// Navigated successfully
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
### Permission Gate
|
### Permission Gate
|
||||||
|
|
|
||||||
|
|
@ -30,7 +30,6 @@ import {
|
||||||
import type { CustomToolContext, CustomToolSessionEvent, LoadedCustomTool } from "./custom-tools/index.js";
|
import type { CustomToolContext, CustomToolSessionEvent, LoadedCustomTool } from "./custom-tools/index.js";
|
||||||
import { exportSessionToHtml } from "./export-html/index.js";
|
import { exportSessionToHtml } from "./export-html/index.js";
|
||||||
import type {
|
import type {
|
||||||
HookContext,
|
|
||||||
HookRunner,
|
HookRunner,
|
||||||
SessionBeforeBranchResult,
|
SessionBeforeBranchResult,
|
||||||
SessionBeforeCompactResult,
|
SessionBeforeCompactResult,
|
||||||
|
|
@ -545,24 +544,8 @@ export class AgentSession {
|
||||||
const command = this._hookRunner.getCommand(commandName);
|
const command = this._hookRunner.getCommand(commandName);
|
||||||
if (!command) return false;
|
if (!command) return false;
|
||||||
|
|
||||||
// Get UI context from hook runner (set by mode)
|
// Get command context from hook runner (includes session control methods)
|
||||||
const uiContext = this._hookRunner.getUIContext();
|
const ctx = this._hookRunner.createCommandContext();
|
||||||
if (!uiContext) return false;
|
|
||||||
|
|
||||||
// Build command context
|
|
||||||
const cwd = process.cwd();
|
|
||||||
const ctx: HookContext = {
|
|
||||||
ui: uiContext,
|
|
||||||
hasUI: this._hookRunner.getHasUI(),
|
|
||||||
cwd,
|
|
||||||
sessionManager: this.sessionManager,
|
|
||||||
modelRegistry: this._modelRegistry,
|
|
||||||
model: this.model,
|
|
||||||
isIdle: () => !this.isStreaming,
|
|
||||||
waitForIdle: () => this.agent.waitForIdle(),
|
|
||||||
abort: () => this.abort(),
|
|
||||||
hasQueuedMessages: () => this.queuedMessageCount > 0,
|
|
||||||
};
|
|
||||||
|
|
||||||
try {
|
try {
|
||||||
await command.handler(args, ctx);
|
await command.handler(args, ctx);
|
||||||
|
|
|
||||||
|
|
@ -3,8 +3,11 @@ export {
|
||||||
discoverAndLoadHooks,
|
discoverAndLoadHooks,
|
||||||
loadHooks,
|
loadHooks,
|
||||||
type AppendEntryHandler,
|
type AppendEntryHandler,
|
||||||
|
type BranchHandler,
|
||||||
type LoadedHook,
|
type LoadedHook,
|
||||||
type LoadHooksResult,
|
type LoadHooksResult,
|
||||||
|
type NavigateTreeHandler,
|
||||||
|
type NewSessionHandler,
|
||||||
type SendMessageHandler,
|
type SendMessageHandler,
|
||||||
} from "./loader.js";
|
} from "./loader.js";
|
||||||
export { execCommand, HookRunner, type HookErrorListener } from "./runner.js";
|
export { execCommand, HookRunner, type HookErrorListener } from "./runner.js";
|
||||||
|
|
|
||||||
|
|
@ -62,7 +62,7 @@ export type SendMessageHandler = <T = unknown>(
|
||||||
export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
|
export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* New session handler type for pi.newSession().
|
* New session handler type for ctx.newSession() in HookCommandContext.
|
||||||
*/
|
*/
|
||||||
export type NewSessionHandler = (options?: {
|
export type NewSessionHandler = (options?: {
|
||||||
parentSession?: string;
|
parentSession?: string;
|
||||||
|
|
@ -70,12 +70,12 @@ export type NewSessionHandler = (options?: {
|
||||||
}) => Promise<{ cancelled: boolean }>;
|
}) => Promise<{ cancelled: boolean }>;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Branch handler type for pi.branch().
|
* Branch handler type for ctx.branch() in HookCommandContext.
|
||||||
*/
|
*/
|
||||||
export type BranchHandler = (entryId: string) => Promise<{ cancelled: boolean }>;
|
export type BranchHandler = (entryId: string) => Promise<{ cancelled: boolean }>;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Navigate tree handler type for pi.navigateTree().
|
* Navigate tree handler type for ctx.navigateTree() in HookCommandContext.
|
||||||
*/
|
*/
|
||||||
export type NavigateTreeHandler = (
|
export type NavigateTreeHandler = (
|
||||||
targetId: string,
|
targetId: string,
|
||||||
|
|
@ -100,12 +100,6 @@ export interface LoadedHook {
|
||||||
setSendMessageHandler: (handler: SendMessageHandler) => void;
|
setSendMessageHandler: (handler: SendMessageHandler) => void;
|
||||||
/** Set the append entry handler for this hook's pi.appendEntry() */
|
/** Set the append entry handler for this hook's pi.appendEntry() */
|
||||||
setAppendEntryHandler: (handler: AppendEntryHandler) => void;
|
setAppendEntryHandler: (handler: AppendEntryHandler) => void;
|
||||||
/** Set the new session handler for this hook's pi.newSession() */
|
|
||||||
setNewSessionHandler: (handler: NewSessionHandler) => void;
|
|
||||||
/** Set the branch handler for this hook's pi.branch() */
|
|
||||||
setBranchHandler: (handler: BranchHandler) => void;
|
|
||||||
/** Set the navigate tree handler for this hook's pi.navigateTree() */
|
|
||||||
setNavigateTreeHandler: (handler: NavigateTreeHandler) => void;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
@ -165,9 +159,6 @@ function createHookAPI(
|
||||||
commands: Map<string, RegisteredCommand>;
|
commands: Map<string, RegisteredCommand>;
|
||||||
setSendMessageHandler: (handler: SendMessageHandler) => void;
|
setSendMessageHandler: (handler: SendMessageHandler) => void;
|
||||||
setAppendEntryHandler: (handler: AppendEntryHandler) => void;
|
setAppendEntryHandler: (handler: AppendEntryHandler) => void;
|
||||||
setNewSessionHandler: (handler: NewSessionHandler) => void;
|
|
||||||
setBranchHandler: (handler: BranchHandler) => void;
|
|
||||||
setNavigateTreeHandler: (handler: NavigateTreeHandler) => void;
|
|
||||||
} {
|
} {
|
||||||
let sendMessageHandler: SendMessageHandler = () => {
|
let sendMessageHandler: SendMessageHandler = () => {
|
||||||
// Default no-op until mode sets the handler
|
// Default no-op until mode sets the handler
|
||||||
|
|
@ -175,18 +166,6 @@ function createHookAPI(
|
||||||
let appendEntryHandler: AppendEntryHandler = () => {
|
let appendEntryHandler: AppendEntryHandler = () => {
|
||||||
// Default no-op until mode sets the handler
|
// Default no-op until mode sets the handler
|
||||||
};
|
};
|
||||||
let newSessionHandler: NewSessionHandler = async () => {
|
|
||||||
// Default no-op until mode sets the handler
|
|
||||||
return { cancelled: false };
|
|
||||||
};
|
|
||||||
let branchHandler: BranchHandler = async () => {
|
|
||||||
// Default no-op until mode sets the handler
|
|
||||||
return { cancelled: false };
|
|
||||||
};
|
|
||||||
let navigateTreeHandler: NavigateTreeHandler = async () => {
|
|
||||||
// Default no-op until mode sets the handler
|
|
||||||
return { cancelled: false };
|
|
||||||
};
|
|
||||||
const messageRenderers = new Map<string, HookMessageRenderer>();
|
const messageRenderers = new Map<string, HookMessageRenderer>();
|
||||||
const commands = new Map<string, RegisteredCommand>();
|
const commands = new Map<string, RegisteredCommand>();
|
||||||
|
|
||||||
|
|
@ -213,15 +192,6 @@ function createHookAPI(
|
||||||
exec(command: string, args: string[], options?: ExecOptions) {
|
exec(command: string, args: string[], options?: ExecOptions) {
|
||||||
return execCommand(command, args, options?.cwd ?? cwd, options);
|
return execCommand(command, args, options?.cwd ?? cwd, options);
|
||||||
},
|
},
|
||||||
newSession(options) {
|
|
||||||
return newSessionHandler(options);
|
|
||||||
},
|
|
||||||
branch(entryId) {
|
|
||||||
return branchHandler(entryId);
|
|
||||||
},
|
|
||||||
navigateTree(targetId, options) {
|
|
||||||
return navigateTreeHandler(targetId, options);
|
|
||||||
},
|
|
||||||
} as HookAPI;
|
} as HookAPI;
|
||||||
|
|
||||||
return {
|
return {
|
||||||
|
|
@ -234,15 +204,6 @@ function createHookAPI(
|
||||||
setAppendEntryHandler: (handler: AppendEntryHandler) => {
|
setAppendEntryHandler: (handler: AppendEntryHandler) => {
|
||||||
appendEntryHandler = handler;
|
appendEntryHandler = handler;
|
||||||
},
|
},
|
||||||
setNewSessionHandler: (handler: NewSessionHandler) => {
|
|
||||||
newSessionHandler = handler;
|
|
||||||
},
|
|
||||||
setBranchHandler: (handler: BranchHandler) => {
|
|
||||||
branchHandler = handler;
|
|
||||||
},
|
|
||||||
setNavigateTreeHandler: (handler: NavigateTreeHandler) => {
|
|
||||||
navigateTreeHandler = handler;
|
|
||||||
},
|
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
@ -270,16 +231,10 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
|
||||||
|
|
||||||
// Create handlers map and API
|
// Create handlers map and API
|
||||||
const handlers = new Map<string, HandlerFn[]>();
|
const handlers = new Map<string, HandlerFn[]>();
|
||||||
const {
|
const { api, messageRenderers, commands, setSendMessageHandler, setAppendEntryHandler } = createHookAPI(
|
||||||
api,
|
handlers,
|
||||||
messageRenderers,
|
cwd,
|
||||||
commands,
|
);
|
||||||
setSendMessageHandler,
|
|
||||||
setAppendEntryHandler,
|
|
||||||
setNewSessionHandler,
|
|
||||||
setBranchHandler,
|
|
||||||
setNavigateTreeHandler,
|
|
||||||
} = createHookAPI(handlers, cwd);
|
|
||||||
|
|
||||||
// Call factory to register handlers
|
// Call factory to register handlers
|
||||||
factory(api);
|
factory(api);
|
||||||
|
|
@ -293,9 +248,6 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
|
||||||
commands,
|
commands,
|
||||||
setSendMessageHandler,
|
setSendMessageHandler,
|
||||||
setAppendEntryHandler,
|
setAppendEntryHandler,
|
||||||
setNewSessionHandler,
|
|
||||||
setBranchHandler,
|
|
||||||
setNavigateTreeHandler,
|
|
||||||
},
|
},
|
||||||
error: null,
|
error: null,
|
||||||
};
|
};
|
||||||
|
|
|
||||||
|
|
@ -20,6 +20,7 @@ import type {
|
||||||
BeforeAgentStartEventResult,
|
BeforeAgentStartEventResult,
|
||||||
ContextEvent,
|
ContextEvent,
|
||||||
ContextEventResult,
|
ContextEventResult,
|
||||||
|
HookCommandContext,
|
||||||
HookContext,
|
HookContext,
|
||||||
HookError,
|
HookError,
|
||||||
HookEvent,
|
HookEvent,
|
||||||
|
|
@ -72,6 +73,9 @@ export class HookRunner {
|
||||||
private waitForIdleFn: () => Promise<void> = async () => {};
|
private waitForIdleFn: () => Promise<void> = async () => {};
|
||||||
private abortFn: () => Promise<void> = async () => {};
|
private abortFn: () => Promise<void> = async () => {};
|
||||||
private hasQueuedMessagesFn: () => boolean = () => false;
|
private hasQueuedMessagesFn: () => boolean = () => false;
|
||||||
|
private newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
|
||||||
|
private branchHandler: BranchHandler = async () => ({ cancelled: false });
|
||||||
|
private navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
|
||||||
|
|
||||||
constructor(hooks: LoadedHook[], cwd: string, sessionManager: SessionManager, modelRegistry: ModelRegistry) {
|
constructor(hooks: LoadedHook[], cwd: string, sessionManager: SessionManager, modelRegistry: ModelRegistry) {
|
||||||
this.hooks = hooks;
|
this.hooks = hooks;
|
||||||
|
|
@ -93,11 +97,11 @@ export class HookRunner {
|
||||||
sendMessageHandler: SendMessageHandler;
|
sendMessageHandler: SendMessageHandler;
|
||||||
/** Handler for hooks to append entries */
|
/** Handler for hooks to append entries */
|
||||||
appendEntryHandler: AppendEntryHandler;
|
appendEntryHandler: AppendEntryHandler;
|
||||||
/** Handler for hooks to create new sessions */
|
/** Handler for creating new sessions (for HookCommandContext) */
|
||||||
newSessionHandler?: NewSessionHandler;
|
newSessionHandler?: NewSessionHandler;
|
||||||
/** Handler for hooks to branch sessions */
|
/** Handler for branching sessions (for HookCommandContext) */
|
||||||
branchHandler?: BranchHandler;
|
branchHandler?: BranchHandler;
|
||||||
/** Handler for hooks to navigate the session tree */
|
/** Handler for navigating session tree (for HookCommandContext) */
|
||||||
navigateTreeHandler?: NavigateTreeHandler;
|
navigateTreeHandler?: NavigateTreeHandler;
|
||||||
/** Function to check if agent is idle */
|
/** Function to check if agent is idle */
|
||||||
isIdle?: () => boolean;
|
isIdle?: () => boolean;
|
||||||
|
|
@ -117,18 +121,20 @@ export class HookRunner {
|
||||||
this.waitForIdleFn = options.waitForIdle ?? (async () => {});
|
this.waitForIdleFn = options.waitForIdle ?? (async () => {});
|
||||||
this.abortFn = options.abort ?? (async () => {});
|
this.abortFn = options.abort ?? (async () => {});
|
||||||
this.hasQueuedMessagesFn = options.hasQueuedMessages ?? (() => false);
|
this.hasQueuedMessagesFn = options.hasQueuedMessages ?? (() => false);
|
||||||
|
// Store session handlers for HookCommandContext
|
||||||
|
if (options.newSessionHandler) {
|
||||||
|
this.newSessionHandler = options.newSessionHandler;
|
||||||
|
}
|
||||||
|
if (options.branchHandler) {
|
||||||
|
this.branchHandler = options.branchHandler;
|
||||||
|
}
|
||||||
|
if (options.navigateTreeHandler) {
|
||||||
|
this.navigateTreeHandler = options.navigateTreeHandler;
|
||||||
|
}
|
||||||
|
// Set per-hook handlers for pi.sendMessage() and pi.appendEntry()
|
||||||
for (const hook of this.hooks) {
|
for (const hook of this.hooks) {
|
||||||
hook.setSendMessageHandler(options.sendMessageHandler);
|
hook.setSendMessageHandler(options.sendMessageHandler);
|
||||||
hook.setAppendEntryHandler(options.appendEntryHandler);
|
hook.setAppendEntryHandler(options.appendEntryHandler);
|
||||||
if (options.newSessionHandler) {
|
|
||||||
hook.setNewSessionHandler(options.newSessionHandler);
|
|
||||||
}
|
|
||||||
if (options.branchHandler) {
|
|
||||||
hook.setBranchHandler(options.branchHandler);
|
|
||||||
}
|
|
||||||
if (options.navigateTreeHandler) {
|
|
||||||
hook.setNavigateTreeHandler(options.navigateTreeHandler);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
this.uiContext = options.uiContext ?? noOpUIContext;
|
this.uiContext = options.uiContext ?? noOpUIContext;
|
||||||
this.hasUI = options.hasUI ?? false;
|
this.hasUI = options.hasUI ?? false;
|
||||||
|
|
@ -242,12 +248,25 @@ export class HookRunner {
|
||||||
modelRegistry: this.modelRegistry,
|
modelRegistry: this.modelRegistry,
|
||||||
model: this.getModel(),
|
model: this.getModel(),
|
||||||
isIdle: () => this.isIdleFn(),
|
isIdle: () => this.isIdleFn(),
|
||||||
waitForIdle: () => this.waitForIdleFn(),
|
|
||||||
abort: () => this.abortFn(),
|
abort: () => this.abortFn(),
|
||||||
hasQueuedMessages: () => this.hasQueuedMessagesFn(),
|
hasQueuedMessages: () => this.hasQueuedMessagesFn(),
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Create the command context for slash command handlers.
|
||||||
|
* Extends HookContext with session control methods that are only safe in commands.
|
||||||
|
*/
|
||||||
|
createCommandContext(): HookCommandContext {
|
||||||
|
return {
|
||||||
|
...this.createContext(),
|
||||||
|
waitForIdle: () => this.waitForIdleFn(),
|
||||||
|
newSession: (options) => this.newSessionHandler(options),
|
||||||
|
branch: (entryId) => this.branchHandler(entryId),
|
||||||
|
navigateTree: (targetId, options) => this.navigateTreeHandler(targetId, options),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Check if event type is a session "before_*" event that can be cancelled.
|
* Check if event type is a session "before_*" event that can be cancelled.
|
||||||
*/
|
*/
|
||||||
|
|
|
||||||
|
|
@ -131,7 +131,8 @@ export interface HookUIContext {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Context passed to hook event and command handlers.
|
* Context passed to hook event handlers.
|
||||||
|
* For command handlers, see HookCommandContext which extends this with session control methods.
|
||||||
*/
|
*/
|
||||||
export interface HookContext {
|
export interface HookContext {
|
||||||
/** UI methods for user interaction */
|
/** UI methods for user interaction */
|
||||||
|
|
@ -148,14 +149,63 @@ export interface HookContext {
|
||||||
model: Model<any> | undefined;
|
model: Model<any> | undefined;
|
||||||
/** Whether the agent is idle (not streaming) */
|
/** Whether the agent is idle (not streaming) */
|
||||||
isIdle(): boolean;
|
isIdle(): boolean;
|
||||||
/** Wait for the agent to finish streaming */
|
/** Abort the current agent operation (fire-and-forget, does not wait) */
|
||||||
waitForIdle(): Promise<void>;
|
|
||||||
/** Abort the current agent operation */
|
|
||||||
abort(): Promise<void>;
|
abort(): Promise<void>;
|
||||||
/** Whether there are queued messages waiting to be processed */
|
/** Whether there are queued messages waiting to be processed */
|
||||||
hasQueuedMessages(): boolean;
|
hasQueuedMessages(): boolean;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Extended context for slash command handlers.
|
||||||
|
* Includes session control methods that are only safe in user-initiated commands.
|
||||||
|
*
|
||||||
|
* These methods are not available in event handlers because they can cause
|
||||||
|
* deadlocks when called from within the agent loop (e.g., tool_call, context events).
|
||||||
|
*/
|
||||||
|
export interface HookCommandContext extends HookContext {
|
||||||
|
/** Wait for the agent to finish streaming */
|
||||||
|
waitForIdle(): Promise<void>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Start a new session, optionally with a setup callback to initialize it.
|
||||||
|
* The setup callback receives a writable SessionManager for the new session.
|
||||||
|
*
|
||||||
|
* @param options.parentSession - Path to parent session for lineage tracking
|
||||||
|
* @param options.setup - Async callback to initialize the new session (e.g., append messages)
|
||||||
|
* @returns Object with `cancelled: true` if a hook cancelled the new session
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* // Handoff: summarize current session and start fresh with context
|
||||||
|
* await ctx.newSession({
|
||||||
|
* parentSession: ctx.sessionManager.getSessionFile(),
|
||||||
|
* setup: async (sm) => {
|
||||||
|
* sm.appendMessage({ role: "user", content: [{ type: "text", text: summary }] });
|
||||||
|
* }
|
||||||
|
* });
|
||||||
|
*/
|
||||||
|
newSession(options?: {
|
||||||
|
parentSession?: string;
|
||||||
|
setup?: (sessionManager: SessionManager) => Promise<void>;
|
||||||
|
}): Promise<{ cancelled: boolean }>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Branch from a specific entry, creating a new session file.
|
||||||
|
*
|
||||||
|
* @param entryId - ID of the entry to branch from
|
||||||
|
* @returns Object with `cancelled: true` if a hook cancelled the branch
|
||||||
|
*/
|
||||||
|
branch(entryId: string): Promise<{ cancelled: boolean }>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Navigate to a different point in the session tree (in-place).
|
||||||
|
*
|
||||||
|
* @param targetId - ID of the entry to navigate to
|
||||||
|
* @param options.summarize - Whether to summarize the abandoned branch
|
||||||
|
* @returns Object with `cancelled: true` if a hook cancelled the navigation
|
||||||
|
*/
|
||||||
|
navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ cancelled: boolean }>;
|
||||||
|
}
|
||||||
|
|
||||||
// ============================================================================
|
// ============================================================================
|
||||||
// Session Events
|
// Session Events
|
||||||
// ============================================================================
|
// ============================================================================
|
||||||
|
|
@ -588,7 +638,7 @@ export interface RegisteredCommand {
|
||||||
name: string;
|
name: string;
|
||||||
description?: string;
|
description?: string;
|
||||||
|
|
||||||
handler: (args: string, ctx: HookContext) => Promise<void>;
|
handler: (args: string, ctx: HookCommandContext) => Promise<void>;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
@ -678,7 +728,7 @@ export interface HookAPI {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Register a custom slash command.
|
* Register a custom slash command.
|
||||||
* Handler receives HookCommandContext.
|
* Handler receives HookCommandContext with session control methods.
|
||||||
*/
|
*/
|
||||||
registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void;
|
registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void;
|
||||||
|
|
||||||
|
|
@ -687,45 +737,6 @@ export interface HookAPI {
|
||||||
* Supports timeout and abort signal.
|
* Supports timeout and abort signal.
|
||||||
*/
|
*/
|
||||||
exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
|
exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
|
||||||
|
|
||||||
/**
|
|
||||||
* Start a new session, optionally with a setup callback to initialize it.
|
|
||||||
* The setup callback receives a writable SessionManager for the new session.
|
|
||||||
*
|
|
||||||
* @param options.parentSession - Path to parent session for lineage tracking
|
|
||||||
* @param options.setup - Async callback to initialize the new session (e.g., append messages)
|
|
||||||
* @returns Object with `cancelled: true` if a hook cancelled the new session
|
|
||||||
*
|
|
||||||
* @example
|
|
||||||
* // Handoff: summarize current session and start fresh with context
|
|
||||||
* await pi.newSession({
|
|
||||||
* parentSession: ctx.sessionManager.getSessionFile(),
|
|
||||||
* setup: async (sm) => {
|
|
||||||
* sm.appendMessage({ role: "user", content: [{ type: "text", text: summary }] });
|
|
||||||
* }
|
|
||||||
* });
|
|
||||||
*/
|
|
||||||
newSession(options?: {
|
|
||||||
parentSession?: string;
|
|
||||||
setup?: (sessionManager: SessionManager) => Promise<void>;
|
|
||||||
}): Promise<{ cancelled: boolean }>;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Branch from a specific entry, creating a new session file.
|
|
||||||
*
|
|
||||||
* @param entryId - ID of the entry to branch from
|
|
||||||
* @returns Object with `cancelled: true` if a hook cancelled the branch
|
|
||||||
*/
|
|
||||||
branch(entryId: string): Promise<{ cancelled: boolean }>;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Navigate to a different point in the session tree (in-place).
|
|
||||||
*
|
|
||||||
* @param targetId - ID of the entry to navigate to
|
|
||||||
* @param options.summarize - Whether to summarize the abandoned branch
|
|
||||||
* @returns Object with `cancelled: true` if a hook cancelled the navigation
|
|
||||||
*/
|
|
||||||
navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ cancelled: boolean }>;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
||||||
|
|
@ -140,7 +140,7 @@ export interface CreateAgentSessionResult {
|
||||||
// Re-exports
|
// Re-exports
|
||||||
|
|
||||||
export type { CustomTool } from "./custom-tools/types.js";
|
export type { CustomTool } from "./custom-tools/types.js";
|
||||||
export type { HookAPI, HookContext, HookFactory } from "./hooks/types.js";
|
export type { HookAPI, HookCommandContext, HookContext, HookFactory } from "./hooks/types.js";
|
||||||
export type { Settings, SkillsSettings } from "./settings-manager.js";
|
export type { Settings, SkillsSettings } from "./settings-manager.js";
|
||||||
export type { Skill } from "./skills.js";
|
export type { Skill } from "./skills.js";
|
||||||
export type { FileSlashCommand } from "./slash-commands.js";
|
export type { FileSlashCommand } from "./slash-commands.js";
|
||||||
|
|
|
||||||
|
|
@ -80,9 +80,6 @@ describe.skipIf(!API_KEY)("Compaction hooks", () => {
|
||||||
commands: new Map(),
|
commands: new Map(),
|
||||||
setSendMessageHandler: () => {},
|
setSendMessageHandler: () => {},
|
||||||
setAppendEntryHandler: () => {},
|
setAppendEntryHandler: () => {},
|
||||||
setNewSessionHandler: () => {},
|
|
||||||
setBranchHandler: () => {},
|
|
||||||
setNavigateTreeHandler: () => {},
|
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
@ -269,9 +266,6 @@ describe.skipIf(!API_KEY)("Compaction hooks", () => {
|
||||||
commands: new Map(),
|
commands: new Map(),
|
||||||
setSendMessageHandler: () => {},
|
setSendMessageHandler: () => {},
|
||||||
setAppendEntryHandler: () => {},
|
setAppendEntryHandler: () => {},
|
||||||
setNewSessionHandler: () => {},
|
|
||||||
setBranchHandler: () => {},
|
|
||||||
setNavigateTreeHandler: () => {},
|
|
||||||
};
|
};
|
||||||
|
|
||||||
createSession([throwingHook]);
|
createSession([throwingHook]);
|
||||||
|
|
@ -319,9 +313,6 @@ describe.skipIf(!API_KEY)("Compaction hooks", () => {
|
||||||
commands: new Map(),
|
commands: new Map(),
|
||||||
setSendMessageHandler: () => {},
|
setSendMessageHandler: () => {},
|
||||||
setAppendEntryHandler: () => {},
|
setAppendEntryHandler: () => {},
|
||||||
setNewSessionHandler: () => {},
|
|
||||||
setBranchHandler: () => {},
|
|
||||||
setNavigateTreeHandler: () => {},
|
|
||||||
};
|
};
|
||||||
|
|
||||||
const hook2: LoadedHook = {
|
const hook2: LoadedHook = {
|
||||||
|
|
@ -351,9 +342,6 @@ describe.skipIf(!API_KEY)("Compaction hooks", () => {
|
||||||
commands: new Map(),
|
commands: new Map(),
|
||||||
setSendMessageHandler: () => {},
|
setSendMessageHandler: () => {},
|
||||||
setAppendEntryHandler: () => {},
|
setAppendEntryHandler: () => {},
|
||||||
setNewSessionHandler: () => {},
|
|
||||||
setBranchHandler: () => {},
|
|
||||||
setNavigateTreeHandler: () => {},
|
|
||||||
};
|
};
|
||||||
|
|
||||||
createSession([hook1, hook2]);
|
createSession([hook1, hook2]);
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue