goatchain 0.0.24 → 0.0.26

package/dist/agent/hooks/types.d.ts

@@ -1,23 +1,110 @@
+import type { ModelStopReason } from '../../model/types';
 import type { ToolExecutionContext } from '../../tool';
-import type { ToolCall } from '../../types';
-export interface HookContext {
+import type { Message, MessageContent, ToolCall, Usage } from '../../types';
+export interface BaseHookContext {
     sessionId: string;
+}
+/**
+ * Context for tool-level hooks (PermissionRequest, PreToolUse, PostToolUse, PostToolUseFailure).
+ * Also exported as `HookContext` for backward compatibility.
+ */
+export interface ToolHookContext extends BaseHookContext {
     toolCall: ToolCall;
     toolContext: ToolExecutionContext;
 }
-export interface PreToolUseResult {
+/** @deprecated Use `ToolHookContext` instead. Kept for backward compatibility. */
+export type HookContext = ToolHookContext;
+export interface SessionStartContext extends BaseHookContext {
+    /** Whether this run starts from a new session or a resumed state/checkpoint. */
+    startReason: 'new' | 'resume';
+    /** Existing conversation messages at the time session start fires (excludes system prompt). */
+    messages: Message[];
+}
+export interface StopContext extends BaseHookContext {
+    stopReason: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'approval_required' | 'max_follow_ups';
     /**
-     * If true, allows the tool to execute and skips the approval flow.
+     * Stop reason reported by the latest model response, when available.
+     * Useful for distinguishing `tool_call` vs `final` in per-LLM stop hooks.
+     */
+    modelStopReason?: ModelStopReason;
+    finalResponse?: string;
+    usage: Usage;
+    error?: {
+        code?: string;
+        message: string;
+    };
+    /** Full conversation messages at the time of stop (excludes system prompt). */
+    messages: Message[];
+}
+export interface SubagentStopContext extends BaseHookContext {
+    subagentId: string;
+    subagentType: string;
+    result?: unknown;
+    error?: Error;
+    durationMs: number;
+    usage?: Usage;
+    /** Full conversation messages from the subagent's session (excludes system prompt). */
+    messages: Message[];
+}
+export interface SubagentStartContext extends BaseHookContext {
+    subagentId: string;
+    subagentType: string;
+    taskDescription?: string;
+    prompt: string;
+}
+export interface UserPromptSubmitContext extends BaseHookContext {
+    input: MessageContent;
+}
+export interface SessionEndContext extends BaseHookContext {
+    stopReason: StopContext['stopReason'];
+    finalResponse?: string;
+    usage: Usage;
+    durationMs: number;
+    error?: {
+        code?: string;
+        message: string;
+    };
+    /** Full conversation messages at the time of session end (excludes system prompt). */
+    messages: Message[];
+}
+export interface PermissionRequestResult {
+    /**
+     * If true, passes permission checks and skips the approval flow.
+     * The tool still goes through normal middleware/disabled checks.
      * If false, blocks the tool execution immediately.
      */
     allow: boolean;
     modifiedToolCall?: ToolCall;
 }
-export type PreToolUseHook = (ctx: HookContext) => Promise<PreToolUseResult>;
-export type PostToolUseHook = (ctx: HookContext, result: unknown) => Promise<void>;
-export type PostToolUseFailureHook = (ctx: HookContext, error: Error) => Promise<void>;
-export interface ToolHooks {
+export interface PreToolUseResult {
+    /** Optionally modify the tool call before execution. */
+    modifiedToolCall?: ToolCall;
+}
+export interface UserPromptSubmitResult {
+    allow: boolean;
+    modifiedInput?: MessageContent;
+}
+export type PermissionRequestHook = (ctx: ToolHookContext) => Promise<PermissionRequestResult>;
+export type PreToolUseHook = (ctx: ToolHookContext) => Promise<PreToolUseResult | void>;
+export type PostToolUseHook = (ctx: ToolHookContext, result: unknown) => Promise<void>;
+export type PostToolUseFailureHook = (ctx: ToolHookContext, error: Error) => Promise<void>;
+export type StopHook = (ctx: StopContext) => Promise<void>;
+export type SessionStartHook = (ctx: SessionStartContext) => Promise<void>;
+export type SessionEndHook = (ctx: SessionEndContext) => Promise<void>;
+export type SubagentStartHook = (ctx: SubagentStartContext) => Promise<void>;
+export type SubagentStopHook = (ctx: SubagentStopContext) => Promise<void>;
+export type UserPromptSubmitHook = (ctx: UserPromptSubmitContext) => Promise<UserPromptSubmitResult>;
+export interface AgentHooks {
+    sessionStart?: SessionStartHook;
+    permissionRequest?: PermissionRequestHook;
     preToolUse?: PreToolUseHook;
     postToolUse?: PostToolUseHook;
     postToolUseFailure?: PostToolUseFailureHook;
+    sessionEnd?: SessionEndHook;
+    stop?: StopHook;
+    subagentStart?: SubagentStartHook;
+    subagentStop?: SubagentStopHook;
+    userPromptSubmit?: UserPromptSubmitHook;
 }
+/** @deprecated Use `AgentHooks` instead. Kept for backward compatibility. */
+export type ToolHooks = AgentHooks;

package/dist/agent/index.d.ts

@@ -6,9 +6,10 @@ export type { ToCheckpointOptions } from '../session/handlers/CheckpointManager'
 export { Agent } from './agent';
 export { AgentAbortError, AgentMaxIterationsError, AgentPauseError, ensureNotAborted } from './errors';
 export { HookManager } from './hooks';
-export type { HookContext, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, ToolHooks, } from './hooks';
+export type { AgentHooks, BaseHookContext, HookContext, PermissionRequestHook, PermissionRequestResult, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, SessionEndContext, SessionEndHook, SessionStartContext, SessionStartHook, StopContext, StopHook, SubagentStartContext, SubagentStartHook, SubagentStopContext, SubagentStopHook, ToolHookContext, ToolHooks, UserPromptSubmitContext, UserPromptSubmitHook, UserPromptSubmitResult, } from './hooks';
 export { compose } from './middleware';
 export type { Middleware, NamedMiddleware, NextFunction } from './middleware';
-export { countContentTokens, countMessagesTokens, countMessageTokens, countTokens, estimateTokens, } from './tokenCounter';
+export { countContentTokens, countMessagesTokens, countMessageTokens, countTokens, createCachedTokenCounter, estimateMessagesTokens, estimateTokens, } from './tokenCounter';
+export type { CachedTokenCounter } from './tokenCounter';
 export { createInitialLoopState } from './types';
 export type { AgentInput, AgentLoopState, AgentOptions, CreateSessionOptions, SendOptions, SessionHandleOptions, ToolCallWithResult, } from './types';

package/dist/agent/middleware.d.ts

@@ -62,7 +62,7 @@ export interface Middleware<State = AgentLoopState> {
      *   // middleware logic...
      *   return next(state);
      * };
-     * middleware.__middlewareName = 'plan-mode';
+     * middleware.__middlewareName = 'plan_mode';
      * middleware.__createTools = () => [
      *   new EnterPlanModeTool(),
      *   new ExitPlanModeTool()
@@ -86,7 +86,7 @@ export interface Middleware<State = AgentLoopState> {
      * const middleware: Middleware = async (state, next) => {
      *   return next(state);
      * };
-     * middleware.__middlewareName = 'plan-mode';
+     * middleware.__middlewareName = 'plan_mode';
      * middleware.__getBlockedTools = (state) => {
      *   // Only block tools when plan mode is active
      *   return state.metadata?.planMode
@@ -96,6 +96,35 @@ export interface Middleware<State = AgentLoopState> {
      * ```
      */
     __getBlockedTools?: (state: State) => string[] | Set<string>;
+    /**
+     * Optional middleware function that runs AFTER the model response
+     * when there are no tool calls (the loop would normally stop).
+     *
+     * Receives state with `currentResponse`, `pendingToolCalls`, and
+     * `lastModelStopReason` already populated from the model call.
+     * Can set `shouldContinue = true` and inject follow-up messages
+     * into `messages` to continue the loop.
+     *
+     * Multiple middleware `__afterResponse` functions are composed using
+     * the same onion-model `compose()` pattern as the main middleware.
+     *
+     * @example
+     * ```ts
+     * const middleware: Middleware = async (state, next) => {
+     *   return next(state);
+     * };
+     * middleware.__afterResponse = async (state, next) => {
+     *   const result = await next(state);
+     *   // Inspect model response and decide continuation
+     *   if (looksIncomplete(result.currentResponse)) {
+     *     result.messages.push({ role: 'user', content: 'Please continue.' });
+     *     result.shouldContinue = true;
+     *   }
+     *   return result;
+     * };
+     * ```
+     */
+    __afterResponse?: Middleware<State>;
 }
 /**
  * Named middleware wrapper

package/dist/agent/tokenCounter.d.ts

@@ -53,13 +53,59 @@ export declare function countMessageTokens(message: Message, model?: TiktokenMod
  */
 export declare function countMessagesTokens(messages: Message[], model?: TiktokenModel): number;
 /**
- * Estimate tokens from a string length.
- * Useful for quick estimates without calling tiktoken.
+ * Estimate tokens from a string using a multi-strategy heuristic.
+ *
+ * Takes the maximum of three estimates to conservatively estimate high
+ * for any language:
+ * - `byChars`: chars / 4 (English-optimized)
+ * - `byBytes`: UTF-8 bytes / 3 (CJK-optimized, 3 bytes per CJK char ~ 1 token)
+ * - `byMixed`: ASCII chars / 4 + non-ASCII chars * 0.9
  *
  * @param text - The text to estimate
  * @returns Estimated token count
  */
 export declare function estimateTokens(text: string): number;
+export declare function estimateMessagesTokens(messages: Message[]): number;
+/**
+ * A cached token counter that reuses a singleton tiktoken encoder
+ * and caches results per text string and per message reference.
+ *
+ * Use this for UI display paths where accurate counts are needed
+ * without the per-call overhead of creating/destroying encoders.
+ */
+export interface CachedTokenCounter {
+    /** Count tokens in a string (cached by content). */
+    countTokens: (text: string) => number;
+    /** Count tokens in a single message (cached by object reference). */
+    countMessageTokens: (message: Message) => number;
+    /** Count tokens in a message array (sums per-message cached counts). */
+    countMessagesTokens: (messages: Message[]) => number;
+    /** Clear all caches. */
+    clearCache: () => void;
+    /** Free the tiktoken encoder and all caches. */
+    dispose: () => void;
+}
+/**
+ * Create a cached token counter with a singleton tiktoken encoder.
+ *
+ * The encoder is lazy-initialized on first use and reused for all
+ * subsequent calls, eliminating WASM instantiation overhead.
+ * Results are cached per text (LRU) and per message (WeakMap).
+ *
+ * Falls back to CJK-aware `estimateTokens` if tiktoken cannot be loaded.
+ *
+ * @param options - Optional cached counter configuration.
+ * @param options.model - Model name for encoding (default: gpt-4o)
+ * @param options.maxCacheSize - Maximum LRU cache entries (default: 500)
+ * @param options.maxCachableLength - Strings longer than this are counted
+ *   but not cached, to avoid holding large tool outputs in memory (default: 4096)
+ */
+export declare function createCachedTokenCounter(options?: {
+    model?: TiktokenModel;
+    maxCacheSize?: number;
+    /** Strings longer than this (in chars) are counted but not cached. Default: 4096. */
+    maxCachableLength?: number;
+}): CachedTokenCounter;
 /**
  * @deprecated Use countTokens directly - encoder is now created and freed per call.
  */

package/dist/agent/types.d.ts

@@ -73,7 +73,7 @@ export interface AgentLoopState {
     /**
      * Stop reason for debugging/logging.
      */
-    stopReason?: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'approval_required';
+    stopReason?: 'max_iterations' | 'final_response' | 'error' | 'cancelled' | 'approval_required' | 'max_follow_ups';
     /**
      * The stop reason reported by the most recent model call (if available).
      *
@@ -100,6 +100,20 @@ export interface AgentLoopState {
      * - planMode: boolean - Whether plan mode is active
      */
     metadata: Record<string, unknown>;
+    /**
+     * Number of follow-up rounds that have occurred in long_running mode.
+     * Incremented each time the completion assessor says "not complete"
+     * and a follow-up message is injected.
+     *
+     * Defaults to 0 when not set (backward compatible with existing code
+     * that constructs AgentLoopState manually without this field).
+     */
+    followUpRound?: number;
+    /**
+     * The original user input that started this run.
+     * Preserved for completion assessors to compare against.
+     */
+    originalInput?: MessageContent;
     /**
      * Flag to skip message snapshot restoration in checkpoint.
      * When true, Session will use `state.messages` directly for checkpoint persistence.

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export * from './acp-adapter';
 export { Agent, AgentAbortError, AgentMaxIterationsError, compose, compressSessionManually, createContextCompressionMiddleware, createInitialLoopState, ensureNotAborted, extractPersistentMetadata, extractPersistentState, fromLoopCheckpoint, HookManager, toLoopCheckpoint, } from './agent';
-export type { AgentInput, AgentLoopState, AgentOptions, CompressionStats, ContextCompressionOptions, CreateSessionOptions, HookContext, ManualCompressionOptions, ManualCompressionResult, Middleware, NextFunction, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, SendOptions, SessionHandleOptions, ToCheckpointOptions, ToolCallWithResult, ToolHooks, } from './agent';
+export type { AgentHooks, AgentInput, AgentLoopState, AgentOptions, BaseHookContext, CompressionStats, ContextCompressionOptions, CreateSessionOptions, HookContext, ManualCompressionOptions, ManualCompressionResult, Middleware, NextFunction, PermissionRequestHook, PermissionRequestResult, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, SessionEndContext, SessionEndHook, SessionStartContext, SessionStartHook, SendOptions, SessionHandleOptions, StopContext, StopHook, SubagentStartContext, SubagentStartHook, SubagentStopContext, SubagentStopHook, ToCheckpointOptions, ToolCallWithResult, ToolHookContext, ToolHooks, UserPromptSubmitContext, UserPromptSubmitHook, UserPromptSubmitResult, } from './agent';
 export { applyCcMockSystemPrompt, CCMOCK_SYSTEM_PROMPT_PREFIX, isCcMockEnabled, readCcMockFlag, } from './ccmock';
 export * from './mcp-client';
 export { createAgentRulesMiddleware } from './middleware/agentRulesMiddleware';
 export type { AgentRulesMiddlewareOptions } from './middleware/agentRulesMiddleware';
 export { createCommitModeMiddleware } from './middleware/commitModeMiddleware';
 export type { CommitModeMiddlewareOptions } from './middleware/commitModeMiddleware';
+export { createAttachmentMiddleware } from './middleware/attachmentMiddleware';
+export type { AttachmentMiddlewareOptions } from './middleware/attachmentMiddleware';
 export { createEnvInfoMiddleware } from './middleware/envInfoMiddleware';
 export type { EnvInfoMiddlewareOptions } from './middleware/envInfoMiddleware';
 export { createParallelSubagentMiddleware } from './middleware/parallelSubagentMiddleware';
@@ -17,16 +19,22 @@ export { createReviewModeMiddleware } from './middleware/reviewMiddleware';
 export type { ReviewModeMiddlewareOptions } from './middleware/reviewMiddleware';
 export { createSkillsMiddleware, parseSkillFile, scanMultipleSkillsDirectories, scanSkillsDirectory } from './middleware/skillsMiddleware';
 export type { ParsedSkill, SkillsMiddlewareOptions } from './middleware/skillsMiddleware';
+export { createLongRunningMiddleware } from './middleware/longRunningMiddleware';
+export type { LongRunningMiddlewareOptions, SelfReflectionOptions } from './middleware/longRunningMiddleware';
 export { injectSystemReminderToLastUserMessage, } from './middleware/utils';
 export * from './model';
 export type { OpenAITool } from './model';
 export { BaseSession, BaseSessionManager, Session } from './session';
+export { CompositeAssessor, ReflectionDecisionTool, RuleBasedAssessor, SelfReflectionAssessor, TodoBasedAssessor, } from './session/completion';
+export type { CompletionAssessment, CompletionAssessor, CompletionContext, ReflectionDecision, ReflectionDecisionCallback, SelfReflectionAssessorOptions, } from './session/completion';
 export { FileStateStore, InMemoryStateStore, StateKeys, StateStore, } from './state';
 export type { CompressionState, FileStateStoreOptions, StateKey, StateStoreOptions, } from './state';
 export * from './subagent';
 export { BaseTool, errorContent, FilteredToolRegistry, imageContent, textContent, ToolRegistry } from './tool';
-export { AskUserTool, BashTool, EditTool, GlobTool, GrepTool, ReadTool, TodoPlanTool, TodoWriteTool, WebFetchTool, WebSearchTool, WriteTool, } from './tool';
+export { AskUserTool, BashTool, EditTool, GlobTool, GrepTool, ReadTool, TodoPlanTool, TodoWriteTool, softWrapLines, WebFetchTool, WebSearchTool, WriteTool, } from './tool';
 export type { BashArgs, BashResult, RiskLevel, ToolApprovalResult, ToolApprovalSettings, ToolApprovalStrategy, ToolExecutionContext, ToolExecutionContextInput, ToolRunUsage, } from './tool';
-export type { AskUserArgs, AskUserResult, EditArgs, EditResult, FetchFormat, GlobArgs, GlobResult, GrepArgs, GrepOutputMode, GrepResult, Question, QuestionOption, ReadArgs, ReadResult, TodoItem, TodoPlanArgs, TodoPlanResult, TodoStatus, TodoWriteArgs, TodoWriteResult, WebFetchArgs, WebFetchResult, WebSearchArgs, WebSearchResult, WriteArgs, WriteResult, } from './tool';
+export type { AskUserArgs, AskUserResult, EditArgs, EditResult, DeliveryMode, FetchFormat, GlobArgs, GlobResult, GrepArgs, GrepOutputMode, GrepResult, Question, QuestionOption, ReadArgs, ReadResult, TodoItem, TodoPlanArgs, TodoPlanResult, TodoStatus, TodoWriteArgs, TodoWriteResult, WebFetchArgs, WebFetchResult, WebSearchArgs, WebSearchResult, WriteArgs, WriteResult, } from './tool';
 export * from './tool/converters';
-export type { AgentEvent, AgentEventType, AgentLoopCheckpoint, AssistantMessage, BaseEvent, CallToolResult, ContentBlock, DoneEvent, ImageContent, IterationEndEvent, IterationStartEvent, JSONSchemaProperty, Message, MessageContent, MessageRole, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';
+export { cacheTextToSessionBlob, cleanupExpiredSessionCaches, cleanupSessionCache, deleteSessionBlobByPath, normalizeSessionId, readBlobMeta, relocateSessionBlobPath, resolveBlobPathFromFileId, resolveSessionCacheDir, resolveStateDir, writeSessionBlob, } from './lib/session-blob';
+export type { BlobLogger, SessionBlobWriteResult } from './lib/session-blob';
+export type { AgentEvent, AgentEventType, AgentLoopCheckpoint, AssistantMessage, BaseEvent, CallToolResult, CompletionAssessedEvent, CompressionEndEvent, CompressionStartEvent, ContentBlock, DoneEvent, ImageContent, IterationEndEvent, IterationStartEvent, JSONSchemaProperty, Message, MessageContent, MessageRole, SystemMessage, TextContent, TextDeltaEvent, TextEndEvent, TextStartEvent, ThinkingDeltaEvent, Tool, ToolCall, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolMessage, ToolResultEvent, Usage, UserMessage, } from './types';