@runtypelabs/sdk 9.12.0 → 9.13.0

package/dist/index.cjs

@@ -20,8 +20,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AgentAliasDependencyError: () => AgentAliasDependencyError,
+  AgentAliasNotFoundError: () => AgentAliasNotFoundError,
+  AgentAliasPreviewLimitError: () => AgentAliasPreviewLimitError,
+  AgentAliasRevisionMismatchError: () => AgentAliasRevisionMismatchError,
+  AgentAliasRevisionRequiredError: () => AgentAliasRevisionRequiredError,
+  AgentAliasesNamespace: () => AgentAliasesNamespace,
+  AgentDeploymentsNamespace: () => AgentDeploymentsNamespace,
   AgentDriftError: () => AgentDriftError,
   AgentEnsureConflictError: () => AgentEnsureConflictError,
+  AgentPromotionError: () => AgentPromotionError,
   AgentVersionsEndpoint: () => AgentVersionsEndpoint,
   AgentsEndpoint: () => AgentsEndpoint,
   AgentsNamespace: () => AgentsNamespace,
@@ -43,6 +51,7 @@ __export(index_exports, {
   DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS: () => DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
   DEFAULT_STALL_STOP_AFTER: () => DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint: () => DispatchEndpoint,
+  ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE: () => ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE,
   EvalBuilder: () => EvalBuilder,
   EvalEndpoint: () => EvalEndpoint,
   EvalRunner: () => EvalRunner,
@@ -60,6 +69,7 @@ __export(index_exports, {
   FlowsNamespace: () => FlowsNamespace,
   IntegrationsEndpoint: () => IntegrationsEndpoint,
   LEDGER_ARTIFACT_LINE_PREFIX: () => LEDGER_ARTIFACT_LINE_PREFIX,
+  LIVE_AGENT_ALIAS: () => LIVE_AGENT_ALIAS,
   LogsEndpoint: () => LogsEndpoint,
   ModelConfigsEndpoint: () => ModelConfigsEndpoint,
   ProductDriftError: () => ProductDriftError,
@@ -96,6 +106,8 @@ __export(index_exports, {
   TypedRecordsScope: () => TypedRecordsScope,
   UNIFIED_EVENTS_QUERY: () => UNIFIED_EVENTS_QUERY,
   UsersEndpoint: () => UsersEndpoint,
+  activateAgentPromotion: () => activateAgentPromotion,
+  agentAliasErrorCode: () => agentAliasErrorCode,
   applyGeneratedRuntimeToolProposalToDispatchRequest: () => applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest: () => attachRuntimeToolsToDispatchRequest,
   buildAgentAdmissionHeaders: () => buildAgentAdmissionHeaders,
@@ -173,7 +185,10 @@ __export(index_exports, {
   parseLedgerArtifactRelativePath: () => parseLedgerArtifactRelativePath,
   parseOffloadedOutputId: () => parseOffloadedOutputId,
   parseSSEChunk: () => parseSSEChunk,
+  prepareAgentPromotion: () => prepareAgentPromotion,
   processStream: () => processStream,
+  promoteAgent: () => promoteAgent,
+  promotionIdempotencyKey: () => promotionIdempotencyKey,
   pullEval: () => pullEval,
   pullFpo: () => pullFpo,
   ranStep: () => ranStep,
@@ -191,6 +206,7 @@ __export(index_exports, {
   unregisterWorkflowHook: () => unregisterWorkflowHook,
   usedNoTools: () => usedNoTools,
   validJson: () => validJson,
+  validateAgentPromotion: () => validateAgentPromotion,
   withDetachedReconnect: () => withDetachedReconnect,
   withUnifiedEvents: () => withUnifiedEvents
 });
@@ -2251,6 +2267,268 @@ data: ${JSON.stringify({
   });
 }
 
+// src/agent-aliases-namespace.ts
+var LIVE_AGENT_ALIAS = "live";
+var AgentAliasRevisionMismatchError = class extends Error {
+  constructor(body) {
+    super(
+      body.error ?? `Alias revision mismatch: expected ${body.expected}, found ${body.actual ?? "no alias"}.`
+    );
+    this.code = "alias_revision_mismatch";
+    this.name = "AgentAliasRevisionMismatchError";
+    this.expectedRevision = body.expected;
+    this.actualRevision = body.actual;
+  }
+};
+var AgentAliasRevisionRequiredError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "alias_revision_required";
+    this.name = "AgentAliasRevisionRequiredError";
+  }
+};
+var AgentAliasNotFoundError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Alias "${body.alias}" was not found on agent ${body.agentId}.`);
+    this.code = "alias_not_found";
+    this.name = "AgentAliasNotFoundError";
+    this.alias = body.alias;
+    this.agentId = body.agentId;
+  }
+};
+var AgentAliasPreviewLimitError = class extends Error {
+  constructor(body) {
+    super(
+      body.error ?? `This ${body.scope} already has ${body.limit} active preview aliases, the maximum.`
+    );
+    this.code = "PREVIEW_ALIAS_LIMIT";
+    this.name = "AgentAliasPreviewLimitError";
+    this.scope = body.scope;
+    this.limit = body.limit;
+    this.active = body.active;
+  }
+};
+var AgentAliasDependencyError = class extends Error {
+  constructor(body) {
+    super(body.error ?? "The version references a dependency that no longer resolves.");
+    this.code = "alias_dependency_unresolved";
+    this.name = "AgentAliasDependencyError";
+    this.refs = body.refs ?? [];
+  }
+};
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function parseRequestError(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const structured = err;
+  if (typeof structured.statusCode === "number") {
+    return { status: structured.statusCode, body: asRecord(structured.data) };
+  }
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: asRecord(JSON.parse(match[2])) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function asString(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+function toAliasError(err, agentId, alias) {
+  const { status, body } = parseRequestError(err);
+  if (status === null) return null;
+  const error = body && typeof body.error === "string" ? body.error : void 0;
+  if (status === 412 && body && typeof body.expected === "number") {
+    return new AgentAliasRevisionMismatchError({
+      ...error !== void 0 ? { error } : {},
+      expected: body.expected,
+      actual: typeof body.actual === "number" ? body.actual : null
+    });
+  }
+  if (status === 428) {
+    return new AgentAliasRevisionRequiredError(
+      error ?? "Updating an existing live alias requires an If-Match revision."
+    );
+  }
+  if (status === 404 && body?.code === "alias_not_found") {
+    return new AgentAliasNotFoundError({
+      ...error !== void 0 ? { error } : {},
+      alias: asString(body.alias, alias),
+      agentId: asString(body.agentId, agentId)
+    });
+  }
+  if (status === 429 && body?.code === "PREVIEW_ALIAS_LIMIT") {
+    return new AgentAliasPreviewLimitError({
+      ...error !== void 0 ? { error } : {},
+      scope: body.scope === "organization" ? "organization" : "agent",
+      limit: typeof body.limit === "number" ? body.limit : 0,
+      active: typeof body.active === "number" ? body.active : 0
+    });
+  }
+  if (status === 422 && body?.code === "alias_dependency_unresolved") {
+    return new AgentAliasDependencyError({
+      ...error !== void 0 ? { error } : {},
+      refs: Array.isArray(body.refs) ? body.refs.filter((ref) => typeof ref === "string") : []
+    });
+  }
+  return null;
+}
+var TYPED_ALIAS_ERRORS = [
+  AgentAliasRevisionMismatchError,
+  AgentAliasRevisionRequiredError,
+  AgentAliasNotFoundError,
+  AgentAliasDependencyError,
+  AgentAliasPreviewLimitError
+];
+function agentAliasErrorCode(err) {
+  return TYPED_ALIAS_ERRORS.some((typed) => err instanceof typed) ? err.code : void 0;
+}
+function writeHeaders(input) {
+  const headers = {};
+  if (typeof input.revision === "number") headers["If-Match"] = String(input.revision);
+  if (input.idempotencyKey) headers["Idempotency-Key"] = input.idempotencyKey;
+  return headers;
+}
+function encode(value) {
+  return encodeURIComponent(value);
+}
+var AgentAliasesNamespace = class {
+  constructor(getTransport) {
+    this.getTransport = getTransport;
+  }
+  /** List this agent's pointers, `live` first then previews by name. */
+  async list(agentId, options = {}) {
+    return this.getTransport().get(`/agents/${encode(agentId)}/aliases`, {
+      ...options.includeArchived ? { includeArchived: "true" } : {},
+      ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+      ...options.cursor ? { cursor: options.cursor } : {}
+    });
+  }
+  /**
+   * Every agent in the organization carrying a pointer with this name, each
+   * with the revision to quote back as `If-Match`. The read a PR-close cleanup
+   * makes before archiving.
+   */
+  async listByName(alias, options = {}) {
+    return this.getTransport().get("/agent-aliases", {
+      alias,
+      ...options.includeArchived ? { includeArchived: "true" } : {}
+    });
+  }
+  /**
+   * Archive this pointer on every agent in the organization that carries it,
+   * each under the revision just read. A failure on one agent is reported and
+   * the rest continue; a second run finds nothing active and archives nothing.
+   */
+  async archiveEverywhere(alias) {
+    const listed = await this.listByName(alias);
+    const rows = listed.data ?? [];
+    const result = { alias, archived: [], failed: [] };
+    for (const row of rows) {
+      try {
+        const archived = await this.archive(row.agentId, alias, { revision: row.revision });
+        result.archived.push({
+          agentId: row.agentId,
+          agentName: row.agentName,
+          revision: archived.revision,
+          receiptId: archived.receiptId
+        });
+      } catch (err) {
+        const code = agentAliasErrorCode(err);
+        result.failed.push({
+          agentId: row.agentId,
+          agentName: row.agentName,
+          error: err instanceof Error ? err.message : String(err),
+          ...code ? { code } : {}
+        });
+      }
+    }
+    return result;
+  }
+  /** Read one pointer. A missing or archived alias throws, never falls back to live. */
+  async get(agentId, alias, options = {}) {
+    return this.run(
+      agentId,
+      alias,
+      () => this.getTransport().get(`/agents/${encode(agentId)}/aliases/${encode(alias)}`, {
+        ...options.includeArchived ? { includeArchived: "true" } : {}
+      })
+    );
+  }
+  /** Aim one pointer at one exact version, appending a deployment receipt. */
+  async activate(agentId, alias, input) {
+    const body = {
+      versionId: input.versionId,
+      ...input.reason ? { reason: input.reason } : {},
+      ...input.promotion ? { promotion: input.promotion } : {}
+    };
+    return this.run(
+      agentId,
+      alias,
+      () => this.getTransport().put(
+        `/agents/${encode(agentId)}/aliases/${encode(alias)}`,
+        body,
+        writeHeaders(input)
+      )
+    );
+  }
+  /** Archive a preview pointer: it stops resolving but keeps its history. */
+  async archive(agentId, alias, input = {}) {
+    return this.run(
+      agentId,
+      alias,
+      () => this.getTransport().delete(
+        `/agents/${encode(agentId)}/aliases/${encode(alias)}`,
+        void 0,
+        writeHeaders(input)
+      )
+    );
+  }
+  /** Re-aim a pointer at the version its receipt history records before this one. */
+  async rollback(agentId, alias, input = {}) {
+    const body = {
+      ...input.steps !== void 0 ? { steps: input.steps } : {},
+      ...input.reason ? { reason: input.reason } : {}
+    };
+    return this.run(
+      agentId,
+      alias,
+      () => this.getTransport().post(
+        `/agents/${encode(agentId)}/aliases/${encode(alias)}/rollback`,
+        body,
+        writeHeaders(input)
+      )
+    );
+  }
+  async run(agentId, alias, call) {
+    try {
+      return await call();
+    } catch (err) {
+      const typed = toAliasError(err, agentId, alias);
+      if (typed) throw typed;
+      throw err;
+    }
+  }
+};
+var AgentDeploymentsNamespace = class {
+  constructor(getTransport) {
+    this.getTransport = getTransport;
+  }
+  /** Receipts newest first, cursor-paginated; filter to one pointer with `alias`. */
+  async list(agentId, options = {}) {
+    return this.getTransport().get(
+      `/agents/${encode(agentId)}/deployments`,
+      {
+        ...options.alias ? { alias: options.alias } : {},
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
+        ...options.cursor ? { cursor: options.cursor } : {}
+      }
+    );
+  }
+};
+
 // src/generated-tool-gate.ts
 var TOOL_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]{1,63}$/;
 var DEFAULT_MAX_CODE_LENGTH = 12e3;
@@ -2273,7 +2551,7 @@ var DEFAULT_ALLOWED_LANGUAGES = [
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function asString(value) {
+function asString2(value) {
   return typeof value === "string" ? value.trim() : void 0;
 }
 function asNumber(value) {
@@ -2306,8 +2584,8 @@ function normalizeGeneratedProposal(proposal, violations) {
     violations.push("Generated tool proposal must be an object");
     return null;
   }
-  const name = asString(candidate.name);
-  const description = asString(candidate.description);
+  const name = asString2(candidate.name);
+  const description = asString2(candidate.description);
   const toolType = candidate.toolType;
   const parametersSchema = candidate.parametersSchema;
   if (!name) {
@@ -2342,7 +2620,7 @@ function normalizeGeneratedProposal(proposal, violations) {
     violations.push("Custom tool config is required");
     return null;
   }
-  const code = asString(config.code);
+  const code = asString2(config.code);
   if (!code) {
     violations.push("Custom tool config.code is required");
     return null;
@@ -5819,6 +6097,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   constructor(client) {
     this.client = client;
     this.TOOL_OUTPUT_INLINE_THRESHOLD = 500;
+    this.aliases = new AgentAliasesNamespace(() => this.client);
+    this.deployments = new AgentDeploymentsNamespace(() => this.client);
   }
   /**
    * List all agents for the authenticated user
@@ -9879,7 +10159,7 @@ var FlowDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError(err) {
+function parseRequestError2(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -9890,7 +10170,7 @@ function parseRequestError(err) {
   }
 }
 function toConflictError(err) {
-  const { status, body } = parseRequestError(err);
+  const { status, body } = parseRequestError2(err);
   if (status !== 409 || !isPlainObject(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -11695,7 +11975,7 @@ var SkillDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError2(err) {
+function parseRequestError3(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -11706,7 +11986,7 @@ function parseRequestError2(err) {
   }
 }
 function toConflictError2(err) {
-  const { status, body } = parseRequestError2(err);
+  const { status, body } = parseRequestError3(err);
   if (status !== 409 || !isPlainObject(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -12015,6 +12295,7 @@ var SkillsNamespace = class {
 };
 
 // src/agents-namespace.ts
+var ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE = 'Provide either release or deploy, not both. release is a compatibility input; use deploy: { alias: "live" } instead of release: "publish", and omit both to save without activating.';
 var AGENT_CONFIG_KEYS = [
   "contextManagement",
   "model",
@@ -12174,7 +12455,7 @@ var AgentDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError3(err) {
+function parseRequestError4(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -12185,7 +12466,7 @@ function parseRequestError3(err) {
   }
 }
 function toConflictError3(err) {
-  const { status, body } = parseRequestError3(err);
+  const { status, body } = parseRequestError4(err);
   if (status !== 409 || !isPlainObject2(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -12205,6 +12486,9 @@ function memoFor4(client) {
 var AgentsNamespace = class {
   constructor(getClient) {
     this.getClient = getClient;
+    const transport = () => this.getClient();
+    this.aliases = new AgentAliasesNamespace(transport);
+    this.deployments = new AgentDeploymentsNamespace(transport);
   }
   /**
    * Idempotently converge a definition onto the platform. Hash-first: probes
@@ -12214,10 +12498,14 @@ var AgentsNamespace = class {
    */
   async ensure(definition, options = {}) {
     const client = this.getClient();
-    const { dryRun, onConflict, release, expectedRemoteHash, version, expectNoChanges } = options;
+    const { dryRun, onConflict, release, deploy, expectedRemoteHash, version, expectNoChanges } = options;
+    if (release !== void 0 && deploy !== void 0) {
+      throw new Error(ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE);
+    }
     const passthrough = {
       ...onConflict ? { onConflict } : {},
       ...release ? { release } : {},
+      ...deploy ? { deploy } : {},
       ...expectedRemoteHash ? { expectedRemoteHash } : {},
       ...version ? { version } : {}
     };
@@ -12382,7 +12670,7 @@ var ToolDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError4(err) {
+function parseRequestError5(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -12393,7 +12681,7 @@ function parseRequestError4(err) {
   }
 }
 function toConflictError4(err) {
-  const { status, body } = parseRequestError4(err);
+  const { status, body } = parseRequestError5(err);
   if (status !== 409 || !isPlainObject(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -12574,7 +12862,7 @@ var ProductDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError5(err) {
+function parseRequestError6(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -12585,7 +12873,7 @@ function parseRequestError5(err) {
   }
 }
 function toConflictError5(err) {
-  const { status, body } = parseRequestError5(err);
+  const { status, body } = parseRequestError6(err);
   if (status !== 409 || !isPlainObject(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -12784,6 +13072,25 @@ var ProductsNamespace = class {
   async pullFpo(name) {
     return pullFpo(this.getClient(), name);
   }
+  /**
+   * One request for the first page of every activity source a product has:
+   * conversations per conversational surface, executions per distinct agent.
+   * Rows, cursors and `hasMore` match the per-source list endpoints, so a
+   * caller continues any source with that source's own endpoint. A source that
+   * fails carries an `error` instead of failing the response.
+   *
+   * @example
+   * ```typescript
+   * const { data } = await Runtype.products.activity('prd_123', { limit: 25 })
+   * for (const surface of data.surfaces) console.log(surface.surfaceId, surface.data.length)
+   * ```
+   */
+  async activity(productId, options = {}) {
+    return this.getClient().get(
+      `/products/${encodeURIComponent(productId)}/activity`,
+      options.limit === void 0 ? void 0 : { limit: String(options.limit) }
+    );
+  }
 };
 
 // src/surfaces-ensure.ts
@@ -12884,7 +13191,7 @@ var SurfaceDriftError = class extends Error {
     this.plan = plan;
   }
 };
-function parseRequestError6(err) {
+function parseRequestError7(err) {
   if (!(err instanceof Error)) return { status: null, body: null };
   const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
   if (!match) return { status: null, body: null };
@@ -12895,7 +13202,7 @@ function parseRequestError6(err) {
   }
 }
 function toConflictError6(err) {
-  const { status, body } = parseRequestError6(err);
+  const { status, body } = parseRequestError7(err);
   if (status !== 409 || !isPlainObject(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
@@ -13067,11 +13374,11 @@ var RuntypeClient = class {
   /**
    * Generic PUT request
    */
-  async put(path, data) {
+  async put(path, data, extraHeaders) {
     const url = this.buildUrl(path);
     const response = await this.makeRequest(url, {
       method: "PUT",
-      headers: this.headers,
+      headers: { ...this.headers, ...extraHeaders },
       body: data ? JSON.stringify(data) : void 0
     });
     return response;
@@ -13091,11 +13398,12 @@ var RuntypeClient = class {
   /**
    * Generic DELETE request
    */
-  async delete(path) {
+  async delete(path, data, extraHeaders) {
     const url = this.buildUrl(path);
     const response = await this.makeRequest(url, {
       method: "DELETE",
-      headers: this.headers
+      headers: { ...this.headers, ...extraHeaders },
+      body: data ? JSON.stringify(data) : void 0
     });
     return response;
   }
@@ -13548,6 +13856,180 @@ var Runtype = class {
   }
 };
 
+// src/agent-promotion.ts
+var MANIFEST_VERSION = 1;
+var RECEIPT_PAGE_SIZE = 50;
+var MAX_RECEIPT_PAGES = 20;
+var AgentPromotionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentPromotionError";
+  }
+};
+function assertManifest(manifest) {
+  if (manifest?.manifest !== MANIFEST_VERSION) {
+    throw new AgentPromotionError(
+      `Unsupported promotion manifest version ${String(manifest?.manifest)}; expected ${MANIFEST_VERSION}.`
+    );
+  }
+}
+async function ensureInto(transport, body) {
+  return transport.post("/agents/ensure", body);
+}
+async function prepareAgentPromotion(input) {
+  if (input.alias === "live") {
+    throw new AgentPromotionError(
+      "prepare stages a candidate at a preview alias and never deploys: pass a non-live alias, then promote it with activate."
+    );
+  }
+  const pulled = await input.source.get("/agents/pull", { name: input.name });
+  const converged = await ensureInto(input.target, {
+    name: input.name,
+    definition: pulled.definition,
+    deploy: { alias: input.alias },
+    ...input.version ? { version: input.version } : {}
+  });
+  if (converged.result === "plan") {
+    throw new AgentPromotionError("The target converge answered a plan; expected a write.");
+  }
+  const deployment = converged.deployment;
+  if (!deployment?.versionId) {
+    throw new AgentPromotionError(
+      `The target converge did not stage a version at "${input.alias}"; nothing to promote.`
+    );
+  }
+  return {
+    manifest: MANIFEST_VERSION,
+    name: input.name,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    source: {
+      agentId: pulled.agentId,
+      versionId: pulled.versionId,
+      contentHash: pulled.contentHash,
+      ...input.commit ? { commit: input.commit } : {}
+    },
+    target: {
+      agentId: converged.agentId,
+      versionId: deployment.versionId,
+      alias: deployment.alias,
+      revision: deployment.revision,
+      contentHash: converged.contentHash
+    }
+  };
+}
+async function validateAgentPromotion(input) {
+  assertManifest(input.manifest);
+  const definition = input.definition ?? await repullStagedDefinition({
+    ...input.source ? { source: input.source } : {},
+    manifest: input.manifest
+  });
+  const planned = await ensureInto(input.target, {
+    name: input.manifest.name,
+    definition,
+    dryRun: true,
+    deploy: { alias: input.manifest.target.alias }
+  });
+  if (planned.result !== "plan") {
+    throw new AgentPromotionError(`Expected a plan from the dry run, got '${planned.result}'.`);
+  }
+  const staged = await findStagedReceipt(input.target, input.manifest);
+  if (!staged) {
+    throw new AgentPromotionError(
+      `No deployment receipt for version ${input.manifest.target.versionId} at "${input.manifest.target.alias}" on agent ${input.manifest.target.agentId}. The staged candidate is gone, so there is nothing to validate; re-run prepare.`
+    );
+  }
+  const refs = readReceiptRefs(staged);
+  const unresolvedRefs = refs.filter((ref) => ref.resolvedId === null).map((ref) => ref.ref);
+  return { ok: unresolvedRefs.length === 0, plan: planned, unresolvedRefs, refs };
+}
+async function repullStagedDefinition(input) {
+  if (!input.source) {
+    throw new AgentPromotionError(
+      "validate needs the definition it planned: pass definition, or pass source credentials to re-pull it."
+    );
+  }
+  const { name } = input.manifest;
+  const pulled = await input.source.get("/agents/pull", { name });
+  if (pulled.contentHash !== input.manifest.source.contentHash) {
+    throw new AgentPromotionError(
+      `The source definition changed since this promotion was prepared: the manifest was staged from ${input.manifest.source.contentHash}, and "${name}" now hashes to ${pulled.contentHash}. Re-run prepare so the artifact you validate is the one you staged.`
+    );
+  }
+  return pulled.definition;
+}
+async function findStagedReceipt(target, manifest) {
+  const deployments = new AgentDeploymentsNamespace(() => target);
+  let cursor;
+  for (let page = 0; page < MAX_RECEIPT_PAGES; page += 1) {
+    const answered = await deployments.list(manifest.target.agentId, {
+      alias: manifest.target.alias,
+      limit: RECEIPT_PAGE_SIZE,
+      ...cursor ? { cursor } : {}
+    });
+    const found = answered.data.find(
+      (receipt) => receipt.versionId === manifest.target.versionId
+    );
+    if (found) return found;
+    const next = answered.pagination?.nextCursor;
+    if (typeof next !== "string" || next.length === 0) return null;
+    cursor = next;
+  }
+  return null;
+}
+function readReceiptRefs(receipt) {
+  const dependencies = receipt?.dependencies;
+  const refs = dependencies?.refs;
+  if (!Array.isArray(refs)) return [];
+  return refs.flatMap((entry) => {
+    if (entry === null || typeof entry !== "object") return [];
+    const row = entry;
+    if (typeof row.ref !== "string") return [];
+    return [
+      {
+        ref: row.ref,
+        resolvedId: typeof row.resolvedId === "string" ? row.resolvedId : null,
+        fingerprint: typeof row.fingerprint === "string" ? row.fingerprint : null
+      }
+    ];
+  });
+}
+async function activateAgentPromotion(input) {
+  assertManifest(input.manifest);
+  const alias = input.alias ?? "live";
+  const aliases = new AgentAliasesNamespace(() => input.target);
+  const current = await aliases.get(input.manifest.target.agentId, alias).catch((error) => {
+    if (error instanceof AgentAliasNotFoundError) return null;
+    throw error;
+  });
+  return aliases.activate(input.manifest.target.agentId, alias, {
+    versionId: input.manifest.target.versionId,
+    ...current ? { revision: current.revision } : {},
+    idempotencyKey: input.idempotencyKey ?? promotionIdempotencyKey(input.manifest, alias),
+    ...input.reason ? { reason: input.reason } : {},
+    promotion: {
+      sourceAgentId: input.manifest.source.agentId,
+      ...input.manifest.source.versionId ? { sourceVersionId: input.manifest.source.versionId } : {},
+      sourceContentHash: input.manifest.source.contentHash,
+      ...input.manifest.source.commit ? { sourceCommit: input.manifest.source.commit } : {}
+    }
+  });
+}
+function promotionIdempotencyKey(manifest, alias) {
+  return `promote:${manifest.target.agentId}:${alias}:${manifest.target.versionId}`;
+}
+async function promoteAgent(input) {
+  const manifest = await prepareAgentPromotion(input);
+  const definition = await repullStagedDefinition({ source: input.source, manifest });
+  const validation = await validateAgentPromotion({ target: input.target, manifest, definition });
+  if (!input.activate) return { manifest, validation };
+  const activation = await activateAgentPromotion({
+    target: input.target,
+    manifest,
+    ...input.activate
+  });
+  return { manifest, validation, activation };
+}
+
 // src/transform.ts
 function transformQueryParams(params) {
   const result = {};
@@ -13565,7 +14047,7 @@ function transformQueryParams(params) {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "9.12.0".length > 0 ? "9.12.0" : FALLBACK_VERSION;
+var SDK_VERSION = "9.13.0".length > 0 ? "9.13.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 
@@ -13944,11 +14426,11 @@ var RuntypeClient2 = class {
   /**
    * Generic PUT request
    */
-  async put(path, data) {
+  async put(path, data, extraHeaders) {
     const url = this.buildUrl(path);
     const response = await this.makeRequest(url, {
       method: "PUT",
-      headers: this.headers,
+      headers: { ...this.headers, ...extraHeaders },
       body: data ? JSON.stringify(data) : void 0
     });
     return response;
@@ -13968,11 +14450,11 @@ var RuntypeClient2 = class {
   /**
    * Generic DELETE request
    */
-  async delete(path, data) {
+  async delete(path, data, extraHeaders) {
     const url = this.buildUrl(path);
     const response = await this.makeRequest(url, {
       method: "DELETE",
-      headers: this.headers,
+      headers: { ...this.headers, ...extraHeaders },
       body: data ? JSON.stringify(data) : void 0
     });
     return response;
@@ -14834,8 +15316,16 @@ var STEP_TYPE_TO_METHOD = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AgentAliasDependencyError,
+  AgentAliasNotFoundError,
+  AgentAliasPreviewLimitError,
+  AgentAliasRevisionMismatchError,
+  AgentAliasRevisionRequiredError,
+  AgentAliasesNamespace,
+  AgentDeploymentsNamespace,
   AgentDriftError,
   AgentEnsureConflictError,
+  AgentPromotionError,
   AgentVersionsEndpoint,
   AgentsEndpoint,
   AgentsNamespace,
@@ -14857,6 +15347,7 @@ var STEP_TYPE_TO_METHOD = {
   DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
   DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint,
+  ENSURE_RELEASE_DEPLOY_CONFLICT_MESSAGE,
   EvalBuilder,
   EvalEndpoint,
   EvalRunner,
@@ -14874,6 +15365,7 @@ var STEP_TYPE_TO_METHOD = {
   FlowsNamespace,
   IntegrationsEndpoint,
   LEDGER_ARTIFACT_LINE_PREFIX,
+  LIVE_AGENT_ALIAS,
   LogsEndpoint,
   ModelConfigsEndpoint,
   ProductDriftError,
@@ -14910,6 +15402,8 @@ var STEP_TYPE_TO_METHOD = {
   TypedRecordsScope,
   UNIFIED_EVENTS_QUERY,
   UsersEndpoint,
+  activateAgentPromotion,
+  agentAliasErrorCode,
   applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest,
   buildAgentAdmissionHeaders,
@@ -14987,7 +15481,10 @@ var STEP_TYPE_TO_METHOD = {
   parseLedgerArtifactRelativePath,
   parseOffloadedOutputId,
   parseSSEChunk,
+  prepareAgentPromotion,
   processStream,
+  promoteAgent,
+  promotionIdempotencyKey,
   pullEval,
   pullFpo,
   ranStep,
@@ -15005,6 +15502,7 @@ var STEP_TYPE_TO_METHOD = {
   unregisterWorkflowHook,
   usedNoTools,
   validJson,
+  validateAgentPromotion,
   withDetachedReconnect,
   withUnifiedEvents
 });