@runtypelabs/sdk 4.11.0 → 4.13.0

package/dist/index.cjs

@@ -73,7 +73,10 @@ __export(index_exports, {
   SkillProposalsNamespace: () => SkillProposalsNamespace,
   SkillsNamespace: () => SkillsNamespace,
   SurfacesEndpoint: () => SurfacesEndpoint,
+  ToolDriftError: () => ToolDriftError,
+  ToolEnsureConflictError: () => ToolEnsureConflictError,
   ToolsEndpoint: () => ToolsEndpoint,
+  ToolsNamespace: () => ToolsNamespace,
   UsersEndpoint: () => UsersEndpoint,
   applyGeneratedRuntimeToolProposalToDispatchRequest: () => applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest: () => attachRuntimeToolsToDispatchRequest,
@@ -85,6 +88,7 @@ __export(index_exports, {
   compileWorkflowConfig: () => compileWorkflowConfig,
   computeAgentContentHash: () => computeAgentContentHash,
   computeFlowContentHash: () => computeFlowContentHash,
+  computeToolContentHash: () => computeToolContentHash,
   createClient: () => createClient,
   createExternalTool: () => createExternalTool,
   defaultWorkflow: () => defaultWorkflow,
@@ -92,6 +96,7 @@ __export(index_exports, {
   defineAgent: () => defineAgent,
   defineFlow: () => defineFlow,
   definePlaybook: () => definePlaybook,
+  defineTool: () => defineTool,
   deployWorkflow: () => deployWorkflow,
   ensureDefaultWorkflowHooks: () => ensureDefaultWorkflowHooks,
   evaluateGeneratedRuntimeToolProposal: () => evaluateGeneratedRuntimeToolProposal,
@@ -107,6 +112,7 @@ __export(index_exports, {
   listWorkflowHooks: () => listWorkflowHooks,
   normalizeAgentDefinition: () => normalizeAgentDefinition,
   normalizeCandidatePath: () => normalizeCandidatePath,
+  normalizeToolDefinition: () => normalizeToolDefinition,
   parseFinalBuffer: () => parseFinalBuffer,
   parseLedgerArtifactRelativePath: () => parseLedgerArtifactRelativePath,
   parseOffloadedOutputId: () => parseOffloadedOutputId,
@@ -1219,20 +1225,20 @@ var FlowBuilder = class {
    */
   build() {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request2 = { flow };
+    const request3 = { flow };
     if (this.recordConfig) {
-      request2.record = this.recordConfig;
+      request3.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request2.messages = this.messagesConfig;
+      request3.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request2.inputs = this.inputsConfig;
+      request3.inputs = this.inputsConfig;
     }
     if (Object.keys(this.optionsConfig).length > 0) {
-      request2.options = this.optionsConfig;
+      request3.options = this.optionsConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -1529,6 +1535,7 @@ function collectStepNonPortableToolRefs(config, path) {
   const found = [];
   const tools = config.tools;
   const isAccountScoped = (ref) => typeof ref === "string" && ref.startsWith("tool_");
+  const isRawId = (ref, prefix) => typeof ref === "string" && ref.startsWith(prefix);
   const scanArray = (value, subPath) => {
     if (!Array.isArray(value)) return;
     value.forEach((ref, i) => {
@@ -1554,6 +1561,24 @@ function collectStepNonPortableToolRefs(config, path) {
     if (isPlainObject(tools.codeModeConfig)) {
       scanArray(tools.codeModeConfig.toolPool, `${path}.tools.codeModeConfig.toolPool`);
     }
+    if (Array.isArray(tools.runtimeTools)) {
+      tools.runtimeTools.forEach((runtimeTool, i) => {
+        if (!isPlainObject(runtimeTool) || !isPlainObject(runtimeTool.config)) return;
+        const base = `${path}.tools.runtimeTools[${i}].config`;
+        const rtConfig = runtimeTool.config;
+        if (runtimeTool.toolType === "subagent" && isRawId(rtConfig.agentId, "agent_")) {
+          found.push(`${base}.agentId`);
+        } else if (runtimeTool.toolType === "flow" && isRawId(rtConfig.flowId, "flow_")) {
+          found.push(`${base}.flowId`);
+        }
+      });
+    }
+  }
+  if (isAccountScoped(config.toolId)) {
+    found.push(`${path}.toolId`);
+  }
+  if (isRawId(config.agentId, "agent_")) {
+    found.push(`${path}.agentId`);
   }
   for (const branch of ["trueSteps", "falseSteps"]) {
     const nested = config[branch];
@@ -1608,7 +1633,7 @@ function defineFlow(input) {
       const nonPortable = collectStepNonPortableToolRefs(config, `steps[${index}].config`);
       if (nonPortable.length > 0) {
         throw new Error(
-          `defineFlow: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+          `defineFlow: account-scoped reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026/agent_\u2026/flow_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved resource by name \u2014 tool:<name>, agent:<name>, or flow:<name> instead.`
         );
       }
     }
@@ -2607,15 +2632,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 request2 = { flow };
+    const request3 = { flow };
     if (this.recordConfig) {
-      request2.record = this.recordConfig;
+      request3.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request2.messages = this.messagesConfig;
+      request3.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request2.inputs = this.inputsConfig;
+      request3.inputs = this.inputsConfig;
     }
     const options = {
       flowMode,
@@ -2633,8 +2658,8 @@ var RuntypeFlowBuilder = class {
     if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
       options.upsertOptions = this.upsertOptions;
     }
-    request2.options = options;
-    return request2;
+    request3.options = options;
+    return request3;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -3501,6 +3526,18 @@ function collectNonPortableToolRefs(config) {
   if (isPlainObject2(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;
+      const base = `tools.runtimeTools[${i}].config`;
+      const rtConfig = runtimeTool.config;
+      if (runtimeTool.toolType === "subagent" && typeof rtConfig.agentId === "string" && rtConfig.agentId.startsWith("agent_")) {
+        found.push(`${base}.agentId`);
+      } else if (runtimeTool.toolType === "flow" && typeof rtConfig.flowId === "string" && rtConfig.flowId.startsWith("flow_")) {
+        found.push(`${base}.flowId`);
+      }
+    });
+  }
   return found;
 }
 function defineAgent(input) {
@@ -3524,7 +3561,7 @@ function defineAgent(input) {
   const nonPortable = collectNonPortableToolRefs(config);
   if (nonPortable.length > 0) {
     throw new Error(
-      `defineAgent: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+      `defineAgent: account-scoped reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026/agent_\u2026/flow_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved resource by name \u2014 tool:<name>, agent:<name>, or flow:<name> instead.`
     );
   }
   return {
@@ -3666,6 +3703,242 @@ var AgentsNamespace = class {
   }
 };
 
+// src/tools-ensure.ts
+function isPlainObject3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue2(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue2(item));
+  }
+  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] = normalizeValue2(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeToolDefinition(definition) {
+  const parametersSchema = isPlainObject3(definition.parametersSchema) ? normalizeValue2(definition.parametersSchema) : {};
+  const config = isPlainObject3(definition.config) ? normalizeValue2(definition.config) : {};
+  return {
+    toolType: definition.toolType,
+    ...definition.description ? { description: definition.description } : {},
+    parametersSchema,
+    config
+  };
+}
+async function computeToolContentHash(definition) {
+  const serialized = JSON.stringify(normalizeToolDefinition(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_TOOL_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "toolType",
+  "parametersSchema",
+  "config"
+]);
+var TOOL_DEFINITION_TYPES = /* @__PURE__ */ new Set([
+  "flow",
+  "custom",
+  "external",
+  "graphql",
+  "mcp",
+  "local",
+  "subagent"
+]);
+function defineTool(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineTool requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineTool requires a non-empty string "name"');
+  }
+  if (typeof input.description !== "string" || input.description.length === 0) {
+    throw new Error('defineTool requires a non-empty string "description"');
+  }
+  if (typeof input.toolType !== "string" || !TOOL_DEFINITION_TYPES.has(input.toolType)) {
+    throw new Error(
+      `defineTool requires "toolType" to be one of: ${[...TOOL_DEFINITION_TYPES].join(", ")}`
+    );
+  }
+  if (!isPlainObject3(input.parametersSchema)) {
+    throw new Error('defineTool requires a "parametersSchema" object (a JSON Schema)');
+  }
+  if (!isPlainObject3(input.config)) {
+    throw new Error('defineTool requires a "config" object');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_TOOL_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineTool: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, description, toolType, parametersSchema, config.`
+    );
+  }
+  return {
+    name: input.name,
+    description: input.description,
+    toolType: input.toolType,
+    parametersSchema: input.parametersSchema,
+    config: input.config
+  };
+}
+var ToolEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Tool ensure conflict: ${body.code}`);
+    this.name = "ToolEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var ToolDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Tool "${plan.toolId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.tools.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "ToolDriftError";
+    this.plan = plan;
+  }
+};
+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 };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: 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 ToolEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo3 = /* @__PURE__ */ new WeakMap();
+function memoFor3(client) {
+  let memo = serverHashMemo3.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo3.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(
+      "/tools/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError3(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureTool(client, definition, options = {}) {
+  const { dryRun, onConflict, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request2(client, {
+      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 ToolDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor3(client);
+  const localHash = await computeToolContentHash(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,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize2(memo, memoKey, converged);
+  return converged;
+}
+async function pullTool(client, name) {
+  return client.get("/tools/pull", { name });
+}
+
+// src/tools-namespace.ts
+var ToolsNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Idempotently converge a `defineTool` definition onto the platform.
+   * Hash-first: the steady state is one tiny probe request. Creates or updates
+   * the saved tool; never deletes. Identity is name + account scope.
+   *
+   * @example
+   * ```typescript
+   * const weather = defineTool({
+   *   name: 'Weather Lookup',
+   *   description: 'Fetch the current weather for a city',
+   *   toolType: 'external',
+   *   parametersSchema: { type: 'object', properties: { city: { type: 'string' } } },
+   *   config: { url: 'https://api.example.com/weather', method: 'GET' },
+   * })
+   *
+   * // Converge (CI/deploy).
+   * const result = await Runtype.tools.ensure(weather)
+   *
+   * // PR drift gate.
+   * await Runtype.tools.ensure(weather, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    return ensureTool(this.getClient(), definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a tool by name — the
+   * absorb-drift direction of the ensure protocol.
+   */
+  async pull(name) {
+    return pullTool(this.getClient(), name);
+  }
+};
+
 // src/transform.ts
 function transformResponse(data) {
   return data;
@@ -4054,6 +4327,34 @@ var Runtype = class {
   static get agents() {
     return new AgentsNamespace(() => this.getClient());
   }
+  /**
+   * Tools namespace - Tool config-as-code (define / ensure / pull)
+   *
+   * @example
+   * ```typescript
+   * import { defineTool, Runtype } from '@runtypelabs/sdk'
+   *
+   * const weather = defineTool({
+   *   name: 'Weather Lookup',
+   *   description: 'Fetch the current weather for a city',
+   *   toolType: 'external',
+   *   parametersSchema: { type: 'object', properties: { city: { type: 'string' } } },
+   *   config: { url: 'https://api.example.com/weather', method: 'GET' },
+   * })
+   *
+   * // Converge at deploy time (idempotent; one tiny probe in steady state)
+   * await Runtype.tools.ensure(weather)
+   *
+   * // CI drift gate
+   * await Runtype.tools.ensure(weather, { expectNoChanges: true })
+   *
+   * // Absorb a dashboard edit back into the repo
+   * const { definition } = await Runtype.tools.pull('Weather Lookup')
+   * ```
+   */
+  static get tools() {
+    return new ToolsNamespace(() => this.getClient());
+  }
 };
 
 // src/generated-tool-gate.ts
@@ -4276,8 +4577,8 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
     ...decision.tool ? { tool: decision.tool } : {}
   };
 }
-function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {}) {
-  const stepList = request2.flow.steps;
+function attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options = {}) {
+  const stepList = request3.flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -4320,9 +4621,9 @@ function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {
     }
   };
   return {
-    ...request2,
+    ...request3,
     flow: {
-      ...request2.flow,
+      ...request3.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
@@ -4332,12 +4633,12 @@ function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {
     }
   };
 }
-function applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options = {}) {
+function applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options = {}) {
   const decision = evaluateGeneratedRuntimeToolProposal(proposal, options.gate);
   if (!decision.approved || !decision.tool) {
-    return { decision, request: request2 };
+    return { decision, request: request3 };
   }
-  const nextRequest = attachRuntimeToolsToDispatchRequest(request2, [decision.tool], options.attach);
+  const nextRequest = attachRuntimeToolsToDispatchRequest(request3, [decision.tool], options.attach);
   return {
     decision,
     request: nextRequest
@@ -6246,6 +6547,19 @@ var RecordsEndpoint = class {
   async getResults(id, params) {
     return this.client.get(`/records/${id}/results`, params);
   }
+  /**
+   * Get unified step-level execution results for a record, with filtering and
+   * pagination.
+   */
+  async getStepResults(id, params) {
+    return this.client.get(`/records/${id}/step-results`, params);
+  }
+  /**
+   * Get the aggregated cost breakdown (by model) for a record's executions.
+   */
+  async getCosts(id) {
+    return this.client.get(`/records/${id}/costs`);
+  }
   /**
    * Delete a specific result for a record
    */
@@ -6574,15 +6888,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(request2, runtimeTools, options) {
-    return attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options);
+  attachApprovedRuntimeTools(request3, runtimeTools, options) {
+    return attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options);
   }
   /**
    * Validate a generated runtime tool proposal and attach it to the redispatch
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
-    return applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options);
+  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
+    return applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options);
   }
 };
 var ChatEndpoint = class {
@@ -7134,8 +7448,8 @@ var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   },
   required: ["name", "description", "toolType", "parametersSchema", "config"]
 };
-function appendRuntimeToolsToAgentRequest(request2, runtimeTools) {
-  const existing = request2.tools?.runtimeTools || [];
+function appendRuntimeToolsToAgentRequest(request3, runtimeTools) {
+  const existing = request3.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,
@@ -7145,9 +7459,9 @@ function appendRuntimeToolsToAgentRequest(request2, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request2,
+    ...request3,
     tools: {
-      ...request2.tools,
+      ...request3.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -7223,21 +7537,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(request2, runtimeTools) {
-    return appendRuntimeToolsToAgentRequest(request2, runtimeTools);
+  attachApprovedRuntimeTools(request3, runtimeTools) {
+    return appendRuntimeToolsToAgentRequest(request3, runtimeTools);
   }
   /**
    * Validate a generated runtime tool proposal and append it to an agent execute
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
+  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
     const decision = evaluateGeneratedRuntimeToolProposal(proposal, options);
     if (!decision.approved || !decision.tool) {
-      return { decision, request: request2 };
+      return { decision, request: request3 };
     }
     return {
       decision,
-      request: appendRuntimeToolsToAgentRequest(request2, [decision.tool])
+      request: appendRuntimeToolsToAgentRequest(request3, [decision.tool])
     };
   }
   /**
@@ -7996,11 +8310,13 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * setting. This never mutates persisted marathon history; masking/offloading
    * is a send-time view over the full-fidelity ledger/history.
    */
-  deriveToolContextMessages(messages, taskName, mode, window) {
+  deriveToolContextMessages(messages, taskName, mode, window, offloadRecorder) {
     if (mode === "full-inline") return [...messages];
     const maskMessage = (msg) => ({
       ...msg,
-      toolResults: (msg.toolResults ?? []).map((tr) => this.compactOneResult(tr, taskName, mode))
+      toolResults: (msg.toolResults ?? []).map(
+        (tr) => this.compactOneResult(tr, taskName, mode, offloadRecorder)
+      )
     });
     const view = [...messages];
     if (window === "session") {
@@ -8034,12 +8350,18 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     }
     return view;
   }
-  compactOneResult(tr, taskName, mode) {
+  compactOneResult(tr, taskName, mode, offloadRecorder) {
     if (typeof tr.result === "string" && tr.result.startsWith("[")) return tr;
     if (mode === "hot-tail") {
       return {
         ...tr,
-        result: this.offloadToolResult(taskName, tr.toolCallId, tr.toolName, tr.result)
+        result: this.offloadToolResult(
+          taskName,
+          tr.toolCallId,
+          tr.toolName,
+          tr.result,
+          offloadRecorder
+        )
       };
     }
     return { ...tr, result: `[Output from ${tr.toolName} masked \u2014 re-run the tool if needed]` };
@@ -8055,9 +8377,16 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
   }
   // chars
-  offloadToolResult(taskName, toolCallId, toolName, result) {
+  offloadToolResult(taskName, toolCallId, toolName, result, offloadRecorder) {
     const resultStr = typeof result === "string" ? result : JSON.stringify(result, null, 2);
     if (resultStr.length <= this.TOOL_OUTPUT_INLINE_THRESHOLD) return result;
+    if (offloadRecorder) {
+      try {
+        const recorded = offloadRecorder({ toolCallId, toolName, content: resultStr });
+        if (recorded?.reference) return recorded.reference;
+      } catch {
+      }
+    }
     let fs;
     try {
       const dynamicRequire = (0, eval)('typeof require !== "undefined" ? require : undefined');
@@ -8784,7 +9113,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           onContextCompaction: options.onContextCompaction,
           onContextNotice: options.onContextNotice,
           toolContextMode: options.toolContextMode || "hot-tail",
-          toolWindow: options.toolWindow ?? "session"
+          toolWindow: options.toolWindow ?? "session",
+          offloadRecorder: options.offloadRecorder
         },
         queuedSteeringMessages
       );
@@ -9575,7 +9905,8 @@ Do NOT redo any of the above work.`
       });
     };
     const buildNativeCompactionEvent = (mode, breakdown) => {
-      if (resolvedStrategy !== "provider_native" || typeof compactionOptions?.autoCompactTokenThreshold !== "number" || compactionOptions.autoCompactTokenThreshold <= 0 || breakdown.estimatedInputTokens < compactionOptions.autoCompactTokenThreshold) {
+      const gateTokens = breakdown.sendEstimatedInputTokens ?? breakdown.estimatedInputTokens;
+      if (resolvedStrategy !== "provider_native" || typeof compactionOptions?.autoCompactTokenThreshold !== "number" || compactionOptions.autoCompactTokenThreshold <= 0 || gateTokens < compactionOptions.autoCompactTokenThreshold) {
         return void 0;
       }
       return {
@@ -9644,7 +9975,8 @@ Do NOT redo any of the above work.`
         sourceReplayHistoryMessages,
         state.taskName,
         compactionOptions?.toolContextMode || "hot-tail",
-        compactionOptions?.toolWindow ?? "session"
+        compactionOptions?.toolWindow ?? "session",
+        compactionOptions?.offloadRecorder
       );
       const continuationGuardrail = this.buildContinuationGuardrail(state);
       const defaultContinueMessage = "Continue the task. Review your prior work above and proceed with any remaining work. If everything is already complete, respond with TASK_COMPLETE.";
@@ -9807,7 +10139,8 @@ Do NOT redo any of the above work.`
         sourceHistoryMessages,
         state.taskName,
         compactionOptions?.toolContextMode || "hot-tail",
-        compactionOptions?.toolWindow ?? "session"
+        compactionOptions?.toolWindow ?? "session",
+        compactionOptions?.offloadRecorder
       );
       const historyArtifactReferences = this.extractArtifactReferencesFromMessages(historyMessages);
       const summaryText = this.generateCompactSummary(
@@ -10454,7 +10787,7 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  async runWithLocalTools(request2, localTools, arg3, arg4) {
+  async runWithLocalTools(request3, 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) ?? {};
@@ -10468,12 +10801,12 @@ var RuntypeClient2 = class {
       ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
     })) : [];
     const modifiedRequest = {
-      ...request2,
+      ...request3,
       ...derivedClientTools.length > 0 ? {
-        clientTools: [...request2.clientTools ?? [], ...derivedClientTools]
+        clientTools: [...request3.clientTools ?? [], ...derivedClientTools]
       } : {},
       options: {
-        ...request2.options || {},
+        ...request3.options || {},
         streamResponse: isStreaming
       }
     };
@@ -10911,20 +11244,20 @@ var BatchBuilder = class {
     if (!this.recordType) {
       throw new Error("BatchBuilder: recordType is required. Call .forRecordType(type) first.");
     }
-    const request2 = {
+    const request3 = {
       flowId: this.flowId,
       recordType: this.recordType
     };
     if (Object.keys(this.batchOptions).length > 0) {
-      request2.options = this.batchOptions;
+      request3.options = this.batchOptions;
     }
     if (this.filterConfig) {
-      request2.filter = this.filterConfig;
+      request3.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request2.limit = this.limitConfig;
+      request3.limit = this.limitConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Execute the batch operation
@@ -11081,32 +11414,32 @@ var EvalBuilder = class {
         "EvalBuilder: records are required. Call .forRecordType(type) or .withRecords([...]) first."
       );
     }
-    const request2 = {};
+    const request3 = {};
     if (this.flowId) {
-      request2.flowId = this.flowId;
+      request3.flowId = this.flowId;
     } else if (this.virtualFlow) {
-      request2.flow = this.virtualFlow;
+      request3.flow = this.virtualFlow;
     }
     if (this.recordType) {
-      request2.recordType = this.recordType;
+      request3.recordType = this.recordType;
     } else if (this.inlineRecords) {
-      request2.records = this.inlineRecords;
+      request3.records = this.inlineRecords;
     }
     if (this.modelOverrides) {
-      request2.modelOverrides = this.modelOverrides;
+      request3.modelOverrides = this.modelOverrides;
     } else if (this.modelConfigs) {
-      request2.modelConfigs = this.modelConfigs;
+      request3.modelConfigs = this.modelConfigs;
     }
     if (Object.keys(this.evalOptions).length > 0) {
-      request2.options = this.evalOptions;
+      request3.options = this.evalOptions;
     }
     if (this.filterConfig) {
-      request2.filter = this.filterConfig;
+      request3.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request2.limit = this.limitConfig;
+      request3.limit = this.limitConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Execute the evaluation
@@ -11626,7 +11959,10 @@ var STEP_TYPE_TO_METHOD = {
   SkillProposalsNamespace,
   SkillsNamespace,
   SurfacesEndpoint,
+  ToolDriftError,
+  ToolEnsureConflictError,
   ToolsEndpoint,
+  ToolsNamespace,
   UsersEndpoint,
   applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest,
@@ -11638,6 +11974,7 @@ var STEP_TYPE_TO_METHOD = {
   compileWorkflowConfig,
   computeAgentContentHash,
   computeFlowContentHash,
+  computeToolContentHash,
   createClient,
   createExternalTool,
   defaultWorkflow,
@@ -11645,6 +11982,7 @@ var STEP_TYPE_TO_METHOD = {
   defineAgent,
   defineFlow,
   definePlaybook,
+  defineTool,
   deployWorkflow,
   ensureDefaultWorkflowHooks,
   evaluateGeneratedRuntimeToolProposal,
@@ -11660,6 +11998,7 @@ var STEP_TYPE_TO_METHOD = {
   listWorkflowHooks,
   normalizeAgentDefinition,
   normalizeCandidatePath,
+  normalizeToolDefinition,
   parseFinalBuffer,
   parseLedgerArtifactRelativePath,
   parseOffloadedOutputId,