@standardagents/spec 0.38.2 → 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
@@ -3809,6 +3815,15 @@ interface PromptToolConfig {
  * a non-empty human-readable `name` argument and runtimes SHOULD persist it as
  * a child thread display name.
  *
+ * Lifecycle tools manage resumable relationships exclusively: runtimes MUST
+ * reject a `subagent_create` invocation that targets a relationship without
+ * `resumable` configuration, without creating a child, and the rejection
+ * SHOULD direct the model to invoke that tool directly instead. Runtimes
+ * SHOULD constrain the injected tool's target argument to the exposed names
+ * of the prompt's resumable relationships. Lifecycle tool references use the
+ * relationship's exposed tool `name`, never an internal agent identifier that
+ * differs from it.
+ *
  * ### Pull-based child visibility
  *
  * Whenever resumable subagent configs exist, runtimes MUST also inject a
@@ -3851,14 +3866,39 @@ interface PromptToolConfig {
  *   },
  * }
  * ```
+ *
+ * @example
+ * ```typescript
+ * // The same agent exposed under a task-specific tool name.
+ * {
+ *   name: 'summarize_document',
+ *   agent: 'document_agent',
+ *   blocking: true,
+ *   initUserMessageProperty: 'message',
+ * }
+ * ```
  */
 interface SubagentToolConfig<T extends string = StandardAgentSpec.Callables> {
     /**
-     * Agent callable name.
+     * Exposed tool name — the name the model invokes this subagent by.
      *
-     * Must reference a `dual_ai` agent with `exposeAsTool: true`.
+     * When `agent` is absent, this MUST reference a `dual_ai` agent with
+     * `exposeAsTool: true` directly. When `agent` is present, this may be any
+     * valid tool identifier; the runtime MUST expose the tool under this name
+     * and MUST resolve invocations to the agent named by `agent`.
      */
-    name: T;
+    name: T | (string & {});
+    /**
+     * The `dual_ai` agent this tool invokes, when the tool is exposed under a
+     * name other than the agent's own. Must reference a `dual_ai` agent with
+     * `exposeAsTool: true`. Defaults to `name`.
+     *
+     * The same agent may be exposed under different tool names by different
+     * prompts. Everything model-facing — the tool schema, instance registries,
+     * and subagent lifecycle tool references — uses the exposed `name`;
+     * runtimes resolve the implementing agent internally as `agent ?? name`.
+     */
+    agent?: T;
     /**
      * Whether parent execution blocks until the subagent returns a result.
      *
@@ -4384,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
@@ -4404,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
@@ -4429,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