@stigmer/runner 3.0.1

package/dist/budget/tracker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Budget tracker — accumulates cost, token, and duration usage against
+ * workflow-level budget limits.
+ *
+ * Port of Go's `pkg/budget/tracker.go`. The tracker is a pure, sandbox-safe
+ * class with zero external dependencies — it can run inside the Temporal
+ * deterministic isolate without importing Node.js or Temporal APIs.
+ *
+ * Budget config arrives via TemporalWorkflowInput (outside YAML) because
+ * budget is a Stigmer extension that doesn't survive YAML round-trip.
+ */
+export type LimitKind = "cost" | "tokens" | "duration";
+export type BudgetExceededPolicy = "terminate" | "warn" | "human_review";
+export interface WorkflowBudget {
+    readonly maxCostMicros?: number;
+    readonly maxTotalTokens?: number;
+    readonly maxDurationSeconds?: number;
+    readonly onExceeded?: BudgetExceededPolicy;
+}
+export interface CheckResult {
+    readonly ok: boolean;
+    readonly warningPct: number;
+    readonly exceeded: boolean;
+    readonly exceededLimit?: LimitKind;
+    readonly exceededMessage?: string;
+    readonly policy: BudgetExceededPolicy;
+}
+export declare class BudgetTracker {
+    private readonly budget;
+    private readonly startedAtMs;
+    costMicros: number;
+    inputTokens: number;
+    outputTokens: number;
+    constructor(budget: WorkflowBudget | undefined, startedAtMs: number);
+    record(costMicros: number, inputTokens: number, outputTokens: number): void;
+    totalTokens(): number;
+    check(nowMs: number): CheckResult;
+    costRemaining(): number;
+    tokensRemaining(): number;
+    private resolvePolicy;
+}
+/**
+ * Extracts cost metadata from task output using the __stigmer_* convention.
+ * Activity outputs that contain LLM cost data should include these keys
+ * for the budget tracker to accumulate.
+ */
+export interface TaskCostInfo {
+    readonly costMicros: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+export declare function extractCostFromOutput(output: unknown): TaskCostInfo;

package/dist/budget/tracker.js

@@ -0,0 +1,123 @@
+/**
+ * Budget tracker — accumulates cost, token, and duration usage against
+ * workflow-level budget limits.
+ *
+ * Port of Go's `pkg/budget/tracker.go`. The tracker is a pure, sandbox-safe
+ * class with zero external dependencies — it can run inside the Temporal
+ * deterministic isolate without importing Node.js or Temporal APIs.
+ *
+ * Budget config arrives via TemporalWorkflowInput (outside YAML) because
+ * budget is a Stigmer extension that doesn't survive YAML round-trip.
+ */
+export class BudgetTracker {
+    budget;
+    startedAtMs;
+    costMicros = 0;
+    inputTokens = 0;
+    outputTokens = 0;
+    constructor(budget, startedAtMs) {
+        this.budget = budget;
+        this.startedAtMs = startedAtMs;
+    }
+    record(costMicros, inputTokens, outputTokens) {
+        this.costMicros += costMicros;
+        this.inputTokens += inputTokens;
+        this.outputTokens += outputTokens;
+    }
+    totalTokens() {
+        return this.inputTokens + this.outputTokens;
+    }
+    check(nowMs) {
+        const policy = this.resolvePolicy();
+        if (!this.budget) {
+            return { ok: true, warningPct: 0, exceeded: false, policy };
+        }
+        let highestPct = 0;
+        if (this.budget.maxCostMicros && this.budget.maxCostMicros > 0) {
+            const pct = this.costMicros / this.budget.maxCostMicros;
+            if (pct > highestPct)
+                highestPct = pct;
+            if (this.costMicros > this.budget.maxCostMicros) {
+                return {
+                    ok: false,
+                    warningPct: pct,
+                    exceeded: true,
+                    exceededLimit: "cost",
+                    exceededMessage: `cost budget exceeded: ${this.costMicros}/${this.budget.maxCostMicros} micro-USD`,
+                    policy,
+                };
+            }
+        }
+        if (this.budget.maxTotalTokens && this.budget.maxTotalTokens > 0) {
+            const total = this.totalTokens();
+            const pct = total / this.budget.maxTotalTokens;
+            if (pct > highestPct)
+                highestPct = pct;
+            if (total > this.budget.maxTotalTokens) {
+                return {
+                    ok: false,
+                    warningPct: pct,
+                    exceeded: true,
+                    exceededLimit: "tokens",
+                    exceededMessage: `token budget exceeded: ${total}/${this.budget.maxTotalTokens} tokens`,
+                    policy,
+                };
+            }
+        }
+        if (this.budget.maxDurationSeconds && this.budget.maxDurationSeconds > 0) {
+            const elapsedMs = nowMs - this.startedAtMs;
+            const maxMs = this.budget.maxDurationSeconds * 1000;
+            const pct = elapsedMs / maxMs;
+            if (pct > highestPct)
+                highestPct = pct;
+            if (elapsedMs > maxMs) {
+                const elapsedSec = Math.round(elapsedMs / 1000);
+                return {
+                    ok: false,
+                    warningPct: pct,
+                    exceeded: true,
+                    exceededLimit: "duration",
+                    exceededMessage: `duration budget exceeded: ${elapsedSec}s/${this.budget.maxDurationSeconds}s`,
+                    policy,
+                };
+            }
+        }
+        return { ok: true, warningPct: highestPct, exceeded: false, policy };
+    }
+    costRemaining() {
+        if (!this.budget?.maxCostMicros)
+            return -1;
+        const rem = this.budget.maxCostMicros - this.costMicros;
+        return rem < 0 ? 0 : rem;
+    }
+    tokensRemaining() {
+        if (!this.budget?.maxTotalTokens)
+            return -1;
+        const rem = this.budget.maxTotalTokens - this.totalTokens();
+        return rem < 0 ? 0 : rem;
+    }
+    resolvePolicy() {
+        return this.budget?.onExceeded ?? "terminate";
+    }
+}
+export function extractCostFromOutput(output) {
+    if (output === null || output === undefined || typeof output !== "object") {
+        return { costMicros: 0, inputTokens: 0, outputTokens: 0 };
+    }
+    const o = output;
+    const usage = (typeof o.usage === "object" && o.usage !== null)
+        ? o.usage
+        : undefined;
+    return {
+        costMicros: toSafeInt(o.__stigmer_cost_micros ?? o.cost_micros),
+        inputTokens: toSafeInt(o.__stigmer_input_tokens ?? o.input_tokens ?? usage?.input_tokens),
+        outputTokens: toSafeInt(o.__stigmer_output_tokens ?? o.output_tokens ?? usage?.output_tokens),
+    };
+}
+function toSafeInt(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(0, Math.floor(value));
+    }
+    return 0;
+}
+//# sourceMappingURL=tracker.js.map

package/dist/budget/tracker.js.map

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

package/dist/claimcheck/compressor.d.ts

@@ -0,0 +1,2 @@
+export declare function compress(data: Buffer): Buffer<ArrayBuffer>;
+export declare function decompress(data: Buffer): Buffer<ArrayBuffer>;

package/dist/claimcheck/compressor.js

@@ -0,0 +1,8 @@
+import { gzipSync, gunzipSync } from "node:zlib";
+export function compress(data) {
+    return gzipSync(data);
+}
+export function decompress(data) {
+    return gunzipSync(data);
+}
+//# sourceMappingURL=compressor.js.map

package/dist/claimcheck/compressor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.js","sourceRoot":"","sources":["../../src/claimcheck/compressor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,QAAQ,CAAC,IAAI,CAAwB,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,UAAU,CAAC,IAAI,CAAwB,CAAC;AACjD,CAAC"}

package/dist/claimcheck/config.d.ts

@@ -0,0 +1,7 @@
+export interface ClaimcheckConfig {
+    readonly enabled: boolean;
+    readonly thresholdBytes: number;
+    readonly compressionEnabled: boolean;
+    readonly keyPrefix: string;
+}
+export declare function loadClaimcheckConfig(): ClaimcheckConfig;

package/dist/claimcheck/config.js

@@ -0,0 +1,10 @@
+const DEFAULT_THRESHOLD_BYTES = 128 * 1024; // 128KB
+export function loadClaimcheckConfig() {
+    return {
+        enabled: process.env.CLAIMCHECK_ENABLED === "true",
+        thresholdBytes: parseInt(process.env.CLAIMCHECK_THRESHOLD_BYTES ?? String(DEFAULT_THRESHOLD_BYTES), 10),
+        compressionEnabled: process.env.CLAIMCHECK_COMPRESSION_ENABLED !== "false",
+        keyPrefix: process.env.CLAIMCHECK_KEY_PREFIX ?? "claimcheck/",
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/claimcheck/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/claimcheck/config.ts"],"names":[],"mappings":"AAOA,MAAM,uBAAuB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,QAAQ;AAEpD,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM;QAClD,cAAc,EAAE,QAAQ,CACtB,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,MAAM,CAAC,uBAAuB,CAAC,EACzE,EAAE,CACH;QACD,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,8BAA8B,KAAK,OAAO;QAC1E,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,aAAa;KAC9D,CAAC;AACJ,CAAC"}

package/dist/claimcheck/index.d.ts

@@ -0,0 +1,3 @@
+export { ClaimcheckPayloadCodec } from "./payload-codec.js";
+export { loadClaimcheckConfig, type ClaimcheckConfig } from "./config.js";
+export { compress, decompress } from "./compressor.js";

package/dist/claimcheck/index.js

@@ -0,0 +1,4 @@
+export { ClaimcheckPayloadCodec } from "./payload-codec.js";
+export { loadClaimcheckConfig } from "./config.js";
+export { compress, decompress } from "./compressor.js";
+//# sourceMappingURL=index.js.map

package/dist/claimcheck/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/claimcheck/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAyB,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/claimcheck/payload-codec.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Temporal PayloadCodec that transparently offloads large payloads to
+ * external storage (ArtifactStorage). Payloads below the threshold pass
+ * through unchanged. Payloads at or above the threshold are compressed
+ * (optional), uploaded, and replaced with a small reference marker.
+ *
+ * On decode, markers are detected, the original payload is downloaded
+ * and decompressed, and the original bytes are restored — transparent
+ * to workflow/activity code.
+ */
+import type { Payload, PayloadCodec } from "@temporalio/common";
+import type { ArtifactStorage } from "../shared/artifact-storage.js";
+import type { ClaimcheckConfig } from "./config.js";
+export declare class ClaimcheckPayloadCodec implements PayloadCodec {
+    private readonly storage;
+    private readonly config;
+    constructor(storage: ArtifactStorage, config: ClaimcheckConfig);
+    encode(payloads: Payload[]): Promise<Payload[]>;
+    decode(payloads: Payload[]): Promise<Payload[]>;
+    private encodePayload;
+    private decodePayload;
+    private isClaimcheckPayload;
+}

package/dist/claimcheck/payload-codec.js

@@ -0,0 +1,81 @@
+/**
+ * Temporal PayloadCodec that transparently offloads large payloads to
+ * external storage (ArtifactStorage). Payloads below the threshold pass
+ * through unchanged. Payloads at or above the threshold are compressed
+ * (optional), uploaded, and replaced with a small reference marker.
+ *
+ * On decode, markers are detected, the original payload is downloaded
+ * and decompressed, and the original bytes are restored — transparent
+ * to workflow/activity code.
+ */
+import { randomUUID } from "node:crypto";
+import { compress, decompress } from "./compressor.js";
+const MARKER_METADATA_KEY = "encoding";
+const MARKER_ENCODING_VALUE = "binary/claimcheck";
+export class ClaimcheckPayloadCodec {
+    storage;
+    config;
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+    }
+    async encode(payloads) {
+        return Promise.all(payloads.map((p) => this.encodePayload(p)));
+    }
+    async decode(payloads) {
+        return Promise.all(payloads.map((p) => this.decodePayload(p)));
+    }
+    async encodePayload(payload) {
+        const data = payload.data;
+        if (!data || data.length < this.config.thresholdBytes) {
+            return payload;
+        }
+        const originalBuf = Buffer.from(data);
+        let uploadBuf = originalBuf;
+        let compressed = false;
+        if (this.config.compressionEnabled) {
+            const compressedBuf = compress(originalBuf);
+            if (compressedBuf.length < originalBuf.length) {
+                uploadBuf = compressedBuf;
+                compressed = true;
+            }
+        }
+        const key = `${this.config.keyPrefix}${randomUUID()}`;
+        await this.storage.upload(key, uploadBuf, "application/octet-stream");
+        const marker = {
+            key,
+            size: data.length,
+            compressed,
+        };
+        return {
+            metadata: {
+                [MARKER_METADATA_KEY]: Buffer.from(MARKER_ENCODING_VALUE),
+            },
+            data: Buffer.from(JSON.stringify(marker)),
+        };
+    }
+    async decodePayload(payload) {
+        if (!this.isClaimcheckPayload(payload)) {
+            return payload;
+        }
+        const marker = JSON.parse(Buffer.from(payload.data).toString("utf-8"));
+        const downloadUrl = await this.storage.getDownloadUrl(marker.key);
+        const response = await fetch(downloadUrl);
+        if (!response.ok) {
+            throw new Error(`Claimcheck retrieve failed for key ${marker.key}: HTTP ${response.status}`);
+        }
+        const rawBuf = Buffer.from(await response.arrayBuffer());
+        const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
+        return {
+            metadata: payload.metadata,
+            data: dataBuf,
+        };
+    }
+    isClaimcheckPayload(payload) {
+        const encoding = payload.metadata?.[MARKER_METADATA_KEY];
+        if (!encoding)
+            return false;
+        return Buffer.from(encoding).toString("utf-8") === MARKER_ENCODING_VALUE;
+    }
+}
+//# sourceMappingURL=payload-codec.js.map

package/dist/claimcheck/payload-codec.js.map

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

package/dist/client/server-contracts.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Server Contract Validation
+ *
+ * Encodes server-side pipeline requirements that the proto schema does not
+ * express. The Java backend's `ResolveSlugStepV2`, `AuthorizeStep`, and
+ * `ValidateSessionOrAgentStep` enforce business rules beyond protovalidate
+ * annotations. These guards catch violations at the client before they
+ * reach the wire, producing actionable error messages.
+ *
+ * Background: `ApiResourceMetadata.name` and `.slug` are proto-optional
+ * (IGNORE_IF_ZERO_VALUE), but the server's ResolveSlugStepV2 requires at
+ * least one on resource creation (when id is absent). This mismatch caused
+ * the same class of bug three times (Jan 2026 CLI, May 2026 runner).
+ */
+export declare class ServerContractError extends Error {
+    constructor(caller: string, detail: string);
+}
+interface ResourceMetadata {
+    name?: string;
+    slug?: string;
+    id?: string;
+    org?: string;
+}
+interface ResourceEnvelope {
+    apiVersion?: string;
+    kind?: string;
+    metadata?: ResourceMetadata;
+}
+interface ResourceReference {
+    org?: string;
+    slug?: string;
+    kind?: number;
+}
+/**
+ * Validates that a resource being created satisfies the server's pipeline
+ * requirements for the CREATE path:
+ *
+ * 1. ResolveSlugStepV2: metadata.slug or metadata.name required (when id absent)
+ * 2. AuthorizeStep: metadata.org required for organization-scoped authorization
+ * 3. Envelope: apiVersion and kind must match expected values
+ */
+export declare function assertCreateRequirements(resource: ResourceEnvelope, expectedKind: string, caller: string): void;
+/**
+ * Validates that an ApiResourceReference has the fields required by
+ * the server's getByReference handlers.
+ *
+ * Proto declares slug as `required = true`, but generated TypeScript types
+ * do not enforce this at runtime. The server's handler also requires org
+ * for scoped lookups.
+ */
+export declare function assertReferenceRequirements(ref: ResourceReference, resourceKind: string, caller: string): void;
+export {};

package/dist/client/server-contracts.js

@@ -0,0 +1,72 @@
+/**
+ * Server Contract Validation
+ *
+ * Encodes server-side pipeline requirements that the proto schema does not
+ * express. The Java backend's `ResolveSlugStepV2`, `AuthorizeStep`, and
+ * `ValidateSessionOrAgentStep` enforce business rules beyond protovalidate
+ * annotations. These guards catch violations at the client before they
+ * reach the wire, producing actionable error messages.
+ *
+ * Background: `ApiResourceMetadata.name` and `.slug` are proto-optional
+ * (IGNORE_IF_ZERO_VALUE), but the server's ResolveSlugStepV2 requires at
+ * least one on resource creation (when id is absent). This mismatch caused
+ * the same class of bug three times (Jan 2026 CLI, May 2026 runner).
+ */
+export class ServerContractError extends Error {
+    constructor(caller, detail) {
+        super(`[ServerContract] ${caller}: ${detail}`);
+        this.name = "ServerContractError";
+    }
+}
+const STIGMER_API_VERSION = "agentic.stigmer.ai/v1";
+/**
+ * Validates that a resource being created satisfies the server's pipeline
+ * requirements for the CREATE path:
+ *
+ * 1. ResolveSlugStepV2: metadata.slug or metadata.name required (when id absent)
+ * 2. AuthorizeStep: metadata.org required for organization-scoped authorization
+ * 3. Envelope: apiVersion and kind must match expected values
+ */
+export function assertCreateRequirements(resource, expectedKind, caller) {
+    if (resource.apiVersion !== STIGMER_API_VERSION) {
+        throw new ServerContractError(caller, `apiVersion must be "${STIGMER_API_VERSION}" (got "${resource.apiVersion ?? ""}"). ` +
+            `Set apiVersion when constructing the proto with create().`);
+    }
+    if (resource.kind !== expectedKind) {
+        throw new ServerContractError(caller, `kind must be "${expectedKind}" (got "${resource.kind ?? ""}"). ` +
+            `Set kind when constructing the proto with create().`);
+    }
+    const meta = resource.metadata;
+    if (!meta) {
+        throw new ServerContractError(caller, `${expectedKind} requires metadata to be set.`);
+    }
+    if (!meta.id && !meta.slug && !meta.name) {
+        throw new ServerContractError(caller, `${expectedKind} requires metadata.name or metadata.slug for creation. ` +
+            `The server's ResolveSlug step generates a slug from the name. ` +
+            `Provide a name like "${expectedKind.toLowerCase()}-{context}-{timestamp}".`);
+    }
+    if (!meta.org) {
+        throw new ServerContractError(caller, `${expectedKind} requires metadata.org for authorization. ` +
+            `The server's Authorize step uses org to check permissions.`);
+    }
+}
+/**
+ * Validates that an ApiResourceReference has the fields required by
+ * the server's getByReference handlers.
+ *
+ * Proto declares slug as `required = true`, but generated TypeScript types
+ * do not enforce this at runtime. The server's handler also requires org
+ * for scoped lookups.
+ */
+export function assertReferenceRequirements(ref, resourceKind, caller) {
+    if (!ref.slug) {
+        throw new ServerContractError(caller, `${resourceKind} reference requires a non-empty slug. ` +
+            `If the slug came from placeholder resolution, the referenced ` +
+            `secret or env var may be missing.`);
+    }
+    if (!ref.org) {
+        throw new ServerContractError(caller, `${resourceKind} reference requires org for scoped lookup. ` +
+            `Pass the organization slug or ensure it is available in the runtime context.`);
+    }
+}
+//# sourceMappingURL=server-contracts.js.map

package/dist/client/server-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-contracts.js","sourceRoot":"","sources":["../../src/client/server-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,MAAc,EAAE,MAAc;QACxC,KAAK,CAAC,oBAAoB,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAqBD,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA0B,EAC1B,YAAoB,EACpB,MAAc;IAEd,IAAI,QAAQ,CAAC,UAAU,KAAK,mBAAmB,EAAE,CAAC;QAChD,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,uBAAuB,mBAAmB,WAAW,QAAQ,CAAC,UAAU,IAAI,EAAE,MAAM;YACpF,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QACnC,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,iBAAiB,YAAY,WAAW,QAAQ,CAAC,IAAI,IAAI,EAAE,MAAM;YACjE,qDAAqD,CACtD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,mBAAmB,CAAC,MAAM,EAAE,GAAG,YAAY,+BAA+B,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACzC,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,GAAG,YAAY,yDAAyD;YACxE,gEAAgE;YAChE,wBAAwB,YAAY,CAAC,WAAW,EAAE,0BAA0B,CAC7E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,GAAG,YAAY,4CAA4C;YAC3D,4DAA4D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,GAAsB,EACtB,YAAoB,EACpB,MAAc;IAEd,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,GAAG,YAAY,wCAAwC;YACvD,+DAA+D;YAC/D,mCAAmC,CACpC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,mBAAmB,CAC3B,MAAM,EACN,GAAG,YAAY,6CAA6C;YAC5D,8EAA8E,CAC/E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/client/stigmer-client.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Connect-RPC client for communicating with the Stigmer server.
+ *
+ * Provides typed wrappers around generated service stubs for RPCs the
+ * runner needs: execution queries, status updates, session reads/writes,
+ * and blueprint resolution (agent, skill, MCP server).
+ *
+ * Shared by all activities in the unified runner.
+ */
+import { type Client, type Transport } from "@connectrpc/connect";
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import type { CreateArtifactInput } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/io_pb";
+import type { RecordLlmCallUsageInput, RecordLlmCallUsageResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { AgentInstance } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+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 { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import type { WorkflowExecution, WorkflowExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+/**
+ * Everything an embedded runner needs to bootstrap: Temporal coordinates plus
+ * its own minted access token.
+ *
+ * The Temporal coordinates are always present. The access token is optional: the
+ * server only mints one when it has a Cursor proxy to authenticate against
+ * (cloud) and a signing key configured — OSS and misconfigured servers omit it,
+ * and the runner keeps using its existing token in that case.
+ */
+export interface RunnerBootstrapConfig {
+    temporalAddress: string;
+    temporalNamespace: string;
+    /** Minted iss=stigmer token for the runner's proxy traffic; absent when not minted. */
+    runnerAccessToken?: string;
+    /** Lifetime of {@link runnerAccessToken} in seconds; absent/0 when no token. */
+    runnerAccessTokenExpiresInSeconds?: number;
+}
+/**
+ * A shared mutable token reference. When provided, the interceptor
+ * reads from this on every request, enabling token updates to
+ * propagate to all clients sharing the same ref.
+ */
+export interface TokenRef {
+    current: string | null;
+}
+export interface StigmerClientOptions {
+    endpoint: string;
+    token: string | null;
+    tokenRef?: TokenRef;
+}
+export declare class StigmerClient {
+    readonly transport: Transport;
+    private currentToken;
+    private readonly executionQuery;
+    private readonly executionCommand;
+    private readonly executionContextQuery;
+    private readonly sessionQuery;
+    private readonly sessionCommand;
+    private readonly agentQuery;
+    private readonly agentInstanceQuery;
+    private readonly mcpServerQuery;
+    private readonly mcpServerCommand;
+    private readonly skillQuery;
+    private readonly billingCommand;
+    private readonly artifactCommand;
+    readonly workflowExecutionCommand: Client<typeof WorkflowExecutionCommandController>;
+    private readonly workflowExecutionQuery;
+    private readonly workflowQuery;
+    private readonly workflowInstanceQuery;
+    private readonly platformQuery;
+    private readonly tokenRef;
+    constructor(options: StigmerClientOptions);
+    /**
+     * Fetch this runner's bootstrap config from the control plane.
+     *
+     * Lets an embedded runner self-bootstrap from a token alone: the control
+     * plane returns the Temporal frontend address and namespace for the
+     * environment the token belongs to (so integrators never hardcode
+     * infrastructure addresses) and, on cloud, a minted iss=stigmer access token
+     * the runner uses for its proxy traffic. The token fields are absent when the
+     * server does not mint one (OSS, or no signing key configured).
+     */
+    getRunnerBootstrapConfig(): Promise<RunnerBootstrapConfig>;
+    getExecution(executionId: string): Promise<AgentExecution>;
+    updateStatus(executionId: string, status: AgentExecutionStatus): Promise<UpdateStatusResponse>;
+    getExecutionContextByExecutionId(executionId: string): Promise<ExecutionContext>;
+    getSession(sessionId: string): Promise<Session>;
+    updateSession(session: Session): Promise<Session>;
+    getAgent(agentId: string): Promise<Agent>;
+    getAgentInstance(instanceId: string): Promise<AgentInstance>;
+    getMcpServer(serverId: string): Promise<McpServer>;
+    getMcpServerByReference(ref: ApiResourceReference): Promise<McpServer>;
+    connectMcpServer(mcpServerId: string, org: string, runtimeEnv?: Record<string, {
+        value: string;
+        isSecret: boolean;
+    }>): Promise<McpServer>;
+    getSkill(skillId: string): Promise<Skill>;
+    getSkillByReference(ref: ApiResourceReference): Promise<Skill>;
+    getSkillArtifact(artifactStorageKey: string): Promise<GetArtifactResponse>;
+    createArtifact(input: CreateArtifactInput): Promise<Artifact>;
+    recordLlmCallUsage(input: RecordLlmCallUsageInput): Promise<RecordLlmCallUsageResponse>;
+    getAgentByReference(ref: ApiResourceReference): Promise<Agent>;
+    createSession(session: Session): Promise<Session>;
+    applySession(session: Session): Promise<Session>;
+    createAgentExecution(execution: AgentExecution): Promise<AgentExecution>;
+    updateWorkflowExecutionStatus(executionId: string, status: WorkflowExecutionStatus, options?: {
+        updatePendingApprovals?: boolean;
+    }): Promise<WorkflowExecution>;
+    getWorkflowExecution(executionId: string): Promise<WorkflowExecution>;
+    /**
+     * Return the highest persisted event sequence_number for a workflow execution.
+     *
+     * Paginates through getEventLog with the maximum page size (500) and
+     * follows the cursor until has_more is false. The final page's
+     * latest_sequence is the global high-water mark.
+     *
+     * Returns 0 when no events have been persisted yet (new execution).
+     */
+    getEventLogHighWaterMark(executionId: string): Promise<bigint>;
+    getWorkflow(workflowId: string): Promise<Workflow>;
+    getWorkflowVersion(workflowId: string, versionHash: string): Promise<import("@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb").WorkflowVersionEntry>;
+    getWorkflowInstance(instanceId: string): Promise<WorkflowInstance>;
+    updateToken(token: string | null): void;
+}