@standardagents/spec 0.39.0 → 0.39.1

package/dist/index.d.ts

@@ -1647,7 +1647,7 @@ interface ExecutionState {
     readonly stopped: boolean;
     /** Which side initiated the stop (if stopped) */
     readonly stoppedBy?: 'a' | 'b';
-    /** Message history loaded for current execution */
+    /** Live chronological persisted history for the current execution */
     readonly messageHistory: Message[];
     /**
      * Force a specific side to play the next turn.
@@ -1873,6 +1873,12 @@ interface ThreadState {
      *
      * Creates a new message in the conversation history. This can be used
      * to add context, simulate user input, or insert assistant responses.
+     * Runs `before_create_message` and `after_create_message`. If a
+     * `before_create_message` hook throws, the returned promise rejects and
+     * no message is persisted. During active execution, the persisted message
+     * becomes immediately visible through `execution.messageHistory`.
+     * `silent` controls client presentation only; silent messages remain
+     * eligible for model context.
      *
      * @param message - The message to inject
      * @returns The created message
@@ -4418,10 +4424,14 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      */
     after_system_message: (state: State, systemMessage: string) => string | Promise<string | null | undefined> | null | undefined;
     /**
-     * Called before messages are filtered and sent to the LLM.
+     * Called exactly once per model-context assembly on a stable snapshot of
+     * eligible persisted history.
      *
      * Receives raw message rows from storage before any transformation.
      * Use for filtering, sorting, or augmenting message history.
+     * The result is the request context and does not replace
+     * `state.execution.messageHistory`. Messages injected while this hook runs
+     * become eligible for the following context assembly.
      *
      * @param state - Thread state
      * @param messages - Array of messages from storage
@@ -4438,10 +4448,12 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      */
     filter_messages: (state: State, messages: Msg[]) => Promise<Msg[]>;
     /**
-     * Called after message history is loaded and before sending to LLM.
+     * Called after filtered history is transformed into provider messages and
+     * before dispatch.
      *
      * Receives messages already transformed into chat completion format.
-     * Use for final adjustments before LLM request.
+     * Use for final request-local adjustments. Messages injected while this
+     * hook runs become eligible for the following context assembly.
      *
      * @param state - Thread state
      * @param messages - Array of LLM-formatted messages
@@ -4463,6 +4475,10 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      * Receives the full message object before insertion. Return modified
      * message to transform before storage.
      *
+     * A hook that throws during `injectMessage()` rejects the injection and
+     * no message is persisted. Other runtime insertions log the failure and
+     * keep the last good message.
+     *
      * @param state - Thread state
      * @param message - Message to be created
      * @returns Modified message