llmist 17.5.1 → 18.0.0

package/dist/index.d.cts

@@ -1010,6 +1010,18 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
      * - `N > 1` = At most N concurrent
      */
     maxConcurrent?: number;
+    /**
+     * If true, this gadget's results are marked sticky and survive compaction.
+     * See `AbstractGadget.stickyResult` for the full contract.
+     */
+    stickyResult?: boolean;
+    /**
+     * If true, the consuming agent loop should treat this gadget as a per-
+     * iteration barrier — when it appears in a tool batch, no sibling gadgets
+     * in the same batch execute. See `AbstractGadget.iterationBarrier` for the
+     * full contract (enforcement is consumer-side; this flag is declarative).
+     */
+    iterationBarrier?: boolean;
 }
 /**
  * Creates a gadget from a function (simpler than class-based approach).
@@ -1229,6 +1241,8 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          * ```
          */
         execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+        stickyResult?: boolean;
+        iterationBarrier?: boolean;
         throwIfAborted(ctx?: ExecutionContext): void;
         onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
         createLinkedAbortController(ctx?: ExecutionContext): AbortController;
@@ -3858,6 +3872,15 @@ interface GadgetExecutionResult {
     mediaIds?: string[];
     /** Stored media with paths (for CLI display) */
     storedMedia?: StoredMedia[];
+    /**
+     * If true, the message persisting this gadget result is marked sticky
+     * (`metadata.sticky = true`) so compaction strategies preserve it
+     * indefinitely. Use for gadgets whose output the agent needs to remember
+     * for the rest of the conversation (e.g. `LoadSkill` whose body is the
+     * canonical reference the agent will keep consulting). Copied from
+     * `AbstractGadget.stickyResult` by the executor.
+     */
+    stickyResult?: boolean;
 }
 /**
  * Result returned by gadget execute() method.
@@ -4131,6 +4154,43 @@ declare abstract class AbstractGadget {
      * This is a safety floor: external config cannot weaken it.
      */
     exclusive?: boolean;
+    /**
+     * If true, results produced by this gadget are marked sticky on the
+     * conversation (`message.metadata.sticky === true`). Compaction strategies
+     * preserve sticky messages past the truncation point, so the agent retains
+     * the gadget's output for the rest of the conversation rather than having
+     * it dropped on the next compaction pass.
+     *
+     * Use for gadgets whose output is *reference material* the agent will keep
+     * consulting — `LoadSkill` is the canonical example: a multi-KB skill body
+     * the agent needs to remember across iterations. Don't use for routine
+     * gadget outputs (file reads, computation results) — those should churn
+     * normally with the conversation.
+     *
+     * Has no effect on agents that don't enable compaction.
+     */
+    stickyResult?: boolean;
+    /**
+     * Hints to the consuming agent loop that when this gadget appears in an
+     * LLM iteration's tool batch, no other gadget in the same batch should
+     * execute. Sibling tool calls in the same iteration are expected to be
+     * skipped (not executed) with a synthetic result; the next LLM iteration
+     * gets only this gadget's output back, and must re-plan from there.
+     *
+     * llmist exposes this as declarative metadata only — enforcement is the
+     * consuming agent loop's responsibility (the loop already owns the
+     * stream-event consumption and the `beforeGadgetExecution` controller, so
+     * it can buffer per-iteration calls, decide barrier-status at
+     * `llm_response_end`, and skip non-barrier siblings via the standard
+     * skip-with-synthetic-result mechanism). See `LoadSkill` for the canonical
+     * use case: the agent loop should freeze sibling tool execution so the
+     * LLM sees only the loaded skill body before issuing dependent work.
+     *
+     * Orthogonal to `stickyResult` (which affects compaction) and `exclusive`
+     * (which queues the marked gadget alone, AFTER others — opposite of this
+     * flag's "freeze the others" semantic).
+     */
+    iterationBarrier?: boolean;
     /**
      * Execute the gadget with the given parameters.
      * Can be synchronous or asynchronous.
@@ -4554,7 +4614,7 @@ declare class LLMMessageBuilder {
      * @param mediaIds - Optional IDs for the media outputs
      * @param storedMedia - Optional stored media info including file paths
      */
-    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): this;
+    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): this;
     /**
      * Format parameters as Block format with JSON Pointer paths.
      * Uses the configured argPrefix for consistency with system prompt.
@@ -5914,7 +5974,7 @@ interface IConversationManager {
      * Optionally includes media outputs (images, audio, etc.) for multimodal results.
      * If storedMedia is provided, file paths will be included in the result message.
      */
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): void;
     /**
      * Gets the complete conversation history including base messages (system prompts, gadget instructions).
      */
@@ -7643,7 +7703,7 @@ declare class ConversationManager implements IConversationManager {
     constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
     addUserMessage(content: MessageContent): void;
     addAssistantMessage(content: string): void;
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): void;
     getMessages(): LLMMessage[];
     getHistoryMessages(): LLMMessage[];
     getBaseMessages(): LLMMessage[];
@@ -10519,8 +10579,8 @@ declare function resolveInstructions(instructions: string, options?: {
  * LoadSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
  *
  * When skills are registered with an agent, this gadget is auto-created and added
- * to the gadget registry. The LLM can invoke it like any other gadget, and the
- * skill's instructions are returned as the gadget result.
+ * to the gadget registry. The LLM invokes it with an array of skill names; each
+ * skill's resolved instructions are composed into a single multi-section result.
  *
  * This approach requires zero changes to the stream processor or agent loop.
  *
@@ -10532,8 +10592,16 @@ declare const LOAD_SKILL_GADGET_NAME = "LoadSkill";
 /**
  * Create the LoadSkill meta-gadget from a skill registry.
  *
- * The gadget description includes a summary of all available skills,
- * so the LLM knows what skills exist and when to load them.
+ * The gadget's tool description includes a summary of all available skills, so
+ * the LLM knows what skills exist and when to load them. Setting
+ * `iterationBarrier: true` and `stickyResult: true` are the two declarative
+ * flags every LoadSkill should carry:
+ *
+ *   - `iterationBarrier`: tells the consuming agent loop to skip every sibling
+ *     tool call in the same iteration's batch. The next LLM iteration sees
+ *     only the loaded skill bodies and re-plans from there.
+ *   - `stickyResult`: tells the compaction layer to preserve the result past
+ *     truncation, so the agent doesn't re-load the same skill ten turns later.
  */
 declare function createLoadSkillGadget(registry: SkillRegistry): AbstractGadget;
 

package/dist/index.d.ts

@@ -1010,6 +1010,18 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
      * - `N > 1` = At most N concurrent
      */
     maxConcurrent?: number;
+    /**
+     * If true, this gadget's results are marked sticky and survive compaction.
+     * See `AbstractGadget.stickyResult` for the full contract.
+     */
+    stickyResult?: boolean;
+    /**
+     * If true, the consuming agent loop should treat this gadget as a per-
+     * iteration barrier — when it appears in a tool batch, no sibling gadgets
+     * in the same batch execute. See `AbstractGadget.iterationBarrier` for the
+     * full contract (enforcement is consumer-side; this flag is declarative).
+     */
+    iterationBarrier?: boolean;
 }
 /**
  * Creates a gadget from a function (simpler than class-based approach).
@@ -1229,6 +1241,8 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          * ```
          */
         execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+        stickyResult?: boolean;
+        iterationBarrier?: boolean;
         throwIfAborted(ctx?: ExecutionContext): void;
         onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
         createLinkedAbortController(ctx?: ExecutionContext): AbortController;
@@ -3858,6 +3872,15 @@ interface GadgetExecutionResult {
     mediaIds?: string[];
     /** Stored media with paths (for CLI display) */
     storedMedia?: StoredMedia[];
+    /**
+     * If true, the message persisting this gadget result is marked sticky
+     * (`metadata.sticky = true`) so compaction strategies preserve it
+     * indefinitely. Use for gadgets whose output the agent needs to remember
+     * for the rest of the conversation (e.g. `LoadSkill` whose body is the
+     * canonical reference the agent will keep consulting). Copied from
+     * `AbstractGadget.stickyResult` by the executor.
+     */
+    stickyResult?: boolean;
 }
 /**
  * Result returned by gadget execute() method.
@@ -4131,6 +4154,43 @@ declare abstract class AbstractGadget {
      * This is a safety floor: external config cannot weaken it.
      */
     exclusive?: boolean;
+    /**
+     * If true, results produced by this gadget are marked sticky on the
+     * conversation (`message.metadata.sticky === true`). Compaction strategies
+     * preserve sticky messages past the truncation point, so the agent retains
+     * the gadget's output for the rest of the conversation rather than having
+     * it dropped on the next compaction pass.
+     *
+     * Use for gadgets whose output is *reference material* the agent will keep
+     * consulting — `LoadSkill` is the canonical example: a multi-KB skill body
+     * the agent needs to remember across iterations. Don't use for routine
+     * gadget outputs (file reads, computation results) — those should churn
+     * normally with the conversation.
+     *
+     * Has no effect on agents that don't enable compaction.
+     */
+    stickyResult?: boolean;
+    /**
+     * Hints to the consuming agent loop that when this gadget appears in an
+     * LLM iteration's tool batch, no other gadget in the same batch should
+     * execute. Sibling tool calls in the same iteration are expected to be
+     * skipped (not executed) with a synthetic result; the next LLM iteration
+     * gets only this gadget's output back, and must re-plan from there.
+     *
+     * llmist exposes this as declarative metadata only — enforcement is the
+     * consuming agent loop's responsibility (the loop already owns the
+     * stream-event consumption and the `beforeGadgetExecution` controller, so
+     * it can buffer per-iteration calls, decide barrier-status at
+     * `llm_response_end`, and skip non-barrier siblings via the standard
+     * skip-with-synthetic-result mechanism). See `LoadSkill` for the canonical
+     * use case: the agent loop should freeze sibling tool execution so the
+     * LLM sees only the loaded skill body before issuing dependent work.
+     *
+     * Orthogonal to `stickyResult` (which affects compaction) and `exclusive`
+     * (which queues the marked gadget alone, AFTER others — opposite of this
+     * flag's "freeze the others" semantic).
+     */
+    iterationBarrier?: boolean;
     /**
      * Execute the gadget with the given parameters.
      * Can be synchronous or asynchronous.
@@ -4554,7 +4614,7 @@ declare class LLMMessageBuilder {
      * @param mediaIds - Optional IDs for the media outputs
      * @param storedMedia - Optional stored media info including file paths
      */
-    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): this;
+    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): this;
     /**
      * Format parameters as Block format with JSON Pointer paths.
      * Uses the configured argPrefix for consistency with system prompt.
@@ -5914,7 +5974,7 @@ interface IConversationManager {
      * Optionally includes media outputs (images, audio, etc.) for multimodal results.
      * If storedMedia is provided, file paths will be included in the result message.
      */
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): void;
     /**
      * Gets the complete conversation history including base messages (system prompts, gadget instructions).
      */
@@ -7643,7 +7703,7 @@ declare class ConversationManager implements IConversationManager {
     constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
     addUserMessage(content: MessageContent): void;
     addAssistantMessage(content: string): void;
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[], metadata?: Record<string, unknown>): void;
     getMessages(): LLMMessage[];
     getHistoryMessages(): LLMMessage[];
     getBaseMessages(): LLMMessage[];
@@ -10519,8 +10579,8 @@ declare function resolveInstructions(instructions: string, options?: {
  * LoadSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
  *
  * When skills are registered with an agent, this gadget is auto-created and added
- * to the gadget registry. The LLM can invoke it like any other gadget, and the
- * skill's instructions are returned as the gadget result.
+ * to the gadget registry. The LLM invokes it with an array of skill names; each
+ * skill's resolved instructions are composed into a single multi-section result.
  *
  * This approach requires zero changes to the stream processor or agent loop.
  *
@@ -10532,8 +10592,16 @@ declare const LOAD_SKILL_GADGET_NAME = "LoadSkill";
 /**
  * Create the LoadSkill meta-gadget from a skill registry.
  *
- * The gadget description includes a summary of all available skills,
- * so the LLM knows what skills exist and when to load them.
+ * The gadget's tool description includes a summary of all available skills, so
+ * the LLM knows what skills exist and when to load them. Setting
+ * `iterationBarrier: true` and `stickyResult: true` are the two declarative
+ * flags every LoadSkill should carry:
+ *
+ *   - `iterationBarrier`: tells the consuming agent loop to skip every sibling
+ *     tool call in the same iteration's batch. The next LLM iteration sees
+ *     only the loaded skill bodies and re-plans from there.
+ *   - `stickyResult`: tells the compaction layer to preserve the result past
+ *     truncation, so the agent doesn't re-load the same skill ten turns later.
  */
 declare function createLoadSkillGadget(registry: SkillRegistry): AbstractGadget;
 

package/dist/index.js

@@ -81,7 +81,7 @@ import {
   toBase64,
   validateGadgetSchema,
   withErrorHandling
-} from "./chunk-HM7PUGPA.js";
+} from "./chunk-DNB4DPM4.js";
 
 // src/core/execution-tree-aggregator.ts
 var ExecutionTreeAggregator;
@@ -1884,11 +1884,19 @@ var init_sliding_window = __esm({
         }
         const turnsToKeep = turns.slice(-preserveCount);
         const turnsRemoved = turns.length - preserveCount;
+        const keptMessageRefs = new Set(turnsToKeep.flatMap((turn) => turn.messages));
+        const stickyToPreserve = messages.filter(
+          (msg) => msg.metadata?.sticky === true && !keptMessageRefs.has(msg)
+        );
         const truncationMarker = {
           role: "user",
           content: TRUNCATION_MARKER_TEMPLATE.replace("{count}", turnsRemoved.toString())
         };
-        const compactedMessages = [truncationMarker, ...flattenTurns(turnsToKeep)];
+        const compactedMessages = [
+          truncationMarker,
+          ...stickyToPreserve,
+          ...flattenTurns(turnsToKeep)
+        ];
         const tokensAfter = Math.ceil(
           compactedMessages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4
         );
@@ -1932,7 +1940,14 @@ var init_summarization = __esm({
         }
         const turnsToSummarize = turns.slice(0, -preserveCount);
         const turnsToKeep = turns.slice(-preserveCount);
-        const conversationToSummarize = this.formatTurnsForSummary(flattenTurns(turnsToSummarize));
+        const keptMessageRefs = new Set(turnsToKeep.flatMap((turn) => turn.messages));
+        const stickyToPreserve = messages.filter(
+          (msg) => msg.metadata?.sticky === true && !keptMessageRefs.has(msg)
+        );
+        const turnsToSummarizeMessages = flattenTurns(turnsToSummarize).filter(
+          (msg) => msg.metadata?.sticky !== true
+        );
+        const conversationToSummarize = this.formatTurnsForSummary(turnsToSummarizeMessages);
         const summary = await this.generateSummary(conversationToSummarize, config, context);
         const summaryMessage = {
           role: "user",
@@ -1940,7 +1955,11 @@ var init_summarization = __esm({
 ${summary}
 [End of summary - conversation continues below]`
         };
-        const compactedMessages = [summaryMessage, ...flattenTurns(turnsToKeep)];
+        const compactedMessages = [
+          summaryMessage,
+          ...stickyToPreserve,
+          ...flattenTurns(turnsToKeep)
+        ];
         const tokensAfter = Math.ceil(
           compactedMessages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4
         );
@@ -2261,7 +2280,7 @@ var init_conversation_manager = __esm({
       addAssistantMessage(content) {
         this.historyBuilder.addAssistant(content);
       }
-      addGadgetCallResult(gadgetName, parameters, result, invocationId, media, mediaIds, storedMedia) {
+      addGadgetCallResult(gadgetName, parameters, result, invocationId, media, mediaIds, storedMedia, metadata) {
         this.historyBuilder.addGadgetCallResult(
           gadgetName,
           parameters,
@@ -2269,7 +2288,8 @@ var init_conversation_manager = __esm({
           invocationId,
           media,
           mediaIds,
-          storedMedia
+          storedMedia,
+          metadata
         );
       }
       getMessages() {
@@ -2401,6 +2421,7 @@ var init_conversation_updater = __esm({
           for (const output of gadgetResults) {
             if (output.type === "gadget_result") {
               const gadgetResult = output.result;
+              const metadata = gadgetResult.stickyResult === true && gadgetResult.error === void 0 ? { sticky: true } : void 0;
               this.conversation.addGadgetCallResult(
                 gadgetResult.gadgetName,
                 gadgetResult.parameters,
@@ -2408,7 +2429,8 @@ var init_conversation_updater = __esm({
                 gadgetResult.invocationId,
                 gadgetResult.media,
                 gadgetResult.mediaIds,
-                gadgetResult.storedMedia
+                gadgetResult.storedMedia,
+                metadata
               );
             }
           }
@@ -4103,11 +4125,20 @@ var init_activation = __esm({
 
 // src/skills/load-skill-gadget.ts
 import { z as z2 } from "zod";
+function composeSkillSections(sections) {
+  return sections.map(({ name, body }) => `==== ${name} ====
+${body}`).join("\n\n");
+}
 function createLoadSkillGadget(registry) {
   const summaries = registry.getMetadataSummaries();
   const skillNames = registry.getModelInvocable().map((s) => s.name);
   const description = [
-    "Load a skill's specialized instructions into context for a task.",
+    "Load one or more skill bodies into context. Pass an array even for a",
+    'single skill: `{skills: ["some-skill"]}`. **This gadget is an iteration',
+    "barrier \u2014 no other gadgets in the same tool batch will execute, so load",
+    "every skill you know you'll need in one shot.** The loaded bodies are",
+    "sticky and survive context compaction.",
+    "",
     "Available skills:",
     summaries
   ].join("\n");
@@ -4115,19 +4146,33 @@ function createLoadSkillGadget(registry) {
     name: LOAD_SKILL_GADGET_NAME,
     description,
     schema: z2.object({
-      skill: z2.enum(skillNames).describe("Name of the skill to load"),
-      arguments: z2.string().optional().describe("Arguments for the skill (e.g., a filename, issue number, or search query)")
+      skills: z2.array(z2.enum(skillNames)).min(1).describe(
+        "One or more skill names to load in this single call. Prefer loading everything you know you'll need at once \u2014 this gadget is an iteration barrier, so sibling tool calls in the same batch will not execute."
+      ),
+      arguments: z2.string().optional().describe(
+        "Optional argument string substituted into each skill's $ARGUMENTS placeholders. Applies to every skill in the batch. To pass different arguments to different skills, issue separate LoadSkill calls."
+      )
     }),
-    execute: async ({ skill: skillName, arguments: args }) => {
-      const skill = registry.get(skillName);
-      if (!skill) {
-        return `Unknown skill: "${skillName}". Available skills: ${skillNames.join(", ")}`;
-      }
-      const activation = await skill.activate({
-        arguments: args,
-        cwd: process.cwd()
-      });
-      return activation.resolvedInstructions;
+    stickyResult: true,
+    iterationBarrier: true,
+    execute: async ({ skills: skillNamesArg, arguments: args }) => {
+      const sections = [];
+      for (const skillName of skillNamesArg) {
+        const skill = registry.get(skillName);
+        if (!skill) {
+          sections.push({
+            name: skillName,
+            body: `Unknown skill: "${skillName}". Available skills: ${skillNames.join(", ")}`
+          });
+          continue;
+        }
+        const activation = await skill.activate({
+          arguments: args,
+          cwd: process.cwd()
+        });
+        sections.push({ name: skillName, body: activation.resolvedInstructions });
+      }
+      return composeSkillSections(sections);
     }
   });
 }
@@ -13499,7 +13544,13 @@ var init_executor = __esm({
             cost: totalCost,
             media,
             mediaIds,
-            storedMedia
+            storedMedia,
+            // Copy the gadget's sticky flag into the result envelope so the
+            // conversation-updater can mark the persisted message sticky for
+            // the compaction layer. Only set on success — errors and other
+            // unsuccessful exits skip this so failed loads don't pin themselves
+            // in context.
+            stickyResult: gadget.stickyResult
           };
         } catch (error) {
           const isTaskCompletionSignal = error instanceof Error && error.name === "TaskCompletionSignal";
@@ -15688,7 +15739,7 @@ var init_agent = __esm({
         }
         const unsubscribeBridge = bridgeTreeToHooks(this.tree, this.hooks, this.logger);
         if (this.mcpSpecs.length > 0) {
-          const { setupMcpServers } = await import("./runtime-GKQ6QIQP.js");
+          const { setupMcpServers } = await import("./runtime-KB7US2FQ.js");
           this.mcpLifecycle = await setupMcpServers({
             specs: this.mcpSpecs,
             registry: this.registry,