@fragola-ai/agent 0.1.0 → 0.1.1

package/dist/src/agent.d.ts

@@ -5,7 +5,7 @@ import type z from "zod";
 import type { Prettify, StoreLike } from "./types";
 import OpenAI from "openai/index.js";
 import { type AgentEventId } from "./event";
-import type { EventToolCall, EventUserMessage, EventModelInvocation, EventAiMessage, ModelInvocationPayload } from "./eventDefault";
+import type { EventToolCall, EventUserMessage, EventModelInvocation, EventAiMessage, ModelInvocationPayload, ToolCallPayload } from "./eventDefault";
 import type { EventAfterStateUpdate, EventAfterStep, EventAfterModelInvocation, EventAfterToolCall } from "./eventAfter";
 import type { EventBeforeStep, EventBeforeModelInvocation, EventBeforeToolCall, ModelInvocationConfig, ToolCallConfig } from "./eventBefore";
 import { type registeredEvent, type eventIdToCallback, EventMap } from "./extendedJS/events/EventMap";
@@ -108,14 +108,14 @@ export type applyEventParams<K extends AgentEventId, TMetaData extends DefineMet
 } : K extends "after:modelInvocation" ? {
     message: ChatCompletionAssistantMessageParam<TMetaData>;
 } : K extends "toolCall" ? {
-    result: any;
+    result: ToolCallPayload;
     params: any;
     tool: Tool<any>;
 } : K extends "before:toolCall" ? {
     config: ToolCallConfig<any>;
     tool: Tool<any>;
 } : K extends "after:toolCall" ? {
-    result: any;
+    result: ToolCallPayload;
     params: any;
     tool: Tool<any>;
 } : K extends "after:stateUpdate" ? null : never;
@@ -134,6 +134,8 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
     private hooks;
     private hookDisposeMap;
     private pendingHookNames;
+    private pendingHookSourceIds;
+    private cancelledHookSourceIds;
     private activeHookSourceId;
     /** serialized async initialization of hooks (ensures tools are ready before generation) */
     private hooksLoaded;
@@ -158,8 +160,9 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
         getStore<T extends unknown>(namespace?: string): Store<T> | undefined;
         addStore(store: Store<any>): void;
         removeStore(namespace: string): void;
+        get systemPrompt(): string;
         setInstructions(instructions: string, scope?: string): void;
-        getInstructions(scope?: string): string | undefined;
+        instructions(scope?: string): string | undefined;
         removeInstructions(scope: string): boolean;
         setOptions(options: SetOptionsParams): void;
         stop(): Promise<{
@@ -171,6 +174,7 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
         updateTools(callback: (prev: Tool[]) => Tool[]): void;
     };
     private setRegisteredEvents;
+    private removeHookScopedEvents;
     [FORK_FRIEND]: {
         setRegisteredEvents: (map: typeof this.registeredEvents) => void;
         getRegisteredEvents: () => EventMap<AgentEventId, registeredEvent<AgentEventId, TMetaData, TGlobalStore, TStore>[], TMetaData, TGlobalStore, TStore>;
@@ -198,7 +202,7 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
     /** Build merged instructions from default + scoped instructions. */
     private computeMergedInstructions;
     /** Return cached merged instructions, computing them if necessary. */
-    private getMergedInstructions;
+    private get mergedInstructions();
     private appendMessages;
     private setIdle;
     private setGenerating;
@@ -218,6 +222,8 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
     get options(): CreateAgentOptions<TStore>;
     private stepOptions;
     private validateStepOptions;
+    /** Waits for all pending hook setup to finish without executing a step. */
+    init(): Promise<void>;
     /**
      * Continues execution from the current message history for one or more steps.
      *
@@ -337,7 +343,7 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
      * Register a tool result handler.
      *
      * This event runs after `before:toolCall` resolves the current config and after the tool
-     * handler (or an injected result) produces a value. Each callback receives the current result
+        * handler (or an injected result) produces a payload. Each callback receives the current payload
      * and may transform it before it is exposed to later `toolCall` handlers, `after:toolCall`,
      * and the tool message appended to state.
      *
@@ -345,11 +351,15 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
      * remaining `toolCall` / `after:toolCall` pipeline for the current tool call.
      *
      * @example
-     * agent.onToolCall((result, params, tool) => {
+    * agent.onToolCall((result, params, tool) => {
      *   if (tool.name !== "getWeather") return result;
+    *   if (!result.success) return result;
      *   return {
-     *     requestedLocation: params.location,
-     *     data: result,
+    *     success: true,
+    *     data: {
+    *       requestedLocation: params.location,
+    *       data: result.data,
+    *     },
      *   };
      * });
      */
@@ -440,9 +450,9 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
      * Register a handler that can alter a tool call before execution.
      *
      * The callback receives `{ params }` before the tool handler runs. It may return a new
-     * `{ params }` object to rewrite validated arguments or `{ injectResult }` to bypass the
-     * handler entirely. `skip()` preserves the current config, and `context.stop()` aborts the
-     * current tool call.
+       * `{ params }` object to rewrite validated arguments or `{ injectConfig }` with a full
+       * `ToolCallPayload` to bypass the handler entirely. `skip()` preserves the current config,
+       * and `context.stop()` aborts the current tool call.
      *
      * @example
      * agent.onBeforeToolCall((config, tool) => {
@@ -454,7 +464,7 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
     /**
      * Register an after tool call event handler.
      *
-     * Called after a tool is executed.
+        * Called after a tool payload is finalized.
      *
      * @example
      * agent.onAfterToolCall((result, params, tool, context) => {
@@ -532,7 +542,7 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
      *
      * @example
      * ```ts
-    * import { Hook } from "@fragola-ai/agentic-sdk-core/hook";
+    * import { Hook } from "@fragola-ai/agent/hook";
     *
     * const loggingHook = Hook((agent) => {
     *   agent.onAfterStateUpdate((context) => {
@@ -554,6 +564,10 @@ export declare class Agent<TMetaData extends DefineMetaData<any> = {}, TGlobalSt
      * Returns `false` if no hook is registered under that name.
      */
     removeHook(name: string): Promise<boolean>;
+    /**
+     * Removes every hook currently registered on the agent.
+     */
+    dispose(): Promise<void>;
 }
 export type AgentAny = Agent<any, any, any>;
 export {};