@stigmer/runner 3.12.2 → 3.12.3

package/dist/middleware/tool-intent.js

@@ -0,0 +1,152 @@
+/**
+ * Tool-intent middleware — model-authored intent titles for shell tool calls
+ * (issue #276).
+ *
+ * The thread UI titles every shell row with the bare category label ("Shell");
+ * only the model knows *why* it is running a command, so a host-side rename
+ * can never close that gap. This middleware lets the model author the title:
+ * at model-call time it presents a schema-extended clone of the shell tool
+ * that adds one optional `description` argument. The model fills it in, the
+ * argument rides the tool call's args verbatim through checkpoints and the
+ * persisted ToolCall proto (no new state, no proto change), and the React SDK
+ * renders it as the row title with the command as secondary text.
+ *
+ * Why this seam:
+ * - The `execute` tool is owned by the deepagents library; its schema is not
+ *   ours to edit. `wrapModelCall` is the framework's intended point for
+ *   reshaping the model-visible tool list — langchain's own llmToolSelector
+ *   middleware swaps `request.tools` through exactly this hook.
+ * - Execution is untouched by construction: the agent's ToolNode is built
+ *   once from the ORIGINAL tools, and the original schema parses with strip
+ *   semantics, so the extra argument is dropped before the backend's
+ *   `execute(command)` ever runs. Approval fingerprints are equally
+ *   unaffected (`description` is not a salient arg field).
+ * - The argument name deliberately matches the Cursor harness, whose built-in
+ *   Shell tool already carries a model-authored `description` — both
+ *   harnesses converge on one wire key and the SDK reads a single field.
+ *
+ * The swapped-in declaration is a `StructuredToolParams` object — langchain's
+ * first-class shape for a non-executable, bind-time-only tool definition
+ * ("the most minimal interface … to be passed to a LLM for tool calling").
+ * A same-name RUNNABLE replacement is rejected by the agent's wrapModelCall
+ * validation (it would threaten ToolNode execution identity); a params
+ * object is exactly the declaration-without-execution the validation exists
+ * to protect, and the graph keeps executing the untouched original. Schema
+ * extension happens at the JSON-schema level via @langchain/core's interop
+ * serializer — the runner's zod (v3) must never construct fields inside the
+ * library's zod (v4) schema object.
+ */
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool } from "../shared/tool-kind.js";
+/**
+ * The wire name of the intent argument. Shared with the Cursor harness's
+ * built-in Shell tool and read by the SDK's tool presentation layer — the
+ * three surfaces must agree on this key.
+ */
+export const INTENT_ARG = "description";
+/**
+ * The behavior-shaping prompt for the intent argument (owner-approved
+ * wording, issue #276). This is prompt engineering, not documentation:
+ * changing it changes what the model writes into every shell row title.
+ */
+export const INTENT_ARG_PROMPT = "A short present-tense phrase describing what this command does and why, " +
+    "shown to the user as the title of this action (5-10 words, e.g. " +
+    "'Run unit tests for the parser'). Do not restate the command syntax.";
+function isStructuredToolLike(candidate) {
+    if (candidate == null || typeof candidate !== "object")
+        return false;
+    const t = candidate;
+    return (typeof t.name === "string" &&
+        typeof t.description === "string" &&
+        "schema" in t);
+}
+function isJsonObjectSchema(schema) {
+    return (schema != null &&
+        typeof schema === "object" &&
+        schema.type === "object");
+}
+/**
+ * Returns a bind-time `StructuredToolParams` declaration for `original`
+ * whose schema carries the optional intent argument, or `original` itself
+ * when the tool is not a shell tool, is not schema-extendable, or already
+ * defines an argument with that name (a real argument must never be
+ * shadowed by presentation metadata).
+ *
+ * Unexpected schemas pass through unchanged on purpose: a missing intent
+ * title degrades to today's rendering, while a mangled schema would break
+ * the tool for the whole execution.
+ */
+function maybeExtendShellTool(original) {
+    if (!isStructuredToolLike(original))
+        return original;
+    if (classifyTool(original.name) !== ToolKind.SHELL)
+        return original;
+    let jsonSchema;
+    try {
+        jsonSchema = toJsonSchema(original.schema);
+    }
+    catch {
+        return original;
+    }
+    if (!isJsonObjectSchema(jsonSchema))
+        return original;
+    const properties = jsonSchema.properties ?? {};
+    if (INTENT_ARG in properties)
+        return original;
+    // A plain frozen declaration, deliberately NOT an executable tool: the
+    // graph's ToolNode executes the ORIGINAL registered tool (it is built from
+    // the registered tools, not from the model request), and the agent's
+    // wrapModelCall validation only forbids swapping same-name EXECUTABLE
+    // instances. `isStructuredToolParams` recognizes this shape, so every
+    // provider's bindTools converts it exactly like a structured tool.
+    return Object.freeze({
+        name: original.name,
+        description: original.description,
+        schema: {
+            ...jsonSchema,
+            properties: {
+                ...properties,
+                [INTENT_ARG]: { type: "string", description: INTENT_ARG_PROMPT },
+            },
+        },
+    });
+}
+/**
+ * Creates the middleware. Install on the parent stack AND on every sub-agent
+ * stack (subagent-wiring.ts) — sub-agent shell rows render in the same
+ * thread and must carry the same titles.
+ */
+export function createToolIntentMiddleware() {
+    // One clone per original tool instance: repeated model calls (and repeated
+    // turns on the same graph) bind a referentially stable clone instead of
+    // re-serializing the schema every round.
+    const cloneCache = new WeakMap();
+    const extendCached = (candidate) => {
+        if (candidate == null || typeof candidate !== "object")
+            return candidate;
+        const cached = cloneCache.get(candidate);
+        if (cached !== undefined)
+            return cached;
+        const extended = maybeExtendShellTool(candidate);
+        cloneCache.set(candidate, extended);
+        return extended;
+    };
+    return {
+        name: "StigmerToolIntentMiddleware",
+        async wrapModelCall(request, handler) {
+            const tools = request.tools;
+            if (!tools || tools.length === 0)
+                return handler(request);
+            let changed = false;
+            const mapped = tools.map((t) => {
+                const extended = extendCached(t);
+                if (extended !== t)
+                    changed = true;
+                return extended;
+            });
+            return handler(changed ? { ...request, tools: mapped } : request);
+        },
+    };
+}
+//# sourceMappingURL=tool-intent.js.map

package/dist/middleware/tool-intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-intent.js","sourceRoot":"","sources":["../../src/middleware/tool-intent.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.12.2",
+  "version": "3.12.3",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -90,7 +90,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.12.2",
+    "@stigmer/protos": "3.12.3",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/common": "^1.11.0",
     "@temporalio/interceptors-opentelemetry": "~1.16.0",

package/src/activities/execute-cursor/__tests__/skill-resolver.test.ts

@@ -2,9 +2,17 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { resolveSkills } from "../skill-resolver.js";
+import { ConnectError, Code } from "@connectrpc/connect";
+import { resolveSkills, downloadArtifact } from "../skill-resolver.js";
 import { buildZip } from "../../../__test-utils__/zip-fixtures.js";
 
+/** A server that predates the transfer lane (#675) answers the mint RPC
+ * with UNIMPLEMENTED — the default posture for these tests, which keeps
+ * every pre-existing case pinned to the unary getSkillArtifact fallback. */
+function unimplementedMint() {
+  return vi.fn().mockRejectedValue(new ConnectError("unimplemented", Code.Unimplemented));
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
 function makeTempDir(prefix: string): string {
@@ -73,6 +81,7 @@ describe("resolveSkills — artifact extraction", () => {
     const client = {
       getSkillByReference: vi.fn(),
       getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
+      getSkillArtifactDownloadUrl: unimplementedMint(),
       ...clientOverrides,
     } as any;
 
@@ -380,3 +389,97 @@ describe("resolveSkills — artifact extraction", () => {
     }
   });
 });
+
+// ─── downloadArtifact — transfer lane routing (#675) ─────────────────────
+
+describe("downloadArtifact — transfer lane routing", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function makeClient(overrides: Record<string, any> = {}) {
+    return {
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
+      getSkillArtifactDownloadUrl: unimplementedMint(),
+      ...overrides,
+    } as any;
+  }
+
+  it("fetches bytes over HTTP when the server mints a download URL", async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
+        sizeBytes: 5n,
+        ttlSeconds: 0,
+      }),
+    });
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => bytes.buffer,
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const got = await downloadArtifact(client, "skills/abc.zip");
+
+    expect(got).toEqual(bytes);
+    expect(fetchMock).toHaveBeenCalledWith("http://localhost:7234/v1/skill-artifacts/skills/abc.zip");
+    // The unary lane (10MB-capped) must not be touched when the URL lane works.
+    expect(client.getSkillArtifact).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the unary RPC when the server predates the lane", async () => {
+    const bytes = new Uint8Array([9, 9]);
+    const client = makeClient({
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: bytes }),
+    });
+    vi.stubGlobal("fetch", vi.fn()); // must never be called
+
+    const got = await downloadArtifact(client, "skills/abc.zip");
+
+    expect(got).toEqual(bytes);
+    expect(client.getSkillArtifact).toHaveBeenCalledWith("skills/abc.zip");
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("does NOT fall back on non-Unimplemented mint failures", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockRejectedValue(
+        new ConnectError("boom", Code.Internal),
+      ),
+    });
+
+    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow("boom");
+    // Falling back here would mask real server faults behind the capped lane.
+    expect(client.getSkillArtifact).not.toHaveBeenCalled();
+  });
+
+  it("rejects truncated fetches via the minted size", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/abc.zip",
+        sizeBytes: 100n,
+        ttlSeconds: 0,
+      }),
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+    }));
+
+    await expect(downloadArtifact(client, "skills/abc.zip")).rejects.toThrow(/truncated/);
+  });
+
+  it("surfaces HTTP failures with the status code", async () => {
+    const client = makeClient({
+      getSkillArtifactDownloadUrl: vi.fn().mockResolvedValue({
+        url: "http://localhost:7234/v1/skill-artifacts/skills/gone.zip",
+        sizeBytes: 0n,
+        ttlSeconds: 0,
+      }),
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: false, status: 404 }));
+
+    await expect(downloadArtifact(client, "skills/gone.zip")).rejects.toThrow(/HTTP 404/);
+  });
+});

package/src/activities/execute-cursor/skill-resolver.ts

@@ -19,6 +19,7 @@
 
 import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -115,14 +116,15 @@ export async function resolveSkills(
       let artifactBytes: Uint8Array | undefined;
       if (wantsArtifact) {
         try {
-          const resp = await client.getSkillArtifact(skill.status!.artifactStorageKey);
-          if (resp.artifact && resp.artifact.length > 0) {
-            artifactBytes = resp.artifact;
-          }
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
         } catch (err) {
-          console.warn(
-            `[resolveSkills] artifact download failed for ${ref.slug}, ` +
-            `falling back to SKILL.md only: ${err instanceof Error ? err.message : err}`,
+          // Deliberate degradation, but LOUD (#675): the session still gets
+          // SKILL.md (better than a dead run), yet a skill silently missing
+          // its scripts/references was exactly how oversized artifacts hid.
+          console.error(
+            `[resolveSkills] artifact download FAILED for ${ref.org || "(default)"}/${ref.slug} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
           );
         }
       }
@@ -161,6 +163,48 @@ async function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact
   }
 }
 
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (#672's hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ *
+ * Exported for tests.
+ */
+export async function downloadArtifact(
+  client: StigmerClient,
+  artifactStorageKey: string,
+): Promise<Uint8Array | undefined> {
+  let minted;
+  try {
+    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      const resp = await client.getSkillArtifact(artifactStorageKey);
+      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url);
+  if (!resp.ok) {
+    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+  }
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+    throw new Error(
+      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
+    );
+  }
+  return bytes.length > 0 ? bytes : undefined;
+}
+
 /**
  * (Re)write a skill's mount directory from scratch.
  *

package/src/activities/execute-deep-agent/__test-utils__/scripted-model.ts

@@ -50,11 +50,20 @@ export type ScriptSelector = (boundToolNames: string[]) => ScriptStep;
  */
 export class ScriptedModel extends BaseChatModel {
   toolNames: string[] = [];
+  /**
+   * The tool objects from the most recent `bindTools` call, exactly as the
+   * agent bound them (post-middleware). Lets tests assert on the bound
+   * SCHEMAS — e.g. the tool-intent middleware's bind-time shell clone — not
+   * just the names. The array is shared across the clones `bindTools`
+   * returns, so the instance the test holds always sees the latest bind.
+   */
+  readonly boundTools: unknown[];
   private readonly select: ScriptSelector;
 
-  constructor(select: ScriptSelector) {
+  constructor(select: ScriptSelector, boundTools: unknown[] = []) {
     super({});
     this.select = select;
+    this.boundTools = boundTools;
   }
 
   _llmType(): string {
@@ -62,8 +71,10 @@ export class ScriptedModel extends BaseChatModel {
   }
 
   bindTools(tools: unknown[]): this {
-    const next = new ScriptedModel(this.select);
+    const next = new ScriptedModel(this.select, this.boundTools);
     next.toolNames = (tools as Array<{ name?: string }>).map((t) => t?.name ?? "");
+    this.boundTools.length = 0;
+    this.boundTools.push(...tools);
     return next as unknown as this;
   }
 

package/src/activities/execute-deep-agent/__tests__/subagent-wiring.test.ts

@@ -7,11 +7,12 @@ describe("buildSubAgentMiddleware", () => {
   it("returns the correct middleware order without cost cap", () => {
     const stack = buildSubAgentMiddleware();
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack[0].name).toBe("LoopDetectionMiddleware");
     expect(stack[1].name).toBe("ExecutionBudgetMiddleware");
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
-    expect(stack[3].name).toBe("ErrorHintsMiddleware");
+    expect(stack[2].name).toBe("StigmerToolIntentMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
+    expect(stack[4].name).toBe("ErrorHintsMiddleware");
   });
 
   it("includes cost cap view when parent cost cap is provided", () => {
@@ -25,9 +26,9 @@ describe("buildSubAgentMiddleware", () => {
 
     const stack = buildSubAgentMiddleware({ costCap: parentCostCap });
 
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("CostCapSubAgentView");
-    expect(stack[4].name).toBe("ErrorHintsMiddleware");
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("CostCapSubAgentView");
+    expect(stack[5].name).toBe("ErrorHintsMiddleware");
   });
 
   it("sub-agent cost cap view shares parent state", () => {
@@ -43,7 +44,7 @@ describe("buildSubAgentMiddleware", () => {
 
     expect(parentCostCap.runningCost).toBe(0);
 
-    const subView = stack[3];
+    const subView = stack[4];
     expect(subView.afterModel).toBeDefined();
     expect(subView.wrapToolCall).toBeDefined();
     expect(subView.beforeAgent).toBeUndefined();
@@ -69,7 +70,7 @@ describe("buildSubAgentMiddleware", () => {
       toolTruncation: { maxChars: 5000 },
     });
 
-    expect(stack[2].name).toBe("ToolTruncationMiddleware");
+    expect(stack[3].name).toBe("ToolTruncationMiddleware");
   });
 
   it("installs the approval gate when an approvalGate config is provided", () => {
@@ -77,16 +78,16 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, error hints
-    expect(stack).toHaveLength(5);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[3].wrapToolCall).toBeDefined();
+    // loop, budget, tool intent, truncation, approval gate, error hints
+    expect(stack).toHaveLength(6);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[4].wrapToolCall).toBeDefined();
   });
 
   it("omits the approval gate when approvalGate is null (auto-approve-all parity)", () => {
     const stack = buildSubAgentMiddleware({ approvalGate: null });
 
-    expect(stack).toHaveLength(4);
+    expect(stack).toHaveLength(5);
     expect(stack.some((m) => m.name === "ApprovalGateMiddleware")).toBe(false);
   });
 
@@ -104,13 +105,13 @@ describe("buildSubAgentMiddleware", () => {
       approvalGate: { policies: new Map(), toolServerMap: new Map() },
     });
 
-    // loop, budget, truncation, approval gate, cost cap view, error hints.
-    // Hints AFTER the gate matches the parent nesting: the gate's HITL
-    // interrupt stays outside the hints' try/catch (issue #255).
-    expect(stack).toHaveLength(6);
-    expect(stack[3].name).toBe("ApprovalGateMiddleware");
-    expect(stack[4].name).toBe("CostCapSubAgentView");
-    expect(stack[5].name).toBe("ErrorHintsMiddleware");
+    // loop, budget, tool intent, truncation, approval gate, cost cap view,
+    // error hints. Hints AFTER the gate matches the parent nesting: the
+    // gate's HITL interrupt stays outside the hints' try/catch (issue #255).
+    expect(stack).toHaveLength(7);
+    expect(stack[4].name).toBe("ApprovalGateMiddleware");
+    expect(stack[5].name).toBe("CostCapSubAgentView");
+    expect(stack[6].name).toBe("ErrorHintsMiddleware");
   });
 
   // captureIgnored is the structural coupling that makes sub-agent gitignored

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -9,6 +9,9 @@
  *   same `permissions` option it bakes into the graph, keeping the rules
  *   and their normalization shim coupled.
  * - Fresh loop detection (independent cycle tracking)
+ * - Tool intent (issue #276) — the shell tool's bind-time schema gains the
+ *   optional model-authored `description`, so sub-agent shell rows carry
+ *   intent titles exactly like the parent's
  * - Fresh tool truncation (same limits as parent)
  * - Periodic execution budget (interval=30, max=4 advisories)
  * - Approval gate (so a mutating tool *inside* a sub-agent is gated, not
@@ -43,6 +46,7 @@ import { createPathNormalizationMiddleware } from "../../middleware/path-normali
 import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
 import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
 import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import { createToolIntentMiddleware } from "../../middleware/tool-intent.js";
 import {
   createApprovalGateMiddleware,
   type ApprovalGateConfig,
@@ -83,7 +87,8 @@ export interface SubAgentMiddlewareOptions {
  *
  * Returns an ordered array mirroring the parent composition:
  * [path normalization] → loop detection → execution budget (periodic) →
- * tool truncation → [approval gate] → cost cap view → error hints.
+ * tool intent → tool truncation → [approval gate] → cost cap view →
+ * error hints.
  * Normalization is outermost so everything downstream observes canonical
  * workspace-absolute paths (matching the parent). The gate sits before the
  * cost-cap view so an approval pause happens before budget accounting, and
@@ -107,6 +112,10 @@ export function buildSubAgentMiddleware(
     maxWarnings: SUB_AGENT_MAX_ADVISORIES,
   }));
 
+  // Sub-agent shell rows render in the same thread as the parent's and must
+  // carry the same model-authored intent titles (issue #276).
+  stack.push(createToolIntentMiddleware());
+
   stack.push(createToolTruncationMiddleware(options.toolTruncation));
 
   if (options.approvalGate) {

package/src/client/stigmer-client.ts

@@ -35,7 +35,7 @@ import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinst
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { GetArtifactResponse } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { GetArtifactResponse, SkillArtifactDownloadUrl } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { create } from "@bufbuild/protobuf";
 import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
@@ -583,6 +583,17 @@ export class StigmerClient {
     return this.skillQuery.getArtifact({ artifactStorageKey });
   }
 
+  /**
+   * Mint an HTTP download URL for a skill artifact (#675). Preferred over
+   * getSkillArtifact for the actual bytes: the unary response is capped by
+   * the server's 10MB gRPC message limit, while skills may be 100MB.
+   * Throws ConnectError with Code.Unimplemented against servers that
+   * predate the transfer lane — callers fall back to getSkillArtifact.
+   */
+  async getSkillArtifactDownloadUrl(artifactStorageKey: string): Promise<SkillArtifactDownloadUrl> {
+    return this.skillQuery.getArtifactDownloadUrl({ artifactStorageKey });
+  }
+
   async createArtifact(input: CreateArtifactInput): Promise<Artifact> {
     return this.artifactCommand.create(input);
   }