llmist 17.6.0 → 18.1.0

package/dist/index.d.cts

@@ -1015,6 +1015,13 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
      * 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).
@@ -1235,6 +1242,7 @@ 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;
@@ -4162,6 +4170,27 @@ declare abstract class AbstractGadget {
      * 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.
@@ -10550,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.
  *
@@ -10563,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

@@ -1015,6 +1015,13 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
      * 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).
@@ -1235,6 +1242,7 @@ 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;
@@ -4162,6 +4170,27 @@ declare abstract class AbstractGadget {
      * 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.
@@ -10550,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.
  *
@@ -10563,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-EXFIXEGW.js";
+} from "./chunk-DNB4DPM4.js";
 
 // src/core/execution-tree-aggregator.ts
 var ExecutionTreeAggregator;
@@ -4125,37 +4125,70 @@ 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 `skills` as a JSON",
+    "array of skill-name strings \u2014 NOT a string of a JSON-encoded array.",
+    'Right: `{"skills": ["alpha"]}` or `{"skills": ["alpha", "beta"]}`.',
+    'Wrong: `{"skills": "[\\"alpha\\"]"}` (the value is a string, not an array).',
+    "**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");
+  const examples = [];
+  if (skillNames.length >= 1) {
+    examples.push({
+      params: { skills: [skillNames[0]] },
+      comment: "Single-skill call \u2014 `skills` is still an array of length 1."
+    });
+  }
+  if (skillNames.length >= 2) {
+    examples.push({
+      params: { skills: [skillNames[0], skillNames[1]] },
+      comment: "Multi-skill call \u2014 load several skills in one shot to avoid round-trips."
+    });
+  }
   return createGadget({
     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."
+      )
     }),
-    // LoadSkill exists specifically so the agent can keep a skill body in
-    // context for the rest of the task — marking its results sticky lets the
-    // compaction layer preserve them past truncation. Without this the agent
-    // gets the skill body once, compaction drops it, and the next iteration
-    // falls back to stale training knowledge of whatever the skill covered.
     stickyResult: true,
-    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;
+    iterationBarrier: true,
+    examples,
+    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);
     }
   });
 }
@@ -15722,7 +15755,7 @@ var init_agent = __esm({
         }
         const unsubscribeBridge = bridgeTreeToHooks(this.tree, this.hooks, this.logger);
         if (this.mcpSpecs.length > 0) {
-          const { setupMcpServers } = await import("./runtime-LKTAP7X6.js");
+          const { setupMcpServers } = await import("./runtime-KB7US2FQ.js");
           this.mcpLifecycle = await setupMcpServers({
             specs: this.mcpSpecs,
             registry: this.registry,