@synapsor/client 0.1.1 → 0.1.3

package/synapsor.mjs

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import net from "node:net";
 import { dirname, join, resolve } from "node:path";
@@ -19,11 +20,26 @@ export {
 };
 
 export class SynapsorError extends Error {
-  constructor(message, { status = undefined, payload = undefined } = {}) {
+  constructor(
+    message,
+    {
+      status = undefined,
+      payload = undefined,
+      code = undefined,
+      requestId = undefined,
+      retryable = undefined,
+    } = {},
+  ) {
     super(message);
     this.name = "SynapsorError";
     this.status = status;
     this.payload = payload;
+    const payloadObject = payload && typeof payload === "object" ? payload : {};
+    this.code = code ?? payloadObject.code ?? payloadObject.error;
+    this.errorCode = this.code;
+    this.requestId = requestId ?? payloadObject.request_id ?? payloadObject.response_request_id;
+    this.request_id = this.requestId;
+    this.retryable = retryable;
   }
 }
 
@@ -64,6 +80,9 @@ export class Synapsor {
     this.apiKey = apiKey;
     this.process = process;
     this.timeoutMs = timeoutMs;
+    this.agentRuns = new AgentRunsNamespace(this);
+    this.externalActions = new ExternalActionsNamespace(this);
+    this.evals = new AgentEvalsNamespace(this);
   }
 
   static async connect(target, options = {}) {
@@ -176,6 +195,19 @@ export class Synapsor {
     });
   }
 
+  async setAdminTenantBudget(tenantId, limits) {
+    return this.request("POST", "/v1/admin/tenant-budgets", {
+      tenant_id: String(tenantId),
+      limits: { ...limits },
+    });
+  }
+
+  async clearAdminTenantBudget(tenantId) {
+    return this.request("POST", "/v1/admin/tenant-budgets/clear", {
+      tenant_id: String(tenantId),
+    });
+  }
+
   async shutdown() {
     return this.request("POST", "/v1/admin/shutdown", {});
   }
@@ -249,6 +281,10 @@ export class Synapsor {
     include_audit_trail = undefined,
     settlementPolicy = undefined,
     settlement_policy = undefined,
+    runId = undefined,
+    run_id = undefined,
+    stepKey = undefined,
+    step_key = undefined,
   } = {}) {
     const payload = {
       capability,
@@ -260,6 +296,8 @@ export class Synapsor {
     const envelope = responseEnvelope ?? response_envelope;
     const audit = includeAuditTrail ?? include_audit_trail;
     const policy = settlementPolicy ?? settlement_policy;
+    const workflowRun = runId ?? run_id;
+    const workflowStep = stepKey ?? step_key;
     if (trace !== undefined) {
       payload.trace_id = trace;
     }
@@ -278,9 +316,467 @@ export class Synapsor {
     if (policy !== undefined) {
       payload.settlement_policy = policy;
     }
+    if (workflowRun !== undefined) {
+      payload.run_id = workflowRun;
+    }
+    if (workflowStep !== undefined) {
+      payload.step_key = workflowStep;
+    }
     return this.request("POST", "/v1/agent/invoke", payload);
   }
 
+  async createAgentWorkflow(workflow, {
+    version = "v1",
+    description = undefined,
+    entryCapability = undefined,
+    entry_capability = undefined,
+    maxSteps = undefined,
+    max_steps = undefined,
+    maxToolCalls = undefined,
+    max_tool_calls = undefined,
+    maxInputTokens = undefined,
+    max_input_tokens = undefined,
+    maxOutputTokens = undefined,
+    max_output_tokens = undefined,
+    evidenceRequired = undefined,
+    evidence_required = undefined,
+    checkpointEveryStep = undefined,
+    checkpoint_every_step = undefined,
+    autoBranchOnProposal = undefined,
+    auto_branch_on_proposal = undefined,
+    branchPolicy = undefined,
+    branch_policy = undefined,
+    riskPolicy = undefined,
+    risk_policy = undefined,
+    errorPolicy = undefined,
+    error_policy = undefined,
+    retentionPolicy = undefined,
+    retention_policy = undefined,
+    sessionRequirements = undefined,
+    session_requirements = undefined,
+    allowedCapabilities = undefined,
+    allowed_capabilities = undefined,
+    allowedActions = undefined,
+    allowed_actions = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      workflow,
+      version,
+      session: this.requireSession(session),
+    };
+    const entry = entryCapability ?? entry_capability;
+    const steps = maxSteps ?? max_steps;
+    const toolCalls = maxToolCalls ?? max_tool_calls;
+    const inputTokens = maxInputTokens ?? max_input_tokens;
+    const outputTokens = maxOutputTokens ?? max_output_tokens;
+    const evidence = evidenceRequired ?? evidence_required;
+    const checkpoint = checkpointEveryStep ?? checkpoint_every_step;
+    const autoBranch = autoBranchOnProposal ?? auto_branch_on_proposal;
+    const branch = branchPolicy ?? branch_policy;
+    const risk = riskPolicy ?? risk_policy;
+    const error = errorPolicy ?? error_policy;
+    const retention = retentionPolicy ?? retention_policy;
+    const requiredSession = sessionRequirements ?? session_requirements;
+    const capabilities = allowedCapabilities ?? allowed_capabilities;
+    const actions = allowedActions ?? allowed_actions;
+    for (const [key, value] of [
+      ["description", description],
+      ["entry_capability", entry],
+      ["max_steps", steps],
+      ["max_tool_calls", toolCalls],
+      ["max_input_tokens", inputTokens],
+      ["max_output_tokens", outputTokens],
+      ["evidence_required", evidence],
+      ["checkpoint_every_step", checkpoint],
+      ["auto_branch_on_proposal", autoBranch],
+      ["branch_policy", branch],
+      ["risk_policy", risk],
+      ["error_policy", error],
+      ["retention_policy", retention],
+      ["session_requirements", requiredSession],
+      ["allowed_capabilities", capabilities],
+      ["allowed_actions", actions],
+    ]) {
+      if (value !== undefined) {
+        payload[key] = value;
+      }
+    }
+    return this.request("POST", "/v1/agent/workflows", payload);
+  }
+
+  async beginAgentRun(workflow, { version = "v1", input = {}, session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/runs", {
+      workflow,
+      version,
+      input,
+      session: this.requireSession(session),
+    });
+  }
+
+  async recordAgentStep(runId, stepKey, {
+    kind = "external_action",
+    status = "completed",
+    input = {},
+    output = {},
+    session = undefined,
+  } = {}) {
+    return this.request("POST", "/v1/agent/runs/steps", {
+      run_id: runId,
+      step_key: stepKey,
+      kind,
+      status,
+      input,
+      output,
+      session: this.requireSession(session),
+    });
+  }
+
+  async checkpointAgentRun(runId, stepKey, {
+    payload = {},
+    session = undefined,
+  } = {}) {
+    return this.request("POST", "/v1/agent/runs/checkpoints", {
+      run_id: runId,
+      step_key: stepKey,
+      payload,
+      session: this.requireSession(session),
+    });
+  }
+
+  async interruptAgentRun(runId, stepKey, {
+    reason,
+    payload = {},
+    session = undefined,
+  } = {}) {
+    return this.request("POST", "/v1/agent/runs/interrupts", {
+      run_id: runId,
+      step_key: stepKey,
+      reason,
+      payload,
+      session: this.requireSession(session),
+    });
+  }
+
+  async handoffAgentRun(runId, stepKey, {
+    target,
+    reason = undefined,
+    payload = {},
+    session = undefined,
+  } = {}) {
+    const body = {
+      run_id: runId,
+      step_key: stepKey,
+      target,
+      payload,
+      session: this.requireSession(session),
+    };
+    if (reason !== undefined) {
+      body.reason = reason;
+    }
+    return this.request("POST", "/v1/agent/runs/handoffs", body);
+  }
+
+  async recordGuardrailEvent(runId, stepKey, {
+    status = "completed",
+    payload = {},
+    session = undefined,
+  } = {}) {
+    return this.request("POST", "/v1/agent/runs/guardrail-events", {
+      run_id: runId,
+      step_key: stepKey,
+      status,
+      payload,
+      session: this.requireSession(session),
+    });
+  }
+
+  async endAgentRun(runId, { status = "completed", output = {}, session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/runs/complete", {
+      run_id: runId,
+      status,
+      output,
+      session: this.requireSession(session),
+    });
+  }
+
+  async explainAgentRun(runId, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/runs/explain", {
+      run_id: runId,
+      session: this.requireSession(session),
+    });
+  }
+
+  async settleAgentRun(runId, {
+    settlementPolicy = undefined,
+    settlement_policy = undefined,
+    policy = undefined,
+    idempotencyKey = undefined,
+    idempotency_key = undefined,
+    session = undefined,
+  } = {}) {
+    const selectedPolicy = settlementPolicy ?? settlement_policy ?? policy;
+    if (selectedPolicy === undefined || selectedPolicy === "") {
+      throw new Error("settleAgentRun requires settlementPolicy");
+    }
+    const payload = {
+      run_id: runId,
+      settlement_policy: selectedPolicy,
+      session: this.requireSession(session),
+    };
+    const idem = idempotencyKey ?? idempotency_key;
+    if (idem !== undefined) {
+      payload.idempotency_key = idem;
+    }
+    return this.request("POST", "/v1/agent/runs/settle", payload);
+  }
+
+  async createAgentEval(evalName, {
+    assertions = [],
+    description = undefined,
+    sourceType = undefined,
+    source_type = undefined,
+    sourceWorkflow = undefined,
+    source_workflow = undefined,
+    sourceTable = undefined,
+    source_table = undefined,
+    sourceStatus = undefined,
+    source_status = undefined,
+    replayMode = "frozen",
+    replay_mode = undefined,
+    session = undefined,
+  } = {}) {
+    const table = sourceTable ?? source_table;
+    const resolvedSourceType = source_type ?? sourceType ?? (table !== undefined ? "table" : "runs");
+    const payload = {
+      eval: evalName,
+      source_type: resolvedSourceType,
+      replay_mode: replay_mode ?? replayMode,
+      assertions,
+      session: this.requireSession(session),
+    };
+    const workflow = sourceWorkflow ?? source_workflow;
+    const status = sourceStatus ?? source_status;
+    if (description !== undefined) {
+      payload.description = description;
+    }
+    if (workflow !== undefined) {
+      payload.source_workflow = workflow;
+    }
+    if (table !== undefined) {
+      payload.source_table = table;
+    }
+    if (status !== undefined) {
+      payload.source_status = status;
+    }
+    return this.request("POST", "/v1/agent/evals", payload);
+  }
+
+  async runAgentEval(evalName, {
+    targetBranch = undefined,
+    target_branch = undefined,
+    replayMode = undefined,
+    replay_mode = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      eval: evalName,
+      session: this.requireSession(session),
+    };
+    const branch = targetBranch ?? target_branch;
+    const mode = replayMode ?? replay_mode;
+    if (branch !== undefined) {
+      payload.target_branch = branch;
+    }
+    if (mode !== undefined) {
+      payload.replay_mode = mode;
+    }
+    return this.request("POST", "/v1/agent/evals/run", payload);
+  }
+
+  async agentEvalFailures(evalRunId, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/evals/failures", {
+      eval_run_id: evalRunId,
+      session: this.requireSession(session),
+    });
+  }
+
+  async diffAgentEval(baselineEvalRunId, candidateEvalRunId, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/evals/diff", {
+      baseline_eval_run_id: baselineEvalRunId,
+      candidate_eval_run_id: candidateEvalRunId,
+      session: this.requireSession(session),
+    });
+  }
+
+  async createAgentAdapter(adapter, {
+    type,
+    tools,
+    resources = [],
+    description = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      adapter,
+      type,
+      tools,
+      resources,
+      session: this.requireSession(session),
+    };
+    if (description !== undefined) {
+      payload.description = description;
+    }
+    return this.request("POST", "/v1/agent/adapters", payload);
+  }
+
+  async adapterTools(adapter, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/adapters/tools", {
+      adapter,
+      session: this.requireSession(session),
+    });
+  }
+
+  async callAdapterTool(adapter, tool, {
+    arguments: args = {},
+    runId = undefined,
+    run_id = undefined,
+    stepKey = undefined,
+    step_key = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      adapter,
+      tool,
+      arguments: args,
+      session: this.requireSession(session),
+    };
+    const run = runId ?? run_id;
+    const step = stepKey ?? step_key;
+    if (run !== undefined) {
+      payload.run_id = run;
+    }
+    if (step !== undefined) {
+      payload.step_key = step;
+    }
+    return this.request("POST", "/v1/agent/adapters/call-tool", payload);
+  }
+
+  async traceAgentRun(runId, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/runs/trace", {
+      run_id: runId,
+      session: this.requireSession(session),
+    });
+  }
+
+  async createObservabilitySink({
+    name,
+    type,
+    endpoint = "",
+    export: exportList = [],
+    redact = {},
+    sampleRateMilli = undefined,
+    sample_rate_milli = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      name,
+      type,
+      endpoint,
+      export: exportList,
+      redact,
+      session: this.requireSession(session),
+    };
+    const sampleRate = sampleRateMilli ?? sample_rate_milli;
+    if (sampleRate !== undefined) {
+      payload.sample_rate_milli = sampleRate;
+    }
+    return this.request("POST", "/v1/observability/sinks", payload);
+  }
+
+  async proposeExternalAction(action, {
+    runId = undefined,
+    run_id = undefined,
+    stepKey = undefined,
+    step_key = undefined,
+    arguments: args = {},
+    idempotencyKey = undefined,
+    idempotency_key = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      action,
+      run_id: runId ?? run_id,
+      step_key: stepKey ?? step_key,
+      arguments: args,
+      session: this.requireSession(session),
+    };
+    const idem = idempotencyKey ?? idempotency_key;
+    if (idem !== undefined) {
+      payload.idempotency_key = idem;
+    }
+    return this.request("POST", "/v1/agent/external-actions/propose", payload);
+  }
+
+  async approveExternalAction(actionInstanceId, {
+    note = undefined,
+    approvalNote = undefined,
+    approval_note = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {};
+    const selectedNote = note ?? approvalNote ?? approval_note;
+    if (selectedNote !== undefined) {
+      payload.note = selectedNote;
+    }
+    if (session !== undefined || Object.keys(this.session).length > 0) {
+      payload.session = this.requireSession(session);
+    }
+    return this.request("POST", `/v1/agent/external-actions/${actionInstanceId}/approve`, payload);
+  }
+
+  async claimExternalAction({
+    queue,
+    workerId = undefined,
+    worker_id = undefined,
+    lockSeconds = 60,
+    lock_seconds = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = {
+      queue,
+      worker_id: workerId ?? worker_id,
+      lock_seconds: lock_seconds ?? lockSeconds,
+    };
+    if (session !== undefined || Object.keys(this.session).length > 0) {
+      payload.session = this.requireSession(session);
+    }
+    return this.request("POST", "/v1/agent/external-actions/claim", payload);
+  }
+
+  async confirmExternalAction(actionInstanceId, {
+    status,
+    providerRequestId = undefined,
+    provider_request_id = undefined,
+    response = {},
+    errorCode = undefined,
+    error_code = undefined,
+    session = undefined,
+  } = {}) {
+    const payload = { status, response };
+    const provider = providerRequestId ?? provider_request_id;
+    const error = errorCode ?? error_code;
+    if (provider !== undefined) {
+      payload.provider_request_id = provider;
+    }
+    if (error !== undefined) {
+      payload.error_code = error;
+    }
+    if (session !== undefined || Object.keys(this.session).length > 0) {
+      payload.session = this.requireSession(session);
+    }
+    return this.request("POST", `/v1/agent/external-actions/${actionInstanceId}/confirm`, payload);
+  }
+
   async listCapabilities(query = "", { session = undefined } = {}) {
     return this.request("POST", "/v1/agent/capabilities", {
       query,
@@ -299,6 +795,40 @@ export class Synapsor {
     return this.memoryCommand(factCommand("agent_memory.remember_fact", options), options);
   }
 
+  async createMemoryPolicy(options) {
+    const command = {
+      kind: "agent_memory.create_policy",
+      name: options.name,
+      scope: options.scope,
+      subject: options.subject,
+      require_evidence: Boolean(options.requireEvidence ?? options.require_evidence ?? false),
+    };
+    for (const [from, to] of [
+      ["description", "description"],
+      ["approvalMinTrustMilli", "approval_min_trust_milli"],
+      ["approval_min_trust_milli", "approval_min_trust_milli"],
+      ["maxActiveFactsPerSubject", "max_active_facts_per_subject"],
+      ["max_active_facts_per_subject", "max_active_facts_per_subject"],
+      ["maxRecallFactsPerCapability", "max_recall_facts_per_capability"],
+      ["max_recall_facts_per_capability", "max_recall_facts_per_capability"],
+      ["forgetMode", "forget_mode"],
+      ["forget_mode", "forget_mode"],
+      ["conflictStrategy", "conflict_strategy"],
+      ["conflict_strategy", "conflict_strategy"],
+      ["supersessionStrategy", "supersession_strategy"],
+      ["supersession_strategy", "supersession_strategy"],
+      ["decayStrategy", "decay_strategy"],
+      ["decay_strategy", "decay_strategy"],
+      ["retentionStrategy", "retention_strategy"],
+      ["retention_strategy", "retention_strategy"],
+    ]) {
+      if (options[from] !== undefined) {
+        command[to] = options[from];
+      }
+    }
+    return this.memoryCommand(command, options);
+  }
+
   async proposeMemoryFact(options) {
     const command = factCommand("agent_memory.propose_fact", options);
     command.replace_subject = Boolean(options.replaceSubject ?? options.replace_subject ?? false);
@@ -348,6 +878,12 @@ export class Synapsor {
     }
     for (const [from, to] of [
       ["asOf", "as_of"],
+      ["as_of", "as_of"],
+      ["asOfAgentRunId", "as_of_agent_run_id"],
+      ["as_of_agent_run_id", "as_of_agent_run_id"],
+      ["policy", "policy"],
+      ["policyName", "policy_name"],
+      ["policy_name", "policy_name"],
       ["budgetTokens", "budget_tokens"],
       ["profile", "profile"],
       ["inlineEvidence", "inline_evidence"],
@@ -361,6 +897,36 @@ export class Synapsor {
     return this.memoryCommand(command, options);
   }
 
+  async recallMemoryAsOfAgentRun(runId, options = {}) {
+    return this.recallMemory({ ...options, asOfAgentRunId: runId });
+  }
+
+  async showMemoryConflicts(options = {}) {
+    const command = {
+      kind: "agent_memory.show_conflicts",
+      subject: typedRef(options.subject),
+    };
+    if (options.scope !== undefined) {
+      command.scope = typedRef(options.scope);
+    }
+    if (options.policy !== undefined) {
+      command.policy = options.policy;
+    }
+    if (options.policyName !== undefined) {
+      command.policy_name = options.policyName;
+    }
+    return this.memoryCommand(command, options);
+  }
+
+  async supersedeMemoryFact(oldMemoryId, newMemoryId, reason, options = {}) {
+    return this.memoryCommand({
+      kind: "agent_memory.supersede_fact",
+      old_memory_id: oldMemoryId,
+      new_memory_id: newMemoryId,
+      reason,
+    }, options);
+  }
+
   async retireFact(memoryId, { validTo, reason, session = undefined }) {
     return this.memoryCommand({
       kind: "agent_memory.retire_fact",
@@ -455,11 +1021,28 @@ export class Synapsor {
   }
 
   async replayAgentRun(runId, options = {}) {
-    return this.request("POST", "/v1/agent/runs/replay", {
+    const payload = {
       run_id: Number(runId),
       session: this.requireSession(options.session),
       include_sensitive_memory: Boolean(options.includeSensitiveMemory ?? options.include_sensitive_memory ?? false),
-    });
+    };
+    const mode = options.mode ?? options.replayMode ?? options.replay_mode;
+    const version = options.version ?? options.commitVersion ?? options.commit_version;
+    const timestamp = options.timestamp;
+    const branchName = options.branchName ?? options.branch_name;
+    if (mode !== undefined) {
+      payload.mode = mode;
+    }
+    if (version !== undefined) {
+      payload.version = Number(version);
+    }
+    if (timestamp !== undefined) {
+      payload.timestamp = timestamp;
+    }
+    if (branchName !== undefined) {
+      payload.branch_name = branchName;
+    }
+    return this.request("POST", "/v1/agent/runs/replay", payload);
   }
 
   async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined, settlementPolicy = undefined, settlement_policy = undefined } = {}) {
@@ -494,7 +1077,8 @@ export class Synapsor {
   }
 
   async request(method, path, payload = undefined) {
-    const headers = { accept: "application/json" };
+    const requestId = `sdk-${randomUUID()}`;
+    const headers = { accept: "application/json", "x-request-id": requestId };
     const init = { method, headers };
     if (payload !== undefined) {
       headers["content-type"] = "application/json";
@@ -515,9 +1099,14 @@ export class Synapsor {
     }
     if (!response.ok) {
       const ErrorType = ERROR_BY_STATUS.get(response.status) ?? SynapsorError;
-      throw new ErrorType(body.error ?? `Synapsor HTTP ${response.status}`, {
+      const responseRequestId = response.headers.get("x-request-id") ?? body.request_id ?? requestId;
+      const retryableHeader = response.headers.get("x-synapsor-retryable");
+      throw new ErrorType(body.message ?? body.error ?? `Synapsor HTTP ${response.status}`, {
         status: response.status,
         payload: body,
+        code: body.code ?? body.error,
+        requestId: responseRequestId,
+        retryable: retryableHeader === null ? undefined : retryableHeader === "true",
       });
     }
     return body;
@@ -542,6 +1131,212 @@ export class Synapsor {
   }
 }
 
+class AgentRunsNamespace {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async start({ workflow, version = "v1", input = {}, session = undefined } = {}) {
+    const response = await this.client.beginAgentRun(workflow, { version, input, session });
+    return new AgentRun(this.client, response);
+  }
+
+  async explain(runId, options = {}) {
+    return this.client.explainAgentRun(runId, options);
+  }
+}
+
+class AgentRun {
+  constructor(client, response) {
+    Object.assign(this, response);
+    this.client = client;
+    this.response = { ...response };
+    this.runId = response.run_id ?? response.id;
+    if (this.runId === undefined || this.runId === "") {
+      throw new Error("agent run response did not include run_id");
+    }
+  }
+
+  toJSON() {
+    return { ...this.response };
+  }
+
+  async invokeCapability(capability, {
+    stepKey = undefined,
+    step_key = undefined,
+    arguments: args = {},
+    mode = undefined,
+    autoBranch = undefined,
+    auto_branch = undefined,
+    responseEnvelope = undefined,
+    response_envelope = undefined,
+    includeAuditTrail = undefined,
+    include_audit_trail = undefined,
+    settlementPolicy = undefined,
+    settlement_policy = undefined,
+    session = undefined,
+  } = {}) {
+    const step = stepKey ?? step_key;
+    if (step === undefined || step === "") {
+      throw new Error("run.invokeCapability requires stepKey");
+    }
+    return this.client.invokeAgentCapability(capability, args, {
+      runId: this.runId,
+      stepKey: step,
+      mode,
+      autoBranch: autoBranch ?? auto_branch,
+      responseEnvelope: responseEnvelope ?? response_envelope,
+      includeAuditTrail: includeAuditTrail ?? include_audit_trail,
+      settlementPolicy: settlementPolicy ?? settlement_policy,
+      session,
+    });
+  }
+
+  async proposeExternalAction(action, {
+    stepKey = undefined,
+    step_key = undefined,
+    arguments: args = {},
+    idempotencyKey = undefined,
+    idempotency_key = undefined,
+    session = undefined,
+  } = {}) {
+    const step = stepKey ?? step_key;
+    if (step === undefined || step === "") {
+      throw new Error("run.proposeExternalAction requires stepKey");
+    }
+    return this.client.proposeExternalAction(action, {
+      runId: this.runId,
+      stepKey: step,
+      arguments: args,
+      idempotencyKey: idempotencyKey ?? idempotency_key,
+      session,
+    });
+  }
+
+  async recordStep(stepKey, options = {}) {
+    return this.client.recordAgentStep(this.runId, stepKey, options);
+  }
+
+  async checkpoint(stepKey, options = {}) {
+    return this.client.checkpointAgentRun(this.runId, stepKey, options);
+  }
+
+  async recordGuardrailEvent(stepKey, options = {}) {
+    return this.client.recordGuardrailEvent(this.runId, stepKey, options);
+  }
+
+  async handoff(stepKey, options = {}) {
+    return this.client.handoffAgentRun(this.runId, stepKey, options);
+  }
+
+  async interrupt(stepKey, options = {}) {
+    return this.client.interruptAgentRun(this.runId, stepKey, options);
+  }
+
+  async complete(output = {}, { status = "completed", session = undefined } = {}) {
+    return this.client.endAgentRun(this.runId, { status, output, session });
+  }
+
+  async settle({
+    settlementPolicy = undefined,
+    settlement_policy = undefined,
+    policy = undefined,
+    idempotencyKey = undefined,
+    idempotency_key = undefined,
+    session = undefined,
+  } = {}) {
+    return this.client.settleAgentRun(this.runId, {
+      settlementPolicy: settlementPolicy ?? settlement_policy ?? policy,
+      idempotencyKey: idempotencyKey ?? idempotency_key,
+      session,
+    });
+  }
+
+  async explain(options = {}) {
+    return this.client.explainAgentRun(this.runId, options);
+  }
+}
+
+class ExternalActionsNamespace {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async propose(action, options = {}) {
+    return this.client.proposeExternalAction(action, options);
+  }
+
+  async claim(options = {}) {
+    return this.client.claimExternalAction(options);
+  }
+
+  async approve(actionInstanceId, options = {}) {
+    return this.client.approveExternalAction(actionInstanceId, options);
+  }
+
+  async confirm(actionInstanceId, options = {}) {
+    return this.client.confirmExternalAction(actionInstanceId, options);
+  }
+}
+
+class AgentEvalsNamespace {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async create(evalName, options = {}) {
+    return this.client.createAgentEval(evalName, options);
+  }
+
+  async run(evalName, {
+    againstBranch = undefined,
+    targetBranch = undefined,
+    target_branch = undefined,
+    replayMode = undefined,
+    replay_mode = undefined,
+    session = undefined,
+  } = {}) {
+    const response = await this.client.runAgentEval(evalName, {
+      targetBranch: targetBranch ?? target_branch ?? againstBranch,
+      replayMode: replayMode ?? replay_mode,
+      session,
+    });
+    return new AgentEvalRun(this.client, response);
+  }
+
+  async failures(evalRunId, options = {}) {
+    return this.client.agentEvalFailures(evalRunId, options);
+  }
+
+  async diff(baselineEvalRunId, candidateEvalRunId, options = {}) {
+    return this.client.diffAgentEval(baselineEvalRunId, candidateEvalRunId, options);
+  }
+}
+
+class AgentEvalRun {
+  constructor(client, response) {
+    Object.assign(this, response);
+    this.client = client;
+    this.response = { ...response };
+    this.evalRunId = response.eval_run_id ?? response.id;
+    if (this.evalRunId === undefined || this.evalRunId === "") {
+      throw new Error("agent eval response did not include eval_run_id");
+    }
+  }
+
+  toJSON() {
+    return { ...this.response };
+  }
+
+  async failures(options = {}) {
+    return this.client.agentEvalFailures(this.evalRunId, options);
+  }
+
+  async diffAgainst(baselineEvalRunId, options = {}) {
+    return this.client.diffAgentEval(baselineEvalRunId, this.evalRunId, options);
+  }
+}
+
 function factCommand(kind, options) {
   const command = {
     kind,
@@ -568,6 +1363,21 @@ function factCommand(kind, options) {
   if (options.valid_to !== undefined) {
     command.valid_to = options.valid_to;
   }
+  for (const [from, to] of [
+    ["policy", "policy"],
+    ["policyName", "policy_name"],
+    ["policy_name", "policy_name"],
+    ["evidenceBundleId", "evidence_bundle_id"],
+    ["evidence_bundle_id", "evidence_bundle_id"],
+    ["runId", "run_id"],
+    ["run_id", "run_id"],
+    ["stepKey", "step_key"],
+    ["step_key", "step_key"],
+  ]) {
+    if (options[from] !== undefined) {
+      command[to] = options[from];
+    }
+  }
   return command;
 }