@stigmer/sdk 3.12.2 → 3.12.4

package/skill.js

@@ -0,0 +1,102 @@
+import { create } from "@bufbuild/protobuf";
+import { Code } from "@connectrpc/connect";
+import { CreateSkillArtifactUploadUrlRequestSchema, PushSkillRequestSchema, } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { isUnimplemented, StigmerError } from "./gen/errors.js";
+import { SkillClient } from "./gen/skill.js";
+/**
+ * Largest artifact pushed inline in the gRPC request (#675). The server's
+ * transport cap is 10MB for the WHOLE message, so the artifact leaves 64KB
+ * of headroom for the request envelope (org, tag, provenance, framing).
+ * Mirrors the Go SDK's maxInlineArtifactBytes.
+ */
+export const MAX_INLINE_ARTIFACT_BYTES = 10 * 1024 * 1024 - 64 * 1024;
+/**
+ * Skill client with transport-aware push routing (stigmer#675 / #701).
+ *
+ * The gRPC transport caps messages at 10MB while skills may be up to 100MB,
+ * so `push` routes by size: small artifacts travel inline in the request
+ * (one round trip, unchanged behavior), larger ones are staged over HTTP
+ * via `createArtifactUploadUrl` — a capability URL, so no auth header —
+ * and pushed by reference. Callers never see the mechanics: `push(req)`
+ * simply works for any valid skill size.
+ *
+ * Every other method is the generated client's, inherited unchanged.
+ */
+export class RoutedSkillClient extends SkillClient {
+    fetchImpl;
+    /**
+     * @param fetchImpl - Custom `fetch` for the staging PUT. Must be the same
+     *   implementation the transport uses where the global one is restricted
+     *   (the Tauri CSP/CORS case the `Stigmer.fetch` property documents).
+     */
+    constructor(transport, fetchImpl) {
+        super(transport);
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * Push a skill, routing the artifact by size (see the class comment).
+     *
+     * A request that already carries an `artifactUploadRef` is passed through
+     * untouched — the caller has done its own staging.
+     */
+    async push(input) {
+        if (input.artifactUploadRef !== "" || input.artifact.length <= MAX_INLINE_ARTIFACT_BYTES) {
+            return super.push(input);
+        }
+        return this.pushViaUploadUrl(input);
+    }
+    /**
+     * Stage the artifact over HTTP and push by reference:
+     * createArtifactUploadUrl → PUT bytes → push(artifactUploadRef).
+     */
+    async pushViaUploadUrl(input) {
+        let minted;
+        try {
+            minted = await super.createArtifactUploadUrl(create(CreateSkillArtifactUploadUrlRequestSchema, {
+                org: input.org,
+                sizeBytes: BigInt(input.artifact.length),
+            }));
+        }
+        catch (err) {
+            if (isUnimplemented(err)) {
+                // Pre-transfer-lane server: without staging, an artifact this size
+                // physically cannot travel. Say so instead of surfacing the raw
+                // transport error (the failure mode #675 reported).
+                throw new StigmerError("unknown", `skill artifact is ${input.artifact.length} bytes, above the ~10MB gRPC message cap, ` +
+                    "and this server does not support the HTTP artifact transfer lane — " +
+                    "upgrade stigmer-server to push skills of this size", Code.Unimplemented, { cause: err });
+            }
+            throw err;
+        }
+        await this.putArtifact(minted.url, input.artifact);
+        // Same request, artifact traveling by reference instead of by value.
+        const byRef = create(PushSkillRequestSchema, {
+            ...input,
+            artifact: new Uint8Array(0),
+            artifactUploadRef: minted.artifactUploadRef,
+        });
+        return super.push(byRef);
+    }
+    /**
+     * PUT the artifact ZIP to the staging URL. The URL is the credential
+     * (capability semantics — a pre-signed R2 URL on cloud, the server's own
+     * transfer lane on OSS), so no auth header is attached.
+     */
+    async putArtifact(url, artifact) {
+        const doFetch = this.fetchImpl ?? globalThis.fetch;
+        const resp = await doFetch(url, {
+            method: "PUT",
+            // Both DOM and undici accept an ArrayBufferView body at runtime; the
+            // cast bridges TS 5.7's ArrayBufferLike generic, which BodyInit's
+            // typing predates. A Blob/Buffer wrapper would copy up to 100MB for
+            // nothing, and Buffer is Node-only while this client is isomorphic.
+            body: artifact,
+            headers: { "content-type": "application/zip" },
+        });
+        if (!resp.ok) {
+            const detail = (await resp.text().catch(() => "")).slice(0, 512).trim();
+            throw new StigmerError("unknown", `skill artifact upload rejected with HTTP ${resp.status}${detail === "" ? "" : `: ${detail}`}`, Code.Unknown);
+        }
+    }
+}
+//# sourceMappingURL=skill.js.map

package/skill.js.map

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

package/src/__tests__/billing.test.ts

@@ -12,6 +12,7 @@ import { BillingQueryController } from "@stigmer/protos/ai/stigmer/billing/v1/qu
 import {
   CreditLedgerResponseSchema,
   type AdjustCreditsInput,
+  type GrantCreditsInput,
   type GetCreditLedgerInput,
 } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
 import { CreditLedgerEntrySchema } from "@stigmer/protos/ai/stigmer/billing/v1/credit_pb";
@@ -20,6 +21,7 @@ import { BillingClient } from "../billing.js";
 
 interface Captured {
   adjustCredits?: AdjustCreditsInput;
+  grantCredits?: GrantCreditsInput;
   getCreditLedger?: GetCreditLedgerInput;
 }
 
@@ -30,6 +32,10 @@ function fakeTransport(captured: Captured): Transport {
         captured.adjustCredits = req;
         return create(CreditLedgerEntrySchema, { amountMicros: req.amountMicros });
       },
+      grantCredits: (req) => {
+        captured.grantCredits = req;
+        return create(CreditLedgerEntrySchema, { amountMicros: req.amountMicros });
+      },
     });
     service(BillingQueryController, {
       getCreditLedger: (req) => {
@@ -60,6 +66,44 @@ describe("BillingClient.adjustCredits", () => {
   });
 });
 
+describe("BillingClient.grantCredits", () => {
+  it("maps params including the expiry onto GrantCreditsInput", async () => {
+    const captured: Captured = {};
+    const client = new BillingClient(fakeTransport(captured));
+
+    const expiresAt = new Date("2026-08-31T23:59:59Z");
+    const entry = await client.grantCredits({
+      orgId: "acme",
+      amountMicros: 5_000_000n,
+      expiresAt,
+      reason: "monthly free allowance 2026-08",
+      idempotencyKey: "allowance-acme-2026-08",
+    });
+
+    expect(entry.amountMicros).toBe(5_000_000n);
+    const req = captured.grantCredits;
+    expect(req?.orgId).toBe("acme");
+    expect(req?.amountMicros).toBe(5_000_000n);
+    expect(req?.expiresAt && timestampDate(req.expiresAt)).toEqual(expiresAt);
+    expect(req?.reason).toBe("monthly free allowance 2026-08");
+    expect(req?.idempotencyKey).toBe("allowance-acme-2026-08");
+  });
+
+  it("omits the expiry for a never-expiring grant", async () => {
+    const captured: Captured = {};
+    const client = new BillingClient(fakeTransport(captured));
+
+    await client.grantCredits({
+      orgId: "acme",
+      amountMicros: 1_000_000n,
+      reason: "welcome credit",
+      idempotencyKey: "welcome-acme",
+    });
+
+    expect(captured.grantCredits?.expiresAt).toBeUndefined();
+  });
+});
+
 describe("BillingClient.getCreditLedger", () => {
   it("maps all filters including the time range", async () => {
     const captured: Captured = {};

package/src/__tests__/skill.test.ts

@@ -0,0 +1,150 @@
+// Wire-shape tests for RoutedSkillClient's size-routed push (stigmer#701).
+// A router transport fakes the skill service in-process, so the routing is
+// exercised through the REAL generated client and its error wrapping — the
+// CLI's earlier copy of this logic keyed its fallback on `instanceof
+// ConnectError`, which the SDK's wrapError made unreachable; these pins run
+// the wrapped path. Mirrors sdk/go/skill_test.go's five routing pins.
+import { describe, expect, it, vi } from "vitest";
+import { Code, ConnectError, createRouterTransport, type Transport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import {
+  PushSkillRequestSchema,
+  SkillArtifactUploadUrlSchema,
+  type PushSkillRequest,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { StigmerError } from "../gen/errors.js";
+import { MAX_INLINE_ARTIFACT_BYTES, RoutedSkillClient } from "../skill.js";
+
+const STAGING_URL = "http://stage.example/v1/skill-artifacts/uploads/sau_t";
+
+interface Captured {
+  pushes: PushSkillRequest[];
+  mints: number;
+}
+
+/**
+ * In-process skill service. `withMint: false` leaves createArtifactUploadUrl
+ * unregistered, so the router answers Unimplemented — the exact wire shape
+ * of a pre-transfer-lane server.
+ */
+function fakeTransport(captured: Captured, opts: { withMint: boolean } = { withMint: true }): Transport {
+  return createRouterTransport(({ service }) => {
+    service(SkillCommandController, {
+      push: (req) => {
+        captured.pushes.push(req);
+        return create(SkillSchema, {});
+      },
+      ...(opts.withMint
+        ? {
+            createArtifactUploadUrl: (req) => {
+              captured.mints++;
+              expect(req.sizeBytes).toBeGreaterThan(0n);
+              return create(SkillArtifactUploadUrlSchema, {
+                url: STAGING_URL,
+                artifactUploadRef: "sau_t",
+                ttlSeconds: 900,
+              });
+            },
+          }
+        : {}),
+    });
+  });
+}
+
+function okFetch(record: { putUrl?: string; putBytes?: number; contentType?: string }) {
+  return vi.fn(async (url: any, init: any) => {
+    record.putUrl = String(url);
+    record.putBytes = init.body instanceof Uint8Array ? init.body.byteLength : -1;
+    record.contentType = init.headers["content-type"];
+    return new Response(null, { status: 200 });
+  }) as unknown as typeof globalThis.fetch;
+}
+
+describe("RoutedSkillClient.push size routing", () => {
+  it("keeps small artifacts inline — no mint, bytes in the request", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const client = new RoutedSkillClient(fakeTransport(captured));
+
+    await client.push(create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(1024) }));
+
+    expect(captured.mints).toBe(0);
+    expect(captured.pushes).toHaveLength(1);
+    expect(captured.pushes[0].artifact.length).toBe(1024);
+  });
+
+  it("stages large artifacts over HTTP and pushes by reference, preserving the envelope", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const record: { putUrl?: string; putBytes?: number; contentType?: string } = {};
+    const client = new RoutedSkillClient(fakeTransport(captured), okFetch(record));
+    const artifact = new Uint8Array(MAX_INLINE_ARTIFACT_BYTES + 1);
+
+    await client.push(create(PushSkillRequestSchema, { org: "acme", artifact, tag: "stable", message: "big" }));
+
+    expect(captured.mints).toBe(1);
+    expect(record.putUrl).toBe(STAGING_URL);
+    expect(record.putBytes).toBe(artifact.length);
+    expect(record.contentType).toBe("application/zip");
+    expect(captured.pushes).toHaveLength(1);
+    expect(captured.pushes[0].artifact.length).toBe(0);
+    expect(captured.pushes[0].artifactUploadRef).toBe("sau_t");
+    // The by-ref rewrite must not lose the rest of the request.
+    expect(captured.pushes[0].tag).toBe("stable");
+    expect(captured.pushes[0].message).toBe("big");
+  });
+
+  it("passes an explicit upload ref through untouched — the caller staged it", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const client = new RoutedSkillClient(fakeTransport(captured));
+
+    await client.push(create(PushSkillRequestSchema, { org: "acme", artifactUploadRef: "sau_mine" }));
+
+    expect(captured.mints).toBe(0);
+    expect(captured.pushes).toHaveLength(1);
+    expect(captured.pushes[0].artifactUploadRef).toBe("sau_mine");
+  });
+
+  it("fails loud against servers that predate the transfer lane (wrapped Unimplemented)", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const client = new RoutedSkillClient(fakeTransport(captured, { withMint: false }));
+
+    await expect(
+      client.push(create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(MAX_INLINE_ARTIFACT_BYTES + 1) })),
+    ).rejects.toThrow(/upgrade stigmer-server/);
+    expect(captured.pushes).toHaveLength(0);
+  });
+
+  it("surfaces the staging rejection body and never proceeds to push", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const rejectingFetch = (async () =>
+      new Response("staging slot expired", { status: 404 })) as unknown as typeof globalThis.fetch;
+    const client = new RoutedSkillClient(fakeTransport(captured), rejectingFetch);
+
+    await expect(
+      client.push(create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(MAX_INLINE_ARTIFACT_BYTES + 1) })),
+    ).rejects.toThrow(/HTTP 404: staging slot expired/);
+    expect(captured.pushes).toHaveLength(0);
+  });
+
+  it("propagates non-Unimplemented mint errors unmasked", async () => {
+    const captured: Captured = { pushes: [], mints: 0 };
+    const transport = createRouterTransport(({ service }) => {
+      service(SkillCommandController, {
+        push: (req) => {
+          captured.pushes.push(req);
+          return create(SkillSchema, {});
+        },
+        createArtifactUploadUrl: () => {
+          throw new ConnectError("artifact too large", Code.InvalidArgument);
+        },
+      });
+    });
+    const client = new RoutedSkillClient(transport);
+
+    await expect(
+      client.push(create(PushSkillRequestSchema, { org: "acme", artifact: new Uint8Array(MAX_INLINE_ARTIFACT_BYTES + 1) })),
+    ).rejects.toSatisfy((err: unknown) => err instanceof StigmerError && err.code === "invalid-argument");
+    expect(captured.pushes).toHaveLength(0);
+  });
+});

package/src/billing.ts

@@ -7,6 +7,7 @@ import {
   GetBillingAccountInputSchema,
   GetCreditBalanceInputSchema,
   AdjustCreditsInputSchema,
+  GrantCreditsInputSchema,
   GetCreditLedgerInputSchema,
   CreateCreditCheckoutSessionInputSchema,
   CreateBillingPortalSessionInputSchema,
@@ -69,6 +70,22 @@ export interface AdjustCreditsParams {
   readonly idempotencyKey: string;
 }
 
+/** Parameters for a promotional credit grant. */
+export interface GrantCreditsParams {
+  readonly orgId: string;
+  /** Amount to grant. Must be positive; grants never remove credits. */
+  readonly amountMicros: bigint;
+  /**
+   * When the grant expires (use-it-or-lose-it). Omit for a grant that never
+   * expires. Precision is whole seconds; sub-second precision is discarded.
+   */
+  readonly expiresAt?: Date;
+  /** Human-readable reason recorded on the ledger entry (audit trail). */
+  readonly reason: string;
+  /** Client-supplied deduplication key to prevent double-processing. */
+  readonly idempotencyKey: string;
+}
+
 /** Parameters for querying the credit ledger. */
 export interface GetCreditLedgerParams {
   readonly orgId: string;
@@ -222,6 +239,33 @@ export class BillingClient {
     }
   }
 
+  /**
+   * Grant promotional credits to an organization, optionally expiring
+   * (use-it-or-lose-it).
+   *
+   * The grant burns before adjustment and purchased credits. When
+   * `expiresAt` is set, any remainder unconsumed at that time is removed
+   * from the balance by the platform's grant-expiry sweep. Idempotent:
+   * replaying an applied idempotency key returns the original ledger entry,
+   * even after the expiry has passed. Requires `can_manage_billing` on
+   * the org.
+   */
+  async grantCredits(params: GrantCreditsParams): Promise<CreditLedgerEntry> {
+    try {
+      return await this.command.grantCredits(
+        create(GrantCreditsInputSchema, {
+          orgId: params.orgId,
+          amountMicros: params.amountMicros,
+          reason: params.reason,
+          idempotencyKey: params.idempotencyKey,
+          ...(params.expiresAt && { expiresAt: timestampFromDate(params.expiresAt) }),
+        }),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+
   /** Retrieve paginated credit ledger entries with optional filters. */
   async getCreditLedger(params: GetCreditLedgerParams): Promise<CreditLedgerResponse> {
     try {

package/src/errors.ts

@@ -11,6 +11,7 @@ export {
   isUnauthenticated,
   isPermissionDenied,
   isRetryable,
+  isUnimplemented,
 } from "./gen/errors.js";
 
 /**

package/src/execution/__tests__/tool-view.fixtures.test.ts

@@ -1,6 +1,7 @@
-// Validates the tool-view layer against the shared cross-language contract in
-// test/fixtures/tool-view/. The Go CLI runs the same fixtures, so the two
-// surfaces cannot drift in classification or result interpretation.
+// Validates the tool-view layer against the shared cross-surface contract in
+// test/fixtures/tool-view/. The runner's middleware tests assert the same
+// fixtures from the writer side, so producers and this reader cannot drift in
+// classification, result interpretation, or intent extraction.
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -9,7 +10,13 @@ import { describe, it, expect } from "vitest";
 import { create, type JsonObject } from "@bufbuild/protobuf";
 import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { ToolKind, resolveToolKindByName, normalizeToolResult } from "../tool-view";
+import {
+  ToolKind,
+  resolveToolKindByName,
+  normalizeToolResult,
+  extractShellIntent,
+  SHELL_INTENT_ARG_FIELD,
+} from "../tool-view";
 
 const here = dirname(fileURLToPath(import.meta.url));
 // sdk/typescript/src/execution/__tests__ -> repo root is five levels up.
@@ -115,6 +122,36 @@ describe("result-view fixtures", () => {
   }
 });
 
+describe("intent-title fixtures", () => {
+  interface IntentCase {
+    name: string;
+    mcpServerSlug: string;
+    args: Record<string, unknown>;
+    intent: string | null;
+  }
+
+  const fixture = loadFixture<{ argField: string; cases: IntentCase[] }>(
+    "intent-title.json",
+  );
+
+  it("loads the fixture and agrees on the wire key", () => {
+    expect(fixture.cases.length).toBeGreaterThan(0);
+    expect(SHELL_INTENT_ARG_FIELD).toBe(fixture.argField);
+  });
+
+  for (const c of fixture.cases) {
+    it(`extracts ${c.name}${c.mcpServerSlug ? ` @${c.mcpServerSlug}` : ""} -> ${JSON.stringify(c.intent)}`, () => {
+      const toolCall = create(ToolCallSchema, {
+        id: c.name,
+        name: c.name,
+        mcpServerSlug: c.mcpServerSlug,
+        args: c.args as JsonObject,
+      });
+      expect(extractShellIntent(toolCall)).toBe(c.intent);
+    });
+  }
+});
+
 describe("resolveToolKind wire field precedence", () => {
   it("prefers the wire tool_kind over the name fallback", () => {
     const toolCall = create(ToolCallSchema, {

package/src/execution/tool-view.ts

@@ -228,6 +228,58 @@ export function resolveToolKindByName(name: string, mcpServerSlug?: string): Too
   return ToolKind.UNSPECIFIED;
 }
 
+// ---------------------------------------------------------------------------
+// Intent: extractShellIntent
+// ---------------------------------------------------------------------------
+
+/**
+ * The tool-call argument that carries a model-authored intent phrase for
+ * SHELL tools (stigmer#276) — a short human description of what the command
+ * does and why, rendered as the row title with the command as secondary text.
+ *
+ * Two writers populate it, converged on one wire key by design: the native
+ * harness's tool-intent middleware (`backend/services/runner/src/middleware/
+ * tool-intent.ts`, `INTENT_ARG`) extends the shell tool's bind-time schema
+ * with it, and the Cursor harness's built-in Shell tool carries it natively.
+ * The shared, machine-checked contract is
+ * `test/fixtures/tool-view/intent-title.json` — keep the writers and this
+ * reader in lockstep.
+ */
+export const SHELL_INTENT_ARG_FIELD = "description";
+
+/**
+ * Args-level intent extraction: SHELL-kind-scoped on purpose, because
+ * `description` means other things on other tools (a task tool's description
+ * is the sub-agent subject, never a row title). Blank and non-string values
+ * degrade to null — callers fall back to their category label.
+ *
+ * The seam for surfaces that hold a pre-resolved kind and raw args instead of
+ * a full ToolCall: the CLI's headless snapshot projection and @stigmer/react's
+ * approval argsPreview path. Everything else should prefer
+ * {@link extractShellIntent}.
+ */
+export function shellIntentFromArgs(
+  kind: ToolKind,
+  args: Record<string, unknown> | undefined,
+): string | null {
+  if (kind !== ToolKind.SHELL || !args) return null;
+  const value = args[SHELL_INTENT_ARG_FIELD];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Extracts the model-authored intent phrase from a SHELL tool call, or null
+ * when absent (legacy executions, models that skipped the optional arg, and
+ * every non-shell kind). See {@link SHELL_INTENT_ARG_FIELD}.
+ */
+export function extractShellIntent(
+  toolCall: Pick<ToolCall, "name" | "mcpServerSlug" | "toolKind" | "args">,
+): string | null {
+  return shellIntentFromArgs(resolveToolKind(toolCall), toolCall.args as Args);
+}
+
 // ---------------------------------------------------------------------------
 // Result: normalizeToolResult
 // ---------------------------------------------------------------------------

package/src/gen/client.ts

@@ -136,4 +136,4 @@ export { type WorkflowExecutionInput } from "./workflowexecution.js";
 export { WorkflowInstanceClient } from "./workflowinstance.js";
 export { type WorkflowInstanceInput } from "./workflowinstance.js";
 export { type ListParams, type ListResult, type DeleteResourceInput, type ResourceRef, type EnvSpecInput, type EnvVarInput, type Page } from "./types.js";
-export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable } from "./errors.js";
+export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, isUnimplemented } from "./errors.js";

package/src/gen/errors.ts

@@ -74,3 +74,13 @@ export function isPermissionDenied(err: unknown): boolean {
 export function isRetryable(err: unknown): boolean {
   return err instanceof StigmerError && (err.code === "internal" || err.code === "unavailable");
 }
+
+/**
+ * The server does not implement the called RPC — the code clients key
+ * capability fallbacks on (e.g. the skill artifact transfer lane's unary
+ * fallback, stigmer#675/#701). Checks the raw connect code: Unimplemented
+ * deliberately has no ErrorCode mapping, so it surfaces as "unknown".
+ */
+export function isUnimplemented(err: unknown): boolean {
+  return err instanceof StigmerError && err.connectCode === Code.Unimplemented;
+}

package/src/gen/skill.ts

@@ -7,7 +7,7 @@ import { create } from "@bufbuild/protobuf";
 import { createClient, type Client, type Transport } from "@connectrpc/connect";
 import { SkillSchema, type Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
-import { SkillIdSchema, PushSkillRequestSchema, PushSkillFromExecutionArtifactRequestSchema, GetArtifactRequestSchema, GetArtifactResponseSchema, ListSkillVersionsInputSchema, ListSkillVersionsResponseSchema, type PushSkillRequest, type PushSkillFromExecutionArtifactRequest, type GetArtifactRequest, type GetArtifactResponse, type ListSkillVersionsInput, type ListSkillVersionsResponse } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { SkillIdSchema, PushSkillRequestSchema, CreateSkillArtifactUploadUrlRequestSchema, SkillArtifactUploadUrlSchema, PushSkillFromExecutionArtifactRequestSchema, GetArtifactRequestSchema, GetArtifactResponseSchema, SkillArtifactDownloadUrlSchema, ListSkillVersionsInputSchema, ListSkillVersionsResponseSchema, type PushSkillRequest, type CreateSkillArtifactUploadUrlRequest, type SkillArtifactUploadUrl, type PushSkillFromExecutionArtifactRequest, type GetArtifactRequest, type GetArtifactResponse, type SkillArtifactDownloadUrl, type ListSkillVersionsInput, type ListSkillVersionsResponse } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
 import { SkillSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/spec_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -36,6 +36,12 @@ export class SkillClient {
     } catch (e) { throw wrapError(e); }
   }
 
+  async createArtifactUploadUrl(input: CreateSkillArtifactUploadUrlRequest): Promise<SkillArtifactUploadUrl> {
+    try {
+      return await this.command.createArtifactUploadUrl(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
   async pushFromExecutionArtifact(input: PushSkillFromExecutionArtifactRequest): Promise<Skill> {
     try {
       return await this.command.pushFromExecutionArtifact(input);
@@ -72,6 +78,12 @@ export class SkillClient {
     } catch (e) { throw wrapError(e); }
   }
 
+  async getArtifactDownloadUrl(input: GetArtifactRequest): Promise<SkillArtifactDownloadUrl> {
+    try {
+      return await this.query.getArtifactDownloadUrl(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
   async listVersions(input: ListSkillVersionsInput): Promise<ListSkillVersionsResponse> {
     try {
       return await this.query.listVersions(input);

package/src/index.ts

@@ -41,6 +41,7 @@ export {
   isUnauthenticated,
   isPermissionDenied,
   isRetryable,
+  isUnimplemented,
   type ErrorCategory,
   isConnectError,
   classifyError,
@@ -104,6 +105,9 @@ export {
   type SetCursorMemberKeyEnabledParams,
 } from "./cursor-accounts.js";
 
+// Provider standing client (platform operators only, read-only)
+export { ProviderStandingClient } from "./provider-standing.js";
+
 // Search client
 export {
   SearchClient,
@@ -271,6 +275,9 @@ export {
   resolveToolKind,
   resolveToolKindByName,
   normalizeToolResult,
+  SHELL_INTENT_ARG_FIELD,
+  extractShellIntent,
+  shellIntentFromArgs,
   type ToolResultView,
   type ToolSearchMatch,
   type ToolContentBlock,
@@ -287,6 +294,7 @@ export {
 } from "./execution/file-review-fold.js";
 export { toDisplayFileChange } from "./execution/to-display-file-change.js";
 export { SkillClient, type SkillInput } from "./gen/skill.js";
+export { RoutedSkillClient, MAX_INLINE_ARTIFACT_BYTES } from "./skill.js";
 export {
   WorkflowClient,
   type WorkflowInput,

package/src/provider-standing.ts

@@ -0,0 +1,37 @@
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { ProviderStandingQueryController } from "@stigmer/protos/ai/stigmer/platform/providerstanding/v1/query_pb";
+import {
+  GetProviderStandingViewInputSchema,
+  type ProviderStandingView,
+} from "@stigmer/protos/ai/stigmer/platform/providerstanding/v1/io_pb";
+import { wrapError } from "./gen/errors.js";
+
+/**
+ * Client for platform provider standing (platform operators only).
+ *
+ * Serves the read-only operator view of the platform's LLM provider
+ * account health: the latest canary-probe verdict per provider (status,
+ * HTTP status, latency, bounded error summary, probe time) recorded by
+ * the hourly standing probe. Requires `can_view_provider_standing` on
+ * `platform:stigmer`. Cloud-only — the OSS Go server does not implement
+ * this controller.
+ */
+export class ProviderStandingClient {
+  private readonly query: Client<typeof ProviderStandingQueryController>;
+
+  constructor(transport: Transport) {
+    this.query = createClient(ProviderStandingQueryController, transport);
+  }
+
+  /** Retrieve the latest probe verdict for every platform provider. */
+  async getStandingView(): Promise<ProviderStandingView> {
+    try {
+      return await this.query.getProviderStandingView(
+        create(GetProviderStandingViewInputSchema, {}),
+      );
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+}