llmist 17.5.1 → 18.0.0

package/dist/index.cjs

@@ -1414,7 +1414,7 @@ Produces: { "items": ["first", "second"] }`);
        * @param mediaIds - Optional IDs for the media outputs
        * @param storedMedia - Optional stored media info including file paths
        */
-      addGadgetCallResult(gadget, parameters, result, invocationId, media, mediaIds, storedMedia) {
+      addGadgetCallResult(gadget, parameters, result, invocationId, media, mediaIds, storedMedia, metadata) {
         const paramStr = this.formatBlockParameters(parameters, "");
         this.messages.push({
           role: "assistant",
@@ -1438,11 +1438,12 @@ ${idRefs}`;
               parts.push(audioFromBase64(item.data, item.mimeType));
             }
           }
-          this.messages.push({ role: "user", content: parts });
+          this.messages.push({ role: "user", content: parts, metadata });
         } else {
           this.messages.push({
             role: "user",
-            content: `Result (${invocationId}): ${result}`
+            content: `Result (${invocationId}): ${result}`,
+            metadata
           });
         }
         return this;
@@ -2674,11 +2675,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
         );
@@ -2722,7 +2731,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",
@@ -2730,7 +2746,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
         );
@@ -3051,7 +3071,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,
@@ -3059,7 +3079,8 @@ var init_conversation_manager = __esm({
           invocationId,
           media,
           mediaIds,
-          storedMedia
+          storedMedia,
+          metadata
         );
       }
       getMessages() {
@@ -3191,6 +3212,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,
@@ -3198,7 +3220,8 @@ var init_conversation_updater = __esm({
                 gadgetResult.invocationId,
                 gadgetResult.media,
                 gadgetResult.mediaIds,
-                gadgetResult.storedMedia
+                gadgetResult.storedMedia,
+                metadata
               );
             }
           }
@@ -4460,6 +4483,43 @@ var init_gadget = __esm({
        * This is a safety floor: external config cannot weaken it.
        */
       exclusive;
+      /**
+       * 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;
+      /**
+       * 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;
       /**
        * Throws an AbortException if the execution has been aborted.
        *
@@ -4656,6 +4716,8 @@ function createGadget(config) {
     timeoutMs = config.timeoutMs;
     examples = config.examples;
     maxConcurrent = config.maxConcurrent;
+    stickyResult = config.stickyResult;
+    iterationBarrier = config.iterationBarrier;
     execute(params, ctx) {
       return config.execute(params, ctx);
     }
@@ -5478,11 +5540,20 @@ var init_activation = __esm({
 });
 
 // src/skills/load-skill-gadget.ts
+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");
@@ -5490,19 +5561,33 @@ function createLoadSkillGadget(registry) {
     name: LOAD_SKILL_GADGET_NAME,
     description,
     schema: import_zod2.z.object({
-      skill: import_zod2.z.enum(skillNames).describe("Name of the skill to load"),
-      arguments: import_zod2.z.string().optional().describe("Arguments for the skill (e.g., a filename, issue number, or search query)")
+      skills: import_zod2.z.array(import_zod2.z.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: import_zod2.z.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);
     }
   });
 }
@@ -14875,7 +14960,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";