@runtypelabs/sdk 4.15.0 → 4.17.0

package/dist/index.cjs

@@ -73,9 +73,15 @@ __export(index_exports, {
   STEP_TYPE_TO_METHOD: () => STEP_TYPE_TO_METHOD,
   SchedulesEndpoint: () => SchedulesEndpoint,
   SecretsEndpoint: () => SecretsEndpoint,
+  SkillDriftError: () => SkillDriftError,
+  SkillEnsureConflictError: () => SkillEnsureConflictError,
   SkillProposalsNamespace: () => SkillProposalsNamespace,
   SkillsNamespace: () => SkillsNamespace,
+  SurfaceDriftError: () => SurfaceDriftError,
+  SurfaceEnsureConflictError: () => SurfaceEnsureConflictError,
   SurfacesEndpoint: () => SurfacesEndpoint,
+  SurfacesNamespace: () => SurfacesNamespace,
+  ToolApprovalGrantsEndpoint: () => ToolApprovalGrantsEndpoint,
   ToolDriftError: () => ToolDriftError,
   ToolEnsureConflictError: () => ToolEnsureConflictError,
   ToolsEndpoint: () => ToolsEndpoint,
@@ -92,6 +98,8 @@ __export(index_exports, {
   computeAgentContentHash: () => computeAgentContentHash,
   computeFlowContentHash: () => computeFlowContentHash,
   computeProductContentHash: () => computeProductContentHash,
+  computeSkillContentHash: () => computeSkillContentHash,
+  computeSurfaceContentHash: () => computeSurfaceContentHash,
   computeToolContentHash: () => computeToolContentHash,
   createClient: () => createClient,
   createExternalTool: () => createExternalTool,
@@ -101,6 +109,8 @@ __export(index_exports, {
   defineFlow: () => defineFlow,
   definePlaybook: () => definePlaybook,
   defineProduct: () => defineProduct,
+  defineSkill: () => defineSkill,
+  defineSurface: () => defineSurface,
   defineTool: () => defineTool,
   deployWorkflow: () => deployWorkflow,
   ensureDefaultWorkflowHooks: () => ensureDefaultWorkflowHooks,
@@ -118,6 +128,8 @@ __export(index_exports, {
   normalizeAgentDefinition: () => normalizeAgentDefinition,
   normalizeCandidatePath: () => normalizeCandidatePath,
   normalizeProductDefinition: () => normalizeProductDefinition,
+  normalizeSkillDefinition: () => normalizeSkillDefinition,
+  normalizeSurfaceDefinition: () => normalizeSurfaceDefinition,
   normalizeToolDefinition: () => normalizeToolDefinition,
   parseFinalBuffer: () => parseFinalBuffer,
   parseLedgerArtifactRelativePath: () => parseLedgerArtifactRelativePath,
@@ -1231,20 +1243,20 @@ var FlowBuilder = class {
    */
   build() {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request4 = { flow };
+    const request6 = { flow };
     if (this.recordConfig) {
-      request4.record = this.recordConfig;
+      request6.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request4.messages = this.messagesConfig;
+      request6.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request4.inputs = this.inputsConfig;
+      request6.inputs = this.inputsConfig;
     }
     if (Object.keys(this.optionsConfig).length > 0) {
-      request4.options = this.optionsConfig;
+      request6.options = this.optionsConfig;
     }
-    return request4;
+    return request6;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -2638,15 +2650,15 @@ var RuntypeFlowBuilder = class {
   build() {
     const flowMode = this.mode === "existing" ? "existing" : this.mode;
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request4 = { flow };
+    const request6 = { flow };
     if (this.recordConfig) {
-      request4.record = this.recordConfig;
+      request6.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request4.messages = this.messagesConfig;
+      request6.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request4.inputs = this.inputsConfig;
+      request6.inputs = this.inputsConfig;
     }
     const options = {
       flowMode,
@@ -2664,8 +2676,8 @@ var RuntypeFlowBuilder = class {
     if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
       options.upsertOptions = this.upsertOptions;
     }
-    request4.options = options;
-    return request4;
+    request6.options = options;
+    return request6;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -3259,6 +3271,192 @@ var PromptsNamespace = class {
   }
 };
 
+// src/skills-ensure.ts
+function isPlainObject2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue(item));
+  }
+  if (isPlainObject2(value)) {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || entry === null) continue;
+      normalized[key] = normalizeValue(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeSkillDefinition(definition) {
+  const manifest = isPlainObject2(definition.manifest) ? definition.manifest : {};
+  const rawFrontmatter = isPlainObject2(manifest.frontmatter) ? manifest.frontmatter : {};
+  const frontmatterWithoutName = {};
+  for (const key of Object.keys(rawFrontmatter)) {
+    if (key === "name") continue;
+    frontmatterWithoutName[key] = rawFrontmatter[key];
+  }
+  const frontmatter = normalizeValue(frontmatterWithoutName);
+  const runtype = isPlainObject2(manifest.runtype) ? normalizeValue(manifest.runtype) : {};
+  const body = typeof manifest.body === "string" ? manifest.body : "";
+  return { frontmatter, runtype, body };
+}
+async function computeSkillContentHash(definition) {
+  const serialized = JSON.stringify(normalizeSkillDefinition(definition));
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_SKILL_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "manifest"]);
+function defineSkill(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineSkill requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineSkill requires a non-empty string "name"');
+  }
+  if (!isPlainObject2(input.manifest)) {
+    throw new Error('defineSkill requires a "manifest" object ({ frontmatter, runtype, body })');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_SKILL_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineSkill: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name and manifest.`
+    );
+  }
+  const frontmatter = input.manifest.frontmatter;
+  if (!isPlainObject2(frontmatter) || typeof frontmatter.name !== "string") {
+    throw new Error("defineSkill: manifest.frontmatter.name is required");
+  }
+  if (frontmatter.name !== input.name) {
+    throw new Error(
+      `defineSkill: manifest.frontmatter.name ("${frontmatter.name}") must match the identity name ("${input.name}").`
+    );
+  }
+  return { name: input.name, manifest: input.manifest };
+}
+var SkillEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Skill ensure conflict: ${body.code}`);
+    this.name = "SkillEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var SkillDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Skill "${plan.skillId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.skills.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "SkillDriftError";
+    this.plan = plan;
+  }
+};
+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 };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError2(err) {
+  const { status, body } = parseRequestError2(err);
+  if (status !== 409 || !isPlainObject2(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new SkillEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo2 = /* @__PURE__ */ new WeakMap();
+function memoFor2(client) {
+  let memo = serverHashMemo2.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo2.set(client, memo);
+  }
+  return memo;
+}
+function memoize2(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request2(client, body) {
+  try {
+    return await client.post(
+      "/skills/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError2(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureSkill(client, definition, options = {}) {
+  const { dryRun, onConflict, release, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...release ? { release } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request2(client, {
+      name: definition.name,
+      definition: manifestToWire(definition),
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new SkillDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor2(client);
+  const localHash = await computeSkillContentHash(definition);
+  const memoKey = `${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request2(client, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize2(memo, memoKey, probe);
+    return probe;
+  }
+  const converged = await request2(client, {
+    name: definition.name,
+    definition: manifestToWire(definition),
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize2(memo, memoKey, converged);
+  return converged;
+}
+function manifestToWire(definition) {
+  const manifest = definition.manifest;
+  const frontmatter = { ...manifest.frontmatter };
+  if (manifest.runtype && Object.keys(manifest.runtype).length > 0) {
+    frontmatter.runtype = manifest.runtype;
+  }
+  return { frontmatter, body: manifest.body ?? "" };
+}
+async function pullSkill(client, name) {
+  return client.get("/skills/pull", { name });
+}
+
 // src/skills-namespace.ts
 var SkillProposalsNamespace = class {
   constructor(getClient) {
@@ -3399,6 +3597,22 @@ var SkillsNamespace = class {
     const client = this.getClient();
     await client.post(`/skills/${skillId}/versions/${versionId}/publish`);
   }
+  /**
+   * Statically scan a SKILL.md document for malicious patterns and return a
+   * two-tier verdict — `warning` when a skill appears suspicious (low–medium
+   * confidence), `error` when high-confidence malicious. Does not persist or
+   * gate; use it as a "scan before save" affordance.
+   *
+   * @example
+   * ```typescript
+   * const { verdict } = await Runtype.skills.scan(skillMarkdown)
+   * if (verdict.tier === 'error') console.warn(verdict.summary)
+   * ```
+   */
+  async scan(markdown) {
+    const client = this.getClient();
+    return client.post("/skills/scan", { markdown });
+  }
   /**
    * Import a single SKILL.md document. The imported skill lands with
    * `trustLevel: 'imported'` and a draft version.
@@ -3441,6 +3655,40 @@ var SkillsNamespace = class {
     const res = await client.get("/skills/bindings", { agentId });
     return res.data;
   }
+  /**
+   * Idempotently converge a `defineSkill` definition onto the platform.
+   * Hash-first: the steady state is one tiny probe request. Creates or appends a
+   * new version; never deletes. Identity is name + account scope. Pass
+   * `release: 'publish'` to publish the converged version.
+   *
+   * @example
+   * ```typescript
+   * const reviewer = defineSkill({
+   *   name: 'code_reviewer',
+   *   manifest: {
+   *     frontmatter: { name: 'code_reviewer', description: 'Reviews pull requests' },
+   *     runtype: { trustLevel: 'org' },
+   *     body: '# Code Reviewer\n\nReview the diff...',
+   *   },
+   * })
+   *
+   * // Converge + publish (CI/deploy).
+   * const result = await Runtype.skills.ensure(reviewer, { release: 'publish' })
+   *
+   * // PR drift gate.
+   * await Runtype.skills.ensure(reviewer, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    return ensureSkill(this.getClient(), definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a skill by name — the
+   * absorb-drift direction of the ensure protocol.
+   */
+  async pull(name) {
+    return pullSkill(this.getClient(), name);
+  }
 };
 
 // src/agents-namespace.ts
@@ -3466,19 +3714,19 @@ var AGENT_CONFIG_KEYS = [
   "memory"
 ];
 var AGENT_CONFIG_KEY_LIST = [...AGENT_CONFIG_KEYS].sort();
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function normalizeValue(value) {
+function normalizeValue2(value) {
   if (Array.isArray(value)) {
-    return value.map((item) => normalizeValue(item));
+    return value.map((item) => normalizeValue2(item));
   }
-  if (isPlainObject2(value)) {
+  if (isPlainObject3(value)) {
     const normalized = {};
     for (const key of Object.keys(value).sort()) {
       const entry = value[key];
       if (entry === void 0 || entry === null) continue;
-      normalized[key] = normalizeValue(entry);
+      normalized[key] = normalizeValue2(entry);
     }
     return normalized;
   }
@@ -3486,11 +3734,11 @@ function normalizeValue(value) {
 }
 function normalizeAgentDefinition(definition) {
   const config = {};
-  const rawConfig = isPlainObject2(definition.config) ? definition.config : {};
+  const rawConfig = isPlainObject3(definition.config) ? definition.config : {};
   for (const key of AGENT_CONFIG_KEY_LIST) {
     const value = rawConfig[key];
     if (value === void 0 || value === null) continue;
-    config[key] = normalizeValue(value);
+    config[key] = normalizeValue2(value);
   }
   return {
     name: definition.name,
@@ -3508,7 +3756,7 @@ async function computeAgentContentHash(definition) {
 var DEFINE_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "description", "icon", ...AGENT_CONFIG_KEYS]);
 function collectNonPortableToolRefs(config) {
   const tools = config.tools;
-  if (!isPlainObject2(tools)) return [];
+  if (!isPlainObject3(tools)) return [];
   const found = [];
   const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
   const scanArray = (value, path) => {
@@ -3518,7 +3766,7 @@ function collectNonPortableToolRefs(config) {
     });
   };
   const scanKeys = (value, path) => {
-    if (!isPlainObject2(value)) return;
+    if (!isPlainObject3(value)) return;
     for (const key of Object.keys(value)) {
       if (isAccountScoped(key)) found.push(`${path}.${key}`);
     }
@@ -3526,16 +3774,16 @@ function collectNonPortableToolRefs(config) {
   scanArray(tools.toolIds, "tools.toolIds");
   scanKeys(tools.toolConfigs, "tools.toolConfigs");
   scanKeys(tools.perToolLimits, "tools.perToolLimits");
-  if (isPlainObject2(tools.approval)) scanArray(tools.approval.require, "tools.approval.require");
-  if (isPlainObject2(tools.subagentConfig)) {
+  if (isPlainObject3(tools.approval)) scanArray(tools.approval.require, "tools.approval.require");
+  if (isPlainObject3(tools.subagentConfig)) {
     scanArray(tools.subagentConfig.toolPool, "tools.subagentConfig.toolPool");
   }
-  if (isPlainObject2(tools.codeModeConfig)) {
+  if (isPlainObject3(tools.codeModeConfig)) {
     scanArray(tools.codeModeConfig.toolPool, "tools.codeModeConfig.toolPool");
   }
   if (Array.isArray(tools.runtimeTools)) {
     tools.runtimeTools.forEach((runtimeTool, i) => {
-      if (!isPlainObject2(runtimeTool) || !isPlainObject2(runtimeTool.config)) return;
+      if (!isPlainObject3(runtimeTool) || !isPlainObject3(runtimeTool.config)) return;
       const base = `tools.runtimeTools[${i}].config`;
       const rtConfig = runtimeTool.config;
       if (runtimeTool.toolType === "subagent" && typeof rtConfig.agentId === "string" && rtConfig.agentId.startsWith("agent_")) {
@@ -3597,7 +3845,7 @@ var AgentDriftError = 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 };
@@ -3607,21 +3855,21 @@ function parseRequestError2(err) {
     return { status: Number(match[1]), body: null };
   }
 }
-function toConflictError2(err) {
-  const { status, body } = parseRequestError2(err);
-  if (status !== 409 || !isPlainObject2(body)) return null;
+function toConflictError3(err) {
+  const { status, body } = parseRequestError3(err);
+  if (status !== 409 || !isPlainObject3(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
   return new AgentEnsureConflictError(
     body
   );
 }
-var serverHashMemo2 = /* @__PURE__ */ new WeakMap();
-function memoFor2(client) {
-  let memo = serverHashMemo2.get(client);
+var serverHashMemo3 = /* @__PURE__ */ new WeakMap();
+function memoFor3(client) {
+  let memo = serverHashMemo3.get(client);
   if (!memo) {
     memo = /* @__PURE__ */ new Map();
-    serverHashMemo2.set(client, memo);
+    serverHashMemo3.set(client, memo);
   }
   return memo;
 }
@@ -3658,7 +3906,7 @@ var AgentsNamespace = class {
       }
       return plan;
     }
-    const memo = memoFor2(client);
+    const memo = memoFor3(client);
     const localHash = await computeAgentContentHash({
       ...definition,
       config: definition.config
@@ -3703,7 +3951,7 @@ var AgentsNamespace = class {
         body
       );
     } catch (err) {
-      const conflict = toConflictError2(err);
+      const conflict = toConflictError3(err);
       if (conflict) throw conflict;
       throw err;
     }
@@ -3711,27 +3959,27 @@ var AgentsNamespace = class {
 };
 
 // src/tools-ensure.ts
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function normalizeValue2(value) {
+function normalizeValue3(value) {
   if (Array.isArray(value)) {
-    return value.map((item) => normalizeValue2(item));
+    return value.map((item) => normalizeValue3(item));
   }
-  if (isPlainObject3(value)) {
+  if (isPlainObject4(value)) {
     const normalized = {};
     for (const key of Object.keys(value).sort()) {
       const entry = value[key];
       if (entry === void 0 || entry === null) continue;
-      normalized[key] = normalizeValue2(entry);
+      normalized[key] = normalizeValue3(entry);
     }
     return normalized;
   }
   return value;
 }
 function normalizeToolDefinition(definition) {
-  const parametersSchema = isPlainObject3(definition.parametersSchema) ? normalizeValue2(definition.parametersSchema) : {};
-  const config = isPlainObject3(definition.config) ? normalizeValue2(definition.config) : {};
+  const parametersSchema = isPlainObject4(definition.parametersSchema) ? normalizeValue3(definition.parametersSchema) : {};
+  const config = isPlainObject4(definition.config) ? normalizeValue3(definition.config) : {};
   return {
     toolType: definition.toolType,
     ...definition.description ? { description: definition.description } : {},
@@ -3776,10 +4024,10 @@ function defineTool(input) {
       `defineTool requires "toolType" to be one of: ${[...TOOL_DEFINITION_TYPES].join(", ")}`
     );
   }
-  if (!isPlainObject3(input.parametersSchema)) {
+  if (!isPlainObject4(input.parametersSchema)) {
     throw new Error('defineTool requires a "parametersSchema" object (a JSON Schema)');
   }
-  if (!isPlainObject3(input.config)) {
+  if (!isPlainObject4(input.config)) {
     throw new Error('defineTool requires a "config" object');
   }
   const unknownKeys = Object.keys(input).filter((key) => !DEFINE_TOOL_TOP_LEVEL_KEYS.has(key));
@@ -3815,7 +4063,7 @@ var ToolDriftError = 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 };
@@ -3825,35 +4073,35 @@ function parseRequestError3(err) {
     return { status: Number(match[1]), body: null };
   }
 }
-function toConflictError3(err) {
-  const { status, body } = parseRequestError3(err);
-  if (status !== 409 || !isPlainObject3(body)) return null;
+function toConflictError4(err) {
+  const { status, body } = parseRequestError4(err);
+  if (status !== 409 || !isPlainObject4(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
   return new ToolEnsureConflictError(
     body
   );
 }
-var serverHashMemo3 = /* @__PURE__ */ new WeakMap();
-function memoFor3(client) {
-  let memo = serverHashMemo3.get(client);
+var serverHashMemo4 = /* @__PURE__ */ new WeakMap();
+function memoFor4(client) {
+  let memo = serverHashMemo4.get(client);
   if (!memo) {
     memo = /* @__PURE__ */ new Map();
-    serverHashMemo3.set(client, memo);
+    serverHashMemo4.set(client, memo);
   }
   return memo;
 }
-function memoize2(memo, memoKey, result) {
+function memoize3(memo, memoKey, result) {
   if (result.result !== "plan") memo.set(memoKey, result.contentHash);
 }
-async function request2(client, body) {
+async function request3(client, body) {
   try {
     return await client.post(
       "/tools/ensure",
       body
     );
   } catch (err) {
-    const conflict = toConflictError3(err);
+    const conflict = toConflictError4(err);
     if (conflict) throw conflict;
     throw err;
   }
@@ -3865,7 +4113,7 @@ async function ensureTool(client, definition, options = {}) {
     ...expectedRemoteHash ? { expectedRemoteHash } : {}
   };
   if (dryRun || expectNoChanges) {
-    const plan = await request2(client, {
+    const plan = await request3(client, {
       name: definition.name,
       definition,
       dryRun: true,
@@ -3879,20 +4127,20 @@ async function ensureTool(client, definition, options = {}) {
     }
     return plan;
   }
-  const memo = memoFor3(client);
+  const memo = memoFor4(client);
   const localHash = await computeToolContentHash(definition);
   const memoKey = `${definition.name} ${localHash}`;
   const contentHash = memo.get(memoKey) ?? localHash;
-  const probe = await request2(client, {
+  const probe = await request3(client, {
     name: definition.name,
     contentHash,
     ...passthrough
   });
   if (probe.result !== "definitionRequired") {
-    memoize2(memo, memoKey, probe);
+    memoize3(memo, memoKey, probe);
     return probe;
   }
-  const converged = await request2(client, {
+  const converged = await request3(client, {
     name: definition.name,
     definition,
     ...passthrough
@@ -3900,7 +4148,7 @@ async function ensureTool(client, definition, options = {}) {
   if (converged.result === "definitionRequired") {
     throw new Error("Server reported definitionRequired for a full-definition request");
   }
-  memoize2(memo, memoKey, converged);
+  memoize3(memo, memoKey, converged);
   return converged;
 }
 async function pullTool(client, name) {
@@ -3947,26 +4195,26 @@ var ToolsNamespace = class {
 };
 
 // src/products-ensure.ts
-function isPlainObject4(value) {
+function isPlainObject5(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function normalizeValue3(value) {
+function normalizeValue4(value) {
   if (Array.isArray(value)) {
-    return value.map((item) => normalizeValue3(item));
+    return value.map((item) => normalizeValue4(item));
   }
-  if (isPlainObject4(value)) {
+  if (isPlainObject5(value)) {
     const normalized = {};
     for (const key of Object.keys(value).sort()) {
       const entry = value[key];
       if (entry === void 0 || entry === null) continue;
-      normalized[key] = normalizeValue3(entry);
+      normalized[key] = normalizeValue4(entry);
     }
     return normalized;
   }
   return value;
 }
 function normalizeProductDefinition(definition) {
-  const spec = isPlainObject4(definition.spec) ? normalizeValue3(definition.spec) : {};
+  const spec = isPlainObject5(definition.spec) ? normalizeValue4(definition.spec) : {};
   return {
     ...definition.description ? { description: definition.description } : {},
     ...definition.icon ? { icon: definition.icon } : {},
@@ -3993,7 +4241,7 @@ function defineProduct(input) {
   if (input.icon != null && typeof input.icon !== "string") {
     throw new Error('defineProduct "icon" must be a string when provided');
   }
-  if (input.spec != null && !isPlainObject4(input.spec)) {
+  if (input.spec != null && !isPlainObject5(input.spec)) {
     throw new Error('defineProduct "spec" must be an object when provided');
   }
   const unknownKeys = Object.keys(input).filter((key) => !DEFINE_PRODUCT_TOP_LEVEL_KEYS.has(key));
@@ -4028,7 +4276,7 @@ var ProductDriftError = 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 };
@@ -4038,35 +4286,35 @@ function parseRequestError4(err) {
     return { status: Number(match[1]), body: null };
   }
 }
-function toConflictError4(err) {
-  const { status, body } = parseRequestError4(err);
-  if (status !== 409 || !isPlainObject4(body)) return null;
+function toConflictError5(err) {
+  const { status, body } = parseRequestError5(err);
+  if (status !== 409 || !isPlainObject5(body)) return null;
   const code = body.code;
   if (code !== "external_modification" && code !== "remote_changed") return null;
   return new ProductEnsureConflictError(
     body
   );
 }
-var serverHashMemo4 = /* @__PURE__ */ new WeakMap();
-function memoFor4(client) {
-  let memo = serverHashMemo4.get(client);
+var serverHashMemo5 = /* @__PURE__ */ new WeakMap();
+function memoFor5(client) {
+  let memo = serverHashMemo5.get(client);
   if (!memo) {
     memo = /* @__PURE__ */ new Map();
-    serverHashMemo4.set(client, memo);
+    serverHashMemo5.set(client, memo);
   }
   return memo;
 }
-function memoize3(memo, memoKey, result) {
+function memoize4(memo, memoKey, result) {
   if (result.result !== "plan") memo.set(memoKey, result.contentHash);
 }
-async function request3(client, body) {
+async function request4(client, body) {
   try {
     return await client.post(
       "/products/ensure",
       body
     );
   } catch (err) {
-    const conflict = toConflictError4(err);
+    const conflict = toConflictError5(err);
     if (conflict) throw conflict;
     throw err;
   }
@@ -4078,7 +4326,7 @@ async function ensureProduct(client, definition, options = {}) {
     ...expectedRemoteHash ? { expectedRemoteHash } : {}
   };
   if (dryRun || expectNoChanges) {
-    const plan = await request3(client, {
+    const plan = await request4(client, {
       name: definition.name,
       definition,
       dryRun: true,
@@ -4092,20 +4340,20 @@ async function ensureProduct(client, definition, options = {}) {
     }
     return plan;
   }
-  const memo = memoFor4(client);
+  const memo = memoFor5(client);
   const localHash = await computeProductContentHash(definition);
   const memoKey = `${definition.name} ${localHash}`;
   const contentHash = memo.get(memoKey) ?? localHash;
-  const probe = await request3(client, {
+  const probe = await request4(client, {
     name: definition.name,
     contentHash,
     ...passthrough
   });
   if (probe.result !== "definitionRequired") {
-    memoize3(memo, memoKey, probe);
+    memoize4(memo, memoKey, probe);
     return probe;
   }
-  const converged = await request3(client, {
+  const converged = await request4(client, {
     name: definition.name,
     definition,
     ...passthrough
@@ -4113,7 +4361,7 @@ async function ensureProduct(client, definition, options = {}) {
   if (converged.result === "definitionRequired") {
     throw new Error("Server reported definitionRequired for a full-definition request");
   }
-  memoize3(memo, memoKey, converged);
+  memoize4(memo, memoKey, converged);
   return converged;
 }
 async function pullProduct(client, name) {
@@ -4159,6 +4407,262 @@ var ProductsNamespace = class {
   }
 };
 
+// src/surfaces-ensure.ts
+function isPlainObject6(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue5(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue5(item));
+  }
+  if (isPlainObject6(value)) {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || entry === null) continue;
+      normalized[key] = normalizeValue5(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeSurfaceDefinition(definition) {
+  const behavior = isPlainObject6(definition.behavior) ? normalizeValue5(definition.behavior) : { type: definition.type };
+  return {
+    type: definition.type,
+    behavior,
+    status: definition.status || "draft",
+    environment: definition.environment || "development"
+  };
+}
+async function computeSurfaceContentHash(definition) {
+  const serialized = JSON.stringify(normalizeSurfaceDefinition(definition));
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_SURFACE_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "type",
+  "behavior",
+  "inbound",
+  "outbound",
+  "status",
+  "environment"
+]);
+var SURFACE_DEFINITION_TYPES = /* @__PURE__ */ new Set([
+  "chat",
+  "mcp",
+  "mcp_code",
+  "api",
+  "webhook",
+  "schedule",
+  "a2a",
+  "email",
+  "slack",
+  "sms",
+  "imessage",
+  "discord",
+  "whatsapp",
+  "telegram",
+  "hosted-page",
+  "chrome_extension"
+]);
+function defineSurface(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineSurface requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineSurface requires a non-empty string "name"');
+  }
+  if (typeof input.type !== "string" || !SURFACE_DEFINITION_TYPES.has(input.type)) {
+    throw new Error(
+      `defineSurface requires "type" to be one of: ${[...SURFACE_DEFINITION_TYPES].join(", ")}`
+    );
+  }
+  if (input.behavior !== void 0 && !isPlainObject6(input.behavior)) {
+    throw new Error('defineSurface "behavior" must be an object when provided');
+  }
+  if (input.inbound !== void 0 && !isPlainObject6(input.inbound)) {
+    throw new Error('defineSurface "inbound" must be an object when provided');
+  }
+  if (input.outbound !== void 0 && !isPlainObject6(input.outbound)) {
+    throw new Error('defineSurface "outbound" must be an object when provided');
+  }
+  if (input.status !== void 0 && !["draft", "active", "paused"].includes(input.status)) {
+    throw new Error('defineSurface "status" must be one of: draft, active, paused');
+  }
+  if (input.environment !== void 0 && !["production", "development"].includes(input.environment)) {
+    throw new Error('defineSurface "environment" must be one of: production, development');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_SURFACE_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineSurface: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, type, behavior, inbound, outbound, status, environment.`
+    );
+  }
+  return {
+    name: input.name,
+    type: input.type,
+    ...input.behavior !== void 0 ? { behavior: input.behavior } : {},
+    ...input.inbound !== void 0 ? { inbound: input.inbound } : {},
+    ...input.outbound !== void 0 ? { outbound: input.outbound } : {},
+    ...input.status !== void 0 ? { status: input.status } : {},
+    ...input.environment !== void 0 ? { environment: input.environment } : {}
+  };
+}
+var SurfaceEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Surface ensure conflict: ${body.code}`);
+    this.name = "SurfaceEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var SurfaceDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Surface "${plan.surfaceId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.surfaces.pull(productId, name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "SurfaceDriftError";
+    this.plan = plan;
+  }
+};
+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 };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError6(err) {
+  const { status, body } = parseRequestError6(err);
+  if (status !== 409 || !isPlainObject6(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new SurfaceEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo6 = /* @__PURE__ */ new WeakMap();
+function memoFor6(client) {
+  let memo = serverHashMemo6.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo6.set(client, memo);
+  }
+  return memo;
+}
+function memoize5(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request5(client, productId, body) {
+  try {
+    return await client.post(
+      `/products/${encodeURIComponent(productId)}/surfaces/ensure`,
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError6(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureSurface(client, productId, definition, options = {}) {
+  const { dryRun, onConflict, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request5(client, productId, {
+      name: definition.name,
+      definition,
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new SurfaceDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor6(client);
+  const localHash = await computeSurfaceContentHash(definition);
+  const memoKey = `${productId} ${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request5(client, productId, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize5(memo, memoKey, probe);
+    return probe;
+  }
+  const converged = await request5(client, productId, {
+    name: definition.name,
+    definition,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize5(memo, memoKey, converged);
+  return converged;
+}
+async function pullSurface(client, productId, name) {
+  return client.get(
+    `/products/${encodeURIComponent(productId)}/surfaces/pull`,
+    { name }
+  );
+}
+
+// src/surfaces-namespace.ts
+var SurfacesNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Idempotently converge a `defineSurface` definition onto a product.
+   * Hash-first: the steady state is one tiny probe request. Creates or updates
+   * the surface; never deletes. Identity is name + product.
+   *
+   * @example
+   * ```typescript
+   * const chat = defineSurface({
+   *   name: 'Support Chat',
+   *   type: 'chat',
+   *   behavior: { type: 'chat', greeting: 'Hi there!' },
+   *   status: 'active',
+   * })
+   *
+   * // Converge (CI/deploy).
+   * const result = await Runtype.surfaces.ensure('product_abc', chat)
+   *
+   * // PR drift gate.
+   * await Runtype.surfaces.ensure('product_abc', chat, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(productId, definition, options = {}) {
+    return ensureSurface(this.getClient(), productId, definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a surface by name within a
+   * product — the absorb-drift direction of the ensure protocol.
+   */
+  async pull(productId, name) {
+    return pullSurface(this.getClient(), productId, name);
+  }
+};
+
 // src/transform.ts
 function transformResponse(data) {
   return data;
@@ -4606,6 +5110,35 @@ var Runtype = class {
   static get products() {
     return new ProductsNamespace(() => this.getClient());
   }
+  /**
+   * Config-as-code operations for product surfaces. `surfaces.ensure` is the
+   * deploy-time, non-executing converge (create-or-update a surface by name
+   * within a product); `surfaces.pull` is the absorb-drift direction.
+   *
+   * @example
+   * ```typescript
+   * import { Runtype, defineSurface } from '@runtypelabs/sdk'
+   *
+   * const chat = defineSurface({
+   *   name: 'Support Chat',
+   *   type: 'chat',
+   *   behavior: { type: 'chat', greeting: 'Hi there!' },
+   *   status: 'active',
+   * })
+   *
+   * // Converge at deploy time (idempotent; one tiny probe in steady state)
+   * await Runtype.surfaces.ensure('product_abc', chat)
+   *
+   * // CI drift gate
+   * await Runtype.surfaces.ensure('product_abc', chat, { expectNoChanges: true })
+   *
+   * // Absorb a dashboard edit back into the repo
+   * const { definition } = await Runtype.surfaces.pull('product_abc', 'Support Chat')
+   * ```
+   */
+  static get surfaces() {
+    return new SurfacesNamespace(() => this.getClient());
+  }
 };
 
 // src/generated-tool-gate.ts
@@ -4828,8 +5361,8 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
     ...decision.tool ? { tool: decision.tool } : {}
   };
 }
-function attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options = {}) {
-  const stepList = request4.flow.steps;
+function attachRuntimeToolsToDispatchRequest(request6, runtimeTools, options = {}) {
+  const stepList = request6.flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -4872,9 +5405,9 @@ function attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options = {
     }
   };
   return {
-    ...request4,
+    ...request6,
     flow: {
-      ...request4.flow,
+      ...request6.flow,
       // `clonedSteps` is a structural clone of `request.flow.steps` (already
       // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
       // merged, so every step's `type` discriminant is preserved. The clone is
@@ -4884,12 +5417,12 @@ function attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options = {
     }
   };
 }
-function applyGeneratedRuntimeToolProposalToDispatchRequest(request4, proposal, options = {}) {
+function applyGeneratedRuntimeToolProposalToDispatchRequest(request6, proposal, options = {}) {
   const decision = evaluateGeneratedRuntimeToolProposal(proposal, options.gate);
   if (!decision.approved || !decision.tool) {
-    return { decision, request: request4 };
+    return { decision, request: request6 };
   }
-  const nextRequest = attachRuntimeToolsToDispatchRequest(request4, [decision.tool], options.attach);
+  const nextRequest = attachRuntimeToolsToDispatchRequest(request6, [decision.tool], options.attach);
   return {
     decision,
     request: nextRequest
@@ -7139,15 +7672,15 @@ var DispatchEndpoint = class {
    * Attach approved runtime tools to a prompt step in a redispatch request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request4, runtimeTools, options) {
-    return attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options);
+  attachApprovedRuntimeTools(request6, runtimeTools, options) {
+    return attachRuntimeToolsToDispatchRequest(request6, runtimeTools, options);
   }
   /**
    * Validate a generated runtime tool proposal and attach it to the redispatch
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request4, proposal, options) {
-    return applyGeneratedRuntimeToolProposalToDispatchRequest(request4, proposal, options);
+  applyGeneratedRuntimeToolProposal(request6, proposal, options) {
+    return applyGeneratedRuntimeToolProposalToDispatchRequest(request6, proposal, options);
   }
 };
 var ChatEndpoint = class {
@@ -7699,8 +8232,8 @@ var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   },
   required: ["name", "description", "toolType", "parametersSchema", "config"]
 };
-function appendRuntimeToolsToAgentRequest(request4, runtimeTools) {
-  const existing = request4.tools?.runtimeTools || [];
+function appendRuntimeToolsToAgentRequest(request6, runtimeTools) {
+  const existing = request6.tools?.runtimeTools || [];
   const existingNames = new Set(existing.map((tool) => tool.name));
   const converted = runtimeTools.filter((tool) => !existingNames.has(tool.name)).map((tool) => ({
     name: tool.name,
@@ -7710,9 +8243,9 @@ function appendRuntimeToolsToAgentRequest(request4, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request4,
+    ...request6,
     tools: {
-      ...request4.tools,
+      ...request6.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -7788,21 +8321,21 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * Attach approved runtime tools to an agent execute request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request4, runtimeTools) {
-    return appendRuntimeToolsToAgentRequest(request4, runtimeTools);
+  attachApprovedRuntimeTools(request6, runtimeTools) {
+    return appendRuntimeToolsToAgentRequest(request6, runtimeTools);
   }
   /**
    * Validate a generated runtime tool proposal and append it to an agent execute
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request4, proposal, options) {
+  applyGeneratedRuntimeToolProposal(request6, proposal, options) {
     const decision = evaluateGeneratedRuntimeToolProposal(proposal, options);
     if (!decision.approved || !decision.tool) {
-      return { decision, request: request4 };
+      return { decision, request: request6 };
     }
     return {
       decision,
-      request: appendRuntimeToolsToAgentRequest(request4, [decision.tool])
+      request: appendRuntimeToolsToAgentRequest(request6, [decision.tool])
     };
   }
   /**
@@ -10903,6 +11436,29 @@ var BillingEndpoint = class {
     return this.client.get("/billing/spend-analytics", params);
   }
 };
+var ToolApprovalGrantsEndpoint = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List active remembered tool-approval grants for the authenticated owner,
+   * optionally filtered to a single agent.
+   */
+  async list(agentId) {
+    const query = agentId ? `?agentId=${encodeURIComponent(agentId)}` : "";
+    const response = await this.client.get(
+      `/tool-approval-grants${query}`
+    );
+    return response.data;
+  }
+  /**
+   * Revoke (soft-delete) a remembered grant so the tool prompts for approval
+   * again on future dispatches.
+   */
+  async revoke(id) {
+    return this.client.delete(`/tool-approval-grants/${id}`);
+  }
+};
 var AppsEndpoint = class {
   constructor(client) {
     this.client = client;
@@ -11000,6 +11556,7 @@ var RuntypeClient2 = class {
     this.flowVersions = new FlowVersionsEndpoint(this);
     this.integrations = new IntegrationsEndpoint(this);
     this.billing = new BillingEndpoint(this);
+    this.toolApprovalGrants = new ToolApprovalGrantsEndpoint(this);
   }
   /**
    * Set the API key for authentication
@@ -11038,7 +11595,7 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  async runWithLocalTools(request4, localTools, arg3, arg4) {
+  async runWithLocalTools(request6, localTools, arg3, arg4) {
     const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
     const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
     const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
@@ -11052,12 +11609,12 @@ var RuntypeClient2 = class {
       ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
     })) : [];
     const modifiedRequest = {
-      ...request4,
+      ...request6,
       ...derivedClientTools.length > 0 ? {
-        clientTools: [...request4.clientTools ?? [], ...derivedClientTools]
+        clientTools: [...request6.clientTools ?? [], ...derivedClientTools]
       } : {},
       options: {
-        ...request4.options || {},
+        ...request6.options || {},
         streamResponse: isStreaming
       }
     };
@@ -11217,6 +11774,30 @@ var RuntypeClient2 = class {
     });
     return transformResponse(response);
   }
+  /**
+   * Conditional GET (`ETag` / `If-None-Match`).
+   *
+   * Unlike {@link get}, this does NOT throw on `304` — it surfaces the not-modified
+   * outcome so callers can keep their cached copy. Used by the dashboard's primary
+   * lists to revalidate the canonical first page in a single round trip on both
+   * the changed and unchanged paths. The `304` path returns no body; the `200`
+   * path returns the parsed body plus the server's fresh `ETag`.
+   */
+  async getConditional(path, params, ifNoneMatch) {
+    const url = this.buildUrl(path, params);
+    const headers = { ...this.headers };
+    if (ifNoneMatch) headers["If-None-Match"] = ifNoneMatch;
+    const response = await this.fetchWithTimeout(url, { method: "GET", headers });
+    const etag = response.headers.get("ETag");
+    if (response.status === 304) {
+      return { notModified: true, etag };
+    }
+    if (!response.ok) {
+      throw await this.createApiError(response);
+    }
+    const data = transformResponse(await response.json());
+    return { notModified: false, etag, data };
+  }
   /**
    * Generic POST request
    */
@@ -11335,7 +11916,15 @@ var RuntypeClient2 = class {
   /**
    * Make HTTP request with timeout and error handling
    */
-  async makeRequest(url, options) {
+  /**
+   * Run a fetch under the client timeout and return the raw `Response`. Maps a
+   * timeout-driven `AbortError` to a descriptive timeout `Error`; does NOT inspect
+   * status, so callers decide how to treat non-2xx (throw, intercept `304`, etc.).
+   *
+   * `makeRawRequest` keeps its own variant: it additionally composes a
+   * caller-supplied `signal` (user-initiated stream aborts) with the timeout.
+   */
+  async fetchWithTimeout(url, options) {
     const controller = this.timeout === null ? null : new AbortController();
     const timeoutId = controller && this.timeout !== null ? setTimeout(() => controller.abort(), this.timeout) : null;
     try {
@@ -11344,17 +11933,7 @@ var RuntypeClient2 = class {
         ...controller ? { signal: controller.signal } : {}
       });
       if (timeoutId) clearTimeout(timeoutId);
-      if (!response.ok) {
-        throw await this.createApiError(response);
-      }
-      if (response.status === 204) {
-        return null;
-      }
-      const contentType = response.headers.get("content-type");
-      if (contentType?.includes("application/json")) {
-        return response.json();
-      }
-      return response.text();
+      return response;
     } catch (error) {
       if (timeoutId) clearTimeout(timeoutId);
       if (timeoutId && error instanceof Error && error.name === "AbortError") {
@@ -11363,6 +11942,20 @@ var RuntypeClient2 = class {
       throw error;
     }
   }
+  async makeRequest(url, options) {
+    const response = await this.fetchWithTimeout(url, options);
+    if (!response.ok) {
+      throw await this.createApiError(response);
+    }
+    if (response.status === 204) {
+      return null;
+    }
+    const contentType = response.headers.get("content-type");
+    if (contentType?.includes("application/json")) {
+      return response.json();
+    }
+    return response.text();
+  }
   /**
    * Make HTTP request that returns raw Response (for streaming)
    */
@@ -11495,20 +12088,20 @@ var BatchBuilder = class {
     if (!this.recordType) {
       throw new Error("BatchBuilder: recordType is required. Call .forRecordType(type) first.");
     }
-    const request4 = {
+    const request6 = {
       flowId: this.flowId,
       recordType: this.recordType
     };
     if (Object.keys(this.batchOptions).length > 0) {
-      request4.options = this.batchOptions;
+      request6.options = this.batchOptions;
     }
     if (this.filterConfig) {
-      request4.filter = this.filterConfig;
+      request6.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request4.limit = this.limitConfig;
+      request6.limit = this.limitConfig;
     }
-    return request4;
+    return request6;
   }
   /**
    * Execute the batch operation
@@ -11665,32 +12258,32 @@ var EvalBuilder = class {
         "EvalBuilder: records are required. Call .forRecordType(type) or .withRecords([...]) first."
       );
     }
-    const request4 = {};
+    const request6 = {};
     if (this.flowId) {
-      request4.flowId = this.flowId;
+      request6.flowId = this.flowId;
     } else if (this.virtualFlow) {
-      request4.flow = this.virtualFlow;
+      request6.flow = this.virtualFlow;
     }
     if (this.recordType) {
-      request4.recordType = this.recordType;
+      request6.recordType = this.recordType;
     } else if (this.inlineRecords) {
-      request4.records = this.inlineRecords;
+      request6.records = this.inlineRecords;
     }
     if (this.modelOverrides) {
-      request4.modelOverrides = this.modelOverrides;
+      request6.modelOverrides = this.modelOverrides;
     } else if (this.modelConfigs) {
-      request4.modelConfigs = this.modelConfigs;
+      request6.modelConfigs = this.modelConfigs;
     }
     if (Object.keys(this.evalOptions).length > 0) {
-      request4.options = this.evalOptions;
+      request6.options = this.evalOptions;
     }
     if (this.filterConfig) {
-      request4.filter = this.filterConfig;
+      request6.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request4.limit = this.limitConfig;
+      request6.limit = this.limitConfig;
     }
-    return request4;
+    return request6;
   }
   /**
    * Execute the evaluation
@@ -12210,9 +12803,15 @@ var STEP_TYPE_TO_METHOD = {
   STEP_TYPE_TO_METHOD,
   SchedulesEndpoint,
   SecretsEndpoint,
+  SkillDriftError,
+  SkillEnsureConflictError,
   SkillProposalsNamespace,
   SkillsNamespace,
+  SurfaceDriftError,
+  SurfaceEnsureConflictError,
   SurfacesEndpoint,
+  SurfacesNamespace,
+  ToolApprovalGrantsEndpoint,
   ToolDriftError,
   ToolEnsureConflictError,
   ToolsEndpoint,
@@ -12229,6 +12828,8 @@ var STEP_TYPE_TO_METHOD = {
   computeAgentContentHash,
   computeFlowContentHash,
   computeProductContentHash,
+  computeSkillContentHash,
+  computeSurfaceContentHash,
   computeToolContentHash,
   createClient,
   createExternalTool,
@@ -12238,6 +12839,8 @@ var STEP_TYPE_TO_METHOD = {
   defineFlow,
   definePlaybook,
   defineProduct,
+  defineSkill,
+  defineSurface,
   defineTool,
   deployWorkflow,
   ensureDefaultWorkflowHooks,
@@ -12255,6 +12858,8 @@ var STEP_TYPE_TO_METHOD = {
   normalizeAgentDefinition,
   normalizeCandidatePath,
   normalizeProductDefinition,
+  normalizeSkillDefinition,
+  normalizeSurfaceDefinition,
   normalizeToolDefinition,
   parseFinalBuffer,
   parseLedgerArtifactRelativePath,